dreadnode 2.0.30__py3-none-any.whl → 2.0.32__py3-none-any.whl

dreadnode/agents/agent.py

@@ -20,6 +20,7 @@ from pydantic import (
 )
 
 import dreadnode
+from dreadnode.agents.engines import AgentEngine, EngineContext, PermissionBridge, resolve_engine
 from dreadnode.agents.events import (
     AgentEnd,
     AgentError,
@@ -185,10 +186,22 @@ class Agent(Executor[AgentEvent, Trajectory]):
     """Base factor for exponential backoff: wait = base_factor * 2 ** (attempt - 1)."""
     backoff_jitter: bool = Config(default=True)
     """Whether to add up to ``backoff_base_factor`` seconds of random jitter to each wait."""
+    engine: str | AgentEngine | None = Config(default=None, expose_as=str | None)
+    """Owner of the agent loop. ``None``/``"native"`` runs the in-process loop; a
+    built-in name (e.g. ``"claude-code"``) or a ``mod:attr`` reference delegates the
+    loop to a foreign harness while sessions/eval/optimization/policy keep working."""
 
     # Private state
     _generator: Generator | None = PrivateAttr(None, init=False)
     _current_input: str = PrivateAttr("", init=False)
+    _capability: tuple[str, str] | None = PrivateAttr(None, init=False)
+    """The (name, version) capability this agent runs under, if any. Bound to
+    ``current_capability`` for the duration of a run (and reset afterward) so
+    runtime tools attribute emitted items to the right producer without leaking
+    attribution into later agents that share the async context."""
+    _permission_bridge: PermissionBridge | None = PrivateAttr(None, init=False)
+    """Tool-approval bridge injected by the runtime so foreign engines wire their
+    permission callback into the native HITL path. ``None`` for bare-SDK use."""
 
     # Discoverability namespace for the AgentJudge specialized construction.
     # Assigned at module-load time by ``dreadnode.agents.__init__._lazy_init``
@@ -660,6 +673,7 @@ class Agent(Executor[AgentEvent, Trajectory]):
                 # out of the result body.
                 tool_error = message.metadata.get("error")
                 tool_error_type = message.metadata.get("error_type")
+                tool_cost_usd = message.metadata.get("subagent_cost_usd")
 
                 end_event = ToolEnd(
                     agent_id=self.agent_id,
@@ -670,6 +684,7 @@ class Agent(Executor[AgentEvent, Trajectory]):
                     stop=stop,
                     error=tool_error,
                     error_type=tool_error_type,
+                    cost_usd=tool_cost_usd,
                 )
                 async for event in self._dispatch(end_event):
                     yield event
@@ -715,6 +730,32 @@ class Agent(Executor[AgentEvent, Trajectory]):
 
     async def _stream(
         self, trajectory: Trajectory | None = None
+    ) -> t.AsyncGenerator[AgentEvent, None]:
+        """Drive the loop through the resolved :class:`AgentEngine`.
+
+        For the native engine this delegates straight to ``_native_run_loop``
+        (which dispatches its own hooks inline). Foreign engines yield translated
+        native events and call ``ctx.dispatch`` themselves for observational hooks.
+        This shim is the ``Executor._stream`` implementation; the surrounding span,
+        trajectory accumulation, and tool-context management stay in ``stream``.
+        """
+        engine = self._resolve_engine()
+        ctx = EngineContext(
+            agent=self,
+            trajectory=trajectory if trajectory is not None else self.trajectory,
+            goal=self._current_input,
+            dispatch=self._dispatch,
+            permission=self._permission_bridge,
+        )
+        async for event in engine.run_loop(ctx):
+            yield event
+
+    def _resolve_engine(self) -> AgentEngine:
+        """Resolve this agent's ``engine`` selector to a concrete engine instance."""
+        return resolve_engine(self.engine)
+
+    async def _native_run_loop(
+        self, trajectory: Trajectory | None = None
     ) -> t.AsyncGenerator[AgentEvent, None]:
         """
         Core agent execution loop with inline tracing.
@@ -1168,6 +1209,13 @@ class Agent(Executor[AgentEvent, Trajectory]):
             active_trajectory = self.trajectory
 
         async with AsyncExitStack() as stack:
+            # Scope capability attribution to THIS run (reset on exit) so it never
+            # leaks into a later agent sharing the async context.
+            if self._capability is not None:
+                from dreadnode.tracing.span import bind_capability
+
+                stack.enter_context(bind_capability(self._capability))
+
             # Enter tool contexts
             for tool_container in self.tools:
                 if hasattr(tool_container, "__aenter__") and hasattr(tool_container, "__aexit__"):

dreadnode/agents/engines/AGENTS.md

@@ -0,0 +1,27 @@
+# AGENTS.md — agent engines
+
+An **engine** owns the agent loop. The native engine is the default; foreign
+engines (e.g. `claude-code`) delegate the loop to an external harness while the
+agent stays a first-class `Agent`. Canonical contract: `specs/capabilities/engines.md`
+(`CAP-ENG-*`, `CAP-ERES-*`, `CAP-EGOV-*`, `CAP-EBIND-*`).
+
+## Files
+
+- `base.py` — `AgentEngine` ABC, `EngineContext`, `EnforcementSurface`, `PolicyFacet`, `PermissionBridge`.
+- `native.py` — `NativeEngine`, a thin delegate to `Agent._native_run_loop` (the historical loop body). Keep native byte-for-byte: the loop logic stays on `Agent`.
+- `__init__.py` — registry (`register_engine`) + `resolve_engine` (built-in name / class / instance / `module.path:ClassName`).
+
+## Authoring a built-in engine
+
+1. Subclass `AgentEngine`, set a stable `name`, implement `async def run_loop(self, ctx)` yielding native `AgentEvent`s and exactly one terminal `AgentEnd`.
+2. Call `register_engine(YourEngine)` in `__init__.py`.
+3. Translate the harness's activity into native events; do **not** invent a new event schema.
+4. If you do not dispatch inline, call `ctx.dispatch(event)` on every translated event so observational hooks run (leave `dispatches_internally = False`).
+5. Override `describe_enforcement(policy)` with an **honest** `EnforcementSurface` — do not claim `enforces` for a facet you only observe. Override `honored_config()` with the explicit set of `Agent` fields you respect, and `consumed_components()` with the capability component kinds you actually use (Decision A: a harness with its own tools consumes none of ours — don't claim `python_tools` you don't inject; see `CAP-ENG-020..025`).
+
+## MUST / NEVER
+
+- **MUST** keep the `native` path unchanged — the existing agent-loop test suite is the regression gate.
+- **MUST** spawn third-party / subprocess engines inside the runtime sandbox, never in-process in the runtime (`CAP-EBIND-002`).
+- **NEVER** let an engine silently downgrade governance: an un-enforceable required policy facet must surface as a refusal/warning via reconciliation, not be ignored.
+- **NEVER** import `Agent` at module load (cycle): use `if TYPE_CHECKING` and reach the agent through `ctx.agent`.

dreadnode/agents/engines/__init__.py

@@ -0,0 +1,89 @@
+"""Agent engines — pluggable, overridable owners of the agent loop.
+
+Built-ins are resolved by name (``native``, ``claude-code``); customer engines
+are resolved from a ``mod:attr`` reference (mirroring ``WorkerDef`` import refs).
+Resolution precedence for the ``engine`` selector itself lives in
+``create_agent`` and mirrors how ``model`` resolves.
+"""
+
+import importlib
+
+from dreadnode.agents.engines.base import (
+    AgentEngine,
+    CapabilityComponent,
+    EnforcementSurface,
+    EngineContext,
+    PermissionBridge,
+    PolicyFacet,
+)
+from dreadnode.agents.engines.claude_code import ClaudeCodeEngine, ClaudeCodeTranslationState
+from dreadnode.agents.engines.native import NativeEngine
+
+__all__ = [
+    "AgentEngine",
+    "CapabilityComponent",
+    "ClaudeCodeEngine",
+    "ClaudeCodeTranslationState",
+    "EnforcementSurface",
+    "EngineContext",
+    "NativeEngine",
+    "PermissionBridge",
+    "PolicyFacet",
+    "register_engine",
+    "resolve_engine",
+]
+
+_REGISTRY: dict[str, type[AgentEngine]] = {}
+
+
+def register_engine(cls: type[AgentEngine]) -> type[AgentEngine]:
+    """Register a built-in engine class under its ``name`` (usable as a decorator)."""
+    name = getattr(cls, "name", None)
+    if not name:
+        raise ValueError(f"Engine {cls!r} must define a non-empty 'name'.")
+    _REGISTRY[name] = cls
+    return cls
+
+
+register_engine(NativeEngine)
+register_engine(ClaudeCodeEngine)
+
+
+def _load_engine_from_ref(ref: str) -> type[AgentEngine]:
+    """Import an engine class from a ``module.path:Attr`` or ``module.path.Attr`` ref."""
+    module_path, _, attr = ref.partition(":")
+    if not attr:
+        module_path, _, attr = ref.rpartition(".")
+    if not module_path or not attr:
+        raise ValueError(f"Invalid engine reference {ref!r}; expected 'module.path:ClassName'.")
+    try:
+        module = importlib.import_module(module_path)
+    except ImportError as exc:
+        raise ValueError(f"Could not import engine module '{module_path}' from {ref!r}.") from exc
+    obj = getattr(module, attr, None)
+    if obj is None or not (isinstance(obj, type) and issubclass(obj, AgentEngine)):
+        raise ValueError(f"Engine reference {ref!r} did not resolve to an AgentEngine subclass.")
+    return obj
+
+
+def resolve_engine(spec: "str | AgentEngine | type[AgentEngine] | None") -> AgentEngine:
+    """Resolve an ``engine`` selector to a concrete :class:`AgentEngine` instance.
+
+    Accepts ``None`` (→ native), an instance, a class, a built-in name, or a
+    ``mod:attr`` reference. A fresh instance is returned for class/name/ref specs
+    so stateful engines (subprocess-backed) don't leak state across turns.
+    """
+    if spec is None:
+        return NativeEngine()
+    if isinstance(spec, AgentEngine):
+        return spec
+    if isinstance(spec, type) and issubclass(spec, AgentEngine):
+        return spec()
+    if isinstance(spec, str):
+        if spec in _REGISTRY:
+            return _REGISTRY[spec]()
+        if ":" in spec or "." in spec:
+            return _load_engine_from_ref(spec)()
+        known = ", ".join(sorted(_REGISTRY)) or "(none)"
+        raise ValueError(f"Unknown engine '{spec}'. Known built-ins: {known}.")
+    raise TypeError(f"Unsupported engine selector: {spec!r}")

dreadnode/agents/engines/base.py

@@ -0,0 +1,166 @@
+"""Engine contract for the agent loop.
+
+An :class:`AgentEngine` owns the *interior* of an agent — the loop that turns a
+goal into generation/tool events. The native engine is the default; foreign
+engines (e.g. ``claude-code``) delegate the loop to an external harness while the
+rest of the stack (sessions, eval, optimization, policy, telemetry, TUI) keeps
+working because the foreign agent is still an :class:`~dreadnode.agents.agent.Agent`.
+
+See ``specs/capabilities/engines.md`` (ENG-*) for the canonical contract.
+"""
+
+import typing as t
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+if t.TYPE_CHECKING:
+    from dreadnode.agents.agent import Agent
+    from dreadnode.agents.events import AgentEvent
+    from dreadnode.agents.trajectory import Trajectory
+
+
+class PolicyFacet(StrEnum):
+    """A single governable dimension of a session policy.
+
+    An engine declares, per facet, whether it *enforces* it, *bridges* it via a
+    harness callback, can only *observe* it, or has *no equivalent* mechanism.
+    The runtime reconciles the session policy against that declaration (ENG-REC-*).
+    """
+
+    AUTONOMY = "autonomy"
+    """Block-vs-auto-allow (native ``is_autonomous`` / harness ``permission_mode``)."""
+    TOOL_APPROVAL = "tool_approval"
+    """Human-in-the-loop tool approval (``ask_user`` → ``prompt.required``)."""
+    STEP_BUDGET = "step_budget"
+    """Step/turn ceiling (``max_steps`` / harness ``max_turns``)."""
+    TOKEN_BUDGET = "token_budget"  # noqa: S105  (facet name, not a secret)
+    """Token ceiling (no harness equivalent — enforced by killing the run)."""
+    COST_BUDGET = "cost_budget"
+    """Cost ceiling (no harness equivalent — enforced by killing the run)."""
+    TIME_BUDGET = "time_budget"
+    """Wall-clock ceiling (no harness equivalent — enforced by killing the run)."""
+    GUARD_STEERING = "guard_steering"
+    """Mid-loop prevention/steering via hook ``Reaction`` (in-loop only)."""
+    SCORERS = "scorers"
+    """Observational scorers/detectors/metrics (attach to events after the fact)."""
+
+
+class CapabilityComponent(StrEnum):
+    """A kind of capability-declared resource an engine may or may not consume.
+
+    The native engine consumes all kinds (it executes our tools in-loop and
+    surfaces our skills). A foreign engine that brings its own tools declares a
+    subset; the runtime informs the author which declared components are inert
+    under that engine (CAP-ENG-022). See ``specs/capabilities/engines.md``.
+    """
+
+    PYTHON_TOOLS = "python_tools"
+    """Capability ``@tool`` / MCP tools from our registry, executed in-loop."""
+    MCP_SERVERS = "mcp_servers"
+    """MCP servers the capability declares (folded with python_tools today)."""
+    SKILLS = "skills"
+    """``SKILL.md`` directories (the shared Agent Skills standard)."""
+
+
+@dataclass(frozen=True)
+class EnforcementSurface:
+    """What an engine can actually do about each policy facet.
+
+    A facet absent from all four sets is treated as ``observes_only`` by the
+    reconciler (the conservative default).
+    """
+
+    enforces: frozenset[PolicyFacet] = field(default_factory=frozenset)
+    """Enforced natively or by translatable config (e.g. ``permission_mode``)."""
+    bridges: frozenset[PolicyFacet] = field(default_factory=frozenset)
+    """Enforced by wiring a harness callback back into our control plane."""
+    observes_only: frozenset[PolicyFacet] = field(default_factory=frozenset)
+    """Visible after the harness acted — can record, cannot prevent."""
+    no_equivalent: frozenset[PolicyFacet] = field(default_factory=frozenset)
+    """No mechanism in the harness — enforceable only by killing the run."""
+
+    @classmethod
+    def all_enforced(cls) -> "EnforcementSurface":
+        """The native engine's surface: it owns the loop, so it enforces everything."""
+        return cls(enforces=frozenset(PolicyFacet))
+
+
+@t.runtime_checkable
+class PermissionBridge(t.Protocol):
+    """Bridges a harness tool-approval callback into the native HITL path.
+
+    Implemented by the runtime over ``_human_prompt_handler`` so a foreign
+    engine's ``can_use_tool`` reuses the existing ``prompt.required`` /
+    ``prompt.respond`` protocol (TUI widget, eval-worker auto-deny). Wired in M1.
+    """
+
+    async def request_tool_approval(
+        self, *, tool_name: str, tool_input: dict[str, t.Any]
+    ) -> bool: ...
+
+
+@dataclass
+class EngineContext:
+    """Everything an engine needs to run one turn.
+
+    The native engine uses only ``agent`` + ``trajectory`` (it reaches the rest
+    through ``agent``). Foreign engines additionally use ``goal``, ``dispatch``
+    (to run observational hooks on translated events), and ``permission``.
+    """
+
+    agent: "Agent"
+    trajectory: "Trajectory"
+    goal: str
+    dispatch: "t.Callable[[AgentEvent], t.AsyncIterator[AgentEvent]]"
+    """Run an event through the agent's hooks (metrics + reactions). Foreign
+    engines call this per translated event; the native engine dispatches inline."""
+    permission: "PermissionBridge | None" = None
+
+
+class AgentEngine(ABC):
+    """Pluggable owner of the agent loop.
+
+    Implementations live in this package (built-ins) or are supplied by a
+    customer via a ``mod:attr`` reference. Built-ins register via
+    :func:`~dreadnode.agents.engines.register_engine`.
+    """
+
+    name: t.ClassVar[str]
+    """Stable identifier used in ``engine:`` declarations and the registry."""
+
+    dispatches_internally: t.ClassVar[bool] = False
+    """True when ``run_loop`` already routes its events through ``ctx.dispatch``
+    (the native engine does, inline). Foreign engines leave this False and call
+    ``ctx.dispatch`` themselves on translated events."""
+
+    @abstractmethod
+    def run_loop(self, ctx: EngineContext) -> "t.AsyncIterator[AgentEvent]":
+        """Drive one turn, yielding native ``AgentEvent``s as it progresses."""
+        ...
+
+    def describe_enforcement(self, policy: t.Any) -> EnforcementSurface:  # noqa: ARG002
+        """Declare which policy facets this engine can enforce for ``policy``.
+
+        Defaults to fully-enforced (correct for any engine that owns a native
+        loop). Foreign engines override with an honest, partial surface.
+        """
+        return EnforcementSurface.all_enforced()
+
+    def honored_config(self) -> set[str] | None:
+        """Which ``Agent`` config fields this engine respects.
+
+        ``None`` means "all" (the native engine). A foreign engine returns the
+        explicit set it honors so the runtime can warn about ignored config.
+        """
+        return None
+
+    def consumed_components(self) -> set[CapabilityComponent]:
+        """Which capability component kinds this engine consumes.
+
+        Defaults to all (the native engine executes our tools in-loop and
+        surfaces our skills). A foreign engine that uses its own tools returns a
+        subset; the runtime informs the author about the unconsumed components
+        a capability declares (CAP-ENG-022).
+        """
+        return set(CapabilityComponent)