computer-agent-py 0.1.3__tar.gz → 0.2.0__tar.gz

{computer_agent_py-0.1.3 → computer_agent_py-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: computer-agent-py
-Version: 0.1.3
+Version: 0.2.0
 Summary: Drop-in replacement for claude-agent-sdk that adds a proxied telemetry pipeline (PII redaction + guardrails) with OpenTelemetry and AgentOS sinks.
 Keywords: computeragent,claude-agent-sdk,claude,agent,telemetry,otel,opentelemetry,agentos,pii
 Author: Abhi Bhat
@@ -26,7 +26,14 @@ Requires-Dist: opentelemetry-exporter-otlp>=1.27 ; extra == 'all'
 Requires-Dist: opentelemetry-semantic-conventions>=0.48b0 ; extra == 'all'
 Requires-Dist: motor>=3.5 ; extra == 'all'
 Requires-Dist: cedarpy>=4,<5 ; extra == 'all'
+Requires-Dist: openai>=1,<2 ; extra == 'all'
+Requires-Dist: anthropic>=0.40,<1 ; extra == 'all'
+Requires-Dist: pyyaml>=6,<7 ; extra == 'all'
 Requires-Dist: cedarpy>=4,<5 ; extra == 'cedar'
+Requires-Dist: pyyaml>=6,<7 ; extra == 'gap'
+Requires-Dist: openai>=1,<2 ; extra == 'gitagent'
+Requires-Dist: anthropic>=0.40,<1 ; extra == 'gitagent'
+Requires-Dist: pyyaml>=6,<7 ; extra == 'gitagent'
 Requires-Dist: opentelemetry-api>=1.27 ; extra == 'otel'
 Requires-Dist: opentelemetry-sdk>=1.27 ; extra == 'otel'
 Requires-Dist: opentelemetry-exporter-otlp>=1.27 ; extra == 'otel'
@@ -38,6 +45,8 @@ Project-URL: Issues, https://github.com/open-gitagent/computer-agent-py/issues
 Provides-Extra: agentos
 Provides-Extra: all
 Provides-Extra: cedar
+Provides-Extra: gap
+Provides-Extra: gitagent
 Provides-Extra: otel
 Description-Content-Type: text/markdown
 
@@ -49,6 +58,8 @@ Description-Content-Type: text/markdown
 
 **Drop-in replacement for [`claude-agent-sdk`](https://pypi.org/project/claude-agent-sdk/)** — change the import line, get a proxied telemetry pipeline with PII redaction, configurable OTel export, policy-based tool authorization, and full AgentOS integration for free.
 
+**New in 0.2.0** — a Python port of the TypeScript [`ComputerAgent`](../ComputerAgent/) harness alongside the drop-in proxy. Same vocabulary (engine / substrate / session-store / identity-loader), `ComputerAgent` + `run_task()` entry points, two built-in engines (`claude-agent-sdk`, `gitagent`). The 0.1.x drop-in surface is untouched — both modes co-exist.
+
 ```diff
 - from claude_agent_sdk import ClaudeAgentOptions, query
 - from claude_agent_sdk.types import ResultMessage
@@ -78,11 +89,57 @@ pip install computer-agent-py                     # core drop-in + OPA policy en
 pip install 'computer-agent-py[otel]'             # + OpenTelemetry sink
 pip install 'computer-agent-py[agentos]'          # + AgentOS Mongo sinks
 pip install 'computer-agent-py[cedar]'            # + Cedar policy engine (in-process)
+pip install 'computer-agent-py[gitagent]'         # + gitagent engine (Anthropic + OpenAI dispatch) + GAP loader
+pip install 'computer-agent-py[gap]'              # + GAP identity loader only (pyyaml; subset of [gitagent])
 pip install 'computer-agent-py[all]'              # everything
 ```
 
 **Prerequisite** — same as upstream: the `claude` CLI binary on `PATH` and Anthropic / Bedrock credentials in the environment.
 
+## Two modes
+
+`computer-agent-py` ships two co-existing surfaces. Use whichever fits the call site — they share the same telemetry pipeline and policy authorizer.
+
+### Mode 1 — drop-in proxy (0.1.x, unchanged)
+
+The default for callers who want minimum-friction observability over `claude-agent-sdk`. Swap the import line and every `query(...)` / `ClaudeSDKClient(...)` call flows through PII redaction → guardrails → OTel + AgentOS sinks.
+
+```python
+from computeragent import ClaudeAgentOptions, query
+
+async for msg in query(prompt="...", options=ClaudeAgentOptions(...)):
+    ...
+```
+
+### Mode 2 — harness (new in 0.2.0)
+
+A Python port of the TypeScript [`ComputerAgent`](../ComputerAgent/) stack. Four orthogonal swappable axes — engine / substrate / session-store / identity-loader — plus a `ComputerAgent` class and a `run_task()` convenience.
+
+```python
+from pathlib import Path
+from computeragent import ComputerAgent
+
+async with ComputerAgent(
+    source=Path.cwd(),
+    engine="claude-agent-sdk",   # or "gitagent" for OpenAI-compatible endpoints
+    runtime="local",
+    options={"system_prompt": "You are terse.", "allowed_tools": ["Read", "Glob"]},
+) as agent:
+    result = await agent.chat("List the files in this directory.")
+    print(result.messages, result.usage)
+```
+
+Built-ins shipped in 0.2.0:
+
+| Axis | Built-ins | Notes |
+|---|---|---|
+| `engine` | `claude-agent-sdk`, `gitagent` | gitagent reads `GITCLAW_MODEL_BASE_URL` + `OPENAI_API_KEY`. MCP-only tools in 0.2.0. |
+| `runtime` (substrate) | `local` | Caller-owned `Path`, or git-clone an `https://` / `git@` `.git` URL into a temp dir. |
+| `session_store` | `memory` | In-process dict. Mongo + SQLite stores in 0.3.0. |
+| `identity_loader` | `passthrough` | Treats inline dicts as manifests. GAP-style loaders in 0.3.0. |
+
+Plug-ins register at import time via `register_engine(name, instance)` etc. — third-party engines (e2b substrate, deepagents engine, mongo session store) drop in by implementing the matching Protocol in `computeragent.protocol_types`.
+
 ## Quickstart
 
 ```python
@@ -221,7 +278,12 @@ The doc shapes are byte-for-byte compatible with the TypeScript `@open-gitagent/
 
 ### Live chat for library-mode agents
 
-When the AgentRegistrySink writes its `agent_registry.source` row, it includes a full inline `IdentitySource` with `files: {agent.yaml, CLAUDE.md}` derived from your `ClaudeAgentOptions`. If a user clicks "New Chat" on the agent in the AgentOS SPA, the harness can clone those files into a sandbox workdir and spawn a live conversation — same UX as hosted (git-sourced) agents. The historical transcript stays available in the Chat tab regardless.
+Two registry shapes for `agent_registry.source`, depending on which mode emitted the event:
+
+- **Drop-in proxy (`computeragent.query(...)` / `ClaudeSDKClient`)** writes a `type: "inline"` source with `files: {agent.yaml, CLAUDE.md}` derived from your `ClaudeAgentOptions`. If a user clicks "New Chat" on the agent in the AgentOS SPA, the harness can clone those files into a sandbox workdir and spawn a live conversation — same UX as hosted (git-sourced) agents.
+- **Harness (`ComputerAgent`, new in 0.2.0)** writes a `type: "library"` source. There's no remote `harness-server` to proxy a chat-sandbox spawn to (the agent runs in your Python process), so this shape deliberately fails AgentOS's `hasResolvableSource()` check. The AgentOS UI hides the chat-sandbox button (via the matching `liveChatCapable` derived field on `GET /agents`); historical transcripts remain visible in the Chat tab.
+
+Either way, every event still flows through OTel and AgentOS Mongo so the Agents list, Logs tab, and Chat transcript stay populated.
 
 ### DocumentDB compatibility
 

{computer_agent_py-0.1.3 → computer_agent_py-0.2.0}/README.md

@@ -6,6 +6,8 @@
 
 **Drop-in replacement for [`claude-agent-sdk`](https://pypi.org/project/claude-agent-sdk/)** — change the import line, get a proxied telemetry pipeline with PII redaction, configurable OTel export, policy-based tool authorization, and full AgentOS integration for free.
 
+**New in 0.2.0** — a Python port of the TypeScript [`ComputerAgent`](../ComputerAgent/) harness alongside the drop-in proxy. Same vocabulary (engine / substrate / session-store / identity-loader), `ComputerAgent` + `run_task()` entry points, two built-in engines (`claude-agent-sdk`, `gitagent`). The 0.1.x drop-in surface is untouched — both modes co-exist.
+
 ```diff
 - from claude_agent_sdk import ClaudeAgentOptions, query
 - from claude_agent_sdk.types import ResultMessage
@@ -35,11 +37,57 @@ pip install computer-agent-py                     # core drop-in + OPA policy en
 pip install 'computer-agent-py[otel]'             # + OpenTelemetry sink
 pip install 'computer-agent-py[agentos]'          # + AgentOS Mongo sinks
 pip install 'computer-agent-py[cedar]'            # + Cedar policy engine (in-process)
+pip install 'computer-agent-py[gitagent]'         # + gitagent engine (Anthropic + OpenAI dispatch) + GAP loader
+pip install 'computer-agent-py[gap]'              # + GAP identity loader only (pyyaml; subset of [gitagent])
 pip install 'computer-agent-py[all]'              # everything
 ```
 
 **Prerequisite** — same as upstream: the `claude` CLI binary on `PATH` and Anthropic / Bedrock credentials in the environment.
 
+## Two modes
+
+`computer-agent-py` ships two co-existing surfaces. Use whichever fits the call site — they share the same telemetry pipeline and policy authorizer.
+
+### Mode 1 — drop-in proxy (0.1.x, unchanged)
+
+The default for callers who want minimum-friction observability over `claude-agent-sdk`. Swap the import line and every `query(...)` / `ClaudeSDKClient(...)` call flows through PII redaction → guardrails → OTel + AgentOS sinks.
+
+```python
+from computeragent import ClaudeAgentOptions, query
+
+async for msg in query(prompt="...", options=ClaudeAgentOptions(...)):
+    ...
+```
+
+### Mode 2 — harness (new in 0.2.0)
+
+A Python port of the TypeScript [`ComputerAgent`](../ComputerAgent/) stack. Four orthogonal swappable axes — engine / substrate / session-store / identity-loader — plus a `ComputerAgent` class and a `run_task()` convenience.
+
+```python
+from pathlib import Path
+from computeragent import ComputerAgent
+
+async with ComputerAgent(
+    source=Path.cwd(),
+    engine="claude-agent-sdk",   # or "gitagent" for OpenAI-compatible endpoints
+    runtime="local",
+    options={"system_prompt": "You are terse.", "allowed_tools": ["Read", "Glob"]},
+) as agent:
+    result = await agent.chat("List the files in this directory.")
+    print(result.messages, result.usage)
+```
+
+Built-ins shipped in 0.2.0:
+
+| Axis | Built-ins | Notes |
+|---|---|---|
+| `engine` | `claude-agent-sdk`, `gitagent` | gitagent reads `GITCLAW_MODEL_BASE_URL` + `OPENAI_API_KEY`. MCP-only tools in 0.2.0. |
+| `runtime` (substrate) | `local` | Caller-owned `Path`, or git-clone an `https://` / `git@` `.git` URL into a temp dir. |
+| `session_store` | `memory` | In-process dict. Mongo + SQLite stores in 0.3.0. |
+| `identity_loader` | `passthrough` | Treats inline dicts as manifests. GAP-style loaders in 0.3.0. |
+
+Plug-ins register at import time via `register_engine(name, instance)` etc. — third-party engines (e2b substrate, deepagents engine, mongo session store) drop in by implementing the matching Protocol in `computeragent.protocol_types`.
+
 ## Quickstart
 
 ```python
@@ -178,7 +226,12 @@ The doc shapes are byte-for-byte compatible with the TypeScript `@open-gitagent/
 
 ### Live chat for library-mode agents
 
-When the AgentRegistrySink writes its `agent_registry.source` row, it includes a full inline `IdentitySource` with `files: {agent.yaml, CLAUDE.md}` derived from your `ClaudeAgentOptions`. If a user clicks "New Chat" on the agent in the AgentOS SPA, the harness can clone those files into a sandbox workdir and spawn a live conversation — same UX as hosted (git-sourced) agents. The historical transcript stays available in the Chat tab regardless.
+Two registry shapes for `agent_registry.source`, depending on which mode emitted the event:
+
+- **Drop-in proxy (`computeragent.query(...)` / `ClaudeSDKClient`)** writes a `type: "inline"` source with `files: {agent.yaml, CLAUDE.md}` derived from your `ClaudeAgentOptions`. If a user clicks "New Chat" on the agent in the AgentOS SPA, the harness can clone those files into a sandbox workdir and spawn a live conversation — same UX as hosted (git-sourced) agents.
+- **Harness (`ComputerAgent`, new in 0.2.0)** writes a `type: "library"` source. There's no remote `harness-server` to proxy a chat-sandbox spawn to (the agent runs in your Python process), so this shape deliberately fails AgentOS's `hasResolvableSource()` check. The AgentOS UI hides the chat-sandbox button (via the matching `liveChatCapable` derived field on `GET /agents`); historical transcripts remain visible in the Chat tab.
+
+Either way, every event still flows through OTel and AgentOS Mongo so the Agents list, Logs tab, and Chat transcript stay populated.
 
 ### DocumentDB compatibility
 

{computer_agent_py-0.1.3 → computer_agent_py-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "computer-agent-py"
-version = "0.1.3"
+version = "0.2.0"
 description = "Drop-in replacement for claude-agent-sdk that adds a proxied telemetry pipeline (PII redaction + guardrails) with OpenTelemetry and AgentOS sinks."
 authors = [
     { name = "Abhi Bhat", email = "abhishek.bhat@lyzr.ai" },
@@ -40,6 +40,14 @@ agentos = [
 cedar = [
     "cedarpy>=4,<5",
 ]
+gitagent = [
+    "openai>=1,<2",
+    "anthropic>=0.40,<1",
+    "pyyaml>=6,<7",
+]
+gap = [
+    "pyyaml>=6,<7",
+]
 all = [
     "opentelemetry-api>=1.27",
     "opentelemetry-sdk>=1.27",
@@ -47,6 +55,9 @@ all = [
     "opentelemetry-semantic-conventions>=0.48b0",
     "motor>=3.5",
     "cedarpy>=4,<5",
+    "openai>=1,<2",
+    "anthropic>=0.40,<1",
+    "pyyaml>=6,<7",
 ]
 
 [project.urls]
@@ -80,6 +91,9 @@ dev = [
     "opentelemetry-semantic-conventions>=0.48b0",
     "motor>=3.5",
     "cedarpy>=4,<5",
+    "openai>=1,<2",
+    "anthropic>=0.40,<1",
+    "pyyaml>=6,<7",
 ]
 
 [tool.ruff]
@@ -103,10 +117,19 @@ select = [
 ignore = ["E501"]
 
 [tool.ruff.lint.per-file-ignores]
-"tests/**" = ["E501", "ASYNC"]
+"tests/**" = ["E501", "ASYNC", "TC001", "TC003"]
 "examples/**" = ["E501"]
 "src/computeragent/__init__.py" = ["F401", "F403"]
 "src/computeragent/types.py" = ["F401", "F403"]
+# 0.2.0 harness layer: protocol value types are referenced from both
+# annotations and runtime code (isinstance, dataclass field defaults).
+# TYPE_CHECKING-only imports would break runtime; ignore the TC nudges.
+"src/computeragent/harness/**" = ["TC001", "TC003", "SIM101"]
+"src/computeragent/engines/**" = ["TC001", "TC003"]
+"src/computeragent/substrates/**" = ["TC003"]
+"src/computeragent/identity/**" = ["TC003"]
+"src/computeragent/session_stores/**" = ["TC001"]
+"src/computeragent/protocol_types/**" = ["TC003"]
 
 [tool.mypy]
 strict = true

computer_agent_py-0.2.0/src/computeragent/__init__.py

@@ -0,0 +1,163 @@
+"""``computeragent`` — drop-in replacement for ``claude_agent_sdk``
+PLUS a harness-based agent stack (added in 0.2.0).
+
+Every public symbol from ``claude_agent_sdk`` is re-exported here with
+identity preserved (``computeragent.ResultMessage is
+claude_agent_sdk.ResultMessage``). ``query`` and ``ClaudeSDKClient`` are
+wrapped so each message flows through a telemetry pipeline with
+configurable PII redaction / guardrails and pluggable sinks
+(OpenTelemetry, AgentOS registry).
+
+Two modes:
+
+1. **Drop-in proxy** (0.1.x, unchanged) — single-import swap::
+
+       # before
+       from claude_agent_sdk import ClaudeAgentOptions, query
+       # after
+       from computeragent import ClaudeAgentOptions, query
+
+2. **Harness** (new in 0.2.0) — mirror of the TypeScript ComputerAgent
+   stack with four orthogonal swappable axes (engine / substrate /
+   session-store / identity-loader)::
+
+       from computeragent import ComputerAgent, run_task
+
+       async with ComputerAgent(source=Path.cwd()) as agent:
+           result = await agent.chat("List the files in this directory")
+
+The two modes co-exist. 0.1.x callers see no behaviour change.
+"""
+
+from __future__ import annotations
+
+import claude_agent_sdk as _cas
+
+# Re-export every public symbol from the upstream package by walking its
+# `__all__`. This is identity-preserving — `computeragent.ResultMessage is
+# claude_agent_sdk.ResultMessage` evaluates True — so user-side
+# `isinstance(msg, ResultMessage)` keeps working regardless of import origin.
+# Skip `__version__` so our own version (set below) wins.
+_upstream_all = [n for n in getattr(_cas, "__all__", []) if n != "__version__"]
+for _name in _upstream_all:
+    globals()[_name] = getattr(_cas, _name)
+
+__version__ = "0.2.0"
+upstream_version = getattr(_cas, "__version__", "unknown")
+
+# Override the two entry points with the proxied versions. Same signatures,
+# same yielded types — but each yielded message also flows through the
+# telemetry pipeline.
+from ._proxy.client import ClaudeSDKClient  # noqa: E402
+from ._proxy.query import query  # noqa: E402
+
+# Harness surface (new in 0.2.0). Importing pulls the registries which
+# register the built-in engines / substrate / session store / identity
+# loader as a side effect — that's intentional so string-label
+# resolution works without an explicit ``register_*`` call.
+from .harness import (  # noqa: E402
+    ChatHandle,
+    ChatInput,
+    ChatResult,
+    ComputerAgent,
+    HarnessError,
+    HarnessProtocolError,
+    UnknownEngineError,
+    UnknownIdentityLoaderError,
+    UnknownSessionStoreError,
+    UnknownSubstrateError,
+    UsageRollup,
+    run_task,
+)
+
+# Policy surface (v0.2 — tool-use authorization). Engines themselves
+# (OpaPolicyEngine, CedarPolicyEngine) stay in ``computeragent.policy`` so
+# users opt into Cedar's extra deliberately.
+from .policy import (  # noqa: E402
+    PolicyAction,
+    PolicyDecision,
+    PolicyEngine,
+    PolicyInput,
+    PolicyPrincipal,
+    PolicyResource,
+    PolicyResult,
+    PolicyToolAuthorizer,
+)
+from .protocol_types import (  # noqa: E402
+    AgentManifest,
+    EngineCapabilities,
+    EngineContext,
+    EngineDriver,
+    EngineEvent,
+    IdentityLoader,
+    IdentitySource,
+    PermissionDecision,
+    PermissionRequest,
+    PolicyDecider,
+    SessionStore,
+    SessionStoreEntry,
+    Substrate,
+    SubstrateHandle,
+)
+
+# Telemetry surface (additions beyond the drop-in mirror).
+from .telemetry import (  # noqa: E402
+    GuardrailFilter,
+    PiiRedactor,
+    Pipeline,
+    TelemetryEvent,
+    TelemetryMiddleware,
+    TelemetrySink,
+    configure,
+    get_pipeline,
+    shutdown,
+)
+
+__all__ = sorted({*_upstream_all, "__version__"}) + [
+    # telemetry + policy add-ons (alphabetical at the tail so the public
+    # symbol list stays scannable when grepped against `claude_agent_sdk.__all__`)
+    "GuardrailFilter",
+    "PiiRedactor",
+    "Pipeline",
+    "PolicyAction",
+    "PolicyDecision",
+    "PolicyEngine",
+    "PolicyInput",
+    "PolicyPrincipal",
+    "PolicyResource",
+    "PolicyResult",
+    "PolicyToolAuthorizer",
+    "TelemetryEvent",
+    "TelemetryMiddleware",
+    "TelemetrySink",
+    "configure",
+    "get_pipeline",
+    "shutdown",
+    # harness layer (0.2.0)
+    "AgentManifest",
+    "ChatHandle",
+    "ChatInput",
+    "ChatResult",
+    "ComputerAgent",
+    "EngineCapabilities",
+    "EngineContext",
+    "EngineDriver",
+    "EngineEvent",
+    "HarnessError",
+    "HarnessProtocolError",
+    "IdentityLoader",
+    "IdentitySource",
+    "PermissionDecision",
+    "PermissionRequest",
+    "PolicyDecider",
+    "SessionStore",
+    "SessionStoreEntry",
+    "Substrate",
+    "SubstrateHandle",
+    "UnknownEngineError",
+    "UnknownIdentityLoaderError",
+    "UnknownSessionStoreError",
+    "UnknownSubstrateError",
+    "UsageRollup",
+    "run_task",
+]

computer_agent_py-0.2.0/src/computeragent/engines/__init__.py

@@ -0,0 +1,56 @@
+"""Engine registry — string labels → :class:`EngineDriver` instances.
+
+Built-ins shipped in 0.2.0:
+
+* ``"claude-agent-sdk"`` — wraps ``claude_agent_sdk.query`` directly.
+* ``"gitagent"`` — Python re-implementation of the gitclaw loop over an
+  OpenAI-compatible endpoint. Requires the ``[gitagent]`` extra (openai).
+  The class is exposed eagerly but the OpenAI client is constructed only
+  on first ``start_session`` — registering the engine never fails on
+  install-time missing extras.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from ..harness.errors import UnknownEngineError
+from ..protocol_types import EngineDriver
+from .claude_agent import ClaudeAgentEngine
+from .git_agent import GitAgentEngine
+
+logger = logging.getLogger("computeragent.engines")
+
+_REGISTRY: dict[str, EngineDriver] = {}
+
+
+def register_engine(name: str, engine: EngineDriver) -> None:
+    if not isinstance(engine, EngineDriver):
+        raise TypeError(
+            f"register_engine({name!r}): instance does not satisfy "
+            "the EngineDriver Protocol"
+        )
+    _REGISTRY[name] = engine
+    logger.debug("registered engine %r", name)
+
+
+def resolve_engine(name: str) -> EngineDriver:
+    try:
+        return _REGISTRY[name]
+    except KeyError as exc:
+        raise UnknownEngineError(
+            f"unknown engine {name!r}; registered: {sorted(_REGISTRY)!r}"
+        ) from exc
+
+
+# Built-ins.
+register_engine("claude-agent-sdk", ClaudeAgentEngine())
+register_engine("gitagent", GitAgentEngine())
+
+
+__all__ = [
+    "ClaudeAgentEngine",
+    "GitAgentEngine",
+    "register_engine",
+    "resolve_engine",
+]

computer_agent_py-0.2.0/src/computeragent/engines/claude_agent.py

@@ -0,0 +1,154 @@
+"""``ClaudeAgentEngine`` — adapter that runs the underlying
+``claude_agent_sdk.query()`` loop inside the harness coordinator.
+
+Calls ``claude_agent_sdk.query`` **directly** rather than going through
+``computeragent._proxy.query``. The proxy emits its own telemetry events
+to the same pipeline the coordinator uses — composing them would double-fire
+every event. Drop-in 0.1.x callers still get the proxy path; harness-mode
+0.2.0 callers go through this engine and rely on the coordinator's
+telemetry hot path.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncIterator
+from contextlib import suppress
+from typing import Any
+
+import claude_agent_sdk
+
+from ..protocol_types import (
+    EngineCapabilities,
+    EngineContext,
+    EngineEvent,
+)
+
+logger = logging.getLogger("computeragent.engines.claude_agent")
+
+_CAPABILITIES = EngineCapabilities(
+    streaming_input=True,
+    partial_messages=True,
+    permission_callback=True,
+    sessions=True,
+    budget=True,
+)
+
+
+class ClaudeAgentEngine:
+    name = "claude-agent-sdk"
+    capabilities = _CAPABILITIES
+
+    async def start_session(
+        self, ctx: EngineContext
+    ) -> AsyncIterator[EngineEvent]:
+        options = _build_options(ctx)
+
+        # claude-agent-sdk wants prompts as an AsyncIterable of
+        # ``{"type": "user", "message": {...}}`` dicts when ``can_use_tool``
+        # is set. The harness supplies normalised user messages in
+        # ``{"role": "user", "content": ...}`` shape via the queue; wrap
+        # them into the SDK's expected envelope here.
+        async def _wrapped_prompts():
+            async for entry in ctx.user_message_queue:
+                if ctx.cancel_event.is_set():
+                    return
+                yield {"type": "user", "message": entry}
+
+        upstream_kwargs: dict[str, Any] = {
+            "prompt": _wrapped_prompts(),
+            "options": options,
+        }
+        try:
+            async for msg in claude_agent_sdk.query(**upstream_kwargs):
+                if ctx.cancel_event.is_set():
+                    with suppress(Exception):
+                        await _maybe_interrupt(msg)
+                    return
+                yield EngineEvent(kind="sdk_message", payload=msg)
+                if _is_result_message(msg):
+                    yield EngineEvent(
+                        kind="usage_snapshot",
+                        cost_semantic="cumulative",
+                        cost_usd=float(getattr(msg, "total_cost_usd", 0.0) or 0.0),
+                        **_usage_fields(msg),
+                    )
+        except Exception:
+            logger.exception("ClaudeAgentEngine.start_session raised")
+            raise
+
+
+def _build_options(ctx: EngineContext) -> Any:
+    """Construct a ``ClaudeAgentOptions`` from the harness context."""
+    from claude_agent_sdk import ClaudeAgentOptions
+
+    # The manifest carries raw kwargs the caller passed via ``options=...``.
+    # Filter to only those keys ``ClaudeAgentOptions`` accepts so a stray
+    # field (e.g. ``model`` typo) raises clearly rather than silently
+    # being attached as an attribute.
+    accepted = set(ClaudeAgentOptions.__dataclass_fields__.keys())
+    payload: dict[str, Any] = {}
+    for key, value in (ctx.manifest.options or {}).items():
+        if key in accepted:
+            payload[key] = value
+
+    payload.setdefault("cwd", str(ctx.workspace_path))
+    if ctx.envs:
+        env_existing = dict(payload.get("env") or {})
+        env_existing.update(ctx.envs)
+        payload["env"] = env_existing
+    # Always stream partials so the harness sees mid-turn assistant text.
+    payload.setdefault("include_partial_messages", True)
+    # Wire policy decider into the can_use_tool slot. ``PolicyToolAuthorizer``
+    # already matches the CanUseTool signature, so no glue.
+    if ctx.policy_decider is not None:
+        payload["can_use_tool"] = ctx.policy_decider
+
+    options = ClaudeAgentOptions(**payload)
+    # Surface harness-supplied agent identity to the proxy's
+    # ``_derive_agent_*`` helpers in case telemetry sinks (or downstream
+    # exporters) introspect these. Setattr instead of ``ClaudeAgentOptions(**...)``
+    # field — the SDK's class doesn't formally declare them but does
+    # accept arbitrary attributes via ``__setattr__``.
+    with suppress(Exception):
+        if ctx.manifest.name:
+            options.agent_name = ctx.manifest.name  # type: ignore[attr-defined]
+    return options
+
+
+def _is_result_message(msg: Any) -> bool:
+    try:
+        from claude_agent_sdk.types import ResultMessage  # type: ignore
+
+        return isinstance(msg, ResultMessage)
+    except ImportError:
+        return False
+
+
+def _usage_fields(msg: Any) -> dict[str, int | None]:
+    usage = getattr(msg, "usage", None)
+    if usage is None:
+        return {}
+    fields: dict[str, int | None] = {}
+    for src_key, dest_key in (
+        ("input_tokens", "input_tokens"),
+        ("output_tokens", "output_tokens"),
+        ("cache_creation_input_tokens", "cache_creation_input_tokens"),
+        ("cache_read_input_tokens", "cache_read_input_tokens"),
+    ):
+        value = getattr(usage, src_key, None)
+        if value is None and isinstance(usage, dict):
+            value = usage.get(src_key)
+        if value is not None:
+            fields[dest_key] = int(value)
+    return fields
+
+
+async def _maybe_interrupt(msg: Any) -> None:
+    # Best-effort cancellation. ``claude_agent_sdk.query`` doesn't expose
+    # an interrupt() hook on the iterator itself; the harness setting
+    # ``cancel_event`` simply causes us to bail out of the loop.
+    return None
+
+
+__all__ = ["ClaudeAgentEngine"]