wehub-resource-sync
1530 lines
62 KiB
Python
1530 lines
62 KiB
Python
"""Typed dataclasses representing a parsed agent image spec."""
|
|
|
|
from __future__ import annotations
|
|
|
|
from dataclasses import dataclass, field
|
|
from enum import Enum
|
|
from pathlib import Path
|
|
from typing import TYPE_CHECKING, Any, Literal
|
|
|
|
from omnigent.inner.datamodel import OSEnvSpec, TerminalEnvSpec
|
|
|
|
if TYPE_CHECKING:
|
|
# EvaluationContext is a runtime evaluation artifact (see
|
|
# omnigent.policies.types); PhaseSelector.matches takes
|
|
# one by attribute access only, so the annotation lives
|
|
# behind TYPE_CHECKING to avoid an import cycle.
|
|
from omnigent.policies.types import EvaluationContext
|
|
|
|
# Default classifier timeout for PromptPolicy evaluations. 30 s
|
|
# balances classifier latency against the cost of blocking the
|
|
# agent loop for every evaluated phase. The agent-level LLM
|
|
# default (300 s) is tuned for generation; using it for a
|
|
# blocking classifier stalls the loop for minutes on each tool
|
|
# call — see POLICIES.md §9.2. Overrideable via
|
|
# ``policy.llm.request_timeout`` on individual policies.
|
|
DEFAULT_POLICY_CLASSIFIER_TIMEOUT = 30
|
|
|
|
# Default timeout (seconds) for user approval on an ASK policy.
|
|
# One day — an ASK is a human-in-the-loop gate and should outlive a
|
|
# user stepping away, matching every other wait-for-a-human budget in
|
|
# the native path (the PermissionRequest / evaluate-policy hook
|
|
# long-polls and their server-side mirrors are all 86400). A shorter
|
|
# default fails closed (DENY) without any user input, flipping the web
|
|
# card to a neutral "Resolved elsewhere" — surprising for an
|
|
# interactive session. Headless/unattended agents that want a fast
|
|
# fail-closed should override this per-policy via ``PolicySpec.ask_timeout``
|
|
# or spec-wide via ``GuardrailsSpec.ask_timeout`` (see polly's config).
|
|
# See POLICIES.md §7, §13.
|
|
DEFAULT_ASK_TIMEOUT = 86400
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class RetryPolicy:
|
|
"""
|
|
Unified retry policy applied at two layers in the harness path
|
|
and as the only retry layer in the in-process LLM path and
|
|
tool-retry contexts.
|
|
|
|
See ``designs/RETRY_ACROSS_HARNESSES.md`` for the architecture.
|
|
|
|
- L0 (SDK-internal): SDK consumes via the relevant per-SDK
|
|
sub-object adapter (``policy.openai``,
|
|
``policy.anthropic``, ``policy.claude_cli``,
|
|
``policy.codex_cli``, ``policy.pi``) at client construction.
|
|
Backoff shape is the SDK's own; we don't override it. Pi
|
|
additionally consumes ``backoff_base_s`` and
|
|
``backoff_max_s`` because Pi exposes the shape declaratively
|
|
via ``.pi/settings.json``.
|
|
- L2 (AP-side workflow): consumed via
|
|
:meth:`compute_backoff_delay` for the workflow's own retry
|
|
loop between executor-turn attempts.
|
|
|
|
:param max_retries: Number of retries beyond the first attempt.
|
|
``max_retries=7`` means up to 8 total tries. Maps directly
|
|
to SDK ``max_retries`` parameters at L0 and bounds L2's
|
|
loop budget.
|
|
:param backoff_base_s: Exponential base in seconds. Delay
|
|
before retry ``i`` (1-indexed) is
|
|
``min(base * 2 ** (i - 1), backoff_max_s)``. Used at L2;
|
|
passed to Pi's L0 settings; ignored by other SDKs.
|
|
:param backoff_max_s: Per-retry cap in seconds. Used at L2 and
|
|
Pi L0 (as ``maxDelayMs`` for fail-fast on absurd
|
|
``Retry-After`` hints).
|
|
:param jitter: Multiply each L2 delay by ``Uniform(0.5, 1.5)``
|
|
to spread retries from many concurrent clients. SDKs handle
|
|
their own jitter at L0.
|
|
:param timeout_per_request_s: Per-HTTP-request timeout. ``None``
|
|
lets the SDK use its default. Used at L0 only — bounds an
|
|
individual attempt's wall-clock.
|
|
:param retryable_status_codes: HTTP status codes the in-process
|
|
LLM path's ``classify_llm_error`` treats as retryable.
|
|
Used only by the in-process LLM path and the tool-retry
|
|
classifier — L0 SDKs ignore this and L2 receives
|
|
already-classified errors.
|
|
"""
|
|
|
|
max_retries: int = 7
|
|
backoff_base_s: float = 2.0
|
|
backoff_max_s: float = 60.0
|
|
jitter: bool = True
|
|
timeout_per_request_s: float | None = 120.0
|
|
retryable_status_codes: tuple[int, ...] = (429, 500, 502, 503, 504)
|
|
|
|
def __post_init__(self) -> None:
|
|
"""
|
|
Validate bounds — extreme values produce weird behavior
|
|
(overflow, infinite loops, zero-delay hammering). Fail
|
|
loud per ``designs/DESIGN_PRINCIPLES.md``.
|
|
|
|
:raises ValueError: If any field is out of bounds.
|
|
"""
|
|
if not 0 <= self.max_retries <= 20:
|
|
raise ValueError(f"max_retries must be 0..20, got {self.max_retries}")
|
|
# Tests use very small backoff for fast-path retry coverage;
|
|
# production uses ~2.0s base. The 0.001 floor catches genuine
|
|
# mistakes (negative, 0.0) without rejecting valid test values.
|
|
if self.backoff_base_s < 0.001:
|
|
raise ValueError(f"backoff_base_s must be > 0, got {self.backoff_base_s}")
|
|
if self.backoff_max_s < 0.001:
|
|
raise ValueError(f"backoff_max_s must be > 0, got {self.backoff_max_s}")
|
|
if self.timeout_per_request_s is not None and self.timeout_per_request_s <= 0:
|
|
raise ValueError(
|
|
f"timeout_per_request_s must be > 0 or None, got {self.timeout_per_request_s}"
|
|
)
|
|
|
|
def to_json(self) -> str:
|
|
"""
|
|
Serialize the policy to a JSON string for cross-process
|
|
env-var transport.
|
|
|
|
Used by AP-side ``_serialize_retry_policy`` (Phase 1f of
|
|
``designs/RETRY_ACROSS_HARNESSES.md``) to thread the
|
|
spec's retry budget into CLI-harness subprocesses via
|
|
``HARNESS_*_RETRY_POLICY`` env vars. Round-trips with
|
|
:meth:`from_json` (which filters unknown keys for
|
|
forwards compatibility).
|
|
|
|
``retryable_status_codes`` is a tuple in the dataclass;
|
|
:func:`dataclasses.asdict` converts it to a list for JSON
|
|
(which has no tuple type). :meth:`from_json` reconstructs
|
|
the tuple on the read side.
|
|
|
|
:returns: JSON string encoding all policy fields, e.g.
|
|
``'{"max_retries": 7, "backoff_base_s": 2.0, ...}'``.
|
|
"""
|
|
import dataclasses
|
|
import json
|
|
|
|
return json.dumps(dataclasses.asdict(self))
|
|
|
|
@classmethod
|
|
def from_json(cls, payload: str) -> RetryPolicy:
|
|
"""
|
|
Deserialize a policy from the JSON wire format produced
|
|
by :meth:`to_json`.
|
|
|
|
Unknown keys are filtered out so older harness wraps stay
|
|
compatible with newer specs that add fields. Malformed
|
|
JSON, non-dict payloads, or values that fail
|
|
:meth:`__post_init__` validation all raise — the caller
|
|
decides whether to fall back to ``RetryPolicy()`` or
|
|
propagate.
|
|
|
|
:param payload: JSON string from :meth:`to_json`, e.g.
|
|
``'{"max_retries": 10, "backoff_base_s": 1.0}'``.
|
|
:returns: A :class:`RetryPolicy` reconstructed from the
|
|
payload, with defaults applied for any unspecified
|
|
fields.
|
|
:raises ValueError: If ``payload`` is not valid JSON,
|
|
does not decode to a dict, or fails the
|
|
:class:`RetryPolicy` field-bound validators.
|
|
"""
|
|
import json
|
|
|
|
try:
|
|
decoded = json.loads(payload)
|
|
except json.JSONDecodeError as exc:
|
|
raise ValueError(f"RetryPolicy.from_json: invalid JSON: {exc}") from exc
|
|
if not isinstance(decoded, dict):
|
|
raise ValueError(f"RetryPolicy.from_json: expected dict, got {type(decoded).__name__}")
|
|
# Filter to known fields. Forwards compatibility:
|
|
# newer specs may carry fields older wraps don't recognize;
|
|
# those are silently dropped. Backwards compatibility:
|
|
# missing fields fall back to dataclass defaults.
|
|
kwargs: dict[str, Any] = {} # type: ignore[explicit-any]
|
|
for field_name in (
|
|
"max_retries",
|
|
"backoff_base_s",
|
|
"backoff_max_s",
|
|
"jitter",
|
|
"timeout_per_request_s",
|
|
):
|
|
if field_name in decoded:
|
|
kwargs[field_name] = decoded[field_name]
|
|
# ``retryable_status_codes`` arrives as a JSON list; the
|
|
# dataclass declares it as ``tuple[int, ...]``. Convert
|
|
# before construction so equality checks (e.g. against
|
|
# the default) and downstream consumers see the
|
|
# canonical type.
|
|
if "retryable_status_codes" in decoded:
|
|
codes = decoded["retryable_status_codes"]
|
|
if not isinstance(codes, list):
|
|
raise ValueError(
|
|
f"RetryPolicy.from_json: "
|
|
f"retryable_status_codes must be a list, got "
|
|
f"{type(codes).__name__}"
|
|
)
|
|
kwargs["retryable_status_codes"] = tuple(codes)
|
|
return cls(**kwargs)
|
|
|
|
@property
|
|
def openai(self) -> _OpenAIRetryAdapter:
|
|
"""Adapter for ``AsyncOpenAI`` / ``OpenAI`` clients."""
|
|
return _OpenAIRetryAdapter(self)
|
|
|
|
@property
|
|
def anthropic(self) -> _AnthropicRetryAdapter:
|
|
"""Adapter for ``Anthropic`` / ``AsyncAnthropic`` clients."""
|
|
return _AnthropicRetryAdapter(self)
|
|
|
|
@property
|
|
def claude_cli(self) -> _ClaudeCliRetryAdapter:
|
|
"""Adapter for the Claude CLI subprocess."""
|
|
return _ClaudeCliRetryAdapter(self)
|
|
|
|
@property
|
|
def codex_cli(self) -> _CodexCliRetryAdapter:
|
|
"""Adapter for the Codex CLI subprocess."""
|
|
return _CodexCliRetryAdapter(self)
|
|
|
|
@property
|
|
def pi(self) -> _PiRetryAdapter:
|
|
"""Adapter for the Pi CLI subprocess."""
|
|
return _PiRetryAdapter(self)
|
|
|
|
def compute_backoff_delay(
|
|
self,
|
|
retry_index: int,
|
|
retry_after_s: float | None = None,
|
|
) -> float:
|
|
"""
|
|
Delay before retry attempt at L2 or in the in-process LLM
|
|
path's retry loop.
|
|
|
|
:param retry_index: 1-indexed retry number — ``1`` is the
|
|
delay before the first retry.
|
|
:param retry_after_s: Server-requested retry hint. When
|
|
provided, the returned delay is at least
|
|
``retry_after_s``, capped by ``backoff_max_s``. ``None``
|
|
means no server hint — pure exponential backoff applies.
|
|
:returns: Delay in seconds.
|
|
"""
|
|
import random
|
|
|
|
delay: float = self.backoff_base_s * float(2 ** (retry_index - 1))
|
|
if retry_after_s is not None:
|
|
delay = max(delay, retry_after_s)
|
|
delay = min(delay, self.backoff_max_s)
|
|
if self.jitter:
|
|
# ``random.uniform`` is typed as ``Any``-returning by
|
|
# the stdlib stub; cast to float so the function's
|
|
# declared return type holds without leaking ``Any``.
|
|
delay = float(delay * random.uniform(0.5, 1.5))
|
|
return delay
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class _OpenAIRetryAdapter:
|
|
"""Sub-object: produces L0 args for OpenAI SDK clients."""
|
|
|
|
policy: RetryPolicy
|
|
|
|
def kwargs(self) -> dict[str, Any]: # type: ignore[explicit-any]
|
|
"""
|
|
Args for ``AsyncOpenAI(...)`` / ``OpenAI(...)``
|
|
constructors. Spread with ``**``.
|
|
|
|
:returns: Dict with ``max_retries`` always, ``timeout``
|
|
when configured.
|
|
"""
|
|
kwargs: dict[str, Any] = {"max_retries": self.policy.max_retries} # type: ignore[explicit-any]
|
|
if self.policy.timeout_per_request_s is not None:
|
|
kwargs["timeout"] = self.policy.timeout_per_request_s
|
|
return kwargs
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class _AnthropicRetryAdapter:
|
|
"""Sub-object: produces L0 args for Anthropic SDK clients."""
|
|
|
|
policy: RetryPolicy
|
|
|
|
def kwargs(self) -> dict[str, Any]: # type: ignore[explicit-any]
|
|
"""
|
|
Args for ``Anthropic(...)`` / ``AsyncAnthropic(...)``
|
|
constructors. Spread with ``**``.
|
|
|
|
:returns: Dict with ``max_retries`` always, ``timeout``
|
|
when configured.
|
|
"""
|
|
kwargs: dict[str, Any] = {"max_retries": self.policy.max_retries} # type: ignore[explicit-any]
|
|
if self.policy.timeout_per_request_s is not None:
|
|
kwargs["timeout"] = self.policy.timeout_per_request_s
|
|
return kwargs
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class _ClaudeCliRetryAdapter:
|
|
"""Sub-object: produces env vars for the Claude CLI subprocess."""
|
|
|
|
policy: RetryPolicy
|
|
|
|
def env(self) -> dict[str, str]:
|
|
"""
|
|
Env vars to merge into ``ClaudeAgentOptions.env``.
|
|
|
|
The Claude CLI's retry budget isn't publicly documented as
|
|
env-tunable; we set Anthropic SDK conventions
|
|
speculatively.
|
|
|
|
:returns: Dict mapping env var names to string values.
|
|
"""
|
|
env: dict[str, str] = {
|
|
"ANTHROPIC_MAX_RETRIES": str(self.policy.max_retries),
|
|
}
|
|
if self.policy.timeout_per_request_s is not None:
|
|
env["ANTHROPIC_REQUEST_TIMEOUT_SECONDS"] = str(int(self.policy.timeout_per_request_s))
|
|
return env
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class _CodexCliRetryAdapter:
|
|
"""Sub-object: produces env vars for the Codex CLI subprocess."""
|
|
|
|
policy: RetryPolicy
|
|
|
|
def env(self) -> dict[str, str]:
|
|
"""
|
|
Env vars to merge into the Codex CLI subprocess env.
|
|
Codex uses the OpenAI SDK internally; presumed to honor
|
|
standard OpenAI env vars.
|
|
|
|
:returns: Dict mapping env var names to string values.
|
|
"""
|
|
env: dict[str, str] = {
|
|
"OPENAI_MAX_RETRIES": str(self.policy.max_retries),
|
|
}
|
|
if self.policy.timeout_per_request_s is not None:
|
|
env["OPENAI_TIMEOUT"] = str(int(self.policy.timeout_per_request_s))
|
|
return env
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class _PiRetryAdapter:
|
|
"""Sub-object: produces a settings.json patch for Pi."""
|
|
|
|
policy: RetryPolicy
|
|
|
|
def settings(self) -> dict[str, Any]: # type: ignore[explicit-any]
|
|
"""
|
|
``retry`` block to merge into Pi's ``.pi/settings.json``
|
|
before subprocess spawn.
|
|
|
|
Schema audited from
|
|
``@earendil-works/pi-coding-agent/docs/settings.md``
|
|
(github.com/earendil-works/pi; formerly published as
|
|
``@mariozechner/pi-coding-agent@0.68.1``, same settings
|
|
schema). Pi natively implements exponential backoff with
|
|
jitter and ``Retry-After`` honoring; we configure the budget
|
|
and shape.
|
|
|
|
:returns: A dict matching Pi's settings shape.
|
|
"""
|
|
return {
|
|
"retry": {
|
|
"enabled": self.policy.max_retries > 0,
|
|
"maxRetries": self.policy.max_retries,
|
|
"baseDelayMs": int(self.policy.backoff_base_s * 1000),
|
|
"maxDelayMs": int(self.policy.backoff_max_s * 1000),
|
|
},
|
|
}
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class ApiKeyAuth:
|
|
"""
|
|
Executor authentication via a direct OpenAI-compatible API key.
|
|
|
|
Use this when the LLM endpoint is reached with a bearer token
|
|
(OpenAI, Azure OpenAI, or any OpenAI-compatible provider).
|
|
|
|
Preferred over raw env-var fallback because the key is explicit
|
|
in the spec: the agent's behaviour is self-contained and does not
|
|
depend on ambient ``OPENAI_API_KEY`` in the caller's shell.
|
|
|
|
Example YAML (OpenAI)::
|
|
|
|
executor:
|
|
auth:
|
|
type: api_key
|
|
api_key: $OPENAI_API_KEY
|
|
|
|
Example YAML (custom OpenAI-compatible endpoint)::
|
|
|
|
executor:
|
|
auth:
|
|
type: api_key
|
|
api_key: $MY_KEY
|
|
base_url: https://my-gateway.example.com/v1
|
|
|
|
:param api_key: The resolved API key value. Env-var references
|
|
(e.g. ``$OPENAI_API_KEY``) are expanded at parse time.
|
|
:param base_url: Optional OpenAI-compatible endpoint URL,
|
|
e.g. ``"https://my-gateway.example.com/v1"``. When omitted,
|
|
the default ``https://api.openai.com/v1`` is used.
|
|
"""
|
|
|
|
# Required: the resolved API key value (env-var refs expanded at parse time).
|
|
api_key: str
|
|
# Optional: custom endpoint; None means use the default OpenAI endpoint.
|
|
base_url: str | None = None
|
|
type: Literal["api_key"] = "api_key"
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class DatabricksAuth:
|
|
"""
|
|
Executor authentication via a Databricks profile from
|
|
``~/.databrickscfg``.
|
|
|
|
Use this to route LLM calls through Databricks model serving
|
|
(Unity AI Gateway or another Databricks-hosted endpoint) using
|
|
a named credential profile.
|
|
|
|
Example YAML::
|
|
|
|
executor:
|
|
auth:
|
|
type: databricks
|
|
profile: oss
|
|
|
|
:param profile: Databricks profile name from ``~/.databrickscfg``,
|
|
e.g. ``"oss"``. The executor resolves workspace host and
|
|
OAuth token from this profile at runtime.
|
|
"""
|
|
|
|
# Required: Databricks profile name from ~/.databrickscfg (e.g. "oss").
|
|
profile: str
|
|
type: Literal["databricks"] = "databricks"
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class ProviderAuth:
|
|
"""
|
|
Executor authentication via a named generic model provider.
|
|
|
|
References a provider declared in the ``providers:`` block of
|
|
``~/.omnigent/config.yaml`` (see
|
|
``designs/oss-cuj/04-model-selection-implementation.md``). The
|
|
provider entry carries a ``kind`` (``key`` / ``subscription`` /
|
|
``gateway`` / ``local`` / ``databricks``) and, for the inline
|
|
kinds, per-harness families (``anthropic`` for Claude-style
|
|
harnesses, ``openai`` for Codex-style) supplying base URLs, secret
|
|
references, default models, and wire protocols. This is the
|
|
open-source counterpart to :class:`DatabricksAuth`: a single named
|
|
provider (e.g. a LiteLLM proxy or OpenRouter) can route every
|
|
harness family.
|
|
|
|
Example YAML::
|
|
|
|
executor:
|
|
auth:
|
|
type: provider
|
|
name: litellm
|
|
|
|
:param name: Provider name keyed under ``providers:`` in the global
|
|
config, e.g. ``"litellm"`` or ``"openrouter"``. The harness
|
|
spawn-env builder resolves the appropriate family (``anthropic``
|
|
for Claude-style harnesses, ``openai`` for Codex-style) at
|
|
runtime.
|
|
:param type: Discriminator literal, always ``"provider"``. Lets the
|
|
:data:`ExecutorAuth` union distinguish this from
|
|
:class:`ApiKeyAuth` / :class:`DatabricksAuth`.
|
|
"""
|
|
|
|
# Required: provider name from ~/.omnigent/config.yaml providers:.
|
|
name: str
|
|
type: Literal["provider"] = "provider"
|
|
|
|
|
|
# Discriminated union of all supported executor auth types.
|
|
# Discriminator field is ``type``.
|
|
ExecutorAuth = ApiKeyAuth | DatabricksAuth | ProviderAuth
|
|
|
|
|
|
@dataclass
|
|
class ExecutorSpec: # type: ignore[explicit-any] # config: dict[str, Any] field (see below)
|
|
"""
|
|
Top-level executor configuration.
|
|
|
|
``type`` is the discriminator for the entire spec's validity —
|
|
it determines which other top-level sections and fields are
|
|
valid. Invalid fields are rejected by the validator.
|
|
|
|
:param type: Executor type. ``"omnigent"`` (default),
|
|
``"claude_sdk"``, or ``"agents_sdk"``.
|
|
:param timeout: Task deadline in seconds (wall-clock limit for
|
|
the entire agent loop), e.g. ``3600``.
|
|
:param max_iterations: Maximum ``run_turn()`` calls before the
|
|
loop terminates as incomplete, e.g. ``1000``.
|
|
:param profile: The Databricks workspace profile name from
|
|
``~/.databrickscfg``, e.g. ``"dev"``. During the
|
|
omnigent-compat sunset this is lifted from raw YAML's
|
|
``executor.profile`` in the omnigent path too. ``None``
|
|
means resolve via env vars / DEFAULT section.
|
|
|
|
.. deprecated::
|
|
Set ``executor.auth: {type: databricks, profile: <name>}``
|
|
instead. Direct ``executor.profile`` / ``executor.config.profile``
|
|
will be removed once all callers migrate.
|
|
:param config: Executor-type-specific configuration. For
|
|
``type == "omnigent"`` this carries ``"harness"`` (e.g.
|
|
``"claude-sdk"`` or ``"codex"``), optional ``"profile"``
|
|
(e.g. ``"<your-profile>"``), and optional ``"os_env"`` — the
|
|
latter is a nested mapping mirroring the omnigent
|
|
``OSEnvSpec`` shape (``{type, cwd, sandbox: {...}}``) or
|
|
the literal string ``"inherit"`` on inline-AgentTool
|
|
sub-specs. Empty dict for other executor types.
|
|
|
|
🚨 **TECH DEBT — REMOVE WHEN OMNIGENT COMPAT ENDS.**
|
|
This field exists *solely* to carry harness / profile /
|
|
os_env data for the Omnigent integration (see
|
|
``designs/OMNIGENT_INTEGRATION.md``). A free-form
|
|
``dict[str, Any]`` on a spec dataclass is the kind of
|
|
bag-of-values escape hatch we'd otherwise reject in
|
|
review — acceptable here only because the Omnigent
|
|
executor is a temporary bridge with explicit sunset
|
|
criteria. Once Omnigent is consolidated (phase 6 of the
|
|
integration design), this field and every reader of it
|
|
must go away. Do NOT use ``config`` as a general-purpose
|
|
extension point for new executor types — add concrete
|
|
fields instead.
|
|
|
|
The value type widened from ``dict[str, str]`` to
|
|
``dict[str, Any]`` when OSEnvSpec support landed, since
|
|
the nested ``sandbox`` mapping can't be flattened to
|
|
string values without losing fidelity.
|
|
:param model: The provider-prefixed model identifier, e.g.
|
|
``"databricks-gpt-5-5"`` or ``"openai/gpt-5.4"``. Primary
|
|
source of truth for the model across all executor types —
|
|
populated by the parser from either the ``executor.model``
|
|
YAML key or (for backward compatibility) the ``llm.model``
|
|
key. Used by harness spawn-env builders, context-window
|
|
auto-detection, telemetry, and tool-provider inference.
|
|
``None`` only when no model is declared anywhere in the spec.
|
|
:param connection: Per-provider connection overrides (credentials,
|
|
endpoint URLs), e.g.
|
|
``{"api_key": "sk-...", "base_url": "https://..."}``.
|
|
Primary source of truth for connection configuration —
|
|
populated by the parser from either the ``executor.connection``
|
|
YAML key or (for backward compatibility) the ``llm.connection``
|
|
key. Keys are provider-specific: ``api_key`` + ``base_url``
|
|
for OpenAI-compatible providers, ``aws_region`` for Bedrock,
|
|
etc. ``None`` means use environment variable defaults or
|
|
profile-based credential resolution.
|
|
:param context_window: Explicit context window size for the model,
|
|
in tokens (input + output combined). When set, overrides the
|
|
automatic litellm / catalog lookup for both the REPL context
|
|
ring and the compression threshold. Use this for models that
|
|
are not yet in the registry, e.g. ``context_window: 400000``
|
|
in ``config.yaml``. ``None`` means auto-detect (default).
|
|
:param auth: Explicit LLM authentication configuration. When set,
|
|
the harness uses this to authenticate instead of falling back
|
|
to ambient environment variables or profile auto-detection.
|
|
Supports three types: :class:`ApiKeyAuth` (inline bearer token),
|
|
:class:`DatabricksAuth` (Databricks profile, ucode-backed), and
|
|
:class:`ProviderAuth` (a named generic provider from
|
|
``~/.omnigent/config.yaml``). ``None`` means fall back to
|
|
environment variable / profile defaults.
|
|
"""
|
|
|
|
type: str = "omnigent"
|
|
timeout: int = 3600
|
|
max_iterations: int = 1000
|
|
# Databricks workspace profile name from ~/.databrickscfg.
|
|
# During the omnigent-compat sunset, lifted from raw YAML's
|
|
# executor.profile in the omnigent path too. None = resolve
|
|
# via env vars / DEFAULT section. See class docstring.
|
|
# DEPRECATED: use executor.auth: {type: databricks, profile: <name>} instead.
|
|
profile: str | None = None
|
|
# TECH DEBT (omnigent compat only — see class docstring).
|
|
# Remove when Omnigent consolidation lands; do NOT extend.
|
|
# Any: opaque per-type executor config passed through to adapters.
|
|
config: dict[str, Any] = field(default_factory=dict) # type: ignore[explicit-any]
|
|
# Primary model identifier for all executor types. Populated by
|
|
# the parser from executor.model or (backward compat) llm.model.
|
|
model: str | None = None
|
|
# Per-provider connection overrides (api_key, base_url, etc.).
|
|
# Populated from executor.connection or (backward compat) llm.connection.
|
|
# None means rely on environment variable / profile defaults.
|
|
connection: dict[str, str] | None = None
|
|
# Explicit context window override (input + output tokens). None = auto-detect via litellm.
|
|
context_window: int | None = None
|
|
# Explicit executor auth. Populated from executor.auth in the YAML.
|
|
# Takes precedence over ambient env vars and profile auto-detection.
|
|
# None = fall back to env vars / profile defaults.
|
|
auth: ApiKeyAuth | DatabricksAuth | ProviderAuth | None = None
|
|
|
|
@property
|
|
def harness_kind(self) -> str:
|
|
"""
|
|
The agent's harness/kind for display and discovery.
|
|
|
|
For ``type == "omnigent"`` the kind lives in
|
|
``config["harness"]`` (e.g. ``"codex"``, ``"codex-native"``,
|
|
``"claude-native"``); for every other executor type the kind
|
|
*is* the executor type (e.g. ``"claude_sdk"``,
|
|
``"agents_sdk"``). Consumed by the ``GET /v1/agents`` catalog
|
|
and ``GET /v1/sessions/{id}/agent`` so the Web UI can tell
|
|
Codex from Claude agents without matching on the name slug.
|
|
|
|
:returns: The harness identifier, e.g. ``"codex"`` or
|
|
``"claude_sdk"``. Never empty — falls back to
|
|
:attr:`type`.
|
|
"""
|
|
return self.config.get("harness") or self.type
|
|
|
|
|
|
@dataclass
|
|
class CompactionConfig:
|
|
"""
|
|
Context compaction configuration.
|
|
|
|
Controls when the agent compacts its conversation history to
|
|
stay within the LLM's context window. Compaction is layered:
|
|
(1) clear tool result bodies, (2) LLM summarization, (3)
|
|
truncation as emergency fallback.
|
|
|
|
:param trigger_threshold: Fraction of the model's context window
|
|
at which proactive compaction fires (after the first overflow
|
|
has been observed and the window size is known), e.g. ``0.8``
|
|
means fire at 80% of the window.
|
|
:param recent_window: Number of recent LLM iterations to protect
|
|
from compaction. Items within this window are never cleared or
|
|
summarized — the agent always has verbatim access to its most
|
|
recent work, e.g. ``5``.
|
|
"""
|
|
|
|
trigger_threshold: float = 0.8
|
|
recent_window: int = 5
|
|
|
|
|
|
@dataclass
|
|
class LLMConfig: # type: ignore[explicit-any] # extra: dict[str, Any] field (see below)
|
|
"""
|
|
LLM configuration block from config.yaml.
|
|
|
|
``model`` is the only required field. ``request_timeout`` and
|
|
``retry`` control call-level resilience. All other keys from the
|
|
YAML ``llm:`` block are collected into ``extra`` and passed
|
|
through to the OpenAI SDK as-is.
|
|
|
|
:param model: The provider-prefixed model identifier, e.g.
|
|
``"openai/gpt-5.4"`` or ``"anthropic/claude-sonnet-4-20250514"``.
|
|
:param extra: Arbitrary kwargs from the YAML ``llm:`` block
|
|
(everything except ``model``, ``connection``,
|
|
``request_timeout``, and ``retry``). Values are heterogeneous
|
|
(str, int, dict, etc.) so ``Any`` is the narrowest safe type.
|
|
Example: ``{"temperature": 0.7, "max_tokens": 4096}``.
|
|
:param connection: Per-provider connection overrides from the
|
|
YAML ``connection:`` sub-block. Keys are provider-specific,
|
|
e.g. ``{"api_key": "...", "base_url": "..."}`` for
|
|
OpenAI-compatible providers or
|
|
``{"aws_region": "us-west-2"}`` for Bedrock.
|
|
``None`` means use environment variable defaults.
|
|
:param profile: Databricks CLI profile name from
|
|
``~/.databrickscfg``, e.g. ``"my-workspace"``. When set,
|
|
the profile is resolved to workspace credentials at build
|
|
time and used as the connection. ``None`` means no profile
|
|
— use ``connection`` or environment defaults. ``connection``
|
|
wins when both are present.
|
|
:param request_timeout: Per-LLM-call timeout in seconds (both
|
|
streaming and non-streaming), e.g. ``300``. Named
|
|
``request_timeout`` to distinguish from the task-level
|
|
``executor.timeout``.
|
|
:param retry: Retry policy for transient LLM failures.
|
|
"""
|
|
|
|
model: str
|
|
# Arbitrary kwargs from the YAML llm block (everything except
|
|
# ``model``, ``connection``, ``request_timeout``, ``profile``,
|
|
# and ``retry``).
|
|
# Values are heterogeneous (str, int, dict, etc.) so Any is the
|
|
# narrowest safe type.
|
|
extra: dict[str, Any] = field(default_factory=dict) # type: ignore[explicit-any]
|
|
# Per-provider connection overrides (api_key, base_url, etc.).
|
|
# None means rely on environment variable defaults.
|
|
connection: dict[str, str] | None = None
|
|
# Databricks CLI profile name for profile-based auth.
|
|
profile: str | None = None
|
|
request_timeout: int = 300
|
|
retry: RetryPolicy = field(default_factory=RetryPolicy)
|
|
|
|
|
|
@dataclass
|
|
class ModalityConfig:
|
|
"""
|
|
Declared input/output content types.
|
|
|
|
:param input: Accepted input modalities. Valid values are
|
|
``"text"``, ``"image"``, ``"audio"``, ``"video"``, and
|
|
``"file"``. Defaults to ``["text"]``.
|
|
:param output: Produced output modalities. Valid values are
|
|
``"text"``, ``"image"``, and ``"audio"``. Defaults to
|
|
``["text"]``.
|
|
"""
|
|
|
|
input: list[str] = field(default_factory=lambda: ["text"])
|
|
output: list[str] = field(default_factory=lambda: ["text"])
|
|
|
|
|
|
@dataclass
|
|
class InteractionConfig:
|
|
"""
|
|
Interaction contract: conversational mode and modalities.
|
|
|
|
:param conversational: Whether the agent supports multi-turn
|
|
conversation. Defaults to ``True``.
|
|
:param modalities: Input/output content type declarations.
|
|
Defaults to text-only.
|
|
"""
|
|
|
|
conversational: bool = True
|
|
modalities: ModalityConfig = field(default_factory=ModalityConfig)
|
|
|
|
|
|
@dataclass
|
|
class BuiltinToolConfig:
|
|
"""
|
|
Configuration for a single built-in tool declared in
|
|
``tools.builtins``.
|
|
|
|
:param name: The registered tool name, e.g.
|
|
``"web_search"``.
|
|
:param config: Tool-specific key-value pairs, e.g.
|
|
``{"api_key": "AIza...", "engine_id": "abc123"}``.
|
|
Empty when the tool needs no configuration.
|
|
"""
|
|
|
|
name: str
|
|
config: dict[str, str] = field(default_factory=dict)
|
|
|
|
|
|
@dataclass
|
|
class SandboxConfig:
|
|
"""
|
|
Agent-level sandbox configuration for local tool execution.
|
|
|
|
Only contains settings the agent author controls (what
|
|
execution environment their tools need). Whether sandboxing
|
|
is enabled/enforced is a runtime decision — see
|
|
``RuntimeCaps.sandbox_enabled``.
|
|
|
|
:param container_image: When set, tools run inside this
|
|
container instead of a local subprocess, e.g.
|
|
``"python:3.12-slim"``.
|
|
:param docker_image: Deprecated alias for ``container_image``.
|
|
If both are set, ``container_image`` takes precedence.
|
|
:param container_runtime: The container CLI to use, either
|
|
``"docker"`` (default) or ``"podman"``.
|
|
"""
|
|
|
|
container_image: str | None = None
|
|
docker_image: str | None = None
|
|
container_runtime: Literal["docker", "podman"] = "docker"
|
|
|
|
_ALLOWED_RUNTIMES = frozenset({"docker", "podman"})
|
|
|
|
def __post_init__(self) -> None:
|
|
if self.container_runtime not in self._ALLOWED_RUNTIMES:
|
|
raise ValueError(
|
|
f"container_runtime must be one of {sorted(self._ALLOWED_RUNTIMES)}, "
|
|
f"got {self.container_runtime!r}"
|
|
)
|
|
# Resolve the deprecated docker_image alias: if only
|
|
# docker_image was provided, promote it to container_image.
|
|
# Then sync docker_image to container_image so both fields
|
|
# always agree after construction.
|
|
if self.container_image is None and self.docker_image is not None:
|
|
self.container_image = self.docker_image
|
|
self.docker_image = self.container_image
|
|
|
|
|
|
@dataclass
|
|
class ToolsConfig:
|
|
"""
|
|
Declared tool references from config.yaml.
|
|
|
|
:param agents: Names of sub-agents this agent can delegate to,
|
|
e.g. ``["summarizer", "code-reviewer"]``. Each name must
|
|
match a directory under ``agents/``.
|
|
:param builtins: Built-in tools to enable, e.g.
|
|
``[BuiltinToolConfig(name="web_search")]``. Each
|
|
entry carries the tool name and optional config fields
|
|
(API keys, engine IDs, etc.).
|
|
:param timeout: Default timeout in seconds for all tool calls,
|
|
e.g. ``60``. Individual tools can override this.
|
|
:param retry: Default retry policy for all tool calls.
|
|
Individual tools can override this.
|
|
"""
|
|
|
|
agents: list[str] = field(default_factory=list)
|
|
builtins: list[BuiltinToolConfig] = field(default_factory=list)
|
|
timeout: int = 60
|
|
retry: RetryPolicy = field(
|
|
default_factory=lambda: RetryPolicy(
|
|
max_retries=1,
|
|
backoff_base_s=1.0,
|
|
backoff_max_s=10.0,
|
|
)
|
|
)
|
|
sandbox: SandboxConfig = field(default_factory=SandboxConfig)
|
|
|
|
|
|
@dataclass
|
|
class SkillSpec:
|
|
"""
|
|
A parsed skill from ``skills/<name>/SKILL.md``.
|
|
|
|
:param name: Lowercase kebab-case skill identifier, e.g.
|
|
``"code-review"``. Must match ``[a-z0-9-]+``.
|
|
:param description: Human-readable summary of what the skill
|
|
does (max 1024 characters).
|
|
:param content: The body of the SKILL.md file after the YAML
|
|
frontmatter, containing the skill's instructions.
|
|
:param skill_dir: Absolute path to the skill's directory on
|
|
disk, e.g. ``Path("/agents/code-review")``. Used by
|
|
``read_skill_file`` to resolve resource paths. ``None``
|
|
when the skill was created in-memory (e.g. tests).
|
|
:param user_invocable: Whether the skill may be invoked directly
|
|
by a user as a slash command. ``False`` for internal
|
|
orchestration skills (frontmatter ``user-invocable: false``);
|
|
such skills are excluded from the composer's ``/`` menu.
|
|
Defaults to ``True`` (absent frontmatter field = invocable).
|
|
"""
|
|
|
|
name: str
|
|
description: str
|
|
content: str
|
|
skill_dir: Path | None = None
|
|
user_invocable: bool = True
|
|
|
|
|
|
@dataclass
|
|
class MCPServerConfig:
|
|
"""
|
|
An MCP server declaration from ``tools/mcp/<name>.yaml``.
|
|
|
|
Two transports are supported:
|
|
|
|
- ``"http"`` — HTTP (SSE) endpoint, reached via
|
|
:func:`mcp.client.sse.sse_client`. ``url`` (and optionally
|
|
``headers``) describe the endpoint. Traditional "deployed MCP"
|
|
shape: the server runs elsewhere; this process is just a
|
|
client.
|
|
- ``"stdio"`` — local subprocess, spawned via
|
|
:func:`mcp.client.stdio.stdio_client`. ``command`` and
|
|
``args`` describe the program to run; ``env`` supplies
|
|
per-process environment variables on top of the parent's
|
|
environment. The subprocess runs unsandboxed — same as the
|
|
legacy inner stack at ``omnigent/inner/mcp_tools.py``
|
|
(which has never sandboxed stdio MCPs). The previous
|
|
AP-only ``sandbox: bool`` field that wrapped the spawn
|
|
with ``srt`` was removed in step 7 of the harness contract
|
|
migration: srt's default policy blocks outbound network
|
|
(which every useful MCP needs to reach its backend), so
|
|
sandboxing was producing silent hangs in practice. Per-MCP
|
|
sandboxing through the ``omnigent/environments/``
|
|
primitive with explicit outbound-host allowlists is the
|
|
eventual replacement; left to a future design.
|
|
|
|
Validator enforces that HTTP fields (``url``, ``headers``) and
|
|
stdio fields (``command``, ``args``, ``env``) don't appear on
|
|
the wrong transport.
|
|
|
|
:param name: Unique server identifier, e.g. ``"github"``.
|
|
:param transport: ``"http"`` or ``"stdio"``. Default
|
|
``"http"`` for backwards compatibility with existing
|
|
``tools/mcp/<name>.yaml`` files that pre-date the stdio
|
|
branch.
|
|
:param url: HTTP (SSE) endpoint URL, e.g.
|
|
``"https://mcp.example.com/sse"``. Required when
|
|
``transport == "http"``; invalid for ``"stdio"``.
|
|
:param headers: HTTP headers, e.g.
|
|
``{"Authorization": "Bearer tok_xyz"}``. Valid only on
|
|
``"http"``.
|
|
:param databricks_profile: Databricks profile name from
|
|
``~/.databrickscfg``, e.g. ``"oss"``. When set, the
|
|
connection resolves an OAuth token at runtime and injects
|
|
``Authorization: Bearer <token>`` into the HTTP headers.
|
|
Valid only on ``"http"``. Avoids hardcoding short-lived
|
|
tokens in the YAML.
|
|
:param command: Executable to spawn, e.g. ``"npx"``. Required
|
|
when ``transport == "stdio"``; invalid for ``"http"``.
|
|
:param args: Arguments to pass to *command*, e.g.
|
|
``["-y", "@modelcontextprotocol/server-github"]``. Valid
|
|
only on ``"stdio"``.
|
|
:param env: Environment variables to set on the spawned
|
|
subprocess (overlaid on the parent environment). Valid
|
|
only on ``"stdio"``. Use for secrets the subprocess reads
|
|
at startup, e.g. ``{"GITHUB_TOKEN": "${GITHUB_TOKEN}"}``.
|
|
:param description: Optional human-readable summary of the
|
|
server's purpose.
|
|
:param timeout: Per-tool timeout in seconds. ``None`` inherits
|
|
``tools.timeout``. When ultimately ``None`` at runtime, the
|
|
MCP SDK defaults apply: 5 s for the initial HTTP connection
|
|
handshake and 300 s (5 min) for each SSE event read.
|
|
Stdio transport applies the same value to session
|
|
initialization and tool calls.
|
|
:param retry: Per-tool retry policy. ``None`` inherits
|
|
``tools.retry``.
|
|
"""
|
|
|
|
name: str
|
|
transport: Literal["http", "stdio"] = "http"
|
|
# HTTP-only fields.
|
|
url: str | None = None
|
|
headers: dict[str, str] = field(default_factory=dict, repr=False)
|
|
# Databricks profile auth — resolves a bearer token at connection
|
|
# time from ``~/.databrickscfg`` and injects it as the
|
|
# ``Authorization`` header. Mutually usable with ``headers``:
|
|
# explicit headers win if both set ``Authorization``.
|
|
databricks_profile: str | None = None
|
|
# Stdio-only fields.
|
|
command: str | None = None
|
|
args: list[str] = field(default_factory=list)
|
|
env: dict[str, str] = field(default_factory=dict, repr=False)
|
|
# Optional per-server tool allow-list: only these tool names are exposed to
|
|
# the model; others are filtered at registration (server/mcp_pool.py,
|
|
# runner/mcp_manager.py). ``None`` exposes all. Applies to both transports
|
|
# and mirrors ``MCPTool.tools`` / the YAML ``tools:`` whitelist documented
|
|
# in docs/AGENT_YAML_SPEC.md.
|
|
tools: list[str] | None = None
|
|
description: str | None = None
|
|
# Per-tool timeout/retry overrides. None = inherit from
|
|
# tools.timeout / tools.retry.
|
|
timeout: int | None = None
|
|
retry: RetryPolicy | None = None
|
|
|
|
def __repr__(self) -> str:
|
|
"""
|
|
String representation that redacts secret-bearing fields.
|
|
|
|
Header and env values are replaced with ``"[REDACTED]"`` —
|
|
credentials commonly travel through these fields and we
|
|
don't want them in exception tracebacks / log scrapes.
|
|
Keys are preserved so operators can still tell which
|
|
secrets were attached.
|
|
"""
|
|
redacted_headers = dict.fromkeys(self.headers, "[REDACTED]") if self.headers else {}
|
|
redacted_env = dict.fromkeys(self.env, "[REDACTED]") if self.env else {}
|
|
return (
|
|
f"MCPServerConfig(name={self.name!r}, transport={self.transport!r}, "
|
|
f"url={self.url!r}, headers={redacted_headers!r}, "
|
|
f"databricks_profile={self.databricks_profile!r}, "
|
|
f"command={self.command!r}, args={self.args!r}, "
|
|
f"env={redacted_env!r}, "
|
|
f"timeout={self.timeout!r}, retry={self.retry!r})"
|
|
)
|
|
|
|
|
|
class ToolRuntime(str, Enum):
|
|
"""Where a function tool's implementation lives.
|
|
|
|
- :attr:`SERVER`: server loads a dotted ``callable:`` path.
|
|
- :attr:`CLIENT`: SDK consumer provides the impl at stream
|
|
start. ``callable:`` is forbidden (validation error).
|
|
- :attr:`UC_FUNCTION`: tool backed by a Unity Catalog SQL
|
|
function. Executed via ``WorkspaceClient
|
|
.statement_execution.execute_statement()`` at tool-call
|
|
time. ``path`` is ``None``; ``catalog_path`` carries the
|
|
three-level UC name (``catalog.schema.function``).
|
|
"""
|
|
|
|
SERVER = "server"
|
|
CLIENT = "client"
|
|
UC_FUNCTION = "uc_function"
|
|
|
|
|
|
class SharePolicy(str, Enum):
|
|
"""How much session-sharing authority ``sys_session_share`` grants.
|
|
|
|
Maps the top-level ``agent_session_sharing:`` YAML flag. The flag is
|
|
the *only* thing that enables the ``sys_session_share`` tool — it is
|
|
independent of ``spawn`` / ``tools.agents`` (which gate the
|
|
spawn-lifecycle tools). Sharing mutates access control, so it is
|
|
off by default and the public tier is a deliberate extra opt-in.
|
|
|
|
- :attr:`NONE`: sharing disabled — ``sys_session_share`` is not
|
|
registered at all (default).
|
|
- :attr:`NON_PUBLIC`: the agent may grant access to named users
|
|
(emails), but NOT to ``__public__`` — no anonymous-read exposure.
|
|
- :attr:`PUBLIC`: the agent may additionally grant ``__public__``
|
|
(anonymous read of the full transcript).
|
|
"""
|
|
|
|
NONE = "none"
|
|
NON_PUBLIC = "non-public"
|
|
PUBLIC = "public"
|
|
|
|
|
|
@dataclass
|
|
class LocalToolInfo: # type: ignore[explicit-any] # parameters: dict[str, Any] field (see below)
|
|
"""
|
|
A discovered local tool file (Python or TypeScript).
|
|
|
|
:param name: Derived tool name from filename stem,
|
|
e.g. ``"arxiv_search"`` (from ``arxiv_search.py``).
|
|
:param path: Dotted callable path or relative file path within
|
|
the agent image, e.g.
|
|
``"examples._shared.tool_functions.search_web"`` or
|
|
``"tools/python/arxiv_search.py"``. ``None`` only when
|
|
:attr:`runtime` is :attr:`ToolRuntime.CLIENT` — client-runtime
|
|
tools have no server-side implementation, so they have no
|
|
path. The validator enforces the runtime↔path invariant
|
|
(server requires a path; client forbids one).
|
|
:param language: Source language. Either ``"python"`` or
|
|
``"typescript"``.
|
|
:param timeout: Per-tool timeout in seconds. ``None`` inherits
|
|
``tools.timeout``.
|
|
:param retry: Per-tool retry policy. ``None`` inherits
|
|
``tools.retry``.
|
|
:param has_inline_deps: ``True`` if the tool file contains
|
|
PEP 723 inline script metadata with dependencies.
|
|
:param inline_deps: PEP 508 dependency specifiers extracted
|
|
from the ``# /// script`` block. ``None`` when no
|
|
inline metadata is present.
|
|
:param parameters: JSON-Schema ``parameters`` block. ``None``
|
|
means "use the harness default" (introspection for plain
|
|
callables). Required for :class:`CancellableFunctionTool`
|
|
(no inspectable signature) and for client-runtime tools
|
|
(no server-side callable).
|
|
:param runtime: See :class:`ToolRuntime`. Client tools forbid
|
|
:attr:`path` and require explicit :attr:`parameters`.
|
|
:param catalog_path: Three-level Unity Catalog function name,
|
|
e.g. ``"my_catalog.my_schema.classify_sentiment"``.
|
|
``None`` for non-UC tools. Mutually exclusive with
|
|
:attr:`path` — UC tools have no server-side callable.
|
|
Set only when :attr:`runtime` is
|
|
:attr:`ToolRuntime.UC_FUNCTION`.
|
|
:param warehouse_id: Databricks SQL warehouse ID for UC
|
|
function execution, e.g. ``"abc123def456"``. Required
|
|
when :attr:`runtime` is :attr:`ToolRuntime.UC_FUNCTION`.
|
|
``None`` for non-UC tools.
|
|
"""
|
|
|
|
name: str
|
|
path: str | None
|
|
language: str
|
|
# Per-tool timeout/retry overrides. None = inherit from
|
|
# tools.timeout / tools.retry.
|
|
timeout: int | None = None
|
|
retry: RetryPolicy | None = None
|
|
# PEP 723 inline dependency metadata. Populated at load time
|
|
# by scanning the tool source file.
|
|
has_inline_deps: bool = False
|
|
inline_deps: list[str] | None = None
|
|
parameters: dict[str, Any] | None = None # type: ignore[explicit-any]
|
|
runtime: ToolRuntime = ToolRuntime.SERVER
|
|
catalog_path: str | None = None
|
|
warehouse_id: str | None = None
|
|
description: str | None = None
|
|
|
|
|
|
# ── Guardrails / Policies (POLICIES.md §3, §4) ──────────────
|
|
#
|
|
# Spec-level types for the policy system. These are pure data
|
|
# containers — no runtime behavior here. Runtime policy classes
|
|
# (FunctionPolicy, PromptPolicy) and the
|
|
# PolicyEngine live under omnigent.runtime.policies in later
|
|
# phases.
|
|
|
|
|
|
class Phase(str, Enum):
|
|
"""
|
|
The six points in the agent loop where policies fire.
|
|
|
|
``str`` mix-in keeps YAML parsing trivial
|
|
(``Phase("tool_call")``) and preserves the string form in
|
|
logs / JSON serialization.
|
|
|
|
Session-level phases (fire once per turn):
|
|
|
|
- ``REQUEST``: after a new user message arrives, before
|
|
the LLM turn.
|
|
- ``RESPONSE``: after the LLM's final assistant message,
|
|
before persistence.
|
|
|
|
Tool phases (fire per tool invocation):
|
|
|
|
- ``TOOL_CALL``: before dispatching a tool call emitted by
|
|
the LLM.
|
|
- ``TOOL_RESULT``: after a tool returns, before the result
|
|
is surfaced back to the LLM.
|
|
LLM phases (fire per LLM round-trip within a turn):
|
|
|
|
- ``LLM_REQUEST``: before each LLM call, with the full
|
|
prompt (system instructions + conversation history +
|
|
tool schemas). A single turn with tool calls fires
|
|
this multiple times — once per round-trip, not once
|
|
per turn. Does NOT fire on retries of the same call.
|
|
- ``LLM_RESPONSE``: after each LLM call returns, with
|
|
the raw model output before tool-call extraction or
|
|
post-processing. Mirrors ``LLM_REQUEST`` in firing
|
|
frequency (once per successful round-trip).
|
|
"""
|
|
|
|
REQUEST = "request"
|
|
TOOL_CALL = "tool_call"
|
|
TOOL_RESULT = "tool_result"
|
|
RESPONSE = "response"
|
|
LLM_REQUEST = "llm_request"
|
|
LLM_RESPONSE = "llm_response"
|
|
|
|
|
|
class PolicyAction(str, Enum):
|
|
"""
|
|
The three decisions a policy can emit.
|
|
|
|
- ``ALLOW``: the phase proceeds normally.
|
|
- ``ASK``: park for user approval; on approve → ALLOW, on
|
|
refuse/timeout → DENY.
|
|
- ``DENY``: short-circuit the phase; replace content with a
|
|
sentinel so downstream steps cannot act on it.
|
|
"""
|
|
|
|
ALLOW = "allow"
|
|
ASK = "ask"
|
|
DENY = "deny"
|
|
|
|
|
|
class StateUpdateAction(str, Enum):
|
|
"""
|
|
Operations a policy can request on the session state.
|
|
|
|
- ``SET``: overwrite (or create) a key with the given value.
|
|
- ``INCREMENT``: add a numeric delta to an existing numeric
|
|
value (defaults to ``0`` when the key is absent).
|
|
- ``DELETE``: remove a key from session state. ``value`` is
|
|
ignored.
|
|
- ``APPEND``: append ``value`` to a list stored at the key.
|
|
Creates a new single-element list when the key is absent.
|
|
"""
|
|
|
|
SET = "set"
|
|
INCREMENT = "increment"
|
|
DELETE = "delete"
|
|
APPEND = "append"
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class StateUpdate: # type: ignore[explicit-any] # value: Any field (see below)
|
|
"""
|
|
A single mutation to apply to the session state dict.
|
|
|
|
Returned by policy callables inside
|
|
:attr:`PolicyResult.state_updates` as a list. The engine
|
|
applies them in order after composing results from all
|
|
policies in a pass.
|
|
|
|
:param key: The session-state key to mutate,
|
|
e.g. ``"call_count"``.
|
|
:param action: The operation to perform,
|
|
e.g. ``StateUpdateAction.INCREMENT``.
|
|
:param value: The operand. Required for ``SET``,
|
|
``INCREMENT``, and ``APPEND``; ignored for ``DELETE``.
|
|
For ``INCREMENT`` this must be numeric (int or float).
|
|
"""
|
|
|
|
key: str
|
|
action: StateUpdateAction
|
|
value: Any = None # type: ignore[explicit-any]
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class PhaseSelector:
|
|
"""
|
|
One entry in a policy's ``on:`` list.
|
|
|
|
YAML shapes:
|
|
|
|
- ``"tool_call"`` →
|
|
``PhaseSelector(phase=Phase.TOOL_CALL, tool_name=None)``
|
|
(wildcard — matches every tool call).
|
|
- ``"tool_call:code_sandbox"`` →
|
|
``PhaseSelector(Phase.TOOL_CALL, "code_sandbox")``
|
|
(narrows to one tool by name).
|
|
|
|
Tool-name narrowing is only valid on ``TOOL_CALL`` and
|
|
``TOOL_RESULT`` phases — the parser rejects it on
|
|
``REQUEST``, ``RESPONSE``, ``LLM_REQUEST``, and
|
|
``LLM_RESPONSE``.
|
|
|
|
:param phase: Which enforcement point this selector fires
|
|
on.
|
|
:param tool_name: When set, only matches that tool. When
|
|
``None``, matches any tool in the phase (wildcard).
|
|
"""
|
|
|
|
phase: Phase
|
|
tool_name: str | None = None
|
|
|
|
def matches(self, ctx: EvaluationContext) -> bool:
|
|
"""
|
|
Test whether this selector matches an evaluation
|
|
context.
|
|
|
|
:param ctx: The current evaluation context
|
|
(phase + resolved tool name).
|
|
:returns: ``True`` if the selector's phase matches and
|
|
(when ``tool_name`` is set) the context's
|
|
``tool_name`` matches.
|
|
"""
|
|
if ctx.phase != self.phase:
|
|
return False
|
|
if self.tool_name is None:
|
|
return True
|
|
return ctx.tool_name == self.tool_name
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class LabelDef:
|
|
"""
|
|
Schema for one label key.
|
|
|
|
Declared statically in
|
|
``spec.guardrails.labels[key]``. Controls what values the
|
|
label can take and how it can change over the course of a
|
|
conversation (see POLICIES.md §10).
|
|
|
|
:param initial: Seed value written at conversation start.
|
|
``None`` means the label is unset until a policy
|
|
writes it for the first time, e.g. ``"0"``.
|
|
:param values: Ordered list of allowed values. ``None``
|
|
means schemaless — writes are unconstrained, e.g.
|
|
``["0", "1"]`` or
|
|
``["public", "internal", "confidential"]``.
|
|
"""
|
|
|
|
initial: str | None = None
|
|
values: list[str] | None = None
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class FunctionRef: # type: ignore[explicit-any] # arguments: dict[str, Any] field (see below)
|
|
"""
|
|
Reference to a policy callable, with optional factory
|
|
kwargs.
|
|
|
|
Two YAML shapes parse into this:
|
|
|
|
- Bare string: ``function: myorg.policies.simple_check`` →
|
|
``FunctionRef(path="myorg.policies.simple_check",
|
|
arguments=None)``. The resolved callable is the
|
|
evaluator itself.
|
|
- Dict: ``function: {path: myorg.policies.rate_limit,
|
|
arguments: {limit: 10}}`` →
|
|
``FunctionRef(path="...", arguments={"limit": 10})``.
|
|
The resolved callable is a factory called once at
|
|
workflow start; its return value is the evaluator.
|
|
|
|
:param path: Dotted import path to the callable or
|
|
factory, e.g.
|
|
``"myorg.policies.search_rate_limit"``.
|
|
:param arguments: Factory kwargs (present = factory form;
|
|
absent = direct callable form). ``None`` when the
|
|
YAML used the short string form.
|
|
"""
|
|
|
|
path: str
|
|
# Any: opaque factory kwargs passed to user-defined policy callable.
|
|
arguments: dict[str, Any] | None = None # type: ignore[explicit-any]
|
|
|
|
|
|
@dataclass
|
|
class PolicySpec:
|
|
"""
|
|
Base class for all policy specs.
|
|
|
|
Concrete subtypes (``FunctionPolicySpec``,
|
|
``PromptPolicySpec``) carry
|
|
type-specific fields. The class itself *is* the
|
|
discriminator — no separate ``type`` field at runtime.
|
|
|
|
``condition`` is a label-gate: if declared, the engine
|
|
checks current label values against it BEFORE dispatching
|
|
to the policy's ``evaluate()``. Non-matching policies are
|
|
skipped entirely (no action emitted, no LLM call, no
|
|
Python call) — cheap way to gate expensive policies on
|
|
session state (POLICIES.md §4, §10).
|
|
|
|
:param name: YAML key this policy was declared under,
|
|
e.g. ``"block_canada_input"``.
|
|
:param on: Phases this policy fires on, e.g.
|
|
``[PhaseSelector(Phase.TOOL_CALL, "web_search")]``.
|
|
``None`` for :class:`FunctionPolicySpec` — the callable
|
|
self-selects by returning ``None`` to abstain.
|
|
:param condition: Label-gate. Empty / absent =
|
|
always-match; values coerced to strings at spec load,
|
|
e.g. ``{"integrity": "0"}`` or
|
|
``{"role": ["admin", "ops"]}``.
|
|
:param ask_timeout: Per-policy approval timeout override
|
|
(seconds). ``None`` falls back to
|
|
``GuardrailsSpec.ask_timeout``. Useful when some ASKs
|
|
are cheap (yes/no) and some expensive (review a 50 KB
|
|
document).
|
|
"""
|
|
|
|
name: str
|
|
on: list[PhaseSelector] | None
|
|
condition: dict[str, str | list[str]] | None = None
|
|
ask_timeout: int | None = None
|
|
|
|
|
|
@dataclass
|
|
class FunctionPolicySpec(PolicySpec):
|
|
"""
|
|
A policy backed by a Python callable (see POLICIES.md §9.1).
|
|
|
|
:param function: Where the callable lives + optional
|
|
factory kwargs.
|
|
:param set_labels: Whitelist of label keys the callable
|
|
may write. Keys outside dropped silently. ``None``
|
|
means no writes declared (any key the callable emits
|
|
that has a ``LabelDef`` will still validate against
|
|
that LabelDef, but keys without a LabelDef are set
|
|
freely per omnigent parity).
|
|
:param config: Runtime configuration key-value pairs passed
|
|
to the callable as the second argument on every
|
|
invocation. Declared at policy attachment time (in the
|
|
YAML spec) and surfaced verbatim at evaluation time.
|
|
``None`` means no config declared; the callable receives
|
|
an empty dict.
|
|
"""
|
|
|
|
function: FunctionRef | None = None
|
|
set_labels: list[str] | None = None
|
|
config: dict[str, str] | None = None
|
|
|
|
|
|
@dataclass
|
|
class GuardrailsSpec:
|
|
"""
|
|
Top-level guardrails block from config.yaml.
|
|
|
|
Bundles label definitions, policies, and the spec-wide
|
|
ASK timeout default (POLICIES.md §3.2).
|
|
|
|
:param labels: Per-key ``LabelDef`` schemas. ``None``
|
|
means no labels declared — all label writes go
|
|
through the schemaless-set-freely path.
|
|
:param policies: Policies in YAML declaration order (the
|
|
engine iterates in this order).
|
|
:param ask_timeout: Spec-wide default approval timeout in
|
|
seconds. Individual policies may override via
|
|
``PolicySpec.ask_timeout``. Defaults to
|
|
:data:`DEFAULT_ASK_TIMEOUT` (1 day).
|
|
"""
|
|
|
|
labels: dict[str, LabelDef] | None = None
|
|
policies: list[PolicySpec] | None = None
|
|
ask_timeout: int = DEFAULT_ASK_TIMEOUT
|
|
|
|
|
|
@dataclass
|
|
class AgentSpec: # type: ignore[explicit-any] # params: dict[str, Any] field (see below)
|
|
"""
|
|
A fully parsed agent image.
|
|
|
|
Produced by the parser from a directory on disk; validated by
|
|
the validator.
|
|
|
|
:param spec_version: Schema version of the agent spec. Currently
|
|
must be ``1``.
|
|
:param name: Human-readable agent name, e.g. ``"code-reviewer"``.
|
|
:param description: Short summary of the agent's purpose.
|
|
:param llm: LLM configuration. ``None`` means the agent does not
|
|
declare an LLM preference.
|
|
:param interaction: Conversational mode and modality settings.
|
|
:param tools: Declared tool references (sub-agent names, etc.).
|
|
:param params: Arbitrary key-value parameters readable by skills
|
|
and tools. Values are heterogeneous (str, int, bool, list,
|
|
dict), so ``Any`` is the narrowest safe type. Example:
|
|
``{"max_retries": 3, "style": "concise"}``.
|
|
:param instructions: Agent system prompt, typically from
|
|
``AGENTS.md``. ``None`` if no instructions file is present.
|
|
:param skills: Parsed skills from ``skills/<name>/SKILL.md``.
|
|
:param mcp_servers: MCP server declarations from
|
|
``tools/mcp/<name>.yaml``.
|
|
:param local_tools: Discovered local tool files from
|
|
``tools/python/`` and ``tools/typescript/``.
|
|
:param sub_agents: Recursively parsed child agents from
|
|
``agents/<name>/``.
|
|
:param executor: Executor configuration (type, task timeout,
|
|
max iterations). ``executor.type`` is the
|
|
discriminator for the entire spec's validity.
|
|
:param compaction: Compaction configuration for context management.
|
|
``None`` means use defaults (trigger at 80%, protect last 5
|
|
iterations).
|
|
:param guardrails: Guardrails configuration (labels + policies
|
|
+ ASK timeout). ``None`` means the agent declared no
|
|
``guardrails:`` block — runtime builds a no-op engine
|
|
with zero policies and an empty label cache. See
|
|
POLICIES.md §3, §4.
|
|
:param async_enabled: Whether the LLM-callable async-dispatch
|
|
builtins (``sys_call_async``, ``sys_read_inbox``,
|
|
``sys_cancel_async``) are registered. YAML key is
|
|
``async:``; the dataclass field avoids the Python
|
|
keyword. **Defaults to ``True``** to match the legacy
|
|
inner-stack default at
|
|
``omnigent/inner/datamodel.py::AgentDef.async_enabled``
|
|
— the same YAML must produce the same tool surface
|
|
whether the user opts into Omnigent mode or runs the legacy
|
|
path. Agents that want to suppress the async surface
|
|
declare ``async: false`` explicitly. See
|
|
``designs/SERVER_HARNESS_CONTRACT.md`` §Async work +
|
|
inbox + the step-11 sub-step entries.
|
|
:param os_env: The agent's OS environment, e.g.
|
|
``OSEnvSpec(type="caller_process", cwd=".",
|
|
sandbox=OSEnvSandboxSpec(type="linux_bwrap",
|
|
write_paths=["."], allow_network=False))``. The default
|
|
sandbox on Linux is ``linux_bwrap`` (mount-namespace +
|
|
seccomp hardening; see
|
|
:mod:`omnigent.inner.bwrap_sandbox`), selected when the
|
|
``bwrap`` binary is on ``PATH``. ``None`` means the agent declares no
|
|
``os_env:`` block — the runtime skips registering
|
|
``sys_os_*`` tools and the ``claude-sdk`` harness wrap
|
|
falls back to its enable-natives-by-default rule.
|
|
Native Omnigent YAML accepts this as a top-level ``os_env:``
|
|
mapping; the omnigent-compat translator copies
|
|
``AgentDef.os_env`` into this field directly. The
|
|
``"inherit"`` string sentinel from omnigent inline
|
|
AgentTool sub-specs is resolved against the parent at
|
|
translation time and is never carried as a string on
|
|
``AgentSpec``.
|
|
:param terminals: Declared interactive tmux terminals
|
|
the agent can launch via ``sys_terminal_launch``.
|
|
Map of ``terminal_name`` → :class:`TerminalEnvSpec`
|
|
(the inner-datamodel dataclass: ``command``, ``args``,
|
|
``env``, per-terminal ``os_env``, ``scrollback``, etc.).
|
|
``None`` means the agent declares no ``terminals:``
|
|
block; ``sys_terminal_*`` tools are not registered.
|
|
Populated by the omnigent-compat translator from
|
|
``AgentDef.terminals``. Native Omnigent YAML support is
|
|
deferred — see ``designs/OMNIGENT_TERMINAL_BRIDGE.md`` §3.
|
|
:param timers: Whether the LLM-callable timer builtins
|
|
(``sys_timer_set``, ``sys_timer_cancel``) are
|
|
registered. YAML key is ``timers:``. **Defaults to
|
|
``False``** to match the legacy inner-stack default at
|
|
``omnigent/inner/datamodel.py::AgentDef.timers`` —
|
|
agents opt into the timer surface explicitly. Step 10
|
|
of the harness contract migration adds the AP-side
|
|
port; firings durable across server restarts via the
|
|
the legacy background-timer workflow (the inner
|
|
stack uses in-memory asyncio tasks; Omnigent supersedes that
|
|
with a workflow per timer pinned to the timer_id). See
|
|
``designs/SERVER_HARNESS_CONTRACT.md`` §Timers and
|
|
step 10.
|
|
:param spawn: Whether the agent may spawn child sessions
|
|
OUTSIDE any declared sub-agent list: registers
|
|
``sys_session_create`` (launch an existing agent by id or
|
|
a custom locally-authored bundle via ``config_path``),
|
|
along with ``sys_session_send`` / ``sys_session_close``
|
|
to drive and tombstone those children. YAML key is
|
|
``spawn:`` (top-level boolean, like ``timers:``).
|
|
**Defaults to ``False``.** This is a distinct grant from
|
|
``tools.agents``, which permits spawning ONLY the
|
|
specified sub-agent types (named ``sys_session_send`` +
|
|
``sys_session_close``, no ``sys_session_create``). The
|
|
session *read* tools (``sys_session_list`` /
|
|
``sys_session_get_history`` / ``sys_session_get_info``)
|
|
are always registered and are not affected by either
|
|
opt-in.
|
|
:param agent_session_sharing: Authority for the agent to share the
|
|
session it is running in, via ``sys_session_share``. YAML key is
|
|
``agent_session_sharing:`` (top-level, like ``spawn:``). This
|
|
flag is the SOLE enabler of that tool — it is independent of
|
|
``spawn`` / ``tools.agents``, and has no bearing on sharing the
|
|
session through the server API or CLI. One of
|
|
:class:`SharePolicy`: ``none`` (default — tool not registered),
|
|
``non-public`` (grant named users only), or ``public`` (also
|
|
allow ``__public__`` anonymous read). **Defaults to
|
|
``SharePolicy.NONE``.**
|
|
"""
|
|
|
|
spec_version: int
|
|
name: str | None = None
|
|
description: str | None = None
|
|
llm: LLMConfig | None = None
|
|
interaction: InteractionConfig = field(default_factory=InteractionConfig)
|
|
tools: ToolsConfig = field(default_factory=ToolsConfig)
|
|
# Arbitrary key-value params readable by skills and tools.
|
|
# Values are heterogeneous (str, int, bool, list, dict), so Any
|
|
# is the narrowest safe type here.
|
|
params: dict[str, Any] = field(default_factory=dict) # type: ignore[explicit-any]
|
|
instructions: str | None = None # contents of AGENTS.md
|
|
skills: list[SkillSpec] = field(default_factory=list)
|
|
# Filter for host-scope skill loading (skills the harness picks up
|
|
# from the user's machine — ``~/.claude/skills/`` and any
|
|
# ``.claude/skills/`` along the cwd ancestry — separate from
|
|
# bundled skills declared above). Maps from the top-level YAML
|
|
# ``skills:`` key. Three forms:
|
|
#
|
|
# - ``"all"`` (default, ``None`` is normalized to ``"all"`` at
|
|
# parse time): every host-scope skill is exposed to the model.
|
|
# - ``"none"``: empty filter, no host-scope skills are exposed
|
|
# (the agent only sees its own bundled skills if any).
|
|
# - ``list[str]``: only the named skills are exposed.
|
|
#
|
|
# The Claude SDK harness consumes this directly as its ``skills``
|
|
# option (``"all"`` ↔ ``"all"``, ``"none"`` ↔ ``[]``,
|
|
# list-of-names passes through). Other harnesses ignore the
|
|
# field. Bundled skills (the ``skills`` field above) are loaded
|
|
# via a separate plugin-dir mechanism and aren't subject to this
|
|
# filter — agents that want to suppress bundled skills do so by
|
|
# not shipping them, not by setting this filter to ``"none"``.
|
|
skills_filter: str | list[str] = "all"
|
|
mcp_servers: list[MCPServerConfig] = field(default_factory=list)
|
|
local_tools: list[LocalToolInfo] = field(default_factory=list)
|
|
sub_agents: list[AgentSpec] = field(default_factory=list)
|
|
executor: ExecutorSpec = field(default_factory=ExecutorSpec)
|
|
compaction: CompactionConfig | None = None
|
|
guardrails: GuardrailsSpec | None = None
|
|
async_enabled: bool = True
|
|
os_env: OSEnvSpec | None = None
|
|
terminals: dict[str, TerminalEnvSpec] | None = None
|
|
timers: bool = False
|
|
spawn: bool = False
|
|
agent_session_sharing: SharePolicy = SharePolicy.NONE
|