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/apps/durable_agent_temporal/backend/app/worker.py b/examples/apps/durable_agent_temporal/backend/app/worker.py index 58aac72f..fe10f33b 100644 --- a/examples/apps/durable_agent_temporal/backend/app/worker.py +++ b/examples/apps/durable_agent_temporal/backend/app/worker.py @@ -109,6 +109,8 @@ class DurableAgent(ai.Agent): async def loop(self, context: ai.Context) -> AsyncGenerator[ai.events.AgentEvent]: tools_data = [tool.model_dump(mode="json") for tool in context.tools] + # A durable step serializes the model: it must be an ai.Model. + assert isinstance(context.model, ai.Model) while context.keep_running(): result = await temporalio.workflow.execute_activity( llm_activity, diff --git a/examples/apps/durable_agent_workflows/backend/app/worker.py b/examples/apps/durable_agent_workflows/backend/app/worker.py index 0b88d193..23eed150 100644 --- a/examples/apps/durable_agent_workflows/backend/app/worker.py +++ b/examples/apps/durable_agent_workflows/backend/app/worker.py @@ -92,6 +92,8 @@ class DurableAgent(ai.Agent): async def loop(self, context: ai.Context) -> AsyncGenerator[ai.events.AgentEvent]: tools_data = [tool.model_dump(mode="json") for tool in context.tools] + # A durable step serializes the model: it must be an ai.Model. + assert isinstance(context.model, ai.Model) while context.keep_running(): result = await llm_step( context.model.model_dump(mode="json"), diff --git a/examples/workers/__init__.py b/examples/workers/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/examples/workers/approvals.py b/examples/workers/approvals.py new file mode 100644 index 00000000..044d70f4 --- /dev/null +++ b/examples/workers/approvals.py @@ -0,0 +1,47 @@ +"""Answer CLI approval requests through `ai.Agent` tool approvals. + +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 [claude-code|codex|pi] +""" + +import asyncio +import sys +from collections.abc import Callable + +import ai +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, + 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 new file mode 100644 index 00000000..feb01d65 --- /dev/null +++ b/examples/workers/streaming.py @@ -0,0 +1,54 @@ +"""A worker where a model goes: stream it, then continue the conversation. + +uv run python examples/workers/streaming.py [claude-code|codex|pi] +""" + +import asyncio +import sys +from collections.abc import Callable + +import ai +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: + async with KINDS[kind]() as worker: + messages = [ + ai.user_message( + "List the files here with a shell command, then say DONE." + ) + ] + async with ai.stream(worker, messages) as s: + async for event in s: + match event: + case ai.events.TextDelta(): + print(event.chunk, end="", flush=True) + case ai.events.BuiltinToolEnd(): # the CLI's own tool + call = event.tool_call + print(f"\n[{call.tool_name}] {call.tool_args[:60]}") + print(f"\nusage: {s.message.usage}") + + # The worker keeps the conversation: send it back with what is new. + follow_up = [ + *worker.messages, + ai.user_message("How many files? Reply with a number only."), + ] + print(await ai.experimental_generate(worker, follow_up)) + + # A worker is data: save it, and continue the conversation later. + saved = worker.model_dump_json() + again = workers.Worker.model_validate_json(saved) + async with again: + reply = await ai.experimental_generate( + again, [*again.messages, ai.user_message("And the largest one?")] + ) + print(reply.text) + + +asyncio.run(main(sys.argv[1] if len(sys.argv) > 1 else "claude-code")) diff --git a/pyproject.toml b/pyproject.toml index 6bfd5968..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", ] @@ -176,6 +187,11 @@ extend-ignore = [ "TC003", # annoying and wrong if TYPE_CHECKING for stdlib imports ] +[tool.ruff.lint.flake8-type-checking] +# pydantic evaluates field annotations at runtime, so their imports must stay +# real even under `from __future__ import annotations` +runtime-evaluated-base-classes = ["pydantic.BaseModel"] + [tool.ruff.lint.per-file-ignores] "examples/**/*.py" = [ "D", # examples are executable samples, not public API diff --git a/src/ai/__init__.py b/src/ai/__init__.py index b10faf3e..c70016ad 100644 --- a/src/ai/__init__.py +++ b/src/ai/__init__.py @@ -8,6 +8,7 @@ testing, ui, util, + workers, ) from .agents import ( Agent, @@ -74,6 +75,7 @@ InferenceRequestParams, MinPSamplerParams, Model, + ModelLike, ModelProviderDefault, OutputParams, Provider, @@ -138,6 +140,7 @@ "InstallationError", "MinPSamplerParams", "Model", + "ModelLike", "ModelProviderDefault", "OutputParams", "Provider", @@ -227,5 +230,6 @@ "ui", "user_message", "util", + "workers", "yield_from", ] diff --git a/src/ai/agents/agent.py b/src/ai/agents/agent.py index ec53583c..3e89a06b 100644 --- a/src/ai/agents/agent.py +++ b/src/ai/agents/agent.py @@ -1039,10 +1039,34 @@ async def _iterate(self) -> AsyncGenerator[events_.ToolCallResult]: yield res +def _validate_model(value: Any) -> models.ModelLike: + # Another model-like (an ai.workers.Worker) is kept as it is. A dict + # 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 "worker_class_id" in value: + from .. import workers # noqa: PLC0415 + + return workers.Worker.model_validate(value) + return models.Model.model_validate(value) + + +def _serialize_model(value: Any, info: pydantic.SerializationInfo) -> Any: + if isinstance(value, pydantic.BaseModel): + return value.model_dump(mode=info.mode) + return {"id": value.id, "provider_name": value.provider_name} + + class Context(pydantic.BaseModel): """Everything that goes into the LLM.""" - model: models.Model + model: Annotated[ + models.ModelLike, + pydantic.PlainValidator(_validate_model), + pydantic.PlainSerializer(_serialize_model), + ] messages: list[types.messages.Message] tools: list[Tool] output_type: type[pydantic.BaseModel] | None = pydantic.Field( @@ -1493,7 +1517,7 @@ async def loop( @overload def run( self, - model: models.Model, + model: models.ModelLike, messages: list[types.messages.Message], *, params: models.InferenceRequestParams | None = None, @@ -1502,7 +1526,7 @@ def run( @overload def run[T: pydantic.BaseModel]( self, - model: models.Model, + model: models.ModelLike, messages: list[types.messages.Message], *, output_type: type[T], @@ -1511,7 +1535,7 @@ def run[T: pydantic.BaseModel]( ) -> AbstractAsyncContextManager[AgentStream[T]]: ... def run( self, - model: models.Model, + model: models.ModelLike, messages: list[types.messages.Message], *, output_type: type[pydantic.BaseModel] | None = None, @@ -1556,7 +1580,7 @@ def run( @contextlib.asynccontextmanager async def _run( self, - model: models.Model, + model: models.ModelLike, messages: list[types.messages.Message], *, output_type: type[pydantic.BaseModel] | None, @@ -1610,7 +1634,7 @@ async def _stream() -> AsyncGenerator[events_.AgentEvent]: agent=type(self).__name__, model=model.id, messages=list(messages), - provider=model.provider.name, + provider=model.provider_name, tool_names=[t.name for t in context.tools], output_type=( output_type.__name__ 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/models/__init__.py b/src/ai/models/__init__.py index 1b3b99d8..9c664b6b 100644 --- a/src/ai/models/__init__.py +++ b/src/ai/models/__init__.py @@ -39,7 +39,7 @@ probe, stream, ) -from .core.model import Model, get_model +from .core.model import Model, ModelLike, get_model from .core.params import ( DEFAULT, GLOBAL, @@ -85,6 +85,7 @@ "InferenceRequestParams", "MinPSamplerParams", "Model", + "ModelLike", "ModelProviderDefault", "OutputParams", "Provider", diff --git a/src/ai/models/core/api.py b/src/ai/models/core/api.py index 4e6f10bf..64d295ba 100644 --- a/src/ai/models/core/api.py +++ b/src/ai/models/core/api.py @@ -22,11 +22,11 @@ from ... import errors, types from ... import experimental_telemetry as telemetry +from . import model as model_ if TYPE_CHECKING: from collections.abc import AsyncGenerator, AsyncIterator, Sequence - from . import model as model_ from . import params as params_ # Stream output type. Defaults to ``str``: when the stream was opened @@ -37,7 +37,7 @@ @dataclasses.dataclass(frozen=True) class _StreamRequest: - model: model_.Model + model: model_.ModelLike messages: list[types.messages.Message] tools: Sequence[types.tools.Tool] | None = None output_type: type[pydantic.BaseModel] | None = None @@ -66,18 +66,26 @@ async def _do_stream( self, request: _StreamRequest, ) -> AsyncGenerator[types.events.Event]: - async for ev in request.model.provider.stream( - request.model, - request.messages, - tools=request.tools, - output_type=request.output_type, - params=request.params, - ): - yield ev + # Closed with the outer generator, not left to the garbage + # collector: a model-like with state (a worker) cleans up in it. + async with contextlib.aclosing( + request.model.stream( + request.messages, + tools=request.tools, + output_type=request.output_type, + params=request.params, + ) + ) as inner: + async for ev in inner: + yield ev async def _do_generate( self, request: _StreamRequest ) -> types.messages.Message: + # Only a provider-backed model has a native generate; anything else + # that is model-like is drained from its stream by the caller. + if not isinstance(request.model, model_.Model): + raise NotImplementedError return await request.model.provider.generate( request.model, request.messages, @@ -307,7 +315,7 @@ class StreamContext(Protocol): """ @property - def model(self) -> model_.Model: ... + def model(self) -> model_.ModelLike: ... @property def messages(self) -> list[types.messages.Message]: ... @property @@ -333,7 +341,7 @@ def stream[T: pydantic.BaseModel]( ) -> AbstractAsyncContextManager[Stream[T]]: ... @overload def stream( - model: model_.Model, + model: model_.ModelLike, messages: list[types.messages.Message], *, tools: Sequence[types.tools.Tool] | None = None, @@ -341,7 +349,7 @@ def stream( ) -> AbstractAsyncContextManager[Stream[str]]: ... @overload def stream[T: pydantic.BaseModel]( - model: model_.Model, + model: model_.ModelLike, messages: list[types.messages.Message], *, tools: Sequence[types.tools.Tool] | None = None, @@ -349,7 +357,7 @@ def stream[T: pydantic.BaseModel]( params: params_.InferenceRequestParams | None = None, ) -> AbstractAsyncContextManager[Stream[T]]: ... def stream( - model: model_.Model | None = None, + model: model_.ModelLike | None = None, messages: list[types.messages.Message] | None = None, *, context: StreamContext | None = None, @@ -401,7 +409,7 @@ def stream( @contextlib.asynccontextmanager async def _stream( *, - model: model_.Model, + model: model_.ModelLike, messages: list[types.messages.Message], tools: Sequence[types.tools.Tool] | None, output_type: type[pydantic.BaseModel] | None, @@ -412,7 +420,7 @@ async def _stream( model=model.id, messages=list(messages), params=params, - provider=model.provider.name, + provider=model.provider_name, tool_names=[t.name for t in tools] if tools is not None else None, output_type=output_type.__name__ if output_type is not None else None, ) @@ -467,7 +475,7 @@ async def experimental_generate( ) -> types.messages.Message: ... @overload async def experimental_generate( - model: model_.Model, + model: model_.ModelLike, messages: list[types.messages.Message], *, tools: Sequence[types.tools.Tool] | None = None, @@ -475,7 +483,7 @@ async def experimental_generate( params: params_.InferenceRequestParams | None = None, ) -> types.messages.Message: ... async def experimental_generate( - model: model_.Model | None = None, + model: model_.ModelLike | None = None, messages: list[types.messages.Message] | None = None, *, context: StreamContext | None = None, @@ -525,7 +533,7 @@ async def experimental_generate( model=model.id, messages=list(messages), params=params, - provider=model.provider.name, + provider=model.provider_name, tool_names=[t.name for t in tools] if tools is not None else None, output_type=output_type.__name__ if output_type is not None else None, ) diff --git a/src/ai/models/core/model.py b/src/ai/models/core/model.py index e944767d..a49dd8e6 100644 --- a/src/ai/models/core/model.py +++ b/src/ai/models/core/model.py @@ -1,13 +1,25 @@ """Model metadata types.""" +from __future__ import annotations + import os import weakref -from typing import TYPE_CHECKING, Any, Self, cast +from typing import ( + TYPE_CHECKING, + Any, + Protocol, + Self, + cast, + runtime_checkable, +) import pydantic if TYPE_CHECKING: - from collections.abc import Callable + from collections.abc import AsyncGenerator, Callable, Sequence + + from ... import types + from . import params as params_ from ... import _modelsdev from ...errors import ConfigurationError @@ -16,6 +28,36 @@ _DEFAULT_MODEL_ENV = "AI_SDK_DEFAULT_MODEL" +@runtime_checkable +class ModelLike(Protocol): + """Anything that answers a conversation the way a model does. + + `ai.stream`, `ai.experimental_generate` and `ai.Agent.run` take a + `ModelLike`. `ai.Model` is one; anything with the same `stream` is + another, a coding-agent CLI for example. + + `stream` receives the WHOLE conversation on every call and yields the + events of ONE assistant message, ending with `StreamEnd`. + """ + + @property + def id(self) -> str: ... + + @property + def provider_name(self) -> str: + """Who answers: a provider name, or a worker kind. For telemetry.""" + ... + + def stream( + self, + messages: list[types.messages.Message], + *, + tools: Sequence[types.tools.Tool] | None = None, + output_type: type[pydantic.BaseModel] | None = None, + params: params_.InferenceRequestParams | None = None, + ) -> AsyncGenerator[types.events.Event]: ... + + def _exclude_if_none(v: Any) -> bool: # pydantic-core's SchemaSerializer doesn't GC-traverse ``exclude_if`` # callables, so a closure stored there directly forms an uncollectable @@ -50,6 +92,27 @@ def __hash__(self) -> int: def with_protocol(self, protocol: base.ProviderProtocol[Any]) -> Self: return self.model_copy(update={"protocol": protocol}) + @property + def provider_name(self) -> str: + return self.provider.name + + def stream( + self, + messages: list[types.messages.Message], + *, + tools: Sequence[types.tools.Tool] | None = None, + output_type: type[pydantic.BaseModel] | None = None, + params: params_.InferenceRequestParams | None = None, + ) -> AsyncGenerator[types.events.Event]: + """Return the raw provider stream. Use `ai.stream(model, ...)`.""" + return self.provider.stream( + self, + messages, + tools=tools, + output_type=output_type, + params=params, + ) + def get_model( model_id: str | None = None, 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 new file mode 100644 index 00000000..be01ec18 --- /dev/null +++ b/src/ai/workers/__init__.py @@ -0,0 +1,76 @@ +"""Coding-agent CLI sessions: Claude Code, Codex and Pi. + +Experimental: not part of the stable API, may change or be removed. + +Use a worker as a model, continuing from its current message mirror:: + + import ai + from ai import workers + + 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.")] + ) + +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``). + +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. + +``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 ._adapter import SessionInfo +from ._errors import ( + ExecutableMissingError, + NotAuthenticatedError, + TranscriptMismatchError, + UnsupportedError, + WorkerError, +) +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/_bridge.py b/src/ai/workers/_bridge.py new file mode 100644 index 00000000..ef0bb5b8 --- /dev/null +++ b/src/ai/workers/_bridge.py @@ -0,0 +1,230 @@ +"""The MCP bridge: `ai` tools, served to a coding-agent CLI. + +A worker's CLI runs its own loop and its own tools. To give it the tools an +`ai.Agent` holds, the worker serves them over MCP on localhost, and the CLI +connects to that server like any other. + +The server does not run a tool. It hands each call to `on_call` and waits +for the answer. The worker turns the call into a normal `ToolCallPart`, ends +its stream with `finish_reason="tool_call"`, and `ai.Agent` runs the tool. +The next `stream()` call brings the result, and the worker answers the +waiting request with it. While the request waits, the CLI waits too. + +Only what an MCP client needs is implemented: streamable HTTP, POST only, +plain JSON responses (no SSE), and the methods `initialize`, `ping`, +`tools/list` and `tools/call`. +""" + +from __future__ import annotations + +import asyncio +import contextlib +import json +from collections.abc import Awaitable, Callable +from typing import TYPE_CHECKING, Any + +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" + +PROTOCOL_VERSION = "2025-06-18" + +# `on_call(name, arguments)` returns `(text, is_error)`. +OnCall = Callable[[str, dict[str, Any]], Awaitable[tuple[str, bool]]] + + +class Bridge: + def __init__(self, on_call: OnCall) -> None: + self._on_call = on_call + self._tools: dict[str, tools_.Tool] = {} + self._server: asyncio.Server | None = None + self._connections: set[asyncio.Task[None]] = set() + + @property + def url(self) -> str: + if self._server is None: + raise RuntimeError("bridge is not started") + host, port = self._server.sockets[0].getsockname()[:2] + return f"http://{host}:{port}/mcp" + + @property + def names(self) -> set[str]: + return set(self._tools) + + def set_tools(self, tools: list[tools_.Tool]) -> None: + """Serve these tools from now on. + + A CLI reads the list when it connects, so a tool added after that + may stay unseen until the next connection. + """ + self._tools = { + t.name: t for t in tools if t.kind == "function" and t.spec + } + + async def start(self) -> None: + if self._server is None: + self._server = await asyncio.start_server( + self._serve, host="127.0.0.1", port=0 + ) + + async def close(self) -> None: + if self._server is None: + return + self._server.close() + for task in list(self._connections): + task.cancel() + for task in list(self._connections): + with contextlib.suppress(BaseException): + await task + with contextlib.suppress(Exception): + await self._server.wait_closed() + self._server = None + + # -- HTTP ----------------------------------------------------------------- + + async def _serve( + self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter + ) -> None: + task = asyncio.current_task() + assert task is not None + self._connections.add(task) + try: + while True: + request = await _read_request(reader) + if request is None: + return + method, body = request + if method != "POST": + # No SSE stream to offer, and a session needs no teardown. + status = 200 if method == "DELETE" else 405 + await _respond(writer, status, None) + continue + reply = await self._dispatch(body) + await _respond(writer, 200 if reply is not None else 202, reply) + except (ConnectionError, asyncio.IncompleteReadError): + return + finally: + self._connections.discard(task) + with contextlib.suppress(Exception): + writer.close() + + # -- JSON-RPC ------------------------------------------------------------- + + async def _dispatch(self, body: bytes) -> Any: + try: + payload = json.loads(body or b"null") + except json.JSONDecodeError: + return _error(None, -32700, "parse error") + if isinstance(payload, list): + replies = [await self._one(item) for item in payload] + kept = [r for r in replies if r is not None] + return kept or None + return await self._one(payload) + + async def _one(self, message: Any) -> Any: + if not isinstance(message, dict) or "method" not in message: + # A response from the client (we send no requests) or junk. + return None + method, rid = message["method"], message.get("id") + if rid is None: + return None # a notification: nothing to answer + params = message.get("params") or {} + if method == "initialize": + return _result( + rid, + { + "protocolVersion": params.get( + "protocolVersion", PROTOCOL_VERSION + ), + "capabilities": {"tools": {"listChanged": False}}, + "serverInfo": {"name": SERVER_NAME, "version": "0"}, + }, + ) + if method == "ping": + return _result(rid, {}) + if method == "tools/list": + return _result( + rid, + { + "tools": [ + { + "name": t.name, + "description": (t.spec and t.spec.description) + or "", + "inputSchema": (t.spec and t.spec.params) + or {"type": "object"}, + } + for t in self._tools.values() + ] + }, + ) + if method == "tools/call": + name = str(params.get("name", "")) + if name not in self._tools: + return _error(rid, -32602, f"unknown tool: {name}") + arguments = params.get("arguments") or {} + text, is_error = await self._on_call(name, dict(arguments)) + return _result( + rid, + { + "content": [{"type": "text", "text": text}], + "isError": is_error, + }, + ) + return _error(rid, -32601, f"method not found: {method}") + + +def _result(rid: Any, result: Any) -> dict[str, Any]: + return {"jsonrpc": "2.0", "id": rid, "result": result} + + +def _error(rid: Any, code: int, message: str) -> dict[str, Any]: + return { + "jsonrpc": "2.0", + "id": rid, + "error": {"code": code, "message": message}, + } + + +async def _read_request( + reader: asyncio.StreamReader, +) -> tuple[str, bytes] | None: + """Read one HTTP/1.1 request. None when the client hung up.""" + try: + head = await reader.readuntil(b"\r\n\r\n") + except asyncio.IncompleteReadError: + return None + lines = head.decode("latin-1").split("\r\n") + method = lines[0].split(" ", 1)[0].upper() + headers = {} + for line in lines[1:]: + if ":" in line: + key, value = line.split(":", 1) + headers[key.strip().lower()] = value.strip() + if headers.get("transfer-encoding", "").lower() == "chunked": + body = b"" + while True: + size = int((await reader.readuntil(b"\r\n")).strip(), 16) + if size == 0: + await reader.readuntil(b"\r\n") + break + body += await reader.readexactly(size) + await reader.readexactly(2) + return method, body + length = int(headers.get("content-length", "0") or 0) + return method, await reader.readexactly(length) if length else b"" + + +async def _respond( + writer: asyncio.StreamWriter, status: int, payload: Any +) -> None: + reason = {200: "OK", 202: "Accepted", 405: "Method Not Allowed"}[status] + body = b"" if payload is None else json.dumps(payload).encode() + head = [f"HTTP/1.1 {status} {reason}", f"Content-Length: {len(body)}"] + if payload is not None: + head.append("Content-Type: application/json") + writer.write(("\r\n".join(head) + "\r\n\r\n").encode() + body) + await writer.drain() 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 new file mode 100644 index 00000000..0b57650e --- /dev/null +++ b/src/ai/workers/_errors.py @@ -0,0 +1,71 @@ +"""The errors a worker raises. + +Three cases have their own class, because a caller fixes them differently. +Everything else is a `WorkerError` with a message that says what happened. +""" + +from __future__ import annotations + +from .. import errors + + +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.""" + + def __init__(self, kind: str, executable: str, install: str) -> None: + super().__init__( + f"{kind} needs {executable!r}, which does not run here. " + f"Install it with: {install}" + ) + self.kind = kind + self.executable = executable + + +class NotAuthenticatedError(WorkerError): + """The CLI has no usable credentials.""" + + def __init__(self, kind: str, detail: str, hint: str) -> None: + super().__init__(f"{kind} is not authenticated: {detail}\n{hint}") + self.kind = kind + self.detail = detail + + +class TranscriptMismatchError(WorkerError): + """The messages given to `stream()` do not continue this conversation. + + A worker holds a conversation in its CLI. It can continue it, or begin a + new one from a history, but it cannot rewrite it. Use a new worker. + """ + + +# Phrases that mean "no usable credentials", collected from what the CLIs +# print. Narrow on purpose: a 403 is authorization, not authentication. +_AUTH_MARKERS = ( + "401", + "unauthorized", + "missing bearer", + "not logged in", + "invalid_api_key", + "invalid api key", + "authentication_error", + "failed to authenticate", + "no api key", + "please run /login", + "please run `codex login`", +) + + +def turn_failed(kind: str, detail: str, hint: str) -> WorkerError: + """Name a failed turn for what the caller has to fix.""" + detail = (detail or "unknown error")[:500] + if any(marker in detail.lower() for marker in _AUTH_MARKERS): + return NotAuthenticatedError(kind, detail, hint) + return WorkerError(f"{kind} turn failed: {detail}") 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/_worker.py b/src/ai/workers/_worker.py new file mode 100644 index 00000000..60cc22eb --- /dev/null +++ b/src/ai/workers/_worker.py @@ -0,0 +1,998 @@ +"""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 dataclasses +import json +import os +from collections.abc import AsyncGenerator, AsyncIterator, Sequence +from typing import Any, ClassVar, Literal, Self + +import pydantic +from pydantic import TypeAdapter + +from ..agents import hooks +from ..agents import runtime as runtime_ +from ..types import events as events_ +from ..types import messages as messages_ +from ..types import tools as tools_ +from ..types import usage as usage_ +from . import _adapter, _bridge +from . import _errors as errors + +Effort = Literal["low", "medium", "high", "max"] +BATCH_WINDOW = 0.05 +OUTPUT_RETRIES = 2 +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: + tool_call_id: str + name: str + arguments: dict[str, Any] + answer: asyncio.Future[tuple[str, bool]] + + +@dataclasses.dataclass +class _Failed: + error: BaseException + + +@dataclasses.dataclass +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) + prompt: _adapter.Prompt = dataclasses.field(default_factory=list) + transcript: list[messages_.Message] = dataclasses.field( + default_factory=list + ) + + +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: + bridge: _bridge.Bridge + queue: asyncio.Queue[Any] = dataclasses.field(default_factory=asyncio.Queue) + send_lock: asyncio.Lock = dataclasses.field(default_factory=asyncio.Lock) + in_session: bool = False + 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 + pending: dict[str, _Call] = dataclasses.field(default_factory=dict) + hidden: set[str] = dataclasses.field(default_factory=set) + 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 of ClaudeCode, Codex and Pi. One object represents one session. + + Dump and validate to resume a session. Use ``await worker.fork()`` to + create an independent native session; copying is not a fork. + """ + + 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) + 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]] = pydantic.Field( + default_factory=dict + ) + approve: bool = False # ToolApproval hooks, also available outside Agent. + session_id: str | None = None + messages: list[messages_.Message] = pydantic.Field(default_factory=list) + + _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) + name = cls.model_fields["worker_class_id"].default + if isinstance(name, str): + Worker._classes[name] = cls + + @pydantic.model_validator(mode="wrap") + @classmethod + def _of_class( + cls, data: Any, handler: pydantic.ValidatorFunctionWrapHandler + ) -> Any: + if cls is Worker and isinstance(data, dict): + 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: + # 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: + return self.__copy__() + + # 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 + + async def _cli_open( + self, + *, + 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") + + 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_name or "default" + + @property + def provider_name(self) -> str: + return self.worker_class_id + + @property + def version(self) -> str | None: + return self._cli_version + + @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 + + 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() + + 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" + ) + return self._runtime + + 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 + + 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" + ) + 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 + + 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): + 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): + async with asyncio.timeout(BATCH_WINDOW): + while True: + more = await rt.queue.get() + if isinstance(more, _Call): + calls.append(more) + else: + rt.queue.put_nowait(more) + break + for call in calls: + rt.pending[call.tool_call_id] = call + part = messages_.ToolCallPart( + tool_call_id=call.tool_call_id, + tool_name=call.name, + tool_args=json.dumps(call.arguments), + ) + yield out( + events_.ToolStart( + tool_call_id=part.tool_call_id, + tool_name=part.tool_name, + ) + ) + yield out( + events_.ToolDelta( + tool_call_id=part.tool_call_id, + chunk=part.tool_args, + ) + ) + yield out( + events_.ToolEnd( + tool_call_id=part.tool_call_id, tool_call=part + ) + ) + yield out( + events_.StreamEnd( + finish_reason="tool_call", + provider_metadata=self._metadata(None), + ) + ) + hydrator = None + continue + if isinstance(item, events_.StreamEnd): + finish = item.finish_reason + rt.hidden.clear() + yield out( + item.model_copy( + update={ + "finish_reason": "other" + if finish == "cancelled" + else finish, + "provider_metadata": { + **(item.provider_metadata or {}), + **self._metadata(finish), + }, + } + ) + ) + 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, + ): + if isinstance(event, events_.TextDelta): + answer.append(event.chunk) + continue + if isinstance(event, events_.BuiltinToolStart): + answer.clear() + yield projection.feed(event) + finally: + rt.stream_owner = None + rt.submission = None + rt.model_ready.set() + + def _plan(self, messages: list[messages_.Message]) -> _Plan: + known = [m.id for m in self.messages] + given = [m.id for m in messages] + plan = _Plan() + plan.instructions = ( + "\n\n".join(m.text for m in messages if m.role == "system") or None + ) + if 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( + "stored message content was changed" + if matched_ids + else f"{self.worker_class_id}: messages do not continue " + "this session; use a new worker" + ) + elif self.session_id is not None: + new_messages = list(messages) + else: + 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 = messages[cut:] + plan.transcript = list(messages[:cut]) + for message in new_messages: + if message.role == "tool": + plan.results.extend(message.tool_results) + elif message.role == "system": + plan.system.append(message.text) + elif message.role == "user": + plan.prompt.extend( + p + for p in message.parts + if isinstance(p, messages_.TextPart | messages_.FilePart) + ) + else: + raise errors.TranscriptMismatchError( + "only user, system and tool messages may follow " + "the last answer" + ) + plan.transcript.extend(new_messages) + return plan + + def _answer(self, results: list[messages_.ToolResultPart]) -> None: + rt = self._require_runtime() + for part in results: + call = rt.pending.pop(part.tool_call_id, None) + if call is None or call.answer.done(): + continue + value = part.model_input + if value is messages_.MODEL_INPUT_UNSET: + value = part.result + call.answer.set_result( + ( + value if isinstance(value, str) else _dump(value), + part.result_kind == "error", + ) + ) + for call in rt.pending.values(): + if not call.answer.done(): + call.answer.set_result(("no result was given", True)) + rt.pending.clear() + + async def _on_call( + self, name: str, arguments: dict[str, Any] + ) -> tuple[str, bool]: + rt = self._runtime + 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() + ) + rt.queue.put_nowait( + _Call(messages_.generate_id("call"), name, arguments, answer) + ) + return await answer + + async def _approve( + self, tool_call_id: str, tool_name: str, tool_input: dict[str, Any] + ) -> tuple[bool, str]: + if self._is_bridge_tool(tool_name): + return True, "" + rt = self._runtime + 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" + except asyncio.CancelledError: + 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: + rt = self._runtime + if rt is None: + return False + server = _bridge.SERVER_NAME + return tool_name == server or any( + tool_name + in (n, f"mcp__{server}__{n}", f"{server}_{n}", f"{server}__{n}") + for n in rt.bridge.names + ) + + def _visible(self, event: events_.Event) -> list[events_.Event]: + rt = self._require_runtime() + match event: + case events_.BuiltinToolStart(): + if self._is_bridge_tool(event.tool_name): + rt.hidden.add(event.tool_call_id) + return [] + case events_.BuiltinToolEnd(): + if event.tool_call_id in rt.hidden or self._is_bridge_tool( + event.tool_call.tool_name + ): + rt.hidden.add(event.tool_call_id) + return [] + case events_.BuiltinToolDelta() | events_.BuiltinToolResult(): + if event.tool_call_id in rt.hidden: + return [] + return [event] + + async def _output( + self, + text: str, + output_type: type[pydantic.BaseModel], + usage: usage_.Usage | None, + feed: AsyncIterator[SessionEvent], + ) -> tuple[str, usage_.Usage | None]: + parsed, error = _parse(text, output_type) + attempt = 0 + while error is not None and attempt < OUTPUT_RETRIES: + attempt += 1 + 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 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_.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] = {"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} + + +def _parse( + text: str, output_type: type[pydantic.BaseModel] +) -> tuple[pydantic.BaseModel | None, Exception | None]: + try: + return output_type.model_validate_json(_extract_json(text)), None + except Exception as exc: + return None, exc + + +def _extract_json(text: str) -> str: + candidate = text.strip() + if candidate.startswith("```"): + parts = candidate.split("```") + if len(parts) >= 2: + candidate = parts[1].removeprefix("json").strip() + try: + json.loads(candidate) + return candidate + except json.JSONDecodeError: + pass + for opener, closer in (("{", "}"), ("[", "]")): + start, end = candidate.find(opener), candidate.rfind(closer) + if 0 <= start < end: + sliced = candidate[start : end + 1] + try: + json.loads(sliced) + return sliced + except json.JSONDecodeError: + continue + return candidate + + +def _dump(value: Any) -> str: + if isinstance(value, pydantic.BaseModel): + return value.model_dump_json() + return json.dumps(value, default=str) 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/codex/jsonrpc.py b/src/ai/workers/codex/jsonrpc.py new file mode 100644 index 00000000..f5b0a8c1 --- /dev/null +++ b/src/ai/workers/codex/jsonrpc.py @@ -0,0 +1,294 @@ +"""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 +supplies the meaning. +""" + +from __future__ import annotations + +import asyncio +import contextlib +import json +import os +from collections.abc import Awaitable, Callable, Mapping, Sequence +from typing import Any + +from .. import _errors as errors + +# 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]] + + +class JsonRpcError(Exception): + def __init__(self, error: dict[str, Any]) -> None: + super().__init__(error.get("message") or json.dumps(error)) + self.code = error.get("code") + self.data = error.get("data") + + +class JsonRpcPeer: + def __init__(self, process: Process, *, kind: str) -> None: + self._process = process + self._kind = kind + self._next_id = 0 + self._waiters: dict[int, asyncio.Future[Any]] = {} + self._pump: asyncio.Task[None] | None = None + self._closed = False + self._on_crash: Callable[[BaseException], None] | None = None + # Server requests being answered. Each runs as its own task: an + # answer can take minutes (a person approving a tool call), and the + # reader must keep reading meanwhile. + self._requests: set[asyncio.Task[None]] = set() + self._answered: set[Any] = set() + + def start( + self, + on_notify: NotifyHandler, + on_request: RequestHandler, + on_crash: Callable[[BaseException], None] | None = None, + ) -> None: + # `on_crash` is for listeners. A turn waits on a stream of + # notifications, not on a future: when the process dies, failing + # the futures wakes nobody who was listening (measured: a SIGKILLed + # codex left the turn blocked until the test timed out). + self._on_crash = on_crash + self._pump = asyncio.create_task(self._read_loop(on_notify, on_request)) + + async def close(self) -> None: + self._closed = True + 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._requests): + task.cancel() + for task in list(self._requests): + with contextlib.suppress(asyncio.CancelledError, Exception): + await task + self._requests.clear() + # A close is not a crash: `on_crash` does not fire. + self._fail_pending( + errors.WorkerError(f"{self._kind}: connection closed"), + crashed=False, + ) + + def _fail_pending( + self, exc: BaseException, *, crashed: bool = True + ) -> None: + for future in list(self._waiters.values()): + if not future.done(): + future.set_exception(exc) + self._waiters.clear() + if crashed and self._on_crash is not None: + with contextlib.suppress(Exception): + self._on_crash(exc) + + async def call( + self, method: str, params: Any = None, *, timeout: float = 120 + ) -> Any: + if self._closed: + raise errors.WorkerError(f"{self._kind}: connection is closed") + self._next_id += 1 + request_id = self._next_id + future: asyncio.Future[Any] = asyncio.get_running_loop().create_future() + self._waiters[request_id] = future + await self._send( + { + "jsonrpc": "2.0", + "id": request_id, + "method": method, + **({"params": params} if params is not None else {}), + } + ) + try: + async with asyncio.timeout(timeout): + return await future + finally: + self._waiters.pop(request_id, None) + + async def notify(self, method: str, params: Any = None) -> None: + await self._send( + { + "jsonrpc": "2.0", + "method": method, + **({"params": params} if params is not None else {}), + } + ) + + async def respond(self, request_id: Any, result: Any) -> None: + self._answered.add(request_id) + await self._send({"jsonrpc": "2.0", "id": request_id, "result": result}) + + async def _answer( + self, + on_request: RequestHandler, + request_id: Any, + method: str, + params: dict[str, Any], + ) -> None: + """Run one request handler; never leave the server without a reply.""" + try: + await on_request(request_id, method, params) + except asyncio.CancelledError: + raise + except Exception as exc: + if request_id not in self._answered: + with contextlib.suppress(Exception): + await self._send( + { + "jsonrpc": "2.0", + "id": request_id, + "error": {"code": -32603, "message": str(exc)}, + } + ) + finally: + self._answered.discard(request_id) + + async def _send(self, message: dict[str, Any]) -> None: + try: + await self._process.write(json.dumps(message) + "\n") + except Exception as exc: + raise errors.WorkerError( + f"{self._kind}: could not write to the CLI: {exc}" + ) from exc + + async def _read_loop( + self, on_notify: NotifyHandler, on_request: RequestHandler + ) -> None: + try: + while True: + line = await self._process.readline() + if not line: + note = await self._process.death_note() + self._fail_pending( + errors.WorkerError(f"{self._kind} crashed: {note}") + ) + return + try: + message = json.loads(line) + except json.JSONDecodeError: + continue # a stray non-JSON line is noise + if not isinstance(message, dict): + continue + if "method" in message and "id" not in message: + # Inline, so notifications are handled in the order sent. + await on_notify( + message["method"], message.get("params") or {} + ) + elif "method" in message: + task = asyncio.create_task( + self._answer( + on_request, + message["id"], + message["method"], + message.get("params") or {}, + ) + ) + self._requests.add(task) + task.add_done_callback(self._requests.discard) + else: + self._resolve(message) + except asyncio.CancelledError: + raise + except Exception as exc: + self._fail_pending(errors.WorkerError(f"{self._kind}: {exc}")) + + def _resolve(self, message: dict[str, Any]) -> None: + msg_id = message.get("id") + future = ( + self._waiters.pop(msg_id, None) if isinstance(msg_id, int) else None + ) + if future is None or future.done(): + return + if "error" in message: + 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/codex/worker.py b/src/ai/workers/codex/worker.py new file mode 100644 index 00000000..eba362e2 --- /dev/null +++ b/src/ai/workers/codex/worker.py @@ -0,0 +1,746 @@ +"""Codex, driven through `codex app-server`. + +Chosen over `codex exec --json`, which cannot be controlled: one process per +turn, stdin unused, no approval channel. app-server has `turn/steer`, +`turn/interrupt` and `item/*/requestApproval`. + +The protocol shapes here were learned by running the server and reading what +it sent (see VERIFIED_VERSION), not from the schema alone. +""" + +from __future__ import annotations + +import asyncio +import base64 +import contextlib +import importlib.metadata +import json +import os +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 _adapter, _bridge, _convert, _handoff, _worker +from .. import _errors as errors +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" +# Put on the turn's queue when app-server dies. +CRASHED = "__crashed__" +LIST_PAGE_SIZE = 100 +# `list_sessions()` reads at most this many pages of threads. +LIST_PAGES = 50 + +APPROVAL_METHODS = ( + "item/commandExecution/requestApproval", + "item/fileChange/requestApproval", + "item/permissions/requestApproval", + "execCommandApproval", + "applyPatchApproval", +) + +# Item types that are the agent doing something, rather than speaking. +TOOL_ITEMS = ( + "fileChange", + "commandExecution", + "mcpToolCall", + "webSearch", + "toolCall", +) + +AUTH_HINT = ( + "codex uses your own login: run `codex login`, or pass " + "env={'OPENAI_API_KEY': ...}, or point it at another provider with " + "config={'model_provider': ..., 'model_providers..base_url': ...}." +) + + +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). + 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 _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, + ) + self._process = await jsonrpc.spawn( + [self._executable, "app-server", *_config_args(self._config)], + cwd=self._cwd, + env=self.env, + ) + self._peer = jsonrpc.JsonRpcPeer(self._process, kind=KIND) + self._peer.start( + self._on_notify, self._on_request, on_crash=self._on_crash + ) + try: + await self._peer.call( + "initialize", + { + "clientInfo": { + "name": "ai-python", + "title": "AI SDK for Python", + "version": importlib.metadata.version("ai"), + } + }, + timeout=60, + ) + await self._peer.notify("initialized") + except BaseException: + # A failed handshake must not leave the server running. + await self._cli_close() + raise + + async def _cli_close(self) -> None: + if self._peer is not None: + await self._peer.close() + self._peer = None + if self._process is not 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: + raise errors.WorkerError(f"{KIND}: app-server is not running") + return self._peer + + def _thread_params(self) -> dict[str, Any]: + """How the thread runs: on start, resume and fork alike. + + A resumed or forked thread otherwise keeps the policy it was created + with, like a person's TUI asking for approvals nobody here answers. + """ + return { + "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._approval_callback + else "never", + **({"model": self.model_name} if self.model_name else {}), + **( + {"developerInstructions": self._instructions} + if self._instructions + else {} + ), + } + + # -- 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 session_id is not None: + await self._require_here(session_id) + method = "thread/fork" if fork else "thread/resume" + try: + result = await self._rpc().call( + method, {"threadId": session_id, **self._thread_params()} + ) + except jsonrpc.JsonRpcError as exc: + raise errors.WorkerError( + f"{KIND}: cannot open thread {session_id}: {exc}" + ) from exc + thread = str((result or {}).get("thread", {}).get("id") or "") + self._thread = thread or session_id + return self._thread + result = await self._rpc().call( + "thread/start", {"cwd": self._cwd, **self._thread_params()} + ) + thread = str((result or {}).get("thread", {}).get("id") or "") + if not thread: + raise errors.WorkerError( + f"{KIND}: thread/start gave no id: {result}" + ) + self._thread = thread + if seed: + # The thread's model-visible history, before the first turn. + _handoff.warn_unsupported_files(seed, KIND) + await self._rpc().call( + "thread/inject_items", + {"threadId": thread, "items": handoff.to_codex_items(seed)}, + ) + return thread + + async def _require_here(self, session_id: str) -> dict[str, Any]: + """Refuse a thread that belongs to another directory. + + Codex's thread store is the whole machine's, so resuming a thread + from another project succeeds natively, and the agent would then + carry a transcript about files that are not here. + """ + try: + result = await self._rpc().call( + "thread/read", {"threadId": session_id} + ) + except jsonrpc.JsonRpcError as exc: + raise errors.WorkerError( + f"{KIND}: cannot read thread {session_id}: {exc}" + ) from exc + thread = (result or {}).get("thread") or {} + if not thread: + raise errors.WorkerError(f"{KIND}: no thread {session_id}") + cwd = thread.get("cwd") + if cwd is not None and cwd != self._cwd: + raise errors.WorkerError( + f"{KIND}: thread {session_id} belongs to {cwd}, not {self._cwd}" + ) + return thread + + # -- notifications and approvals ------------------------------------------ + + async def _on_notify(self, method: str, params: dict[str, Any]) -> None: + thread = params.get("threadId") or (params.get("thread") or {}).get( + "id" + ) + if thread != self._thread: + return + if method == "thread/tokenUsage/updated": + self._usage = _usage(params.get("tokenUsage") or {}) + if self._queue is not None: + self._queue.put_nowait((method, params)) + + def _on_crash(self, exc: BaseException) -> None: + if self._queue is not None: + self._queue.put_nowait((CRASHED, {"detail": str(exc)})) + self._peer = None + + async def _on_request( + self, request_id: Any, method: str, params: dict[str, Any] + ) -> 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._approval_callback( + str(params.get("itemId") or params.get("callId") or ""), + _approval_tool_name(method), + { + k: v + for k, v in params.items() + if k not in ("threadId", "turnId", "itemId") and v is not None + }, + ) + # The protocol has no field for a reason: codex only hears "declined". + await self._rpc().respond( + request_id, {"decision": "accept" if granted else "decline"} + ) + + # -- turns ---------------------------------------------------------------- + + 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() + self._queue = queue + self._interrupted = False + self._usage = usage_.Usage() + open_text: set[str] = set() + open_reasoning: set[str] = set() + started: set[str] = set() + # The last transport error codex reported while retrying: if the turn + # then fails without a message of its own, the only explanation. + last_error = "" + try: + try: + begun = await self._rpc().call( + "turn/start", + { + "threadId": self._thread, + "input": await _input_items(prompt), + }, + ) + except jsonrpc.JsonRpcError as exc: + raise errors.turn_failed(KIND, str(exc), AUTH_HINT) from exc + # 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: + method, params = await queue.get() + if method == CRASHED: + raise errors.WorkerError( + f"{KIND} crashed: {params.get('detail')}" + ) + # An interrupted turn's notifications can still arrive when + # the next one starts. Without this the new turn settled on + # the OLD turn's completion and came back empty. + other = params.get("turnId") or (params.get("turn") or {}).get( + "id" + ) + if turn and other and other != turn: + continue + if method == "item/agentMessage/delta": + item_id = params.get("itemId", "") + if item_id not in open_text: + open_text.add(item_id) + yield events_.TextStart(block_id=item_id) + yield events_.TextDelta( + chunk=params.get("delta", ""), block_id=item_id + ) + elif method in ( + "item/reasoning/textDelta", + "item/reasoning/summaryTextDelta", + ): + item_id = params.get("itemId", "") + if item_id not in open_reasoning: + open_reasoning.add(item_id) + yield events_.ReasoningStart(block_id=item_id) + yield events_.ReasoningDelta( + chunk=params.get("delta", ""), block_id=item_id + ) + elif method == "item/started": + item = params.get("item") or {} + if item.get("type") in TOOL_ITEMS: + started.add(item.get("id", "")) + yield events_.BuiltinToolStart( + tool_call_id=item.get("id", ""), + tool_name=_tool_name(item), + ) + elif method == "item/completed": + item = params.get("item") or {} + item_id = item.get("id", "") + kind = item.get("type") + if kind == "agentMessage" and item_id in open_text: + open_text.discard(item_id) + yield events_.TextEnd(block_id=item_id) + elif kind == "agentMessage" and item.get("text"): + # A message that was never streamed. + yield events_.TextStart(block_id=item_id) + yield events_.TextDelta( + chunk=item["text"], block_id=item_id + ) + yield events_.TextEnd(block_id=item_id) + elif kind == "reasoning" and item_id in open_reasoning: + open_reasoning.discard(item_id) + yield events_.ReasoningEnd(block_id=item_id) + elif kind in TOOL_ITEMS: + for event in _convert.builtin_call( + item_id, + _tool_name(item), + json.dumps(_tool_args(item)), + started=started, + ): + yield event + yield _convert.builtin_result( + item_id, + _tool_name(item), + _item_result(item), + is_error=item.get("status") == "failed", + ) + elif method == "turn/completed": + completed = params.get("turn") or {} + # A failed turn says so. Reported as a normal stop with + # empty text, "401 Unauthorized" became silence. + if ( + completed.get("status") == "failed" + and not self._interrupted + ): + raise errors.turn_failed( + KIND, + _error_message(completed) or last_error, + AUTH_HINT, + ) + yield events_.StreamEnd( + usage=self._usage, + finish_reason=( + "cancelled" if self._interrupted else "stop" + ), + ) + return + elif method == "turn/failed": + raise errors.turn_failed( + KIND, _error_message(params), AUTH_HINT + ) + elif method == "error": + last_error = _error_message(params) or last_error + finally: + self._queue = None + self._turn = None + + 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", + { + "threadId": self._thread, + # A precondition: steering the wrong turn is worse than + # failing to steer. + "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 _cli_interrupt(self) -> None: + self._interrupted = True + if not self._turn or self._peer is None: + return + with contextlib.suppress(Exception): + await self._peer.call( + "turn/interrupt", + {"threadId": self._thread, "turnId": self._turn}, + timeout=30, + ) + + # -- the store ------------------------------------------------------------ + + 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"}, + ) + out: list[messages_.Message] = [] + for turn in ((result or {}).get("thread") or {}).get("turns") or []: + for item in turn.get("items") or []: + out.extend(_item_to_messages(item)) + return out + + 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]] = [] + cursor: str | None = None + for _ in range(LIST_PAGES): + page = await self._rpc().call( + "thread/list", + { + "cwd": self._cwd, + "limit": LIST_PAGE_SIZE, + **({"cursor": cursor} if cursor else {}), + }, + ) + threads += (page or {}).get("data") or [] + cursor = (page or {}).get("nextCursor") + if not cursor: + break + return [ + _adapter.SessionInfo( + session_id=t.get("id", ""), + title=t.get("name") or t.get("preview") or None, + cwd=t.get("cwd"), + created_at=t.get("createdAt"), + updated_at=t.get("updatedAt"), + ) + for t in threads + if t.get("id") and t.get("cwd") in (None, self._cwd) + ] + + 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._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 + # "Update now / Skip" dialog that the first keystrokes answer. + argv = [ + self._executable, + *(["resume", session_id] if session_id else []), + "--disable", + "in_app_updates", + *_config_args(config), + ] + 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 + + +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. + """ + items: list[dict[str, Any]] = [] + for part in prompt: + if isinstance(part, messages_.TextPart): + items.append({"type": "text", "text": part.text}) + elif part.media_type.startswith("text/"): + items.append({"type": "text", "text": await _convert.as_text(part)}) + else: + encoded = base64.b64encode(await _convert.data(part)).decode( + "ascii" + ) + items.append( + { + "type": "image", + "url": f"data:{part.media_type};base64,{encoded}", + } + ) + return items + + +def _tool_name(item: dict[str, Any]) -> str: + # Never the command line: that made every shell call a differently named + # tool. The command is in the arguments (`_tool_args`). + return ( + item.get("toolName") or item.get("server") or item.get("type") or "tool" + ) + + +def _approval_tool_name(method: str) -> str: + """Return the native tool kind an approval is about, never its args.""" + if "commandExecution" in method or "execCommand" in method: + return "commandExecution" + if "fileChange" in method or "applyPatch" in method: + return "fileChange" + return method.rsplit("/", 1)[-1] + + +def _tool_args(item: dict[str, Any]) -> dict[str, Any]: + return { + k: v + for k, v in item.items() + if k in ("command", "changes", "arguments", "query", "path", "cwd") + } + + +def _item_result(item: dict[str, Any]) -> Any: + """Return what a tool item produced, under whichever name codex uses. + + A command's output is `aggregatedOutput` (codex 0.160; reading only + `output` made every command result None), a file change's `changes`, an + MCP call's `result`. + """ + for key in ("aggregatedOutput", "output", "changes", "result"): + if item.get(key) is not None: + return item[key] + return None + + +def _reasoning_text(item: dict[str, Any]) -> str: + """Codex reports reasoning as text, or as a LIST of summary parts.""" + text = item.get("text") + if isinstance(text, str) and text: + return text + summary = item.get("summary") + if isinstance(summary, str): + return summary + if isinstance(summary, list): + return "".join(part for part in summary if isinstance(part, str)) + return "" + + +def _item_to_messages(item: dict[str, Any]) -> list[messages_.Message]: + """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. + text = item.get("text") + files: list[messages_.Part] = [] + if not isinstance(text, str): + blocks = [ + b for b in item.get("content") or [] if isinstance(b, dict) + ] + text = "".join(b.get("text", "") for b in blocks) + for block in blocks: + url = block.get("url") + if block.get("type") == "image" and isinstance(url, str): + files.append(messages_.FilePart.from_url(url)) + return [ + messages_.Message( + role="user", parts=[messages_.TextPart(text=text), *files] + ) + ] + if kind == "agentMessage" and item.get("text"): + return [ + messages_.Message( + role="assistant", parts=[messages_.TextPart(text=item["text"])] + ) + ] + if kind == "reasoning" and _reasoning_text(item): + return [ + messages_.Message( + role="assistant", + parts=[messages_.ReasoningPart(text=_reasoning_text(item))], + ) + ] + if kind in TOOL_ITEMS: + call = messages_.BuiltinToolCallPart( + tool_call_id=item.get("id", ""), + tool_name=_tool_name(item), + tool_args=json.dumps(_tool_args(item)), + ) + result = messages_.BuiltinToolReturnPart( + tool_call_id=call.tool_call_id, + tool_name=call.tool_name, + result=_item_result(item), + is_error=item.get("status") == "failed", + ) + return [messages_.Message(role="assistant", parts=[call, result])] + return [] + + +def _usage(raw: dict[str, Any]) -> usage_.Usage: + totals = raw.get("lastTurn") or raw.get("total") or raw + + def count(*names: str) -> int: + for name in names: + value = totals.get(name) + if isinstance(value, int): + return value + return 0 + + return usage_.Usage( + input_tokens=count("inputTokens", "input_tokens"), + output_tokens=count("outputTokens", "output_tokens"), + cache_read_tokens=count("cachedInputTokens", "cached_input_tokens"), + reasoning_tokens=count( + "reasoningOutputTokens", "reasoning_output_tokens" + ), + raw={"codex": raw}, + ) + + +def _error_message(payload: dict[str, Any]) -> str: + error = payload.get("error") + if isinstance(error, dict): + detail = error.get("additionalDetails") or "" + message = str(error.get("message") or "") + return f"{message} {detail}".strip() + return str(error or "") + + +def mcp_config(servers: dict[str, Any]) -> dict[str, Any]: + """MCP servers, in the shape claude takes, as codex `-c` overrides. + + `{"name": {"command": ..., "args": [...], "env": {...}}}` for a local + server, `{"name": {"url": ...}}` for a remote one. + """ + out: dict[str, Any] = {} + for name, server in servers.items(): + prefix = f"mcp_servers.{name}" + for key in ("command", "args", "url"): + if server.get(key) is not None: + out[f"{prefix}.{key}"] = server[key] + for var, value in (server.get("env") or {}).items(): + out[f"{prefix}.env.{var}"] = value + return out + + +def _config_args(config: dict[str, Any]) -> list[str]: + """`-c key=value` pairs, the values as TOML. + + JSON string, number and bool literals are valid TOML. + """ + args: list[str] = [] + for key, value in config.items(): + args += ["-c", f"{key}={json.dumps(value)}"] + return args 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/models/core/test_api.py b/tests/models/core/test_api.py index 67925265..7eccd056 100644 --- a/tests/models/core/test_api.py +++ b/tests/models/core/test_api.py @@ -67,6 +67,7 @@ def test_context_json_roundtrip_includes_model() -> None: restored = ai.Context.model_validate_json(context.model_dump_json()) + assert isinstance(restored.model, ai.Model) assert restored.model.id == "anthropic/claude-sonnet-4.6" assert isinstance(restored.model.provider, ai.providers.GatewayProvider) diff --git a/tests/models/core/test_model.py b/tests/models/core/test_model.py new file mode 100644 index 00000000..8281de75 --- /dev/null +++ b/tests/models/core/test_model.py @@ -0,0 +1,77 @@ +"""`ai.ModelLike`: anything with a model's `stream` goes where a model goes.""" + +from __future__ import annotations + +from collections.abc import AsyncGenerator, Sequence +from typing import Any + +import pydantic + +import ai +from ai.types import events +from ai.types import messages as m +from ai.types import tools as tools_ + + +class Echo: + """Not an `ai.Model`: it answers with the last user message's text.""" + + def __init__(self) -> None: + self.calls: list[list[m.Message]] = [] + + @property + def id(self) -> str: + return "echo" + + @property + def provider_name(self) -> str: + return "echo" + + async def stream( + self, + messages: list[m.Message], + *, + tools: Sequence[tools_.Tool] | None = None, + output_type: type[pydantic.BaseModel] | None = None, + params: Any = None, + ) -> AsyncGenerator[events.Event]: + self.calls.append(list(messages)) + text = next(x.text for x in reversed(messages) if x.role == "user") + yield events.StreamStart() + yield events.TextStart(block_id="t") + yield events.TextDelta(chunk=text, block_id="t") + yield events.TextEnd(block_id="t") + yield events.StreamEnd(finish_reason="stop") + + +def test_a_model_and_a_stand_in_are_model_like() -> None: + assert isinstance(Echo(), ai.ModelLike) + assert isinstance(ai.get_model("openai/gpt-5"), ai.ModelLike) + + +async def test_stream_takes_a_model_like() -> None: + async with ai.stream(Echo(), [ai.user_message("hello")]) as s: + async for _ in s: + pass + assert s.text == "hello" + + +async def test_generate_takes_a_model_like() -> None: + message = await ai.experimental_generate(Echo(), [ai.user_message("hi")]) + assert message.text == "hi" + + +async def test_an_agent_runs_on_a_model_like() -> None: + model = Echo() + async with ai.Agent().run(model, [ai.user_message("ping")]) as run: + async for _ in run: + pass + assert [x.role for x in run.messages] == ["user", "assistant"] + assert run.messages[-1].text == "ping" + assert len(model.calls) == 1 + + +def test_a_context_keeps_a_model_like_as_it_is() -> None: + model = Echo() + context = ai.Context(model=model, messages=[], tools=[]) + assert context.model is model diff --git a/tests/workers/__init__.py b/tests/workers/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/tests/workers/claude_code/__init__.py b/tests/workers/claude_code/__init__.py new file mode 100644 index 00000000..e69de29b 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/codex/__init__.py b/tests/workers/codex/__init__.py new file mode 100644 index 00000000..e69de29b 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/codex/test_jsonrpc.py b/tests/workers/codex/test_jsonrpc.py new file mode 100644 index 00000000..23deb002 --- /dev/null +++ b/tests/workers/codex/test_jsonrpc.py @@ -0,0 +1,161 @@ +"""The JSON-RPC peer codex is driven over, offline.""" + +from __future__ import annotations + +import asyncio +import time +from typing import Any, cast + +import pytest + +from ai import workers +from ai.workers.codex import jsonrpc + +from .. import fakes + + +def _peer( + process: fakes.FakeProcess, + on_request: Any = None, + on_notify: Any = None, +) -> jsonrpc.JsonRpcPeer: + async def no_notify(method: str, params: dict[str, Any]) -> None: + pass + + async def no_request( + request_id: Any, method: str, params: dict[str, Any] + ) -> None: + pass + + peer = jsonrpc.JsonRpcPeer(cast("Any", process), kind="test") + peer.start(on_notify or no_notify, on_request or no_request) + return peer + + +async def test_a_call_gets_its_answer() -> None: + process = fakes.FakeProcess(lambda message: {"echo": message["method"]}) + peer = _peer(process) + assert await peer.call("ping", timeout=1) == {"echo": "ping"} + await peer.close() + + +async def test_a_call_made_while_answering_a_request_is_answered() -> None: + """Answering a server request must not stop the peer reading.""" + process = fakes.FakeProcess() + took: list[float] = [] + done = asyncio.Event() + peer: jsonrpc.JsonRpcPeer + + async def on_request( + request_id: Any, method: str, params: dict[str, Any] + ) -> None: + started = time.monotonic() + await peer.respond(request_id, {"decision": "decline"}) + await peer.call("turn/interrupt", {}, timeout=2) + took.append(time.monotonic() - started) + done.set() + + peer = _peer(process, on_request=on_request) + process.server_says({"id": 99, "method": "approval", "params": {}}) + await asyncio.wait_for(done.wait(), 3) + assert took[0] < 0.5 + await peer.close() + + +async def test_notifications_flow_while_a_request_is_pending() -> None: + """A slow answer (a person approving) does not freeze the stream.""" + process = fakes.FakeProcess() + release = asyncio.Event() + seen: list[str] = [] + + async def on_request( + request_id: Any, method: str, params: dict[str, Any] + ) -> None: + await release.wait() + + async def on_notify(method: str, params: dict[str, Any]) -> None: + seen.append(method) + + peer = _peer(process, on_request=on_request, on_notify=on_notify) + process.server_says({"id": 1, "method": "approval", "params": {}}) + process.server_says({"method": "item/agentMessage/delta", "params": {}}) + assert await peer.call("thread/read", timeout=1) == {} + for _ in range(50): + if seen: + break + await asyncio.sleep(0.01) + assert seen == ["item/agentMessage/delta"] + release.set() + await peer.close() + + +async def test_notifications_keep_their_order() -> None: + process = fakes.FakeProcess() + seen: list[int] = [] + + async def on_notify(method: str, params: dict[str, Any]) -> None: + await asyncio.sleep(0) + seen.append(params["n"]) + + peer = _peer(process, on_notify=on_notify) + for n in range(20): + process.server_says({"method": "n", "params": {"n": n}}) + await peer.call("ping", timeout=1) + assert seen == list(range(20)) + await peer.close() + + +async def test_close_cancels_requests_still_being_answered() -> None: + process = fakes.FakeProcess() + cancelled = asyncio.Event() + started = asyncio.Event() + + async def on_request( + request_id: Any, method: str, params: dict[str, Any] + ) -> None: + started.set() + try: + await asyncio.Event().wait() + except asyncio.CancelledError: + cancelled.set() + raise + + peer = _peer(process, on_request=on_request) + process.server_says({"id": 1, "method": "approval", "params": {}}) + await asyncio.wait_for(started.wait(), 1) + await peer.close() + assert cancelled.is_set() + + +async def test_a_failing_request_handler_does_not_kill_the_peer() -> None: + process = fakes.FakeProcess() + + async def on_request( + request_id: Any, method: str, params: dict[str, Any] + ) -> None: + raise ValueError("bug in the handler") + + peer = _peer(process, on_request=on_request) + process.server_says({"id": 1, "method": "approval", "params": {}}) + assert await peer.call("ping", timeout=1) == {} + await peer.close() + with pytest.raises(workers.WorkerError): + await peer.call("ping", timeout=1) + + +async def test_a_dead_process_fails_its_callers() -> None: + process = fakes.FakeProcess(lambda message: None) # never answers + crashed: list[BaseException] = [] + peer = jsonrpc.JsonRpcPeer(cast("Any", process), kind="test") + + async def nothing(*args: Any) -> None: + pass + + peer.start(nothing, nothing, on_crash=crashed.append) + call = asyncio.ensure_future(peer.call("ping", timeout=2)) + await asyncio.sleep(0) + await process.terminate() # EOF + with pytest.raises(workers.WorkerError, match="crashed"): + await call + assert len(crashed) == 1 + await peer.close() diff --git a/tests/workers/fakes.py b/tests/workers/fakes.py new file mode 100644 index 00000000..6196bd89 --- /dev/null +++ b/tests/workers/fakes.py @@ -0,0 +1,297 @@ +"""Test doubles for workers: a scripted adapter and an in-memory process.""" + +from __future__ import annotations + +import asyncio +import dataclasses +import json +import sys +from collections.abc import AsyncIterator, Awaitable, Callable, Iterable +from typing import Any, Literal + +import pydantic + +from ai import workers +from ai.types import events +from ai.types import messages as m +from ai.types import usage as usage_ +from ai.workers import _adapter, _convert + + +@dataclasses.dataclass +class Pause: + """Wait here until the turn is interrupted (or cancelled).""" + + +@dataclasses.dataclass +class Run: + """Await a coroutine here, mid-turn: a bridge call, say.""" + + fn: Callable[[], Awaitable[None]] + + +@dataclasses.dataclass +class Ask: + """Ask the worker to approve one of the CLI's own tool calls.""" + + tool_call_id: str + tool_name: str + tool_input: dict[str, Any] = dataclasses.field(default_factory=dict) + + +Step = events.Event | Pause | Run | Ask +Script = Callable[[str], Iterable[Step]] + + +def text(chunk: str, block: str = "t") -> list[Step]: + return [ + events.TextStart(block_id=block), + events.TextDelta(chunk=chunk, block_id=block), + events.TextEnd(block_id=block), + ] + + +def tool( + call_id: str, name: str, args: str = "{}", result: Any = "ok" +) -> list[Step]: + """One of the CLI's own tool calls, start to result.""" + return [ + *_convert.builtin_call(call_id, name, args, started=set()), + _convert.builtin_result(call_id, name, result, is_error=False), + ] + + +def reply(prompt: str) -> list[Step]: + """Echo the prompt back.""" + return text(prompt) + + +class FakeAdapter: + def __init__( + self, script: Script, approve: _adapter.Approve | None + ) -> None: + self.script = script + self.approve = approve + self.version: str | None = None + self.opens: list[dict[str, Any]] = [] + self.turns: list[str] = [] + self.steers: list[str] = [] + self.interrupts = 0 + self.answers: list[tuple[bool, str]] = [] + 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" + + async def close(self) -> None: + self.closed = True + + async def open( + self, + *, + session_id: str | None, + fork: bool, + seed: list[m.Message] | None, + instructions: str | None, + ) -> str: + self.opens.append( + { + "session_id": session_id, + "fork": fork, + "seed": seed, + "instructions": instructions, + } + ) + if fork: + 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() + 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), + ) + 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 [ + message.model_copy(deep=True) + for message in self.stored.get(session_id, []) + ] + + async def list_sessions(self) -> list[_adapter.SessionInfo]: + return [_adapter.SessionInfo(session_id="s1", title="first")] + + @staticmethod + def tui_command( + session_id: str | None, + ) -> tuple[list[str], dict[str, str], str | None]: + return ( + [sys.executable, "-c", "pass"], + {"FAKE_TUI": "1"}, + session_id or "minted", + ) + + +class FakeWorker(workers.Worker): + """A worker whose CLI is a `FakeAdapter`, run by a script.""" + + 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 + ) + + 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 + # 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) + + @property + def servers(self) -> dict[str, dict[str, Any]]: + return self._servers + + def script(self, script: Script) -> None: + self._script = script + + @property + def fake(self) -> FakeAdapter: + assert self._fake is not None + return self._fake + + +class FakeProcess: + """In-memory duplex stdio, for the JSON-RPC peer and the adapters. + + `answer(message)` is called for every message the client writes. For a + request, a non-None return is sent back as its result. `server_says()` + pushes a line from the "server": a notification or a request. + """ + + def __init__( + self, answer: Callable[[dict[str, Any]], Any] | None = None + ) -> None: + self._lines: asyncio.Queue[str] = asyncio.Queue() + self.answer = answer or (lambda message: {}) + self.written: list[dict[str, Any]] = [] + + def server_says(self, message: dict[str, Any]) -> None: + self._lines.put_nowait(json.dumps(message) + "\n") + + async def write(self, data: str) -> None: + message = json.loads(data) + self.written.append(message) + result = self.answer(message) + if "method" in message and "id" in message and result is not None: + self.server_says({"id": message["id"], "result": result}) + + async def readline(self) -> str: + return await self._lines.get() + + async def read_stderr(self) -> str: + return "" + + async def wait(self) -> int: + return 0 + + async def terminate(self) -> None: + self._lines.put_nowait("") + + async def death_note(self) -> str: + return "exit code 0; no stderr" 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/test_handoff.py b/tests/workers/test_handoff.py new file mode 100644 index 00000000..8746525d --- /dev/null +++ b/tests/workers/test_handoff.py @@ -0,0 +1,232 @@ +"""The seeding rule, pinned without a CLI. + +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). 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 + +import json + +from ai.types.messages import ( + BuiltinToolCallPart, + BuiltinToolReturnPart, + Message, + ReasoningPart, + TextPart, + ToolCallPart, + ToolResultPart, +) +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 + +# 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", + parts=[ + ReasoningPart(text="The user wants a file; Write is the tool."), + TextPart(text="Creating it."), + ToolCallPart( + tool_call_id="call_1", + tool_name="Write", + tool_args=json.dumps( + {"file_path": "/w/recipe.txt", "content": "two eggs"} + ), + ), + ], + ), + Message( + role="tool", + parts=[ + ToolResultPart( + tool_call_id="call_1", + tool_name="Write", + result={"ok": True}, + result_kind="json", + ) + ], + ), + Message(role="assistant", parts=[TextPart(text="Done.")]), +] + +# The same conversation, Write as a tool the CLI ran: built-in parts. +CLI_TOOL = [ + AGENT_TOOL[0], + Message( + role="assistant", + parts=[ + ReasoningPart(text="The user wants a file; Write is the tool."), + TextPart(text="Creating it."), + BuiltinToolCallPart( + tool_call_id="call_1", + tool_name="Write", + tool_args=json.dumps( + {"file_path": "/w/recipe.txt", "content": "two eggs"} + ), + ), + BuiltinToolReturnPart( + tool_call_id="call_1", tool_name="Write", result={"ok": True} + ), + ], + ), + AGENT_TOOL[3], +] + + +def test_codex_items_follow_the_rule() -> None: + items = codex_handoff.to_codex_items(AGENT_TOOL) + kinds = [(i["type"], i.get("role")) for i in items] + assert kinds == [ + ("message", "user"), + ("message", "assistant"), # "Creating it." + ("function_call", None), # Write, name untouched + ("message", "user"), # the reasoning note, after its turn + ("function_call_output", None), + ("message", "assistant"), # "Done." + ] + call = items[2] + assert call["name"] == "Write" + assert json.loads(call["arguments"])["content"] == "two eggs" + assert call["call_id"] == "call_1" + out = items[4] + assert out["call_id"] == "call_1" + assert out["output"] == json.dumps({"ok": True}) + note = items[3]["content"][0]["text"] + assert note.startswith(codex_handoff.NOTE_PREFIX) + assert "Write is the tool" in note + + +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 = 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] == [ + "user", + "assistant", + "user", + "assistant", + ] + assistant = recs[1]["message"]["content"] + assert [b["type"] for b in assistant] == ["text", "tool_use"] + assert assistant[1]["name"] == "Write" + assert assistant[1]["input"]["content"] == "two eggs" + assert assistant[1]["id"] == "call_1" + result = recs[2]["message"]["content"][0] + assert result["type"] == "tool_result" + assert result["tool_use_id"] == "call_1" + 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( + recs[i]["parentUuid"] == recs[i - 1]["uuid"] + for i in range(1, len(recs)) + ) + assert all(r["sessionId"] == "sid-1" and r["cwd"] == "/w" for r in recs) + + +def test_pi_merges_assistant_messages_and_keeps_tool_results() -> None: + rendered = pi_handoff.to_pi_messages( + [ + Message(role="user", parts=[TextPart(text="hi")]), + Message(role="assistant", parts=[TextPart(text="one")]), + Message( + role="assistant", + parts=[ + BuiltinToolCallPart( + tool_call_id="c1", tool_name="Bash", tool_args="{}" + ), + BuiltinToolReturnPart( + tool_call_id="c1", + tool_name="Bash", + result={"ok": True}, + is_error=True, + ), + ], + ), + ], + timestamp=1, + ) + assert [r["role"] for r in rendered] == ["user", "assistant", "toolResult"] + assert [b["type"] for b in rendered[1]["content"]] == ["text", "toolCall"] + assert rendered[1]["stopReason"] == "toolUse" + assert rendered[2]["content"] == [{"type": "text", "text": '{"ok": true}'}] + assert rendered[2]["isError"] is True + + +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=[ + BuiltinToolCallPart(tool_call_id="c", tool_name="Read"), + BuiltinToolReturnPart( + tool_call_id="c", tool_name="Read", result="x" + ), + TextPart(text="It says x."), + ], + ) + 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", + "toolResult", + "assistant", + ] + 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 = codex_handoff.to_codex_items(AGENT_TOOL) + assert not any(i["type"] == "reasoning" for i in items) + blocks = [ + b + for r in claude_handoff.to_claude_records(AGENT_TOOL, "s", "/w") + if isinstance(r["message"]["content"], list) + for b in r["message"]["content"] + ] + assert not any(b["type"] == "thinking" for b in blocks) + + +def test_empty_parts_produce_nothing() -> None: + blank = [Message(role="assistant", parts=[TextPart(text=" ")])] + assert codex_handoff.to_codex_items(blank) == [] + empty = [Message(role="assistant", parts=[ReasoningPart(text="")])] + 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 new file mode 100644 index 00000000..70409e71 --- /dev/null +++ b/tests/workers/test_worker.py @@ -0,0 +1,1257 @@ +"""`ai.workers.Worker` over a scripted adapter: no real CLI runs here.""" + +from __future__ import annotations + +import asyncio +import contextlib +import json +from collections.abc import AsyncIterator, Iterator +from typing import Any + +import pydantic +import pytest + +import ai +from ai import workers +from ai.types import events +from ai.types import messages as m +from ai.workers import _adapter, _bridge + +from . import fakes + + +@pytest.fixture +def worker() -> fakes.FakeWorker: + return fakes.FakeWorker() + + +async def post(url: str, payload: Any) -> Any: + """POST JSON the way an MCP client does, over a raw socket.""" + host, rest = url.removeprefix("http://").split(":", 1) + port, path = rest.split("/", 1) + reader, writer = await asyncio.open_connection(host, int(port)) + body = json.dumps(payload).encode() + writer.write( + ( + f"POST /{path} HTTP/1.1\r\nHost: {host}\r\n" + f"Content-Type: application/json\r\n" + f"Content-Length: {len(body)}\r\n\r\n" + ).encode() + + body + ) + await writer.drain() + head = await reader.readuntil(b"\r\n\r\n") + length = 0 + for line in head.decode().split("\r\n"): + if line.lower().startswith("content-length:"): + length = int(line.split(":")[1]) + data = await reader.readexactly(length) if length else b"" + writer.close() + return json.loads(data) if data else None + + +async def collect(stream: Any) -> list[Any]: + return [event async for event in stream] + + +# -- the model protocol ------------------------------------------------------- + + +async def test_a_worker_is_model_like(worker: fakes.FakeWorker) -> None: + assert isinstance(worker, ai.ModelLike) + assert worker.provider_name == "fake" + assert worker.id == "default" + async with worker: + assert worker.version == "fake 1.0" + async with ai.stream(worker, [ai.user_message("hello")]) as s: + seen = await collect(s) + assert isinstance(seen[0], events.StreamStart) + assert isinstance(seen[-1], events.StreamEnd) + assert seen[-1].finish_reason == "stop" + assert s.text == "hello" + assert s.message.usage is not None and s.message.usage.input_tokens == 3 + meta = seen[-1].provider_metadata + assert meta is not None and meta["worker"]["session_id"] == "s1" + + +async def test_generate_drains_the_stream(worker: fakes.FakeWorker) -> None: + async with worker: + message = await ai.experimental_generate( + worker, [ai.user_message("hi")] + ) + assert message.text == "hi" + + +async def test_cli_tools_are_builtin(worker: fakes.FakeWorker) -> None: + worker.script( + lambda prompt: [ + *fakes.tool("c1", "Bash", '{"command": "ls"}', "a.py"), + *fakes.text("done"), + ] + ) + async with worker: + async with ai.stream(worker, [ai.user_message("go")]) as s: + kinds = [type(e).__name__ for e in await collect(s)] + assert "BuiltinToolStart" in kinds + assert "BuiltinToolResult" in kinds + assert "ToolStart" not in kinds + assert s.tool_calls == [] # nothing for an ai.Agent to run + call, result = s.message.parts[0], s.message.parts[1] + assert isinstance(call, m.BuiltinToolCallPart) + assert call.tool_name == "Bash" + assert call.tool_args == '{"command": "ls"}' + assert isinstance(result, m.BuiltinToolReturnPart) + assert result.result == "a.py" + + +async def test_a_cancelled_turn_ends_as_other(worker: fakes.FakeWorker) -> None: + worker.script(lambda prompt: [*fakes.text("a"), fakes.Pause()]) + async with worker: + stream = worker.stream([ai.user_message("go")]) + seen = [] + async for event in stream: + seen.append(event) + if isinstance(event, events.TextEnd): + await worker.interrupt() + end = seen[-1] + assert isinstance(end, events.StreamEnd) + assert end.finish_reason == "other" + assert end.provider_metadata is not None + assert end.provider_metadata["worker"]["finish_reason"] == "cancelled" + + +# -- the conversation --------------------------------------------------------- + + +async def test_only_new_turns_reach_the_cli(worker: fakes.FakeWorker) -> None: + async with worker: + first = await ai.experimental_generate(worker, [ai.user_message("one")]) + assert worker.messages[-1].id == first.id + await ai.experimental_generate( + worker, [*worker.messages, ai.user_message("two")] + ) + assert worker.fake.turns == ["one", "two"] + assert len(worker.fake.opens) == 1 + assert [x.role for x in worker.messages] == [ + "user", + "assistant", + "user", + "assistant", + ] + + +async def test_a_new_worker_is_seeded_with_the_past( + worker: fakes.FakeWorker, +) -> None: + past = [ + ai.system_message("Be terse."), + ai.user_message("earlier"), + m.Message(role="assistant", parts=[m.TextPart(text="answer")]), + ] + async with worker: + await ai.experimental_generate(worker, [*past, ai.user_message("now")]) + opened = worker.fake.opens[0] + assert worker.fake.turns == ["now"] + # The system message is the CLI's instructions, not part of the seed. + assert opened["instructions"] == "Be terse." + assert [x.id for x in opened["seed"]] == [x.id for x in past[1:]] + assert opened["session_id"] is None + + +async def test_a_later_system_message_joins_the_prompt( + worker: fakes.FakeWorker, +) -> None: + async with worker: + await ai.experimental_generate(worker, [ai.user_message("one")]) + await ai.experimental_generate( + worker, + [ + *worker.messages, + ai.system_message("Now in French."), + ai.user_message("two"), + ], + ) + assert worker.fake.turns[1] == "Now in French.\n\n\n\ntwo" + + +async def test_a_rewritten_past_is_refused(worker: fakes.FakeWorker) -> None: + async with worker: + await ai.experimental_generate(worker, [ai.user_message("one")]) + with pytest.raises(workers.TranscriptMismatchError): + await ai.experimental_generate(worker, [ai.user_message("other")]) + + +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) + message = ai.user_message("one") + async with worker: + with pytest.raises(RuntimeError, match="boom"): + 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) + 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( + worker: fakes.FakeWorker, +) -> None: + worker.script(lambda prompt: [*fakes.text("a"), fakes.Pause()]) + async with worker: + async with ai.stream(worker, [ai.user_message("go")]) as s: + async for event in s: + if isinstance(event, events.TextDelta): + break + assert worker.fake.interrupts == 1 + + +async def test_structured_output(worker: fakes.FakeWorker) -> None: + class Finding(pydantic.BaseModel): + file: str + line: int + + worker.script( + lambda prompt: [ + *fakes.text("Let me look."), + *fakes.tool("c1", "Read"), + *fakes.text('```json\n{"file": "a.py", "line": 3}\n```', block="x"), + ] + ) + async with worker: + async with ai.stream( + worker, [ai.user_message("scan")], output_type=Finding + ) as s: + await collect(s) + assert "JSON value matching this schema" in worker.fake.turns[0] + assert s.output == Finding(file="a.py", line=3) + + +async def test_structured_output_asks_again(worker: fakes.FakeWorker) -> None: + class Count(pydantic.BaseModel): + n: int + + worker.script( + lambda prompt: fakes.text( + '{"n": 2}' if "failed validation" in prompt else "two" + ) + ) + async with worker: + async with ai.stream( + worker, [ai.user_message("how many?")], output_type=Count + ) as s: + await collect(s) + assert len(worker.fake.turns) == 2 + assert s.output == Count(n=2) + + +# -- a worker is data --------------------------------------------------------- + + +async def test_a_dumped_worker_continues_its_conversation( + worker: fakes.FakeWorker, +) -> None: + async with worker: + await ai.experimental_generate(worker, [ai.user_message("one")]) + data = json.loads(worker.model_dump_json()) + assert data["session_id"] == "s1" + again = workers.Worker.model_validate(data) + assert isinstance(again, fakes.FakeWorker) + assert [x.id for x in again.messages] == [x.id for x in worker.messages] + async with again: + await ai.experimental_generate( + again, [*again.messages, ai.user_message("two")] + ) + assert again.fake.opens[0]["session_id"] == "s1" # resumed + assert again.fake.turns == ["two"] + + +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: + worker = fakes.FakeWorker(session_id="old") + async with worker: + # The CLI holds the past: what is given is all new. + await ai.experimental_generate(worker, [ai.user_message("go on")]) + assert worker.fake.opens[0]["session_id"] == "old" + assert worker.fake.opens[0]["seed"] is None + assert worker.fake.turns == ["go on"] + assert worker.session_id == "old" + + +async def test_sync_reads_the_stored_past() -> None: + worker = fakes.FakeWorker(session_id="old") + stored = [ + ai.user_message("earlier"), + m.Message(role="assistant", parts=[m.TextPart(text="answer")]), + ] + async with worker: + worker.fake.stored["old"] = stored + 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_fork_branches_natively(worker: fakes.FakeWorker) -> None: + async with worker: + await ai.experimental_generate(worker, [ai.user_message("one")]) + branch = await worker.fork() + async with branch: + 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 == [ + { + "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 + + +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"]["worker_class_id"] == "fake" + restored = ai.Context.model_validate(data) + assert isinstance(restored.model, fakes.FakeWorker) + + +async def test_close_keeps_the_fields(worker: fakes.FakeWorker) -> None: + async with worker: + await ai.experimental_generate(worker, [ai.user_message("one")]) + fake = worker.fake + assert fake.closed + assert worker.session_id == "s1" + async with worker: # opens again, and resumes + await ai.experimental_generate( + worker, [*worker.messages, ai.user_message("two")] + ) + 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 --------------------------------------- + + +async def test_agent_tools_run_in_the_agent(worker: fakes.FakeWorker) -> None: + ran: list[tuple[int, int]] = [] + + @ai.tool + async def add(a: int, b: int) -> int: + """Add two numbers.""" + ran.append((a, b)) + return a + b + + answers: list[Any] = [] + + def script(prompt: str) -> Iterator[fakes.Step]: + url = worker.servers[_bridge.SERVER_NAME]["url"] + + async def call() -> None: + listed = await post( + url, {"jsonrpc": "2.0", "id": 1, "method": "tools/list"} + ) + assert [t["name"] for t in listed["result"]["tools"]] == ["add"] + answers.append( + await post( + url, + { + "jsonrpc": "2.0", + "id": 2, + "method": "tools/call", + "params": { + "name": "add", + "arguments": {"a": 1, "b": 2}, + }, + }, + ) + ) + + # What the CLI reports about its own MCP call: hidden from the + # stream, because the agent reports the call itself. + yield events.BuiltinToolStart( + tool_call_id="x1", tool_name="mcp__ai_sdk__add" + ) + yield fakes.Run(call) + yield from fakes.tool("x1", "mcp__ai_sdk__add")[1:] + text = answers[0]["result"]["content"][0]["text"] + yield from fakes.text(f"the sum is {text}") + + worker.script(script) + agent = ai.Agent(tools=[add]) + async with worker: + async with agent.run(worker, [ai.user_message("add 1 and 2")]) as run: + seen = await collect(run) + assert ran == [(1, 2)] + assert run.messages[-1].text == "the sum is 3" + names = [ + e.tool_name for e in seen if isinstance(e, events.BuiltinToolStart) + ] + assert names == [] # the CLI's own report of the MCP call is hidden + assert [x.role for x in run.messages] == [ + "user", + "assistant", + "tool", + "assistant", + ] + + +async def test_bridge_tool_names(worker: fakes.FakeWorker) -> None: + @ai.tool + async def lookup(q: str) -> str: + """Look up.""" + return q + + async with worker: + assert worker._runtime is not None + worker._runtime.bridge.set_tools([lookup.tool]) + assert worker._is_bridge_tool("lookup") # codex, with a tool name + assert worker._is_bridge_tool("ai_sdk") # codex, without one + assert worker._is_bridge_tool("mcp__ai_sdk__lookup") # claude code + assert not worker._is_bridge_tool("Bash") + + +# -- approvals, through ai.hook ----------------------------------------------- + + +@pytest.mark.parametrize("granted", [True, False]) +async def test_approvals_are_tool_approval_hooks(granted: bool) -> None: + worker = fakes.FakeWorker(approve=True) + worker.script( + lambda prompt: [ + fakes.Ask("c1", "Bash", {"command": "rm -rf build"}), + *fakes.text("done"), + ] + ) + pending: list[m.HookPart[Any]] = [] + async with worker: + async with ai.Agent().run(worker, [ai.user_message("clean")]) as run: + async for event in run: + if isinstance(event, events.PendingHookEvent): + pending.append(event.hook) + ai.resolve_hook( + event.hook, + {"granted": granted, "reason": "not today"}, + ) + answers = worker.fake.answers + assert [h.hook_type for h in pending] == ["ToolApproval"] + assert pending[0].tool_call_id == "c1" + assert pending[0].metadata == { + "tool": "Bash", + "kwargs": {"command": "rm -rf build"}, + } + assert [granted for granted, _ in answers] == [granted] + if not granted: + assert answers[0][1] == "not today" # the reason the agent reads + + +@pytest.mark.parametrize("granted", [True, False]) +async def test_agent_resolves_approval_from_a_preexisting_task( + granted: bool, +) -> None: + worker = fakes.FakeWorker(approve=True) + 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"] + + +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_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: + 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.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: + argv, env = worker.tui_command() + assert env == {"FAKE_TUI": "1"} + assert argv[0] + assert worker.session_id == "minted" + + +async def test_tui_hands_over_and_reads_back() -> None: + worker = fakes.FakeWorker(session_id="s1") + stored = [ + ai.user_message("typed by a person"), + m.Message(role="assistant", parts=[m.TextPart(text="ok")]), + ] + async with worker: + assert await worker.tui() == 0 + # tui() closed the worker's CLI, ran the TUI, and opened again. + worker.fake.stored["s1"] = stored + await worker.sync() + assert worker.messages == stored + + +async def test_list_sessions() -> None: + sessions = await fakes.FakeWorker.list_sessions(cwd="/tmp") + assert [s.session_id for s in sessions] == ["s1"] + + +# -- the bridge alone --------------------------------------------------------- + + +async def test_bridge_speaks_mcp() -> None: + async def on_call(name: str, arguments: dict[str, Any]) -> tuple[str, bool]: + return (f"{name}:{arguments['q']}", False) + + @ai.tool + async def search(q: str) -> str: + """Search.""" + return q + + bridge = _bridge.Bridge(on_call) + await bridge.start() + try: + bridge.set_tools([search.tool]) + init = await post( + bridge.url, + { + "jsonrpc": "2.0", + "id": 1, + "method": "initialize", + "params": {"protocolVersion": "2025-03-26"}, + }, + ) + assert init["result"]["protocolVersion"] == "2025-03-26" + assert ( + await post( + bridge.url, + {"jsonrpc": "2.0", "method": "notifications/initialized"}, + ) + is None + ) + listed = await post( + bridge.url, {"jsonrpc": "2.0", "id": 2, "method": "tools/list"} + ) + tool = listed["result"]["tools"][0] + assert tool["name"] == "search" + assert tool["inputSchema"]["properties"]["q"]["type"] == "string" + called = await post( + bridge.url, + { + "jsonrpc": "2.0", + "id": 3, + "method": "tools/call", + "params": {"name": "search", "arguments": {"q": "x"}}, + }, + ) + assert called["result"]["content"][0]["text"] == "search:x" + unknown = await post( + bridge.url, {"jsonrpc": "2.0", "id": 4, "method": "nope"} + ) + assert unknown["error"]["code"] == -32601 + finally: + await bridge.close() 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"