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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: computer-agent-py
-Version: 0.1.1
+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.1 → 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.1 → computer_agent_py-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "computer-agent-py"
-version = "0.1.1"
+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.1.1 → computer_agent_py-0.2.0}/src/computeragent/_proxy/client.py

@@ -20,7 +20,7 @@ import claude_agent_sdk
 from claude_agent_sdk.types import AssistantMessage, ResultMessage, TextBlock
 
 from ..telemetry import TelemetryEvent, get_pipeline, new_session_id
-from .query import _derive_agent_name
+from .query import _derive_agent_description, _derive_agent_name
 
 if TYPE_CHECKING:
     from collections.abc import AsyncIterable, AsyncIterator
@@ -50,6 +50,7 @@ class ClaudeSDKClient:
         # placeholder-vs-upstream rationale).
         self._upstream_session_id: str | None = None
         self._agent_name = _derive_agent_name(options)
+        self._agent_description = _derive_agent_description(options)
         self._started_at: float | None = None
         self._last_result: ResultMessage | None = None
         self._last_assistant_text: str = ""
@@ -75,6 +76,7 @@ class ClaudeSDKClient:
             TelemetryEvent.session_started(
                 session_id=self._session_id,
                 agent_name=self._agent_name,
+                agent_description=self._agent_description,
                 options=self._options,
                 prompt=prompt if prompt is not None else "<connect>",
             )
@@ -122,6 +124,8 @@ class ClaudeSDKClient:
             for ev in TelemetryEvent.from_message(
                 msg, session_id=self._session_id, agent_name=self._agent_name
             ):
+                if self._agent_description is not None:
+                    ev.agent_description = self._agent_description
                 await pipeline.emit(ev)
             if isinstance(msg, AssistantMessage):
                 for block in getattr(msg, "content", []) or []:
@@ -145,6 +149,8 @@ class ClaudeSDKClient:
             for ev in TelemetryEvent.from_message(
                 msg, session_id=self._session_id, agent_name=self._agent_name
             ):
+                if self._agent_description is not None:
+                    ev.agent_description = self._agent_description
                 await pipeline.emit(ev)
             if isinstance(msg, AssistantMessage):
                 for block in getattr(msg, "content", []) or []:
@@ -203,6 +209,7 @@ class ClaudeSDKClient:
                 duration_ms=duration_ms,
                 last_assistant_text=self._last_assistant_text,
             )
+            ev.agent_description = self._agent_description
             if self._upstream_session_id is not None:
                 ev.payload["upstream_session_id"] = self._upstream_session_id
             await pipeline.emit(ev)
@@ -212,6 +219,7 @@ class ClaudeSDKClient:
                     kind="session_ended",
                     session_id=self._session_id,
                     agent_name=self._agent_name,
+                    agent_description=self._agent_description,
                     payload={
                         "is_error": False,
                         "subtype": "no_result",

{computer_agent_py-0.1.1 → computer_agent_py-0.2.0}/src/computeragent/_proxy/query.py

@@ -39,6 +39,7 @@ async def query(  # noqa: PLR0912 - mirror upstream's tolerant param surface
     pipeline = get_pipeline()
     session_id = new_session_id()
     agent_name = _derive_agent_name(options)
+    agent_description = _derive_agent_description(options)
     started_at = time.monotonic()
     last_assistant_text = ""
 
@@ -47,6 +48,7 @@ async def query(  # noqa: PLR0912 - mirror upstream's tolerant param surface
             TelemetryEvent.session_started(
                 session_id=session_id,
                 agent_name=agent_name,
+                agent_description=agent_description,
                 options=options,
                 prompt=prompt,
             )
@@ -78,6 +80,11 @@ async def query(  # noqa: PLR0912 - mirror upstream's tolerant param surface
             for ev in TelemetryEvent.from_message(
                 msg, session_id=session_id, agent_name=agent_name
             ):
+                # Carry the description forward on every event so sinks that
+                # group by description (or want to surface it on per-message
+                # telemetry) don't have to back-reference session_started.
+                if agent_description is not None:
+                    ev.agent_description = agent_description
                 await pipeline.emit(ev)
 
             if isinstance(msg, AssistantMessage):
@@ -100,6 +107,7 @@ async def query(  # noqa: PLR0912 - mirror upstream's tolerant param surface
                 duration_ms=duration_ms,
                 last_assistant_text=last_assistant_text,
             )
+            ev.agent_description = agent_description
             if upstream_session_id is not None:
                 ev.payload["upstream_session_id"] = upstream_session_id
             await pipeline.emit(ev)
@@ -110,6 +118,7 @@ async def query(  # noqa: PLR0912 - mirror upstream's tolerant param surface
                     kind="session_ended",
                     session_id=session_id,
                     agent_name=agent_name,
+                    agent_description=agent_description,
                     payload={
                         "is_error": False,
                         "subtype": "no_result",
@@ -124,14 +133,14 @@ async def query(  # noqa: PLR0912 - mirror upstream's tolerant param surface
     except BaseException as exc:
         duration_ms = (time.monotonic() - started_at) * 1000.0
         try:
-            await pipeline.emit(
-                TelemetryEvent.session_ended_error(
-                    session_id=session_id,
-                    agent_name=agent_name,
-                    exc=exc,
-                    duration_ms=duration_ms,
-                )
+            err_ev = TelemetryEvent.session_ended_error(
+                session_id=session_id,
+                agent_name=agent_name,
+                exc=exc,
+                duration_ms=duration_ms,
             )
+            err_ev.agent_description = agent_description
+            await pipeline.emit(err_ev)
         except Exception:  # noqa: BLE001
             logger.debug("error-path telemetry emit failed", exc_info=True)
         raise
@@ -163,3 +172,20 @@ def _derive_agent_name(options: Any) -> str | None:
         if first:
             return first[:80]
     return None
+
+
+def _derive_agent_description(options: Any) -> str | None:
+    """Pick an agent description from options.
+
+    Mirrors :func:`_derive_agent_name` — the description is purely opt-in.
+    Callers set it on options via ``options.agent_description = "..."`` and
+    the proxy threads it through to the telemetry pipeline. Unlike the
+    name, there's no implicit fallback to system_prompt: a description is
+    a human label, not something we want to synthesize from the prompt.
+    """
+    if options is None:
+        return None
+    desc = getattr(options, "agent_description", None)
+    if isinstance(desc, str) and desc:
+        return desc
+    return None

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",
+]