diff --git a/WORKERS.md b/WORKERS.md new file mode 100644 index 00000000..15c93d0b --- /dev/null +++ b/WORKERS.md @@ -0,0 +1,143 @@ +# Workers: one object, one CLI session + +`ai.workers` is experimental. `ClaudeCode`, `Codex`, and `Pi` share one session +API. They also work with `ai.stream`, `ai.experimental_generate`, and +`ai.Agent.run`. The CLI store owns the transcript; `worker.messages` is its +Python mirror. + +## Direct control + +```python +import contextlib + +import ai +from ai import workers + +async def main(): + async with workers.ClaudeCode(model_name="sonnet", approve=True) as worker: + await worker.send("Inspect this directory and summarize it.") + async with contextlib.aclosing(worker.events()) as feed: + async for event in feed: + if isinstance(event, ai.events.PendingHookEvent): + ai.resolve_hook( + event.hook, + {"granted": False, "reason": "No tool access today."}, + registry=worker.hook_registry, + ) + elif isinstance(event, ai.events.TextDelta): + print(event.chunk, end="") + elif isinstance(event, ai.events.StreamEnd): + break +``` + +- `open()` starts the transport once. Session creation is lazy until input. + The context manager and input/output methods call `open()` automatically. +- `send()` takes a string or a list of `TextPart | FilePart`. It waits for + transport acceptance, not an answer. During a turn, it sends guidance. +- `events()` is one feed across turns. Only one reader is permitted. A second + reader, including an overlapping model stream, raises `WorkerError`. +- `interrupt()` requests a clean turn end. Keep reading to receive the end event. +- `close()` stops the CLI and unblocks the reader. The saved fields remain. + Use `contextlib.aclosing` if you leave a reader early; it stops active work. + +The feed type is `workers.SessionEvent`: + +| Event | Meaning | +| --- | --- | +| `StreamStart`, `StreamEnd` | Assistant response boundaries | +| `UserMessageAccepted` | Transport accepted input; reading this event updates the mirror | +| `Text*`, `Reasoning*`, `BuiltinTool*` | Output and CLI-owned tool activity | +| `HookEvent` | An approval is pending, resolved, or cancelled | + +Direct approvals work without Agent. Pass `registry=worker.hook_registry` to +`ai.resolve_hook`. Inside Agent, its current registry is used, including when +the CLI transport was opened before the run. Approval coverage depends on the +native policy; `approve=True` is not a sandbox. Bare model streaming outside +Agent cannot deliver hook events: use the direct feed or Agent for approvals. + +## Model use + +```python +async def model_use(): + async with workers.Codex() as worker: + answer = await ai.experimental_generate( + worker, [ai.user_message("Explain the tests.")] + ) + follow_up = await ai.experimental_generate( + worker, [*worker.messages, ai.user_message("Give a short summary.")] + ) + return answer, follow_up +``` + +`stream()` sends only new input, then reads `events()` through one assistant +message. To add Python tools, use `ai.Agent(tools=[...]).run(worker, messages)`. +The MCP bridge passes these calls to Agent. CLI tools remain built-in events +and are not executed again by Agent. Direct `send()` does not take Python tools. + +The request must preserve the known history. Changed ids, roles, or parts raise +`TranscriptMismatchError`; a mismatch never silently creates a new session. +Structured output keeps native parts in the mirror and saves the model-facing +parts in message metadata. Validation retries also remain in native history, +but are hidden from the model-facing view. Both complete views can continue the +session, including after dump/validate. After `sync()`, use the new native mirror. + +Read pending direct events before switching to model use. Alternatively, once +the turn is idle, `sync()` replaces the mirror and discards superseded events. + +## State, fork, and TUI + +- `model_dump()` / `Worker.model_validate()` save and restore settings, + `session_id`, and `messages`. They do not save processes or pending hooks. +- `sync()` reads authoritative native history. It requires a session id and + no active turn or reader. Store normalization can change message ids/parts. +- `fork()` creates an already-open native branch with a different session id + and loaded history. It requires an idle session with no reader. Close the + returned worker, or manage it with `async with`. +- `model_copy()` resets private transport state but retains the session id. + It is **not a fork**. Do not use two copies as concurrent writers. +- `tui_command()` returns `(argv, env)`. Close the worker before running that + command in `worker.cwd`; call `sync()` when the person finishes. `tui()` + handles those steps. `ConcreteWorker.list_sessions(cwd=...)` lists sessions. +- Unsupported operations raise `UnsupportedError`. There is no capabilities + object or adapter instance. Concrete workers own private CLI state and + `_cli_*` methods; common `send()` / `events()` logic stays in the base. + +## Migration + +| Old API | New API | +| --- | --- | +| `kind` | `worker_class_id` | +| `model` | `model_name` | +| `fork=True` | `await worker.fork()` | +| `load()` | `await worker.sync()` | +| `steer()` | `await worker.send(prompt)` | + +Old field names have no aliases. Rename saved keys and remove the old fork flag +before validation. If it was true, explicitly create a native fork. +`executable` remains a string: a PATH command or filesystem path. + +A fresh worker can import history on its first model call. This is **lossy +seeding**, not a native fork. Unsupported reasoning/files are omitted or rendered +as notes with warnings. Native ids and arbitrary metadata are not guaranteed. + +## CLI limits and verification + +Acceptance is transport-level. Claude confirms an SDK input write; Codex confirms +a start/steer RPC; Pi confirms a prompt that can be queued or extension-handled. +This does not prove native storage or expose universal input-to-turn correlation. +Only `sync()` reconciles the mirror with the CLI store. Claude's response counting +assumes one terminal result per accepted query; native coalescing and background +responses need live verification. Pi has no public follow-up selector. + +Offline verification includes workers, Agent hooks, and model integration: + +```sh +uv run --frozen pytest -q tests/workers tests/agents tests/models --timeout=15 --tb=short +uv run --frozen ruff format --check src tests examples +uv run --frozen ruff check src tests examples +uv run --frozen mypy +uv run --frozen ty check +``` + +Live tests were updated but not run. They use real CLI logins and paid model +calls. Historical `VERIFIED_VERSION` comments do not verify this rework. diff --git a/examples/workers/agent_tools.py b/examples/workers/agent_tools.py deleted file mode 100644 index 3885abe7..00000000 --- a/examples/workers/agent_tools.py +++ /dev/null @@ -1,50 +0,0 @@ -"""A worker as the model of an `ai.Agent`: the agent's tools reach it by MCP. - -The CLI calls `lookup_order`. The worker hands the call to the agent, the -agent runs the tool, and the CLI gets the result and goes on. - - uv run python examples/workers/agent_tools.py [codex] -""" - -import asyncio -import sys -from collections.abc import Callable - -import ai -from ai import workers - -KINDS: dict[str, Callable[..., workers.Worker]] = { - "codex": workers.Codex, -} - - -@ai.tool -async def lookup_order(order_id: str) -> str: - """Look up the status of an order by its id.""" - return f"order {order_id}: shipped on 2026-11-02" - - -async def main(kind: str) -> None: - agent = ai.Agent(tools=[lookup_order]) - messages = [ - ai.user_message( - "Use the lookup_order tool for order A-17, then tell me its " - "status in one sentence." - ) - ] - async with KINDS[kind]() as worker: - async with agent.run(worker, messages) as run: - async for event in run: - match event: - case ai.events.ToolEnd(): # the agent runs this one - call = event.tool_call - print(f"[agent tool] {call.tool_name} {call.tool_args}") - case ai.events.BuiltinToolEnd(): # the CLI's own tool - print(f"[cli tool] {event.tool_call.tool_name}") - case ai.events.TextDelta(): - print(event.chunk, end="", flush=True) - print() - print([m.role for m in run.messages]) - - -asyncio.run(main(sys.argv[1] if len(sys.argv) > 1 else "codex")) diff --git a/examples/workers/approvals.py b/examples/workers/approvals.py index 348a47b2..044d70f4 100644 --- a/examples/workers/approvals.py +++ b/examples/workers/approvals.py @@ -1,9 +1,10 @@ -"""Approve each of the CLI's own tool calls, as `ai.Agent` tool approvals. +"""Answer CLI approval requests through `ai.Agent` tool approvals. -With `approve=True`, every tool call the CLI makes becomes a `ToolApproval` -hook. Answer it with `ai.resolve_hook`, the way any tool approval is. +With `approve=True`, native approval requests become `ToolApproval` hooks. +Coverage depends on the CLI's policy; this is not a sandbox. Answer each +request with `ai.resolve_hook`, the way any tool approval is. - uv run python examples/workers/approvals.py [codex] + uv run python examples/workers/approvals.py [claude-code|codex|pi] """ import asyncio @@ -14,29 +15,33 @@ from ai import workers KINDS: dict[str, Callable[..., workers.Worker]] = { + "claude-code": workers.ClaudeCode, "codex": workers.Codex, + "pi": workers.Pi, } async def main(kind: str) -> None: messages = [ai.user_message("Create notes.txt containing 'hello'.")] - async with KINDS[kind](approve=True) as worker: - async with ai.Agent().run(worker, messages) as run: - async for event in run: - match event: - case ai.events.PendingHookEvent(hook=hook): - meta = hook.metadata - answer = await asyncio.to_thread( - input, - f"allow {meta['tool']} {meta['kwargs']}? [y/N] ", - ) - granted = answer.strip().lower() == "y" - ai.resolve_hook( - hook, {"granted": granted, "reason": "user said no"} - ) - case ai.events.TextDelta(): - print(event.chunk, end="", flush=True) - print() - - -asyncio.run(main(sys.argv[1] if len(sys.argv) > 1 else "codex")) + async with ( + KINDS[kind](approve=True) as worker, + ai.Agent().run(worker, messages) as run, + ): + async for event in run: + match event: + case ai.events.PendingHookEvent(hook=hook): + meta = hook.metadata + answer = await asyncio.to_thread( + input, + f"allow {meta['tool']} {meta['kwargs']}? [y/N] ", + ) + granted = answer.strip().lower() == "y" + ai.resolve_hook( + hook, {"granted": granted, "reason": "user said no"} + ) + case ai.events.TextDelta(): + print(event.chunk, end="", flush=True) + print() + + +asyncio.run(main(sys.argv[1] if len(sys.argv) > 1 else "claude-code")) diff --git a/examples/workers/claude_code/agent_tools.py b/examples/workers/claude_code/agent_tools.py new file mode 100644 index 00000000..7de0f79f --- /dev/null +++ b/examples/workers/claude_code/agent_tools.py @@ -0,0 +1,46 @@ +"""Claude Code as the model of an `ai.Agent`: the agent's tools reach it by MCP. + +Claude Code calls `lookup_order`. The worker hands the call to the agent, the +agent runs the tool, and Claude Code gets the result and goes on. + + uv run python examples/workers/claude_code/agent_tools.py +""" + +import asyncio + +import ai +from ai import workers + + +@ai.tool +async def lookup_order(order_id: str) -> str: + """Look up the status of an order by its id.""" + return f"order {order_id}: shipped on 2026-11-02" + + +async def main() -> None: + agent = ai.Agent(tools=[lookup_order]) + messages = [ + ai.user_message( + "Use the lookup_order tool for order A-17, then tell me its " + "status in one sentence." + ) + ] + async with ( + workers.ClaudeCode() as worker, + agent.run(worker, messages) as run, + ): + async for event in run: + match event: + case ai.events.ToolEnd(): # the agent runs this one + call = event.tool_call + print(f"[agent tool] {call.tool_name} {call.tool_args}") + case ai.events.BuiltinToolEnd(): # Claude Code's own tool + print(f"[cli tool] {event.tool_call.tool_name}") + case ai.events.TextDelta(): + print(event.chunk, end="", flush=True) + print() + print([m.role for m in run.messages]) + + +asyncio.run(main()) diff --git a/examples/workers/codex/agent_tools.py b/examples/workers/codex/agent_tools.py new file mode 100644 index 00000000..3a781bd9 --- /dev/null +++ b/examples/workers/codex/agent_tools.py @@ -0,0 +1,46 @@ +"""Codex as the model of an `ai.Agent`: the agent's tools reach it by MCP. + +Codex calls `lookup_order`. The worker hands the call to the agent, the +agent runs the tool, and Codex gets the result and goes on. + + uv run python examples/workers/codex/agent_tools.py +""" + +import asyncio + +import ai +from ai import workers + + +@ai.tool +async def lookup_order(order_id: str) -> str: + """Look up the status of an order by its id.""" + return f"order {order_id}: shipped on 2026-11-02" + + +async def main() -> None: + agent = ai.Agent(tools=[lookup_order]) + messages = [ + ai.user_message( + "Use the lookup_order tool for order A-17, then tell me its " + "status in one sentence." + ) + ] + async with ( + workers.Codex() as worker, + agent.run(worker, messages) as run, + ): + async for event in run: + match event: + case ai.events.ToolEnd(): # the agent runs this one + call = event.tool_call + print(f"[agent tool] {call.tool_name} {call.tool_args}") + case ai.events.BuiltinToolEnd(): # Codex's own tool + print(f"[cli tool] {event.tool_call.tool_name}") + case ai.events.TextDelta(): + print(event.chunk, end="", flush=True) + print() + print([m.role for m in run.messages]) + + +asyncio.run(main()) diff --git a/examples/workers/pi/agent_tools.py b/examples/workers/pi/agent_tools.py new file mode 100644 index 00000000..45f3ec5b --- /dev/null +++ b/examples/workers/pi/agent_tools.py @@ -0,0 +1,46 @@ +"""Pi as the model of an `ai.Agent`: the agent's tools reach it by MCP. + +pi calls `lookup_order`. The worker hands the call to the agent, the +agent runs the tool, and pi gets the result and goes on. + + uv run python examples/workers/pi/agent_tools.py +""" + +import asyncio + +import ai +from ai import workers + + +@ai.tool +async def lookup_order(order_id: str) -> str: + """Look up the status of an order by its id.""" + return f"order {order_id}: shipped on 2026-11-02" + + +async def main() -> None: + agent = ai.Agent(tools=[lookup_order]) + messages = [ + ai.user_message( + "Use the lookup_order tool for order A-17, then tell me its " + "status in one sentence." + ) + ] + async with ( + workers.Pi() as worker, + agent.run(worker, messages) as run, + ): + async for event in run: + match event: + case ai.events.ToolEnd(): # the agent runs this one + call = event.tool_call + print(f"[agent tool] {call.tool_name} {call.tool_args}") + case ai.events.BuiltinToolEnd(): # pi's own tool + print(f"[cli tool] {event.tool_call.tool_name}") + case ai.events.TextDelta(): + print(event.chunk, end="", flush=True) + print() + print([m.role for m in run.messages]) + + +asyncio.run(main()) diff --git a/examples/workers/streaming.py b/examples/workers/streaming.py index a5239cd3..feb01d65 100644 --- a/examples/workers/streaming.py +++ b/examples/workers/streaming.py @@ -1,6 +1,6 @@ """A worker where a model goes: stream it, then continue the conversation. -uv run python examples/workers/streaming.py [codex] +uv run python examples/workers/streaming.py [claude-code|codex|pi] """ import asyncio @@ -11,7 +11,9 @@ from ai import workers KINDS: dict[str, Callable[..., workers.Worker]] = { + "claude-code": workers.ClaudeCode, "codex": workers.Codex, + "pi": workers.Pi, } @@ -49,4 +51,4 @@ async def main(kind: str) -> None: print(reply.text) -asyncio.run(main(sys.argv[1] if len(sys.argv) > 1 else "codex")) +asyncio.run(main(sys.argv[1] if len(sys.argv) > 1 else "claude-code")) diff --git a/pyproject.toml b/pyproject.toml index 2bbe0863..a22eab04 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -35,6 +35,7 @@ dependencies = [ [project.optional-dependencies] anthropic = ["anthropic>=0.83.0,<2.0.0"] +claude-code = ["claude-agent-sdk>=0.2.144,<0.3"] mcp = ["mcp>=2.0.0,<3.0.0"] openai = ["openai>=2.34.0,<4.0.0"] otel = [ @@ -69,6 +70,7 @@ bump = true [dependency-groups] dev = [ "anthropic>=0.83.0", + "claude-agent-sdk>=0.2.144,<0.3", "mcp>=2.0.0,<3.0.0", "python-dotenv>=1.2.1", "pytest>=8.0", @@ -82,6 +84,7 @@ dev = [ "vercel-oidc>=0.8.0", "opentelemetry-sdk>=1.43.0", "opentelemetry-exporter-otlp-proto-http>=1.43.0", + "pytest-timeout>=2.3", "typesafe-sdk>=0.7.2", ] @@ -115,6 +118,14 @@ exclude = [ [tool.pytest.ini_options] asyncio_mode = "auto" testpaths = ["tests"] +# Live worker tests drive real agent CLIs, so they are opt-in: +# `uv run pytest -m live tests/workers` (a later -m overrides this one). +addopts = "-m 'not live'" +# A live test drives a real agent; hanging must be a failure. +timeout = 300 +markers = [ + "live: drives a real Claude Code, Codex or Pi (deselect with -m 'not live')", +] filterwarnings = [ "ignore:'asyncio\\.DefaultEventLoopPolicy' is deprecated.*:DeprecationWarning:async_solipsism\\.loop", ] diff --git a/src/ai/agents/agent.py b/src/ai/agents/agent.py index 0b5933bb..3e89a06b 100644 --- a/src/ai/agents/agent.py +++ b/src/ai/agents/agent.py @@ -1041,12 +1041,12 @@ async def _iterate(self) -> AsyncGenerator[events_.ToolCallResult]: def _validate_model(value: Any) -> models.ModelLike: # Another model-like (an ai.workers.Worker) is kept as it is. A dict - # from JSON with a worker's `kind` is a worker; any other is an ai.Model. + # JSON with `worker_class_id` is a worker; any other dict is an ai.Model. if isinstance(value, models.ModelLike) and not isinstance( value, models.Model ): return value - if isinstance(value, dict) and "kind" in value: + if isinstance(value, dict) and "worker_class_id" in value: from .. import workers # noqa: PLC0415 return workers.Worker.model_validate(value) diff --git a/src/ai/agents/hooks.py b/src/ai/agents/hooks.py index 049ac0ae..ec990abe 100644 --- a/src/ai/agents/hooks.py +++ b/src/ai/agents/hooks.py @@ -40,7 +40,7 @@ class HookRegistry: """Holds hook state: live suspensions and pre-registered resolutions. ``_live_hooks``: - Populated by ``hook()`` when it suspends inside a running agent. + Populated by ``hook()`` when it suspends. Maps hook label -> (future, metadata dict, Runtime). Consumed by ``resolve_hook()`` / ``cancel_hook()`` to unblock the awaiting coroutine. Each entry is removed by the suspended hook @@ -154,9 +154,15 @@ async def hook[T: pydantic.BaseModel]( metadata: dict[str, Any] | None = None, tool_call_id: str | None = None, registry: HookRegistry | None = None, + runtime: runtime_.Runtime | None = None, ) -> T: """Create a hook suspension point and await its resolution. + Outside an Agent run, pass an explicit ``registry`` and ``runtime``. + The runtime emits hook events; a Runtime subclass can override + ``put_event()`` to forward them to its own queue. Resolve or cancel + the hook using the same registry. + Args: hook: Unique identifier for this hook instance, or a HookPart whose ``hook_id`` supplies it. @@ -172,9 +178,11 @@ async def hook[T: pydantic.BaseModel]( custom gating wrappers should pass it too. registry: The :class:`HookRegistry` to register the hook in. Defaults to the current registry. + runtime: The Runtime that emits pending, resolved, and cancelled + hook events. Defaults to the current runtime. """ - rt = runtime_.get_runtime() + rt = runtime if runtime is not None else runtime_.get_runtime() registry = _registry(registry) label = _label(hook) hook_metadata = dict(metadata or {}) diff --git a/src/ai/providers/_optional.py b/src/ai/providers/_optional.py index d3f48140..5ee15265 100644 --- a/src/ai/providers/_optional.py +++ b/src/ai/providers/_optional.py @@ -12,17 +12,25 @@ def import_optional_sdk( - module_name: str, *, provider: str, extra: str + module_name: str, + *, + provider: str | None = None, + extra: str, + feature: str | None = None, ) -> ModuleType: - """Import an optional upstream SDK or raise a helpful installation error.""" + """Import an optional upstream SDK or raise a helpful installation error. + + ``feature`` names what needs the SDK when it is not a provider. + """ root_module = module_name.partition(".")[0] + feature = feature or f"the {provider} provider" try: return importlib.import_module(module_name) except ModuleNotFoundError as exc: if exc.name not in {module_name, root_module}: raise raise ai_errors.InstallationError( - f"could not import `{root_module}`, which is required to use the " - f"{provider} provider, you can install it with `pip install " + f"could not import `{root_module}`, which is required to use " + f"{feature}, you can install it with `pip install " f'"ai[{extra}]"` or `uv add "ai[{extra}]"`' ) from exc diff --git a/src/ai/workers/__init__.py b/src/ai/workers/__init__.py index 058a3b95..be01ec18 100644 --- a/src/ai/workers/__init__.py +++ b/src/ai/workers/__init__.py @@ -1,45 +1,76 @@ -"""Coding-agent CLIs as workers. +"""Coding-agent CLI sessions: Claude Code, Codex and Pi. Experimental: not part of the stable API, may change or be removed. -A worker goes where a model goes, and it keeps its conversation:: +Use a worker as a model, continuing from its current message mirror:: import ai from ai import workers - async with workers.Codex(model="gpt-5.5") as worker: + async with workers.ClaudeCode(model_name="sonnet") as worker: async with ai.stream(worker, [ai.user_message("Fix the tests")]) as s: async for event in s: ... + reply = await ai.experimental_generate( + worker, [*worker.messages, ai.user_message("Summarize the fix.")] + ) - # an ai.Agent's tools reach the CLI through MCP - async with ai.Agent(tools=[search_docs]).run(worker, messages) as run: - ... +Or use ``await worker.send(prompt)`` and ``worker.events()`` directly. +``SessionEvent`` includes model events (``StreamStart``/``StreamEnd``), +``UserMessageAccepted`` and ``HookEvent``. The feed spans turns until close; +there is exactly one reader, including ``stream()`` or ``ai.Agent.run()``. +Explicitly close a reader when leaving it early (``contextlib.aclosing``). -The CLI's own tools come back as `ai.events.BuiltinTool*` events. +With ``approve=True``, direct consumers answer ``PendingHookEvent`` outside +Agent using ``ai.resolve_hook(event.hook, {"granted": False}, +registry=worker.hook_registry)``. Bare model streaming cannot deliver these +approvals: use the direct feed or Agent. Python tools run only through +``ai.Agent(tools=[...]).run(worker, messages)`` and reach the CLI via MCP; +CLI-owned tools appear as ``ai.events.BuiltinTool*`` events. -A worker is a pydantic model: `worker.model_dump()` saves the conversation, -`workers.Worker.model_validate(data)` continues it, `worker.model_copy()` is -a new worker on the same settings, and `Codex(session_id=...)` resumes -a conversation the CLI has stored. +``send()`` waits for transport acceptance, not an answer or durable storage. +The reader updates ``messages``; once the turn and reader stop, ``sync()`` +replaces that mirror from the authoritative CLI store (also after TUI use). +``interrupt()`` requests a clean turn end. ``await worker.fork()`` returns +an open native branch with a new session id; close it when done. Copying +preserves the same session id and is not a fork. + +Dump/validate with ``model_dump()`` / ``Worker.model_validate()`` to resume +settings and the mirror; native storage is still required. Migrate old +``kind``/``model`` keys to ``worker_class_id``/``model_name`` and remove the +old ``fork`` field; no legacy aliases exist. ``executable`` remains a string +(PATH command or filesystem path), or None for the CLI default. A mismatched +history raises ``TranscriptMismatchError`` instead of silently reseeding. +Importing history into a fresh worker is lossy, unlike a native fork. + +Concrete classes own private CLI transport hooks; adapter objects are gone. +See WORKERS.md for examples, migration details and protocol limitations. """ -from ._adapters.base import SessionInfo +from ._adapter import SessionInfo from ._errors import ( ExecutableMissingError, NotAuthenticatedError, TranscriptMismatchError, + UnsupportedError, WorkerError, ) -from ._kinds import Codex -from ._worker import Worker +from ._worker import SessionEvent, UserMessageAccepted, Worker +from .claude_code import ClaudeCode +from .codex import Codex +from .pi import Pi __all__ = [ + "ClaudeCode", "Codex", "ExecutableMissingError", "NotAuthenticatedError", + "Pi", + "SessionEvent", "SessionInfo", "TranscriptMismatchError", + "UnsupportedError", + "UserMessageAccepted", "Worker", "WorkerError", ] diff --git a/src/ai/workers/_adapter.py b/src/ai/workers/_adapter.py new file mode 100644 index 00000000..b0a6b153 --- /dev/null +++ b/src/ai/workers/_adapter.py @@ -0,0 +1,69 @@ +"""Shared CLI data and executable probing; no adapter objects.""" + +from __future__ import annotations + +import asyncio +import os +import re +import warnings +from collections.abc import Awaitable, Callable, Mapping +from typing import Any + +import pydantic + +from ..types import messages as messages_ +from . import _errors as errors + +Prompt = list[messages_.TextPart | messages_.FilePart] +Approve = Callable[[str, str, dict[str, Any]], Awaitable[tuple[bool, str]]] + + +class SessionInfo(pydantic.BaseModel): + """A session in a CLI's own store. Timestamps are milliseconds.""" + + session_id: str + title: str | None = None + cwd: str | None = None + created_at: int | None = None + updated_at: int | None = None + + +async def probe( + kind: str, + executable: str, + *, + install: str, + verified: str, + cwd: str, + env: Mapping[str, str], +) -> str: + """Check the CLI and warn if its version is older than tested.""" + try: + proc = await asyncio.create_subprocess_exec( + executable, + "--version", + cwd=cwd, + env={**os.environ, **env}, + stdout=asyncio.subprocess.PIPE, + stderr=asyncio.subprocess.PIPE, + ) + async with asyncio.timeout(60): + stdout, _ = await proc.communicate() + except (OSError, TimeoutError) as exc: + raise errors.ExecutableMissingError(kind, executable, install) from exc + if proc.returncode != 0: + raise errors.ExecutableMissingError(kind, executable, install) + version = (stdout.decode(errors="replace").strip().splitlines() or [""])[0] + have, want = _version(version), _version(verified) + if have is not None and want is not None and have < want: + warnings.warn( + f"{kind} {version} is older than {verified}, the version this " + "SDK was verified with; update it if something misbehaves", + stacklevel=2, + ) + return version + + +def _version(text: str | None) -> tuple[int, ...] | None: + found = re.search(r"\d+(?:\.\d+)+", text or "") + return tuple(int(n) for n in found.group(0).split(".")) if found else None diff --git a/src/ai/workers/_adapters/_handoff.py b/src/ai/workers/_adapters/_handoff.py deleted file mode 100644 index 873a0b6c..00000000 --- a/src/ai/workers/_adapters/_handoff.py +++ /dev/null @@ -1,504 +0,0 @@ -"""Seeding a CLI with a past: one rendering rule, every CLI. - -A worker given `[*past, user_message]` on its first turn starts a new -conversation from `past`. Each CLI stores it natively so the agent truly -has the context, and the rule for what becomes what is the same everywhere: - -- text: verbatim, same role. -- tool calls and results: the NATIVE tool items, original name and - arguments unaltered. Measured: the receiving agent reads them as history - and acts with its own tools; it does not try to call a tool it lacks. - Names are not translated — mapping `Write` to `fileChange` would be the - invented taxonomy this SDK refuses everywhere else. Nor are PATHS: a call - that wrote /Users/x/proj/recipe.txt says so, and that is where it was - written. Across machines the receiver must be told where things are now - (or the workspace copied to the same path) — as any colleague would be. -- reasoning: a user-role handoff note after the turn it belonged to — where - the destination accepts it. Measured: fed back as the agent's OWN thoughts - it is rejected (Claude signs thinking blocks) or silently ignored (codex - accepts a reasoning item and never reads it). As a note, codex uses it. - Claude does NOT accept it in any form: Anthropic's safeguards flag real - model reasoning replayed as user content (`[reasoning_extraction]`) — - hand-written notes passed, genuine Opus thinking was refused. So the - Claude renderer omits reasoning, and the adapter warns with the count, - because dropping context silently is the one thing this SDK never does. - Pi omits it too, for both reasons: pi drops thinking another model wrote, - and pi often runs Claude. -- files: images go to every harness, as the image input each takes (pi - takes bytes, so an image known only by URL becomes a note naming it); - PDFs to Claude as documents. Anything else (a PDF into codex, a text - file) is left out and counted (`unsupported_files`), and the adapter - warns, like it does for reasoning into Claude. -""" - -from __future__ import annotations - -import datetime -import json -import uuid -import warnings -from typing import Any - -from ...types import media -from ...types import messages as messages_ - -NOTE_PREFIX = "[Handoff from a previous session — earlier reasoning: " -AUTHOR = ("api", "provider", "model") -"""What names a reply's author in a pi session: its API and model.""" -SYSTEM_PREFIX = "[Handoff from a previous session — instructions it was given: " - - -def _text(value: Any) -> str: - return value if isinstance(value, str) else json.dumps(value) - - -def _note(reasoning: list[str]) -> str: - return ( - NOTE_PREFIX + " ".join(r.strip() for r in reasoning if r.strip()) + "]" - ) - - -def _image_url(part: messages_.FilePart) -> str: - """Return an http(s) URL as it is, anything else as a data URL.""" - return media.data_to_data_url(part.data, part.media_type) - - -def _source(part: messages_.FilePart) -> dict[str, Any]: - """Return an Anthropic content-block source for a file.""" - if isinstance(part.data, str) and media.is_downloadable_url(part.data): - return {"type": "url", "url": part.data} - return { - "type": "base64", - "media_type": part.media_type, - "data": media.data_to_base64(part.data), - } - - -def harness_view(history: list[messages_.Message]) -> list[messages_.Message]: - """Return a past with the CLI's own tools as ordinary tool calls. - - A worker's messages hold the tools a CLI ran itself as - `BuiltinToolCallPart`/`BuiltinToolReturnPart`, the way a provider's web - search is. A CLI's store holds them as tool calls, each with its result - in a `tool` message after it. The renderers below read that shape. - """ - out: list[messages_.Message] = [] - for message in history: - parts: list[messages_.Part] = [] - results: list[messages_.Part] = [] - first = True - for part in message.parts: - if results and not isinstance( - part, messages_.BuiltinToolReturnPart - ): - # What follows a result comes after it: a new message. - if parts: - out.append(_split(message, parts, first=first)) - first = False - out.append(messages_.Message(role="tool", parts=results)) - parts, results = [], [] - if isinstance(part, messages_.BuiltinToolCallPart): - parts.append( - messages_.ToolCallPart( - tool_call_id=part.tool_call_id, - tool_name=part.tool_name, - tool_args=part.tool_args or "{}", - provider_metadata=part.provider_metadata, - ) - ) - elif isinstance(part, messages_.BuiltinToolReturnPart): - results.append( - messages_.ToolResultPart( - tool_call_id=part.tool_call_id, - tool_name=part.tool_name, - result=part.result, - result_kind="error" if part.is_error else "json", - ) - ) - else: - parts.append(part) - if parts: - out.append(_split(message, parts, first=first)) - if results: - out.append(messages_.Message(role="tool", parts=results)) - return out - - -def _split( - message: messages_.Message, parts: list[messages_.Part], *, first: bool -) -> messages_.Message: - """One piece of a message: the first keeps its id, the rest get new ones.""" - if first: - return message.model_copy(update={"parts": parts}) - return messages_.Message( - role=message.role, - parts=parts, - provider_metadata=message.provider_metadata, - ) - - -def model_view(stored: list[messages_.Message]) -> list[messages_.Message]: - """Return a stored conversation the way a worker shows it. - - The reverse of `harness_view`: the CLI's tool calls become built-in - parts, and each result joins the assistant message of its call. - """ - out: list[messages_.Message] = [] - owner: dict[str, int] = {} # tool_call_id -> index in `out` - for message in stored: - if message.role == "assistant": - parts: list[messages_.Part] = [] - for part in message.parts: - if isinstance(part, messages_.ToolCallPart): - owner[part.tool_call_id] = len(out) - parts.append( - messages_.BuiltinToolCallPart( - tool_call_id=part.tool_call_id, - tool_name=part.tool_name, - tool_args=part.tool_args, - provider_metadata=part.provider_metadata, - ) - ) - else: - parts.append(part) - out.append(message.model_copy(update={"parts": parts})) - elif message.role == "tool": - for result in message.tool_results: - index = owner.get(result.tool_call_id) - if index is None: - continue - target = out[index] - out[index] = target.model_copy( - update={ - "parts": [ - *target.parts, - messages_.BuiltinToolReturnPart( - tool_call_id=result.tool_call_id, - tool_name=result.tool_name - or _name_of(target, result.tool_call_id), - result=result.result, - is_error=result.result_kind == "error", - ), - ] - } - ) - else: - out.append(message) - return out - - -def _name_of(message: messages_.Message, tool_call_id: str) -> str: - return next( - ( - p.tool_name - for p in message.parts - if isinstance(p, messages_.BuiltinToolCallPart) - and p.tool_call_id == tool_call_id - ), - "", - ) - - -def warn_unsupported_files( - messages: list[messages_.Message], kind: str -) -> None: - """Say how many files a history held that `kind` was not given.""" - left = unsupported_files(messages, kind) - if left: - warnings.warn( - f"{left} file(s) in the history were not carried into {kind}: " - + "it takes images" - + (" and PDFs" if kind == "claude-code" else "") - + " from a history. Text, tool calls and images were carried.", - stacklevel=3, - ) - - -def unsupported_files(messages: list[messages_.Message], kind: str) -> int: - """Count files a history holds that `kind` cannot take as input.""" - return sum( - 1 - for m in messages - for p in m.parts - if isinstance(p, messages_.FilePart) - and not p.media_type.startswith("image/") - and not (kind == "claude-code" and p.media_type == "application/pdf") - ) - - -def to_codex_items(messages: list[messages_.Message]) -> list[dict[str, Any]]: - """Responses API items for `thread/inject_items`.""" - items: list[dict[str, Any]] = [] - for m in harness_view(messages): - reasoning: list[str] = [] - for p in m.parts: - if isinstance(p, messages_.TextPart) and p.text.strip(): - ctype = "input_text" if m.role == "user" else "output_text" - items.append( - { - "type": "message", - "role": m.role, - "content": [{"type": ctype, "text": p.text}], - } - ) - elif ( - isinstance(p, messages_.FilePart) - and m.role == "user" - and p.media_type.startswith("image/") - ): - items.append( - { - "type": "message", - "role": "user", - "content": [ - {"type": "input_image", "image_url": _image_url(p)} - ], - } - ) - elif isinstance(p, messages_.ToolCallPart): - items.append( - { - "type": "function_call", - "call_id": p.tool_call_id or p.id, - "name": p.tool_name, - "arguments": p.tool_args or "{}", - } - ) - elif isinstance(p, messages_.ToolResultPart): - items.append( - { - "type": "function_call_output", - "call_id": p.tool_call_id, - "output": _text(p.result), - } - ) - elif isinstance(p, messages_.ReasoningPart) and p.text.strip(): - reasoning.append(p.text) - if reasoning: - items.append( - { - "type": "message", - "role": "user", - "content": [ - {"type": "input_text", "text": _note(reasoning)} - ], - } - ) - return items - - -def reasoning_count(messages: list[messages_.Message]) -> int: - return sum( - 1 - for m in messages - for p in m.parts - if isinstance(p, messages_.ReasoningPart) and p.text.strip() - ) - - -def to_claude_records( - messages: list[messages_.Message], session_id: str, cwd: str -) -> list[dict[str, Any]]: - """Build Claude Code transcript records for the CLI's store. - - Chained by parentUuid. - - Reasoning parts are omitted: see the module docstring. Callers report - the omission — `reasoning_count()` says how many. - """ - records: list[dict[str, Any]] = [] - parent: str | None = None - - def add(role: str, content: Any) -> None: - nonlocal parent - uid = str(uuid.uuid4()) - ts = ( - datetime.datetime.now(datetime.UTC) - .isoformat() - .replace("+00:00", "Z") - ) - records.append( - { - "parentUuid": parent, - "isSidechain": False, - "type": role, - "message": {"role": role, "content": content}, - "uuid": uid, - "timestamp": ts, - "sessionId": session_id, - "cwd": cwd, - } - ) - parent = uid - - for m in harness_view(messages): - blocks: list[dict[str, Any]] = [] - for p in m.parts: - if isinstance(p, messages_.TextPart) and p.text.strip(): - blocks.append({"type": "text", "text": p.text}) - elif isinstance(p, messages_.FilePart) and m.role == "user": - if p.media_type.startswith("image/"): - blocks.append({"type": "image", "source": _source(p)}) - elif p.media_type == "application/pdf": - blocks.append({"type": "document", "source": _source(p)}) - elif isinstance(p, messages_.ToolCallPart): - try: - args = json.loads(p.tool_args) if p.tool_args else {} - except json.JSONDecodeError: - args = {"raw": p.tool_args} - blocks.append( - { - "type": "tool_use", - "id": p.tool_call_id or p.id, - "name": p.tool_name, - "input": args, - } - ) - elif isinstance(p, messages_.ToolResultPart): - blocks.append( - { - "type": "tool_result", - "tool_use_id": p.tool_call_id, - "content": _text(p.result), - **( - {"is_error": True} - if p.result_kind == "error" - else {} - ), - } - ) - # ReasoningPart: omitted on purpose — Anthropic's safeguards - # refuse replayed reasoning. The adapter warns with the count. - if blocks: - # Tool results live in role="tool" messages in the IR; on disk - # the CLI keeps them as user records with tool_result blocks. - add("user" if m.role in ("user", "tool") else "assistant", blocks) - return records - - -def to_pi_messages( - messages: list[messages_.Message], *, timestamp: int -) -> list[dict[str, Any]]: - """Build pi `AgentMessage`s for a session file. - - Assistant messages pi wrote keep their author (`provider_metadata["pi"]`): - pi restores a session's model from it. Any other is attributed to a - model pi does not run (`ai-python/handoff`), so pi treats it as another - model's — it keeps its text and tool calls and normalizes the call ids - for its own provider. Consecutive assistant messages are merged, the way one - model response holds text and calls together. Reasoning is omitted: see - the module docstring. - """ - out: list[dict[str, Any]] = [] - usage = { - "input": 0, - "output": 0, - "cacheRead": 0, - "cacheWrite": 0, - "totalTokens": 0, - "cost": { - "input": 0, - "output": 0, - "cacheRead": 0, - "cacheWrite": 0, - "total": 0, - }, - } - for m in harness_view(messages): - if m.role == "tool": - for p in m.parts: - if isinstance(p, messages_.ToolResultPart): - out.append( - { - "role": "toolResult", - "toolCallId": p.tool_call_id, - "toolName": p.tool_name, - "content": [ - {"type": "text", "text": _text(p.result)} - ], - "isError": p.result_kind == "error", - "timestamp": timestamp, - } - ) - continue - blocks: list[dict[str, Any]] = [] - for p in m.parts: - if isinstance(p, messages_.TextPart) and p.text.strip(): - blocks.append({"type": "text", "text": p.text}) - elif ( - isinstance(p, messages_.FilePart) - and m.role == "user" - and p.media_type.startswith("image/") - ): - if isinstance(p.data, str) and media.is_downloadable_url( - p.data - ): - blocks.append( - {"type": "text", "text": f"[image: {p.data}]"} - ) - else: - blocks.append( - { - "type": "image", - "data": media.data_to_base64(p.data), - "mimeType": p.media_type, - } - ) - elif ( - isinstance(p, messages_.ToolCallPart) and m.role == "assistant" - ): - try: - args = json.loads(p.tool_args) if p.tool_args else {} - except json.JSONDecodeError: - args = {"raw": p.tool_args} - blocks.append( - { - "type": "toolCall", - "id": p.tool_call_id or p.id, - "name": p.tool_name, - "arguments": args if isinstance(args, dict) else {}, - } - ) - if not blocks: - continue - if m.role == "system": - # Measured (pi 1.3.0): a system message in a session file is - # pi's own prompt state, and replaying one REPLACED pi's system - # prompt and its tools. So instructions travel as what they are - # to the agent — the caller's words — never as its own output. - text = " ".join(b["text"] for b in blocks if b["type"] == "text") - blocks = [{"type": "text", "text": SYSTEM_PREFIX + text + "]"}] - if m.role in ("user", "system"): - out.append( - {"role": "user", "content": blocks, "timestamp": timestamp} - ) - continue - if out and out[-1]["role"] == "assistant": - out[-1]["content"] += blocks - else: - # A reply pi wrote keeps its author: pi restores a session's model - # from its last reply's, and a model it does not know (ours) - # put the conversation on pi's default one (measured). - author = (m.provider_metadata or {}).get("pi") or {} - known = all(isinstance(author.get(k), str) for k in AUTHOR) - out.append( - { - "role": "assistant", - "content": blocks, - **( - {k: author[k] for k in AUTHOR} - if known - else { - "api": "ai-python", - "provider": "ai-python", - "model": "handoff", - } - ), - "usage": usage, - "stopReason": "stop", - "timestamp": timestamp, - } - ) - if any(b["type"] == "toolCall" for b in out[-1]["content"]): - out[-1]["stopReason"] = "toolUse" - return out diff --git a/src/ai/workers/_adapters/base.py b/src/ai/workers/_adapters/base.py deleted file mode 100644 index 10d09016..00000000 --- a/src/ai/workers/_adapters/base.py +++ /dev/null @@ -1,333 +0,0 @@ -"""What every adapter shares: its protocol, local processes, prompt files. - -An adapter drives ONE conversation with one CLI. It speaks the model view -both ways: `turn()` yields the events of one assistant message, with the -CLI's own tools as `BuiltinTool*` events, and ends with a `StreamEnd`; a -history it reads or is seeded with is a plain `list[Message]`. -""" - -from __future__ import annotations - -import asyncio -import base64 -import contextlib -import os -import re -import warnings -from collections.abc import ( - AsyncIterator, - Awaitable, - Callable, - Mapping, - Sequence, -) -from typing import Any, Protocol - -import pydantic - -from ...models.core.helpers import files -from ...types import events, media -from ...types import messages as messages_ -from .. import _errors as errors - -Prompt = list[messages_.TextPart | messages_.FilePart] - -Approve = Callable[[str, str, dict[str, Any]], Awaitable[tuple[bool, str]]] -"""`approve(tool_call_id, tool_name, tool_input)` returns `(granted, reason)`. - -Never raises: the worker answers a failure with a denial.""" - -LINE_LIMIT = 256 * 1024 * 1024 -"""Longest line a CLI may write. The protocols are JSON lines, and one line -can be megabytes (a codex `thread/read` of a long thread). With asyncio's -default (64 KiB) such a line failed as if the CLI had crashed.""" - -TERM_GRACE = 3.0 -"""Seconds a CLI gets to exit after SIGTERM, before SIGKILL.""" - - -class SessionInfo(pydantic.BaseModel): - """A conversation in a CLI's own store.""" - - session_id: str - title: str | None = None - cwd: str | None = None - created_at: int | None = None - """Milliseconds since the epoch, when the CLI records it.""" - updated_at: int | None = None - - -class Adapter(Protocol): - version: str | None - """What ` --version` printed, once started.""" - - async def start(self) -> None: - """Check the CLI runs, and start what it needs (codex: a server).""" - ... - - async def close(self) -> None: ... - - async def open( - self, - *, - session_id: str | None, - fork: bool, - seed: list[messages_.Message] | None, - instructions: str | None, - ) -> str: - """Open the conversation and return its session id. - - A new one (seeded with a past when `seed` is given), the stored one - `session_id` names, or a native fork of it. - """ - ... - - def turn(self, prompt: Prompt) -> AsyncIterator[events.Event]: - """Send a prompt; yield one assistant message, ending in StreamEnd.""" - ... - - async def steer(self, text: str) -> None: - """Send guidance to the turn that runs now.""" - ... - - async def interrupt(self) -> None: - """End the running turn. The CLI keeps its transcript.""" - ... - - async def history(self, session_id: str) -> list[messages_.Message]: - """Read a stored conversation.""" - ... - - async def list_sessions(self) -> list[SessionInfo]: ... - - def tui_command( - self, session_id: str | None - ) -> tuple[list[str], dict[str, str], str | None]: - """Return the CLI's interactive command, its env, and its session id. - - The session id is minted here for a new conversation when the CLI - lets us choose it, else None. - """ - ... - - -# -- local processes ----------------------------------------------------------- - - -class Process: - """A CLI started by `spawn`: JSON lines on stdin and stdout.""" - - def __init__(self, proc: asyncio.subprocess.Process) -> None: - self._proc = proc - - @property - def pid(self) -> int: - return self._proc.pid - - async def write(self, data: str) -> None: - assert self._proc.stdin is not None - self._proc.stdin.write(data.encode()) - await self._proc.stdin.drain() - - async def readline(self) -> str: - assert self._proc.stdout is not None - return (await self._proc.stdout.readline()).decode() - - async def read_stderr(self) -> str: - if self._proc.stderr is None: - return "" - return (await self._proc.stderr.read()).decode(errors="replace") - - async def wait(self) -> int: - return await self._proc.wait() - - async def terminate(self) -> None: - """Stop the process group: SIGTERM, then SIGKILL.""" - if self._proc.returncode is not None: - return - with contextlib.suppress(ProcessLookupError): - os.killpg(os.getpgid(self._proc.pid), 15) - try: - async with asyncio.timeout(TERM_GRACE): - await self._proc.wait() - except TimeoutError: - with contextlib.suppress(ProcessLookupError): - os.killpg(os.getpgid(self._proc.pid), 9) - with contextlib.suppress(Exception): - await self._proc.wait() - - async def death_note(self) -> str: - """Say how the process ended, and its last words.""" - code: int | None = None - tail = "" - with contextlib.suppress(Exception): - async with asyncio.timeout(2): - code = await self.wait() - with contextlib.suppress(Exception): - async with asyncio.timeout(2): - tail = (await self.read_stderr()).strip() - how = f"exit code {code}" if code is not None else "exited" - if code in (137, -9): - how += " (SIGKILL, typically the kernel's OOM killer)" - return f"{how}; stderr: {tail[-800:]}" if tail else f"{how}; no stderr" - - -async def spawn( - argv: Sequence[str], *, cwd: str, env: Mapping[str, str] -) -> Process: - """Start a CLI in its own process group, with pipes for stdio.""" - try: - proc = await asyncio.create_subprocess_exec( - *argv, - cwd=cwd, - env={**os.environ, **env}, - stdin=asyncio.subprocess.PIPE, - stdout=asyncio.subprocess.PIPE, - stderr=asyncio.subprocess.PIPE, - # Own the whole tree, so teardown reaches grandchildren too. - start_new_session=True, - limit=LINE_LIMIT, - ) - except OSError as exc: - raise errors.WorkerError(f"cannot start {argv[0]!r}: {exc}") from exc - return Process(proc) - - -async def probe( - kind: str, - executable: str, - *, - install: str, - verified: str, - cwd: str, - env: Mapping[str, str], -) -> str: - """Check that the CLI runs, and return its version. - - Warns when it is older than the version the adapter was verified with: - the adapters lean on CLI behavior that is measured, not documented. - """ - try: - proc = await asyncio.create_subprocess_exec( - executable, - "--version", - cwd=cwd, - env={**os.environ, **env}, - stdout=asyncio.subprocess.PIPE, - stderr=asyncio.subprocess.PIPE, - ) - async with asyncio.timeout(60): - stdout, _ = await proc.communicate() - except (OSError, TimeoutError) as exc: - raise errors.ExecutableMissingError(kind, executable, install) from exc - if proc.returncode != 0: - raise errors.ExecutableMissingError(kind, executable, install) - version = (stdout.decode(errors="replace").strip().splitlines() or [""])[0] - have, want = _version(version), _version(verified) - if have is not None and want is not None and have < want: - warnings.warn( - f"{kind} {version} is older than {verified}, the version this " - "SDK was verified with; update it if something misbehaves", - stacklevel=2, - ) - return version - - -def _version(text: str | None) -> tuple[int, ...] | None: - found = re.search(r"\d+(?:\.\d+)+", text or "") - return tuple(int(n) for n in found.group(0).split(".")) if found else None - - -# -- files in a prompt --------------------------------------------------------- -# -# Files are turned into bytes HERE: a URL is downloaded with the SDK's own -# SSRF-checked downloader, not handed to the CLI. Measured: Claude Code drops -# an image given by URL without a word. - - -async def data(part: messages_.FilePart) -> bytes: - """Return a file's bytes, downloading a URL first.""" - if isinstance(part.data, bytes): - return part.data - if media.is_downloadable_url(part.data): - body, _ = await files.download(part.data) - return body - return base64.b64decode(media.data_to_base64(part.data)) - - -async def as_text(part: messages_.FilePart) -> str: - """Return a text file as text a CLI reads inline, named if it has one.""" - body = (await data(part)).decode("utf-8", errors="replace") - name = part.filename or "attached file" - return f"\n{body}\n" - - -def check_files(prompt: Prompt, kind: str, accepts: Sequence[str]) -> None: - """Refuse a file the CLI cannot take, before anything runs. - - Text files (`text/*`) go everywhere, as text. `accepts` lists the other - media type prefixes the CLI takes. - """ - for part in prompt: - if isinstance(part, messages_.FilePart) and not any( - part.media_type.startswith(p) for p in ("text/", *accepts) - ): - raise errors.WorkerError( - f"{kind} does not take {part.media_type} files" - ) - - -def text_of(prompt: Prompt) -> str: - return "\n\n".join( - p.text for p in prompt if isinstance(p, messages_.TextPart) - ) - - -def builtin_call( - tool_call_id: str, - tool_name: str, - tool_args: str, - *, - started: set[str], -) -> list[events.Event]: - """Return the events of one finished CLI tool call. - - `started` holds the calls whose start was already sent: the start is - sent here otherwise, because the hydrator only completes a call it saw - start. The arguments travel as a delta: the hydrator builds a call's - arguments only from its deltas. - """ - out: list[events.Event] = [] - if tool_call_id not in started: - started.add(tool_call_id) - out.append( - events.BuiltinToolStart( - tool_call_id=tool_call_id, tool_name=tool_name - ) - ) - return [ - *out, - events.BuiltinToolDelta(tool_call_id=tool_call_id, chunk=tool_args), - events.BuiltinToolEnd( - tool_call_id=tool_call_id, - tool_call=messages_.BuiltinToolCallPart( - tool_call_id=tool_call_id, - tool_name=tool_name, - tool_args=tool_args, - ), - ), - ] - - -def builtin_result( - tool_call_id: str, tool_name: str, result: Any, *, is_error: bool -) -> events.BuiltinToolResult: - return events.BuiltinToolResult( - tool_call_id=tool_call_id, - result=messages_.BuiltinToolReturnPart( - tool_call_id=tool_call_id, - tool_name=tool_name, - result=result, - is_error=is_error, - ), - ) diff --git a/src/ai/workers/_bridge.py b/src/ai/workers/_bridge.py index f32f5a59..ef0bb5b8 100644 --- a/src/ai/workers/_bridge.py +++ b/src/ai/workers/_bridge.py @@ -26,14 +26,14 @@ if TYPE_CHECKING: from ..types import tools as tools_ +# The MCP server name the CLI sees. Claude Code calls a tool +# `mcp__ai_sdk__`. SERVER_NAME = "ai_sdk" -"""The MCP server name the CLI sees. Claude Code calls a tool -`mcp__ai_sdk__`.""" PROTOCOL_VERSION = "2025-06-18" +# `on_call(name, arguments)` returns `(text, is_error)`. OnCall = Callable[[str, dict[str, Any]], Awaitable[tuple[str, bool]]] -"""`on_call(name, arguments)` returns `(text, is_error)`.""" class Bridge: diff --git a/src/ai/workers/_convert.py b/src/ai/workers/_convert.py new file mode 100644 index 00000000..62e6f88b --- /dev/null +++ b/src/ai/workers/_convert.py @@ -0,0 +1,116 @@ +"""What every adapter converts the same way. + +Prompt files go in as bytes or text. The CLI's own tool calls come out as +`BuiltinTool*` events. +""" + +from __future__ import annotations + +import base64 +from collections.abc import Sequence +from typing import Any + +from ..models.core.helpers import files +from ..types import events, media +from ..types import messages as messages_ +from . import _adapter +from . import _errors as errors + +# -- files in a prompt --------------------------------------------------------- +# +# Files are turned into bytes HERE: a URL is downloaded with the SDK's own +# SSRF-checked downloader, not handed to the CLI. Measured: Claude Code drops +# an image given by URL without a word. + + +async def data(part: messages_.FilePart) -> bytes: + """Return a file's bytes, downloading a URL first.""" + if isinstance(part.data, bytes): + return part.data + if media.is_downloadable_url(part.data): + body, _ = await files.download(part.data) + return body + return base64.b64decode(media.data_to_base64(part.data)) + + +async def as_text(part: messages_.FilePart) -> str: + """Return a text file as text a CLI reads inline, named if it has one.""" + body = (await data(part)).decode("utf-8", errors="replace") + name = part.filename or "attached file" + return f"\n{body}\n" + + +def check_files( + prompt: _adapter.Prompt, kind: str, accepts: Sequence[str] +) -> None: + """Refuse a file the CLI cannot take, before anything runs. + + Text files (`text/*`) go everywhere, as text. `accepts` lists the other + media type prefixes the CLI takes. + """ + for part in prompt: + if isinstance(part, messages_.FilePart) and not any( + part.media_type.startswith(p) for p in ("text/", *accepts) + ): + raise errors.WorkerError( + f"{kind} does not take {part.media_type} files" + ) + + +def text_of(prompt: _adapter.Prompt) -> str: + return "\n\n".join( + p.text for p in prompt if isinstance(p, messages_.TextPart) + ) + + +# -- the CLI's own tools as events -------------------------------------------- + + +def builtin_call( + tool_call_id: str, + tool_name: str, + tool_args: str, + *, + started: set[str], +) -> list[events.Event]: + """Return the events of one finished CLI tool call. + + `started` holds the calls whose start was already sent: the start is + sent here otherwise, because the hydrator only completes a call it saw + start. The arguments travel as a delta: the hydrator builds a call's + arguments only from its deltas. + """ + out: list[events.Event] = [] + if tool_call_id not in started: + started.add(tool_call_id) + out.append( + events.BuiltinToolStart( + tool_call_id=tool_call_id, tool_name=tool_name + ) + ) + return [ + *out, + events.BuiltinToolDelta(tool_call_id=tool_call_id, chunk=tool_args), + events.BuiltinToolEnd( + tool_call_id=tool_call_id, + tool_call=messages_.BuiltinToolCallPart( + tool_call_id=tool_call_id, + tool_name=tool_name, + tool_args=tool_args, + ), + ), + ] + + +def builtin_result( + tool_call_id: str, tool_name: str, result: Any, *, is_error: bool +) -> events.BuiltinToolResult: + return events.BuiltinToolResult( + tool_call_id=tool_call_id, + result=messages_.BuiltinToolReturnPart( + tool_call_id=tool_call_id, + tool_name=tool_name, + result=result, + is_error=is_error, + ), + ) diff --git a/src/ai/workers/_errors.py b/src/ai/workers/_errors.py index 21baddee..0b57650e 100644 --- a/src/ai/workers/_errors.py +++ b/src/ai/workers/_errors.py @@ -13,6 +13,10 @@ class WorkerError(errors.AIError): """A worker or its CLI failed.""" +class UnsupportedError(WorkerError): + """The CLI does not support the requested operation.""" + + class ExecutableMissingError(WorkerError): """The CLI is not installed, or `executable=` does not run.""" diff --git a/src/ai/workers/_handoff.py b/src/ai/workers/_handoff.py new file mode 100644 index 00000000..36039d87 --- /dev/null +++ b/src/ai/workers/_handoff.py @@ -0,0 +1,81 @@ +"""Seeding a CLI with a past: one rendering rule, every CLI. + +A worker given `[*past, user_message]` on its first turn starts a new +conversation from `past`. Each CLI stores it natively so the agent truly +has the context, and the rule for what becomes what is the same everywhere: + +- text: verbatim, same role. +- tool calls and results: the NATIVE tool items, original name and + arguments unaltered. Measured: the receiving agent reads them as history + and acts with its own tools; it does not try to call a tool it lacks. + Names are not translated — mapping `Write` to `fileChange` would be the + invented taxonomy this SDK refuses everywhere else. Nor are PATHS: a call + that wrote /Users/x/proj/recipe.txt says so, and that is where it was + written. Across machines the receiver must be told where things are now + (or the workspace copied to the same path) — as any colleague would be. +- reasoning: a user-role handoff note after the turn it belonged to — where + the destination accepts it. Measured: fed back as the agent's OWN thoughts + it is rejected (Claude signs thinking blocks) or silently ignored (codex + accepts a reasoning item and never reads it). As a note, codex uses it. + Claude does NOT accept it in any form: Anthropic's safeguards flag real + model reasoning replayed as user content (`[reasoning_extraction]`) — + hand-written notes passed, genuine Opus thinking was refused. So the + Claude renderer omits reasoning, and the worker warns with the count, + because dropping context silently is the one thing this SDK never does. + Pi omits it too, for both reasons: pi drops thinking another model wrote, + and pi often runs Claude. +- files: images go to every harness, as the image input each takes (pi + takes bytes, so an image known only by URL becomes a note naming it); + PDFs to Claude as documents. Anything else (a PDF into codex, a text + file) is left out and counted (`unsupported_files`), and the worker + warns, like it does for reasoning into Claude. +""" + +from __future__ import annotations + +import json +import warnings +from typing import Any + +from ..types import messages as messages_ + + +def result_text(value: Any) -> str: + """Return a tool result as the text a CLI's store holds.""" + return value if isinstance(value, str) else json.dumps(value) + + +def warn_unsupported_files( + messages: list[messages_.Message], kind: str +) -> None: + """Say how many files a history held that `kind` was not given.""" + left = unsupported_files(messages, kind) + if left: + warnings.warn( + f"{left} file(s) in the history were not carried into {kind}: " + + "it takes images" + + (" and PDFs" if kind == "claude-code" else "") + + " from a history. Text, tool calls and images were carried.", + stacklevel=3, + ) + + +def unsupported_files(messages: list[messages_.Message], kind: str) -> int: + """Count files a history holds that `kind` cannot take as input.""" + return sum( + 1 + for m in messages + for p in m.parts + if isinstance(p, messages_.FilePart) + and not p.media_type.startswith("image/") + and not (kind == "claude-code" and p.media_type == "application/pdf") + ) + + +def reasoning_count(messages: list[messages_.Message]) -> int: + return sum( + 1 + for m in messages + for p in m.parts + if isinstance(p, messages_.ReasoningPart) and p.text.strip() + ) diff --git a/src/ai/workers/_kinds.py b/src/ai/workers/_kinds.py deleted file mode 100644 index 69285dc0..00000000 --- a/src/ai/workers/_kinds.py +++ /dev/null @@ -1,57 +0,0 @@ -"""The workers, one per CLI. - -Each adds its CLI's own options to `Worker` and builds its adapter. -""" - -from __future__ import annotations - -from typing import Any, Literal - -import pydantic - -from . import _bridge, _worker -from ._adapters import base, codex - - -class Codex(_worker.Worker): - """Codex, over `codex app-server`. - - `sandbox` is Codex's own sandbox mode: `"read-only"`, - `"workspace-write"` or `"danger-full-access"` (the default). `config` - takes Codex `-c` overrides. - """ - - kind: Literal["codex"] = "codex" - sandbox: ( - Literal["read-only", "workspace-write", "danger-full-access"] | None - ) = None - config: dict[str, Any] = pydantic.Field(default_factory=dict) - - def _make_adapter( - self, - mcp_servers: dict[str, dict[str, Any]], - approve: base.Approve | None, - ) -> base.Adapter: - config = dict(self.config) - if self.effort is not None: - config.setdefault( - "model_reasoning_effort", - "xhigh" if self.effort == "max" else self.effort, - ) - if _bridge.SERVER_NAME in mcp_servers: - # Codex's default wait for an MCP tool (60s) is too short for a - # tool an `ai.Agent` runs, maybe after an approval. - config.setdefault( - f"mcp_servers.{_bridge.SERVER_NAME}.tool_timeout_sec", - 24 * 3600, - ) - return codex.CodexAdapter( - cwd=self.cwd, - env=dict(self.env), - executable=self.executable or "codex", - model=self.model, - mcp_servers=dict(mcp_servers), - approve=approve, - sandbox=self.sandbox, - config=config, - ) diff --git a/src/ai/workers/_worker.py b/src/ai/workers/_worker.py index 89aa3994..60cc22eb 100644 --- a/src/ai/workers/_worker.py +++ b/src/ai/workers/_worker.py @@ -1,32 +1,18 @@ -"""`ai.workers.Worker`: a coding-agent CLI that goes where a model goes. - -A worker is ONE conversation with one coding-agent CLI, such as Codex. It is -a pydantic model: its fields are its settings, the CLI's `session_id` and -the conversation so far (`messages`). Dump it, store it, and validate it -again later; it continues the same conversation. - -It follows the model protocol: `stream(messages, tools=, output_type=)` -yields the events of one assistant message, so `ai.stream`, -`ai.experimental_generate` and `ai.Agent.run` take a worker where they take -a model. The CLI runs its own loop and its own tools; those come back as -`BuiltinTool*` events, so an `ai.Agent` does not run them again. The tools -of an `ai.Agent` reach the CLI through the MCP bridge (see `_bridge`) and -come back as normal tool calls, for the agent to run. - -A worker has state, a model does not. `stream()` still receives the whole -conversation on every call. The worker compares it with `messages` and -sends the CLI only what is new (see `_plan`). +"""One serializable CLI session, with direct control and the model protocol. + +The CLI owns the transcript. Input and output are separate: ``send`` accepts +input, and one reader consumes ``events`` across turns. ``stream`` uses those +same primitives to expose one assistant message to the model API. """ from __future__ import annotations import asyncio import contextlib -import contextvars import dataclasses import json import os -from collections.abc import AsyncGenerator, Sequence +from collections.abc import AsyncGenerator, AsyncIterator, Sequence from typing import Any, ClassVar, Literal, Self import pydantic @@ -38,29 +24,34 @@ from ..types import messages as messages_ from ..types import tools as tools_ from ..types import usage as usage_ -from . import _bridge +from . import _adapter, _bridge from . import _errors as errors -from ._adapters import base Effort = Literal["low", "medium", "high", "max"] - BATCH_WINDOW = 0.05 -"""Seconds to wait for more bridge calls before handing a batch to the -caller. A CLI that calls tools in parallel sends them close together.""" - OUTPUT_RETRIES = 2 -"""How many times to ask again for output that does not validate.""" - OUTPUT_INSTRUCTION = ( "\n\nRespond with ONLY a JSON value matching this schema, " "no prose, no code fences:\n" ) +class UserMessageAccepted(events_.BaseEvent): + """The transport accepted input. This is not a model response event. + + CLI protocols differ: Claude Code confirms the input write, while Codex + and Pi acknowledge an RPC. ``sync`` reads the authoritative stored text. + """ + + kind: Literal["user_message_accepted"] = "user_message_accepted" + message: messages_.Message + + +SessionEvent = events_.Event | events_.HookEvent | UserMessageAccepted + + @dataclasses.dataclass class _Call: - """A call from the CLI to an `ai` tool, through the bridge.""" - tool_call_id: str name: str arguments: dict[str, Any] @@ -73,212 +64,375 @@ class _Failed: @dataclasses.dataclass -class _Plan: - """What one `stream()` call must do, from the messages it was given.""" +class _Accepted: + messages: list[messages_.Message] + +@dataclasses.dataclass +class _Plan: seed: list[messages_.Message] = dataclasses.field(default_factory=list) instructions: str | None = None results: list[messages_.ToolResultPart] = dataclasses.field( default_factory=list ) system: list[str] = dataclasses.field(default_factory=list) - """System text that arrived after the conversation began.""" - prompt: list[messages_.TextPart | messages_.FilePart] = dataclasses.field( - default_factory=list - ) + prompt: _adapter.Prompt = dataclasses.field(default_factory=list) transcript: list[messages_.Message] = dataclasses.field( default_factory=list ) - """The transcript once this call succeeds, before its answer.""" + + +class _HookRuntime(runtime_.Runtime): + """Route hooks into the same session feed as CLI output.""" + + def __init__(self, queue: asyncio.Queue[Any]) -> None: + super().__init__() + self.queue = queue + + async def put_event(self, event: events_.AgentEvent) -> None: + self.queue.put_nowait(event) @dataclasses.dataclass class _Runtime: - """What lives only while a worker is open. Never copied, never dumped.""" - - adapter: base.Adapter bridge: _bridge.Bridge - lock: asyncio.Lock = dataclasses.field(default_factory=asyncio.Lock) + queue: asyncio.Queue[Any] = dataclasses.field(default_factory=asyncio.Queue) + send_lock: asyncio.Lock = dataclasses.field(default_factory=asyncio.Lock) in_session: bool = False - # The running turn: its pump task and the queue it fills. - queue: asyncio.Queue[Any] | None = None + closed: bool = False + reader: bool = False + stream_owner: asyncio.Task[Any] | None = None + model_ready: asyncio.Event = dataclasses.field( + default_factory=asyncio.Event + ) pump: asyncio.Task[None] | None = None - # Bridge calls handed to the caller, waiting for their results. pending: dict[str, _Call] = dataclasses.field(default_factory=dict) - # CLI tool ids that are bridge calls, hidden from the stream. hidden: set[str] = dataclasses.field(default_factory=set) - # The context of the latest `stream()` call: approvals ask in it. - context: contextvars.Context | None = None + submission: list[messages_.Message] | None = None + registry: hooks.HookRegistry = dataclasses.field( + default_factory=hooks.HookRegistry + ) + approvals: set[asyncio.Task[Any]] = dataclasses.field(default_factory=set) class Worker(pydantic.BaseModel): - """Base class of the workers, such as `Codex`. + """Base of ClaudeCode, Codex and Pi. One object represents one session. - `Worker.model_validate(data)` builds the kind that `data["kind"]` names. + Dump and validate to resume a session. Use ``await worker.fork()`` to + create an independent native session; copying is not a fork. """ - kind: str - model: str | None = None - """The CLI's model. None: the CLI's own default.""" + model_config = pydantic.ConfigDict(extra="forbid") + + worker_class_id: str + model_name: str | None = None # None selects the CLI default. cwd: str = pydantic.Field(default_factory=os.getcwd) - """Where the CLI runs and keeps its sessions.""" - env: dict[str, str] = {} - """Added to the CLI's environment: keys, base URLs, config dirs.""" - executable: str | None = None + env: dict[str, str] = pydantic.Field(default_factory=dict) + executable: str | None = None # A PATH command or a filesystem path. effort: Effort | None = None - mcp_servers: dict[str, dict[str, Any]] = {} - """MCP servers for the CLI. - - `{"name": {"command": ..., "args": [...]}}` or `{"name": {"url": ...}}`. - """ - approve: bool = False - """Ask before each of the CLI's own tool calls, through `ai.hook`. - - False: the CLI's own permission settings decide (`allowed_tools`, - Codex's `sandbox`). True: each call becomes a `ToolApproval` hook, which - `ai.resolve_hook` and UIs answer as they answer any tool approval. Needs - an `ai.Agent.run()`, where hooks live. - """ + mcp_servers: dict[str, dict[str, Any]] = pydantic.Field( + default_factory=dict + ) + approve: bool = False # ToolApproval hooks, also available outside Agent. session_id: str | None = None - """The CLI's own id for the conversation. Set it to resume one.""" - fork: bool = False - """With `session_id`: fork that conversation natively on first use.""" - messages: list[messages_.Message] = [] - """The conversation so far. Send it back with the next user message.""" + messages: list[messages_.Message] = pydantic.Field(default_factory=list) - _kinds: ClassVar[dict[str, type[Worker]]] = {} + _classes: ClassVar[dict[str, type[Worker]]] = {} _runtime: _Runtime | None = pydantic.PrivateAttr(default=None) + _cli_version: str | None = pydantic.PrivateAttr(default=None) + _open_lock: asyncio.Lock = pydantic.PrivateAttr( + default_factory=asyncio.Lock + ) @classmethod def __pydantic_init_subclass__(cls, **kwargs: Any) -> None: # noqa: PLW3201 super().__pydantic_init_subclass__(**kwargs) - kind = cls.model_fields["kind"].default - if isinstance(kind, str): - Worker._kinds[kind] = cls + name = cls.model_fields["worker_class_id"].default + if isinstance(name, str): + Worker._classes[name] = cls @pydantic.model_validator(mode="wrap") @classmethod - def _of_kind( + def _of_class( cls, data: Any, handler: pydantic.ValidatorFunctionWrapHandler ) -> Any: if cls is Worker and isinstance(data, dict): - kind = Worker._kinds.get(str(data.get("kind"))) - if kind is None: - raise ValueError(f"no worker of kind {data.get('kind')!r}") - return kind.model_validate(data) + worker_class = Worker._classes.get(str(data.get("worker_class_id"))) + if worker_class is None: + raise ValueError( + f"unknown worker class {data.get('worker_class_id')!r}" + ) + return worker_class.model_validate(data) return handler(data) def __copy__(self) -> Self: - # A copy is a new worker: it opens a CLI of its own. - copied = super().__copy__() - copied._runtime = None - return copied + # Revalidation resets ALL private transport state, not just the base. + return type(self).model_validate(self.model_dump()) def __deepcopy__(self, memo: dict[int, Any] | None = None) -> Self: - copied = super().__deepcopy__(memo) - copied._runtime = None - return copied + return self.__copy__() - # -- subclass point ------------------------------------------------------- + # Private transport operations. Concrete workers own their CLI processes. + async def _cli_start(self, mcp_servers: dict[str, dict[str, Any]]) -> None: + raise errors.UnsupportedError("this worker cannot start a CLI") + + async def _cli_close(self) -> None: + pass - def _make_adapter( + async def _cli_open( self, - mcp_servers: dict[str, dict[str, Any]], - approve: base.Approve | None, - ) -> base.Adapter: - raise NotImplementedError + *, + session_id: str | None, + fork: bool, + seed: list[messages_.Message] | None, + instructions: str | None, + ) -> str: + raise errors.UnsupportedError("this worker cannot open a session") + + def _cli_turn( + self, prompt: _adapter.Prompt + ) -> AsyncIterator[events_.Event]: + raise errors.UnsupportedError("this worker cannot send input") + + async def _cli_send_running(self, prompt: _adapter.Prompt) -> bool: + raise errors.UnsupportedError("this worker cannot send during a turn") + + async def _cli_interrupt(self) -> None: + raise errors.UnsupportedError("this worker cannot interrupt") + + async def _cli_history(self, session_id: str) -> list[messages_.Message]: + raise errors.UnsupportedError("this worker cannot read history") - # -- ModelLike ------------------------------------------------------------ + async def _cli_list_sessions(self) -> list[_adapter.SessionInfo]: + raise errors.UnsupportedError("this worker cannot list sessions") + + def _cli_tui_command( + self, + session_id: str | None, + ) -> tuple[list[str], dict[str, str], str | None]: + raise errors.UnsupportedError("this worker has no TUI command") @property def id(self) -> str: - return self.model or "default" + return self.model_name or "default" @property def provider_name(self) -> str: - return self.kind + return self.worker_class_id - async def stream( - self, - messages: list[messages_.Message], - *, - tools: Sequence[tools_.Tool] | None = None, - output_type: type[pydantic.BaseModel] | None = None, - params: Any = None, - ) -> AsyncGenerator[events_.Event]: - """Answer `messages` with one assistant message. + @property + def version(self) -> str | None: + return self._cli_version - Use `ai.stream(worker, messages)`, as with a model. The message ends - in one of two ways: + @property + def hook_registry(self) -> hooks.HookRegistry: + """Pass to ``ai.resolve_hook(..., registry=worker.hook_registry)``.""" + return self._require_runtime().registry + + async def open(self) -> None: + """Start the CLI transport once. A session opens on first input.""" + async with self._open_lock: + if self._runtime is not None: + return + bridge = _bridge.Bridge(self._on_call) + await bridge.start() + rt = _Runtime(bridge=bridge) + self._runtime = rt + try: + await self._cli_start( + { + **self.mcp_servers, + _bridge.SERVER_NAME: { + "type": "http", + "url": bridge.url, + }, + } + ) + except BaseException: + self._runtime = None + try: + await self._cli_close() + finally: + await bridge.close() + raise - - `finish_reason="tool_call"`: the CLI called `ai` tools from - `tools=`. The message holds them as `ToolCallPart`s. Run them and - call again with the results; the CLI waits until then. - - Anything else: the CLI's turn is over. + async def close(self) -> None: + """Stop the CLI and unblock the reader. Keep serializable state.""" + async with self._open_lock: + rt = self._runtime + if rt is None: + return + await self._abandon() + rt.closed = True + rt.queue.put_nowait(None) + try: + await self._cli_close() + finally: + self._runtime = None + await rt.bridge.close() - `params` is ignored: the CLI chooses its own. - """ - rt = await self._open() - await rt.lock.acquire() - paused = False - try: - if self.approve: - try: - hooks.get_hook_registry() - runtime_.get_runtime() - except LookupError: - raise errors.WorkerError( - "approve=True asks through ai.hook, which needs a " - "run: use the worker in ai.Agent.run()" - ) from None - rt.context = contextvars.copy_context() - plan = self._plan(messages) - rt.bridge.set_tools( - [t for t in tools or () if t.kind == "function"] + async def __aenter__(self) -> Self: + await self.open() + return self + + async def __aexit__(self, *exc_info: object) -> None: + await self.close() + + def _require_runtime(self) -> _Runtime: + if self._runtime is None: + raise errors.WorkerError( + f"{self.worker_class_id} worker is not open" ) - if rt.pending: - if plan.results: - self._answer(plan.results) - else: - await self._abandon() - if plan.prompt: - if rt.in_session and plan.system: - text = "\n\n".join(plan.system) + "\n\n" - plan.prompt.insert(0, messages_.TextPart(text=text)) - if rt.queue is not None: - # Tool results came with a new user message. The CLI is - # still in its turn: the message is guidance for it. - await rt.adapter.steer(base.text_of(plan.prompt)) - else: - await self._ensure_session(plan) - self._start(plan.prompt, output_type) - if rt.queue is None: - raise ValueError( - "stream(): no new user message or tool result to send" - ) + return self._runtime - stamp = messages_.Message(role="assistant", parts=[]) - hydrator = events_.MessageHydrator() + async def _ensure_session(self, plan: _Plan | None = None) -> None: + rt = self._require_runtime() + if rt.in_session: + return + plan = plan or _Plan() + self.session_id = await self._cli_open( + session_id=self.session_id, + fork=False, + seed=plan.seed if self.session_id is None and plan.seed else None, + instructions=plan.instructions, + ) + rt.in_session = True - def out(event: events_.Event) -> events_.Event: - event = event.model_copy( - update={ - "message": messages_.Message( - id=stamp.id, role="assistant", parts=[] + async def send(self, prompt: str | _adapter.Prompt) -> None: + """Submit input and wait for transport acceptance, not the answer. + + While a turn runs this is guidance; when idle it starts a turn. + Read ``events`` to observe acceptance and update ``messages``. + """ + parts: _adapter.Prompt = ( + [messages_.TextPart(text=prompt)] + if isinstance(prompt, str) + else list(prompt) + ) + if not parts: + raise ValueError("send(): prompt must not be empty") + await self.open() + rt = self._require_runtime() + if ( + rt.stream_owner is not None + and rt.stream_owner is not asyncio.current_task() + ): + # Initial model input must open the session before another task + # can steer it. Otherwise both paths can create a native session. + await rt.model_ready.wait() + async with rt.send_lock: + accepted = rt.submission + rt.submission = None + if accepted is None: + accepted = [messages_.Message(role="user", parts=list(parts))] + await self._ensure_session() + if rt.pump is not None and not rt.pump.done(): + if await self._cli_send_running(parts): + rt.queue.put_nowait(_Accepted(accepted)) + return + # The CLI confirmed idle without writing. Let the old reader + # finish its terminal event before starting another turn. + await rt.pump + ready: asyncio.Future[None] = ( + asyncio.get_running_loop().create_future() + ) + + async def pump() -> None: + try: + async for event in self._cli_turn(parts): + if ( + isinstance(event, events_.StreamStart) + and not ready.done() + ): + rt.queue.put_nowait(_Accepted(accepted)) + ready.set_result(None) + rt.queue.put_nowait(event) + if not ready.done(): + raise errors.WorkerError( + "CLI ended before accepting input" ) - } - ) - hydrator.feed(event) - return event + except asyncio.CancelledError: + if not ready.done(): + ready.cancel() + raise + except BaseException as exc: + if not ready.done(): + ready.set_exception(exc) + else: + rt.queue.put_nowait(_Failed(exc)) + + rt.pump = asyncio.create_task(pump()) + try: + await ready + except asyncio.CancelledError: + await self._abandon() + raise - yield out(events_.StreamStart()) - # Text after the last CLI tool call: the answer, for output_type. - answer: list[str] = [] + async def events(self) -> AsyncGenerator[SessionEvent]: + """Read the session feed until close; exactly one reader is allowed. + + StreamStart/StreamEnd mark assistant messages. UserMessageAccepted + records input. HookEvent carries approvals. Closing/cancelling a + reader interrupts a running turn, except when Agent tools must run. + """ + await self.open() + rt = self._require_runtime() + if rt.reader or ( + rt.stream_owner is not None + and rt.stream_owner is not asyncio.current_task() + ): + raise errors.WorkerError( + "events(): this session already has a reader" + ) + rt.reader = True + hydrator: events_.MessageHydrator | None = None + + def out(event: events_.Event) -> events_.Event: + nonlocal hydrator + if hydrator is None: + hydrator = events_.MessageHydrator() + event = event.model_copy(update={"message": hydrator.message}) + hydrator.feed(event) + if all(m.id != hydrator.message.id for m in self.messages): + self.messages.append(hydrator.message) + return event + + try: while True: item = await rt.queue.get() + if item is None: + return if isinstance(item, _Failed): - self._end_turn() raise item.error + if isinstance(item, _Accepted): + known = {m.id for m in self.messages} + for message in item.messages: + if message.id not in known: + # Guidance belongs before the in-progress answer, + # not after the final answer in the model history. + if ( + hydrator is not None + and hydrator.message in self.messages + ): + self.messages.insert( + self.messages.index(hydrator.message), + message, + ) + else: + self.messages.append(message) + known.add(message.id) + if message.role == "user": + yield UserMessageAccepted(message=message) + continue + if isinstance(item, events_.HookEvent): + yield item + continue + if isinstance(item, events_.StreamStart): + hydrator = None + yield out(item) + continue + if hydrator is None: + yield out(events_.StreamStart()) if isinstance(item, _Call): calls = [item] with contextlib.suppress(TimeoutError): @@ -288,7 +442,6 @@ def out(event: events_.Event) -> events_.Event: if isinstance(more, _Call): calls.append(more) else: - # Not ours to handle here: put it back. rt.queue.put_nowait(more) break for call in calls: @@ -315,94 +468,336 @@ def out(event: events_.Event) -> events_.Event: tool_call_id=part.tool_call_id, tool_call=part ) ) - paused = True yield out( events_.StreamEnd( finish_reason="tool_call", provider_metadata=self._metadata(None), ) ) - break + hydrator = None + continue if isinstance(item, events_.StreamEnd): - self._end_turn() - usage = item.usage - if output_type is not None: - text, usage = await self._output( - "".join(answer), output_type, usage - ) - yield out(events_.TextStart(block_id="output")) - yield out( - events_.TextDelta(chunk=text, block_id="output") - ) - yield out(events_.TextEnd(block_id="output")) finish = item.finish_reason + rt.hidden.clear() yield out( - events_.StreamEnd( - finish_reason=( - "other" if finish == "cancelled" else finish - ), - usage=usage, - provider_metadata={ - **(item.provider_metadata or {}), - **self._metadata(finish), - }, + item.model_copy( + update={ + "finish_reason": "other" + if finish == "cancelled" + else finish, + "provider_metadata": { + **(item.provider_metadata or {}), + **self._metadata(finish), + }, + } ) ) - break + hydrator = None + continue for event in self._visible(item): + yield out(event) + finally: + rt.reader = False + if not rt.closed and not rt.pending: + await self._abandon() + + async def interrupt(self) -> None: + """Request a clean turn end. The current reader receives StreamEnd.""" + rt = self._runtime + if rt is None or rt.pump is None or rt.pump.done(): + return + for task in list(rt.approvals): + task.cancel() + self._answer([]) + await self._cli_interrupt() + + async def _abandon(self) -> None: + rt = self._runtime + if rt is None: + return + for task in list(rt.approvals): + task.cancel() + self._answer([]) + pump = rt.pump + if pump is not None and not pump.done(): + with contextlib.suppress(Exception): + await self._cli_interrupt() + pump.cancel() + with contextlib.suppress(asyncio.CancelledError): + await pump + rt.pump = None + # A cancelled reader must not hand its queued terminal event to the + # next model request. The partial mirror remains until sync(). + while not rt.queue.empty(): + item = rt.queue.get_nowait() + if isinstance(item, _Call) and not item.answer.done(): + item.answer.set_result(("cancelled by the caller", True)) + rt.hidden.clear() + + async def sync(self) -> None: + """Replace the mirror from the CLI store, for example after TUI use.""" + await self.open() + rt = self._require_runtime() + if rt.reader or (rt.pump is not None and not rt.pump.done()): + raise errors.WorkerError("sync(): stop the turn and reader first") + if self.session_id is None: + raise errors.WorkerError("sync(): no session_id to read") + self.messages = await self._cli_history(self.session_id) + # Native history supersedes output queued before synchronization. + await self._abandon() + + async def fork(self) -> Self: + """Create a native session with a new id. Never fork a running turn.""" + if self.session_id is None: + raise errors.WorkerError("fork(): no session_id to fork") + rt = self._runtime + if rt is not None and ( + rt.reader or (rt.pump is not None and not rt.pump.done()) + ): + raise errors.WorkerError("fork(): stop the turn and reader first") + branch = self.__copy__() + try: + await branch.open() + branch.session_id = await branch._cli_open( + session_id=self.session_id, + fork=True, + seed=None, + instructions=None, + ) + if branch.session_id == self.session_id: + raise errors.WorkerError( + "fork(): CLI did not create a new session id" + ) + branch._require_runtime().in_session = True + branch.messages = await branch._cli_history(branch.session_id) + return branch + except BaseException: + await branch.close() + raise + + def tui_command(self) -> tuple[list[str], dict[str, str]]: + """Return argv and env. Close this worker before starting the TUI.""" + argv, env, minted = self._cli_tui_command(self.session_id) + if self.session_id is None: + if minted is None: + raise errors.WorkerError( + "CLI chooses its session id: send input first" + ) + self.session_id = minted + return argv, env + + async def tui(self) -> int: + await self.close() + argv, env = self.tui_command() + proc = await asyncio.create_subprocess_exec( + *argv, cwd=self.cwd, env={**os.environ, **env} + ) + code = await proc.wait() + await self.sync() + return code + + @classmethod + async def list_sessions( + cls, cwd: str, **fields: Any + ) -> list[_adapter.SessionInfo]: + worker = cls(cwd=cwd, **fields) + async with worker: + return await worker._cli_list_sessions() + + async def stream( + self, + messages: list[messages_.Message], + *, + tools: Sequence[tools_.Tool] | None = None, + output_type: type[pydantic.BaseModel] | None = None, + params: Any = None, + ) -> AsyncGenerator[events_.Event]: + """Send only new input and read one assistant message via events().""" + await self.open() + rt = self._require_runtime() + if rt.reader or rt.stream_owner is not None: + raise errors.WorkerError( + "stream(): this session already has a reader" + ) + if not rt.queue.empty() and not rt.pending: + raise errors.WorkerError( + "stream(): unread session events; " + "consume events() or sync() first" + ) + rt.stream_owner = asyncio.current_task() + rt.model_ready.clear() + # Transport reader tasks can predate Agent.run(). Use the current + # consumer's registry, not the callback task's inherited context. + with contextlib.suppress(LookupError): + rt.registry = hooks.get_hook_registry() + try: + plan = self._plan(messages) + rt.bridge.set_tools( + [t for t in tools or () if t.kind == "function"] + ) + if rt.pending: + self._answer(plan.results) + for message in plan.transcript: + if all(m.id != message.id for m in self.messages): + self.messages.append(message) + if plan.prompt: + if rt.in_session and plan.system: + plan.prompt.insert( + 0, + messages_.TextPart( + text="\n\n".join(plan.system) + "\n\n" + ), + ) + await self._ensure_session(plan) + rt.submission = plan.transcript + prompt = list(plan.prompt) + if output_type is not None: + prompt.append( + messages_.TextPart( + text=OUTPUT_INSTRUCTION + + json.dumps(TypeAdapter(output_type).json_schema()) + ) + ) + await self.send(prompt) + elif not plan.results: + raise ValueError( + "stream(): no new user message or tool result to send" + ) + rt.model_ready.set() + + answer: list[str] = [] + # events() owns the native mirror; model output must hydrate a + # separate message, retaining the native id even across retries. + projection = events_.MessageHydrator() + async with contextlib.aclosing(self.events()) as feed: + async for event in feed: + if isinstance(event, UserMessageAccepted): + continue + if isinstance(event, events_.HookEvent): + # Agent's outer runtime carries hook events, while the + # direct path exposes them in events(). + try: + runtime = runtime_.get_runtime() + except LookupError: + raise errors.WorkerError( + "approval requires events() or ai.Agent.run(); " + "resolve with worker.hook_registry" + ) from None + await runtime.put_event(event) + continue + if isinstance(event, events_.StreamEnd): + if ( + output_type is not None + and event.finish_reason != "tool_call" + ): + text, usage = await self._output( + "".join(answer), output_type, event.usage, feed + ) + yield projection.feed( + events_.TextStart( + block_id="output", message=event.message + ) + ) + yield projection.feed( + events_.TextDelta( + chunk=text, + block_id="output", + message=event.message, + ) + ) + yield projection.feed( + events_.TextEnd( + block_id="output", message=event.message + ) + ) + event = event.model_copy(update={"usage": usage}) + native = event.message + event = projection.feed(event) + if output_type is not None: + # Persist all emitted parts, including builtin and + # Agent tools, not just the validated output text. + metadata = native.provider_metadata or {} + native.provider_metadata = { + **metadata, + "worker": { + **metadata.get("worker", {}), + "model_parts": event.message.model_dump( + mode="json" + )["parts"], + }, + } + yield event + break if output_type is not None and isinstance( event, events_.TextStart | events_.TextDelta | events_.TextEnd, ): - # Narration is not the output. Keep only the text - # after the last tool call, and send it once parsed. if isinstance(event, events_.TextDelta): answer.append(event.chunk) continue if isinstance(event, events_.BuiltinToolStart): answer.clear() - yield out(event) - # Committed only now: a call that failed can be sent again. - self.messages = [*plan.transcript, hydrator.message] - except (GeneratorExit, asyncio.CancelledError): - if not paused: - # Nobody reads this turn any more: end it in the CLI too. - await self._abandon() - raise + yield projection.feed(event) finally: - rt.lock.release() - - # -- the conversation ----------------------------------------------------- + rt.stream_owner = None + rt.submission = None + rt.model_ready.set() def _plan(self, messages: list[messages_.Message]) -> _Plan: - """Compare `messages` with the transcript; return what is new.""" known = [m.id for m in self.messages] given = [m.id for m in messages] plan = _Plan() - system = [m.text for m in messages if m.role == "system"] - plan.instructions = "\n\n".join(system) or None + plan.instructions = ( + "\n\n".join(m.text for m in messages if m.role == "system") or None + ) if known: - if given[: len(known)] != known: + projected: list[messages_.Message] = [] + for message in self.messages: + metadata = (message.provider_metadata or {}).get("worker", {}) + if metadata.get("model_hidden"): + continue + parts = metadata.get("model_parts") + projected.append( + message + if parts is None + else message.model_copy( + update={ + "parts": TypeAdapter( + list[messages_.Part] + ).validate_python(parts) + } + ) + ) + matched_ids = False + for history in (self.messages, projected): + if given[: len(history)] != [m.id for m in history]: + continue + matched_ids = True + # Accept either complete view, never arbitrary per-message + # substitutions. Matching ids must not conceal changed parts. + if all( + old.role == new.role and old.parts == new.parts + for old, new in zip(history, messages, strict=False) + ): + new_messages = messages[len(history) :] + break + else: raise errors.TranscriptMismatchError( - f"{self.kind}: these messages do not continue this " - "worker's conversation; start a new worker" + "stored message content was changed" + if matched_ids + else f"{self.worker_class_id}: messages do not continue " + "this session; use a new worker" ) - new = messages[len(known) :] - plan.transcript = list(self.messages) elif self.session_id is not None: - # A stored conversation the worker has not loaded: the CLI holds - # the past, so everything given is new. `load()` reads the past. - new = list(messages) + new_messages = list(messages) else: - # A new conversation. What comes before the last user turn is - # its past; the CLI is seeded with it before the first turn. cut = len(messages) while cut and messages[cut - 1].role in ("user", "system", "tool"): cut -= 1 plan.seed = [m for m in messages[:cut] if m.role != "system"] - new = messages[cut:] + new_messages = messages[cut:] plan.transcript = list(messages[:cut]) - for message in new: + for message in new_messages: if message.role == "tool": plan.results.extend(message.tool_results) elif message.role == "system": @@ -415,59 +810,12 @@ def _plan(self, messages: list[messages_.Message]) -> _Plan: ) else: raise errors.TranscriptMismatchError( - f"{self.kind}: a {message.role} message the worker did " - "not write; only user, system and tool messages can " - "follow its last answer (load() reads a stored past)" + "only user, system and tool messages may follow " + "the last answer" ) - plan.transcript.extend(new) + plan.transcript.extend(new_messages) return plan - async def _ensure_session(self, plan: _Plan) -> None: - rt = self._require_runtime() - if rt.in_session: - return - self.session_id = await rt.adapter.open( - session_id=self.session_id, - fork=self.fork, - seed=plan.seed if self.session_id is None and plan.seed else None, - instructions=plan.instructions, - ) - self.fork = False - rt.in_session = True - - def _start( - self, - prompt: list[messages_.TextPart | messages_.FilePart], - output_type: type[pydantic.BaseModel] | None, - ) -> None: - rt = self._require_runtime() - if output_type is not None: - schema = json.dumps(TypeAdapter(output_type).json_schema()) - prompt = [ - *prompt, - messages_.TextPart(text=OUTPUT_INSTRUCTION + schema), - ] - queue: asyncio.Queue[Any] = asyncio.Queue() - adapter = rt.adapter - - async def pump() -> None: - try: - async for event in adapter.turn(prompt): - queue.put_nowait(event) - except asyncio.CancelledError: - raise - except BaseException as exc: - queue.put_nowait(_Failed(exc)) - - rt.queue = queue - rt.pump = asyncio.create_task(pump()) - - def _end_turn(self) -> None: - rt = self._require_runtime() - rt.queue = None - rt.pump = None - rt.hidden.clear() - def _answer(self, results: list[messages_.ToolResultPart]) -> None: rt = self._require_runtime() for part in results: @@ -477,40 +825,23 @@ def _answer(self, results: list[messages_.ToolResultPart]) -> None: value = part.model_input if value is messages_.MODEL_INPUT_UNSET: value = part.result - text = value if isinstance(value, str) else _dump(value) - call.answer.set_result((text, part.result_kind == "error")) + call.answer.set_result( + ( + value if isinstance(value, str) else _dump(value), + part.result_kind == "error", + ) + ) for call in rt.pending.values(): - # A call the caller did not answer: tell the CLI, do not hang. if not call.answer.done(): call.answer.set_result(("no result was given", True)) rt.pending.clear() - async def _abandon(self) -> None: - """End the running turn: the caller moved on without it.""" - rt = self._runtime - if rt is None: - return - for call in rt.pending.values(): - if not call.answer.done(): - call.answer.set_result(("cancelled by the caller", True)) - rt.pending.clear() - pump = rt.pump - if pump is None: - return - with contextlib.suppress(Exception): - await rt.adapter.interrupt() - pump.cancel() - with contextlib.suppress(BaseException): - await pump - self._end_turn() - async def _on_call( self, name: str, arguments: dict[str, Any] ) -> tuple[str, bool]: - """Hand a bridge call to the caller, and wait for the result.""" rt = self._runtime - if rt is None or rt.queue is None: - return ("no turn is running", True) + if rt is None or rt.pump is None: + return "no turn is running", True answer: asyncio.Future[tuple[str, bool]] = ( asyncio.get_running_loop().create_future() ) @@ -522,44 +853,33 @@ async def _on_call( async def _approve( self, tool_call_id: str, tool_name: str, tool_input: dict[str, Any] ) -> tuple[bool, str]: - """Ask about one of the CLI's own tool calls, through `ai.hook`.""" if self._is_bridge_tool(tool_name): - # An `ai` tool: the agent gates it itself, if it is gated. return True, "" rt = self._runtime - if rt is None or rt.context is None: - return False, "no run to ask in; denied" - - async def ask() -> tuple[bool, str]: + if rt is None or rt.closed: + return False, "session is closed" + task = asyncio.current_task() + if task is not None: + rt.approvals.add(task) + try: approval = await hooks.hook( f"approve_{tool_call_id}", payload=hooks.ToolApproval, metadata={"tool": tool_name, "kwargs": tool_input}, tool_call_id=tool_call_id, + registry=rt.registry, + runtime=_HookRuntime(rt.queue), ) return approval.granted, approval.reason or "denied" - - # In the caller's context: that is where the run's hooks live. - task = asyncio.create_task(ask(), context=rt.context) - try: - return await task except asyncio.CancelledError: - current = asyncio.current_task() - if current is not None and current.cancelling(): - raise return False, "the approval was cancelled" except Exception as exc: return False, f"approval failed ({type(exc).__name__}); denied" + finally: + if task is not None: + rt.approvals.discard(task) def _is_bridge_tool(self, tool_name: str) -> bool: - """Whether a tool the CLI reports is a bridge call. - - Those reach the caller as `ToolCallPart`s, so the CLI's own report - of them is hidden. Claude Code names an MCP tool - `mcp____`; codex uses the bare name, or the server's - name when the tool name is missing (measured: codex 0.160). How pi - names them is not measured yet: the forms it may use are accepted. - """ rt = self._runtime if rt is None: return False @@ -571,11 +891,8 @@ def _is_bridge_tool(self, tool_name: str) -> bool: ) def _visible(self, event: events_.Event) -> list[events_.Event]: - """Drop StreamStart and the CLI's own report of bridge calls.""" rt = self._require_runtime() match event: - case events_.StreamStart(): - return [] # a worker message has its own case events_.BuiltinToolStart(): if self._is_bridge_tool(event.tool_name): rt.hidden.add(event.tool_call_id) @@ -596,175 +913,52 @@ async def _output( text: str, output_type: type[pydantic.BaseModel], usage: usage_.Usage | None, + feed: AsyncIterator[SessionEvent], ) -> tuple[str, usage_.Usage | None]: - """Parse the answer, asking again when it does not validate.""" - adapter = self._require_runtime().adapter parsed, error = _parse(text, output_type) attempt = 0 while error is not None and attempt < OUTPUT_RETRIES: attempt += 1 - retry = messages_.TextPart( - text=f"Your previous reply failed validation: {error}\n" + await self.send( + f"Your previous reply failed validation: {error}\n" "Reply again with ONLY the corrected JSON." ) chunks: list[str] = [] - async for event in adapter.turn([retry]): - if isinstance(event, events_.BuiltinToolStart): - chunks.clear() - elif isinstance(event, events_.TextDelta): + async for event in feed: + if isinstance(event, UserMessageAccepted | events_.ModelEvent): + # Retry input and answers remain in the native mirror, but + # are not separate messages in the caller's model view. + # Reapply on StreamEnd, which installs native metadata. + metadata = event.message.provider_metadata or {} + event.message.provider_metadata = { + **metadata, + "worker": { + **metadata.get("worker", {}), + "model_hidden": True, + }, + } + if isinstance(event, events_.TextDelta): chunks.append(event.chunk) - elif isinstance(event, events_.StreamEnd) and event.usage: - usage = usage + event.usage if usage else event.usage + elif isinstance(event, events_.BuiltinToolStart): + chunks.clear() + elif isinstance(event, events_.StreamEnd): + if event.usage: + usage = usage + event.usage if usage else event.usage + break + elif isinstance(event, events_.HookEvent): + await runtime_.get_runtime().put_event(event) text = "".join(chunks) parsed, error = _parse(text, output_type) return (parsed.model_dump_json() if parsed else text), usage def _metadata(self, finish: str | None) -> dict[str, Any]: - meta: dict[str, Any] = {"kind": self.kind} + meta: dict[str, Any] = {"worker_class_id": self.worker_class_id} if self.session_id: meta["session_id"] = self.session_id if finish is not None: meta["finish_reason"] = finish return {"worker": meta} - # -- lifecycle ------------------------------------------------------------ - - async def _open(self) -> _Runtime: - if self._runtime is not None: - return self._runtime - bridge = _bridge.Bridge(self._on_call) - await bridge.start() - servers = { - **self.mcp_servers, - _bridge.SERVER_NAME: {"type": "http", "url": bridge.url}, - } - adapter = self._make_adapter( - servers, self._approve if self.approve else None - ) - try: - await adapter.start() - except BaseException: - await bridge.close() - raise - self._runtime = _Runtime(adapter=adapter, bridge=bridge) - return self._runtime - - async def close(self) -> None: - """End the turn, the CLI and the bridge. The fields stay as they are. - - A closed worker opens again on its next use, and resumes its - conversation. - """ - rt = self._runtime - if rt is None: - return - await self._abandon() - self._runtime = None - try: - await rt.adapter.close() - finally: - await rt.bridge.close() - - async def __aenter__(self) -> Self: - await self._open() - return self - - async def __aexit__(self, *exc_info: object) -> None: - await self.close() - - def _require_runtime(self) -> _Runtime: - if self._runtime is None: - raise errors.WorkerError(f"{self.kind} worker is not open") - return self._runtime - - @property - def version(self) -> str | None: - """What the CLI's `--version` printed, once the worker is open.""" - return self._runtime.adapter.version if self._runtime else None - - # -- what only a CLI has -------------------------------------------------- - - async def load(self) -> None: - """Read the stored conversation `session_id` names into `messages`. - - Also after a person worked in the CLI's TUI (see `tui()`). - """ - if self.session_id is None: - raise errors.WorkerError(f"{self.kind}: no session_id to load") - rt = await self._open() - self.messages = await rt.adapter.history(self.session_id) - - async def steer(self, text: str) -> None: - """Send guidance to the turn that runs now; the agent acts on it. - - For use from another task while `stream()` runs. The text is not - added to `messages`; `load()` reads it back from the CLI. - """ - rt = self._require_runtime() - if rt.queue is None: - raise errors.WorkerError(f"{self.kind}: no turn is running") - await rt.adapter.steer(text) - - def tui_command(self) -> tuple[list[str], dict[str, str]]: - """Return the CLI's own TUI command for this conversation. - - Run it in `cwd`, with the env added to yours:: - - argv, env = worker.tui_command() - subprocess.run(argv, cwd=worker.cwd, env={**os.environ, **env}) - - A worker with no conversation yet gets a new one, when the CLI lets - us choose its id (Claude Code, Pi). Close the worker first: one - writer per conversation. - """ - if self.fork: - raise errors.WorkerError( - f"{self.kind}: run a turn first; the fork happens on first use" - ) - rt = self._runtime - adapter = ( - rt.adapter if rt else self._make_adapter(self.mcp_servers, None) - ) - argv, env, minted = adapter.tui_command(self.session_id) - if self.session_id is None: - if minted is None: - raise errors.WorkerError( - f"{self.kind} picks its own session id: run a turn " - "first, or pass session_id=" - ) - self.session_id = minted - return argv, env - - async def tui(self) -> int: - """Hand the conversation to a person, in this terminal. - - Runs the CLI's TUI on it and returns its exit code once the person - quits. The worker then reads the conversation back (`load()`) and - goes on headless. - """ - await self.close() - argv, env = self.tui_command() - proc = await asyncio.create_subprocess_exec( - *argv, cwd=self.cwd, env={**os.environ, **env} - ) - code = await proc.wait() - await self.load() - return code - - @classmethod - async def list_sessions(cls, **fields: Any) -> list[base.SessionInfo]: - """Return the conversations the CLI has stored for a directory. - - Takes the worker's fields: `cwd=`, `env=`, `executable=`. - """ - worker = cls(**fields) - adapter = worker._make_adapter({}, None) - await adapter.start() - try: - return await adapter.list_sessions() - finally: - await adapter.close() - def _parse( text: str, output_type: type[pydantic.BaseModel] @@ -776,7 +970,6 @@ def _parse( def _extract_json(text: str) -> str: - """Best effort: the model was told "only JSON", but fences happen.""" candidate = text.strip() if candidate.startswith("```"): parts = candidate.split("```") diff --git a/src/ai/workers/claude_code/__init__.py b/src/ai/workers/claude_code/__init__.py new file mode 100644 index 00000000..0d2ab501 --- /dev/null +++ b/src/ai/workers/claude_code/__init__.py @@ -0,0 +1,3 @@ +from .worker import ClaudeCode + +__all__ = ["ClaudeCode"] diff --git a/src/ai/workers/claude_code/handoff.py b/src/ai/workers/claude_code/handoff.py new file mode 100644 index 00000000..15800dc4 --- /dev/null +++ b/src/ai/workers/claude_code/handoff.py @@ -0,0 +1,131 @@ +"""Seeding Claude Code with a past: records for its transcript store. + +The rule for what becomes what is the same for every CLI: see `_handoff`. +""" + +from __future__ import annotations + +import datetime +import json +import uuid +from typing import Any + +from ...types import media +from ...types import messages as messages_ +from .. import _handoff + + +def _source(part: messages_.FilePart) -> dict[str, Any]: + """Return an Anthropic content-block source for a file.""" + if isinstance(part.data, str) and media.is_downloadable_url(part.data): + return {"type": "url", "url": part.data} + return { + "type": "base64", + "media_type": part.media_type, + "data": media.data_to_base64(part.data), + } + + +def to_claude_records( + messages: list[messages_.Message], session_id: str, cwd: str +) -> list[dict[str, Any]]: + """Build Claude Code transcript records for the CLI's store. + + Chained by parentUuid. + + Reasoning parts are omitted: see the module docstring. Callers report + the omission — `reasoning_count()` says how many. + """ + records: list[dict[str, Any]] = [] + parent: str | None = None + + def add(role: str, content: Any) -> None: + nonlocal parent + uid = str(uuid.uuid4()) + ts = ( + datetime.datetime.now(datetime.UTC) + .isoformat() + .replace("+00:00", "Z") + ) + records.append( + { + "parentUuid": parent, + "isSidechain": False, + "type": role, + "message": {"role": role, "content": content}, + "uuid": uid, + "timestamp": ts, + "sessionId": session_id, + "cwd": cwd, + } + ) + parent = uid + + for m in messages: + role = "user" if m.role in ("user", "tool") else "assistant" + blocks: list[dict[str, Any]] = [] + results: list[dict[str, Any]] = [] + for p in m.parts: + if isinstance(p, messages_.BuiltinToolReturnPart): + # A tool the CLI ran: the worker holds its result in the + # assistant message, the store in the NEXT user record. So + # the assistant record ends here, and the results follow. + if blocks: + add(role, blocks) + blocks = [] + results.append( + { + "type": "tool_result", + "tool_use_id": p.tool_call_id, + "content": _handoff.result_text(p.result), + **({"is_error": True} if p.is_error else {}), + } + ) + continue + if results: + add("user", results) + results = [] + if isinstance(p, messages_.TextPart) and p.text.strip(): + blocks.append({"type": "text", "text": p.text}) + elif isinstance(p, messages_.FilePart) and m.role == "user": + if p.media_type.startswith("image/"): + blocks.append({"type": "image", "source": _source(p)}) + elif p.media_type == "application/pdf": + blocks.append({"type": "document", "source": _source(p)}) + elif isinstance( + p, messages_.ToolCallPart | messages_.BuiltinToolCallPart + ): + try: + args = json.loads(p.tool_args) if p.tool_args else {} + except json.JSONDecodeError: + args = {"raw": p.tool_args} + blocks.append( + { + "type": "tool_use", + "id": p.tool_call_id or p.id, + "name": p.tool_name, + "input": args, + } + ) + elif isinstance(p, messages_.ToolResultPart): + # A tool an `ai.Agent` ran: its result is in a `tool` + # message, which becomes a user record of its own. + blocks.append( + { + "type": "tool_result", + "tool_use_id": p.tool_call_id, + "content": _handoff.result_text(p.result), + **( + {"is_error": True} + if p.result_kind == "error" + else {} + ), + } + ) + # ReasoningPart: omitted on purpose — Anthropic's safeguards + # refuse replayed reasoning. The adapter warns with the count. + if blocks: + add(role, blocks) + if results: + add("user", results) + return records diff --git a/src/ai/workers/claude_code/worker.py b/src/ai/workers/claude_code/worker.py new file mode 100644 index 00000000..5b3b74a8 --- /dev/null +++ b/src/ai/workers/claude_code/worker.py @@ -0,0 +1,757 @@ +"""Claude Code, driven through claude-agent-sdk. + +The session id we hand the CLI IS its own session id, so `claude --resume +` opens the same conversation, here or in the CLI's own UI. + +The comments record what was MEASURED against a real `claude` CLI (see +VERIFIED_VERSION), not what the API suggested. +""" + +from __future__ import annotations + +import asyncio +import base64 +import contextlib +import json +import os +import pathlib +import uuid +import warnings +from collections.abc import AsyncGenerator, AsyncIterator +from typing import TYPE_CHECKING, Any, Literal + +import pydantic + +from ...providers import _optional +from ...types import events as events_ +from ...types import messages as messages_ +from ...types import usage as usage_ +from .. import _adapter, _bridge, _convert, _handoff, _worker +from .. import _errors as errors +from . import handoff + +if TYPE_CHECKING: + import claude_agent_sdk + +KIND = "claude-code" +INSTALL = "npm install -g @anthropic-ai/claude-code" +# The CLI the live tests last passed against. Older ones get a warning. +VERIFIED_VERSION = "2.1.289" + +# Seconds the CLI waits for an approval. Its own default (60s) would cut a +# person short: the hook would time out and the call would be denied. +APPROVAL_TIMEOUT = 24 * 3600 + +AUTH_HINT = ( + "claude-code uses your own login: run `claude` once and sign in, or " + "pass env={'ANTHROPIC_API_KEY': ...}." +) + + +class ClaudeCode(_worker.Worker): + """Claude Code, through `claude-agent-sdk`. Needs the `claude-code` extra. + + `allowed_tools` limits Claude Code's own tools (`["Read", "Grep"]`, or + `[]` for none), and `disallowed_tools` takes some away. `max_turns` caps + the agent's steps in one turn; a turn that hits it ends with + `finish_reason="length"`. + """ + + worker_class_id: Literal["claude-code"] = "claude-code" + allowed_tools: list[str] | None = None + disallowed_tools: list[str] | None = None + max_turns: int | None = None + + _mcp_servers: dict[str, dict[str, Any]] = pydantic.PrivateAttr( + default_factory=dict + ) + _approval_callback: _adapter.Approve | None = pydantic.PrivateAttr( + default=None + ) + _instructions: str | None = pydantic.PrivateAttr(default=None) + _client: Any = pydantic.PrivateAttr(default=None) + # Requested interrupt, or unread responses after a failed turn. The + # next query must drain these before it writes any new input. + _interrupted: bool = pydantic.PrivateAttr(default=False) + # A reader owns the responses to all queries accepted into this run. + _running: bool = pydantic.PrivateAttr(default=False) + # Account one terminal result per query written to streaming input. + # The SDK supplies no input-id/result-id correlation: this is not proof + # of native consumption, nor accounting for autonomous/background turns. + _pending_results: int = pydantic.PrivateAttr(default=0) + _input_lock: asyncio.Lock = pydantic.PrivateAttr( + default_factory=asyncio.Lock + ) + + @property + def _cwd(self) -> str: + # The CLI keys its store by the real path of its directory. + return os.path.realpath(self.cwd) + + @property + def _executable(self) -> str: + return self.executable or "claude" + + async def _cli_start(self, mcp_servers: dict[str, dict[str, Any]]) -> None: + _sdk() + self._mcp_servers = dict(mcp_servers) + self._approval_callback = self._approve if self.approve else None + self._cli_version = await _adapter.probe( + KIND, + self._executable, + install=INSTALL, + verified=VERIFIED_VERSION, + cwd=self._cwd, + env=self.env, + ) + + async def _cli_close(self) -> None: + client, self._client = self._client, None + self._running = False + self._pending_results = 0 + self._interrupted = False + self._instructions = None + self._approval_callback = None + self._mcp_servers = {} + if client is not None: + with contextlib.suppress(Exception): + await client.disconnect() + + # -- the conversation ----------------------------------------------------- + + async def _cli_open( + self, + *, + session_id: str | None, + fork: bool, + seed: list[messages_.Message] | None, + instructions: str | None, + ) -> str: + claude_agent_sdk = _sdk() + self._instructions = instructions + if seed: + session_id = await self._stage(seed) + elif session_id is not None: + await self._require_known(session_id) + if fork: + try: + # The SDK remaps every UUID and rewrites the chain. + result = await asyncio.to_thread( + claude_agent_sdk.fork_session, session_id, self._cwd + ) + except Exception as exc: + raise errors.WorkerError( + f"{KIND}: cannot fork session {session_id}: {exc}" + ) from exc + session_id = result.session_id + if session_id is None: + session_id = str(uuid.uuid4()) + await self._connect(session_id, resume=None) + else: + await self._connect(session_id, resume=session_id) + return session_id + + async def _stage(self, history: list[messages_.Message]) -> str: + """Write a past into the CLI's store under a fresh id; run nothing.""" + claude_agent_sdk = _sdk() + session_id = str(uuid.uuid4()) + _handoff.warn_unsupported_files(history, KIND) + dropped = _handoff.reasoning_count(history) + if dropped: + warnings.warn( + f"{dropped} reasoning part(s) in the history were not carried " + "into claude-code: Anthropic's safeguards refuse replayed " + "model reasoning ([reasoning_extraction]). Text and tool " + "calls were carried in full.", + stacklevel=2, + ) + # Where the CLI keeps transcripts: + # `$CLAUDE_CONFIG_DIR/projects//.jsonl`. + config = ( + self.env.get("CLAUDE_CONFIG_DIR") + or os.environ.get("CLAUDE_CONFIG_DIR") + or str(pathlib.Path.home() / ".claude") + ) + key = claude_agent_sdk.project_key_for_directory(self._cwd) + path = pathlib.Path(config) / "projects" / key / f"{session_id}.jsonl" + records = handoff.to_claude_records(history, session_id, self._cwd) + text = "".join( + json.dumps(r, separators=(",", ":")) + "\n" for r in records + ) + + def write() -> None: + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(text) + + await asyncio.to_thread(write) + return session_id + + async def _require_known(self, session_id: str) -> None: + """Refuse an unknown session before connecting to it. + + Connecting to a ghost surfaces as claude-agent-sdk's own error + somewhere downstream. + """ + claude_agent_sdk = _sdk() + try: + info = await asyncio.to_thread( + claude_agent_sdk.get_session_info, session_id, self._cwd + ) + except Exception as exc: + raise errors.WorkerError( + f"{KIND}: cannot read session {session_id}: {exc}" + ) from exc + if info is None: + raise errors.WorkerError( + f"{KIND}: no session {session_id} in {self._cwd}" + ) + + async def _connect(self, session_id: str, *, resume: str | None) -> None: + claude_agent_sdk = _sdk() + options: dict[str, Any] = { + "cwd": self._cwd, + "cli_path": self._executable, + # Raw Anthropic stream events, which map 1:1 onto Start/Delta/End + # triples. Without them the SDK yields only whole messages. + "include_partial_messages": True, + "session_id": session_id if resume is None else None, + "resume": resume, + } + if self.env: + # claude-agent-sdk spawns the CLI itself: pass the env along. + options["env"] = dict(self.env) + if self.model_name: + options["model"] = self.model_name + if self._instructions: + # Added to Claude Code's own system prompt, never replacing it. + options["system_prompt"] = { + "type": "preset", + "preset": "claude_code", + "append": self._instructions, + } + if self._mcp_servers: + options["mcp_servers"] = self._mcp_servers + if self.allowed_tools is not None: + options["tools"] = self.allowed_tools + if self.disallowed_tools: + options["disallowed_tools"] = self.disallowed_tools + if self.max_turns is not None: + options["max_turns"] = self.max_turns + if self.effort: + # Reasoning effort, with adaptive thinking so the budget follows. + options["effort"] = self.effort + options["thinking"] = {"type": "adaptive"} + if self._approval_callback is not None: + # A PreToolUse hook sees EVERY tool call, read-only ones included + # (measured). The permission callback alone only sees what the + # CLI's policy asks about; it stays as a safety net. + options["hooks"] = { + "PreToolUse": [ + claude_agent_sdk.HookMatcher( + matcher=None, + hooks=[self._pre_tool_use], + timeout=APPROVAL_TIMEOUT, + ) + ] + } + options["can_use_tool"] = self._can_use_tool + else: + # No gate: an always-allow callback would freeze the agent at + # its next tool call once nobody answers (measured). + options["permission_mode"] = "bypassPermissions" + client = claude_agent_sdk.ClaudeSDKClient( + options=claude_agent_sdk.ClaudeAgentOptions(**options) + ) + try: + await client.connect() + except claude_agent_sdk.ClaudeSDKError as exc: + raise _translate(exc) from exc + self._client = client + + # -- approval ------------------------------------------------------------- + + async def _pre_tool_use( + self, data: Any, tool_use_id: str | None, ctx: Any + ) -> Any: + assert self._approval_callback is not None + granted, reason = await self._approval_callback( + tool_use_id or str(data.get("tool_use_id") or uuid.uuid4()), + str(data.get("tool_name") or ""), + dict(data.get("tool_input") or {}), + ) + output: dict[str, Any] = { + "hookEventName": "PreToolUse", + "permissionDecision": "allow" if granted else "deny", + } + if not granted: + output["permissionDecisionReason"] = reason + return {"hookSpecificOutput": output} + + async def _can_use_tool( + self, + name: str, + tool_input: dict[str, Any], + ctx: claude_agent_sdk.ToolPermissionContext, + ) -> claude_agent_sdk.PermissionResult: + import claude_agent_sdk # noqa: PLC0415 + + assert self._approval_callback is not None + granted, reason = await self._approval_callback( + str(getattr(ctx, "tool_use_id", None) or uuid.uuid4()), + name, + dict(tool_input), + ) + if granted: + return claude_agent_sdk.PermissionResultAllow() + return claude_agent_sdk.PermissionResultDeny(message=reason) + + # -- turns ---------------------------------------------------------------- + + async def _cli_turn( + self, prompt: _adapter.Prompt + ) -> AsyncGenerator[events_.Event]: + claude_agent_sdk = _sdk() + _convert.check_files(prompt, KIND, ("image/", "application/pdf")) + client = self._client + assert client is not None + # Interruption or failure can leave accepted responses unread. + # Drain them first, or THIS turn could settle on an earlier result. + await self._drain_interrupted() + content = await _content(prompt) + names: dict[str, str] = {} + open_blocks: dict[int, str] = {} + try: + if isinstance(content, str): + await client.query(content) + else: + await client.query(_one_message(content)) + except claude_agent_sdk.ClaudeSDKError as exc: + raise _translate(exc) from exc + self._pending_results = 1 + self._running = True + try: + # query() completed its write. The base uses this as the send + # acknowledgement; waiting for output can deadlock approvals. + yield events_.StreamStart() + # receive_response() stops at the FIRST result, even if a duplex + # query has already queued another response. Keep one reader + # until every accepted query has a terminal result. + async with contextlib.aclosing( + _guard(client.receive_messages()) + ) as incoming: + async for message in incoming: + if isinstance(message, claude_agent_sdk.StreamEvent): + # Whole AssistantMessages repeat streamed text; only + # tool calls are taken from them below. + for event in _stream_events(message.event, open_blocks): + yield event + elif isinstance(message, claude_agent_sdk.AssistantMessage): + for block in message.content: + if isinstance(block, claude_agent_sdk.ToolUseBlock): + names[block.id] = block.name + for event in _convert.builtin_call( + block.id, + block.name, + json.dumps(block.input), + started=set(), + ): + yield event + elif isinstance(message, claude_agent_sdk.UserMessage): + content_blocks = ( + message.content + if isinstance(message.content, list) + else [] + ) + for block in content_blocks: + if isinstance( + block, claude_agent_sdk.ToolResultBlock + ): + yield _convert.builtin_result( + block.tool_use_id, + names.get(block.tool_use_id, ""), + block.content, + is_error=bool(block.is_error), + ) + elif isinstance(message, claude_agent_sdk.ResultMessage): + # A write that began before this result must finish + # accounting before we decide to retire this reader. + # Never hold this lock across a yield to the caller. + async with self._input_lock: + self._pending_results -= 1 + finished = self._pending_results == 0 + self._running = not finished + interrupted = self._interrupted + self._interrupted = False + try: + reason = _finish_reason( + message, interrupted=interrupted + ) + except errors.WorkerError: + # stream()/generate() stop at StreamEnd: raising + # after it would turn this failure into success. + # Stop accepting input now, before closing the SDK + # iterator can yield control. Preserve response + # debt for the next turn's drain (or close). + self._running = False + self._interrupted = not finished + raise + yield events_.StreamEnd( + usage=_usage(message), finish_reason=reason + ) + if finished: + return + names.clear() + open_blocks.clear() + yield events_.StreamStart() + raise errors.WorkerError( + f"{KIND}: CLI output ended with " + f"{self._pending_results} response(s) outstanding" + ) + finally: + self._running = False + + async def _drain_interrupted(self) -> None: + if not self._interrupted or self._client is None: + return + claude_agent_sdk = _sdk() + remaining = max(1, self._pending_results) + # Cancellation or failure can leave several accepted responses. + # Drain them all before allowing another query on this connection. + async with ( + asyncio.timeout(30), + contextlib.aclosing( + _guard(self._client.receive_messages()) + ) as incoming, + ): + async for message in incoming: + if isinstance(message, claude_agent_sdk.ResultMessage): + remaining -= 1 + self._pending_results = remaining + if remaining == 0: + self._interrupted = False + return + raise errors.WorkerError(f"{KIND}: CLI output ended during interrupt") + + async def _cli_send_running(self, prompt: _adapter.Prompt) -> bool: + if not self._running: + return False + _convert.check_files(prompt, KIND, ("image/", "application/pdf")) + content = await _content(prompt) + # Reading a file (or waiting for another writer) can yield while the + # response finishes. If it did, the base can start a fresh iterator. + async with self._input_lock: + if not self._running: + return False + client = self._client + if client is None: + raise errors.WorkerError(f"{KIND}: no CLI connection") + claude_agent_sdk = _sdk() + try: + await client.query( + content + if isinstance(content, str) + else _one_message(content) + ) + except claude_agent_sdk.ClaudeSDKError as exc: + raise _translate(exc) from exc + # The result reader uses this same lock, so it cannot retire + # between the successful write and recording its response debt. + # This acknowledges transport acceptance, not native processing. + self._pending_results += 1 + return True + + async def _cli_interrupt(self) -> None: + # Only a running turn: the CLI answers an interrupt with a result, + # which the next turn reads first (see `_drain_interrupted`). + if self._client is None or not self._running: + return + self._interrupted = True + with contextlib.suppress(Exception): + await self._client.interrupt() + + # -- the store ------------------------------------------------------------ + + async def _cli_history(self, session_id: str) -> list[messages_.Message]: + """Read the CLI's own transcript, every content block included.""" + claude_agent_sdk = _sdk() + await self._require_known(session_id) + stored = await asyncio.to_thread( + claude_agent_sdk.get_session_messages, session_id, self._cwd + ) + return _read(stored) + + async def _cli_list_sessions(self) -> list[_adapter.SessionInfo]: + claude_agent_sdk = _sdk() + infos = await asyncio.to_thread( + claude_agent_sdk.list_sessions, self._cwd + ) + return [ + _adapter.SessionInfo( + session_id=i.session_id, + title=i.custom_title or i.summary or i.first_prompt, + cwd=i.cwd, + created_at=i.created_at, + updated_at=i.last_modified, + ) + for i in infos + ] + + def _cli_tui_command( + self, session_id: str | None + ) -> tuple[list[str], dict[str, str], str | None]: + running_as = session_id or str(uuid.uuid4()) + argv = [self._executable] + argv += ( + ["--resume", session_id] + if session_id + else ["--session-id", running_as] + ) + if self.model_name: + argv += ["--model", self.model_name] + if self._instructions: + argv += ["--append-system-prompt", self._instructions] + servers = { + k: v + for k, v in self.mcp_servers.items() + if k != _bridge.SERVER_NAME + } + if servers: + argv += ["--mcp-config", json.dumps({"mcpServers": servers})] + if self.allowed_tools is not None: + argv += ["--tools", ",".join(self.allowed_tools)] + if self.disallowed_tools: + argv += ["--disallowedTools", ",".join(self.disallowed_tools)] + # Measured: the TUI otherwise updates itself in the background and + # announces "Restart to apply" mid-session. + env = {"DISABLE_AUTOUPDATER": "1", **self.env} + return argv, env, running_as + + +def _sdk() -> Any: + return _optional.import_optional_sdk( + "claude_agent_sdk", extra="claude-code", feature="ai.workers.ClaudeCode" + ) + + +async def _content(prompt: _adapter.Prompt) -> str | list[dict[str, Any]]: + """Return a prompt as the CLI takes it: a string, or content blocks. + + Images and PDFs travel as base64 blocks (measured: both read correctly). + """ + if len(prompt) == 1 and isinstance(prompt[0], messages_.TextPart): + return prompt[0].text + blocks: list[dict[str, Any]] = [] + for part in prompt: + if isinstance(part, messages_.TextPart): + blocks.append({"type": "text", "text": part.text}) + elif part.media_type.startswith("text/"): + blocks.append( + {"type": "text", "text": await _convert.as_text(part)} + ) + else: + kind = ( + "image" if part.media_type.startswith("image/") else "document" + ) + blocks.append( + { + "type": kind, + "source": { + "type": "base64", + "media_type": part.media_type, + "data": base64.b64encode( + await _convert.data(part) + ).decode("ascii"), + }, + } + ) + return blocks + + +async def _one_message( + content: list[dict[str, Any]], +) -> AsyncIterator[dict[str, Any]]: + """Yield one stream-json user message, the way `query()` sends a str.""" + yield { + "type": "user", + "message": {"role": "user", "content": content}, + "parent_tool_use_id": None, + "session_id": "default", + } + + +def _usage(message: Any) -> usage_.Usage: + raw = message.usage or {} + return usage_.Usage( + input_tokens=int(raw.get("input_tokens", 0)), + output_tokens=int(raw.get("output_tokens", 0)), + cache_read_tokens=int(raw.get("cache_read_input_tokens", 0)), + cache_write_tokens=int(raw.get("cache_creation_input_tokens", 0)), + # Cost has no home in Usage; the CLI's own number rides in `raw`. + raw={"cost_usd": message.total_cost_usd, "claude": raw}, + ) + + +def _finish_reason(message: Any, *, interrupted: bool) -> str: + subtype = message.subtype or "" + if interrupted: + # We asked for this. The CLI reports an error result after an + # interrupt; it is not a failure. + return "cancelled" + if subtype == "error_max_turns": + return "length" + if getattr(message, "is_error", False): + detail = str(getattr(message, "result", None) or subtype) + raise errors.turn_failed(KIND, detail, AUTH_HINT) + return "stop" + + +def _translate(exc: BaseException) -> BaseException: + """Turn a claude-agent-sdk exception into a worker error.""" + claude_agent_sdk = _sdk() + if isinstance(exc, claude_agent_sdk.CLINotFoundError): + return errors.ExecutableMissingError(KIND, "claude", INSTALL) + if isinstance(exc, claude_agent_sdk.ProcessError): + code = getattr(exc, "exit_code", None) + return errors.WorkerError(f"{KIND} crashed (exit {code}): {exc}") + if isinstance(exc, claude_agent_sdk.CLIConnectionError): + return errors.WorkerError(f"{KIND}: lost the CLI connection: {exc}") + if isinstance(exc, claude_agent_sdk.CLIJSONDecodeError): + return errors.WorkerError(f"{KIND}: unparseable CLI output: {exc}") + return exc + + +async def _guard(stream: Any) -> Any: + """Re-raise claude-agent-sdk failures as worker errors, mid-stream too.""" + claude_agent_sdk = _sdk() + try: + async with contextlib.aclosing(stream): + async for item in stream: + yield item + except claude_agent_sdk.ClaudeSDKError as exc: + raise _translate(exc) from exc + + +def _stream_events( + raw: dict[str, Any], open_blocks: dict[int, str] +) -> list[events_.Event]: + """One raw Anthropic stream event -> text and reasoning events. + + `open_blocks` tracks which content-block index is text or thinking, so + the closing event emits the matching End. + """ + kind = raw.get("type") + index = raw.get("index", 0) + out: list[events_.Event] = [] + block_id = f"b{index}" + if kind == "content_block_start": + block_type = (raw.get("content_block") or {}).get("type") + if block_type == "text": + open_blocks[index] = "text" + out.append(events_.TextStart(block_id=block_id)) + elif block_type == "thinking": + open_blocks[index] = "thinking" + out.append(events_.ReasoningStart(block_id=block_id)) + elif kind == "content_block_delta": + delta = raw.get("delta") or {} + if delta.get("type") == "text_delta" and delta.get("text"): + out.append( + events_.TextDelta(chunk=delta["text"], block_id=block_id) + ) + elif delta.get("type") == "thinking_delta" and delta.get("thinking"): + out.append( + events_.ReasoningDelta( + chunk=delta["thinking"], block_id=block_id + ) + ) + elif kind == "content_block_stop": + opened = open_blocks.pop(index, None) + if opened == "text": + out.append(events_.TextEnd(block_id=block_id)) + elif opened == "thinking": + out.append(events_.ReasoningEnd(block_id=block_id)) + return out + + +def _read(records: list[Any]) -> list[messages_.Message]: + """Read stored transcript records as messages, like a live turn's. + + The CLI's tools are built-in parts. On disk a tool result is a block in + the NEXT user record; here it joins the assistant message of its call. + """ + out: list[messages_.Message] = [] + calls: dict[str, tuple[messages_.Message, messages_.BuiltinToolCallPart]] + calls = {} + for record in records: + role, parts, results = _record(record) + if parts and role is not None: + message = messages_.Message(role=role, parts=parts) + out.append(message) + for part in parts: + if isinstance(part, messages_.BuiltinToolCallPart): + calls[part.tool_call_id] = (message, part) + for block in results: + found = calls.get(block.get("tool_use_id", "")) + if found is None: + continue # a result without its call: nothing to join + message, call = found + message.parts.append( + messages_.BuiltinToolReturnPart( + tool_call_id=call.tool_call_id, + tool_name=call.tool_name, + result=block.get("content"), + is_error=bool(block.get("is_error")), + ) + ) + return out + + +def _record( + record: Any, +) -> tuple[ + Literal["user", "assistant"] | None, list[Any], list[dict[str, Any]] +]: + """Return a record's role, its parts, and its tool result blocks. + + The role is None for a record that is neither user nor assistant. + """ + raw = record.message if isinstance(record.message, dict) else {} + role = raw.get("role") or record.type + content = raw.get("content") + if isinstance(content, str): + blocks: list[Any] = [{"type": "text", "text": content}] + else: + blocks = content if isinstance(content, list) else [] + parts: list[Any] = [] + results: list[dict[str, Any]] = [] + for block in blocks: + if not isinstance(block, dict): + continue + kind = block.get("type") + if kind == "text" and block.get("text"): + parts.append(messages_.TextPart(text=block["text"])) + elif kind in ("image", "document"): + found = block.get("source") + source: dict[str, Any] = found if isinstance(found, dict) else {} + if source.get("type") == "base64" and source.get("data"): + fallback = "image/png" if kind == "image" else "application/pdf" + parts.append( + messages_.FilePart( + data=str(source["data"]), + media_type=str(source.get("media_type") or fallback), + ) + ) + elif source.get("type") == "url" and source.get("url"): + parts.append(messages_.FilePart.from_url(str(source["url"]))) + elif kind == "thinking" and block.get("thinking"): + parts.append(messages_.ReasoningPart(text=block["thinking"])) + elif kind == "tool_use": + parts.append( + messages_.BuiltinToolCallPart( + tool_call_id=block.get("id", ""), + tool_name=block.get("name", ""), + tool_args=json.dumps(block.get("input") or {}), + ) + ) + elif kind == "tool_result": + results.append(block) + return (role if role in ("user", "assistant") else None), parts, results diff --git a/src/ai/workers/codex/__init__.py b/src/ai/workers/codex/__init__.py new file mode 100644 index 00000000..37337a31 --- /dev/null +++ b/src/ai/workers/codex/__init__.py @@ -0,0 +1,3 @@ +from .worker import Codex + +__all__ = ["Codex"] diff --git a/src/ai/workers/codex/handoff.py b/src/ai/workers/codex/handoff.py new file mode 100644 index 00000000..796f9937 --- /dev/null +++ b/src/ai/workers/codex/handoff.py @@ -0,0 +1,97 @@ +"""Seeding Codex with a past: Responses API items for `thread/inject_items`. + +The rule for what becomes what is the same for every CLI: see `_handoff`. +""" + +from __future__ import annotations + +from typing import Any + +from ...types import media +from ...types import messages as messages_ +from .. import _handoff + +NOTE_PREFIX = "[Handoff from a previous session — earlier reasoning: " + + +def _note(reasoning: list[str]) -> dict[str, Any]: + """Return the reasoning of a turn as a user-role note.""" + text = " ".join(r.strip() for r in reasoning if r.strip()) + return { + "type": "message", + "role": "user", + "content": [{"type": "input_text", "text": NOTE_PREFIX + text + "]"}], + } + + +def _image_url(part: messages_.FilePart) -> str: + """Return an http(s) URL as it is, anything else as a data URL.""" + return media.data_to_data_url(part.data, part.media_type) + + +def to_codex_items(messages: list[messages_.Message]) -> list[dict[str, Any]]: + """Responses API items for `thread/inject_items`. + + The items are a flat list, so each message goes in as it is: a call and + its result are two items that follow each other. That holds for a tool + an `ai.Agent` ran (a `ToolCallPart`, its result in a `tool` message) and + for a tool the CLI ran (built-in parts, the result in the same message). + A turn's reasoning goes in as a note after its calls, before their + results. + """ + items: list[dict[str, Any]] = [] + for m in messages: + reasoning: list[str] = [] + for p in m.parts: + if isinstance(p, messages_.TextPart) and p.text.strip(): + ctype = "input_text" if m.role == "user" else "output_text" + items.append( + { + "type": "message", + "role": m.role, + "content": [{"type": ctype, "text": p.text}], + } + ) + elif ( + isinstance(p, messages_.FilePart) + and m.role == "user" + and p.media_type.startswith("image/") + ): + items.append( + { + "type": "message", + "role": "user", + "content": [ + {"type": "input_image", "image_url": _image_url(p)} + ], + } + ) + elif isinstance( + p, messages_.ToolCallPart | messages_.BuiltinToolCallPart + ): + items.append( + { + "type": "function_call", + "call_id": p.tool_call_id or p.id, + "name": p.tool_name, + "arguments": p.tool_args or "{}", + } + ) + elif isinstance( + p, messages_.ToolResultPart | messages_.BuiltinToolReturnPart + ): + if reasoning: + items.append(_note(reasoning)) + reasoning = [] + items.append( + { + "type": "function_call_output", + "call_id": p.tool_call_id, + "output": _handoff.result_text(p.result), + } + ) + elif isinstance(p, messages_.ReasoningPart) and p.text.strip(): + reasoning.append(p.text) + if reasoning: + items.append(_note(reasoning)) + return items diff --git a/src/ai/workers/_adapters/jsonrpc.py b/src/ai/workers/codex/jsonrpc.py similarity index 68% rename from src/ai/workers/_adapters/jsonrpc.py rename to src/ai/workers/codex/jsonrpc.py index 14837088..f5b0a8c1 100644 --- a/src/ai/workers/_adapters/jsonrpc.py +++ b/src/ai/workers/codex/jsonrpc.py @@ -1,4 +1,4 @@ -"""A small JSON-RPC 2.0 peer over a CLI's stdio. +"""The transport to `codex app-server`: its process, and JSON-RPC over stdio. Line-delimited JSON, request/response futures, and two callbacks for what a server can start. Nothing here is protocol-specific: the Codex adapter @@ -10,13 +10,19 @@ import asyncio import contextlib import json -from collections.abc import Awaitable, Callable -from typing import TYPE_CHECKING, Any +import os +from collections.abc import Awaitable, Callable, Mapping, Sequence +from typing import Any from .. import _errors as errors -if TYPE_CHECKING: - from . import base +# Longest line app-server may write. One JSON line can be megabytes (a +# `thread/read` of a long thread). With asyncio's default (64 KiB) such a line +# failed as if the CLI had crashed. +LINE_LIMIT = 256 * 1024 * 1024 + +# Seconds app-server gets to exit after SIGTERM, before SIGKILL. +TERM_GRACE = 3.0 NotifyHandler = Callable[[str, dict[str, Any]], Awaitable[None]] RequestHandler = Callable[[Any, str, dict[str, Any]], Awaitable[None]] @@ -30,7 +36,7 @@ def __init__(self, error: dict[str, Any]) -> None: class JsonRpcPeer: - def __init__(self, process: base.Process, *, kind: str) -> None: + def __init__(self, process: Process, *, kind: str) -> None: self._process = process self._kind = kind self._next_id = 0 @@ -208,3 +214,81 @@ def _resolve(self, message: dict[str, Any]) -> None: future.set_exception(JsonRpcError(message["error"])) else: future.set_result(message.get("result")) + + +# -- the process ------------------------------------------------------------- + + +class Process: + """A CLI started by `spawn`: JSON lines on stdin and stdout.""" + + def __init__(self, proc: asyncio.subprocess.Process) -> None: + self._proc = proc + + async def write(self, data: str) -> None: + assert self._proc.stdin is not None + self._proc.stdin.write(data.encode()) + await self._proc.stdin.drain() + + async def readline(self) -> str: + assert self._proc.stdout is not None + return (await self._proc.stdout.readline()).decode() + + async def read_stderr(self) -> str: + if self._proc.stderr is None: + return "" + return (await self._proc.stderr.read()).decode(errors="replace") + + async def wait(self) -> int: + return await self._proc.wait() + + async def terminate(self) -> None: + """Stop the process group: SIGTERM, then SIGKILL.""" + if self._proc.returncode is not None: + return + with contextlib.suppress(ProcessLookupError): + os.killpg(os.getpgid(self._proc.pid), 15) + try: + async with asyncio.timeout(TERM_GRACE): + await self._proc.wait() + except TimeoutError: + with contextlib.suppress(ProcessLookupError): + os.killpg(os.getpgid(self._proc.pid), 9) + with contextlib.suppress(Exception): + await self._proc.wait() + + async def death_note(self) -> str: + """Say how the process ended, and its last words.""" + code: int | None = None + tail = "" + with contextlib.suppress(Exception): + async with asyncio.timeout(2): + code = await self.wait() + with contextlib.suppress(Exception): + async with asyncio.timeout(2): + tail = (await self.read_stderr()).strip() + how = f"exit code {code}" if code is not None else "exited" + if code in (137, -9): + how += " (SIGKILL, typically the kernel's OOM killer)" + return f"{how}; stderr: {tail[-800:]}" if tail else f"{how}; no stderr" + + +async def spawn( + argv: Sequence[str], *, cwd: str, env: Mapping[str, str] +) -> Process: + """Start a CLI in its own process group, with pipes for stdio.""" + try: + proc = await asyncio.create_subprocess_exec( + *argv, + cwd=cwd, + env={**os.environ, **env}, + stdin=asyncio.subprocess.PIPE, + stdout=asyncio.subprocess.PIPE, + stderr=asyncio.subprocess.PIPE, + # Own the whole tree, so teardown reaches grandchildren too. + start_new_session=True, + limit=LINE_LIMIT, + ) + except OSError as exc: + raise errors.WorkerError(f"cannot start {argv[0]!r}: {exc}") from exc + return Process(proc) diff --git a/src/ai/workers/_adapters/codex.py b/src/ai/workers/codex/worker.py similarity index 78% rename from src/ai/workers/_adapters/codex.py rename to src/ai/workers/codex/worker.py index 84dc8809..eba362e2 100644 --- a/src/ai/workers/_adapters/codex.py +++ b/src/ai/workers/codex/worker.py @@ -16,25 +16,27 @@ import importlib.metadata import json import os -from collections.abc import AsyncIterator -from typing import Any +from collections.abc import AsyncGenerator +from typing import Any, Literal + +import pydantic from ...types import events as events_ from ...types import messages as messages_ from ...types import usage as usage_ -from .. import _bridge +from .. import _adapter, _bridge, _convert, _handoff, _worker from .. import _errors as errors -from . import _handoff, base, jsonrpc +from . import handoff, jsonrpc KIND = "codex" INSTALL = "npm install -g @openai/codex" +# The CLI the live tests last passed against. Older ones get a warning. VERIFIED_VERSION = "0.160.1" -"""The CLI the live tests last passed against. Older ones get a warning.""" +# Put on the turn's queue when app-server dies. CRASHED = "__crashed__" -"""Put on the turn's queue when app-server dies.""" LIST_PAGE_SIZE = 100 +# `list_sessions()` reads at most this many pages of threads. LIST_PAGES = 50 -"""`list_sessions()` reads at most this many pages of threads.""" APPROVAL_METHODS = ( "item/commandExecution/requestApproval", @@ -44,6 +46,7 @@ "applyPatchApproval", ) +# Item types that are the agent doing something, rather than speaking. TOOL_ITEMS = ( "fileChange", "commandExecution", @@ -51,7 +54,6 @@ "webSearch", "toolCall", ) -"""Item types that are the agent doing something, rather than speaking.""" AUTH_HINT = ( "codex uses your own login: run `codex login`, or pass " @@ -60,56 +62,79 @@ ) -class CodexAdapter: - def __init__( - self, - *, - cwd: str, - env: dict[str, str], - executable: str, - model: str | None, - mcp_servers: dict[str, Any], - approve: base.Approve | None, - sandbox: str | None, - config: dict[str, Any], - ) -> None: +class Codex(_worker.Worker): + """Codex, over `codex app-server`. + + `sandbox` is Codex's own sandbox mode: `"read-only"`, + `"workspace-write"` or `"danger-full-access"` (the default). `config` + takes Codex `-c` overrides. + """ + + worker_class_id: Literal["codex"] = "codex" + sandbox: ( + Literal["read-only", "workspace-write", "danger-full-access"] | None + ) = None + config: dict[str, Any] = pydantic.Field(default_factory=dict) + + _config: dict[str, Any] = pydantic.PrivateAttr(default_factory=dict) + _approval_callback: _adapter.Approve | None = pydantic.PrivateAttr( + default=None + ) + _instructions: str | None = pydantic.PrivateAttr(default=None) + _process: jsonrpc.Process | None = pydantic.PrivateAttr(default=None) + _peer: jsonrpc.JsonRpcPeer | None = pydantic.PrivateAttr(default=None) + _thread: str | None = pydantic.PrivateAttr(default=None) + _turn: str | None = pydantic.PrivateAttr(default=None) + _queue: asyncio.Queue[tuple[str, dict[str, Any]]] | None = ( + pydantic.PrivateAttr(default=None) + ) + _usage: usage_.Usage = pydantic.PrivateAttr(default_factory=usage_.Usage) + _interrupted: bool = pydantic.PrivateAttr(default=False) + + @property + def _cwd(self) -> str: # Codex records a thread's directory as its real path (on macOS a # temp dir is /var/..., recorded as /private/var/..., measured). - self._cwd = os.path.realpath(cwd) - self._env = env - self._executable = executable - self._model = model - self._approve = approve - # Full access by default, like claude without a gate: a worker is - # driven by a program, and a mode that silently refuses writes reads - # as an agent that did nothing. - self._sandbox = sandbox or "danger-full-access" - # Passed to app-server as `-c key=value`, the overrides the codex - # CLI takes. An explicit config wins over the MCP servers. - self._config = {**mcp_config(mcp_servers), **config} - self._instructions: str | None = None - self._process: base.Process | None = None - self._peer: jsonrpc.JsonRpcPeer | None = None - self._thread: str | None = None - self._turn: str | None = None - self._queue: asyncio.Queue[tuple[str, dict[str, Any]]] | None = None - self._usage = usage_.Usage() - self._interrupted = False - self.version: str | None = None + return os.path.realpath(self.cwd) + + @property + def _executable(self) -> str: + return self.executable or "codex" + + def _codex_config( + self, mcp_servers: dict[str, dict[str, Any]] + ) -> dict[str, Any]: + config = dict(self.config) + if self.effort is not None: + config.setdefault( + "model_reasoning_effort", + "xhigh" if self.effort == "max" else self.effort, + ) + if _bridge.SERVER_NAME in mcp_servers: + # An ai.Agent tool may wait for approval longer than Codex's + # default MCP tool timeout (60 seconds). + config.setdefault( + f"mcp_servers.{_bridge.SERVER_NAME}.tool_timeout_sec", + 24 * 3600, + ) + # Explicit config wins over the MCP server settings. + return {**mcp_config(mcp_servers), **config} - async def start(self) -> None: - self.version = await base.probe( + async def _cli_start(self, mcp_servers: dict[str, dict[str, Any]]) -> None: + self._config = self._codex_config(mcp_servers) + self._approval_callback = self._approve if self.approve else None + self._cli_version = await _adapter.probe( KIND, self._executable, install=INSTALL, verified=VERIFIED_VERSION, cwd=self._cwd, - env=self._env, + env=self.env, ) - self._process = await base.spawn( + self._process = await jsonrpc.spawn( [self._executable, "app-server", *_config_args(self._config)], cwd=self._cwd, - env=self._env, + env=self.env, ) self._peer = jsonrpc.JsonRpcPeer(self._process, kind=KIND) self._peer.start( @@ -130,10 +155,10 @@ async def start(self) -> None: await self._peer.notify("initialized") except BaseException: # A failed handshake must not leave the server running. - await self.close() + await self._cli_close() raise - async def close(self) -> None: + async def _cli_close(self) -> None: if self._peer is not None: await self._peer.close() self._peer = None @@ -141,6 +166,12 @@ async def close(self) -> None: with contextlib.suppress(Exception): await self._process.terminate() self._process = None + self._thread = None + self._turn = None + self._queue = None + self._instructions = None + self._approval_callback = None + self._config = {} def _rpc(self) -> jsonrpc.JsonRpcPeer: if self._peer is None: @@ -154,12 +185,14 @@ def _thread_params(self) -> dict[str, Any]: with, like a person's TUI asking for approvals nobody here answers. """ return { - "sandbox": self._sandbox, + "sandbox": (self.sandbox or "danger-full-access"), # With a gate: ask about everything the policy can ask about. # Without one the server never asks: a request nobody answers # would freeze the agent (measured). - "approvalPolicy": "untrusted" if self._approve else "never", - **({"model": self._model} if self._model else {}), + "approvalPolicy": "untrusted" + if self._approval_callback + else "never", + **({"model": self.model_name} if self.model_name else {}), **( {"developerInstructions": self._instructions} if self._instructions @@ -169,7 +202,7 @@ def _thread_params(self) -> dict[str, Any]: # -- the conversation ----------------------------------------------------- - async def open( + async def _cli_open( self, *, session_id: str | None, @@ -206,7 +239,7 @@ async def open( _handoff.warn_unsupported_files(seed, KIND) await self._rpc().call( "thread/inject_items", - {"threadId": thread, "items": _handoff.to_codex_items(seed)}, + {"threadId": thread, "items": handoff.to_codex_items(seed)}, ) return thread @@ -256,12 +289,12 @@ def _on_crash(self, exc: BaseException) -> None: async def _on_request( self, request_id: Any, method: str, params: dict[str, Any] ) -> None: - if method not in APPROVAL_METHODS or self._approve is None: + if method not in APPROVAL_METHODS or self._approval_callback is None: # Unknown, or unasked for: answer rather than hang the agent. decision = "accept" if method in APPROVAL_METHODS else "decline" await self._rpc().respond(request_id, {"decision": decision}) return - granted, _ = await self._approve( + granted, _ = await self._approval_callback( str(params.get("itemId") or params.get("callId") or ""), _approval_tool_name(method), { @@ -277,8 +310,10 @@ async def _on_request( # -- turns ---------------------------------------------------------------- - async def turn(self, prompt: base.Prompt) -> AsyncIterator[events_.Event]: - base.check_files(prompt, KIND, ("image/",)) + async def _cli_turn( + self, prompt: _adapter.Prompt + ) -> AsyncGenerator[events_.Event]: + _convert.check_files(prompt, KIND, ("image/",)) # Unbounded: the reader fills it inline and must never wait on a # slow consumer. queue: asyncio.Queue[tuple[str, dict[str, Any]]] = asyncio.Queue() @@ -305,6 +340,10 @@ async def turn(self, prompt: base.Prompt) -> AsyncIterator[events_.Event]: # The turn id comes from the RESPONSE: this server sends no # `turn/started`, and steer and interrupt need the id. turn = ((begun or {}).get("turn") or {}).get("id") + if not isinstance(turn, str) or not turn: + raise errors.WorkerError( + f"{KIND}: turn/start gave no id: {begun}" + ) self._turn = turn yield events_.StreamStart() while True: @@ -366,14 +405,14 @@ async def turn(self, prompt: base.Prompt) -> AsyncIterator[events_.Event]: open_reasoning.discard(item_id) yield events_.ReasoningEnd(block_id=item_id) elif kind in TOOL_ITEMS: - for event in base.builtin_call( + for event in _convert.builtin_call( item_id, _tool_name(item), json.dumps(_tool_args(item)), started=started, ): yield event - yield base.builtin_result( + yield _convert.builtin_result( item_id, _tool_name(item), _item_result(item), @@ -409,9 +448,11 @@ async def turn(self, prompt: base.Prompt) -> AsyncIterator[events_.Event]: self._queue = None self._turn = None - async def steer(self, text: str) -> None: - if not self._turn: - raise errors.WorkerError(f"{KIND}: no turn is running to steer") + async def _cli_send_running(self, prompt: _adapter.Prompt) -> bool: + turn = self._turn + if turn is None: + return False + _convert.check_files(prompt, KIND, ("image/",)) try: await self._rpc().call( "turn/steer", @@ -419,14 +460,25 @@ async def steer(self, text: str) -> None: "threadId": self._thread, # A precondition: steering the wrong turn is worse than # failing to steer. - "expectedTurnId": self._turn, - "input": [{"type": "text", "text": text}], + "expectedTurnId": turn, + "input": await _input_items(prompt), }, ) except jsonrpc.JsonRpcError as exc: + # The turn may finish after we capture its id, even before its + # completion notification is consumed. Only this explicit CLI + # rejection confirms that the prompt was NOT accepted and no + # turn is running. Never retry timeouts, transport failures, + # mismatched turn ids, or other rejections as a new turn. + if exc.code == -32600 and str(exc) in ( + "no active turn", + "no active turn to steer", + ): + return False raise errors.WorkerError(f"{KIND}: steer rejected: {exc}") from exc + return True - async def interrupt(self) -> None: + async def _cli_interrupt(self) -> None: self._interrupted = True if not self._turn or self._peer is None: return @@ -439,20 +491,20 @@ async def interrupt(self) -> None: # -- the store ------------------------------------------------------------ - async def history(self, session_id: str) -> list[messages_.Message]: + async def _cli_history(self, session_id: str) -> list[messages_.Message]: """Read the thread's stored record, every item included.""" await self._require_here(session_id) result = await self._rpc().call( "thread/read", {"threadId": session_id, "includeTurns": True, "itemsView": "full"}, ) - stored: list[messages_.Message] = [] + out: list[messages_.Message] = [] for turn in ((result or {}).get("thread") or {}).get("turns") or []: for item in turn.get("items") or []: - stored.extend(_item_to_messages(item)) - return _handoff.model_view(stored) + out.extend(_item_to_messages(item)) + return out - async def list_sessions(self) -> list[base.SessionInfo]: + async def _cli_list_sessions(self) -> list[_adapter.SessionInfo]: # Asked for THIS directory, page by page: one unfiltered page of the # machine's store (measured: 3159 threads) missed threads from here. threads: list[dict[str, Any]] = [] @@ -471,7 +523,7 @@ async def list_sessions(self) -> list[base.SessionInfo]: if not cursor: break return [ - base.SessionInfo( + _adapter.SessionInfo( session_id=t.get("id", ""), title=t.get("name") or t.get("preview") or None, cwd=t.get("cwd"), @@ -482,12 +534,12 @@ async def list_sessions(self) -> list[base.SessionInfo]: if t.get("id") and t.get("cwd") in (None, self._cwd) ] - def tui_command( + def _cli_tui_command( self, session_id: str | None ) -> tuple[list[str], dict[str, str], str | None]: config = { k: v - for k, v in self._config.items() + for k, v in self._codex_config(self.mcp_servers).items() if not k.startswith(f"mcp_servers.{_bridge.SERVER_NAME}.") } # --disable in_app_updates: measured, the TUI otherwise opens on an @@ -499,15 +551,15 @@ def tui_command( "in_app_updates", *_config_args(config), ] - if self._model: - argv += ["--model", self._model] + if self.model_name: + argv += ["--model", self.model_name] if self._instructions: argv += _config_args({"developer_instructions": self._instructions}) # None: codex mints its own thread id. - return argv, dict(self._env), None + return argv, dict(self.env), None -async def _input_items(prompt: base.Prompt) -> list[dict[str, Any]]: +async def _input_items(prompt: _adapter.Prompt) -> list[dict[str, Any]]: """Return a prompt as app-server's `UserInput` items. An image travels as a data URL, built here from its bytes. @@ -517,9 +569,11 @@ async def _input_items(prompt: base.Prompt) -> list[dict[str, Any]]: if isinstance(part, messages_.TextPart): items.append({"type": "text", "text": part.text}) elif part.media_type.startswith("text/"): - items.append({"type": "text", "text": await base.as_text(part)}) + items.append({"type": "text", "text": await _convert.as_text(part)}) else: - encoded = base64.b64encode(await base.data(part)).decode("ascii") + encoded = base64.b64encode(await _convert.data(part)).decode( + "ascii" + ) items.append( { "type": "image", @@ -581,7 +635,11 @@ def _reasoning_text(item: dict[str, Any]) -> str: def _item_to_messages(item: dict[str, Any]) -> list[messages_.Message]: - """One stored thread item -> messages, CLI tools as tool calls.""" + """One stored thread item -> messages, shaped like a live turn's. + + A tool item holds the call and its result: one assistant message with + both, as built-in parts. + """ kind = item.get("type") if kind == "userMessage": # A user item carries `content` blocks, its `UserInput`s. @@ -615,21 +673,18 @@ def _item_to_messages(item: dict[str, Any]) -> list[messages_.Message]: ) ] if kind in TOOL_ITEMS: - call = messages_.ToolCallPart( + call = messages_.BuiltinToolCallPart( tool_call_id=item.get("id", ""), tool_name=_tool_name(item), tool_args=json.dumps(_tool_args(item)), ) - result = messages_.ToolResultPart( - tool_call_id=item.get("id", ""), + result = messages_.BuiltinToolReturnPart( + tool_call_id=call.tool_call_id, tool_name=call.tool_name, result=_item_result(item), - result_kind="error" if item.get("status") == "failed" else "json", + is_error=item.get("status") == "failed", ) - return [ - messages_.Message(role="assistant", parts=[call]), - messages_.Message(role="tool", parts=[result]), - ] + return [messages_.Message(role="assistant", parts=[call, result])] return [] diff --git a/src/ai/workers/pi/__init__.py b/src/ai/workers/pi/__init__.py new file mode 100644 index 00000000..af788365 --- /dev/null +++ b/src/ai/workers/pi/__init__.py @@ -0,0 +1,3 @@ +from .worker import Pi + +__all__ = ["Pi"] diff --git a/src/ai/workers/pi/extension.js b/src/ai/workers/pi/extension.js new file mode 100644 index 00000000..164712c0 --- /dev/null +++ b/src/ai/workers/pi/extension.js @@ -0,0 +1,88 @@ +// Loaded into every `pi` the ai-python SDK launches (`pi -e `). +// It does nothing on its own: AI_PYTHON_PI, a JSON object in the +// environment, says which of its three jobs this process needs. +// +// - "approve": ask the SDK about every tool call. pi has no permission +// channel of its own; an extension's `tool_call` handler is the gate, and +// an RPC dialog (`ctx.ui.input`) is how it reaches the SDK. The answer is +// a JSON decision: allow (optionally with rewritten input) or deny. +// - "mcp": MCP servers, registered for this session only. +// - "gateway": the Vercel AI Gateway, reached with `Authorization: Bearer` +// rather than the `x-api-key` header pi's provider sends, so a sandbox +// firewall that rewrites `Authorization` can inject the credential. +// `baseUrl` moves the provider when the gateway is not the default one. +const APPROVE = "ai-python:approve"; +// Registered LAST: its presence in `get_commands` is how the SDK knows every +// part above loaded — above all the approval gate. No marker, no session. +const READY = "ai-python-ready"; + +export default function (pi) { + // Unparseable configuration fails the load (and so the session) rather + // than reading as "no approval asked for". + const config = JSON.parse(process.env.AI_PYTHON_PI || "{}") || {}; + + if (config.approve) { + pi.on("tool_call", async (event, ctx) => { + const answer = await ctx.ui.input( + APPROVE, + JSON.stringify({ + toolCallId: event.toolCallId, + parentToolCallId: event.parentToolCallId, + toolName: event.toolName, + input: event.input, + }), + ); + let decision = null; + try { + decision = JSON.parse(answer ?? ""); + } catch { + decision = null; + } + if (decision && decision.decision === "allow") { + if (decision.input && typeof decision.input === "object") { + // pi reads the arguments from this object after the handler: + // rewrite it in place. + for (const key of Object.keys(event.input)) delete event.input[key]; + Object.assign(event.input, decision.input); + } + return undefined; + } + return { + block: true, + // No answer: the SDK withdrew the question (the turn was stopped). + reason: + answer === undefined + ? "the approval was withdrawn" + : (decision && decision.reason) || "denied by policy", + ...(decision && decision.stop ? { terminate: true } : {}), + }; + }); + } + + for (const [name, server] of Object.entries(config.mcp || {})) { + pi.registerMcpServer(name, server); + } + + const gateway = config.gateway; + if (gateway) { + if (gateway.baseUrl) { + pi.registerProvider("vercel-ai-gateway", { baseUrl: gateway.baseUrl }); + } + pi.on("before_provider_headers", (event, ctx) => { + if (ctx.model?.provider !== "vercel-ai-gateway") return; + for (const key of Object.keys(event.headers)) { + const lower = key.toLowerCase(); + if (lower === "x-api-key" || lower === "authorization") { + event.headers[key] = null; + } + } + event.headers["authorization"] = + "Bearer " + (process.env.AI_GATEWAY_API_KEY || ""); + }); + } + + pi.registerCommand(READY, { + description: "Marks the ai-python SDK's extension as loaded", + handler: async () => {}, + }); +} diff --git a/src/ai/workers/pi/handoff.py b/src/ai/workers/pi/handoff.py new file mode 100644 index 00000000..65b94e39 --- /dev/null +++ b/src/ai/workers/pi/handoff.py @@ -0,0 +1,167 @@ +"""Seeding pi with a past: `AgentMessage`s for a session file. + +The rule for what becomes what is the same for every CLI: see `_handoff`. +""" + +from __future__ import annotations + +import json +from typing import Any + +from ...types import media +from ...types import messages as messages_ +from .. import _handoff + +# What names a reply's author in a pi session: its API and model. +AUTHOR = ("api", "provider", "model") +SYSTEM_PREFIX = "[Handoff from a previous session — instructions it was given: " + + +def to_pi_messages( + messages: list[messages_.Message], *, timestamp: int +) -> list[dict[str, Any]]: + """Build pi `AgentMessage`s for a session file. + + Assistant messages pi wrote keep their author (`provider_metadata["pi"]`): + pi restores a session's model from it. Any other is attributed to a + model pi does not run (`ai-python/handoff`), so pi treats it as another + model's — it keeps its text and tool calls and normalizes the call ids + for its own provider. Consecutive assistant messages are merged, the way one + model response holds text and calls together. Reasoning is omitted: see + the module docstring. + """ + out: list[dict[str, Any]] = [] + usage = { + "input": 0, + "output": 0, + "cacheRead": 0, + "cacheWrite": 0, + "totalTokens": 0, + "cost": { + "input": 0, + "output": 0, + "cacheRead": 0, + "cacheWrite": 0, + "total": 0, + }, + } + + def result(call_id: str, name: str, value: Any, *, is_error: bool) -> None: + out.append( + { + "role": "toolResult", + "toolCallId": call_id, + "toolName": name, + "content": [ + {"type": "text", "text": _handoff.result_text(value)} + ], + "isError": is_error, + "timestamp": timestamp, + } + ) + + def add(m: messages_.Message, blocks: list[dict[str, Any]]) -> None: + if not blocks: + return + if m.role == "system": + # Measured (pi 1.3.0): a system message in a session file is + # pi's own prompt state, and replaying one REPLACED pi's system + # prompt and its tools. So instructions travel as what they are + # to the agent — the caller's words — never as its own output. + text = " ".join(b["text"] for b in blocks if b["type"] == "text") + blocks = [{"type": "text", "text": SYSTEM_PREFIX + text + "]"}] + if m.role in ("user", "system"): + out.append( + {"role": "user", "content": blocks, "timestamp": timestamp} + ) + return + if out and out[-1]["role"] == "assistant": + out[-1]["content"] += blocks + else: + # A reply pi wrote keeps its author: pi restores a session's model + # from its last reply's, and a model it does not know (ours) + # put the conversation on pi's default one (measured). + author = (m.provider_metadata or {}).get("pi") or {} + known = all(isinstance(author.get(k), str) for k in AUTHOR) + out.append( + { + "role": "assistant", + "content": blocks, + **( + {k: author[k] for k in AUTHOR} + if known + else { + "api": "ai-python", + "provider": "ai-python", + "model": "handoff", + } + ), + "usage": usage, + "stopReason": "stop", + "timestamp": timestamp, + } + ) + if any(b["type"] == "toolCall" for b in out[-1]["content"]): + out[-1]["stopReason"] = "toolUse" + + for m in messages: + blocks: list[dict[str, Any]] = [] + for p in m.parts: + if isinstance(p, messages_.ToolResultPart): + # A tool an `ai.Agent` ran: its result is in a `tool` message. + result( + p.tool_call_id, + p.tool_name, + p.result, + is_error=p.result_kind == "error", + ) + elif isinstance(p, messages_.BuiltinToolReturnPart): + # A tool the CLI ran: the worker holds its result in the + # assistant message, pi as a message of its own. So the + # assistant message ends here, and the result follows. + add(m, blocks) + blocks = [] + result( + p.tool_call_id, p.tool_name, p.result, is_error=p.is_error + ) + elif isinstance(p, messages_.TextPart) and p.text.strip(): + blocks.append({"type": "text", "text": p.text}) + elif ( + isinstance(p, messages_.FilePart) + and m.role == "user" + and p.media_type.startswith("image/") + ): + if isinstance(p.data, str) and media.is_downloadable_url( + p.data + ): + blocks.append( + {"type": "text", "text": f"[image: {p.data}]"} + ) + else: + blocks.append( + { + "type": "image", + "data": media.data_to_base64(p.data), + "mimeType": p.media_type, + } + ) + elif ( + isinstance( + p, messages_.ToolCallPart | messages_.BuiltinToolCallPart + ) + and m.role == "assistant" + ): + try: + args = json.loads(p.tool_args) if p.tool_args else {} + except json.JSONDecodeError: + args = {"raw": p.tool_args} + blocks.append( + { + "type": "toolCall", + "id": p.tool_call_id or p.id, + "name": p.tool_name, + "arguments": args if isinstance(args, dict) else {}, + } + ) + add(m, blocks) + return out diff --git a/src/ai/workers/pi/worker.py b/src/ai/workers/pi/worker.py new file mode 100644 index 00000000..f0d3e581 --- /dev/null +++ b/src/ai/workers/pi/worker.py @@ -0,0 +1,1297 @@ +"""Pi, driven through `pi --mode rpc`. + +One pi process per conversation: an RPC process holds one session. The id we +hand pi (`--session-id`) IS its session id, so `pi --session-id ` opens +the same conversation in pi's own TUI. + +pi has no permission prompt. Approval is an extension loaded into every pi +a worker starts (`extension.js`): its `tool_call` handler asks through an +RPC dialog, and the worker answers it. The protocol shapes here were +measured against a real pi (see VERIFIED_VERSION). +""" + +from __future__ import annotations + +import asyncio +import base64 +import contextlib +import datetime +import json +import os +import pathlib +import re +import uuid +import warnings +from collections.abc import AsyncGenerator, Mapping, Sequence +from typing import Any, Literal + +import pydantic + +from ...types import events as events_ +from ...types import messages as messages_ +from ...types import usage as usage_ +from .. import _adapter, _bridge, _convert, _handoff, _worker +from .. import _errors as errors +from . import handoff + +KIND = "pi" +INSTALL = "npm install -g @earendil-works/pi-coding-agent" +# The CLI the live tests last passed against. Older ones get a warning. +VERIFIED_VERSION = "1.3.0" +EXTENSION = str(pathlib.Path(__file__).with_name("extension.js")) +# The dialog title the extension asks approvals under. +APPROVE = "ai-python:approve" +# The command the extension registers last: proof that it loaded. +READY = "ai-python-ready" +# The environment variable that configures the extension. +CONFIG_VAR = "AI_PYTHON_PI" +# pi's rule for a session id: letters, digits, `.`, `_` and `-`, starting and +# ending with a letter or digit. Never a path. +SESSION_ID = re.compile(r"[A-Za-z0-9](?:[A-Za-z0-9._-]{0,198}[A-Za-z0-9])?\Z") +# Extension UI methods that wait for an answer; the rest are notices. +DIALOGS = ("select", "confirm", "input", "editor") +CRASHED = "__crashed__" +CLOSED = "__closed__" + +# Longest line pi may write. The protocol is JSON lines, and one line can be +# megabytes. With asyncio's default (64 KiB) such a line fails as if the CLI had +# crashed. +LINE_LIMIT = 256 * 1024 * 1024 + +# Seconds pi gets to exit after SIGTERM, before SIGKILL. +TERM_GRACE = 3.0 + +AUTH_HINT = ( + "pi uses its own login (`/login`, auth.json) or a provider key in the " + "environment: pass env={'ANTHROPIC_API_KEY': ...}." +) + + +class Pi(_worker.Worker): + """Pi, over `pi --mode rpc`. + + `allowed_tools` limits pi's own tools (`["read", "grep"]`, or `[]` for + none), and `disallowed_tools` takes some away. + """ + + worker_class_id: Literal["pi"] = "pi" + allowed_tools: list[str] | None = None + disallowed_tools: list[str] | None = None + + _mcp_servers: dict[str, dict[str, Any]] = pydantic.PrivateAttr( + default_factory=dict + ) + _approval_callback: _adapter.Approve | None = pydantic.PrivateAttr( + default=None + ) + _instructions: str | None = pydantic.PrivateAttr(default=None) + _agent: _Agent | None = pydantic.PrivateAttr(default=None) + _interrupted: bool = pydantic.PrivateAttr(default=False) + _running: bool = pydantic.PrivateAttr(default=False) + # Serialize input acceptance with consuming the final agent_settled. + _input_lock: asyncio.Lock = pydantic.PrivateAttr( + default_factory=asyncio.Lock + ) + _continued_runs: int = pydantic.PrivateAttr(default=0) + _settled_count: int = pydantic.PrivateAttr(default=0) + + @property + def _executable(self) -> str: + return self.executable or "pi" + + async def _cli_start(self, mcp_servers: dict[str, dict[str, Any]]) -> None: + self._mcp_servers = dict(mcp_servers) + self._approval_callback = self._approve if self.approve else None + self._cli_version = await _adapter.probe( + KIND, + self._executable, + install=INSTALL, + verified=VERIFIED_VERSION, + cwd=self.cwd, + env=self.env, + ) + + async def _cli_close(self) -> None: + agent, self._agent = self._agent, None + self._running = False + self._continued_runs = 0 + self._instructions = None + self._approval_callback = None + self._mcp_servers = {} + if agent is not None: + await agent.close() + with contextlib.suppress(Exception): + await agent.process.terminate() + + def _args(self) -> list[str]: + """How pi runs: headless and in the TUI alike.""" + args = ["-e", EXTENSION] + if self.model_name: + args += ["--model", self.model_name] + if self.effort: + args += ["--thinking", self.effort] + if self._instructions: + args += ["--append-system-prompt", self._instructions] + if self.allowed_tools is not None: + args += ( + ["--tools", ",".join(self.allowed_tools)] + if self.allowed_tools + else ["--no-tools"] + ) + if self.disallowed_tools: + args += ["--exclude-tools", ",".join(self.disallowed_tools)] + return args + + def _extension_env( + self, *, approve: bool, servers: dict[str, Any] + ) -> dict[str, str]: + config: dict[str, Any] = {"approve": approve} + if servers: + config["mcp"] = mcp_config(servers) + return {**self.env, CONFIG_VAR: json.dumps(config)} + + # -- the conversation ----------------------------------------------------- + + async def _cli_open( + self, + *, + session_id: str | None, + fork: bool, + seed: list[messages_.Message] | None, + instructions: str | None, + ) -> str: + self._instructions = instructions + if seed: + session_id = await self._stage(seed) + args = ["--session-id", session_id] + elif session_id is not None: + # Checked first: `--session-id` CREATES a session it cannot + # find, so a typo would silently start an empty conversation. + found = await self._find(session_id) + if fork: + session_id = str(uuid.uuid4()) + # By path, not id: pi matches a partial id, a path is exact. + args = ["--fork", found["path"], "--session-id", session_id] + else: + args = ["--session-id", session_id] + else: + session_id = str(uuid.uuid4()) + args = ["--session-id", session_id] + await self._spawn(session_id, args) + return session_id + + async def _spawn(self, session_id: str, args: list[str]) -> None: + """Start pi on one conversation and wait until it answers. + + A pi that cannot start (an unknown model, a bad flag) exits at once, + and the handshake reports its last words. + """ + process = await spawn( + [self._executable, "--mode", "rpc", *args, *self._args()], + cwd=self.cwd, + env=self._extension_env( + approve=self._approval_callback is not None, + servers=self._mcp_servers, + ), + ) + agent = _Agent(process, on_dialog=self._on_dialog) + agent.start() + try: + state = await agent.call({"type": "get_state"}, timeout=60) + reported = (state or {}).get("sessionId") + if reported and reported != session_id: + raise errors.WorkerError( + f"{KIND} opened session {reported}, not {session_id}" + ) + # The approval gate must be there before any work is accepted: + # a gate that failed to load is a gate that fails open. + listed = await agent.call({"type": "get_commands"}, timeout=60) + names = { + c.get("name") for c in (listed or {}).get("commands") or [] + } + if READY not in names: + raise errors.WorkerError( + f"{KIND} did not load the SDK's extension ({EXTENSION}); " + "refusing to run without it" + ) + except BaseException: + await agent.close() + with contextlib.suppress(Exception): + await process.terminate() + raise + self._agent = agent + + async def _stage(self, history: list[messages_.Message]) -> str: + """Write a session file with this past; start nothing on it.""" + session_id = str(uuid.uuid4()) + _handoff.warn_unsupported_files(history, KIND) + dropped = _handoff.reasoning_count(history) + if dropped: + # pi drops thinking another model produced, and replaying it as + # user text is refused by Anthropic's safeguards. + warnings.warn( + f"{dropped} reasoning part(s) in the history were not carried " + "into pi: a model only reads its own reasoning. Text, tool " + "calls and images were carried in full.", + stacklevel=2, + ) + directory = self._session_dir() + now = datetime.datetime.now(datetime.UTC) + stamp = now.isoformat(timespec="milliseconds").replace("+00:00", "Z") + lines: list[dict[str, Any]] = [ + { + "type": "session", + "version": 3, + "id": session_id, + "timestamp": stamp, + "cwd": os.path.realpath(self.cwd), + } + ] + parent: str | None = None + # The model the conversation was on, as pi records a switch: pi + # restores a session's model from its last reply's author. Measured: + # without it, a seeded conversation ran on pi's default model. + written: dict[str, Any] = next( + ( + found + for m in reversed(history) + if m.role == "assistant" + and isinstance( + found := (m.provider_metadata or {}).get(KIND), dict + ) + ), + {}, + ) + changes: list[dict[str, Any]] = [] + if written.get("provider") and written.get("model"): + changes.append( + { + "type": "model_change", + "provider": written["provider"], + "modelId": written["model"], + } + ) + if written.get("thinkingLevel"): + changes.append( + { + "type": "thinking_level_change", + "thinkingLevel": written["thinkingLevel"], + } + ) + entries = [ + *changes, + *( + {"type": "message", "message": message} + for message in handoff.to_pi_messages( + history, timestamp=int(now.timestamp() * 1000) + ) + ), + ] + for entry in entries: + entry_id = uuid.uuid4().hex[:8] + lines.append( + { + **entry, + "id": entry_id, + "parentId": parent, + "timestamp": stamp, + } + ) + parent = entry_id + name = stamp.replace(":", "-").replace(".", "-") + path = directory / f"{name}_{session_id}.jsonl" + text = "".join(json.dumps(line) + "\n" for line in lines) + + def write() -> None: + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(text) + + await asyncio.to_thread(write) + return session_id + + # -- approval ------------------------------------------------------------- + + async def _on_dialog(self, agent: _Agent, request: dict[str, Any]) -> None: + if request.get("method") not in DIALOGS: + return # a notice: nothing waits for an answer + reply: dict[str, Any] = { + "type": "extension_ui_response", + "id": request.get("id"), + } + if ( + request.get("method") != "input" + or request.get("title") != APPROVE + or self._approval_callback is None + or self._interrupted + ): + # Another extension asking a person, who is not there; or the + # turn is being stopped, and `abort` would wait on the question. + agent.pending.pop(str(request.get("id")), None) + await agent.send({**reply, "cancelled": True}) + return + try: + payload = json.loads(request.get("placeholder") or "{}") + except json.JSONDecodeError: + payload = {} + granted, reason = await self._approval_callback( + str(payload.get("toolCallId") or ""), + str(payload.get("toolName") or ""), + dict(payload.get("input") or {}), + ) + decision = ( + {"decision": "allow"} + if granted + else {"decision": "deny", "reason": reason} + ) + # Answered from here on: `dismiss` must not withdraw it too. + agent.pending.pop(str(request.get("id")), None) + await agent.send({**reply, "value": json.dumps(decision)}) + + # -- turns ---------------------------------------------------------------- + + async def _cli_turn( + self, prompt: _adapter.Prompt + ) -> AsyncGenerator[events_.Event]: + _convert.check_files(prompt, KIND, ("image/",)) + agent = self._agent + assert agent is not None + if agent.dead is not None: + raise errors.WorkerError(f"{KIND} crashed: {agent.dead}") + # What the last turn left behind (a stopped turn's tail) is not this + # turn's: `abort` answers only once pi is idle, so it has all arrived. + while not agent.events.empty(): + agent.events.get_nowait() + self._interrupted = False + self._continued_runs = 0 + self._settled_count = agent.settled_count + command = await _prompt_command(prompt) + runs_started = agent.runs_started + try: + accepted = await agent.call(command) + except _CommandError as exc: + raise errors.turn_failed(KIND, str(exc), AUTH_HINT) from exc + if (accepted or {}).get("disposition") == "handled": + # An extension command consumed it. It may start a run of its own + # (measured: then pi is already streaming, and that run is ours). + state = await agent.call({"type": "get_state"}) + if ( + not (state or {}).get("isStreaming") + and agent.runs_started == runs_started + ): + yield events_.StreamStart() + yield events_.StreamEnd(finish_reason="stop") + return + self._running = True + usage = usage_.Usage() + cost = 0.0 + started: set[str] = set() + streamed: set[str] = set() + open_blocks: dict[str, str] = {} + message_no = 0 + last: dict[str, Any] = {} + retry_error = "" + settled: dict[str, Any] = {} + try: + yield events_.StreamStart() + while True: + event = await agent.events.get() + kind = event.get("type") + if kind == CRASHED: + raise errors.WorkerError( + f"{KIND} crashed: {event.get('detail')}" + ) + if kind == CLOSED: + raise errors.WorkerError( + f"{KIND}: the worker closed while its turn ran" + ) + message = event.get("message") or {} + if kind == "message_start" and message.get("role") == ( + "assistant" + ): + message_no += 1 + elif kind == "message_update": + for out in _stream_events( + event.get("assistantMessageEvent") or {}, + f"{message_no}", + open_blocks, + started, + ): + if isinstance( + out, events_.TextStart | events_.ReasoningStart + ): + streamed.add(out.block_id) + yield out + elif kind == "message_end" and message.get("role") == ( + "assistant" + ): + last = message + raw = message.get("usage") or {} + usage = usage + _usage(raw) + cost += float((raw.get("cost") or {}).get("total") or 0) + for out in _close_blocks(open_blocks): + yield out + if message.get("stopReason") != "error": + # What the message holds that was never streamed (a + # run an extension command started, measured). + for out in _unstreamed( + message.get("content"), + f"{message_no}", + streamed, + started, + ): + yield out + elif kind == "tool_execution_end" and not event.get( + "parentToolCallId" + ): + # A nested call (a codemode script's) is not in the + # transcript: only the tool that made it reports it. + call_id = str(event.get("toolCallId") or "") + name = str(event.get("toolName") or "") + yield _convert.builtin_result( + call_id, + name, + _tool_result(event.get("result") or {}), + is_error=bool(event.get("isError")), + ) + elif kind == "auto_retry_end" and not event.get("success"): + retry_error = str(event.get("finalError") or "") + elif kind == "agent_settled": + async with self._input_lock: + self._settled_count += 1 + if self._continued_runs: + # An input raced this completion and started a + # new native run. Its events are already queued; + # keep this reader alive to consume them once. + self._continued_runs -= 1 + continue + self._running = False + settled = event + break + finally: + self._running = False + interrupted = self._interrupted or bool(settled.get("aborted")) + self._interrupted = False + stop = last.get("stopReason") + if stop == "error" and not interrupted: + raise errors.turn_failed( + KIND, + str(last.get("errorMessage") or retry_error), + AUTH_HINT, + ) + yield events_.StreamEnd( + # Cost has no home in Usage; pi's own number rides in `raw`. + usage=usage.model_copy(update={"raw": {"cost_usd": cost}}), + finish_reason=( + "cancelled" + if interrupted or stop == "aborted" + else "length" + if stop == "length" + else "stop" + ), + provider_metadata=_written_by(last), + ) + + async def _cli_send_running(self, prompt: _adapter.Prompt) -> bool: + """Accept input without stranding a steer on a just-finished run.""" + _convert.check_files(prompt, KIND, ("image/",)) + command = await _prompt_command(prompt) + async with self._input_lock: + agent = self._agent + if agent is None: + raise errors.WorkerError(f"{KIND}: RPC process is not running") + state = await agent.call({"type": "get_state"}) + if (state or {}).get("isStreaming") is False: + # No input was submitted. The base can finish draining the + # old turn and submit this prompt as a new one. + return False + if not self._running: + raise errors.WorkerError( + f"{KIND}: no turn reader for the running CLI" + ) + try: + # `steer` queues even when idle. `prompt` chooses atomically + # between queueing and starting, including after async input + # hooks. Never clear_queue: it returns text only, losing files. + accepted = await agent.call( + {**command, "streamingBehavior": "steer"} + ) + except _CommandError as exc: + raise errors.turn_failed(KIND, str(exc), AUTH_HINT) from exc + disposition = (accepted or {}).get("disposition") + if disposition == "started": + self._continued_runs += 1 + elif disposition == "handled": + # Extension commands may start independent work, even after + # the old run settled. Follow it, including fast completions. + state = await agent.call({"type": "get_state"}) + latest = agent.last_start_settled + if (state or {}).get("isStreaming"): + latest = max(latest, agent.settled_count) + self._continued_runs = max( + self._continued_runs, latest - self._settled_count + ) + elif disposition != "queued": + # An ambiguous acceptance must never be retried as a new turn. + raise errors.WorkerError( + f"{KIND}: unknown prompt disposition: {accepted}" + ) + return True + + async def _cli_interrupt(self) -> None: + self._interrupted = True + agent = self._agent + if agent is None or agent.dead is not None: + return + # A tool call waiting on approval keeps pi busy, and `abort` only + # answers once pi is idle (measured: the turn ran on). Withdraw the + # question first: the call is denied, and the abort lands at once. + await agent.dismiss() + with contextlib.suppress(Exception): + await agent.call({"type": "abort"}, timeout=30) + + # -- the store ------------------------------------------------------------ + + def _session_dir(self) -> pathlib.Path: + """Where pi keeps this directory's sessions, decided as pi does. + + The environment, then project settings, then global ones; else one + directory per working directory under the agent dir. + """ + env = {**os.environ, **self.env} + cwd = os.path.realpath(self.cwd) + agent = pathlib.Path( + os.path.expanduser(env.get("PI_CODING_AGENT_DIR") or "~/.pi/agent") + ) + custom = ( + env.get("PI_CODING_AGENT_SESSION_DIR") + or _setting(pathlib.Path(cwd, ".pi", "settings.json")) + or _setting(agent / "settings.json") + ) + if custom: + return pathlib.Path(cwd, os.path.expanduser(custom)) + safe = cwd.lstrip("/\\") + for c in "/\\:": + safe = safe.replace(c, "-") + return agent / "sessions" / f"--{safe}--" + + def _scan(self, *, titles: bool) -> list[dict[str, Any]]: + """Describe the sessions of this directory, newest first.""" + directory = self._session_dir() + cwd = os.path.realpath(self.cwd) + out: list[dict[str, Any]] = [] + try: + paths = sorted(directory.glob("*.jsonl")) + except OSError: + return [] + for path in paths: + with contextlib.suppress(Exception): + info = _describe(path, (cwd, self.cwd), titles=titles) + if info is not None: + out.append(info) + return sorted(out, key=lambda s: -s["updated"]) + + async def _find(self, session_id: str) -> dict[str, Any]: + if not SESSION_ID.match(session_id): + raise errors.WorkerError( + f"{KIND}: {session_id!r} is not a pi session id" + ) + found = next( + ( + s + for s in await asyncio.to_thread(self._scan, titles=False) + if s["id"] == session_id + ), + None, + ) + if found is None: + raise errors.WorkerError( + f"{KIND}: no session {session_id} in {self.cwd}" + ) + return found + + async def _cli_history(self, session_id: str) -> list[messages_.Message]: + """Read the active branch of the session file. + + Every message on it, root to latest entry, including what a + compaction summarized away, which pi keeps on disk. + """ + found = await self._find(session_id) + text = await asyncio.to_thread(pathlib.Path(found["path"]).read_text) + return _read(_active_branch(text)) + + async def _cli_list_sessions(self) -> list[_adapter.SessionInfo]: + return [ + _adapter.SessionInfo( + session_id=s["id"], + title=s.get("title"), + cwd=s.get("cwd"), + created_at=s.get("created"), + updated_at=s.get("updated"), + ) + for s in await asyncio.to_thread(self._scan, titles=True) + ] + + def _cli_tui_command( + self, session_id: str | None + ) -> tuple[list[str], dict[str, str], str | None]: + running_as = session_id or str(uuid.uuid4()) + argv = [self._executable, "--session-id", running_as, *self._args()] + servers = { + k: v + for k, v in self.mcp_servers.items() + if k != _bridge.SERVER_NAME + } + # The person at the TUI is the gate: the extension asks nothing. + return ( + argv, + self._extension_env(approve=False, servers=servers), + running_as, + ) + + +# -- the process ------------------------------------------------------------- + + +class Process: + """A CLI started by `spawn`: JSON lines on stdin and stdout.""" + + def __init__(self, proc: asyncio.subprocess.Process) -> None: + self._proc = proc + + async def write(self, data: str) -> None: + assert self._proc.stdin is not None + self._proc.stdin.write(data.encode()) + await self._proc.stdin.drain() + + async def readline(self) -> str: + assert self._proc.stdout is not None + return (await self._proc.stdout.readline()).decode() + + async def read_stderr(self) -> str: + if self._proc.stderr is None: + return "" + return (await self._proc.stderr.read()).decode(errors="replace") + + async def wait(self) -> int: + return await self._proc.wait() + + async def terminate(self) -> None: + """Stop the process group: SIGTERM, then SIGKILL.""" + if self._proc.returncode is not None: + return + with contextlib.suppress(ProcessLookupError): + os.killpg(os.getpgid(self._proc.pid), 15) + try: + async with asyncio.timeout(TERM_GRACE): + await self._proc.wait() + except TimeoutError: + with contextlib.suppress(ProcessLookupError): + os.killpg(os.getpgid(self._proc.pid), 9) + with contextlib.suppress(Exception): + await self._proc.wait() + + async def death_note(self) -> str: + """Say how the process ended, and its last words.""" + code: int | None = None + tail = "" + with contextlib.suppress(Exception): + async with asyncio.timeout(2): + code = await self.wait() + with contextlib.suppress(Exception): + async with asyncio.timeout(2): + tail = (await self.read_stderr()).strip() + how = f"exit code {code}" if code is not None else "exited" + if code in (137, -9): + how += " (SIGKILL, typically the kernel's OOM killer)" + return f"{how}; stderr: {tail[-800:]}" if tail else f"{how}; no stderr" + + +async def spawn( + argv: Sequence[str], *, cwd: str, env: Mapping[str, str] +) -> Process: + """Start a CLI in its own process group, with pipes for stdio.""" + try: + proc = await asyncio.create_subprocess_exec( + *argv, + cwd=cwd, + env={**os.environ, **env}, + stdin=asyncio.subprocess.PIPE, + stdout=asyncio.subprocess.PIPE, + stderr=asyncio.subprocess.PIPE, + # Own the whole tree, so teardown reaches grandchildren too. + start_new_session=True, + limit=LINE_LIMIT, + ) + except OSError as exc: + raise errors.WorkerError(f"cannot start {argv[0]!r}: {exc}") from exc + return Process(proc) + + +class _CommandError(Exception): + """pi answered a command with `success: false`.""" + + +class _Agent: + """One `pi --mode rpc` process: its commands, its events, its dialogs. + + Responses resolve the command that asked (by id). Session events go on + `events`, in order. A dialog is answered in a task of its own: an + approval can take minutes, and the reader must keep reading meanwhile, + including the reply to an `abort` sent from inside it. + """ + + def __init__(self, process: Process, *, on_dialog: Any) -> None: + self.process = process + self.events: asyncio.Queue[dict[str, Any]] = asyncio.Queue() + self.dead: str | None = None + self.runs_started = 0 + self.settled_count = 0 + self.last_start_settled = 0 + self._on_dialog = on_dialog + self._waiters: dict[str, asyncio.Future[Any]] = {} + self._pump: asyncio.Task[None] | None = None + self._dialogs: set[asyncio.Task[None]] = set() + # Dialogs pi still waits on, by request id: what `dismiss` withdraws. + self.pending: dict[str, asyncio.Task[None]] = {} + + def start(self) -> None: + self._pump = asyncio.create_task(self._read()) + + async def call( + self, command: dict[str, Any], *, timeout: float = 120 + ) -> Any: + if self.dead is not None: + raise errors.WorkerError(f"{KIND} crashed: {self.dead}") + request_id = uuid.uuid4().hex + future: asyncio.Future[Any] = asyncio.get_running_loop().create_future() + self._waiters[request_id] = future + try: + await self.send({**command, "id": request_id}) + async with asyncio.timeout(timeout): + return await future + finally: + self._waiters.pop(request_id, None) + + async def send(self, record: dict[str, Any]) -> None: + try: + await self.process.write(json.dumps(record) + "\n") + except Exception as exc: + raise errors.WorkerError( + f"{KIND}: could not write to pi: {exc}" + ) from exc + + def _track(self, request_id: str, task: asyncio.Task[None]) -> None: + self.pending[request_id] = task + + def forget(_: asyncio.Task[None]) -> None: + if self.pending.get(request_id) is task: + del self.pending[request_id] + + task.add_done_callback(forget) + + async def dismiss(self) -> None: + """Withdraw every question pi still waits on. + + The approval deciding it is cancelled, and pi hears `cancelled`: the + extension then blocks the call. + """ + for request_id, task in list(self.pending.items()): + self.pending.pop(request_id, None) + task.cancel() + with contextlib.suppress(asyncio.CancelledError, Exception): + await task + with contextlib.suppress(Exception): + await self.send( + { + "type": "extension_ui_response", + "id": request_id, + "cancelled": True, + } + ) + + async def close(self) -> None: + if self._pump is not None: + self._pump.cancel() + with contextlib.suppress(asyncio.CancelledError, Exception): + await self._pump + self._pump = None + for task in list(self._dialogs): + task.cancel() + for task in list(self._dialogs): + with contextlib.suppress(asyncio.CancelledError, Exception): + await task + self._dialogs.clear() + self._fail("connection closed") + # A turn reading events must hear it too: the producer is gone. + self.events.put_nowait({"type": CLOSED}) + + def _fail(self, detail: str) -> None: + self.dead = self.dead or detail + for future in self._waiters.values(): + if not future.done(): + future.set_exception( + errors.WorkerError(f"{KIND} crashed: {detail}") + ) + self._waiters.clear() + + async def _read(self) -> None: + try: + while True: + line = await self.process.readline() + if not line: + detail = await self.process.death_note() + self._fail(detail) + self.events.put_nowait({"type": CRASHED, "detail": detail}) + return + try: + record = json.loads(line) + except json.JSONDecodeError: + continue # stdout is protocol only; tolerate noise + if not isinstance(record, dict): + continue + kind = record.get("type") + if kind == "response": + self._resolve(record) + elif kind == "extension_ui_request": + task = asyncio.create_task(self._on_dialog(self, record)) + self._dialogs.add(task) + task.add_done_callback(self._dialogs.discard) + if record.get("method") in DIALOGS: + self._track(str(record.get("id")), task) + else: + if kind == "agent_start": + self.runs_started += 1 + self.last_start_settled = self.settled_count + elif kind == "agent_settled": + self.settled_count += 1 + self.events.put_nowait(record) + except asyncio.CancelledError: + raise + except Exception as exc: + self._fail(str(exc)) + self.events.put_nowait({"type": CRASHED, "detail": str(exc)}) + + def _resolve(self, record: dict[str, Any]) -> None: + future = self._waiters.get(str(record.get("id"))) + if future is None or future.done(): + return + if record.get("success") is False: + future.set_exception(_CommandError(str(record.get("error") or ""))) + else: + future.set_result(record.get("data")) + + +async def _prompt_command(prompt: _adapter.Prompt) -> dict[str, Any]: + """Return a prompt as pi's `prompt` command: text, and images as base64.""" + texts: list[str] = [] + images: list[dict[str, Any]] = [] + for part in prompt: + if isinstance(part, messages_.TextPart): + texts.append(part.text) + elif part.media_type.startswith("text/"): + texts.append(await _convert.as_text(part)) + else: + images.append( + { + "type": "image", + "data": base64.b64encode(await _convert.data(part)).decode( + "ascii" + ), + "mimeType": part.media_type, + } + ) + command: dict[str, Any] = {"type": "prompt", "message": "\n\n".join(texts)} + if images: + command["images"] = images + return command + + +def _stream_events( + update: dict[str, Any], + message: str, + open_blocks: dict[str, str], + started: set[str], +) -> list[events_.Event]: + """One `assistantMessageEvent` -> events. + + Block ids are `.`: pi numbers content blocks per + assistant message, and a turn holds several. Tool-call arguments travel + as ONE delta, the final arguments, at `toolcall_end`: streamed fragments + are not guaranteed to add up to what pi settles on. + """ + kind = update.get("type") or "" + block = f"{message}.{update.get('contentIndex', 0)}" + out: list[events_.Event] = [] + if kind == "text_start": + open_blocks[block] = "text" + out.append(events_.TextStart(block_id=block)) + elif kind == "text_delta" and update.get("delta"): + out.append(events_.TextDelta(chunk=update["delta"], block_id=block)) + elif kind == "thinking_start": + open_blocks[block] = "thinking" + out.append(events_.ReasoningStart(block_id=block)) + elif kind == "thinking_delta" and update.get("delta"): + out.append( + events_.ReasoningDelta(chunk=update["delta"], block_id=block) + ) + elif kind in ("text_end", "thinking_end"): + out += _close_blocks(open_blocks, only=block) + elif kind == "toolcall_start" and update.get("id"): + started.add(update["id"]) + out.append( + events_.BuiltinToolStart( + tool_call_id=update["id"], + tool_name=update.get("toolName") or "", + ) + ) + elif kind == "toolcall_end": + call = _tool_call(update.get("toolCall") or {}) + out += _convert.builtin_call( + call.tool_call_id, call.tool_name, call.tool_args, started=started + ) + return out + + +def _unstreamed( + content: Any, message: str, streamed: set[str], started: set[str] +) -> list[events_.Event]: + """Return the events of a finished message's unstreamed blocks.""" + out: list[events_.Event] = [] + blocks = content if isinstance(content, list) else [] + for index, block in enumerate(blocks): + if not isinstance(block, dict): + continue + block_id = f"{message}.{index}" + kind = block.get("type") + if kind == "text" and block.get("text") and block_id not in streamed: + out += [ + events_.TextStart(block_id=block_id), + events_.TextDelta(chunk=block["text"], block_id=block_id), + events_.TextEnd(block_id=block_id), + ] + elif ( + kind == "thinking" + and block.get("thinking") + and block_id not in streamed + ): + out += [ + events_.ReasoningStart(block_id=block_id), + events_.ReasoningDelta( + chunk=block["thinking"], block_id=block_id + ), + events_.ReasoningEnd(block_id=block_id), + ] + elif kind == "toolCall" and str(block.get("id")) not in started: + call = _tool_call(block) + out += _convert.builtin_call( + call.tool_call_id, + call.tool_name, + call.tool_args, + started=started, + ) + return out + + +def _close_blocks( + open_blocks: dict[str, str], only: str | None = None +) -> list[events_.Event]: + """End the text and reasoning blocks still open (an aborted message's).""" + out: list[events_.Event] = [] + for block in [only] if only is not None else list(open_blocks): + opened = open_blocks.pop(block, None) + if opened == "text": + out.append(events_.TextEnd(block_id=block)) + elif opened == "thinking": + out.append(events_.ReasoningEnd(block_id=block)) + return out + + +def _tool_call(block: dict[str, Any]) -> messages_.ToolCallPart: + return messages_.ToolCallPart( + tool_call_id=str(block.get("id") or ""), + tool_name=str(block.get("name") or ""), + tool_args=json.dumps(block.get("arguments") or {}), + ) + + +def _assistant_parts(content: Any) -> list[messages_.Part]: + parts: list[messages_.Part] = [] + for block in content if isinstance(content, list) else []: + if not isinstance(block, dict): + continue + kind = block.get("type") + if kind == "text" and block.get("text"): + parts.append(messages_.TextPart(text=block["text"])) + elif kind == "thinking" and block.get("thinking"): + parts.append(messages_.ReasoningPart(text=block["thinking"])) + elif kind == "toolCall": + call = _tool_call(block) + parts.append( + messages_.BuiltinToolCallPart( + tool_call_id=call.tool_call_id, + tool_name=call.tool_name, + tool_args=call.tool_args, + ) + ) + return parts + + +def _content_parts(content: Any) -> list[messages_.Part]: + """Return a user message's parts: from a string, or text and images.""" + if isinstance(content, str): + return [messages_.TextPart(text=content)] if content else [] + parts: list[messages_.Part] = [] + for block in content if isinstance(content, list) else []: + if not isinstance(block, dict): + continue + if block.get("type") == "text" and block.get("text"): + parts.append(messages_.TextPart(text=block["text"])) + elif block.get("type") == "image" and block.get("data"): + parts.append( + messages_.FilePart( + data=str(block["data"]), + media_type=str(block.get("mimeType") or "image/png"), + ) + ) + return parts + + +def _tool_result(result: Any) -> Any: + """Return what a tool returned: its text, when that is all it is. + + pi tools return content blocks; text-only content (nearly every call) + reads as the string it is, anything else stays the blocks themselves. + """ + content = result.get("content") if isinstance(result, dict) else result + if isinstance(content, list) and all( + isinstance(b, dict) and b.get("type") == "text" for b in content + ): + content = "".join(b.get("text") or "" for b in content) + return content + + +def _active_branch(text: str) -> list[dict[str, Any]]: + """Return the session file's active branch: root to latest entry. + + A session is a tree (`id`/`parentId`); the leaf is the entry appended + last, and abandoned branches are not part of the conversation. + """ + entries: dict[str, dict[str, Any]] = {} + leaf: str | None = None + for line in text.splitlines(): + try: + entry = json.loads(line) + except json.JSONDecodeError: + continue + if ( + isinstance(entry, dict) + and entry.get("id") + and entry.get("type") != "session" + ): + entries[str(entry["id"])] = entry + leaf = str(entry["id"]) + path: list[dict[str, Any]] = [] + seen: set[str] = set() + while leaf is not None and leaf in entries and leaf not in seen: + seen.add(leaf) + path.append(entries[leaf]) + parent = entries[leaf].get("parentId") + leaf = str(parent) if parent is not None else None + return list(reversed(path)) + + +def _read(entries: list[dict[str, Any]]) -> list[messages_.Message]: + """Read session entries as messages, like a live turn's. + + The CLI's tools are built-in parts. pi keeps a tool result as a message + of its own (`toolResult`); here it joins the assistant message of its + call. + """ + out: list[messages_.Message] = [] + calls: dict[str, tuple[messages_.Message, messages_.BuiltinToolCallPart]] + calls = {} + for entry in entries: + message = entry.get("message") or {} + if entry.get("type") == "message" and message.get("role") == ( + "toolResult" + ): + found = calls.get(str(message.get("toolCallId") or "")) + if found is None: + continue # a result without its call: nothing to join + owner, call = found + owner.parts.append( + messages_.BuiltinToolReturnPart( + tool_call_id=call.tool_call_id, + tool_name=str(message.get("toolName") or call.tool_name), + result=_tool_result(message), + is_error=bool(message.get("isError")), + ) + ) + continue + for found_message in _stored_to_messages(entry): + out.append(found_message) + for part in found_message.parts: + if isinstance(part, messages_.BuiltinToolCallPart): + calls[part.tool_call_id] = (found_message, part) + return out + + +def _stored_to_messages(entry: dict[str, Any]) -> list[messages_.Message]: + """One session entry -> messages. A tool result is `_read`'s to join. + + Everything pi sends the model is kept: what an extension injected + (`custom_message`) and a `!` command's output (`bashExecution`) reach it + as user messages, and so they are user messages here; a branch summary + is the context pi carried over from an abandoned branch. + """ + kind = entry.get("type") + if kind == "custom_message": + parts = _content_parts(entry.get("content")) + return [messages_.Message(role="user", parts=parts)] if parts else [] + if kind == "branch_summary" and entry.get("summary"): + text = str(entry["summary"]) + return [ + messages_.Message( + role="user", parts=[messages_.TextPart(text=text)] + ) + ] + if kind != "message": + return [] + message = entry.get("message") or {} + role = message.get("role") + if role in ("custom", "user"): + parts = _content_parts(message.get("content")) + return [messages_.Message(role="user", parts=parts)] if parts else [] + if role == "bashExecution" and not message.get("excludeFromContext"): + # pi's own rendering of it for the model. + text = ( + f"Ran `{message.get('command', '')}`\n```\n" + f"{message.get('output', '')}\n```" + ) + return [ + messages_.Message( + role="user", parts=[messages_.TextPart(text=text)] + ) + ] + if role == "assistant": + parts = _assistant_parts(message.get("content")) + if not parts: + return [] + return [ + messages_.Message( + role="assistant", + parts=parts, + provider_metadata=_written_by(message), + ) + ] + return [] + + +def _written_by(message: dict[str, Any]) -> dict[str, Any] | None: + """Which provider and model wrote an assistant message, as pi says. + + Kept on the message (`provider_metadata["pi"]`) so a conversation + seeded into another pi continues on the model it was on. + """ + written = { + k: message[k] + for k in ("api", "provider", "model", "thinkingLevel") + if isinstance(message.get(k), str) + } + if not written or written.get("provider") == "ai-python": + return None + return {KIND: written} + + +def _usage(raw: dict[str, Any]) -> usage_.Usage: + """Return pi's per-message usage. pi's `input` excludes cached input.""" + + def count(name: str) -> int: + value = raw.get(name) + return value if isinstance(value, int) else 0 + + reasoning = raw.get("reasoning") + return usage_.Usage( + input_tokens=count("input") + count("cacheRead") + count("cacheWrite"), + output_tokens=count("output"), + cache_read_tokens=count("cacheRead"), + cache_write_tokens=count("cacheWrite"), + reasoning_tokens=reasoning if isinstance(reasoning, int) else None, + ) + + +def mcp_config(servers: dict[str, Any]) -> dict[str, Any]: + """MCP servers, in the shape claude takes, as pi registers them. + + pi validates the config, so only the keys it knows are passed. + """ + keys = ("command", "args", "env", "cwd", "url", "headers") + return { + name: {k: server[k] for k in keys if server.get(k) is not None} + for name, server in servers.items() + } + + +def _setting(path: pathlib.Path) -> str | None: + """Return the `sessionDir` a pi settings file names, if any.""" + try: + value = json.loads(path.read_text()).get("sessionDir") + except Exception: + return None + return value if isinstance(value, str) and value else None + + +def _describe( + path: pathlib.Path, cwds: tuple[str, ...], *, titles: bool +) -> dict[str, Any] | None: + """Describe one session file of this directory, or None. + + A session file can come from anyone (a project's settings choose the + directory), and its id becomes a CLI argument: one that breaks pi's + rule is not a session. + """ + with path.open() as f: + header = json.loads(f.readline() or "{}") + if header.get("type") != "session" or not SESSION_ID.match( + str(header.get("id") or "") + ): + return None + if header.get("cwd") not in cwds: + return None + created: int | None = None + with contextlib.suppress(ValueError): + when = datetime.datetime.strptime( + str(header.get("timestamp") or "")[:19], "%Y-%m-%dT%H:%M:%S" + ).replace(tzinfo=datetime.UTC) + created = int(when.timestamp() * 1000) + info: dict[str, Any] = { + "id": header["id"], + "path": str(path), + "cwd": header.get("cwd"), + "created": created, + "updated": int(path.stat().st_mtime * 1000), + } + if not titles: + return info + name: str | None = None + first: str | None = None + for line in f: + try: + entry = json.loads(line) + except ValueError: + continue + if entry.get("type") == "session_info": + name = entry.get("name") or None + elif first is None and entry.get("type") == "message": + message = entry.get("message") or {} + if message.get("role") == "user": + content = message.get("content") + if isinstance(content, list): + content = " ".join( + b.get("text", "") + for b in content + if isinstance(b, dict) and b.get("type") == "text" + ) + first = (content or "").strip()[:200] or None + info["title"] = name or first + return info diff --git a/tests/agents/test_hooks.py b/tests/agents/test_hooks.py index 2f449f36..af235e49 100644 --- a/tests/agents/test_hooks.py +++ b/tests/agents/test_hooks.py @@ -10,6 +10,7 @@ import pytest import ai +from ai.agents import runtime from ai.types import events as agent_events_ from ..conftest import MOCK_MODEL, Recorder, mock_llm, text_msg @@ -137,6 +138,87 @@ async def loop( assert resolved_value.approved is True +# -- Hooks outside Agent ----------------------------------------------------- + + +class QueueRuntime(runtime.Runtime): + def __init__(self) -> None: + super().__init__() + self.events: asyncio.Queue[agent_events_.AgentEvent] = asyncio.Queue() + + async def put_event(self, event: agent_events_.AgentEvent) -> None: + await self.events.put(event) + + +@pytest.mark.parametrize("cancel", [False, True]) +async def test_hook_outside_agent(cancel: bool) -> None: + reg = ai.HookRegistry() + rt = QueueRuntime() + with pytest.raises(LookupError): + runtime.get_runtime() + with pytest.raises(LookupError): + ai.agents.hooks.get_hook_registry() + + async with asyncio.TaskGroup() as tasks: + task = tasks.create_task( + ai.hook( + "approval", + payload=Confirmation, + metadata={"tool": "write_file"}, + tool_call_id="call_1", + registry=reg, + runtime=rt, + ) + ) + pending = await rt.events.get() + assert isinstance(pending, agent_events_.HookEvent) + assert pending.hook.hook_id == "approval" + assert pending.hook.hook_type == "Confirmation" + assert pending.hook.status == "pending" + assert pending.hook.metadata == {"tool": "write_file"} + assert pending.hook.tool_call_id == "call_1" + assert not task.done() + assert reg._live_hooks["approval"][2] is rt + + if cancel: + await ai.cancel_hook(pending.hook, reason="denied", registry=reg) + with pytest.raises(asyncio.CancelledError, match="denied"): + await task + else: + ai.resolve_hook(pending.hook, {"approved": True}, registry=reg) + assert await task == Confirmation(approved=True) + + completed = await rt.events.get() + assert isinstance(completed, agent_events_.HookEvent) + assert completed.hook.hook_id == "approval" + assert completed.hook.metadata == {"tool": "write_file"} + if cancel: + assert completed.hook.status == "cancelled" + else: + assert completed.hook.status == "resolved" + assert completed.hook.resolution == {"approved": True} + assert completed.hook.tool_call_id == "call_1" + + assert not reg._live_hooks + assert not reg._pending_resolutions + assert rt.events.empty() + + +async def test_pre_registered_hook_outside_agent() -> None: + reg = ai.HookRegistry() + rt = QueueRuntime() + ai.resolve_hook("approval", {"approved": True}, registry=reg) + + result = await ai.hook( + "approval", payload=Confirmation, registry=reg, runtime=rt + ) + + assert result == Confirmation(approved=True) + assert not reg._live_hooks + assert not reg._pending_resolutions + assert rt.events.empty() + + # -- Explicit HookRegistry --------------------------------------------------- diff --git a/tests/workers/_adapters/test_codex.py b/tests/workers/_adapters/test_codex.py deleted file mode 100644 index de1fedb9..00000000 --- a/tests/workers/_adapters/test_codex.py +++ /dev/null @@ -1,384 +0,0 @@ -"""The codex adapter against a scripted `codex app-server`, offline.""" - -from __future__ import annotations - -import asyncio -import json -from collections.abc import Callable -from typing import Any, cast - -import pytest - -from ai import workers -from ai.types import events -from ai.types import messages as m -from ai.workers._adapters import codex, jsonrpc - -from .. import fakes - -THREAD = "T" -CWD = "/w" - - -class AppServer: - """Answers like `codex app-server`. `turn` plays out after turn/start.""" - - def __init__(self, turn: list[dict[str, Any]] | None = None) -> None: - self.process = fakes.FakeProcess(self.answer) - self.turn = turn or [] - self.on_turn: Callable[[], None] | None = None - self.threads: dict[str, dict[str, Any]] = { - THREAD: {"id": THREAD, "cwd": CWD, "turns": []} - } - - def says(self, method: str, **params: Any) -> None: - self.process.server_says({"method": method, "params": params}) - - def answer(self, message: dict[str, Any]) -> Any: - method = message.get("method") - params = message.get("params") or {} - if method == "turn/start": - if self.on_turn is not None: - self.on_turn() - for record in self.turn: - self.process.server_says(record) - return {"turn": {"id": "turn-1"}} - if method == "turn/interrupt": - self.says( - "turn/completed", - threadId=THREAD, - turn={"id": "turn-1", "status": "interrupted"}, - ) - return {} - if method == "thread/read": - return {"thread": self.threads.get(str(params.get("threadId")), {})} - if method in ("thread/start", "thread/fork"): - return {"thread": {"id": "new"}} - if method == "thread/resume": - return {"thread": {"id": params["threadId"]}} - if "method" in message and "id" in message: - return {} - return None - - def sent(self, method: str) -> list[dict[str, Any]]: - return [w for w in self.process.written if w.get("method") == method] - - -def note(method: str, **params: Any) -> dict[str, Any]: - return { - "method": method, - "params": {"threadId": THREAD, "turnId": "turn-1", **params}, - } - - -COMMAND = { - "type": "commandExecution", - "id": "c1", - "command": "/bin/zsh -lc 'cat secret.txt'", - "aggregatedOutput": "the word is HERON\n", - "exitCode": 0, - "status": "completed", -} - -TURN = [ - note("item/reasoning/summaryTextDelta", itemId="r1", delta="plan"), - note("item/completed", item={"type": "reasoning", "id": "r1"}), - note("item/started", item={**COMMAND, "aggregatedOutput": None}), - note("item/completed", item=COMMAND), - note("item/agentMessage/delta", itemId="a1", delta="HER"), - note("item/agentMessage/delta", itemId="a1", delta="ON"), - note("item/completed", item={"type": "agentMessage", "id": "a1"}), - note( - "thread/tokenUsage/updated", - tokenUsage={"lastTurn": {"inputTokens": 10, "outputTokens": 4}}, - ), - note("turn/completed", turn={"id": "turn-1", "status": "completed"}), -] - - -def _adapter( - server: AppServer, approve: Any = None, **options: Any -) -> codex.CodexAdapter: - adapter = codex.CodexAdapter( - cwd=CWD, - env={}, - executable="codex", - model=None, - mcp_servers=options.pop("mcp_servers", {}), - approve=approve, - sandbox=None, - config={}, - ) - peer = jsonrpc.JsonRpcPeer(cast("Any", server.process), kind="codex") - adapter._process = cast("Any", server.process) - adapter._peer = peer - adapter._thread = THREAD - peer.start( - adapter._on_notify, adapter._on_request, on_crash=adapter._on_crash - ) - return adapter - - -async def _turn(adapter: codex.CodexAdapter, text: str = "go") -> list[Any]: - async with asyncio.timeout(5): - return [e async for e in adapter.turn([m.TextPart(text=text)])] - - -async def test_a_turn_streams_in_the_model_view() -> None: - adapter = _adapter(AppServer(TURN)) - seen = await _turn(adapter) - assert [type(e).__name__ for e in seen] == [ - "StreamStart", - "ReasoningStart", - "ReasoningDelta", - "ReasoningEnd", - "BuiltinToolStart", - "BuiltinToolDelta", - "BuiltinToolEnd", - "BuiltinToolResult", - "TextStart", - "TextDelta", - "TextDelta", - "TextEnd", - "StreamEnd", - ] - result = next(e for e in seen if isinstance(e, events.BuiltinToolResult)) - # codex 0.160 reports a command's output as `aggregatedOutput`. - assert result.result.result == "the word is HERON\n" - end = seen[-1] - assert end.finish_reason == "stop" - assert end.usage.input_tokens == 10 - hydrator = events.MessageHydrator() - for event in seen: - hydrator.feed(event) - assert [type(p).__name__ for p in hydrator.message.parts] == [ - "ReasoningPart", - "BuiltinToolCallPart", - "BuiltinToolReturnPart", - "TextPart", - ] - - -async def test_a_message_that_was_never_streamed_still_arrives() -> None: - server = AppServer( - [ - note( - "item/completed", - item={"type": "agentMessage", "id": "a1", "text": "PONG"}, - ), - note( - "turn/completed", turn={"id": "turn-1", "status": "completed"} - ), - ] - ) - seen = await _turn(_adapter(server)) - assert [e.chunk for e in seen if isinstance(e, events.TextDelta)] == [ - "PONG" - ] - - -async def test_another_turns_notifications_are_not_this_turns() -> None: - server = AppServer( - [ - { - "method": "turn/completed", - "params": {"threadId": THREAD, "turn": {"id": "old"}}, - }, - { - "method": "item/agentMessage/delta", - "params": {"threadId": "other", "itemId": "x", "delta": "no"}, - }, - note( - "turn/completed", turn={"id": "turn-1", "status": "completed"} - ), - ] - ) - seen = await _turn(_adapter(server)) - assert [type(e).__name__ for e in seen] == ["StreamStart", "StreamEnd"] - - -async def test_a_failed_turn_without_a_key_is_not_authenticated() -> None: - server = AppServer( - [ - note("error", error={"message": "401 Unauthorized"}), - note("turn/completed", turn={"id": "turn-1", "status": "failed"}), - ] - ) - with pytest.raises(workers.NotAuthenticatedError): - await _turn(_adapter(server)) - - -@pytest.mark.parametrize("granted", [True, False]) -async def test_approvals_ask_and_answer(granted: bool) -> None: - server = AppServer() - asked: list[tuple[str, str, dict[str, Any]]] = [] - - async def approve( - call_id: str, name: str, tool_input: dict[str, Any] - ) -> tuple[bool, str]: - asked.append((call_id, name, tool_input)) - return granted, "no" - - def ask() -> None: - server.process.server_says( - { - "id": 500, - "method": "item/commandExecution/requestApproval", - "params": { - "threadId": THREAD, - "turnId": "turn-1", - "itemId": "i1", - "command": "rm -rf /", - }, - } - ) - - def complete(message: dict[str, Any]) -> Any: - if message.get("id") == 500: - server.says( - "turn/completed", - threadId=THREAD, - turn={"id": "turn-1", "status": "completed"}, - ) - return None - return AppServer.answer(server, message) - - server.on_turn = ask - server.process.answer = complete - adapter = _adapter(server, approve) - assert adapter._thread_params()["approvalPolicy"] == "untrusted" - await _turn(adapter) - assert asked == [("i1", "commandExecution", {"command": "rm -rf /"})] - answer = next(w for w in server.process.written if w.get("id") == 500) - assert answer["result"] == {"decision": "accept" if granted else "decline"} - - -async def test_without_a_gate_codex_never_asks() -> None: - adapter = _adapter(AppServer()) - assert adapter._thread_params() == { - "sandbox": "danger-full-access", - "approvalPolicy": "never", - } - - -async def test_an_interrupted_turn_ends_as_cancelled() -> None: - server = AppServer() - adapter = _adapter(server) - turn = adapter.turn([m.TextPart(text="go")]) - assert isinstance(await anext(turn), events.StreamStart) - reader = asyncio.ensure_future(_rest(turn)) - await asyncio.sleep(0) - await adapter.interrupt() - seen = await asyncio.wait_for(reader, 5) - assert seen[-1].finish_reason == "cancelled" - assert server.sent("turn/interrupt")[0]["params"] == { - "threadId": THREAD, - "turnId": "turn-1", - } - - -async def _rest(turn: Any) -> list[Any]: - return [e async for e in turn] - - -async def test_opening_a_new_thread_seeds_it() -> None: - server = AppServer() - adapter = _adapter(server) - seed = [ - m.Message(role="user", parts=[m.TextPart(text="earlier")]), - m.Message(role="assistant", parts=[m.TextPart(text="answer")]), - ] - assert ( - await adapter.open( - session_id=None, fork=False, seed=seed, instructions="Be terse." - ) - == "new" - ) - started = server.sent("thread/start")[0]["params"] - assert started["cwd"] == CWD - assert started["developerInstructions"] == "Be terse." - injected = server.sent("thread/inject_items")[0]["params"] - assert injected["threadId"] == "new" - assert [i["role"] for i in injected["items"]] == ["user", "assistant"] - - -async def test_a_fork_is_native() -> None: - server = AppServer() - adapter = _adapter(server) - forked = await adapter.open( - session_id=THREAD, fork=True, seed=None, instructions=None - ) - assert forked == "new" - assert server.sent("thread/fork")[0]["params"]["threadId"] == THREAD - - -async def test_a_thread_from_another_directory_is_refused() -> None: - server = AppServer() - server.threads["elsewhere"] = {"id": "elsewhere", "cwd": "/other"} - adapter = _adapter(server) - with pytest.raises(workers.WorkerError, match="/other"): - await adapter.open( - session_id="elsewhere", fork=False, seed=None, instructions=None - ) - - -async def test_history_is_the_model_view() -> None: - server = AppServer() - server.threads[THREAD]["turns"] = [ - { - "items": [ - { - "type": "userMessage", - "content": [{"type": "text", "text": "q"}], - }, - COMMAND, - {"type": "agentMessage", "text": "HERON"}, - ] - } - ] - history = await _adapter(server).history(THREAD) - assert [x.role for x in history] == ["user", "assistant", "assistant"] - call, result = history[1].parts - assert isinstance(call, m.BuiltinToolCallPart) - assert json.loads(call.tool_args)["command"].endswith("'cat secret.txt'") - assert isinstance(result, m.BuiltinToolReturnPart) - assert result.result == "the word is HERON\n" - - -async def test_listing_asks_for_this_directory_and_reads_every_page() -> None: - """`thread/list` is paged, and the store is the whole machine's.""" - asked: list[dict[str, Any]] = [] - pages = { - None: ({"id": "t1", "cwd": CWD}, "p2"), - "p2": ({"id": "t2", "cwd": CWD}, None), - } - server = AppServer() - - def answer(message: dict[str, Any]) -> Any: - if message.get("method") != "thread/list": - return AppServer.answer(server, message) - params = message["params"] - asked.append(params) - thread, cursor = pages[params.get("cursor")] - return {"data": [thread], "nextCursor": cursor} - - server.process.answer = answer - infos = await _adapter(server).list_sessions() - assert [i.session_id for i in infos] == ["t1", "t2"] - assert all(p["cwd"] == CWD for p in asked) - assert [p.get("cursor") for p in asked] == [None, "p2"] - - -async def test_the_tui_gets_no_bridge() -> None: - adapter = _adapter( - AppServer(), - mcp_servers={ - "ai_sdk": {"url": "http://127.0.0.1:1/mcp"}, - "docs": {"command": "docs-mcp"}, - }, - ) - argv, _, minted = adapter.tui_command(THREAD) - assert argv[:3] == ["codex", "resume", THREAD] - assert 'mcp_servers.docs.command="docs-mcp"' in argv - assert not any("ai_sdk" in arg for arg in argv) - assert minted is None # codex picks its own ids diff --git a/src/ai/workers/_adapters/__init__.py b/tests/workers/claude_code/__init__.py similarity index 100% rename from src/ai/workers/_adapters/__init__.py rename to tests/workers/claude_code/__init__.py diff --git a/tests/workers/claude_code/test_adapter.py b/tests/workers/claude_code/test_adapter.py new file mode 100644 index 00000000..6a229041 --- /dev/null +++ b/tests/workers/claude_code/test_adapter.py @@ -0,0 +1,966 @@ +"""The Claude worker against a scripted claude-agent-sdk client, offline.""" + +from __future__ import annotations + +import asyncio +import json +from collections.abc import AsyncIterator +from pathlib import Path +from types import SimpleNamespace +from typing import Any +from unittest import mock + +import pydantic +import pytest + +claude_agent_sdk = pytest.importorskip("claude_agent_sdk") + +import ai # noqa: E402 +from ai import workers # noqa: E402 +from ai.types import events # noqa: E402 +from ai.types import messages as m # noqa: E402 +from ai.workers import _adapter # noqa: E402 +from ai.workers.claude_code import worker as worker_ # noqa: E402 + + +def _stream(event: dict[str, Any]) -> Any: + return claude_agent_sdk.StreamEvent(uuid="u", session_id="s", event=event) + + +def _result(**fields: Any) -> Any: + return claude_agent_sdk.ResultMessage( + subtype=fields.pop("subtype", "success"), + duration_ms=1, + duration_api_ms=1, + is_error=fields.pop("is_error", False), + num_turns=1, + session_id="s", + usage={"input_tokens": 7, "output_tokens": 3}, + total_cost_usd=0.01, + **fields, + ) + + +TURN = [ + _stream( + { + "type": "content_block_start", + "index": 0, + "content_block": {"type": "thinking"}, + } + ), + _stream( + { + "type": "content_block_delta", + "index": 0, + "delta": {"type": "thinking_delta", "thinking": "plan"}, + } + ), + _stream({"type": "content_block_stop", "index": 0}), + claude_agent_sdk.AssistantMessage( + content=[ + claude_agent_sdk.ToolUseBlock( + id="t1", name="Bash", input={"command": "ls"} + ) + ], + model="claude", + ), + claude_agent_sdk.UserMessage( + content=[ + claude_agent_sdk.ToolResultBlock(tool_use_id="t1", content="a.py") + ] + ), + _stream( + { + "type": "content_block_start", + "index": 1, + "content_block": {"type": "text"}, + } + ), + _stream( + { + "type": "content_block_delta", + "index": 1, + "delta": {"type": "text_delta", "text": "one file"}, + } + ), + _stream({"type": "content_block_stop", "index": 1}), + claude_agent_sdk.AssistantMessage( + content=[claude_agent_sdk.TextBlock(text="one file")], model="claude" + ), + _result(), +] + + +class Client: + """Answers like `ClaudeSDKClient`: a query, then the scripted reply.""" + + def __init__(self, *replies: list[Any]) -> None: + self.replies = list(replies) + self.queries: list[Any] = [] + self.interrupted = False + + async def query(self, prompt: Any) -> None: + self.queries.append(prompt) + + async def receive_messages(self) -> AsyncIterator[Any]: + while self.replies: + for message in self.replies.pop(0): + yield message + + async def interrupt(self) -> None: + self.interrupted = True + + async def disconnect(self) -> None: + pass + + +def _worker(tmp_path: Path, **options: Any) -> workers.ClaudeCode: + return workers.ClaudeCode( + cwd=str(tmp_path), + env={"CLAUDE_CONFIG_DIR": str(tmp_path / "config")}, + **options, + ) + + +async def _turn(worker: workers.ClaudeCode, *prompt: Any) -> list[Any]: + async with asyncio.timeout(5): + return [e async for e in worker._cli_turn(list(prompt))] + + +async def test_a_turn_streams_in_the_model_view(tmp_path: Path) -> None: + worker = _worker(tmp_path) + worker._client = Client(TURN) + seen = await _turn(worker, m.TextPart(text="what is here?")) + assert [type(e).__name__ for e in seen] == [ + "StreamStart", + "ReasoningStart", + "ReasoningDelta", + "ReasoningEnd", + "BuiltinToolStart", + "BuiltinToolDelta", + "BuiltinToolEnd", + "BuiltinToolResult", + "TextStart", + "TextDelta", + "TextEnd", + "StreamEnd", + ] + assert worker._client.queries == ["what is here?"] + end = seen[-1] + assert end.finish_reason == "stop" + assert end.usage.input_tokens == 7 + assert end.usage.raw["cost_usd"] == 0.01 + delta = next(e for e in seen if isinstance(e, events.BuiltinToolDelta)) + assert json.loads(delta.chunk) == {"command": "ls"} + result = next(e for e in seen if isinstance(e, events.BuiltinToolResult)) + assert (result.result.tool_name, result.result.result) == ("Bash", "a.py") + + +async def test_files_travel_as_base64_blocks(tmp_path: Path) -> None: + worker = _worker(tmp_path) + worker._client = Client([_result()]) + png = m.FilePart(data=b"\x89PNG", media_type="image/png") + await _turn(worker, m.TextPart(text="look"), png) + (sent,) = worker._client.queries + (record,) = [record async for record in sent] + message = record["message"] + assert message["content"][1] == { + "type": "image", + "source": { + "type": "base64", + "media_type": "image/png", + "data": "iVBORw==", + }, + } + + +async def test_an_unknown_file_is_refused(tmp_path: Path) -> None: + worker = _worker(tmp_path) + worker._client = Client([_result()]) + zipped = m.FilePart(data=b"PK", media_type="application/zip") + with pytest.raises(workers.WorkerError, match="application/zip"): + await _turn(worker, zipped) + + +async def test_finish_reasons(tmp_path: Path) -> None: + worker = _worker(tmp_path) + worker._client = Client([_result(subtype="error_max_turns")]) + assert (await _turn(worker, m.TextPart(text="x")))[-1].finish_reason == ( + "length" + ) + worker._client = Client( + [_result(is_error=True, result="Invalid API key · Please run /login")] + ) + with pytest.raises(workers.NotAuthenticatedError): + await _turn(worker, m.TextPart(text="x")) + worker._client = Client([_result(is_error=True, result="overloaded")]) + with pytest.raises(workers.WorkerError, match="overloaded"): + await _turn(worker, m.TextPart(text="x")) + + +@pytest.mark.parametrize( + ("detail", "error_type"), + [ + ("Invalid API key · Please run /login", workers.NotAuthenticatedError), + ("overloaded", workers.WorkerError), + ], +) +@pytest.mark.parametrize("partial", [False, True]) +async def test_public_generate_raises_native_failure( + tmp_path: Path, + detail: str, + error_type: type[workers.WorkerError], + partial: bool, +) -> None: + worker = _worker(tmp_path) + # Exercise the real public model/worker path. Only the CLI lifecycle + # and output are mocked; a terminal event must not hide its failure. + replies = [*TURN[:-1]] if partial else [] + replies.append(_result(is_error=True, result=detail)) + client = Client(replies) + worker._client = client + with ( + mock.patch.object( + workers.ClaudeCode, "_cli_start", new_callable=mock.AsyncMock + ), + mock.patch.object( + workers.ClaudeCode, + "_cli_open", + new_callable=mock.AsyncMock, + return_value="session", + ), + ): + async with asyncio.timeout(5), worker: + with pytest.raises(error_type, match=detail): + await ai.experimental_generate( + worker, [ai.user_message("hello")] + ) + assert client.queries == ["hello"] + assert worker._pending_results == 0 + assert not worker._running + + +async def test_an_interrupted_turn_is_cancelled_not_failed( + tmp_path: Path, +) -> None: + worker = _worker(tmp_path) + # The CLI's error result after the interrupt is read first, then the + # next turn settles on its own result. + client = Client([_result(is_error=True, result="interrupted")], [_result()]) + worker._client = client + worker._running = True # a turn was running when it was interrupted + await worker._cli_interrupt() + assert client.interrupted + seen = await _turn(worker, m.TextPart(text="again")) + assert seen[-1].finish_reason == "stop" + assert client.replies == [] + + +async def test_a_seed_is_written_where_the_cli_reads(tmp_path: Path) -> None: + worker = _worker(tmp_path) + seed = [ + m.Message(role="user", parts=[m.TextPart(text="earlier")]), + m.Message( + role="assistant", + parts=[ + m.BuiltinToolCallPart( + tool_call_id="t1", tool_name="Read", tool_args="{}" + ), + m.BuiltinToolReturnPart( + tool_call_id="t1", tool_name="Read", result="milk" + ), + m.TextPart(text="It says milk."), + ], + ), + ] + session_id = await worker._stage(seed) + key = claude_agent_sdk.project_key_for_directory(str(tmp_path)) + path = tmp_path / "config" / "projects" / key / f"{session_id}.jsonl" + records = [json.loads(line) for line in path.read_text().splitlines()] + assert [r["type"] for r in records] == [ + "user", + "assistant", + "user", + "assistant", + ] + assert records[1]["message"]["content"][0]["type"] == "tool_use" + assert records[2]["message"]["content"][0]["type"] == "tool_result" + + +def test_a_stored_result_joins_the_message_of_its_call() -> None: + """On disk the result is in the next user record, without a name.""" + records = [ + claude_agent_sdk.SessionMessage( + type="user", + uuid="1", + session_id="s", + message={"role": "user", "content": "q"}, + parent_tool_use_id=None, + ), + claude_agent_sdk.SessionMessage( + type="assistant", + uuid="2", + session_id="s", + message={ + "role": "assistant", + "content": [ + { + "type": "tool_use", + "id": "t1", + "name": "Read", + "input": {}, + } + ], + }, + parent_tool_use_id=None, + ), + claude_agent_sdk.SessionMessage( + type="user", + uuid="3", + session_id="s", + message={ + "role": "user", + "content": [ + {"type": "tool_result", "tool_use_id": "t1", "content": "x"} + ], + }, + parent_tool_use_id=None, + ), + ] + history = worker_._read(records) + assert [x.role for x in history] == ["user", "assistant"] + call, result = history[1].parts + assert isinstance(call, m.BuiltinToolCallPart) + assert isinstance(result, m.BuiltinToolReturnPart) + assert (result.tool_name, result.result) == ("Read", "x") + + +def test_the_tui_command(tmp_path: Path) -> None: + worker = _worker( + tmp_path, + model_name="sonnet", + mcp_servers={ + "ai_sdk": {"type": "http", "url": "http://127.0.0.1:1/mcp"}, + "docs": {"command": "docs-mcp"}, + }, + ) + argv, env, minted = worker._cli_tui_command("abc") + assert argv[:3] == ["claude", "--resume", "abc"] + assert argv[argv.index("--model") + 1] == "sonnet" + config = json.loads(argv[argv.index("--mcp-config") + 1]) + assert list(config["mcpServers"]) == ["docs"] # no bridge in a TUI + assert env["DISABLE_AUTOUPDATER"] == "1" + assert minted == "abc" + argv, _, minted = worker._cli_tui_command(None) + assert argv[1] == "--session-id" and argv[2] == minted + + +def test_worker_fields_and_private_state(tmp_path: Path) -> None: + worker = _worker(tmp_path, model_name="sonnet", allowed_tools=[]) + worker._client = Client() + worker._running = True + dumped = worker.model_dump() + assert dumped["worker_class_id"] == "claude-code" + assert dumped["model_name"] == "sonnet" + assert dumped["allowed_tools"] == [] + assert "kind" not in dumped and "model" not in dumped + assert not any(key.startswith("_") for key in dumped) + restored = workers.ClaudeCode.model_validate(dumped) + assert restored._client is None and not restored._running + assert "model_name" not in workers.ClaudeCode.__annotations__ + assert "_make_adapter" not in workers.ClaudeCode.__dict__ + assert worker._approve is not None # still the base's method + with pytest.raises(pydantic.ValidationError): + _worker(tmp_path, worker_class_id="codex") + + +async def test_stream_start_acknowledges_query_not_response( + tmp_path: Path, +) -> None: + worker = _worker(tmp_path) + entered, accepted = asyncio.Event(), asyncio.Event() + + class SlowQuery(Client): + async def query(self, prompt: Any) -> None: + entered.set() + await accepted.wait() + await super().query(prompt) + + client = SlowQuery([_result()]) + worker._client = client + stream = worker._cli_turn([m.TextPart(text="hello")]) + async with asyncio.timeout(5): + first = asyncio.create_task(anext(stream)) + try: + await entered.wait() + assert not first.done() + assert not worker._running + accepted.set() + assert isinstance(await first, events.StreamStart) + assert client.queries == ["hello"] + # No response was read to acknowledge the send. + assert len(client.replies) == 1 + assert worker._running + assert isinstance(await anext(stream), events.StreamEnd) + finally: + accepted.set() + await first + await stream.aclose() + assert not worker._running + + +async def test_query_failure_does_not_acknowledge(tmp_path: Path) -> None: + worker = _worker(tmp_path) + worker._client = mock.Mock( + query=mock.AsyncMock( + side_effect=claude_agent_sdk.CLIConnectionError("gone") + ) + ) + stream = worker._cli_turn([m.TextPart(text="hello")]) + with pytest.raises(workers.WorkerError, match="lost the CLI connection"): + await anext(stream) + assert not worker._running + + +async def test_closing_turn_clears_running_flag(tmp_path: Path) -> None: + worker = _worker(tmp_path) + worker._client = Client() + stream = worker._cli_turn([m.TextPart(text="hello")]) + assert isinstance(await anext(stream), events.StreamStart) + assert worker._running + await stream.aclose() + assert not worker._running + + +async def test_running_send_preserves_text_and_files(tmp_path: Path) -> None: + worker = _worker(tmp_path) + worker._client = Client() + worker._running = True + assert await worker._cli_send_running([m.TextPart(text="first")]) + assert await worker._cli_send_running( + [ + m.TextPart(text="look"), + m.FilePart(data=b"notes", media_type="text/plain"), + m.FilePart(data=b"\x89PNG", media_type="image/png"), + m.FilePart(data=b"%PDF", media_type="application/pdf"), + ] + ) + text, blocks = worker._client.queries + assert text == "first" + (record,) = [record async for record in blocks] + assert record["message"]["content"] == [ + {"type": "text", "text": "look"}, + {"type": "text", "text": "\nnotes\n"}, + { + "type": "image", + "source": { + "type": "base64", + "media_type": "image/png", + "data": "iVBORw==", + }, + }, + { + "type": "document", + "source": { + "type": "base64", + "media_type": "application/pdf", + "data": "JVBERg==", + }, + }, + ] + + +async def test_running_send_rejects_unsupported_files(tmp_path: Path) -> None: + worker = _worker(tmp_path) + worker._client = Client() + worker._running = True + with pytest.raises(workers.WorkerError, match="application/zip"): + await worker._cli_send_running( + [m.FilePart(data=b"PK", media_type="application/zip")] + ) + assert worker._client.queries == [] + + +async def test_running_send_returns_false_only_before_writing( + tmp_path: Path, +) -> None: + worker = _worker(tmp_path) + client = Client() + worker._client = client + prompt: _adapter.Prompt = [m.TextPart(text="next")] + assert not await worker._cli_send_running(prompt) + assert client.queries == [] + worker._running = True + + async def finish_while_reading(prompt: Any) -> str: + worker._running = False + return "next" + + with mock.patch.object(worker_, "_content", finish_while_reading): + assert not await worker._cli_send_running(prompt) + assert client.queries == [] + + +@pytest.mark.parametrize("accepted", [False, True]) +async def test_result_during_query_keeps_reader_until_accepted_input_settles( + tmp_path: Path, + accepted: bool, +) -> None: + worker = _worker(tmp_path) + writing, release, result_read = ( + asyncio.Event(), + asyncio.Event(), + asyncio.Event(), + ) + output: asyncio.Queue[Any] = asyncio.Queue() + + class DuplexClient(Client): + closed_readers = 0 + + async def query(self, prompt: Any) -> None: + if prompt == "second": + writing.set() + await release.wait() + if not accepted: + raise claude_agent_sdk.CLIConnectionError("write failed") + await super().query(prompt) + + async def receive_messages(self) -> AsyncIterator[Any]: + try: + while True: + message = await output.get() + if isinstance(message, claude_agent_sdk.ResultMessage): + result_read.set() + yield message + finally: + self.closed_readers += 1 + + client = DuplexClient() + worker._client = client + stream = worker._cli_turn([m.TextPart(text="first")]) + assert isinstance(await anext(stream), events.StreamStart) + seen: list[events.Event] = [] + + async def pump() -> None: + async for event in stream: + seen.append(event) + + async with asyncio.timeout(5): + reader = asyncio.create_task(pump()) + sender = asyncio.create_task( + worker._cli_send_running([m.TextPart(text="second")]) + ) + try: + await writing.wait() + output.put_nowait(_result()) + await result_read.wait() + # The native result has arrived while query() is suspended. + # Its accounting must wait for the write's acceptance decision. + assert not reader.done() and not sender.done() + assert worker._running and client.closed_readers == 0 + release.set() + if accepted: + assert await sender + for message in TURN: + output.put_nowait(message) + else: + with pytest.raises(workers.WorkerError, match="write failed"): + await sender + await reader + finally: + release.set() + for task in (sender, reader): + if not task.done(): + task.cancel() + await asyncio.gather(sender, reader, return_exceptions=True) + await stream.aclose() + + assert client.queries == (["first", "second"] if accepted else ["first"]) + boundaries = [ + type(e).__name__ + for e in seen + if isinstance(e, events.StreamStart | events.StreamEnd) + ] + assert boundaries == ( + ["StreamEnd", "StreamStart", "StreamEnd"] if accepted else ["StreamEnd"] + ) + if accepted: + assert [e.chunk for e in seen if isinstance(e, events.TextDelta)] == [ + "one file" + ] + assert output.empty() and client.closed_readers == 1 + assert worker._pending_results == 0 and not worker._running + assert not await worker._cli_send_running([m.TextPart(text="third")]) + output.put_nowait(_result()) + assert [ + type(e).__name__ for e in await _turn(worker, m.TextPart(text="third")) + ] == ["StreamStart", "StreamEnd"] + assert client.queries[-1] == "third" + assert client.closed_readers == 2 and output.empty() + + +async def test_multiple_accepted_queries_have_separate_boundaries( + tmp_path: Path, +) -> None: + worker = _worker(tmp_path) + client = Client([_result()], TURN, [_result()]) + worker._client = client + stream = worker._cli_turn([m.TextPart(text="first")]) + assert isinstance(await anext(stream), events.StreamStart) + assert await worker._cli_send_running([m.TextPart(text="second")]) + assert await worker._cli_send_running([m.TextPart(text="third")]) + assert worker._pending_results == 3 + async with asyncio.timeout(5): + seen = [event async for event in stream] + assert [ + type(e).__name__ + for e in seen + if isinstance(e, events.StreamStart | events.StreamEnd) + ] == ["StreamEnd", "StreamStart", "StreamEnd", "StreamStart", "StreamEnd"] + assert client.queries == ["first", "second", "third"] + assert client.replies == [] + assert worker._pending_results == 0 and not worker._running + + +@pytest.mark.parametrize("pending", [1, 2]) +async def test_failed_response_raises_before_terminal_event_and_preserves_drain( + tmp_path: Path, + pending: int, +) -> None: + worker = _worker(tmp_path) + # Failed response, accepted follow-ups, then the NEXT query's response. + client = Client( + [_result(is_error=True, result="overloaded")], + *[[_result()] for _ in range(pending)], + TURN, + ) + worker._client = client + stream = worker._cli_turn([m.TextPart(text="first")]) + assert isinstance(await anext(stream), events.StreamStart) + for index in range(pending): + assert await worker._cli_send_running( + [m.TextPart(text=f"follow-up {index}")] + ) + seen: list[events.Event] = [] + with pytest.raises(workers.WorkerError, match="overloaded"): + async for event in stream: + seen.append(event) + # No terminal event can hide the exception from a public stream reader. + assert seen == [] + assert not worker._running and worker._interrupted + assert worker._pending_results == pending + assert len(client.replies) == pending + 1 + assert not await worker._cli_send_running([m.TextPart(text="next")]) + assert len(client.queries) == pending + 1 + + # Resume drains only the already accepted replies, then sends once. + next_turn = await _turn(worker, m.TextPart(text="next")) + assert [e.chunk for e in next_turn if isinstance(e, events.TextDelta)] == [ + "one file" + ] + assert next_turn[-1].finish_reason == "stop" + assert client.queries[-1] == "next" and len(client.queries) == pending + 2 + assert client.replies == [] and worker._pending_results == 0 + assert not worker._running and not worker._interrupted + + +async def test_early_output_end_does_not_silently_drop_accepted_input( + tmp_path: Path, +) -> None: + worker = _worker(tmp_path) + worker._client = Client([_result()]) + stream = worker._cli_turn([m.TextPart(text="first")]) + assert isinstance(await anext(stream), events.StreamStart) + assert await worker._cli_send_running([m.TextPart(text="second")]) + with pytest.raises( + workers.WorkerError, match="1 response\\(s\\) outstanding" + ): + async for _ in stream: + pass + assert not worker._running + + +async def test_send_after_result_before_reader_exit_writes_nothing( + tmp_path: Path, +) -> None: + worker = _worker(tmp_path) + client = Client([_result()], [_result()]) + worker._client = client + stream = worker._cli_turn([m.TextPart(text="first")]) + assert isinstance(await anext(stream), events.StreamStart) + assert isinstance(await anext(stream), events.StreamEnd) + assert not await worker._cli_send_running([m.TextPart(text="second")]) + assert client.queries == ["first"] + with pytest.raises(StopAsyncIteration): + await anext(stream) + await _turn(worker, m.TextPart(text="second")) + assert client.queries == ["first", "second"] + assert client.replies == [] and worker._pending_results == 0 + + +async def test_interrupted_reader_drains_all_previously_accepted_responses( + tmp_path: Path, +) -> None: + worker = _worker(tmp_path) + client = Client( + [_result(is_error=True, result="interrupted")], [_result()], [_result()] + ) + worker._client = client + stream = worker._cli_turn([m.TextPart(text="first")]) + assert isinstance(await anext(stream), events.StreamStart) + assert await worker._cli_send_running([m.TextPart(text="second")]) + await worker._cli_interrupt() + await stream.aclose() + assert worker._pending_results == 2 + seen = await _turn(worker, m.TextPart(text="third")) + assert [type(event).__name__ for event in seen] == [ + "StreamStart", + "StreamEnd", + ] + assert client.replies == [] and worker._pending_results == 0 + assert not worker._interrupted + + +async def test_running_send_failure_is_not_reported_as_idle( + tmp_path: Path, +) -> None: + worker = _worker(tmp_path) + worker._running = True + with pytest.raises(workers.WorkerError, match="no CLI connection"): + await worker._cli_send_running([m.TextPart(text="x")]) + worker._client = mock.Mock( + query=mock.AsyncMock( + side_effect=claude_agent_sdk.CLIConnectionError("gone") + ) + ) + with pytest.raises(workers.WorkerError, match="lost the CLI connection"): + await worker._cli_send_running([m.TextPart(text="x")]) + + +async def test_interrupt_reports_cancelled_on_current_stream( + tmp_path: Path, +) -> None: + worker = _worker(tmp_path) + client = Client([_result(is_error=True, result="interrupted")]) + worker._client = client + stream = worker._cli_turn([m.TextPart(text="x")]) + try: + assert isinstance(await anext(stream), events.StreamStart) + await worker._cli_interrupt() + end = await anext(stream) + assert isinstance(end, events.StreamEnd) + assert end.finish_reason == "cancelled" + assert client.interrupted + assert not worker._interrupted + finally: + await stream.aclose() + + +@pytest.mark.parametrize("approve", [False, True]) +async def test_start_connect_and_close( + tmp_path: Path, + approve: bool, +) -> None: + worker = _worker( + tmp_path, + approve=approve, + executable="/custom/claude", + model_name="sonnet", + effort="high", + allowed_tools=[], + disallowed_tools=["Bash"], + max_turns=3, + ) + servers = {"docs": {"command": "docs-mcp"}} + client = mock.Mock(connect=mock.AsyncMock(), disconnect=mock.AsyncMock()) + with ( + mock.patch.object( + _adapter, "probe", new_callable=mock.AsyncMock + ) as probe, + mock.patch.object( + claude_agent_sdk, "ClaudeSDKClient", return_value=client + ) as factory, + ): + probe.return_value = "2.1.289" + await worker._cli_start(servers) + assert worker._cli_version == "2.1.289" + assert worker._approval_callback == ( + worker._approve if approve else None + ) + probe.assert_awaited_once_with( + "claude-code", + "/custom/claude", + install=worker_.INSTALL, + verified=worker_.VERIFIED_VERSION, + cwd=str(tmp_path.resolve()), + env=worker.env, + ) + sid = await worker._cli_open( + session_id=None, fork=False, seed=None, instructions="Be brief" + ) + options = factory.call_args.kwargs["options"] + assert options.session_id == sid and options.resume is None + assert options.cli_path == "/custom/claude" + assert options.cwd == str(tmp_path.resolve()) + assert options.env == worker.env + assert options.model == "sonnet" + assert options.effort == "high" + assert options.thinking == {"type": "adaptive"} + assert options.tools == [] + assert options.disallowed_tools == ["Bash"] + assert options.max_turns == 3 + assert options.mcp_servers == servers + assert options.system_prompt["append"] == "Be brief" + if approve: + assert options.can_use_tool == worker._can_use_tool + assert options.hooks["PreToolUse"][0].hooks == [ + worker._pre_tool_use + ] + else: + assert options.permission_mode == "bypassPermissions" + assert options.can_use_tool is None + client.connect.assert_awaited_once() + worker._running = worker._interrupted = True + await worker._cli_close() + await worker._cli_close() + client.disconnect.assert_awaited_once() + assert worker._client is None + assert not worker._running and not worker._interrupted + assert worker._approval_callback is None + assert worker._instructions is None and worker._mcp_servers == {} + + +@pytest.mark.parametrize("granted", [False, True]) +async def test_approval_callbacks_do_not_shadow_base_method( + tmp_path: Path, + granted: bool, +) -> None: + worker = _worker(tmp_path, approve=True) + approve = mock.AsyncMock(return_value=(granted, "policy")) + worker._approval_callback = approve + output = await worker._pre_tool_use( + {"tool_name": "Read", "tool_input": {"path": "a"}}, "t1", None + ) + assert output["hookSpecificOutput"]["permissionDecision"] == ( + "allow" if granted else "deny" + ) + approve.assert_awaited_once_with("t1", "Read", {"path": "a"}) + result = await worker._can_use_tool( + "Read", {"path": "a"}, claude_agent_sdk.ToolPermissionContext() + ) + assert result.behavior == ("allow" if granted else "deny") + assert callable(worker._approve) + if not granted: + assert ( + output["hookSpecificOutput"]["permissionDecisionReason"] == "policy" + ) + assert isinstance(result, claude_agent_sdk.PermissionResultDeny) + assert result.message == "policy" + + +@pytest.mark.parametrize("fork", [False, True]) +async def test_open_resumes_or_natively_forks( + tmp_path: Path, fork: bool +) -> None: + worker = _worker(tmp_path) + with ( + mock.patch.object( + claude_agent_sdk, "get_session_info", return_value=object() + ) as known, + mock.patch.object( + claude_agent_sdk, + "fork_session", + return_value=SimpleNamespace(session_id="child"), + ) as native_fork, + mock.patch.object( + workers.ClaudeCode, "_connect", new_callable=mock.AsyncMock + ) as connect, + ): + sid = await worker._cli_open( + session_id="parent", fork=fork, seed=None, instructions=None + ) + assert sid == ("child" if fork else "parent") + known.assert_called_once_with("parent", str(tmp_path.resolve())) + connect.assert_awaited_once_with(sid, resume=sid) + if fork: + native_fork.assert_called_once_with( + "parent", str(tmp_path.resolve()) + ) + else: + native_fork.assert_not_called() + + +async def test_unknown_session_is_rejected_before_connect( + tmp_path: Path, +) -> None: + worker = _worker(tmp_path) + with ( + mock.patch.object( + claude_agent_sdk, "get_session_info", return_value=None + ), + mock.patch.object( + workers.ClaudeCode, "_connect", new_callable=mock.AsyncMock + ) as connect, + ): + with pytest.raises(workers.WorkerError, match="no session ghost"): + await worker._cli_open( + session_id="ghost", fork=False, seed=None, instructions=None + ) + connect.assert_not_awaited() + + +async def test_history_and_session_listing_use_the_cli_store( + tmp_path: Path, +) -> None: + worker = _worker(tmp_path) + record = SimpleNamespace( + type="user", message={"role": "user", "content": "hello"} + ) + info = SimpleNamespace( + session_id="s", + custom_title=None, + summary="summary", + first_prompt="hello", + cwd=str(tmp_path), + created_at=10, + last_modified=20, + ) + with ( + mock.patch.object( + claude_agent_sdk, "get_session_info", return_value=info + ), + mock.patch.object( + claude_agent_sdk, "get_session_messages", return_value=[record] + ) as history, + mock.patch.object( + claude_agent_sdk, "list_sessions", return_value=[info] + ) as sessions, + ): + (message,) = await worker._cli_history("s") + assert message.role == "user" + (part,) = message.parts + assert isinstance(part, m.TextPart) and part.text == "hello" + (session,) = await worker._cli_list_sessions() + assert session.session_id == "s" and session.title == "summary" + assert session.created_at == 10 and session.updated_at == 20 + history.assert_called_once_with("s", str(tmp_path.resolve())) + sessions.assert_called_once_with(str(tmp_path.resolve())) + + +def test_tui_needs_no_open_or_optional_sdk(tmp_path: Path) -> None: + worker = _worker( + tmp_path, + executable="/custom/claude", + allowed_tools=[], + disallowed_tools=["Bash"], + ) + with mock.patch.object( + worker_, "_sdk", side_effect=AssertionError("SDK imported") + ): + argv, env, sid = worker._cli_tui_command(None) + assert argv[:3] == ["/custom/claude", "--session-id", sid] + assert argv[argv.index("--tools") + 1] == "" + assert argv[argv.index("--disallowedTools") + 1] == "Bash" + assert env["CLAUDE_CONFIG_DIR"] == str(tmp_path / "config") + assert worker._client is None diff --git a/tests/workers/_adapters/__init__.py b/tests/workers/codex/__init__.py similarity index 100% rename from tests/workers/_adapters/__init__.py rename to tests/workers/codex/__init__.py diff --git a/tests/workers/codex/test_adapter.py b/tests/workers/codex/test_adapter.py new file mode 100644 index 00000000..aba4165c --- /dev/null +++ b/tests/workers/codex/test_adapter.py @@ -0,0 +1,703 @@ +"""The Codex worker transport against a scripted `codex app-server`, offline.""" + +from __future__ import annotations + +import asyncio +import json +from collections.abc import Callable +from typing import Any, cast + +import pytest + +from ai import workers +from ai.types import events +from ai.types import messages as m +from ai.workers import _adapter +from ai.workers.codex import jsonrpc + +from .. import fakes + +THREAD = "T" +CWD = "/w" + + +class AppServer: + """Answers like `codex app-server`. `turn` plays out after turn/start.""" + + def __init__(self, turn: list[dict[str, Any]] | None = None) -> None: + self.process = fakes.FakeProcess(self.answer) + self.turn = turn or [] + self.on_turn: Callable[[], None] | None = None + self.threads: dict[str, dict[str, Any]] = { + THREAD: {"id": THREAD, "cwd": CWD, "turns": []} + } + + def says(self, method: str, **params: Any) -> None: + self.process.server_says({"method": method, "params": params}) + + def answer(self, message: dict[str, Any]) -> Any: + method = message.get("method") + params = message.get("params") or {} + if method == "turn/start": + if self.on_turn is not None: + self.on_turn() + for record in self.turn: + self.process.server_says(record) + return {"turn": {"id": "turn-1"}} + if method == "turn/interrupt": + self.says( + "turn/completed", + threadId=THREAD, + turn={"id": "turn-1", "status": "interrupted"}, + ) + return {} + if method == "thread/read": + return {"thread": self.threads.get(str(params.get("threadId")), {})} + if method in ("thread/start", "thread/fork"): + return {"thread": {"id": "new"}} + if method == "thread/resume": + return {"thread": {"id": params["threadId"]}} + if "method" in message and "id" in message: + return {} + return None + + def sent(self, method: str) -> list[dict[str, Any]]: + return [w for w in self.process.written if w.get("method") == method] + + +def note(method: str, **params: Any) -> dict[str, Any]: + return { + "method": method, + "params": {"threadId": THREAD, "turnId": "turn-1", **params}, + } + + +COMMAND = { + "type": "commandExecution", + "id": "c1", + "command": "/bin/zsh -lc 'cat secret.txt'", + "aggregatedOutput": "the word is HERON\n", + "exitCode": 0, + "status": "completed", +} + +TURN = [ + note("item/reasoning/summaryTextDelta", itemId="r1", delta="plan"), + note("item/completed", item={"type": "reasoning", "id": "r1"}), + note("item/started", item={**COMMAND, "aggregatedOutput": None}), + note("item/completed", item=COMMAND), + note("item/agentMessage/delta", itemId="a1", delta="HER"), + note("item/agentMessage/delta", itemId="a1", delta="ON"), + note("item/completed", item={"type": "agentMessage", "id": "a1"}), + note( + "thread/tokenUsage/updated", + tokenUsage={"lastTurn": {"inputTokens": 10, "outputTokens": 4}}, + ), + note("turn/completed", turn={"id": "turn-1", "status": "completed"}), +] + + +def _worker( + server: AppServer, approve: _adapter.Approve | None = None, **options: Any +) -> workers.Codex: + worker = workers.Codex(cwd=CWD, approve=approve is not None, **options) + worker._approval_callback = approve + peer = jsonrpc.JsonRpcPeer(cast("Any", server.process), kind="codex") + worker._process = cast("Any", server.process) + worker._peer = peer + worker._thread = THREAD + peer.start(worker._on_notify, worker._on_request, on_crash=worker._on_crash) + return worker + + +async def _turn(worker: workers.Codex, text: str = "go") -> list[Any]: + async with asyncio.timeout(5): + return [e async for e in worker._cli_turn([m.TextPart(text=text)])] + + +async def test_a_turn_streams_in_the_model_view() -> None: + worker = _worker(AppServer(TURN)) + seen = await _turn(worker) + assert [type(e).__name__ for e in seen] == [ + "StreamStart", + "ReasoningStart", + "ReasoningDelta", + "ReasoningEnd", + "BuiltinToolStart", + "BuiltinToolDelta", + "BuiltinToolEnd", + "BuiltinToolResult", + "TextStart", + "TextDelta", + "TextDelta", + "TextEnd", + "StreamEnd", + ] + result = next(e for e in seen if isinstance(e, events.BuiltinToolResult)) + # codex 0.160 reports a command's output as `aggregatedOutput`. + assert result.result.result == "the word is HERON\n" + end = seen[-1] + assert end.finish_reason == "stop" + assert end.usage.input_tokens == 10 + hydrator = events.MessageHydrator() + for event in seen: + hydrator.feed(event) + assert [type(p).__name__ for p in hydrator.message.parts] == [ + "ReasoningPart", + "BuiltinToolCallPart", + "BuiltinToolReturnPart", + "TextPart", + ] + + +async def test_a_message_that_was_never_streamed_still_arrives() -> None: + server = AppServer( + [ + note( + "item/completed", + item={"type": "agentMessage", "id": "a1", "text": "PONG"}, + ), + note( + "turn/completed", turn={"id": "turn-1", "status": "completed"} + ), + ] + ) + seen = await _turn(_worker(server)) + assert [e.chunk for e in seen if isinstance(e, events.TextDelta)] == [ + "PONG" + ] + + +async def test_another_turns_notifications_are_not_this_turns() -> None: + server = AppServer( + [ + { + "method": "turn/completed", + "params": {"threadId": THREAD, "turn": {"id": "old"}}, + }, + { + "method": "item/agentMessage/delta", + "params": {"threadId": "other", "itemId": "x", "delta": "no"}, + }, + note( + "turn/completed", turn={"id": "turn-1", "status": "completed"} + ), + ] + ) + seen = await _turn(_worker(server)) + assert [type(e).__name__ for e in seen] == ["StreamStart", "StreamEnd"] + + +async def test_a_failed_turn_without_a_key_is_not_authenticated() -> None: + server = AppServer( + [ + note("error", error={"message": "401 Unauthorized"}), + note("turn/completed", turn={"id": "turn-1", "status": "failed"}), + ] + ) + with pytest.raises(workers.NotAuthenticatedError): + await _turn(_worker(server)) + + +@pytest.mark.parametrize("granted", [True, False]) +async def test_approvals_ask_and_answer(granted: bool) -> None: + server = AppServer() + asked: list[tuple[str, str, dict[str, Any]]] = [] + + async def approve( + call_id: str, name: str, tool_input: dict[str, Any] + ) -> tuple[bool, str]: + asked.append((call_id, name, tool_input)) + return granted, "no" + + def ask() -> None: + server.process.server_says( + { + "id": 500, + "method": "item/commandExecution/requestApproval", + "params": { + "threadId": THREAD, + "turnId": "turn-1", + "itemId": "i1", + "command": "rm -rf /", + }, + } + ) + + def complete(message: dict[str, Any]) -> Any: + if message.get("id") == 500: + server.says( + "turn/completed", + threadId=THREAD, + turn={"id": "turn-1", "status": "completed"}, + ) + return None + return AppServer.answer(server, message) + + server.on_turn = ask + server.process.answer = complete + worker = _worker(server, approve) + assert worker._thread_params()["approvalPolicy"] == "untrusted" + await _turn(worker) + assert asked == [("i1", "commandExecution", {"command": "rm -rf /"})] + answer = next(w for w in server.process.written if w.get("id") == 500) + assert answer["result"] == {"decision": "accept" if granted else "decline"} + + +async def test_without_a_gate_codex_never_asks() -> None: + worker = _worker(AppServer()) + assert worker._thread_params() == { + "sandbox": "danger-full-access", + "approvalPolicy": "never", + } + + +async def test_an_interrupted_turn_ends_as_cancelled() -> None: + server = AppServer() + worker = _worker(server) + turn = worker._cli_turn([m.TextPart(text="go")]) + assert isinstance(await anext(turn), events.StreamStart) + reader = asyncio.ensure_future(_rest(turn)) + await asyncio.sleep(0) + await worker._cli_interrupt() + seen = await asyncio.wait_for(reader, 5) + assert seen[-1].finish_reason == "cancelled" + assert server.sent("turn/interrupt")[0]["params"] == { + "threadId": THREAD, + "turnId": "turn-1", + } + + +async def _rest(turn: Any) -> list[Any]: + return [e async for e in turn] + + +async def test_opening_a_new_thread_seeds_it() -> None: + server = AppServer() + worker = _worker(server) + seed = [ + m.Message(role="user", parts=[m.TextPart(text="earlier")]), + m.Message(role="assistant", parts=[m.TextPart(text="answer")]), + ] + assert ( + await worker._cli_open( + session_id=None, fork=False, seed=seed, instructions="Be terse." + ) + == "new" + ) + started = server.sent("thread/start")[0]["params"] + assert started["cwd"] == CWD + assert started["developerInstructions"] == "Be terse." + injected = server.sent("thread/inject_items")[0]["params"] + assert injected["threadId"] == "new" + assert [i["role"] for i in injected["items"]] == ["user", "assistant"] + + +async def test_a_fork_is_native() -> None: + server = AppServer() + worker = _worker(server) + forked = await worker._cli_open( + session_id=THREAD, fork=True, seed=None, instructions=None + ) + assert forked == "new" + assert server.sent("thread/fork")[0]["params"]["threadId"] == THREAD + + +async def test_a_thread_from_another_directory_is_refused() -> None: + server = AppServer() + server.threads["elsewhere"] = {"id": "elsewhere", "cwd": "/other"} + worker = _worker(server) + with pytest.raises(workers.WorkerError, match="/other"): + await worker._cli_open( + session_id="elsewhere", fork=False, seed=None, instructions=None + ) + + +async def test_history_has_the_cli_tools_as_builtin_parts() -> None: + server = AppServer() + server.threads[THREAD]["turns"] = [ + { + "items": [ + { + "type": "userMessage", + "content": [{"type": "text", "text": "q"}], + }, + COMMAND, + {"type": "agentMessage", "text": "HERON"}, + ] + } + ] + history = await _worker(server)._cli_history(THREAD) + assert [x.role for x in history] == ["user", "assistant", "assistant"] + call, result = history[1].parts + assert isinstance(call, m.BuiltinToolCallPart) + assert json.loads(call.tool_args)["command"].endswith("'cat secret.txt'") + assert isinstance(result, m.BuiltinToolReturnPart) + assert result.result == "the word is HERON\n" + + +async def test_listing_asks_for_this_directory_and_reads_every_page() -> None: + """`thread/list` is paged, and the store is the whole machine's.""" + asked: list[dict[str, Any]] = [] + pages = { + None: ({"id": "t1", "cwd": CWD}, "p2"), + "p2": ({"id": "t2", "cwd": CWD}, None), + } + server = AppServer() + + def answer(message: dict[str, Any]) -> Any: + if message.get("method") != "thread/list": + return AppServer.answer(server, message) + params = message["params"] + asked.append(params) + thread, cursor = pages[params.get("cursor")] + return {"data": [thread], "nextCursor": cursor} + + server.process.answer = answer + infos = await _worker(server)._cli_list_sessions() + assert [i.session_id for i in infos] == ["t1", "t2"] + assert all(p["cwd"] == CWD for p in asked) + assert [p.get("cursor") for p in asked] == [None, "p2"] + + +def test_the_tui_gets_no_bridge_before_open() -> None: + worker = workers.Codex( + mcp_servers={ + "ai_sdk": {"url": "http://127.0.0.1:1/mcp"}, + "docs": {"command": "docs-mcp"}, + }, + ) + argv, _, minted = worker._cli_tui_command(THREAD) + assert argv[:3] == ["codex", "resume", THREAD] + assert 'mcp_servers.docs.command="docs-mcp"' in argv + assert not any("ai_sdk" in arg for arg in argv) + assert minted is None # codex picks its own ids + assert worker._process is None + + +def test_tui_uses_public_settings_before_open() -> None: + worker = workers.Codex( + executable="/custom/codex", + env={"CODEX_HOME": "/custom/home"}, + model_name="test-model", + effort="max", + config={"model_reasoning_effort": "low"}, + ) + argv, env, minted = worker._cli_tui_command(None) + assert argv[0] == "/custom/codex" + assert argv[-2:] == ["--model", "test-model"] + assert 'model_reasoning_effort="low"' in argv + assert env == worker.env + assert env is not worker.env + assert minted is None + assert worker._process is None + + +@pytest.mark.parametrize("approve", [False, True]) +async def test_start_initializes_runtime_from_worker_fields( + monkeypatch: pytest.MonkeyPatch, approve: bool +) -> None: + server = AppServer() + probed: list[tuple[str, str, dict[str, Any]]] = [] + spawned: list[tuple[list[str], dict[str, Any]]] = [] + + async def probe(kind: str, executable: str, **kwargs: Any) -> str: + probed.append((kind, executable, kwargs)) + return "codex 0.160.1" + + async def spawn(argv: list[str], **kwargs: Any) -> jsonrpc.Process: + spawned.append((argv, kwargs)) + return cast("jsonrpc.Process", server.process) + + monkeypatch.setattr(_adapter, "probe", probe) + monkeypatch.setattr(jsonrpc, "spawn", spawn) + worker = workers.Codex( + cwd=CWD, + executable="/custom/codex", + env={"CODEX_HOME": "/custom/home"}, + model_name="test-model", + effort="max", + approve=approve, + sandbox="workspace-write", + config={"mcp_servers.docs.command": "custom-mcp"}, + ) + settings = worker.model_dump() + servers = { + "ai_sdk": {"url": "http://127.0.0.1:1/mcp"}, + "docs": {"command": "docs-mcp"}, + } + try: + await worker._cli_start(servers) + assert worker._cli_version == "codex 0.160.1" + assert worker._process is cast("jsonrpc.Process", server.process) + assert worker._peer is not None + assert probed[0][:2] == ("codex", "/custom/codex") + assert probed[0][2]["cwd"] == CWD + assert probed[0][2]["env"] == worker.env + argv, kwargs = spawned[0] + assert argv[:2] == ["/custom/codex", "app-server"] + assert 'model_reasoning_effort="xhigh"' in argv + assert 'mcp_servers.docs.command="custom-mcp"' in argv + assert "mcp_servers.ai_sdk.tool_timeout_sec=86400" in argv + assert kwargs == {"cwd": CWD, "env": worker.env} + assert server.sent("initialize") + assert server.sent("initialized") + assert worker._thread_params() == { + "sandbox": "workspace-write", + "approvalPolicy": "untrusted" if approve else "never", + "model": "test-model", + } + assert worker._approval_callback == ( + worker._approve if approve else None + ) + assert worker.model_dump() == settings + assert settings["worker_class_id"] == "codex" + assert settings["model_name"] == "test-model" + assert "kind" not in settings and "model" not in settings + assert not any(k.startswith("_") for k in settings) + finally: + await worker._cli_close() + assert worker._process is None + assert worker._peer is None + assert worker._approval_callback is None + await worker._cli_close() # idempotent + + +async def test_a_failed_handshake_closes_the_process( + monkeypatch: pytest.MonkeyPatch, +) -> None: + server = AppServer() + terminated = False + + async def probe(*args: Any, **kwargs: Any) -> str: + return "codex 0.160.1" + + async def spawn(*args: Any, **kwargs: Any) -> jsonrpc.Process: + return cast("jsonrpc.Process", server.process) + + async def terminate() -> None: + nonlocal terminated + terminated = True + + def answer(message: dict[str, Any]) -> None: + server.process.server_says( + {"id": message["id"], "error": {"message": "bad handshake"}} + ) + + monkeypatch.setattr(_adapter, "probe", probe) + monkeypatch.setattr(jsonrpc, "spawn", spawn) + monkeypatch.setattr(server.process, "terminate", terminate) + server.process.answer = answer + worker = workers.Codex(cwd=CWD) + with pytest.raises(jsonrpc.JsonRpcError, match="bad handshake"): + await worker._cli_start({}) + assert terminated + assert worker._process is None + assert worker._peer is None + + +async def test_stream_start_waits_for_cli_acceptance() -> None: + server = AppServer() + received = asyncio.Event() + + def answer(message: dict[str, Any]) -> None: + assert message["method"] == "turn/start" + received.set() + + server.process.answer = answer + worker = _worker(server) + turn = worker._cli_turn([m.TextPart(text="go")]) + first = asyncio.ensure_future(anext(turn)) + try: + await asyncio.wait_for(received.wait(), 5) + assert not first.done() + request = server.sent("turn/start")[0] + server.process.server_says( + {"id": request["id"], "result": {"turn": {"id": "turn-1"}}} + ) + assert isinstance(await asyncio.wait_for(first, 5), events.StreamStart) + assert worker._turn == "turn-1" + finally: + first.cancel() + await asyncio.gather(first, return_exceptions=True) + await turn.aclose() + await worker._cli_close() + + +@pytest.mark.parametrize("malformed", [False, True]) +async def test_rejected_or_malformed_start_never_acknowledges( + malformed: bool, +) -> None: + server = AppServer() + + def answer(message: dict[str, Any]) -> Any: + if malformed: + return {"turn": {}} + server.process.server_says( + { + "id": message["id"], + "error": {"code": -32600, "message": "start rejected"}, + } + ) + return None + + server.process.answer = answer + worker = _worker(server) + turn = worker._cli_turn([m.TextPart(text="go")]) + try: + with pytest.raises(workers.WorkerError): + await anext(turn) + assert worker._turn is None + assert worker._queue is None + finally: + await turn.aclose() + await worker._cli_close() + + +async def test_running_send_preserves_text_and_images() -> None: + server = AppServer() + worker = _worker(server) + turn = worker._cli_turn([m.TextPart(text="go")]) + try: + assert isinstance(await anext(turn), events.StreamStart) + image = "data:image/png;base64,aW1hZ2U=" + assert await worker._cli_send_running( + [m.TextPart(text="look"), m.FilePart.from_url(image)] + ) + assert server.sent("turn/steer")[0]["params"] == { + "threadId": THREAD, + "expectedTurnId": "turn-1", + "input": [ + {"type": "text", "text": "look"}, + {"type": "image", "url": image}, + ], + } + assert len(server.sent("turn/start")) == 1 + finally: + await turn.aclose() + await worker._cli_close() + + +async def test_idle_send_reports_no_running_turn_without_sending() -> None: + server = AppServer() + worker = _worker(server) + try: + assert not await worker._cli_send_running([m.TextPart(text="next")]) + assert not server.sent("turn/steer") + assert not server.sent("turn/start") + finally: + await worker._cli_close() + + +@pytest.mark.parametrize( + "detail", ["no active turn", "no active turn to steer"] +) +async def test_steer_racing_turn_end_can_start_a_new_turn(detail: str) -> None: + server = AppServer() + + def answer(message: dict[str, Any]) -> Any: + if message.get("method") == "turn/steer": + server.says( + "turn/completed", + threadId=THREAD, + turn={"id": "turn-1", "status": "completed"}, + ) + server.process.server_says( + { + "id": message["id"], + "error": {"code": -32600, "message": detail}, + } + ) + return None + return AppServer.answer(server, message) + + server.process.answer = answer + worker = _worker(server) + turn = worker._cli_turn([m.TextPart(text="go")]) + try: + assert isinstance(await anext(turn), events.StreamStart) + # The event consumer has not drained the completed turn yet. + assert not await worker._cli_send_running([m.TextPart(text="next")]) + assert len(server.sent("turn/start")) == 1 + seen = await asyncio.wait_for(_rest(turn), 5) + assert isinstance(seen[-1], events.StreamEnd) + assert worker._turn is None + # The base drains the old turn before starting the new one. + server.turn = TURN + await _turn(worker, "next") + assert len(server.sent("turn/start")) == 2 + assert len(server.sent("turn/steer")) == 1 + finally: + await turn.aclose() + await worker._cli_close() + + +@pytest.mark.parametrize( + ("code", "detail"), + [ + (-32600, "expected turn id does not match active turn id"), + (-32600, "invalid input"), + (-32603, "internal error"), + (-32603, "no active turn"), + ], +) +async def test_other_steer_rejections_are_not_retried( + code: int, + detail: str, +) -> None: + server = AppServer() + + def answer(message: dict[str, Any]) -> Any: + if message.get("method") == "turn/steer": + # Even a concurrent completion must not hide unrelated failures. + server.says( + "turn/completed", + threadId=THREAD, + turn={"id": "turn-1", "status": "completed"}, + ) + server.process.server_says( + { + "id": message["id"], + "error": {"code": code, "message": detail}, + } + ) + return None + return AppServer.answer(server, message) + + server.process.answer = answer + worker = _worker(server) + turn = worker._cli_turn([m.TextPart(text="go")]) + try: + assert isinstance(await anext(turn), events.StreamStart) + with pytest.raises(workers.WorkerError, match="steer rejected"): + await worker._cli_send_running([m.TextPart(text="next")]) + assert len(server.sent("turn/start")) == 1 + assert len(server.sent("turn/steer")) == 1 + finally: + await turn.aclose() + await worker._cli_close() + + +@pytest.mark.parametrize("error", [TimeoutError(), workers.WorkerError("lost")]) +async def test_ambiguous_steer_failures_are_not_retried( + monkeypatch: pytest.MonkeyPatch, + error: Exception, +) -> None: + server = AppServer() + worker = _worker(server) + turn = worker._cli_turn([m.TextPart(text="go")]) + + async def fail(*args: Any, **kwargs: Any) -> Any: + raise error + + try: + assert isinstance(await anext(turn), events.StreamStart) + assert worker._peer is not None + monkeypatch.setattr(worker._peer, "call", fail) + with pytest.raises(type(error)) as caught: + await worker._cli_send_running([m.TextPart(text="next")]) + assert caught.value is error + assert len(server.sent("turn/start")) == 1 + finally: + await turn.aclose() + await worker._cli_close() diff --git a/tests/workers/_adapters/test_jsonrpc.py b/tests/workers/codex/test_jsonrpc.py similarity index 99% rename from tests/workers/_adapters/test_jsonrpc.py rename to tests/workers/codex/test_jsonrpc.py index a6849316..23deb002 100644 --- a/tests/workers/_adapters/test_jsonrpc.py +++ b/tests/workers/codex/test_jsonrpc.py @@ -9,7 +9,7 @@ import pytest from ai import workers -from ai.workers._adapters import jsonrpc +from ai.workers.codex import jsonrpc from .. import fakes diff --git a/tests/workers/fakes.py b/tests/workers/fakes.py index 51ed6b6c..6196bd89 100644 --- a/tests/workers/fakes.py +++ b/tests/workers/fakes.py @@ -15,7 +15,7 @@ from ai.types import events from ai.types import messages as m from ai.types import usage as usage_ -from ai.workers._adapters import base +from ai.workers import _adapter, _convert @dataclasses.dataclass @@ -56,8 +56,8 @@ def tool( ) -> list[Step]: """One of the CLI's own tool calls, start to result.""" return [ - *base.builtin_call(call_id, name, args, started=set()), - base.builtin_result(call_id, name, result, is_error=False), + *_convert.builtin_call(call_id, name, args, started=set()), + _convert.builtin_result(call_id, name, result, is_error=False), ] @@ -67,7 +67,9 @@ def reply(prompt: str) -> list[Step]: class FakeAdapter: - def __init__(self, script: Script, approve: base.Approve | None) -> None: + def __init__( + self, script: Script, approve: _adapter.Approve | None + ) -> None: self.script = script self.approve = approve self.version: str | None = None @@ -79,6 +81,7 @@ def __init__(self, script: Script, approve: base.Approve | None) -> None: self.closed = False self.stored: dict[str, list[m.Message]] = {} self._resume = asyncio.Event() + self.running = False async def start(self) -> None: self.version = "fake 1.0" @@ -103,49 +106,69 @@ async def open( } ) if fork: - return f"{session_id}-fork" - return session_id or "s1" - - async def turn(self, prompt: base.Prompt) -> AsyncIterator[events.Event]: - self.turns.append(base.text_of(prompt)) + fork_id = f"{session_id}-fork" + self.stored[fork_id] = await self.history(session_id or "") + return fork_id + opened = session_id or "s1" + if seed is not None: + self.stored[opened] = [ + message.model_copy(deep=True) for message in seed + ] + return opened + + async def turn( + self, prompt: _adapter.Prompt + ) -> AsyncIterator[events.Event]: + self.turns.append(_convert.text_of(prompt)) self._resume.clear() - yield events.StreamStart() - for step in self.script(base.text_of(prompt)): - if isinstance(step, Pause): - await self._resume.wait() - yield events.StreamEnd(finish_reason="cancelled") - return - if isinstance(step, Run): - await step.fn() - elif isinstance(step, Ask): - assert self.approve is not None - self.answers.append( - await self.approve( - step.tool_call_id, step.tool_name, step.tool_input + self.running = True + try: + yield events.StreamStart() + for step in self.script(_convert.text_of(prompt)): + if isinstance(step, Pause): + await self._resume.wait() + yield events.StreamEnd(finish_reason="cancelled") + return + if isinstance(step, Run): + await step.fn() + elif isinstance(step, Ask): + assert self.approve is not None + self.answers.append( + await self.approve( + step.tool_call_id, step.tool_name, step.tool_input + ) ) - ) - else: - yield step - yield events.StreamEnd( - finish_reason="stop", - usage=usage_.Usage(input_tokens=3, output_tokens=2), - ) - - async def steer(self, text: str) -> None: - self.steers.append(text) + else: + yield step + yield events.StreamEnd( + finish_reason="stop", + usage=usage_.Usage(input_tokens=3, output_tokens=2), + ) + finally: + self.running = False + + async def send_running(self, prompt: _adapter.Prompt) -> bool: + if not self.running: + return False + self.steers.append(_convert.text_of(prompt)) + return True async def interrupt(self) -> None: self.interrupts += 1 self._resume.set() async def history(self, session_id: str) -> list[m.Message]: - return self.stored.get(session_id, []) + return [ + message.model_copy(deep=True) + for message in self.stored.get(session_id, []) + ] - async def list_sessions(self) -> list[base.SessionInfo]: - return [base.SessionInfo(session_id="s1", title="first")] + async def list_sessions(self) -> list[_adapter.SessionInfo]: + return [_adapter.SessionInfo(session_id="s1", title="first")] + @staticmethod def tui_command( - self, session_id: str | None + session_id: str | None, ) -> tuple[list[str], dict[str, str], str | None]: return ( [sys.executable, "-c", "pass"], @@ -157,21 +180,65 @@ def tui_command( class FakeWorker(workers.Worker): """A worker whose CLI is a `FakeAdapter`, run by a script.""" - kind: Literal["fake"] = "fake" + worker_class_id: Literal["fake"] = "fake" _script: Script = pydantic.PrivateAttr(default_factory=lambda: reply) _fake: FakeAdapter | None = pydantic.PrivateAttr(default=None) _servers: dict[str, dict[str, Any]] = pydantic.PrivateAttr( default_factory=dict ) - def _make_adapter( - self, - mcp_servers: dict[str, dict[str, Any]], - approve: base.Approve | None, - ) -> base.Adapter: - self._fake = FakeAdapter(self._run, approve) + async def _cli_start(self, mcp_servers: dict[str, dict[str, Any]]) -> None: + self._fake = FakeAdapter( + self._run, self._approve if self.approve else None + ) self._servers = mcp_servers - return self._fake + # A resumed/native-forked fake has the serialized mirror in its store. + # History reads and forks must not alias the stored messages. + if self.session_id is not None: + self.fake.stored[self.session_id] = [ + message.model_copy(deep=True) for message in self.messages + ] + await self.fake.start() + self._cli_version = self.fake.version + + async def _cli_close(self) -> None: + if self._fake is not None: + await self.fake.close() + + async def _cli_open( + self, + *, + session_id: str | None, + fork: bool, + seed: list[m.Message] | None, + instructions: str | None, + ) -> str: + return await self.fake.open( + session_id=session_id, + fork=fork, + seed=seed, + instructions=instructions, + ) + + def _cli_turn(self, prompt: _adapter.Prompt) -> AsyncIterator[events.Event]: + return self.fake.turn(prompt) + + async def _cli_send_running(self, prompt: _adapter.Prompt) -> bool: + return await self.fake.send_running(prompt) + + async def _cli_interrupt(self) -> None: + await self.fake.interrupt() + + async def _cli_history(self, session_id: str) -> list[m.Message]: + return await self.fake.history(session_id) + + async def _cli_list_sessions(self) -> list[_adapter.SessionInfo]: + return await self.fake.list_sessions() + + def _cli_tui_command( + self, session_id: str | None + ) -> tuple[list[str], dict[str, str], str | None]: + return FakeAdapter.tui_command(session_id) def _run(self, prompt: str) -> Iterable[Step]: return self._script(prompt) @@ -203,7 +270,6 @@ def __init__( self._lines: asyncio.Queue[str] = asyncio.Queue() self.answer = answer or (lambda message: {}) self.written: list[dict[str, Any]] = [] - self.pid = 0 def server_says(self, message: dict[str, Any]) -> None: self._lines.put_nowait(json.dumps(message) + "\n") diff --git a/tests/workers/pi/__init__.py b/tests/workers/pi/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/tests/workers/pi/test_adapter.py b/tests/workers/pi/test_adapter.py new file mode 100644 index 00000000..fe8ee0ce --- /dev/null +++ b/tests/workers/pi/test_adapter.py @@ -0,0 +1,853 @@ +"""The Pi worker against a scripted `pi --mode rpc`, offline. + +The records here are the shapes a real pi 1.3.0 sent when measured. +""" + +from __future__ import annotations + +import asyncio +import json +from collections.abc import Callable +from pathlib import Path +from typing import Any, cast + +import pytest + +from ai import workers +from ai.types import events +from ai.types import messages as m +from ai.workers.pi import worker as worker_ + +from .. import fakes + +SID = "s1" + + +def _update(kind: str, index: int = 0, **fields: Any) -> dict[str, Any]: + return { + "type": "message_update", + "assistantMessageEvent": { + "type": kind, + "contentIndex": index, + **fields, + }, + } + + +def _assistant(*content: dict[str, Any], stop: str = "stop") -> dict[str, Any]: + return { + "role": "assistant", + "content": list(content), + "usage": { + "input": 10, + "output": 5, + "cacheRead": 100, + "cacheWrite": 0, + "cost": {"total": 0.01}, + }, + "stopReason": stop, + } + + +CALL = { + "type": "toolCall", + "id": "toolu_1", + "name": "bash", + "arguments": {"command": "echo hi"}, +} + +# text -> tool call -> tool result -> text: what pi sent for +# "run `echo hi`, then say done". +TOOL_TURN: list[dict[str, Any]] = [ + {"type": "agent_start"}, + {"type": "message_start", "message": {"role": "assistant"}}, + _update("thinking_start"), + _update("thinking_delta", delta="plan"), + _update("thinking_end", content="plan"), + _update("toolcall_start", 1, id="toolu_1", toolName="bash"), + _update("toolcall_delta", 1, delta='{"command": "ec'), + _update("toolcall_end", 1, toolCall=CALL), + { + "type": "message_end", + "message": _assistant( + {"type": "thinking", "thinking": "plan"}, CALL, stop="toolUse" + ), + }, + { + "type": "tool_execution_end", + "toolCallId": "toolu_1", + "toolName": "bash", + "result": {"content": [{"type": "text", "text": "hi\n"}]}, + "isError": False, + }, + {"type": "message_start", "message": {"role": "assistant"}}, + _update("text_start"), + _update("text_delta", delta="done"), + _update("text_end", content="done"), + { + "type": "message_end", + "message": _assistant({"type": "text", "text": "done"}), + }, + {"type": "agent_end", "messages": []}, + {"type": "agent_settled", "aborted": False}, +] + + +class Pi: + """Answers like `pi --mode rpc`: a prompt is accepted, then `turn` + plays out; `abort` settles the turn as aborted.""" + + def __init__( + self, + turn: list[dict[str, Any]] | None = None, + *, + prompt_error: str | None = None, + ) -> None: + self.process = fakes.FakeProcess(self.answer) + self.turn = turn if turn is not None else TOOL_TURN + self.prompt_error = prompt_error + self.on_prompt: Callable[[], None] | None = None + self.streaming = False + + def says(self, record: dict[str, Any]) -> None: + if record.get("type") == "agent_start": + self.streaming = True + elif record.get("type") == "agent_settled": + self.streaming = False + self.process.server_says(record) + + def respond(self, message: dict[str, Any], **fields: Any) -> None: + self.says( + { + "type": "response", + "id": message["id"], + "command": message["type"], + **fields, + } + ) + + def answer(self, message: dict[str, Any]) -> None: + kind = message.get("type") + if kind == "prompt": + if self.prompt_error is not None: + self.respond(message, success=False, error=self.prompt_error) + return + self.streaming = True + self.respond(message, success=True, data={"disposition": "started"}) + if self.on_prompt is not None: + self.on_prompt() + return + for record in self.turn: + self.says(record) + elif kind == "abort": + self.says({"type": "agent_settled", "aborted": True}) + self.respond(message, success=True) + elif kind == "get_state": + self.respond( + message, + success=True, + data={"sessionId": SID, "isStreaming": self.streaming}, + ) + elif kind == "get_commands": + self.respond( + message, + success=True, + data={"commands": [{"name": worker_.READY}]}, + ) + elif "id" in message: + self.respond(message, success=True) + + def sent(self, kind: str) -> list[dict[str, Any]]: + return [w for w in self.process.written if w.get("type") == kind] + + +def _worker( + server: Pi | None = None, approve: Any = None, cwd: str = "/w", **env: str +) -> worker_.Pi: + worker = worker_.Pi(cwd=cwd, env=env, approve=approve is not None) + worker._approval_callback = approve + if server is not None: + agent = worker_._Agent( + cast("Any", server.process), on_dialog=worker._on_dialog + ) + agent.start() + worker._agent = agent + return worker + + +async def _turn(worker: worker_.Pi, *prompt: Any) -> list[Any]: + parts: list[m.TextPart | m.FilePart] = list(prompt) or [ + m.TextPart(text="go") + ] + async with asyncio.timeout(5): + return [e async for e in worker._cli_turn(parts)] + + +async def test_a_turn_streams_in_the_model_view() -> None: + server = Pi() + seen = await _turn(_worker(server), m.TextPart(text="say done")) + assert [type(e).__name__ for e in seen] == [ + "StreamStart", + "ReasoningStart", + "ReasoningDelta", + "ReasoningEnd", + "BuiltinToolStart", + "BuiltinToolDelta", + "BuiltinToolEnd", + "BuiltinToolResult", + "TextStart", + "TextDelta", + "TextEnd", + "StreamEnd", + ] + # The arguments travel once, whole: pi's fragments are not what it + # settles on. + delta = next(e for e in seen if isinstance(e, events.BuiltinToolDelta)) + assert json.loads(delta.chunk) == {"command": "echo hi"} + result = next(e for e in seen if isinstance(e, events.BuiltinToolResult)) + assert result.result.result == "hi\n" + end = seen[-1] + assert end.finish_reason == "stop" + # Two model calls: cached input counts as input, cost rides in raw. + assert end.usage.input_tokens == 220 + assert end.usage.output_tokens == 10 + assert end.usage.cache_read_tokens == 200 + assert end.usage.raw == {"cost_usd": 0.02} + assert server.sent("prompt")[0]["message"] == "say done" + # Blocks of different model calls never share an id. + starts = [e.block_id for e in seen if isinstance(e, events.TextStart)] + assert starts == ["2.0"] + + +async def test_images_travel_as_base64() -> None: + server = Pi() + png = m.FilePart(data=b"\x89PNG", media_type="image/png") + await _turn(_worker(server), m.TextPart(text="look"), png) + assert server.sent("prompt")[0]["images"] == [ + {"type": "image", "data": "iVBORw==", "mimeType": "image/png"} + ] + + +async def test_a_rejected_prompt_without_a_key_is_not_authenticated() -> None: + """Measured: pi refuses the prompt itself when it has no credentials.""" + server = Pi(prompt_error="No API key found for openai.\n\nUse /login") + with pytest.raises(workers.NotAuthenticatedError): + await _turn(_worker(server)) + + +async def test_a_failed_model_call_fails_the_turn() -> None: + server = Pi( + [ + { + "type": "message_end", + "message": { + **_assistant(stop="error"), + "errorMessage": "529 overloaded", + }, + }, + {"type": "agent_settled", "aborted": False}, + ] + ) + with pytest.raises(workers.WorkerError, match="overloaded"): + await _turn(_worker(server)) + + +def _ask(server: Pi) -> None: + server.says( + { + "type": "extension_ui_request", + "id": "ui-1", + "method": "input", + "title": worker_.APPROVE, + "placeholder": json.dumps( + { + "toolCallId": "toolu_1", + "toolName": "bash", + "input": {"command": "echo hi"}, + } + ), + } + ) + + +@pytest.mark.parametrize("granted", [True, False]) +async def test_approvals_ask_and_answer(granted: bool) -> None: + server = Pi() + asked: list[Any] = [] + + async def approve( + call_id: str, name: str, tool_input: dict[str, Any] + ) -> tuple[bool, str]: + asked.append((call_id, name, tool_input)) + return granted, "not that" + + def answer(message: dict[str, Any]) -> None: + if message.get("type") == "extension_ui_response": + for record in TOOL_TURN: + server.says(record) + else: + Pi.answer(server, message) + + server.on_prompt = lambda: _ask(server) + server.process.answer = answer + seen = await _turn(_worker(server, approve)) + assert asked == [("toolu_1", "bash", {"command": "echo hi"})] + reply = server.sent("extension_ui_response")[0] + assert reply["id"] == "ui-1" + assert json.loads(reply["value"]) == ( + {"decision": "allow"} + if granted + else {"decision": "deny", "reason": "not that"} + ) + assert isinstance(seen[-1], events.StreamEnd) + + +async def test_another_extensions_dialog_is_dismissed() -> None: + """Nobody is at a terminal to answer it; the agent must not wait.""" + server = Pi() + worker = _worker(server) + assert worker._agent is not None + await worker._on_dialog( + worker._agent, {"id": "x", "method": "confirm", "title": "Clear?"} + ) + await worker._on_dialog( + worker._agent, {"id": "y", "method": "notify", "message": "hello"} + ) + assert server.sent("extension_ui_response") == [ + {"type": "extension_ui_response", "id": "x", "cancelled": True} + ] + + +async def test_an_interrupted_turn_ends_as_cancelled() -> None: + server = Pi([]) + worker = _worker(server) + turn = worker._cli_turn([m.TextPart(text="go")]) + assert isinstance(await anext(turn), events.StreamStart) + reader = asyncio.ensure_future(_rest(turn)) + await worker._cli_interrupt() + seen = await asyncio.wait_for(reader, 5) + assert seen[-1].finish_reason == "cancelled" + + +async def _rest(turn: Any) -> list[Any]: + return [e async for e in turn] + + +async def test_a_dead_pi_crashes_the_turn() -> None: + server = Pi([]) + server.on_prompt = lambda: server.process._lines.put_nowait("") + with pytest.raises(workers.WorkerError, match="crashed"): + await _turn(_worker(server)) + + +@pytest.mark.parametrize("still_streaming", [True, False]) +async def test_a_run_an_extension_command_starts_is_followed( + still_streaming: bool, +) -> None: + """Measured: `/ask` answered `handled`, and the run the command started + followed, with pi already streaming. Its text was never streamed.""" + server = Pi( + [ + {"type": "agent_start"}, + {"type": "message_start", "message": {"role": "assistant"}}, + { + "type": "message_end", + "message": _assistant({"type": "text", "text": "PONG"}), + }, + {"type": "agent_settled", "aborted": False}, + ] + ) + + def answer(message: dict[str, Any]) -> None: + if message.get("type") == "prompt": + server.respond( + message, success=True, data={"disposition": "handled"} + ) + for record in server.turn: + server.says(record) + elif message.get("type") == "get_state": + server.respond( + message, success=True, data={"isStreaming": still_streaming} + ) + else: + Pi.answer(server, message) + + server.process.answer = answer + seen = await _turn(_worker(server), m.TextPart(text="/ask PONG")) + assert [e.chunk for e in seen if isinstance(e, events.TextDelta)] == [ + "PONG" + ] + + +async def test_a_command_that_starts_nothing_ends_the_turn_empty() -> None: + server = Pi() + + def answer(message: dict[str, Any]) -> None: + if message.get("type") == "prompt": + server.respond( + message, success=True, data={"disposition": "handled"} + ) + elif message.get("type") == "get_state": + server.respond(message, success=True, data={"isStreaming": False}) + else: + Pi.answer(server, message) + + server.process.answer = answer + seen = await _turn(_worker(server), m.TextPart(text="/noop")) + assert [type(e).__name__ for e in seen] == ["StreamStart", "StreamEnd"] + + +def test_history_follows_the_active_branch_only() -> None: + lines = [ + {"type": "session", "id": "S", "cwd": "/w"}, + { + "type": "message", + "id": "a", + "parentId": None, + "message": {"role": "user", "content": "first"}, + }, + { + "type": "message", + "id": "b", + "parentId": "a", + "message": _assistant({"type": "text", "text": "abandoned"}), + }, + { + "type": "message", + "id": "c", + "parentId": "a", + "message": _assistant(CALL, stop="toolUse"), + }, + { + "type": "message", + "id": "d", + "parentId": "c", + "message": { + "role": "toolResult", + "toolCallId": "toolu_1", + "toolName": "bash", + "content": [{"type": "text", "text": "hi"}], + "isError": True, + }, + }, + {"type": "label", "id": "e", "parentId": "d"}, + ] + text = "\n".join(json.dumps(line) for line in lines) + stored = worker_._read(worker_._active_branch(text)) + assert [msg.role for msg in stored] == ["user", "assistant"] + call, result = stored[1].parts # the result joins its call + assert isinstance(call, m.BuiltinToolCallPart) + assert isinstance(result, m.BuiltinToolReturnPart) + assert (result.result, result.is_error) == ("hi", True) + + +async def test_a_seed_is_listed_and_read_back(tmp_path: Path) -> None: + """The store, for real: write where pi looks, find it there.""" + agent_dir = tmp_path / "agent" + project = tmp_path / "project" + project.mkdir() + worker = _worker(cwd=str(project), PI_CODING_AGENT_DIR=str(agent_dir)) + seed = [ + m.Message(role="user", parts=[m.TextPart(text="the word is HERON")]), + m.Message( + role="assistant", + parts=[ + m.ReasoningPart(text="hmm"), + m.TextPart(text="Reading."), + m.BuiltinToolCallPart( + tool_call_id="c1", + tool_name="read", + tool_args='{"path": "a.txt"}', + ), + m.BuiltinToolReturnPart( + tool_call_id="c1", tool_name="read", result="milk" + ), + ], + ), + m.Message(role="assistant", parts=[m.TextPart(text="It says milk.")]), + ] + with pytest.warns(UserWarning, match="reasoning"): + session_id = await worker._stage(seed) + infos = await worker._cli_list_sessions() + assert [i.session_id for i in infos] == [session_id] + assert infos[0].title == "the word is HERON" + files = list(agent_dir.glob("sessions/*/*.jsonl")) + assert len(files) == 1 + assert files[0].parent.name.startswith("--") + assert files[0].name.endswith(f"_{session_id}.jsonl") + back = await worker._cli_history(session_id) + assert [msg.role for msg in back] == ["user", "assistant", "assistant"] + text, call, result = back[1].parts # the reasoning was not carried + assert isinstance(text, m.TextPart) + assert isinstance(call, m.BuiltinToolCallPart) + assert json.loads(call.tool_args) == {"path": "a.txt"} + assert isinstance(result, m.BuiltinToolReturnPart) + assert result.result == "milk" + assert back[2].text == "It says milk." + with pytest.raises(workers.WorkerError): + await worker._cli_history("not-a-session") + + +async def test_a_seeded_pi_conversation_stays_on_its_model( + tmp_path: Path, +) -> None: + """Measured: a seeded pi conversation ran on pi's default model, not the + one it was on. History says which model wrote each reply, and seeding + writes it back the way pi records a switch.""" + agent_dir = tmp_path / "agent" + project = tmp_path / "project" + project.mkdir() + worker = _worker(cwd=str(project), PI_CODING_AGENT_DIR=str(agent_dir)) + stored = { + "type": "message", + "message": { + **_assistant({"type": "text", "text": "hi"}), + "api": "anthropic-messages", + "provider": "vercel-ai-gateway", + "model": "anthropic/claude-haiku-4.5", + "thinkingLevel": "high", + }, + } + seed = [ + m.Message(role="user", parts=[m.TextPart(text="hello")]), + *worker_._stored_to_messages(stored), + ] + session_id = await worker._stage(seed) + (written,) = agent_dir.glob(f"sessions/*/*_{session_id}.jsonl") + entries = [json.loads(line) for line in written.read_text().splitlines()] + assert [e["type"] for e in entries] == [ + "session", + "model_change", + "thinking_level_change", + "message", + "message", + ] + assert (entries[1]["provider"], entries[1]["modelId"]) == ( + "vercel-ai-gateway", + "anthropic/claude-haiku-4.5", + ) + # A chain, root first: pi reads it as one branch. + assert [e.get("parentId") for e in entries[1:]] == [ + None, + *[e["id"] for e in entries[1:-1]], + ] + + +def test_options_reach_pi_in_its_own_spelling() -> None: + worker = worker_.Pi( + cwd="/w", + env={"K": "v"}, + executable="pi", + model_name="anthropic/claude-sonnet-4.6", + effort="high", + mcp_servers={ + "ai_sdk": {"type": "http", "url": "http://127.0.0.1:1/mcp"}, + "docs": {"command": "docs-mcp", "ignored": True}, + }, + approve=False, + allowed_tools=[], + disallowed_tools=["bash"], + ) + argv, env, minted = worker._cli_tui_command(None) + assert argv[:3] == ["pi", "--session-id", minted] + assert argv[3:5] == ["-e", worker_.EXTENSION] + assert argv[argv.index("--model") + 1] == "anthropic/claude-sonnet-4.6" + assert argv[argv.index("--thinking") + 1] == "high" + assert "--no-tools" in argv + assert argv[argv.index("--exclude-tools") + 1] == "bash" + assert env["K"] == "v" + # The person at the TUI is the gate; the bridge is not there. + assert json.loads(env[worker_.CONFIG_VAR]) == { + "approve": False, + "mcp": {"docs": {"command": "docs-mcp"}}, + } + # The base's public TUI method must work without open()/a running process. + public_argv, public_env = worker.tui_command() + assert public_argv[0] == "pi" + assert public_env == env + assert worker._agent is None + + +async def test_stream_start_waits_for_prompt_acceptance() -> None: + server = Pi([]) + submitted = asyncio.Event() + + def answer(message: dict[str, Any]) -> None: + if message.get("type") == "prompt": + submitted.set() + else: + Pi.answer(server, message) + + server.process.answer = answer + worker = _worker(server) + turn = worker._cli_turn([m.TextPart(text="go")]) + first = asyncio.create_task(anext(turn)) + try: + await asyncio.wait_for(submitted.wait(), 5) + assert not first.done() + server.respond( + server.sent("prompt")[0], + success=True, + data={"disposition": "started"}, + ) + assert isinstance(await asyncio.wait_for(first, 5), events.StreamStart) + finally: + await turn.aclose() + await worker._cli_close() + + +async def test_running_input_keeps_images_and_text_files() -> None: + server = Pi([]) + worker = _worker(server) + turn = worker._cli_turn([m.TextPart(text="go")]) + assert isinstance(await anext(turn), events.StreamStart) + + def answer(message: dict[str, Any]) -> None: + if message.get("streamingBehavior") == "steer": + server.respond( + message, success=True, data={"disposition": "queued"} + ) + else: + Pi.answer(server, message) + + server.process.answer = answer + try: + assert await worker._cli_send_running( + [ + m.TextPart(text="look"), + m.FilePart(data=b"notes", media_type="text/plain"), + m.FilePart(data=b"\x89PNG", media_type="image/png"), + ] + ) + command = server.sent("prompt")[1] + assert "look" in command["message"] + assert "notes" in command["message"] + assert command["images"] == [ + {"type": "image", "data": "iVBORw==", "mimeType": "image/png"} + ] + assert not server.sent("steer") + assert not server.sent("clear_queue") + finally: + await turn.aclose() + await worker._cli_close() + + +async def test_confirmed_idle_does_not_submit_running_input() -> None: + server = Pi([]) + worker = _worker(server) + turn = worker._cli_turn([m.TextPart(text="go")]) + assert isinstance(await anext(turn), events.StreamStart) + # Completion has arrived, but the old generator has not consumed it. + server.says({"type": "agent_settled", "aborted": False}) + try: + assert worker._running + assert not await worker._cli_send_running([m.TextPart(text="next")]) + assert len(server.sent("prompt")) == 1 + assert isinstance((await _rest(turn))[-1], events.StreamEnd) + finally: + await turn.aclose() + await worker._cli_close() + + +@pytest.mark.parametrize("completion_before_ack", [True, False]) +@pytest.mark.parametrize("disposition", ["started", "handled"]) +async def test_turn_end_race_keeps_the_accepted_new_runs_events( + completion_before_ack: bool, + disposition: str, +) -> None: + server = Pi([]) + worker = _worker(server) + turn = worker._cli_turn([m.TextPart(text="go")]) + assert isinstance(await anext(turn), events.StreamStart) + submitted = asyncio.Event() + + def answer(message: dict[str, Any]) -> None: + if message.get("streamingBehavior") == "steer": + # get_state said streaming, but the run ended before acceptance. + server.says({"type": "agent_settled", "aborted": False}) + submitted.set() + else: + Pi.answer(server, message) + + server.process.answer = answer + reader = asyncio.create_task(_rest(turn)) + send = asyncio.create_task( + worker._cli_send_running([m.TextPart(text="next")]) + ) + try: + await asyncio.wait_for(submitted.wait(), 5) + assert not reader.done() + assert not send.done() + server.says(TOOL_TURN[0]) # The accepted input starts a new run. + if completion_before_ack: + for record in TOOL_TURN[1:]: + server.says(record) + server.respond( + server.sent("prompt")[1], + success=True, + data={"disposition": disposition}, + ) + assert await asyncio.wait_for(send, 5) + if not completion_before_ack: + assert not reader.done() + for record in TOOL_TURN[1:]: + server.says(record) + seen = await asyncio.wait_for(reader, 5) + assert [e.chunk for e in seen if isinstance(e, events.TextDelta)] == [ + "done" + ] + assert sum(isinstance(e, events.StreamEnd) for e in seen) == 1 + assert not worker._running + assert worker._continued_runs == 0 + assert len(server.sent("prompt")) == 2 + finally: + send.cancel() + reader.cancel() + await asyncio.gather(send, reader, return_exceptions=True) + await turn.aclose() + await worker._cli_close() + + +@pytest.mark.parametrize("disposition", [None, "unexpected"]) +async def test_ambiguous_acceptance_is_not_retried(disposition: Any) -> None: + server = Pi([]) + worker = _worker(server) + turn = worker._cli_turn([m.TextPart(text="go")]) + assert isinstance(await anext(turn), events.StreamStart) + + def answer(message: dict[str, Any]) -> None: + if message.get("streamingBehavior") == "steer": + server.respond( + message, success=True, data={"disposition": disposition} + ) + else: + Pi.answer(server, message) + + server.process.answer = answer + try: + with pytest.raises(workers.WorkerError, match="unknown prompt"): + await worker._cli_send_running([m.TextPart(text="next")]) + assert len(server.sent("prompt")) == 2 + finally: + await turn.aclose() + await worker._cli_close() + + +async def test_rejected_running_input_is_not_reported_as_idle() -> None: + server = Pi([]) + worker = _worker(server) + turn = worker._cli_turn([m.TextPart(text="go")]) + assert isinstance(await anext(turn), events.StreamStart) + server.prompt_error = ( + "Cannot submit a prompt while compaction is in progress" + ) + try: + with pytest.raises(workers.WorkerError, match="compaction"): + await worker._cli_send_running([m.TextPart(text="next")]) + assert len(server.sent("prompt")) == 2 + finally: + await turn.aclose() + await worker._cli_close() + + +@pytest.mark.parametrize("failure", ["timeout", "crash"]) +async def test_uncertain_running_input_is_never_retried( + failure: str, + monkeypatch: pytest.MonkeyPatch, +) -> None: + server = Pi([]) + worker = _worker(server) + turn = worker._cli_turn([m.TextPart(text="go")]) + assert isinstance(await anext(turn), events.StreamStart) + assert worker._agent is not None + call = worker._agent.call + + async def short_call(command: dict[str, Any], **kwargs: Any) -> Any: + return await call(command, timeout=0.01) + + def answer(message: dict[str, Any]) -> None: + if message.get("streamingBehavior") == "steer": + if failure == "crash": + server.process._lines.put_nowait("") + # No response: input may already have been accepted. + else: + Pi.answer(server, message) + + server.process.answer = answer + monkeypatch.setattr(worker._agent, "call", short_call) + try: + error = TimeoutError if failure == "timeout" else workers.WorkerError + with pytest.raises(error): + await worker._cli_send_running([m.TextPart(text="next")]) + assert len(server.sent("prompt")) == 2 + finally: + await turn.aclose() + await worker._cli_close() + + +async def test_start_wires_approval_and_private_version( + monkeypatch: pytest.MonkeyPatch, +) -> None: + async def probe(*args: Any, **kwargs: Any) -> str: + return "pi test" + + from ai.workers import _adapter + + monkeypatch.setattr(_adapter, "probe", probe) + servers = {"docs": {"command": "docs-mcp"}} + worker = worker_.Pi(approve=True) + await worker._cli_start(servers) + assert worker._approval_callback == worker._approve + assert worker._cli_version == "pi test" + assert worker._mcp_servers == servers + assert worker._mcp_servers is not servers + dumped = worker.model_dump() + assert dumped["worker_class_id"] == "pi" + assert "model_name" in dumped + assert "kind" not in dumped + assert "model" not in dumped + assert not any(key.startswith("_") for key in dumped) + restored = worker_.Pi.model_validate(dumped) + assert restored._agent is None + assert restored._approval_callback is None + await worker._cli_close() + assert worker._approval_callback is None + worker.approve = False + await worker._cli_start({}) + assert worker._approval_callback is None + + +async def test_open_and_close_own_the_rpc_process( + monkeypatch: pytest.MonkeyPatch, +) -> None: + server = Pi() + started: list[Any] = [] + + async def spawn(argv: Any, **kwargs: Any) -> Any: + started.append((argv, kwargs)) + return server.process + + def answer(message: dict[str, Any]) -> None: + if message.get("type") == "get_state": + server.respond( + message, success=True, data={"sessionId": started[0][0][4]} + ) + else: + Pi.answer(server, message) + + server.process.answer = answer + monkeypatch.setattr(worker_, "spawn", spawn) + worker = worker_.Pi(cwd="/w", model_name="test-model") + try: + session_id = await worker._cli_open( + session_id=None, fork=False, seed=None, instructions="be brief" + ) + argv, options = started[0] + assert argv[:5] == ["pi", "--mode", "rpc", "--session-id", session_id] + assert argv[argv.index("--append-system-prompt") + 1] == "be brief" + assert options["cwd"] == "/w" + assert worker._agent is not None + finally: + await worker._cli_close() + assert worker._agent is None + assert await asyncio.wait_for(server.process.readline(), 5) == "" diff --git a/tests/workers/_adapters/test_handoff.py b/tests/workers/test_handoff.py similarity index 70% rename from tests/workers/_adapters/test_handoff.py rename to tests/workers/test_handoff.py index 4f55dadd..8746525d 100644 --- a/tests/workers/_adapters/test_handoff.py +++ b/tests/workers/test_handoff.py @@ -3,7 +3,9 @@ Text verbatim; tool calls as native items with the ORIGINAL name and arguments; tool results as strings bound to their call; reasoning as a user-role note after the turn it belonged to (codex), or not at all -(claude, pi). The CLI's own tools arrive as built-in parts. +(claude, pi). A worker holds a tool an `ai.Agent` ran as a call and a +`tool` message, and a tool the CLI ran as built-in parts in one message: +each renderer takes both, and both seed the same. """ from __future__ import annotations @@ -19,9 +21,13 @@ ToolCallPart, ToolResultPart, ) -from ai.workers._adapters import _handoff +from ai.workers import _handoff +from ai.workers.claude_code import handoff as claude_handoff +from ai.workers.codex import handoff as codex_handoff +from ai.workers.pi import handoff as pi_handoff -HISTORY = [ +# Write as a tool an `ai.Agent` ran: its result in a `tool` message. +AGENT_TOOL = [ Message(role="user", parts=[TextPart(text="Create recipe.txt")]), Message( role="assistant", @@ -51,9 +57,9 @@ Message(role="assistant", parts=[TextPart(text="Done.")]), ] -# The same conversation, the way a worker holds it. -MODEL_VIEW = [ - HISTORY[0], +# The same conversation, Write as a tool the CLI ran: built-in parts. +CLI_TOOL = [ + AGENT_TOOL[0], Message( role="assistant", parts=[ @@ -71,12 +77,12 @@ ), ], ), - HISTORY[3], + AGENT_TOOL[3], ] def test_codex_items_follow_the_rule() -> None: - items = _handoff.to_codex_items(HISTORY) + items = codex_handoff.to_codex_items(AGENT_TOOL) kinds = [(i["type"], i.get("role")) for i in items] assert kinds == [ ("message", "user"), @@ -94,18 +100,28 @@ def test_codex_items_follow_the_rule() -> None: assert out["call_id"] == "call_1" assert out["output"] == json.dumps({"ok": True}) note = items[3]["content"][0]["text"] - assert note.startswith(_handoff.NOTE_PREFIX) + assert note.startswith(codex_handoff.NOTE_PREFIX) assert "Write is the tool" in note -def test_the_model_view_seeds_the_same_items() -> None: - assert _handoff.to_codex_items(MODEL_VIEW) == _handoff.to_codex_items( - HISTORY +def test_both_shapes_seed_the_same() -> None: + assert codex_handoff.to_codex_items(CLI_TOOL) == ( + codex_handoff.to_codex_items(AGENT_TOOL) ) + assert pi_handoff.to_pi_messages(CLI_TOOL, timestamp=1) == ( + pi_handoff.to_pi_messages(AGENT_TOOL, timestamp=1) + ) + assert [ + (r["type"], r["message"]) + for r in claude_handoff.to_claude_records(CLI_TOOL, "s", "/w") + ] == [ + (r["type"], r["message"]) + for r in claude_handoff.to_claude_records(AGENT_TOOL, "s", "/w") + ] def test_claude_records_follow_the_rule() -> None: - recs = _handoff.to_claude_records(MODEL_VIEW, "sid-1", "/w") + recs = claude_handoff.to_claude_records(CLI_TOOL, "sid-1", "/w") # user prompt, assistant (text + tool_use), tool result, assistant; NO # reasoning note: Claude's safeguards refuse replayed reasoning. assert [r["type"] for r in recs] == [ @@ -122,7 +138,7 @@ def test_claude_records_follow_the_rule() -> None: result = recs[2]["message"]["content"][0] assert result["type"] == "tool_result" assert result["tool_use_id"] == "call_1" - assert _handoff.reasoning_count(MODEL_VIEW) == 1 # what is warned about + assert _handoff.reasoning_count(CLI_TOOL) == 1 # what is warned about # a real chain, in the CLI's own store shape assert recs[0]["parentUuid"] is None assert all( @@ -133,7 +149,7 @@ def test_claude_records_follow_the_rule() -> None: def test_pi_merges_assistant_messages_and_keeps_tool_results() -> None: - rendered = _handoff.to_pi_messages( + rendered = pi_handoff.to_pi_messages( [ Message(role="user", parts=[TextPart(text="hi")]), Message(role="assistant", parts=[TextPart(text="one")]), @@ -161,19 +177,9 @@ def test_pi_merges_assistant_messages_and_keeps_tool_results() -> None: assert rendered[2]["isError"] is True -def test_model_view_and_harness_view_are_inverse() -> None: - model = _handoff.model_view(HISTORY) - assert [m.role for m in model] == ["user", "assistant", "assistant"] - parts = model[1].parts - assert isinstance(parts[2], BuiltinToolCallPart) - assert isinstance(parts[3], BuiltinToolReturnPart) - assert parts[3].result == {"ok": True} - back = _handoff.harness_view(model) - assert [m.role for m in back] == ["user", "assistant", "tool", "assistant"] - assert isinstance(back[2].parts[0], ToolResultPart) - - def test_text_after_a_cli_tool_stays_after_its_result() -> None: + """Claude and pi keep a result in a message of its own: the message + with the call ends there, and what follows comes after the result.""" one = Message( role="assistant", parts=[ @@ -184,43 +190,35 @@ def test_text_after_a_cli_tool_stays_after_its_result() -> None: TextPart(text="It says x."), ], ) - first, result, after = _handoff.harness_view([one]) - assert (first.role, result.role, after.role) == ( + recs = claude_handoff.to_claude_records([one], "s", "/w") + assert [r["type"] for r in recs] == ["assistant", "user", "assistant"] + assert recs[1]["message"]["content"][0]["type"] == "tool_result" + assert recs[2]["message"]["content"] == [ + {"type": "text", "text": "It says x."} + ] + rendered = pi_handoff.to_pi_messages([one], timestamp=1) + assert [r["role"] for r in rendered] == [ "assistant", - "tool", + "toolResult", "assistant", - ) - assert first.id == one.id and after.id != one.id - assert after.text == "It says x." - - -def test_a_stored_result_without_a_name_takes_its_calls() -> None: - stored = [ - Message( - role="assistant", - parts=[ - ToolCallPart(tool_call_id="c", tool_name="Read", tool_args="") - ], - ), - Message( - role="tool", - parts=[ToolResultPart(tool_call_id="c", tool_name="", result="x")], - ), ] - (message,) = _handoff.model_view(stored) - result = message.parts[1] - assert isinstance(result, BuiltinToolReturnPart) - assert result.tool_name == "Read" + assert rendered[2]["content"] == [{"type": "text", "text": "It says x."}] + items = codex_handoff.to_codex_items([one]) + assert [i["type"] for i in items] == [ + "function_call", + "function_call_output", + "message", + ] def test_reasoning_is_never_the_agents_own_thought() -> None: """No thinking block, no reasoning item: both were measured to fail, one rejected, one silently ignored. It travels as a note, or not at all.""" - items = _handoff.to_codex_items(HISTORY) + items = codex_handoff.to_codex_items(AGENT_TOOL) assert not any(i["type"] == "reasoning" for i in items) blocks = [ b - for r in _handoff.to_claude_records(HISTORY, "s", "/w") + for r in claude_handoff.to_claude_records(AGENT_TOOL, "s", "/w") if isinstance(r["message"]["content"], list) for b in r["message"]["content"] ] @@ -229,6 +227,6 @@ def test_reasoning_is_never_the_agents_own_thought() -> None: def test_empty_parts_produce_nothing() -> None: blank = [Message(role="assistant", parts=[TextPart(text=" ")])] - assert _handoff.to_codex_items(blank) == [] + assert codex_handoff.to_codex_items(blank) == [] empty = [Message(role="assistant", parts=[ReasoningPart(text="")])] - assert _handoff.to_claude_records(empty, "s", "/w") == [] + assert claude_handoff.to_claude_records(empty, "s", "/w") == [] diff --git a/tests/workers/test_live.py b/tests/workers/test_live.py new file mode 100644 index 00000000..61a8f752 --- /dev/null +++ b/tests/workers/test_live.py @@ -0,0 +1,216 @@ +"""Workers against real CLIs; opt-in and never part of offline verification. + +Run explicitly: `uv run --frozen pytest -m live tests/workers/test_live.py`. +Each test runs once per CLI installed here, in a fresh directory, with the +CLI's own login. They require user credentials and cost tokens. +""" + +from __future__ import annotations + +import contextlib +import importlib.util +import shutil +from collections.abc import Callable +from pathlib import Path +from typing import Any + +import pytest + +import ai +from ai import workers +from ai.types import events + +pytestmark = pytest.mark.live + +WORKER_CLASSES: dict[str, tuple[str, Callable[..., workers.Worker]]] = { + "claude-code": ("claude", workers.ClaudeCode), + "codex": ("codex", workers.Codex), + "pi": ("pi", workers.Pi), +} + + +@pytest.fixture(params=list(WORKER_CLASSES)) +def worker_class_id(request: pytest.FixtureRequest) -> str: + worker_class_id = str(request.param) + executable, _ = WORKER_CLASSES[worker_class_id] + if shutil.which(executable) is None: + pytest.skip(f"{executable} is not installed") + if worker_class_id == "claude-code" and not importlib.util.find_spec( + "claude_agent_sdk" + ): + pytest.skip("claude-agent-sdk is not installed") + return worker_class_id + + +@pytest.fixture +def make(worker_class_id: str, tmp_path: Path) -> Callable[..., workers.Worker]: + """Build this worker class in a fresh directory.""" + _, cls = WORKER_CLASSES[worker_class_id] + return lambda **fields: cls(cwd=str(tmp_path), **fields) + + +async def test_a_turn_and_a_resume(worker_class_id: str, make: Any) -> None: + # None selects the authenticated CLI's default model. + async with make(model_name=None) as worker: + first = await ai.experimental_generate( + worker, + [ai.user_message("Reply with the word PONG and nothing else.")], + ) + await worker.sync() + assert any( + "PONG" in m.text for m in worker.messages if m.role == "assistant" + ) + assert "PONG" in first.text + assert worker.session_id + saved = worker.model_dump() + assert saved["worker_class_id"] == worker_class_id + assert saved["model_name"] is None + assert not {"kind", "model", "fork"}.intersection(saved) + again = workers.Worker.model_validate_json(worker.model_dump_json()) + assert again.worker_class_id == worker_class_id + async with again: + # Read native storage again: its normalized messages/ids are the prefix + # to continue, not a pre-sync copy of the streamed mirror. + await again.sync() + second = await ai.experimental_generate( + again, + [ + *again.messages, + ai.user_message("Which word did you reply with? One word."), + ], + ) + assert "PONG" in second.text.upper() + assert again.session_id == worker.session_id + + +async def test_direct_events_and_sync(make: Any) -> None: + prompt = "Reply with the word PONG and nothing else." + seen: list[workers.SessionEvent] = [] + async with make() as worker: + await worker.send(prompt) + # The feed spans the session; break at the end of this answer and + # explicitly release its sole reader before sync(). + async with contextlib.aclosing(worker.events()) as feed: + async for event in feed: + seen.append(event) + if isinstance(event, events.StreamEnd): + break + accepted = [ + e for e in seen if isinstance(e, workers.UserMessageAccepted) + ] + assert [e.message.text for e in accepted] == [prompt] + assert any(isinstance(e, events.StreamStart) for e in seen) + assert isinstance(seen[-1], events.StreamEnd) + assert "PONG" in "".join( + e.chunk for e in seen if isinstance(e, events.TextDelta) + ) + session_id = worker.session_id + assert session_id + # A session-id-only worker has no mirror until it reads the CLI's store. + async with make(session_id=session_id) as again: + assert again.messages == [] + await again.sync() + assert any( + m.role == "user" and prompt in m.text for m in again.messages + ) + assert any( + m.role == "assistant" and "PONG" in m.text for m in again.messages + ) + + +async def test_a_native_fork_keeps_the_past(make: Any) -> None: + async with make() as worker: + await ai.experimental_generate( + worker, + [ai.user_message("Remember the word HERON. Reply with OK only.")], + ) + branch = await worker.fork() + async with branch: + assert branch.session_id and branch.session_id != worker.session_id + assert branch.worker_class_id == worker.worker_class_id + assert any("HERON" in message.text for message in branch.messages) + reply = await ai.experimental_generate( + branch, + [ + *branch.messages, + ai.user_message("Which word did I ask you to remember?"), + ], + ) + assert "HERON" in reply.text.upper() + assert branch.session_id != worker.session_id + + +async def test_agent_tools_reach_the_cli(make: Any) -> None: + @ai.tool + async def lookup_order(order_id: str) -> str: + """Look up the status of an order by its id.""" + return f"order {order_id}: shipped on 2026-11-02" + + prompt = ( + "Use the lookup_order tool for order A-17, then state its status in " + "one short sentence." + ) + async with make() as worker: + agent = ai.Agent(tools=[lookup_order]) + async with agent.run(worker, [ai.user_message(prompt)]) as run: + seen = [event async for event in run] + assert [m.role for m in run.messages] == [ + "user", + "assistant", + "tool", + "assistant", + ] + assert "2026" in run.messages[-1].text or "Nov" in run.messages[-1].text + hidden = [ + e + for e in seen + if isinstance(e, events.BuiltinToolStart) and "lookup" in e.tool_name + ] + assert hidden == [] # the CLI's own report of the bridge call + + +async def test_a_denied_tool_call_does_not_run( + worker_class_id: str, make: Any, tmp_path: Path +) -> None: + if worker_class_id == "codex": + pytest.skip("codex asks only when its own policy escalates") + pending: list[Any] = [] + prompt = "Create a file named notes.txt containing hello. Use a tool." + async with make(approve=True) as worker: + async with ai.Agent().run(worker, [ai.user_message(prompt)]) as run: + async for event in run: + if isinstance(event, events.PendingHookEvent): + pending.append(event.hook) + ai.resolve_hook( + event.hook, + {"granted": False, "reason": "not allowed here"}, + ) + assert pending + assert all(h.hook_type == "ToolApproval" for h in pending) + assert not (tmp_path / "notes.txt").exists() + + +async def test_direct_approval_outside_agent( + worker_class_id: str, make: Any, tmp_path: Path +) -> None: + if worker_class_id == "codex": + pytest.skip("codex asks only when its own policy escalates") + pending: list[Any] = [] + async with make(approve=True) as worker: + await worker.send( + "Create a file named notes.txt containing hello. Use a tool." + ) + async with contextlib.aclosing(worker.events()) as feed: + async for event in feed: + if isinstance(event, events.PendingHookEvent): + pending.append(event.hook) + ai.resolve_hook( + event.hook, + {"granted": False, "reason": "not allowed here"}, + registry=worker.hook_registry, + ) + elif isinstance(event, events.StreamEnd): + break + assert pending + assert all(h.hook_type == "ToolApproval" for h in pending) + assert not (tmp_path / "notes.txt").exists() diff --git a/tests/workers/test_output.py b/tests/workers/test_output.py new file mode 100644 index 00000000..94cd1de0 --- /dev/null +++ b/tests/workers/test_output.py @@ -0,0 +1,233 @@ +"""Structured model output is a serializable view of the native transcript.""" + +from __future__ import annotations + +import json +from collections.abc import Iterator + +import pydantic +import pytest + +import ai +from ai import workers +from ai.types import events +from ai.types import messages as m + +from . import fakes + + +class Count(pydantic.BaseModel): + n: int + + +@pytest.mark.parametrize("retries", [0, 1, 2]) +@pytest.mark.parametrize("restore", [False, True]) +@pytest.mark.parametrize("native_prefix", [False, True]) +async def test_output_continuation( + retries: int, restore: bool, native_prefix: bool +) -> None: + worker = fakes.FakeWorker() + fields = set(worker.model_dump()) + attempts = 0 + + def script(prompt: str) -> list[fakes.Step]: + nonlocal attempts + attempts += 1 + return fakes.text( + "not JSON" if attempts <= retries else '```json\n{"n": 2}\n```' + ) + + worker.script(script) + first = ai.user_message("count") + async with worker: + async with ai.stream(worker, [first], output_type=Count) as stream: + seen = [event async for event in stream] + assert stream.output == Count(n=2) + assert len(worker.fake.turns) == retries + 1 + native = worker.messages[1] + assert native.id == stream.message.id + assert native is not stream.message + assert native.text == ( + "not JSON" if retries else '```json\n{"n": 2}\n```' + ) + assert native.parts[0].id == "t" + assert stream.message.parts[0].id == "output" + assert {event.message.id for event in seen} == {native.id} + assert len(worker.messages) == 2 + 2 * retries + assert stream.usage is not None + assert stream.usage.input_tokens == 3 * (retries + 1) + assert native.usage is not None and native.usage.input_tokens == 3 + for hidden in worker.messages[2:]: + assert hidden.provider_metadata is not None + assert hidden.provider_metadata["worker"]["model_hidden"] is True + before = worker.model_dump_json() + + if restore: + data = json.loads(before) + assert set(data) == fields + restored = workers.Worker.model_validate(data) + assert isinstance(restored, fakes.FakeWorker) + worker = restored + worker.script(lambda prompt: fakes.text('{"n": 3}')) + # Round-trip the caller's transcript independently, too. + history = ( + list(worker.messages) + if native_prefix + else [ + first, + m.Message.model_validate_json(stream.message.model_dump_json()), + ] + ) + second = ai.user_message("count again") + plan = worker._plan([*history, second]) + assert plan.transcript == [second] + assert plan.prompt == second.parts + async with worker: + async with ai.stream( + worker, [*history, second], output_type=Count + ) as continuation: + _ = [event async for event in continuation] + assert continuation.output == Count(n=3) + assert len(worker.fake.turns) == 1 + assert worker.fake.turns[0].startswith("count again") + assert ( + worker.messages[:-2] + == fakes.FakeWorker.model_validate_json(before).messages + ) + + +async def test_projection_keeps_builtin_parts_and_suppresses_narration() -> ( + None +): + worker = fakes.FakeWorker() + worker.script( + lambda prompt: [ + *fakes.text("Let me look."), + *fakes.tool("read", "Read", '{"path":"a.py"}', "contents"), + *fakes.text('{"n": 2}', block="answer"), + ] + ) + first = ai.user_message("count") + async with worker: + seen = [ + event async for event in worker.stream([first], output_type=Count) + ] + native = worker.messages[1] + projected = seen[-1].message + assert projected is not native + assert {event.message.id for event in seen} == {native.id} + assert all(event.message is projected for event in seen) + assert projected.text == '{"n":2}' + assert native.text == 'Let me look.{"n": 2}' + assert [part.kind for part in projected.parts] == [ + "builtin_tool_call", + "builtin_tool_return", + "text", + ] + assert projected.builtin_tool_calls == native.builtin_tool_calls + assert projected.builtin_tool_returns == native.builtin_tool_returns + metadata = native.provider_metadata + assert metadata is not None + assert ( + metadata["worker"]["model_parts"] + == projected.model_dump(mode="json")["parts"] + ) + next_message = ai.user_message("again") + assert worker._plan([first, projected, next_message]).transcript == [ + next_message + ] + + +@pytest.mark.parametrize("native_prefix", [False, True]) +@pytest.mark.parametrize("change", ["id", "role", "text", "part_id", "omit"]) +async def test_changed_output_history_is_rejected( + native_prefix: bool, change: str +) -> None: + worker = fakes.FakeWorker() + worker.script(lambda prompt: fakes.text('{"n": 2}')) + first = ai.user_message("count") + async with worker: + async with ai.stream(worker, [first], output_type=Count) as stream: + _ = [event async for event in stream] + history = [ + message.model_copy(deep=True) + for message in ( + worker.messages if native_prefix else [first, stream.message] + ) + ] + answer = history[-1] + if change == "id": + answer.id = "changed" + elif change == "role": + answer.role = "user" + elif change == "text": + assert isinstance(answer.parts[0], m.TextPart) + answer.parts[0].text = '{"n":999}' + elif change == "part_id": + assert isinstance(answer.parts[0], m.TextPart) + answer.parts[0].id = "changed" + else: + history.pop() + with pytest.raises(workers.TranscriptMismatchError): + async with ai.stream( + worker, [*history, ai.user_message("again")] + ) as continuation: + _ = [event async for event in continuation] + assert len(worker.fake.turns) == 1 + + +async def test_agent_output_tool_loop_with_narration() -> None: + worker = fakes.FakeWorker() + ran: list[int] = [] + answers: list[tuple[str, bool]] = [] + + @ai.tool + async def count(n: int) -> int: + """Return the count.""" + ran.append(n) + return n + + async def call() -> None: + answers.append(await worker._on_call("count", {"n": 2})) + + def script(prompt: str) -> Iterator[fakes.Step]: + yield from fakes.text("I will count with a tool.") + yield from fakes.tool("read", "Read") + yield fakes.Run(call) + yield from fakes.text('{"n": 2}') + + worker.script(script) + async with worker: + async with ai.Agent(tools=[count]).run( + worker, [ai.user_message("count")], output_type=Count + ) as run: + seen = [event async for event in run] + assert run.output == Count(n=2) + assert ran == [2] + assert answers == [("2", False)] + assert len(worker.fake.turns) == 1 + assert [message.role for message in run.messages] == [ + "user", + "assistant", + "tool", + "assistant", + ] + tool_message = run.messages[1] + assert tool_message.text == "" + assert [part.kind for part in tool_message.parts] == [ + "builtin_tool_call", + "builtin_tool_return", + "tool_call", + ] + assert worker.messages[1].text == "I will count with a tool." + assert worker.messages[1].id == tool_message.id + assert not any( + isinstance(event, events.TextDelta) and "I will" in event.chunk + for event in seen + ) + worker.script(lambda prompt: fakes.text('{"n": 3}')) + async with ai.stream( + worker, [*run.messages, ai.user_message("again")], output_type=Count + ) as continuation: + _ = [event async for event in continuation] + assert continuation.output == Count(n=3) diff --git a/tests/workers/test_session_sync.py b/tests/workers/test_session_sync.py new file mode 100644 index 00000000..4e8b9e00 --- /dev/null +++ b/tests/workers/test_session_sync.py @@ -0,0 +1,49 @@ +"""Switching from direct input to model use must not replay queued output.""" + +import contextlib + +import pytest + +import ai +from ai import workers +from ai.types import events + +from . import fakes + + +async def test_model_use_refuses_unread_direct_output() -> None: + async with fakes.FakeWorker() as worker: + await worker.send("one") + with pytest.raises(workers.WorkerError, match="unread session events"): + await ai.experimental_generate(worker, [ai.user_message("two")]) + assert worker.fake.turns == ["one"] + async with contextlib.aclosing(worker.events()) as feed: + async for event in feed: + if isinstance(event, events.StreamEnd): + break + answer = await ai.experimental_generate( + worker, [*worker.messages, ai.user_message("two")] + ) + assert answer.text == "two" + + +async def test_sync_replaces_unread_output_with_native_history() -> None: + async with fakes.FakeWorker() as worker: + await worker.send("one") + assert worker._runtime is not None + assert worker._runtime.pump is not None + await worker._runtime.pump + stored = [ai.user_message("one"), ai.assistant_message("native one")] + worker.fake.stored["s1"] = stored + await worker.sync() + assert worker.messages == stored + answer = await ai.experimental_generate( + worker, [*worker.messages, ai.user_message("two")] + ) + assert answer.text == "two" + assert [message.text for message in worker.messages] == [ + "one", + "native one", + "two", + "two", + ] diff --git a/tests/workers/test_worker.py b/tests/workers/test_worker.py index 299cf600..70409e71 100644 --- a/tests/workers/test_worker.py +++ b/tests/workers/test_worker.py @@ -3,8 +3,9 @@ from __future__ import annotations import asyncio +import contextlib import json -from collections.abc import Iterator +from collections.abc import AsyncIterator, Iterator from typing import Any import pydantic @@ -14,7 +15,7 @@ from ai import workers from ai.types import events from ai.types import messages as m -from ai.workers import _bridge +from ai.workers import _adapter, _bridge from . import fakes @@ -111,7 +112,7 @@ async def test_a_cancelled_turn_ends_as_other(worker: fakes.FakeWorker) -> None: async for event in stream: seen.append(event) if isinstance(event, events.TextEnd): - await worker.fake.interrupt() + await worker.interrupt() end = seen[-1] assert isinstance(end, events.StreamEnd) assert end.finish_reason == "other" @@ -180,21 +181,59 @@ async def test_a_rewritten_past_is_refused(worker: fakes.FakeWorker) -> None: await ai.experimental_generate(worker, [ai.user_message("other")]) -async def test_a_failed_call_can_be_sent_again( +async def test_failure_after_acceptance_keeps_the_accepted_user( worker: fakes.FakeWorker, ) -> None: def boom(prompt: str) -> list[fakes.Step]: raise RuntimeError("boom") worker.script(boom) - messages = [ai.user_message("one")] + message = ai.user_message("one") async with worker: with pytest.raises(RuntimeError, match="boom"): - await ai.experimental_generate(worker, messages) - assert worker.messages == [] + await ai.experimental_generate(worker, [message]) + assert worker.messages[0] == message + assert [x.role for x in worker.messages] == ["user", "assistant"] + assert worker.messages[1].parts == [] worker.script(fakes.reply) - again = await ai.experimental_generate(worker, messages) + with pytest.raises(ValueError, match="no new user message"): + await ai.experimental_generate(worker, list(worker.messages)) + again = await ai.experimental_generate( + worker, [*worker.messages, ai.user_message("two")] + ) + assert worker.fake.turns == ["one", "two"] + assert again.text == "two" + assert sum(x.id == message.id for x in worker.messages) == 1 + + +async def test_failure_before_acceptance_can_be_retried( + worker: fakes.FakeWorker, monkeypatch: pytest.MonkeyPatch +) -> None: + turn = fakes.FakeAdapter.turn + reject = True + + async def sometimes_reject( + adapter: fakes.FakeAdapter, prompt: _adapter.Prompt + ) -> AsyncIterator[events.Event]: + if reject: + raise RuntimeError("not accepted") + async for event in turn(adapter, prompt): + yield event + + monkeypatch.setattr(fakes.FakeAdapter, "turn", sometimes_reject) + message = ai.user_message("one") + async with worker: + with pytest.raises(RuntimeError, match="not accepted"): + await ai.experimental_generate(worker, [message]) + assert worker.messages == [] + assert worker._runtime is not None + assert worker._runtime.stream_owner is None + assert worker._runtime.submission is None + reject = False + again = await ai.experimental_generate(worker, [message]) + assert worker.fake.turns == ["one"] assert again.text == "one" + assert worker.messages[0] == message async def test_walking_away_interrupts_the_turn( @@ -269,9 +308,24 @@ async def test_a_dumped_worker_continues_its_conversation( assert again.fake.turns == ["two"] -async def test_an_unknown_kind_is_refused() -> None: - with pytest.raises(pydantic.ValidationError): - workers.Worker.model_validate({"kind": "nope"}) +async def test_an_unknown_worker_class_is_refused() -> None: + with pytest.raises(pydantic.ValidationError, match="unknown worker class"): + workers.Worker.model_validate({"worker_class_id": "nope"}) + + +def test_worker_identity_and_removed_fields() -> None: + worker = fakes.FakeWorker(model_name="test-model") + assert worker.id == "test-model" + assert worker.worker_class_id == worker.provider_name == "fake" + assert worker.version is None + data = worker.model_dump() + assert data["model_name"] == "test-model" + assert data["worker_class_id"] == "fake" + assert "fork" not in data + assert callable(worker.fork) + for field, value in (("kind", "fake"), ("model", "old"), ("fork", True)): + with pytest.raises(pydantic.ValidationError, match="Extra inputs"): + fakes.FakeWorker.model_validate({field: value}) async def test_resume_by_session_id() -> None: @@ -285,7 +339,7 @@ async def test_resume_by_session_id() -> None: assert worker.session_id == "old" -async def test_load_reads_the_stored_past() -> None: +async def test_sync_reads_the_stored_past() -> None: worker = fakes.FakeWorker(session_id="old") stored = [ ai.user_message("earlier"), @@ -293,33 +347,44 @@ async def test_load_reads_the_stored_past() -> None: ] async with worker: worker.fake.stored["old"] = stored - await worker.load() + await worker.sync() assert worker.messages == stored + assert worker.messages is not stored + assert worker.messages[0] is not stored[0] await ai.experimental_generate( worker, [*worker.messages, ai.user_message("now")] ) assert worker.fake.turns == ["now"] -async def test_a_copy_with_fork_branches_natively( - worker: fakes.FakeWorker, -) -> None: +async def test_fork_branches_natively(worker: fakes.FakeWorker) -> None: async with worker: await ai.experimental_generate(worker, [ai.user_message("one")]) - branch = worker.model_copy(update={"fork": True}) + branch = await worker.fork() async with branch: - assert branch.fake is not worker.fake # a CLI of its own + assert branch.fake is not worker.fake + assert branch.session_id == "s1-fork" + assert branch.messages == worker.messages + assert branch.messages is not worker.messages + assert branch.messages[0] is not worker.messages[0] + assert ( + branch.messages[0].parts[0] is not worker.messages[0].parts[0] + ) + stored = branch.fake.stored["s1-fork"] + assert branch.messages == stored + assert branch.messages[0] is not stored[0] await ai.experimental_generate( branch, [*branch.messages, ai.user_message("two")] ) - assert branch.fake.opens[0] == { - "session_id": "s1", - "fork": True, - "seed": None, - "instructions": None, - } - assert branch.session_id == "s1-fork" - assert branch.fork is False + assert branch.fake.opens == [ + { + "session_id": "s1", + "fork": True, + "seed": None, + "instructions": None, + } + ] + assert branch.fake.turns == ["two"] assert worker.session_id == "s1" assert len(worker.messages) == 2 assert len(branch.messages) == 4 @@ -328,7 +393,7 @@ async def test_a_copy_with_fork_branches_natively( async def test_a_worker_goes_in_a_context(worker: fakes.FakeWorker) -> None: context = ai.Context(model=worker, messages=[], tools=[]) data = json.loads(context.model_dump_json()) - assert data["model"]["kind"] == "fake" + assert data["model"]["worker_class_id"] == "fake" restored = ai.Context.model_validate(data) assert isinstance(restored.model, fakes.FakeWorker) @@ -346,6 +411,188 @@ async def test_close_keeps_the_fields(worker: fakes.FakeWorker) -> None: assert worker.fake.opens[0]["session_id"] == "s1" +@pytest.mark.parametrize("mode", ["resume", "copy", "deepcopy"]) +async def test_resume_and_copy_reset_all_private_state( + worker: fakes.FakeWorker, mode: str +) -> None: + async with worker: + await ai.experimental_generate(worker, [ai.user_message("one")]) + worker.script(lambda prompt: fakes.text("private script")) + if mode == "resume": + restored = workers.Worker.model_validate_json( + worker.model_dump_json() + ) + else: + restored = worker.model_copy(deep=mode == "deepcopy") + assert isinstance(restored, fakes.FakeWorker) + assert restored.model_dump() == worker.model_dump() + assert restored.messages is not worker.messages + assert restored.messages[0].parts[0] is not worker.messages[0].parts[0] + assert restored._runtime is None + assert restored._fake is None + assert restored._servers == {} + assert restored._script is fakes.reply + assert restored.version is None + assert restored._open_lock is not worker._open_lock + async with restored: + assert restored._runtime is not worker._runtime + assert restored.fake is not worker.fake + assert restored.hook_registry is not worker.hook_registry + answer = await ai.experimental_generate( + restored, [*restored.messages, ai.user_message("two")] + ) + assert answer.text == "two" + assert restored.fake.opens == [ + { + "session_id": "s1", + "fork": False, + "seed": None, + "instructions": None, + } + ] + assert not worker.fake.closed + assert len(worker.messages) == 2 + + +async def test_concurrent_open_starts_one_transport( + worker: fakes.FakeWorker, monkeypatch: pytest.MonkeyPatch +) -> None: + entered = asyncio.Event() + release = asyncio.Event() + second_entered = asyncio.Event() + starts: list[fakes.FakeAdapter] = [] + start = fakes.FakeAdapter.start + + async def slow_start(adapter: fakes.FakeAdapter) -> None: + starts.append(adapter) + entered.set() + await release.wait() + await start(adapter) + + async def second_open() -> None: + second_entered.set() + await worker.open() + + monkeypatch.setattr(fakes.FakeAdapter, "start", slow_start) + try: + async with asyncio.timeout(5), asyncio.TaskGroup() as tasks: + first = tasks.create_task(worker.open()) + await entered.wait() + second = tasks.create_task(second_open()) + await second_entered.wait() + assert not first.done() + assert not second.done() + assert len(starts) == 1 + release.set() + assert starts == [worker.fake] + assert worker.version == "fake 1.0" + runtime = worker._runtime + await worker.open() + assert worker._runtime is runtime + assert len(starts) == 1 + message = await ai.experimental_generate( + worker, [ai.user_message("one")] + ) + assert message.text == "one" + assert len(worker.fake.opens) == 1 + finally: + release.set() + await worker.close() + assert starts[0].closed + + +async def test_initial_stream_and_send_open_once_and_preserve_input( + worker: fakes.FakeWorker, monkeypatch: pytest.MonkeyPatch +) -> None: + opening = asyncio.Event() + release_open = asyncio.Event() + sending = asyncio.Event() + reading = asyncio.Event() + finish = asyncio.Event() + native_open = fakes.FakeAdapter.open + initial = ai.user_message("one") + + async def slow_open( + adapter: fakes.FakeAdapter, + *, + session_id: str | None, + fork: bool, + seed: list[m.Message] | None, + instructions: str | None, + ) -> str: + opened = await native_open( + adapter, + session_id=session_id, + fork=fork, + seed=seed, + instructions=instructions, + ) + opening.set() + await release_open.wait() + return opened + + async def read() -> list[events.Event]: + seen = [] + async with contextlib.aclosing(worker.stream([initial])) as feed: + async for event in feed: + seen.append(event) + if isinstance(event, events.StreamStart): + reading.set() + return seen + + async def send_guidance() -> None: + sending.set() + await worker.send("use tabs") + + async def wait_for_finish() -> None: + await finish.wait() + + monkeypatch.setattr(fakes.FakeAdapter, "open", slow_open) + worker.script( + lambda prompt: [fakes.Run(wait_for_finish), *fakes.text("done")] + ) + async with worker, asyncio.timeout(5): + reader = asyncio.create_task(read()) + sender: asyncio.Task[None] | None = None + try: + await opening.wait() + assert worker._runtime is not None + assert worker._runtime.stream_owner is reader + # The stream has reserved the reader, but its native session and + # initial input are not ready. A public send must wait, then steer. + sender = asyncio.create_task(send_guidance()) + await sending.wait() + assert not sender.done() + assert len(worker.fake.opens) == 1 + assert worker.fake.turns == [] + release_open.set() + await sender + await reading.wait() + finish.set() + seen = await reader + assert len(worker.fake.opens) == 1 + assert worker.fake.turns == ["one"] + assert worker.fake.steers == ["use tabs"] + users = [ + message for message in worker.messages if message.role == "user" + ] + assert [message.text for message in users] == ["one", "use tabs"] + assert users[0].id == initial.id + assert users[1].id != initial.id + assert worker.messages[-1].text == "done" + assert isinstance(seen[-1], events.StreamEnd) + assert seen[-1].finish_reason == "stop" + finally: + release_open.set() + finish.set() + reader.cancel() + tasks: list[asyncio.Task[Any]] = [reader] + if sender is not None: + sender.cancel() + tasks.append(sender) + await asyncio.gather(*tasks, return_exceptions=True) + + # -- ai.Agent tools, through the bridge --------------------------------------- @@ -461,29 +708,470 @@ async def test_approvals_are_tool_approval_hooks(granted: bool) -> None: assert answers[0][1] == "not today" # the reason the agent reads -async def test_approve_needs_a_run() -> None: +@pytest.mark.parametrize("granted", [True, False]) +async def test_agent_resolves_approval_from_a_preexisting_task( + granted: bool, +) -> None: worker = fakes.FakeWorker(approve=True) - async with worker: - with pytest.raises(workers.WorkerError, match=r"ai\.Agent\.run"): - await ai.experimental_generate(worker, [ai.user_message("go")]) + requested = asyncio.Event() + answered = asyncio.Event() + + async def external_callback() -> tuple[bool, str]: + await requested.wait() + approve = worker.fake.approve + assert approve is not None + answer = await approve("c1", "Bash", {"command": "ls"}) + answered.set() + return answer + + async def request_approval() -> None: + requested.set() + await answered.wait() + + worker.script( + lambda prompt: [fakes.Run(request_approval), *fakes.text("done")] + ) + async with worker, asyncio.timeout(5): + # CLI readers are often created before Agent.run establishes its + # context. The callback must use the stream's registry, not its own. + callback = asyncio.create_task(external_callback()) + seen: list[events.HookEvent] = [] + try: + async with ai.Agent().run(worker, [ai.user_message("go")]) as run: + async for event in run: + if isinstance(event, events.HookEvent): + seen.append(event) + if isinstance(event, events.PendingHookEvent): + assert event.hook.tool_call_id == "c1" + assert event.hook.metadata == { + "tool": "Bash", + "kwargs": {"command": "ls"}, + } + # Deliberately use the Agent context, without registry=. + ai.resolve_hook( + event.hook, + {"granted": granted, "reason": "user decision"}, + ) + done, _ = await asyncio.wait({callback}, timeout=1) + assert callback in done, ( + "Agent resolution did not reach the approval " + "callback created before Agent.run" + ) + assert callback.result() == (granted, "user decision") + assert [type(event) for event in seen] == [ + events.PendingHookEvent, + events.ResolvedHookEvent, + ] + assert run.messages[-1].text == "done" + assert worker.hook_registry._live_hooks == {} + assert worker._runtime is not None + assert worker._runtime.approvals == set() + finally: + callback.cancel() + with contextlib.suppress(asyncio.CancelledError): + await callback + + +@pytest.mark.parametrize("granted", [True, False]) +async def test_direct_approvals_use_the_worker_registry(granted: bool) -> None: + worker = fakes.FakeWorker(approve=True) + worker.script( + lambda prompt: [ + fakes.Ask("c1", "Bash", {"command": "ls"}), + *fakes.text("done"), + ] + ) + seen: list[workers.SessionEvent] = [] + async with worker, contextlib.aclosing(worker.events()) as feed: + async with asyncio.timeout(5): + await worker.send("go") + async for event in feed: + seen.append(event) + if isinstance(event, events.PendingHookEvent): + assert worker.fake.answers == [] + assert event.hook.tool_call_id == "c1" + assert event.hook.hook_type == "ToolApproval" + assert event.hook.metadata == { + "tool": "Bash", + "kwargs": {"command": "ls"}, + } + ai.resolve_hook( + event.hook, + {"granted": granted, "reason": "user decision"}, + registry=worker.hook_registry, + ) + if isinstance(event, events.StreamEnd): + break + assert worker.fake.answers == [(granted, "user decision")] + assert [ + type(event) for event in seen if isinstance(event, events.HookEvent) + ] == [events.PendingHookEvent, events.ResolvedHookEvent] + assert worker.hook_registry._live_hooks == {} + assert worker._runtime is not None + assert worker._runtime.approvals == set() + assert worker.messages[-1].text == "done" + + +@pytest.mark.parametrize("action", ["interrupt", "cancel"]) +async def test_stopping_a_pending_approval_cleans_up(action: str) -> None: + worker = fakes.FakeWorker(approve=True) + worker.script(lambda prompt: [fakes.Ask("c1", "Bash"), fakes.Pause()]) + pending = asyncio.Event() + seen: list[workers.SessionEvent] = [] + + async def read() -> None: + async with contextlib.aclosing(worker.events()) as feed: + async for event in feed: + seen.append(event) + if isinstance(event, events.PendingHookEvent): + pending.set() + if isinstance(event, events.StreamEnd): + return + + async with worker, asyncio.timeout(5): + await worker.send("one") + reader = asyncio.create_task(read()) + try: + await pending.wait() + registry = worker.hook_registry + assert len(registry._live_hooks) == 1 + if action == "interrupt": + await worker.interrupt() + await reader + assert isinstance(seen[-1], events.StreamEnd) + assert seen[-1].finish_reason == "other" + else: + reader.cancel() + with pytest.raises(asyncio.CancelledError): + await reader + finally: + if not reader.done(): + reader.cancel() + with contextlib.suppress(asyncio.CancelledError): + await reader + assert worker.fake.answers == [(False, "the approval was cancelled")] + assert registry._live_hooks == {} + assert not worker.fake.running + assert worker._runtime is not None + assert not worker._runtime.reader + assert worker._runtime.pump is None + assert worker._runtime.approvals == set() + worker.script(fakes.reply) + answer = await ai.experimental_generate( + worker, [*worker.messages, ai.user_message("two")] + ) + assert answer.text == "two" + assert worker.messages[-2].text == "two" + assert worker.fake.turns == ["one", "two"] -# -- steer, the TUI, the store ------------------------------------------------ +async def test_approve_without_a_hook_does_not_require_an_agent() -> None: + async with fakes.FakeWorker(approve=True) as worker: + message = await ai.experimental_generate( + worker, [ai.user_message("go")] + ) + assert message.text == "go" + + +# -- direct control, the TUI, the store --------------------------------------- + + +async def test_send_reaches_the_running_turn(worker: fakes.FakeWorker) -> None: + worker.script(lambda prompt: [*fakes.text("working"), fakes.Pause()]) + async with worker, contextlib.aclosing(worker.events()) as feed: + async with asyncio.timeout(5): + await worker.send("go") + accepted = [] + async for event in feed: + if isinstance(event, workers.UserMessageAccepted): + accepted.append(event.message.text) + if event.message.text == "use tabs": + await worker.interrupt() + if isinstance(event, events.TextEnd): + await worker.send("use tabs") + assert [ + x.text for x in worker.messages if x.role == "user" + ] == ["go"] + if isinstance(event, events.StreamEnd): + assert event.finish_reason == "other" + break + assert accepted == ["go", "use tabs"] + assert worker.fake.turns == ["go"] + assert worker.fake.steers == ["use tabs"] -async def test_steer_reaches_the_running_turn( +async def test_one_persistent_feed_mirrors_multiple_sends( worker: fakes.FakeWorker, +) -> None: + async with worker, contextlib.aclosing(worker.events()) as feed: + async with asyncio.timeout(5): + for index, prompt in enumerate(("one", "two")): + await worker.send(prompt) + # Acceptance is queued, but send() must not mutate the mirror. + assert len(worker.messages) == index * 2 + accepted = await anext(feed) + assert isinstance(accepted, workers.UserMessageAccepted) + assert accepted.message.text == prompt + assert worker.messages[-1] is accepted.message + assert len(worker.messages) == index * 2 + 1 + seen = [] + async for event in feed: + seen.append(event) + if isinstance(event, events.StreamEnd): + break + assert [type(event) for event in seen] == [ + events.StreamStart, + events.TextStart, + events.TextDelta, + events.TextEnd, + events.StreamEnd, + ] + assert len(worker.messages) == (index + 1) * 2 + assert worker.messages[-1].text == prompt + assert all( + event.message is worker.messages[-1] for event in seen + ) + assert worker.fake.turns == ["one", "two"] + assert len(worker.fake.opens) == 1 + await worker.close() + with pytest.raises(StopAsyncIteration): + await anext(feed) + assert [message.role for message in worker.messages] == [ + "user", + "assistant", + "user", + "assistant", + ] + assert len({message.id for message in worker.messages}) == 4 + + +@pytest.mark.parametrize("owner", ["direct", "stream"]) +@pytest.mark.parametrize("challenger", ["direct", "stream"]) +async def test_one_reader_guard_across_direct_and_model_apis( + worker: fakes.FakeWorker, owner: str, challenger: str ) -> None: worker.script(lambda prompt: [*fakes.text("working"), fakes.Pause()]) async with worker: - with pytest.raises(workers.WorkerError): - await worker.steer("too early") - async with ai.stream(worker, [ai.user_message("go")]) as s: - async for event in s: + if owner == "direct": + await worker.send("one") + feed = worker.events() + else: + feed = worker.stream([ai.user_message("one")]) + async with contextlib.aclosing(feed): + await anext(feed) + other = ( + worker.events() + if challenger == "direct" + else worker.stream([*worker.messages, ai.user_message("two")]) + ) + async with contextlib.aclosing(other): + with pytest.raises( + workers.WorkerError, match="already has a reader" + ): + await anext(other) + assert worker.fake.turns == ["one"] + assert worker.fake.interrupts == 0 + async with asyncio.timeout(5): + await worker.interrupt() + async for event in feed: + if isinstance(event, events.StreamEnd): + assert event.finish_reason == "other" + break + assert worker._runtime is not None + assert not worker._runtime.reader + assert worker._runtime.stream_owner is None + + +async def test_stream_reserves_the_reader_before_send_acceptance( + worker: fakes.FakeWorker, monkeypatch: pytest.MonkeyPatch +) -> None: + entered = asyncio.Event() + release = asyncio.Event() + turn = fakes.FakeAdapter.turn + + async def slow_turn( + adapter: fakes.FakeAdapter, prompt: _adapter.Prompt + ) -> AsyncIterator[events.Event]: + entered.set() + await release.wait() + async for event in turn(adapter, prompt): + yield event + + monkeypatch.setattr(fakes.FakeAdapter, "turn", slow_turn) + async with worker, asyncio.timeout(5), asyncio.TaskGroup() as tasks: + first = tasks.create_task( + collect(worker.stream([ai.user_message("one")])) + ) + await entered.wait() + try: + for other in ( + worker.events(), + worker.stream([ai.user_message("two")]), + ): + async with contextlib.aclosing(other): + with pytest.raises( + workers.WorkerError, match="already has a reader" + ): + await anext(other) + finally: + release.set() + assert isinstance(first.result()[-1], events.StreamEnd) + assert [message.text for message in worker.messages] == ["one", "one"] + + +async def test_cancellation_before_acceptance_cleans_up( + worker: fakes.FakeWorker, monkeypatch: pytest.MonkeyPatch +) -> None: + entered = asyncio.Event() + release = asyncio.Event() + exited = asyncio.Event() + turn = fakes.FakeAdapter.turn + + async def slow_turn( + adapter: fakes.FakeAdapter, prompt: _adapter.Prompt + ) -> AsyncIterator[events.Event]: + entered.set() + try: + await release.wait() + async for event in turn(adapter, prompt): + yield event + finally: + exited.set() + + monkeypatch.setattr(fakes.FakeAdapter, "turn", slow_turn) + async with worker, asyncio.timeout(5): + reader = asyncio.create_task( + collect(worker.stream([ai.user_message("one")])) + ) + try: + await entered.wait() + finally: + reader.cancel() + with pytest.raises(asyncio.CancelledError): + await reader + assert exited.is_set() + assert worker.messages == [] + assert worker.fake.interrupts == 1 + assert worker._runtime is not None + assert worker._runtime.pump is None + assert not worker._runtime.reader + assert worker._runtime.stream_owner is None + assert worker._runtime.submission is None + release.set() + answer = await ai.experimental_generate( + worker, [ai.user_message("one")] + ) + assert answer.text == "one" + assert worker.fake.turns == ["one"] + + +async def test_interrupt_ends_a_turn_but_not_the_session_feed( + worker: fakes.FakeWorker, +) -> None: + worker.script(lambda prompt: [*fakes.text("partial"), fakes.Pause()]) + async with worker, contextlib.aclosing(worker.events()) as feed: + async with asyncio.timeout(5): + await worker.send("one") + async for event in feed: if isinstance(event, events.TextEnd): - await worker.steer("use tabs") - await worker.fake.interrupt() - assert worker.fake.steers == ["use tabs"] + await worker.interrupt() + if isinstance(event, events.StreamEnd): + assert event.finish_reason == "other" + assert event.provider_metadata is not None + assert ( + event.provider_metadata["worker"]["finish_reason"] + == "cancelled" + ) + break + assert worker.fake.interrupts == 1 + assert worker.messages[-1].text == "partial" + worker.script(fakes.reply) + await worker.send("two") + accepted = await anext(feed) + assert isinstance(accepted, workers.UserMessageAccepted) + assert accepted.message.text == "two" + async for event in feed: + if isinstance(event, events.StreamEnd): + assert event.finish_reason == "stop" + break + assert worker.messages[-1].text == "two" + assert worker.fake.turns == ["one", "two"] + + +@pytest.mark.parametrize("api", ["direct", "stream"]) +async def test_cancelling_a_reader_cleans_up_and_allows_another_turn( + worker: fakes.FakeWorker, api: str +) -> None: + waiting = asyncio.Event() + worker.script(lambda prompt: [*fakes.text("partial"), fakes.Pause()]) + + async def read() -> None: + if api == "direct": + await worker.send("one") + feed = worker.events() + else: + feed = worker.stream([ai.user_message("one")]) + async with contextlib.aclosing(feed): + async for event in feed: + if isinstance(event, events.TextEnd): + waiting.set() + + async with worker, asyncio.timeout(5): + reader = asyncio.create_task(read()) + try: + await waiting.wait() + finally: + reader.cancel() + with pytest.raises(asyncio.CancelledError): + await reader + assert worker.fake.interrupts == 1 + assert not worker.fake.running + assert worker._runtime is not None + assert worker._runtime.pump is None + assert not worker._runtime.reader + assert worker._runtime.stream_owner is None + assert worker._runtime.pending == {} + assert worker._runtime.approvals == set() + assert [message.text for message in worker.messages] == [ + "one", + "partial", + ] + worker.script(fakes.reply) + answer = await ai.experimental_generate( + worker, [*worker.messages, ai.user_message("two")] + ) + assert answer.text == "two" + assert worker.fake.turns == ["one", "two"] + + +async def test_sync_and_fork_require_an_idle_session( + worker: fakes.FakeWorker, +) -> None: + async with worker: + for action in (worker.sync, worker.fork): + with pytest.raises(workers.WorkerError, match="no session_id"): + await action() + worker.script(lambda prompt: [fakes.Pause()]) + await worker.send("one") + for action in (worker.sync, worker.fork): + with pytest.raises( + workers.WorkerError, match="stop the turn and reader" + ): + await action() + async with ( + contextlib.aclosing(worker.events()) as feed, + asyncio.timeout(5), + ): + await worker.interrupt() + async for event in feed: + if isinstance(event, events.StreamEnd): + break + # Even between turns a live reader owns the mirror. + for action in (worker.sync, worker.fork): + with pytest.raises( + workers.WorkerError, match="stop the turn and reader" + ): + await action() async def test_tui_command_mints_a_session(worker: fakes.FakeWorker) -> None: @@ -503,7 +1191,7 @@ async def test_tui_hands_over_and_reads_back() -> None: assert await worker.tui() == 0 # tui() closed the worker's CLI, ran the TUI, and opened again. worker.fake.stored["s1"] = stored - await worker.load() + await worker.sync() assert worker.messages == stored diff --git a/uv.lock b/uv.lock index d371b1aa..0d0c4a4c 100644 --- a/uv.lock +++ b/uv.lock @@ -25,6 +25,9 @@ dependencies = [ anthropic = [ { name = "anthropic" }, ] +claude-code = [ + { name = "claude-agent-sdk" }, +] mcp = [ { name = "mcp" }, ] @@ -46,6 +49,7 @@ vercel = [ dev = [ { name = "anthropic" }, { name = "async-solipsism" }, + { name = "claude-agent-sdk" }, { name = "mcp" }, { name = "mypy" }, { name = "openai" }, @@ -53,6 +57,7 @@ dev = [ { name = "opentelemetry-sdk" }, { name = "pytest" }, { name = "pytest-asyncio" }, + { name = "pytest-timeout" }, { name = "python-dotenv" }, { name = "rich" }, { name = "ruff" }, @@ -64,6 +69,7 @@ dev = [ [package.metadata] requires-dist = [ { name = "anthropic", marker = "extra == 'anthropic'", specifier = ">=0.83.0,<2.0.0" }, + { name = "claude-agent-sdk", marker = "extra == 'claude-code'", specifier = ">=0.2.144,<0.3" }, { name = "httpx2", specifier = ">=2.12.0" }, { name = "mcp", marker = "extra == 'mcp'", specifier = ">=2.0.0,<3.0.0" }, { name = "modelsdotdev", specifier = "==0.*" }, @@ -75,12 +81,13 @@ requires-dist = [ { name = "typing-extensions", specifier = ">=4.15.0" }, { name = "vercel-oidc", marker = "extra == 'vercel'", specifier = ">=0.8.0" }, ] -provides-extras = ["anthropic", "mcp", "openai", "otel", "typesafe", "vercel"] +provides-extras = ["anthropic", "claude-code", "mcp", "openai", "otel", "typesafe", "vercel"] [package.metadata.requires-dev] dev = [ { name = "anthropic", specifier = ">=0.83.0" }, { name = "async-solipsism", specifier = ">=0.9" }, + { name = "claude-agent-sdk", specifier = ">=0.2.144,<0.3" }, { name = "mcp", specifier = ">=2.0.0,<3.0.0" }, { name = "mypy", specifier = "~=2.1.0" }, { name = "openai", specifier = ">=2.14.0" }, @@ -88,6 +95,7 @@ dev = [ { name = "opentelemetry-sdk", specifier = ">=1.43.0" }, { name = "pytest", specifier = ">=8.0" }, { name = "pytest-asyncio", specifier = ">=0.24" }, + { name = "pytest-timeout", specifier = ">=2.3" }, { name = "python-dotenv", specifier = ">=1.2.1" }, { name = "rich", specifier = ">=14.2.0" }, { name = "ruff", specifier = "~=0.8.0" }, @@ -333,6 +341,25 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/db/8f/61959034484a4a7c527811f4721e75d02d653a35afb0b6054474d8185d4c/charset_normalizer-3.4.7-py3-none-any.whl", hash = "sha256:3dce51d0f5e7951f8bb4900c257dad282f49190fdbebecd4ba99bcc41fef404d", size = 61958, upload-time = "2026-04-02T09:28:37.794Z" }, ] +[[package]] +name = "claude-agent-sdk" +version = "0.2.178" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "anyio" }, + { name = "jsonschema" }, + { name = "mcp" }, + { name = "sniffio" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/bb/96/029c76e62b48c7eef3982873f6882d8e5f94a8eaa293392a91229cc0b87e/claude_agent_sdk-0.2.178.tar.gz", hash = "sha256:b59aca6ba61d43a6d78f0ad03a2230485a26a73d7f5e7b60e9d5e8a70cdba8f2", size = 400217, upload-time = "2026-11-04T00:52:25.514Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/d2/cd/73bf0d3b6ec1456461e7e83e900c3bcf1ef6d767530dac1ad4590cc2ea74/claude_agent_sdk-0.2.178-py3-none-macosx_11_0_arm64.whl", hash = "sha256:7a20f490cfdd7d7cb9a70b3500cb0d9d026420d987e25a10667c638c5dfe036d", size = 138228664, upload-time = "2026-11-04T00:52:32.383Z" }, + { url = "https://files.pythonhosted.org/packages/ba/b6/62e1a2d67ff4561cf31758b4332594086979c849eede9ab21950601af24e/claude_agent_sdk-0.2.178-py3-none-macosx_11_0_x86_64.whl", hash = "sha256:c944ff5f0bac523b8c77d8d2f7913d533efc983e42eece1502fe74aa3a4a0482", size = 145514246, upload-time = "2026-11-04T00:52:39.069Z" }, + { url = "https://files.pythonhosted.org/packages/bb/10/c5d2908e1bded45de8b69b44bc5d76f431534e18cca99d192a755d04801e/claude_agent_sdk-0.2.178-py3-none-manylinux_2_17_aarch64.whl", hash = "sha256:98fcd5ea6b591d14a65580bee3df3f5fa7c75ad68a44ff81780177d2ed8db2a3", size = 149927469, upload-time = "2026-11-04T00:52:45.46Z" }, + { url = "https://files.pythonhosted.org/packages/49/5f/fb5dc93b604e8c55bd0da2465ba075b28e6ba4f0b0cda30cd15649c87e7d/claude_agent_sdk-0.2.178-py3-none-manylinux_2_17_x86_64.whl", hash = "sha256:1d5e6d2cced242b9d74658ec90d96936a7c9db5867b85705ae52ec0736060146", size = 150300143, upload-time = "2026-11-04T00:52:52.87Z" }, + { url = "https://files.pythonhosted.org/packages/46/9b/2a8cf8def2c32bd296d6380d08dafef63969ca9eb0c5674a7fa8cce4d1d6/claude_agent_sdk-0.2.178-py3-none-win_amd64.whl", hash = "sha256:b31f5b4076b6a0ce138716f03d04ab9899fa8b4bde7d7760f9862bdcf9b2786b", size = 151962195, upload-time = "2026-11-04T00:53:00.908Z" }, +] + [[package]] name = "click" version = "8.3.1" @@ -1092,6 +1119,18 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/e5/35/f8b19922b6a25bc0880171a2f1a003eaeb93657475193ab516fd87cac9da/pytest_asyncio-1.3.0-py3-none-any.whl", hash = "sha256:611e26147c7f77640e6d0a92a38ed17c3e9848063698d5c93d5aa7aa11cebff5", size = 15075, upload-time = "2025-11-10T16:07:45.537Z" }, ] +[[package]] +name = "pytest-timeout" +version = "2.4.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "pytest" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/ac/82/4c9ecabab13363e72d880f2fb504c5f750433b2b6f16e99f4ec21ada284c/pytest_timeout-2.4.0.tar.gz", hash = "sha256:7e68e90b01f9eff71332b25001f85c75495fc4e3a836701876183c4bcfd0540a", size = 17973, upload-time = "2025-05-05T19:44:34.99Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/fa/b6/3127540ecdf1464a00e5a01ee60a1b09175f6913f0644ac748494d9c4b21/pytest_timeout-2.4.0-py3-none-any.whl", hash = "sha256:c42667e5cdadb151aeb5b26d114aff6bdf5a907f176a007a30b940d3d865b5c2", size = 14382, upload-time = "2025-05-05T19:44:33.502Z" }, +] + [[package]] name = "python-dotenv" version = "1.2.1"