computer-agent-py 0.1.0__py3-none-any.whl

computer_agent_py-0.1.0.dist-info/METADATA

@@ -0,0 +1,307 @@
+Metadata-Version: 2.3
+Name: computer-agent-py
+Version: 0.1.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
+Author-email: Abhi Bhat <abhishek.bhat@lyzr.ai>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: claude-agent-sdk>=0.2,<0.3
+Requires-Dist: typing-extensions>=4.12
+Requires-Dist: motor>=3.5 ; extra == 'agentos'
+Requires-Dist: opentelemetry-api>=1.27 ; extra == 'all'
+Requires-Dist: opentelemetry-sdk>=1.27 ; extra == 'all'
+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: cedarpy>=4,<5 ; extra == 'cedar'
+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'
+Requires-Dist: opentelemetry-semantic-conventions>=0.48b0 ; extra == 'otel'
+Requires-Python: >=3.10
+Project-URL: Changelog, https://github.com/open-gitagent/computer-agent-py/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://github.com/open-gitagent/computer-agent-py
+Project-URL: Issues, https://github.com/open-gitagent/computer-agent-py/issues
+Provides-Extra: agentos
+Provides-Extra: all
+Provides-Extra: cedar
+Provides-Extra: otel
+Description-Content-Type: text/markdown
+
+# computer-agent-py
+
+[![PyPI](https://img.shields.io/pypi/v/computer-agent-py.svg)](https://pypi.org/project/computer-agent-py/)
+[![Python](https://img.shields.io/pypi/pyversions/computer-agent-py.svg)](https://pypi.org/project/computer-agent-py/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**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.
+
+```diff
+- from claude_agent_sdk import ClaudeAgentOptions, query
+- from claude_agent_sdk.types import ResultMessage
++ from computeragent import ClaudeAgentOptions, query
++ from computeragent.types import ResultMessage
+```
+
+Every other line stays identical. `isinstance(msg, ResultMessage)` still works. The `claude` CLI subprocess, AWS Bedrock auth, MCP servers, permission modes, `cwd`, `add_dirs` — all behave exactly as the upstream SDK does.
+
+> **Package vs import name** — PyPI distribution is `computer-agent-py` (hyphens for the wheel); the import name is `computeragent` (Python doesn't allow hyphens). So `pip install computer-agent-py` then `from computeragent import …`.
+
+## Why use this
+
+Adopting `computer-agent-py` in place of `claude-agent-sdk` gives you, without rewriting your agent code:
+
+- **OpenTelemetry traces** following the GenAI Semantic Conventions, vendor-neutral (New Relic, Datadog, ClickHouse, Honeycomb, Tempo, Jaeger — one env-var change).
+- **PII redaction** at the package boundary — email, phone, SSN, credit cards, AWS keys redacted before anything reaches a sink.
+- **Generic guardrails** — attribute truncation, tool allowlists, per-session cost ceilings, content filters.
+- **Policy-based tool-use authorization** — gate every tool call through OPA (remote) or Cedar (in-process). Fail-closed by default.
+- **AgentOS visibility** — write to the same Mongo collections (`agent_registry`, `agent_logs`, `agent_messages`, `sessions`, `slack_threads`) the AgentOS frontend already reads. Library-mode agents show up in the Agents list, Logs tab, Chat transcript, and (with the harness running) live chat sandboxes.
+- **Per-message archive** — every message, tool call, and policy decision archived to `agent_messages` for replay, RAG, and forensic audit.
+
+## Install
+
+```bash
+pip install computer-agent-py                     # core drop-in + OPA policy engine
+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[all]'              # everything
+```
+
+**Prerequisite** — same as upstream: the `claude` CLI binary on `PATH` and Anthropic / Bedrock credentials in the environment.
+
+## Quickstart
+
+```python
+import asyncio
+from computeragent import ClaudeAgentOptions, query
+from computeragent.types import ResultMessage
+
+async def main():
+    options = ClaudeAgentOptions(
+        model="claude-sonnet-4-5",
+        system_prompt="You are a helpful assistant.",
+        allowed_tools=["Read", "Glob", "Grep"],
+        permission_mode="bypassPermissions",
+    )
+
+    async for message in query(prompt="Summarize the README.md in this directory.", options=options):
+        if isinstance(message, ResultMessage):
+            print(f"answer ({message.num_turns} turns, ${message.total_cost_usd:.4f}):")
+            print(message.result)
+
+asyncio.run(main())
+```
+
+That's it — same shape as `claude-agent-sdk`. Telemetry is configured from env vars; without anything set, nothing leaves your process.
+
+## Configure telemetry
+
+### Env-driven (zero code change)
+
+| Variable | Effect |
+|---|---|
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | Enables OTLP/HTTP export. Unset → console exporter (debug). |
+| `OTEL_EXPORTER_OTLP_HEADERS` | Comma-separated `key=value` (e.g. `api-key=NRRX-...` for New Relic). |
+| `OTEL_SERVICE_NAME` | `service.name` attribute on every span. Default: `computeragent`. |
+| `COMPUTERAGENT_OTEL` | `disabled` to suppress OtelSink. |
+| `AGENTOS_MONGO_URL` | When set + `[agentos]` installed, attaches AgentOS sinks (registry, logs, sessions, agent_messages, slack_threads). |
+| `AGENTOS_MONGO_DB` | Mongo database name. Default: `agentos`. |
+| `COMPUTERAGENT_CAPTURE_CONTENT` | `1` to include prompts/responses on OTel spans. Default: off. |
+| `COMPUTERAGENT_CAPTURE_CONTENT_MODE` | `events` (default) \| `attributes` \| `both`. |
+
+### Programmatic
+
+```python
+from computeragent import configure, PiiRedactor, GuardrailFilter
+from computeragent.telemetry.sinks import OtelSink, AgentRegistrySink, MongoMessageSink
+
+configure(
+    middleware=[
+        PiiRedactor(strategy="hash", extra_patterns=[r"BADGE-\d{6}"]),
+        GuardrailFilter(
+            max_attribute_length=4096,
+            tool_name_allowlist={"Read", "Glob", "Grep", "mcp__nordassist-tools__*"},
+            cost_ceiling_usd=1.50,
+        ),
+    ],
+    sinks=[
+        OtelSink(),                                                     # picks up env
+        AgentRegistrySink(mongo_url="mongodb://..."),                   # registry + logs + sessions + slack_threads
+        MongoMessageSink(mongo_url="mongodb://..."),                    # per-message archive
+    ],
+)
+```
+
+## Vendor-neutral OTel destinations
+
+The package emits standard OTLP — point it at any backend by setting two env vars. No code change.
+
+| Destination | `OTEL_EXPORTER_OTLP_ENDPOINT` | `OTEL_EXPORTER_OTLP_HEADERS` |
+|---|---|---|
+| **New Relic** | `https://otlp.nr-data.net` | `api-key=<NR_LICENSE_KEY>` |
+| **Datadog** (via DD Agent OTLP) | `http://localhost:4318` | _(unset; agent handles auth)_ |
+| **Honeycomb** | `https://api.honeycomb.io` | `x-honeycomb-team=<KEY>` |
+| **Grafana Cloud Tempo** | `https://tempo-prod-...grafana.net:443` | `authorization=Basic <base64>` |
+| **Self-hosted Jaeger / Tempo / SigNoz** | `http://<host>:4318` | _(unset)_ |
+| **Local console (debug)** | _(unset)_ | _(unset)_ |
+
+Full recipe table — including direct New Relic / Datadog without an OTel collector — is in [`examples/e2e/destinations.md`](examples/e2e/destinations.md).
+
+## Policy-based tool-use authorization
+
+For agents that need stronger guardrails than `permission_mode`, attach an external policy engine. Activation is a single new option-field; the rest of the worker code is unchanged.
+
+```python
+from computeragent import ClaudeAgentOptions, PolicyPrincipal, PolicyResource, query
+from computeragent.policy import OpaPolicyEngine, PolicyToolAuthorizer
+
+opa = OpaPolicyEngine(
+    url="http://opa.platform:8181",
+    policy_path="computeragent/tools/allow",
+    fail_mode="deny",   # default — engine errors deny the call
+)
+authorizer = PolicyToolAuthorizer(
+    engine=opa,
+    principal_resolver=lambda ctx: PolicyPrincipal(id="alice", groups=["engineer"]),
+    resource_resolver=lambda ctx: PolicyResource(agent_name="nordassist", model="claude-sonnet-4-5"),
+    context_resolver=lambda ctx: {"env": "prod"},
+)
+
+options = ClaudeAgentOptions(
+    ...,
+    permission_mode="default",  # was "bypassPermissions"
+    can_use_tool=authorizer,
+)
+```
+
+Swap `OpaPolicyEngine` for `CedarPolicyEngine` (install with `pip install 'computer-agent-py[cedar]'`) and the worker code is identical:
+
+```python
+from computeragent.policy import CedarPolicyEngine
+
+cedar = CedarPolicyEngine(
+    policies=open("policies/computeragent.cedar").read(),
+    fail_mode="deny",
+)
+authorizer = PolicyToolAuthorizer(engine=cedar, principal_resolver=..., ...)
+```
+
+Sample policies are in [`examples/policies/`](examples/policies/) — one Rego file for OPA, one Cedar file. Each policy receives a canonical `PolicyInput` shape (`principal`, `action`, `resource`, `context`) so the engine choice is purely operational.
+
+Every authorization decision emits a `policy_decision` telemetry event — `OtelSink` annotates the active `execute_tool` span with `policy.decision`, `policy.reason`, `policy.engine`, and `policy.latency_ms` so security audits and span queries co-locate.
+
+## AgentOS integration
+
+When `[agentos]` is installed and `AGENTOS_MONGO_URL` is set, every agent run writes to the Mongo collections the AgentOS frontend already reads:
+
+| Collection | Per | What's in it |
+|---|---|---|
+| `agent_registry` | agent name | Identity + harness + model + last-seen; idempotent upsert |
+| `agent_logs` | run | Rolled-up query/reply + tokens + cost + ok/error — drives the Logs tab |
+| `sessions` | session | `entries[]` of `{type, text}` chat-bubble messages — drives the Chat tab transcript |
+| `slack_threads` | session | TS parity row that drives the per-agent `sessionCount` + `lastActivity` aggregates |
+| `agent_messages` | message | Per-event archive (`user_message`, `assistant_message`, `tool_use`, `tool_result`, `usage_snapshot`, `policy_decision`, `system_message`) for replay, RAG, audit |
+
+The doc shapes are byte-for-byte compatible with the TypeScript `@open-gitagent/agent-registry-mongo` package — Python-driven agents show up in the same AgentOS UI that hosted TS agents do, with no frontend change.
+
+### 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.
+
+### DocumentDB compatibility
+
+Prod deployments on AWS DocumentDB work without changes. The sinks use only operators DocumentDB supports — `$set`, `$setOnInsert`, `$push`, `update_one(upsert=True)`, `insert_one`. No aggregation pipelines, transactions, change streams, or TTL indexes. Set `MONGO_URL` with the standard `tls=true&tlsCAFile=...` params and mount the DocumentDB CA bundle.
+
+## Architecture
+
+```
+                 user code: from computeragent import query, ClaudeAgentOptions
+                                          │
+                                          ▼
+                      computeragent._proxy.query  ──┐
+                        │                            │
+                        ▼                            │  PolicyToolAuthorizer
+   claude_agent_sdk → claude CLI subprocess → Bedrock│ (OPA / Cedar)
+                        │                            │  via can_use_tool
+                        ▼                            │
+                  yielded messages                   │
+                        │                            │
+                        ▼                            │
+               TelemetryPipeline (taps stream)       │
+                        │                            │
+       ┌──── middleware ─────┐                       │
+       │  PiiRedactor        │                       │
+       │  GuardrailFilter    │  ◄────────────────────┘
+       │  <user-defined>     │
+       └────────┬────────────┘
+                ▼
+     ┌──── fan-out to sinks ───────────────────────────┐
+     │                                                  │
+     ▼            ▼                       ▼             ▼
+  OtelSink   AgentRegistrySink     MongoMessageSink  <user>
+     │            │                       │
+     ▼            ▼                       ▼
+  OTLP backend  agent_registry      agent_messages
+  (NR / DD /    agent_logs          (per-message
+   ClickHouse / sessions             archive)
+   Tempo …)     slack_threads
+                (drives AgentOS UI)
+```
+
+The proxy is a pure tap — messages are never modified or reordered. Sinks run as background tasks so a slow exporter never stalls the agent hot path; `query()`'s `finally` block awaits them with a 5 s default timeout. Telemetry never breaks an agent run: middleware and sink exceptions are absorbed and logged.
+
+## Live e2e against AgentOS
+
+[`examples/e2e/`](examples/e2e/) contains a recipe for standing up the full TypeScript stack (mongo + clickhouse + otel-collector + harness + agentos-server + SPA) via docker-compose and running this package against it. After ~60s of warm-up plus a 30s Python script run, you'll see the agent appear in the SPA's Agents list with `logCount`, `sessionCount`, `lastActivity`, and `activeSandboxes` populated; the Logs tab will show the rollup; the Chat tab will show the per-message transcript; the Observability tab will show the OTel trace tree. See [`examples/e2e/README.md`](examples/e2e/README.md).
+
+## Examples
+
+| File | Demonstrates |
+|---|---|
+| [`examples/pdf_drop_in.py`](examples/pdf_drop_in.py) | The minimum drop-in change |
+| [`examples/with_otel.py`](examples/with_otel.py) | OTel pointed at a local collector |
+| [`examples/with_new_relic.py`](examples/with_new_relic.py) | OTel pointed at New Relic (just env vars) |
+| [`examples/with_datadog.py`](examples/with_datadog.py) | OTel pointed at Datadog |
+| [`examples/with_agentos.py`](examples/with_agentos.py) | AgentOS Mongo writes |
+| [`examples/with_message_archive.py`](examples/with_message_archive.py) | Per-message archive |
+| [`examples/with_pii_redaction.py`](examples/with_pii_redaction.py) | PII middleware in front of every sink |
+| [`examples/with_opa_policy.py`](examples/with_opa_policy.py) | OPA-gated tool use |
+| [`examples/with_cedar_policy.py`](examples/with_cedar_policy.py) | Cedar-gated tool use (in-process) |
+| [`examples/multi_sink.py`](examples/multi_sink.py) | All sinks + all guardrails together |
+| [`examples/e2e/run_live_demo.py`](examples/e2e/run_live_demo.py) | Full live demo against the AgentOS docker-compose stack |
+
+## Upstream pin
+
+This release tracks **`claude-agent-sdk` 0.2.x**. The pinned upstream version is recorded in [`CHANGELOG.md`](CHANGELOG.md). Bump deliberately — wire-protocol field additions in upstream get re-exported automatically (identity-preserving), but any behavioral changes need a passthrough audit.
+
+## Development
+
+```bash
+git clone https://github.com/open-gitagent/computer-agent-py
+cd computer-agent-py
+uv sync --all-extras --dev
+uv run ruff check src tests
+uv run ruff format --check src tests
+uv run mypy src
+uv run pytest -q                    # 120+ unit tests
+uv run pytest -q -m integration     # requires ANTHROPIC_API_KEY + claude CLI
+uv build
+```
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

computer_agent_py-0.1.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+computeragent/__init__.py,sha256=w_MWC-nCutEhDdnHx4SiKFToiVex8lHHKyIG1DHexzA,2939
+computeragent/_proxy/__init__.py,sha256=7x5lm5tt4NhW8-4LvlM1grmdH0D_H5Ijc7a_BQjmMU8,218
+computeragent/_proxy/client.py,sha256=FxRfA8mUdVTjQhlf4xTHCbUddZruvTPLzUOLWs5hzx8,8768
+computeragent/_proxy/query.py,sha256=VIKMkbUPVHL3dUF4wggbXb0Gu35cTcu2HYd6-yL1nUg,6107
+computeragent/policy/__init__.py,sha256=pKiV2ulBZW8khTa57UfqXGnicMviYxqL3CTO37Xo2js,1814
+computeragent/policy/authorizer.py,sha256=PlkIcKtnSwl-B9f2FspX3-nVfzNLa43itV8EgnjW0BU,6310
+computeragent/policy/cedar.py,sha256=mofBDW3HntADaim2WcMLUAXeZ9_OKaXuhMsaLRqzw10,6959
+computeragent/policy/opa.py,sha256=Pho2_a97UhEpFsdvHJ71dXTnytqBYCmYb2GYpR7dABM,4920
+computeragent/policy/types.py,sha256=sAGXyqT_-I-u9y2Mp583vkg86X9EOuI4YVBnaElnFVo,3488
+computeragent/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+computeragent/telemetry/__init__.py,sha256=VZFpiN6hJHu5w8ISROlrRvotKyGdGlbSWjmXdu6mTEk,647
+computeragent/telemetry/config.py,sha256=luSsIftLniXQ0n9rDY3oFaA19I3D5tZHTL9wFS9iExk,6475
+computeragent/telemetry/event.py,sha256=qsBvY3q4ORUSaUC49pzHWnH_27Qy9eujT4KCHMlimgM,13819
+computeragent/telemetry/middleware/__init__.py,sha256=4poNMyaJuiVhE0KSvYcTwCbcwbNAqOUJb6HeSkn160M,222
+computeragent/telemetry/middleware/guardrails.py,sha256=elcT3AdvOTddwY-Lp0rQKchTlCAq3Y2-ky3cp9n2lbo,5435
+computeragent/telemetry/middleware/pii.py,sha256=xD2JRR97GNw_5TMz1PhYLcl2HkLuLS4BQrfhOjsJMVg,6453
+computeragent/telemetry/pipeline.py,sha256=bxuYJ1oNzRyT992I6SUF-K65MJywKpFZBp6-zcc3HOI,5667
+computeragent/telemetry/sinks/__init__.py,sha256=sDBRPu9-9pDWFeavxzs6mo3EXIL8jJyElB8hC03e4uc,1009
+computeragent/telemetry/sinks/agentos.py,sha256=vOZq-kwzGFHCiaMj82AOQqKGxcDLePngwlos7SMhs4Y,17707
+computeragent/telemetry/sinks/message_archive.py,sha256=N5kEjCHjph0oevY7n0EeRd2c0bFppSrlpHm3Ijcu4ao,5339
+computeragent/telemetry/sinks/otel.py,sha256=xOUufyiJpZsuPCmUp0bi7onCcEUPmGE3xXfyj9le5Y8,15914
+computeragent/types.py,sha256=ttjh1Ovb4zWWUv68jhCtb14lH83YsapP8ailmpo7PbY,475
+computer_agent_py-0.1.0.dist-info/WHEEL,sha256=eycQt0QpYmJMLKpE3X9iDk8R04v2ZF0x82ogq-zP6bQ,79
+computer_agent_py-0.1.0.dist-info/METADATA,sha256=WsCcBdn8DSTEreP49T1ir1c2T35nwprXYXyZYLkcfg8,16897
+computer_agent_py-0.1.0.dist-info/RECORD,,

computer_agent_py-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.9.24
+Root-Is-Purelib: true
+Tag: py3-none-any

computeragent/__init__.py

@@ -0,0 +1,90 @@
+"""``computeragent`` — drop-in replacement for ``claude_agent_sdk``.
+
+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 that every message flowing
+through the upstream stream also flows through a telemetry pipeline with
+configurable PII-redaction / guardrail middleware and pluggable sinks
+(OpenTelemetry, AgentOS registry).
+
+Drop-in usage::
+
+    # before
+    from claude_agent_sdk import ClaudeAgentOptions, query
+    from claude_agent_sdk.types import ResultMessage
+
+    # after — every other line stays identical
+    from computeragent import ClaudeAgentOptions, query
+    from computeragent.types import ResultMessage
+"""
+
+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.1.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
+
+# 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,
+)
+
+# 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",
+]

computeragent/_proxy/__init__.py

@@ -0,0 +1,8 @@
+"""Proxied entry points — same signatures as upstream, plus telemetry tap."""
+
+from __future__ import annotations
+
+from .client import ClaudeSDKClient
+from .query import query
+
+__all__ = ["ClaudeSDKClient", "query"]

computeragent/_proxy/client.py

@@ -0,0 +1,225 @@
+"""``ClaudeSDKClient`` — wraps upstream's class with a telemetry tap.
+
+The wrapper holds an instance of the upstream client and forwards every
+public method. ``receive_messages`` and ``receive_response`` re-yield messages
+through the telemetry pipeline so multi-turn callers get the same
+observability as :func:`computeragent.query`.
+
+Control methods (``set_model``, ``get_context_usage``, etc.) pass straight
+through — no telemetry for those today (can be added later as
+``operation_started`` / ``operation_ended`` events).
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import TYPE_CHECKING, Any
+
+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
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterable, AsyncIterator
+
+logger = logging.getLogger("computeragent")
+
+
+class ClaudeSDKClient:
+    """Drop-in for :class:`claude_agent_sdk.ClaudeSDKClient`.
+
+    Same surface, same semantics, plus telemetry. The wrapper does not hold
+    extra state beyond the upstream instance and a per-session id used to
+    correlate emitted events.
+    """
+
+    def __init__(self, options: Any = None, transport: Any = None) -> None:
+        kwargs: dict[str, Any] = {}
+        if options is not None:
+            kwargs["options"] = options
+        if transport is not None:
+            kwargs["transport"] = transport
+        self._inner = claude_agent_sdk.ClaudeSDKClient(**kwargs)
+        self._options = options
+        self._session_id: str = new_session_id()
+        # Upstream's own session id is captured for join-by-id but is NOT
+        # used as the sink/event session_id (see _proxy.query for the
+        # placeholder-vs-upstream rationale).
+        self._upstream_session_id: str | None = None
+        self._agent_name = _derive_agent_name(options)
+        self._started_at: float | None = None
+        self._last_result: ResultMessage | None = None
+        self._last_assistant_text: str = ""
+        self._connected = False
+
+    # ── lifecycle ----------------------------------------------------------
+
+    async def __aenter__(self) -> ClaudeSDKClient:
+        await self.connect()
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> bool:
+        try:
+            await self.disconnect()
+        except Exception:  # noqa: BLE001
+            logger.debug("disconnect in __aexit__ failed", exc_info=True)
+        return False
+
+    async def connect(self, prompt: str | AsyncIterable[dict[str, Any]] | None = None) -> None:
+        pipeline = get_pipeline()
+        self._started_at = time.monotonic()
+        await pipeline.emit(
+            TelemetryEvent.session_started(
+                session_id=self._session_id,
+                agent_name=self._agent_name,
+                options=self._options,
+                prompt=prompt if prompt is not None else "<connect>",
+            )
+        )
+        if prompt is None:
+            await self._inner.connect()
+        else:
+            await self._inner.connect(prompt)
+        self._connected = True
+
+    async def disconnect(self) -> None:
+        if not self._connected:
+            return
+        try:
+            await self._emit_session_ended()
+        finally:
+            self._connected = False
+            try:
+                await self._inner.disconnect()
+            finally:
+                try:
+                    await get_pipeline().flush()
+                except Exception:  # noqa: BLE001
+                    logger.debug("flush in disconnect failed", exc_info=True)
+
+    # ── streaming ----------------------------------------------------------
+
+    async def query(
+        self, prompt: str | AsyncIterable[dict[str, Any]], session_id: str = "default"
+    ) -> None:
+        await self._inner.query(prompt, session_id=session_id)
+
+    async def receive_messages(self) -> AsyncIterator[Any]:
+        pipeline = get_pipeline()
+        async for msg in self._inner.receive_messages():
+            real_sid = getattr(msg, "session_id", None)
+            if (
+                isinstance(real_sid, str)
+                and real_sid
+                and real_sid != self._session_id
+                and self._upstream_session_id is None
+            ):
+                # Capture but don't rebind — see _proxy.query for rationale.
+                self._upstream_session_id = real_sid
+            for ev in TelemetryEvent.from_message(
+                msg, session_id=self._session_id, agent_name=self._agent_name
+            ):
+                await pipeline.emit(ev)
+            if isinstance(msg, AssistantMessage):
+                for block in getattr(msg, "content", []) or []:
+                    if isinstance(block, TextBlock):
+                        self._last_assistant_text = block.text
+            if isinstance(msg, ResultMessage):
+                self._last_result = msg
+            yield msg
+
+    async def receive_response(self) -> AsyncIterator[Any]:
+        pipeline = get_pipeline()
+        async for msg in self._inner.receive_response():
+            real_sid = getattr(msg, "session_id", None)
+            if (
+                isinstance(real_sid, str)
+                and real_sid
+                and real_sid != self._session_id
+                and self._upstream_session_id is None
+            ):
+                self._upstream_session_id = real_sid
+            for ev in TelemetryEvent.from_message(
+                msg, session_id=self._session_id, agent_name=self._agent_name
+            ):
+                await pipeline.emit(ev)
+            if isinstance(msg, AssistantMessage):
+                for block in getattr(msg, "content", []) or []:
+                    if isinstance(block, TextBlock):
+                        self._last_assistant_text = block.text
+            if isinstance(msg, ResultMessage):
+                self._last_result = msg
+            yield msg
+
+    async def interrupt(self) -> None:
+        await self._inner.interrupt()
+
+    # ── pass-through control methods ---------------------------------------
+
+    async def set_model(self, model: str | None = None) -> None:
+        await self._inner.set_model(model)
+
+    async def set_permission_mode(self, mode: Any) -> None:
+        await self._inner.set_permission_mode(mode)
+
+    async def get_context_usage(self) -> Any:
+        return await self._inner.get_context_usage()
+
+    async def get_mcp_status(self) -> Any:
+        return await self._inner.get_mcp_status()
+
+    async def get_server_info(self) -> dict[str, Any] | None:
+        # Upstream's `get_server_info` is async; the proxy mirrors that.
+        result: dict[str, Any] | None = await self._inner.get_server_info()
+        return result
+
+    async def reconnect_mcp_server(self, server_name: str) -> None:
+        await self._inner.reconnect_mcp_server(server_name)
+
+    async def toggle_mcp_server(self, server_name: str, enabled: bool) -> None:
+        await self._inner.toggle_mcp_server(server_name, enabled)
+
+    async def stop_task(self, task_id: str) -> None:
+        await self._inner.stop_task(task_id)
+
+    async def rewind_files(self, user_message_id: str) -> None:
+        await self._inner.rewind_files(user_message_id)
+
+    # ── internals ----------------------------------------------------------
+
+    async def _emit_session_ended(self) -> None:
+        if self._started_at is None:
+            return
+        duration_ms = (time.monotonic() - self._started_at) * 1000.0
+        pipeline = get_pipeline()
+        if self._last_result is not None:
+            ev = TelemetryEvent.session_ended_ok(
+                session_id=self._session_id,
+                agent_name=self._agent_name,
+                result=self._last_result,
+                duration_ms=duration_ms,
+                last_assistant_text=self._last_assistant_text,
+            )
+            if self._upstream_session_id is not None:
+                ev.payload["upstream_session_id"] = self._upstream_session_id
+            await pipeline.emit(ev)
+        else:
+            await pipeline.emit(
+                TelemetryEvent(
+                    kind="session_ended",
+                    session_id=self._session_id,
+                    agent_name=self._agent_name,
+                    payload={
+                        "is_error": False,
+                        "subtype": "no_result",
+                        "result": self._last_assistant_text,
+                        "duration_ms": duration_ms,
+                        "num_turns": 0,
+                        "total_cost_usd": 0.0,
+                        "usage": {},
+                    },
+                )
+            )