From e299fef931f82b32cd871717676d25de75767775 Mon Sep 17 00:00:00 2001 From: Andrey Buzin Date: Thu, 5 Nov 2026 19:02:42 -0800 Subject: [PATCH 1/6] Add ai.ModelLike --- .../backend/app/worker.py | 2 + .../backend/app/worker.py | 2 + src/ai/__init__.py | 2 + src/ai/agents/agent.py | 31 ++++++-- src/ai/models/__init__.py | 3 +- src/ai/models/core/api.py | 46 ++++++----- src/ai/models/core/model.py | 67 +++++++++++++++- tests/models/core/test_api.py | 1 + tests/models/core/test_model.py | 77 +++++++++++++++++++ 9 files changed, 203 insertions(+), 28 deletions(-) create mode 100644 tests/models/core/test_model.py 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/src/ai/__init__.py b/src/ai/__init__.py index b10faf3e..8fada860 100644 --- a/src/ai/__init__.py +++ b/src/ai/__init__.py @@ -74,6 +74,7 @@ InferenceRequestParams, MinPSamplerParams, Model, + ModelLike, ModelProviderDefault, OutputParams, Provider, @@ -138,6 +139,7 @@ "InstallationError", "MinPSamplerParams", "Model", + "ModelLike", "ModelProviderDefault", "OutputParams", "Provider", diff --git a/src/ai/agents/agent.py b/src/ai/agents/agent.py index ec53583c..df063fd1 100644 --- a/src/ai/agents/agent.py +++ b/src/ai/agents/agent.py @@ -1039,10 +1039,29 @@ async def _iterate(self) -> AsyncGenerator[events_.ToolCallResult]: yield res +def _validate_model(value: Any) -> models.ModelLike: + # Another model-like is kept as it is; a dict from JSON is an ai.Model. + if isinstance(value, models.ModelLike) and not isinstance( + value, models.Model + ): + return 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 +1512,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 +1521,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 +1530,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 +1575,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 +1629,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/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/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 From 6cd51f79ffb9ece848aa97b1d87fea0b51d17db6 Mon Sep 17 00:00:00 2001 From: Andrey Buzin Date: Thu, 5 Nov 2026 19:03:24 -0800 Subject: [PATCH 2/6] Implement ai.workers --- examples/workers/__init__.py | 0 examples/workers/agent_tools.py | 50 ++ examples/workers/approvals.py | 42 ++ examples/workers/streaming.py | 52 ++ pyproject.toml | 5 + src/ai/__init__.py | 2 + src/ai/agents/agent.py | 7 +- src/ai/workers/__init__.py | 45 ++ src/ai/workers/_adapters/__init__.py | 0 src/ai/workers/_adapters/_handoff.py | 504 +++++++++++++++ src/ai/workers/_adapters/base.py | 333 ++++++++++ src/ai/workers/_adapters/codex.py | 691 ++++++++++++++++++++ src/ai/workers/_adapters/jsonrpc.py | 210 +++++++ src/ai/workers/_bridge.py | 230 +++++++ src/ai/workers/_errors.py | 67 ++ src/ai/workers/_kinds.py | 57 ++ src/ai/workers/_worker.py | 805 ++++++++++++++++++++++++ tests/workers/__init__.py | 0 tests/workers/_adapters/__init__.py | 0 tests/workers/_adapters/test_codex.py | 384 +++++++++++ tests/workers/_adapters/test_handoff.py | 234 +++++++ tests/workers/_adapters/test_jsonrpc.py | 161 +++++ tests/workers/fakes.py | 231 +++++++ tests/workers/test_worker.py | 569 +++++++++++++++++ 24 files changed, 4678 insertions(+), 1 deletion(-) create mode 100644 examples/workers/__init__.py create mode 100644 examples/workers/agent_tools.py create mode 100644 examples/workers/approvals.py create mode 100644 examples/workers/streaming.py create mode 100644 src/ai/workers/__init__.py create mode 100644 src/ai/workers/_adapters/__init__.py create mode 100644 src/ai/workers/_adapters/_handoff.py create mode 100644 src/ai/workers/_adapters/base.py create mode 100644 src/ai/workers/_adapters/codex.py create mode 100644 src/ai/workers/_adapters/jsonrpc.py create mode 100644 src/ai/workers/_bridge.py create mode 100644 src/ai/workers/_errors.py create mode 100644 src/ai/workers/_kinds.py create mode 100644 src/ai/workers/_worker.py create mode 100644 tests/workers/__init__.py create mode 100644 tests/workers/_adapters/__init__.py create mode 100644 tests/workers/_adapters/test_codex.py create mode 100644 tests/workers/_adapters/test_handoff.py create mode 100644 tests/workers/_adapters/test_jsonrpc.py create mode 100644 tests/workers/fakes.py create mode 100644 tests/workers/test_worker.py diff --git a/examples/workers/__init__.py b/examples/workers/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/examples/workers/agent_tools.py b/examples/workers/agent_tools.py new file mode 100644 index 00000000..3885abe7 --- /dev/null +++ b/examples/workers/agent_tools.py @@ -0,0 +1,50 @@ +"""A worker as the model of an `ai.Agent`: the agent's tools reach it by MCP. + +The CLI calls `lookup_order`. The worker hands the call to the agent, the +agent runs the tool, and the CLI gets the result and goes on. + + uv run python examples/workers/agent_tools.py [codex] +""" + +import asyncio +import sys +from collections.abc import Callable + +import ai +from ai import workers + +KINDS: dict[str, Callable[..., workers.Worker]] = { + "codex": workers.Codex, +} + + +@ai.tool +async def lookup_order(order_id: str) -> str: + """Look up the status of an order by its id.""" + return f"order {order_id}: shipped on 2026-11-02" + + +async def main(kind: str) -> None: + agent = ai.Agent(tools=[lookup_order]) + messages = [ + ai.user_message( + "Use the lookup_order tool for order A-17, then tell me its " + "status in one sentence." + ) + ] + async with KINDS[kind]() as worker: + async with agent.run(worker, messages) as run: + async for event in run: + match event: + case ai.events.ToolEnd(): # the agent runs this one + call = event.tool_call + print(f"[agent tool] {call.tool_name} {call.tool_args}") + case ai.events.BuiltinToolEnd(): # the CLI's own tool + print(f"[cli tool] {event.tool_call.tool_name}") + case ai.events.TextDelta(): + print(event.chunk, end="", flush=True) + print() + print([m.role for m in run.messages]) + + +asyncio.run(main(sys.argv[1] if len(sys.argv) > 1 else "codex")) diff --git a/examples/workers/approvals.py b/examples/workers/approvals.py new file mode 100644 index 00000000..348a47b2 --- /dev/null +++ b/examples/workers/approvals.py @@ -0,0 +1,42 @@ +"""Approve each of the CLI's own tool calls, as `ai.Agent` tool approvals. + +With `approve=True`, every tool call the CLI makes becomes a `ToolApproval` +hook. Answer it with `ai.resolve_hook`, the way any tool approval is. + + uv run python examples/workers/approvals.py [codex] +""" + +import asyncio +import sys +from collections.abc import Callable + +import ai +from ai import workers + +KINDS: dict[str, Callable[..., workers.Worker]] = { + "codex": workers.Codex, +} + + +async def main(kind: str) -> None: + messages = [ai.user_message("Create notes.txt containing 'hello'.")] + async with KINDS[kind](approve=True) as worker: + async with ai.Agent().run(worker, messages) as run: + async for event in run: + match event: + case ai.events.PendingHookEvent(hook=hook): + meta = hook.metadata + answer = await asyncio.to_thread( + input, + f"allow {meta['tool']} {meta['kwargs']}? [y/N] ", + ) + granted = answer.strip().lower() == "y" + ai.resolve_hook( + hook, {"granted": granted, "reason": "user said no"} + ) + case ai.events.TextDelta(): + print(event.chunk, end="", flush=True) + print() + + +asyncio.run(main(sys.argv[1] if len(sys.argv) > 1 else "codex")) diff --git a/examples/workers/streaming.py b/examples/workers/streaming.py new file mode 100644 index 00000000..a5239cd3 --- /dev/null +++ b/examples/workers/streaming.py @@ -0,0 +1,52 @@ +"""A worker where a model goes: stream it, then continue the conversation. + +uv run python examples/workers/streaming.py [codex] +""" + +import asyncio +import sys +from collections.abc import Callable + +import ai +from ai import workers + +KINDS: dict[str, Callable[..., workers.Worker]] = { + "codex": workers.Codex, +} + + +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 "codex")) diff --git a/pyproject.toml b/pyproject.toml index 6bfd5968..2bbe0863 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -176,6 +176,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 8fada860..c70016ad 100644 --- a/src/ai/__init__.py +++ b/src/ai/__init__.py @@ -8,6 +8,7 @@ testing, ui, util, + workers, ) from .agents import ( Agent, @@ -229,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 df063fd1..0b5933bb 100644 --- a/src/ai/agents/agent.py +++ b/src/ai/agents/agent.py @@ -1040,11 +1040,16 @@ async def _iterate(self) -> AsyncGenerator[events_.ToolCallResult]: def _validate_model(value: Any) -> models.ModelLike: - # Another model-like is kept as it is; a dict from JSON is an ai.Model. + # Another model-like (an ai.workers.Worker) is kept as it is. A dict + # from JSON with a worker's `kind` is a worker; any other is an ai.Model. if isinstance(value, models.ModelLike) and not isinstance( value, models.Model ): return value + if isinstance(value, dict) and "kind" in value: + from .. import workers # noqa: PLC0415 + + return workers.Worker.model_validate(value) return models.Model.model_validate(value) diff --git a/src/ai/workers/__init__.py b/src/ai/workers/__init__.py new file mode 100644 index 00000000..058a3b95 --- /dev/null +++ b/src/ai/workers/__init__.py @@ -0,0 +1,45 @@ +"""Coding-agent CLIs as workers. + +Experimental: not part of the stable API, may change or be removed. + +A worker goes where a model goes, and it keeps its conversation:: + + import ai + from ai import workers + + async with workers.Codex(model="gpt-5.5") as worker: + async with ai.stream(worker, [ai.user_message("Fix the tests")]) as s: + async for event in s: + ... + + # an ai.Agent's tools reach the CLI through MCP + async with ai.Agent(tools=[search_docs]).run(worker, messages) as run: + ... + +The CLI's own tools come back as `ai.events.BuiltinTool*` events. + +A worker is a pydantic model: `worker.model_dump()` saves the conversation, +`workers.Worker.model_validate(data)` continues it, `worker.model_copy()` is +a new worker on the same settings, and `Codex(session_id=...)` resumes +a conversation the CLI has stored. +""" + +from ._adapters.base import SessionInfo +from ._errors import ( + ExecutableMissingError, + NotAuthenticatedError, + TranscriptMismatchError, + WorkerError, +) +from ._kinds import Codex +from ._worker import Worker + +__all__ = [ + "Codex", + "ExecutableMissingError", + "NotAuthenticatedError", + "SessionInfo", + "TranscriptMismatchError", + "Worker", + "WorkerError", +] diff --git a/src/ai/workers/_adapters/__init__.py b/src/ai/workers/_adapters/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/src/ai/workers/_adapters/_handoff.py b/src/ai/workers/_adapters/_handoff.py new file mode 100644 index 00000000..873a0b6c --- /dev/null +++ b/src/ai/workers/_adapters/_handoff.py @@ -0,0 +1,504 @@ +"""Seeding a CLI with a past: one rendering rule, every CLI. + +A worker given `[*past, user_message]` on its first turn starts a new +conversation from `past`. Each CLI stores it natively so the agent truly +has the context, and the rule for what becomes what is the same everywhere: + +- text: verbatim, same role. +- tool calls and results: the NATIVE tool items, original name and + arguments unaltered. Measured: the receiving agent reads them as history + and acts with its own tools; it does not try to call a tool it lacks. + Names are not translated — mapping `Write` to `fileChange` would be the + invented taxonomy this SDK refuses everywhere else. Nor are PATHS: a call + that wrote /Users/x/proj/recipe.txt says so, and that is where it was + written. Across machines the receiver must be told where things are now + (or the workspace copied to the same path) — as any colleague would be. +- reasoning: a user-role handoff note after the turn it belonged to — where + the destination accepts it. Measured: fed back as the agent's OWN thoughts + it is rejected (Claude signs thinking blocks) or silently ignored (codex + accepts a reasoning item and never reads it). As a note, codex uses it. + Claude does NOT accept it in any form: Anthropic's safeguards flag real + model reasoning replayed as user content (`[reasoning_extraction]`) — + hand-written notes passed, genuine Opus thinking was refused. So the + Claude renderer omits reasoning, and the adapter warns with the count, + because dropping context silently is the one thing this SDK never does. + Pi omits it too, for both reasons: pi drops thinking another model wrote, + and pi often runs Claude. +- files: images go to every harness, as the image input each takes (pi + takes bytes, so an image known only by URL becomes a note naming it); + PDFs to Claude as documents. Anything else (a PDF into codex, a text + file) is left out and counted (`unsupported_files`), and the adapter + warns, like it does for reasoning into Claude. +""" + +from __future__ import annotations + +import datetime +import json +import uuid +import warnings +from typing import Any + +from ...types import media +from ...types import messages as messages_ + +NOTE_PREFIX = "[Handoff from a previous session — earlier reasoning: " +AUTHOR = ("api", "provider", "model") +"""What names a reply's author in a pi session: its API and model.""" +SYSTEM_PREFIX = "[Handoff from a previous session — instructions it was given: " + + +def _text(value: Any) -> str: + return value if isinstance(value, str) else json.dumps(value) + + +def _note(reasoning: list[str]) -> str: + return ( + NOTE_PREFIX + " ".join(r.strip() for r in reasoning if r.strip()) + "]" + ) + + +def _image_url(part: messages_.FilePart) -> str: + """Return an http(s) URL as it is, anything else as a data URL.""" + return media.data_to_data_url(part.data, part.media_type) + + +def _source(part: messages_.FilePart) -> dict[str, Any]: + """Return an Anthropic content-block source for a file.""" + if isinstance(part.data, str) and media.is_downloadable_url(part.data): + return {"type": "url", "url": part.data} + return { + "type": "base64", + "media_type": part.media_type, + "data": media.data_to_base64(part.data), + } + + +def harness_view(history: list[messages_.Message]) -> list[messages_.Message]: + """Return a past with the CLI's own tools as ordinary tool calls. + + A worker's messages hold the tools a CLI ran itself as + `BuiltinToolCallPart`/`BuiltinToolReturnPart`, the way a provider's web + search is. A CLI's store holds them as tool calls, each with its result + in a `tool` message after it. The renderers below read that shape. + """ + out: list[messages_.Message] = [] + for message in history: + parts: list[messages_.Part] = [] + results: list[messages_.Part] = [] + first = True + for part in message.parts: + if results and not isinstance( + part, messages_.BuiltinToolReturnPart + ): + # What follows a result comes after it: a new message. + if parts: + out.append(_split(message, parts, first=first)) + first = False + out.append(messages_.Message(role="tool", parts=results)) + parts, results = [], [] + if isinstance(part, messages_.BuiltinToolCallPart): + parts.append( + messages_.ToolCallPart( + tool_call_id=part.tool_call_id, + tool_name=part.tool_name, + tool_args=part.tool_args or "{}", + provider_metadata=part.provider_metadata, + ) + ) + elif isinstance(part, messages_.BuiltinToolReturnPart): + results.append( + messages_.ToolResultPart( + tool_call_id=part.tool_call_id, + tool_name=part.tool_name, + result=part.result, + result_kind="error" if part.is_error else "json", + ) + ) + else: + parts.append(part) + if parts: + out.append(_split(message, parts, first=first)) + if results: + out.append(messages_.Message(role="tool", parts=results)) + return out + + +def _split( + message: messages_.Message, parts: list[messages_.Part], *, first: bool +) -> messages_.Message: + """One piece of a message: the first keeps its id, the rest get new ones.""" + if first: + return message.model_copy(update={"parts": parts}) + return messages_.Message( + role=message.role, + parts=parts, + provider_metadata=message.provider_metadata, + ) + + +def model_view(stored: list[messages_.Message]) -> list[messages_.Message]: + """Return a stored conversation the way a worker shows it. + + The reverse of `harness_view`: the CLI's tool calls become built-in + parts, and each result joins the assistant message of its call. + """ + out: list[messages_.Message] = [] + owner: dict[str, int] = {} # tool_call_id -> index in `out` + for message in stored: + if message.role == "assistant": + parts: list[messages_.Part] = [] + for part in message.parts: + if isinstance(part, messages_.ToolCallPart): + owner[part.tool_call_id] = len(out) + parts.append( + messages_.BuiltinToolCallPart( + tool_call_id=part.tool_call_id, + tool_name=part.tool_name, + tool_args=part.tool_args, + provider_metadata=part.provider_metadata, + ) + ) + else: + parts.append(part) + out.append(message.model_copy(update={"parts": parts})) + elif message.role == "tool": + for result in message.tool_results: + index = owner.get(result.tool_call_id) + if index is None: + continue + target = out[index] + out[index] = target.model_copy( + update={ + "parts": [ + *target.parts, + messages_.BuiltinToolReturnPart( + tool_call_id=result.tool_call_id, + tool_name=result.tool_name + or _name_of(target, result.tool_call_id), + result=result.result, + is_error=result.result_kind == "error", + ), + ] + } + ) + else: + out.append(message) + return out + + +def _name_of(message: messages_.Message, tool_call_id: str) -> str: + return next( + ( + p.tool_name + for p in message.parts + if isinstance(p, messages_.BuiltinToolCallPart) + and p.tool_call_id == tool_call_id + ), + "", + ) + + +def warn_unsupported_files( + messages: list[messages_.Message], kind: str +) -> None: + """Say how many files a history held that `kind` was not given.""" + left = unsupported_files(messages, kind) + if left: + warnings.warn( + f"{left} file(s) in the history were not carried into {kind}: " + + "it takes images" + + (" and PDFs" if kind == "claude-code" else "") + + " from a history. Text, tool calls and images were carried.", + stacklevel=3, + ) + + +def unsupported_files(messages: list[messages_.Message], kind: str) -> int: + """Count files a history holds that `kind` cannot take as input.""" + return sum( + 1 + for m in messages + for p in m.parts + if isinstance(p, messages_.FilePart) + and not p.media_type.startswith("image/") + and not (kind == "claude-code" and p.media_type == "application/pdf") + ) + + +def to_codex_items(messages: list[messages_.Message]) -> list[dict[str, Any]]: + """Responses API items for `thread/inject_items`.""" + items: list[dict[str, Any]] = [] + for m in harness_view(messages): + reasoning: list[str] = [] + for p in m.parts: + if isinstance(p, messages_.TextPart) and p.text.strip(): + ctype = "input_text" if m.role == "user" else "output_text" + items.append( + { + "type": "message", + "role": m.role, + "content": [{"type": ctype, "text": p.text}], + } + ) + elif ( + isinstance(p, messages_.FilePart) + and m.role == "user" + and p.media_type.startswith("image/") + ): + items.append( + { + "type": "message", + "role": "user", + "content": [ + {"type": "input_image", "image_url": _image_url(p)} + ], + } + ) + elif isinstance(p, messages_.ToolCallPart): + items.append( + { + "type": "function_call", + "call_id": p.tool_call_id or p.id, + "name": p.tool_name, + "arguments": p.tool_args or "{}", + } + ) + elif isinstance(p, messages_.ToolResultPart): + items.append( + { + "type": "function_call_output", + "call_id": p.tool_call_id, + "output": _text(p.result), + } + ) + elif isinstance(p, messages_.ReasoningPart) and p.text.strip(): + reasoning.append(p.text) + if reasoning: + items.append( + { + "type": "message", + "role": "user", + "content": [ + {"type": "input_text", "text": _note(reasoning)} + ], + } + ) + return items + + +def reasoning_count(messages: list[messages_.Message]) -> int: + return sum( + 1 + for m in messages + for p in m.parts + if isinstance(p, messages_.ReasoningPart) and p.text.strip() + ) + + +def to_claude_records( + messages: list[messages_.Message], session_id: str, cwd: str +) -> list[dict[str, Any]]: + """Build Claude Code transcript records for the CLI's store. + + Chained by parentUuid. + + Reasoning parts are omitted: see the module docstring. Callers report + the omission — `reasoning_count()` says how many. + """ + records: list[dict[str, Any]] = [] + parent: str | None = None + + def add(role: str, content: Any) -> None: + nonlocal parent + uid = str(uuid.uuid4()) + ts = ( + datetime.datetime.now(datetime.UTC) + .isoformat() + .replace("+00:00", "Z") + ) + records.append( + { + "parentUuid": parent, + "isSidechain": False, + "type": role, + "message": {"role": role, "content": content}, + "uuid": uid, + "timestamp": ts, + "sessionId": session_id, + "cwd": cwd, + } + ) + parent = uid + + for m in harness_view(messages): + blocks: list[dict[str, Any]] = [] + for p in m.parts: + if isinstance(p, messages_.TextPart) and p.text.strip(): + blocks.append({"type": "text", "text": p.text}) + elif isinstance(p, messages_.FilePart) and m.role == "user": + if p.media_type.startswith("image/"): + blocks.append({"type": "image", "source": _source(p)}) + elif p.media_type == "application/pdf": + blocks.append({"type": "document", "source": _source(p)}) + elif isinstance(p, messages_.ToolCallPart): + try: + args = json.loads(p.tool_args) if p.tool_args else {} + except json.JSONDecodeError: + args = {"raw": p.tool_args} + blocks.append( + { + "type": "tool_use", + "id": p.tool_call_id or p.id, + "name": p.tool_name, + "input": args, + } + ) + elif isinstance(p, messages_.ToolResultPart): + blocks.append( + { + "type": "tool_result", + "tool_use_id": p.tool_call_id, + "content": _text(p.result), + **( + {"is_error": True} + if p.result_kind == "error" + else {} + ), + } + ) + # ReasoningPart: omitted on purpose — Anthropic's safeguards + # refuse replayed reasoning. The adapter warns with the count. + if blocks: + # Tool results live in role="tool" messages in the IR; on disk + # the CLI keeps them as user records with tool_result blocks. + add("user" if m.role in ("user", "tool") else "assistant", blocks) + return records + + +def to_pi_messages( + messages: list[messages_.Message], *, timestamp: int +) -> list[dict[str, Any]]: + """Build pi `AgentMessage`s for a session file. + + Assistant messages pi wrote keep their author (`provider_metadata["pi"]`): + pi restores a session's model from it. Any other is attributed to a + model pi does not run (`ai-python/handoff`), so pi treats it as another + model's — it keeps its text and tool calls and normalizes the call ids + for its own provider. Consecutive assistant messages are merged, the way one + model response holds text and calls together. Reasoning is omitted: see + the module docstring. + """ + out: list[dict[str, Any]] = [] + usage = { + "input": 0, + "output": 0, + "cacheRead": 0, + "cacheWrite": 0, + "totalTokens": 0, + "cost": { + "input": 0, + "output": 0, + "cacheRead": 0, + "cacheWrite": 0, + "total": 0, + }, + } + for m in harness_view(messages): + if m.role == "tool": + for p in m.parts: + if isinstance(p, messages_.ToolResultPart): + out.append( + { + "role": "toolResult", + "toolCallId": p.tool_call_id, + "toolName": p.tool_name, + "content": [ + {"type": "text", "text": _text(p.result)} + ], + "isError": p.result_kind == "error", + "timestamp": timestamp, + } + ) + continue + blocks: list[dict[str, Any]] = [] + for p in m.parts: + if isinstance(p, messages_.TextPart) and p.text.strip(): + blocks.append({"type": "text", "text": p.text}) + elif ( + isinstance(p, messages_.FilePart) + and m.role == "user" + and p.media_type.startswith("image/") + ): + if isinstance(p.data, str) and media.is_downloadable_url( + p.data + ): + blocks.append( + {"type": "text", "text": f"[image: {p.data}]"} + ) + else: + blocks.append( + { + "type": "image", + "data": media.data_to_base64(p.data), + "mimeType": p.media_type, + } + ) + elif ( + isinstance(p, messages_.ToolCallPart) and m.role == "assistant" + ): + try: + args = json.loads(p.tool_args) if p.tool_args else {} + except json.JSONDecodeError: + args = {"raw": p.tool_args} + blocks.append( + { + "type": "toolCall", + "id": p.tool_call_id or p.id, + "name": p.tool_name, + "arguments": args if isinstance(args, dict) else {}, + } + ) + if not blocks: + continue + if m.role == "system": + # Measured (pi 1.3.0): a system message in a session file is + # pi's own prompt state, and replaying one REPLACED pi's system + # prompt and its tools. So instructions travel as what they are + # to the agent — the caller's words — never as its own output. + text = " ".join(b["text"] for b in blocks if b["type"] == "text") + blocks = [{"type": "text", "text": SYSTEM_PREFIX + text + "]"}] + if m.role in ("user", "system"): + out.append( + {"role": "user", "content": blocks, "timestamp": timestamp} + ) + continue + if out and out[-1]["role"] == "assistant": + out[-1]["content"] += blocks + else: + # A reply pi wrote keeps its author: pi restores a session's model + # from its last reply's, and a model it does not know (ours) + # put the conversation on pi's default one (measured). + author = (m.provider_metadata or {}).get("pi") or {} + known = all(isinstance(author.get(k), str) for k in AUTHOR) + out.append( + { + "role": "assistant", + "content": blocks, + **( + {k: author[k] for k in AUTHOR} + if known + else { + "api": "ai-python", + "provider": "ai-python", + "model": "handoff", + } + ), + "usage": usage, + "stopReason": "stop", + "timestamp": timestamp, + } + ) + if any(b["type"] == "toolCall" for b in out[-1]["content"]): + out[-1]["stopReason"] = "toolUse" + return out diff --git a/src/ai/workers/_adapters/base.py b/src/ai/workers/_adapters/base.py new file mode 100644 index 00000000..10d09016 --- /dev/null +++ b/src/ai/workers/_adapters/base.py @@ -0,0 +1,333 @@ +"""What every adapter shares: its protocol, local processes, prompt files. + +An adapter drives ONE conversation with one CLI. It speaks the model view +both ways: `turn()` yields the events of one assistant message, with the +CLI's own tools as `BuiltinTool*` events, and ends with a `StreamEnd`; a +history it reads or is seeded with is a plain `list[Message]`. +""" + +from __future__ import annotations + +import asyncio +import base64 +import contextlib +import os +import re +import warnings +from collections.abc import ( + AsyncIterator, + Awaitable, + Callable, + Mapping, + Sequence, +) +from typing import Any, Protocol + +import pydantic + +from ...models.core.helpers import files +from ...types import events, media +from ...types import messages as messages_ +from .. import _errors as errors + +Prompt = list[messages_.TextPart | messages_.FilePart] + +Approve = Callable[[str, str, dict[str, Any]], Awaitable[tuple[bool, str]]] +"""`approve(tool_call_id, tool_name, tool_input)` returns `(granted, reason)`. + +Never raises: the worker answers a failure with a denial.""" + +LINE_LIMIT = 256 * 1024 * 1024 +"""Longest line a CLI may write. The protocols are JSON lines, and one line +can be megabytes (a codex `thread/read` of a long thread). With asyncio's +default (64 KiB) such a line failed as if the CLI had crashed.""" + +TERM_GRACE = 3.0 +"""Seconds a CLI gets to exit after SIGTERM, before SIGKILL.""" + + +class SessionInfo(pydantic.BaseModel): + """A conversation in a CLI's own store.""" + + session_id: str + title: str | None = None + cwd: str | None = None + created_at: int | None = None + """Milliseconds since the epoch, when the CLI records it.""" + updated_at: int | None = None + + +class Adapter(Protocol): + version: str | None + """What ` --version` printed, once started.""" + + async def start(self) -> None: + """Check the CLI runs, and start what it needs (codex: a server).""" + ... + + async def close(self) -> None: ... + + async def open( + self, + *, + session_id: str | None, + fork: bool, + seed: list[messages_.Message] | None, + instructions: str | None, + ) -> str: + """Open the conversation and return its session id. + + A new one (seeded with a past when `seed` is given), the stored one + `session_id` names, or a native fork of it. + """ + ... + + def turn(self, prompt: Prompt) -> AsyncIterator[events.Event]: + """Send a prompt; yield one assistant message, ending in StreamEnd.""" + ... + + async def steer(self, text: str) -> None: + """Send guidance to the turn that runs now.""" + ... + + async def interrupt(self) -> None: + """End the running turn. The CLI keeps its transcript.""" + ... + + async def history(self, session_id: str) -> list[messages_.Message]: + """Read a stored conversation.""" + ... + + async def list_sessions(self) -> list[SessionInfo]: ... + + def tui_command( + self, session_id: str | None + ) -> tuple[list[str], dict[str, str], str | None]: + """Return the CLI's interactive command, its env, and its session id. + + The session id is minted here for a new conversation when the CLI + lets us choose it, else None. + """ + ... + + +# -- local processes ----------------------------------------------------------- + + +class Process: + """A CLI started by `spawn`: JSON lines on stdin and stdout.""" + + def __init__(self, proc: asyncio.subprocess.Process) -> None: + self._proc = proc + + @property + def pid(self) -> int: + return self._proc.pid + + async def write(self, data: str) -> None: + assert self._proc.stdin is not None + self._proc.stdin.write(data.encode()) + await self._proc.stdin.drain() + + async def readline(self) -> str: + assert self._proc.stdout is not None + return (await self._proc.stdout.readline()).decode() + + async def read_stderr(self) -> str: + if self._proc.stderr is None: + return "" + return (await self._proc.stderr.read()).decode(errors="replace") + + async def wait(self) -> int: + return await self._proc.wait() + + async def terminate(self) -> None: + """Stop the process group: SIGTERM, then SIGKILL.""" + if self._proc.returncode is not None: + return + with contextlib.suppress(ProcessLookupError): + os.killpg(os.getpgid(self._proc.pid), 15) + try: + async with asyncio.timeout(TERM_GRACE): + await self._proc.wait() + except TimeoutError: + with contextlib.suppress(ProcessLookupError): + os.killpg(os.getpgid(self._proc.pid), 9) + with contextlib.suppress(Exception): + await self._proc.wait() + + async def death_note(self) -> str: + """Say how the process ended, and its last words.""" + code: int | None = None + tail = "" + with contextlib.suppress(Exception): + async with asyncio.timeout(2): + code = await self.wait() + with contextlib.suppress(Exception): + async with asyncio.timeout(2): + tail = (await self.read_stderr()).strip() + how = f"exit code {code}" if code is not None else "exited" + if code in (137, -9): + how += " (SIGKILL, typically the kernel's OOM killer)" + return f"{how}; stderr: {tail[-800:]}" if tail else f"{how}; no stderr" + + +async def spawn( + argv: Sequence[str], *, cwd: str, env: Mapping[str, str] +) -> Process: + """Start a CLI in its own process group, with pipes for stdio.""" + try: + proc = await asyncio.create_subprocess_exec( + *argv, + cwd=cwd, + env={**os.environ, **env}, + stdin=asyncio.subprocess.PIPE, + stdout=asyncio.subprocess.PIPE, + stderr=asyncio.subprocess.PIPE, + # Own the whole tree, so teardown reaches grandchildren too. + start_new_session=True, + limit=LINE_LIMIT, + ) + except OSError as exc: + raise errors.WorkerError(f"cannot start {argv[0]!r}: {exc}") from exc + return Process(proc) + + +async def probe( + kind: str, + executable: str, + *, + install: str, + verified: str, + cwd: str, + env: Mapping[str, str], +) -> str: + """Check that the CLI runs, and return its version. + + Warns when it is older than the version the adapter was verified with: + the adapters lean on CLI behavior that is measured, not documented. + """ + try: + proc = await asyncio.create_subprocess_exec( + executable, + "--version", + cwd=cwd, + env={**os.environ, **env}, + stdout=asyncio.subprocess.PIPE, + stderr=asyncio.subprocess.PIPE, + ) + async with asyncio.timeout(60): + stdout, _ = await proc.communicate() + except (OSError, TimeoutError) as exc: + raise errors.ExecutableMissingError(kind, executable, install) from exc + if proc.returncode != 0: + raise errors.ExecutableMissingError(kind, executable, install) + version = (stdout.decode(errors="replace").strip().splitlines() or [""])[0] + have, want = _version(version), _version(verified) + if have is not None and want is not None and have < want: + warnings.warn( + f"{kind} {version} is older than {verified}, the version this " + "SDK was verified with; update it if something misbehaves", + stacklevel=2, + ) + return version + + +def _version(text: str | None) -> tuple[int, ...] | None: + found = re.search(r"\d+(?:\.\d+)+", text or "") + return tuple(int(n) for n in found.group(0).split(".")) if found else None + + +# -- files in a prompt --------------------------------------------------------- +# +# Files are turned into bytes HERE: a URL is downloaded with the SDK's own +# SSRF-checked downloader, not handed to the CLI. Measured: Claude Code drops +# an image given by URL without a word. + + +async def data(part: messages_.FilePart) -> bytes: + """Return a file's bytes, downloading a URL first.""" + if isinstance(part.data, bytes): + return part.data + if media.is_downloadable_url(part.data): + body, _ = await files.download(part.data) + return body + return base64.b64decode(media.data_to_base64(part.data)) + + +async def as_text(part: messages_.FilePart) -> str: + """Return a text file as text a CLI reads inline, named if it has one.""" + body = (await data(part)).decode("utf-8", errors="replace") + name = part.filename or "attached file" + return f"\n{body}\n" + + +def check_files(prompt: Prompt, kind: str, accepts: Sequence[str]) -> None: + """Refuse a file the CLI cannot take, before anything runs. + + Text files (`text/*`) go everywhere, as text. `accepts` lists the other + media type prefixes the CLI takes. + """ + for part in prompt: + if isinstance(part, messages_.FilePart) and not any( + part.media_type.startswith(p) for p in ("text/", *accepts) + ): + raise errors.WorkerError( + f"{kind} does not take {part.media_type} files" + ) + + +def text_of(prompt: Prompt) -> str: + return "\n\n".join( + p.text for p in prompt if isinstance(p, messages_.TextPart) + ) + + +def builtin_call( + tool_call_id: str, + tool_name: str, + tool_args: str, + *, + started: set[str], +) -> list[events.Event]: + """Return the events of one finished CLI tool call. + + `started` holds the calls whose start was already sent: the start is + sent here otherwise, because the hydrator only completes a call it saw + start. The arguments travel as a delta: the hydrator builds a call's + arguments only from its deltas. + """ + out: list[events.Event] = [] + if tool_call_id not in started: + started.add(tool_call_id) + out.append( + events.BuiltinToolStart( + tool_call_id=tool_call_id, tool_name=tool_name + ) + ) + return [ + *out, + events.BuiltinToolDelta(tool_call_id=tool_call_id, chunk=tool_args), + events.BuiltinToolEnd( + tool_call_id=tool_call_id, + tool_call=messages_.BuiltinToolCallPart( + tool_call_id=tool_call_id, + tool_name=tool_name, + tool_args=tool_args, + ), + ), + ] + + +def builtin_result( + tool_call_id: str, tool_name: str, result: Any, *, is_error: bool +) -> events.BuiltinToolResult: + return events.BuiltinToolResult( + tool_call_id=tool_call_id, + result=messages_.BuiltinToolReturnPart( + tool_call_id=tool_call_id, + tool_name=tool_name, + result=result, + is_error=is_error, + ), + ) diff --git a/src/ai/workers/_adapters/codex.py b/src/ai/workers/_adapters/codex.py new file mode 100644 index 00000000..84dc8809 --- /dev/null +++ b/src/ai/workers/_adapters/codex.py @@ -0,0 +1,691 @@ +"""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 AsyncIterator +from typing import Any + +from ...types import events as events_ +from ...types import messages as messages_ +from ...types import usage as usage_ +from .. import _bridge +from .. import _errors as errors +from . import _handoff, base, jsonrpc + +KIND = "codex" +INSTALL = "npm install -g @openai/codex" +VERIFIED_VERSION = "0.160.1" +"""The CLI the live tests last passed against. Older ones get a warning.""" +CRASHED = "__crashed__" +"""Put on the turn's queue when app-server dies.""" +LIST_PAGE_SIZE = 100 +LIST_PAGES = 50 +"""`list_sessions()` reads at most this many pages of threads.""" + +APPROVAL_METHODS = ( + "item/commandExecution/requestApproval", + "item/fileChange/requestApproval", + "item/permissions/requestApproval", + "execCommandApproval", + "applyPatchApproval", +) + +TOOL_ITEMS = ( + "fileChange", + "commandExecution", + "mcpToolCall", + "webSearch", + "toolCall", +) +"""Item types that are the agent doing something, rather than speaking.""" + +AUTH_HINT = ( + "codex uses your own login: run `codex login`, or pass " + "env={'OPENAI_API_KEY': ...}, or point it at another provider with " + "config={'model_provider': ..., 'model_providers..base_url': ...}." +) + + +class CodexAdapter: + def __init__( + self, + *, + cwd: str, + env: dict[str, str], + executable: str, + model: str | None, + mcp_servers: dict[str, Any], + approve: base.Approve | None, + sandbox: str | None, + config: dict[str, Any], + ) -> None: + # Codex records a thread's directory as its real path (on macOS a + # temp dir is /var/..., recorded as /private/var/..., measured). + self._cwd = os.path.realpath(cwd) + self._env = env + self._executable = executable + self._model = model + self._approve = approve + # Full access by default, like claude without a gate: a worker is + # driven by a program, and a mode that silently refuses writes reads + # as an agent that did nothing. + self._sandbox = sandbox or "danger-full-access" + # Passed to app-server as `-c key=value`, the overrides the codex + # CLI takes. An explicit config wins over the MCP servers. + self._config = {**mcp_config(mcp_servers), **config} + self._instructions: str | None = None + self._process: base.Process | None = None + self._peer: jsonrpc.JsonRpcPeer | None = None + self._thread: str | None = None + self._turn: str | None = None + self._queue: asyncio.Queue[tuple[str, dict[str, Any]]] | None = None + self._usage = usage_.Usage() + self._interrupted = False + self.version: str | None = None + + async def start(self) -> None: + self.version = await base.probe( + KIND, + self._executable, + install=INSTALL, + verified=VERIFIED_VERSION, + cwd=self._cwd, + env=self._env, + ) + self._process = await base.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.close() + raise + + async def 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 + + 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, + # With a gate: ask about everything the policy can ask about. + # Without one the server never asks: a request nobody answers + # would freeze the agent (measured). + "approvalPolicy": "untrusted" if self._approve else "never", + **({"model": self._model} if self._model else {}), + **( + {"developerInstructions": self._instructions} + if self._instructions + else {} + ), + } + + # -- the conversation ----------------------------------------------------- + + async def 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._approve is None: + # Unknown, or unasked for: answer rather than hang the agent. + decision = "accept" if method in APPROVAL_METHODS else "decline" + await self._rpc().respond(request_id, {"decision": decision}) + return + granted, _ = await self._approve( + 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 turn(self, prompt: base.Prompt) -> AsyncIterator[events_.Event]: + base.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") + 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 base.builtin_call( + item_id, + _tool_name(item), + json.dumps(_tool_args(item)), + started=started, + ): + yield event + yield base.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 steer(self, text: str) -> None: + if not self._turn: + raise errors.WorkerError(f"{KIND}: no turn is running to steer") + try: + await self._rpc().call( + "turn/steer", + { + "threadId": self._thread, + # A precondition: steering the wrong turn is worse than + # failing to steer. + "expectedTurnId": self._turn, + "input": [{"type": "text", "text": text}], + }, + ) + except jsonrpc.JsonRpcError as exc: + raise errors.WorkerError(f"{KIND}: steer rejected: {exc}") from exc + + async def 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 history(self, session_id: str) -> list[messages_.Message]: + """Read the thread's stored record, every item included.""" + await self._require_here(session_id) + result = await self._rpc().call( + "thread/read", + {"threadId": session_id, "includeTurns": True, "itemsView": "full"}, + ) + stored: list[messages_.Message] = [] + for turn in ((result or {}).get("thread") or {}).get("turns") or []: + for item in turn.get("items") or []: + stored.extend(_item_to_messages(item)) + return _handoff.model_view(stored) + + async def list_sessions(self) -> list[base.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 [ + base.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 tui_command( + self, session_id: str | None + ) -> tuple[list[str], dict[str, str], str | None]: + config = { + k: v + for k, v in self._config.items() + 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: + argv += ["--model", self._model] + 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: base.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 base.as_text(part)}) + else: + encoded = base64.b64encode(await base.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, CLI tools as tool calls.""" + 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_.ToolCallPart( + tool_call_id=item.get("id", ""), + tool_name=_tool_name(item), + tool_args=json.dumps(_tool_args(item)), + ) + result = messages_.ToolResultPart( + tool_call_id=item.get("id", ""), + tool_name=call.tool_name, + result=_item_result(item), + result_kind="error" if item.get("status") == "failed" else "json", + ) + return [ + messages_.Message(role="assistant", parts=[call]), + messages_.Message(role="tool", parts=[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/_adapters/jsonrpc.py b/src/ai/workers/_adapters/jsonrpc.py new file mode 100644 index 00000000..14837088 --- /dev/null +++ b/src/ai/workers/_adapters/jsonrpc.py @@ -0,0 +1,210 @@ +"""A small JSON-RPC 2.0 peer over a CLI's 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 +from collections.abc import Awaitable, Callable +from typing import TYPE_CHECKING, Any + +from .. import _errors as errors + +if TYPE_CHECKING: + from . import base + +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: base.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")) diff --git a/src/ai/workers/_bridge.py b/src/ai/workers/_bridge.py new file mode 100644 index 00000000..f32f5a59 --- /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_ + +SERVER_NAME = "ai_sdk" +"""The MCP server name the CLI sees. Claude Code calls a tool +`mcp__ai_sdk__`.""" + +PROTOCOL_VERSION = "2025-06-18" + +OnCall = Callable[[str, dict[str, Any]], Awaitable[tuple[str, bool]]] +"""`on_call(name, arguments)` returns `(text, is_error)`.""" + + +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/_errors.py b/src/ai/workers/_errors.py new file mode 100644 index 00000000..21baddee --- /dev/null +++ b/src/ai/workers/_errors.py @@ -0,0 +1,67 @@ +"""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 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/_kinds.py b/src/ai/workers/_kinds.py new file mode 100644 index 00000000..69285dc0 --- /dev/null +++ b/src/ai/workers/_kinds.py @@ -0,0 +1,57 @@ +"""The workers, one per CLI. + +Each adds its CLI's own options to `Worker` and builds its adapter. +""" + +from __future__ import annotations + +from typing import Any, Literal + +import pydantic + +from . import _bridge, _worker +from ._adapters import base, codex + + +class Codex(_worker.Worker): + """Codex, over `codex app-server`. + + `sandbox` is Codex's own sandbox mode: `"read-only"`, + `"workspace-write"` or `"danger-full-access"` (the default). `config` + takes Codex `-c` overrides. + """ + + kind: Literal["codex"] = "codex" + sandbox: ( + Literal["read-only", "workspace-write", "danger-full-access"] | None + ) = None + config: dict[str, Any] = pydantic.Field(default_factory=dict) + + def _make_adapter( + self, + mcp_servers: dict[str, dict[str, Any]], + approve: base.Approve | None, + ) -> base.Adapter: + config = dict(self.config) + if self.effort is not None: + config.setdefault( + "model_reasoning_effort", + "xhigh" if self.effort == "max" else self.effort, + ) + if _bridge.SERVER_NAME in mcp_servers: + # Codex's default wait for an MCP tool (60s) is too short for a + # tool an `ai.Agent` runs, maybe after an approval. + config.setdefault( + f"mcp_servers.{_bridge.SERVER_NAME}.tool_timeout_sec", + 24 * 3600, + ) + return codex.CodexAdapter( + cwd=self.cwd, + env=dict(self.env), + executable=self.executable or "codex", + model=self.model, + mcp_servers=dict(mcp_servers), + approve=approve, + sandbox=self.sandbox, + config=config, + ) diff --git a/src/ai/workers/_worker.py b/src/ai/workers/_worker.py new file mode 100644 index 00000000..89aa3994 --- /dev/null +++ b/src/ai/workers/_worker.py @@ -0,0 +1,805 @@ +"""`ai.workers.Worker`: a coding-agent CLI that goes where a model goes. + +A worker is ONE conversation with one coding-agent CLI, such as Codex. It is +a pydantic model: its fields are its settings, the CLI's `session_id` and +the conversation so far (`messages`). Dump it, store it, and validate it +again later; it continues the same conversation. + +It follows the model protocol: `stream(messages, tools=, output_type=)` +yields the events of one assistant message, so `ai.stream`, +`ai.experimental_generate` and `ai.Agent.run` take a worker where they take +a model. The CLI runs its own loop and its own tools; those come back as +`BuiltinTool*` events, so an `ai.Agent` does not run them again. The tools +of an `ai.Agent` reach the CLI through the MCP bridge (see `_bridge`) and +come back as normal tool calls, for the agent to run. + +A worker has state, a model does not. `stream()` still receives the whole +conversation on every call. The worker compares it with `messages` and +sends the CLI only what is new (see `_plan`). +""" + +from __future__ import annotations + +import asyncio +import contextlib +import contextvars +import dataclasses +import json +import os +from collections.abc import AsyncGenerator, 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 _bridge +from . import _errors as errors +from ._adapters import base + +Effort = Literal["low", "medium", "high", "max"] + +BATCH_WINDOW = 0.05 +"""Seconds to wait for more bridge calls before handing a batch to the +caller. A CLI that calls tools in parallel sends them close together.""" + +OUTPUT_RETRIES = 2 +"""How many times to ask again for output that does not validate.""" + +OUTPUT_INSTRUCTION = ( + "\n\nRespond with ONLY a JSON value matching this schema, " + "no prose, no code fences:\n" +) + + +@dataclasses.dataclass +class _Call: + """A call from the CLI to an `ai` tool, through the bridge.""" + + tool_call_id: str + name: str + arguments: dict[str, Any] + answer: asyncio.Future[tuple[str, bool]] + + +@dataclasses.dataclass +class _Failed: + error: BaseException + + +@dataclasses.dataclass +class _Plan: + """What one `stream()` call must do, from the messages it was given.""" + + seed: list[messages_.Message] = dataclasses.field(default_factory=list) + instructions: str | None = None + results: list[messages_.ToolResultPart] = dataclasses.field( + default_factory=list + ) + system: list[str] = dataclasses.field(default_factory=list) + """System text that arrived after the conversation began.""" + prompt: list[messages_.TextPart | messages_.FilePart] = dataclasses.field( + default_factory=list + ) + transcript: list[messages_.Message] = dataclasses.field( + default_factory=list + ) + """The transcript once this call succeeds, before its answer.""" + + +@dataclasses.dataclass +class _Runtime: + """What lives only while a worker is open. Never copied, never dumped.""" + + adapter: base.Adapter + bridge: _bridge.Bridge + lock: asyncio.Lock = dataclasses.field(default_factory=asyncio.Lock) + in_session: bool = False + # The running turn: its pump task and the queue it fills. + queue: asyncio.Queue[Any] | None = None + pump: asyncio.Task[None] | None = None + # Bridge calls handed to the caller, waiting for their results. + pending: dict[str, _Call] = dataclasses.field(default_factory=dict) + # CLI tool ids that are bridge calls, hidden from the stream. + hidden: set[str] = dataclasses.field(default_factory=set) + # The context of the latest `stream()` call: approvals ask in it. + context: contextvars.Context | None = None + + +class Worker(pydantic.BaseModel): + """Base class of the workers, such as `Codex`. + + `Worker.model_validate(data)` builds the kind that `data["kind"]` names. + """ + + kind: str + model: str | None = None + """The CLI's model. None: the CLI's own default.""" + cwd: str = pydantic.Field(default_factory=os.getcwd) + """Where the CLI runs and keeps its sessions.""" + env: dict[str, str] = {} + """Added to the CLI's environment: keys, base URLs, config dirs.""" + executable: str | None = None + effort: Effort | None = None + mcp_servers: dict[str, dict[str, Any]] = {} + """MCP servers for the CLI. + + `{"name": {"command": ..., "args": [...]}}` or `{"name": {"url": ...}}`. + """ + approve: bool = False + """Ask before each of the CLI's own tool calls, through `ai.hook`. + + False: the CLI's own permission settings decide (`allowed_tools`, + Codex's `sandbox`). True: each call becomes a `ToolApproval` hook, which + `ai.resolve_hook` and UIs answer as they answer any tool approval. Needs + an `ai.Agent.run()`, where hooks live. + """ + session_id: str | None = None + """The CLI's own id for the conversation. Set it to resume one.""" + fork: bool = False + """With `session_id`: fork that conversation natively on first use.""" + messages: list[messages_.Message] = [] + """The conversation so far. Send it back with the next user message.""" + + _kinds: ClassVar[dict[str, type[Worker]]] = {} + _runtime: _Runtime | None = pydantic.PrivateAttr(default=None) + + @classmethod + def __pydantic_init_subclass__(cls, **kwargs: Any) -> None: # noqa: PLW3201 + super().__pydantic_init_subclass__(**kwargs) + kind = cls.model_fields["kind"].default + if isinstance(kind, str): + Worker._kinds[kind] = cls + + @pydantic.model_validator(mode="wrap") + @classmethod + def _of_kind( + cls, data: Any, handler: pydantic.ValidatorFunctionWrapHandler + ) -> Any: + if cls is Worker and isinstance(data, dict): + kind = Worker._kinds.get(str(data.get("kind"))) + if kind is None: + raise ValueError(f"no worker of kind {data.get('kind')!r}") + return kind.model_validate(data) + return handler(data) + + def __copy__(self) -> Self: + # A copy is a new worker: it opens a CLI of its own. + copied = super().__copy__() + copied._runtime = None + return copied + + def __deepcopy__(self, memo: dict[int, Any] | None = None) -> Self: + copied = super().__deepcopy__(memo) + copied._runtime = None + return copied + + # -- subclass point ------------------------------------------------------- + + def _make_adapter( + self, + mcp_servers: dict[str, dict[str, Any]], + approve: base.Approve | None, + ) -> base.Adapter: + raise NotImplementedError + + # -- ModelLike ------------------------------------------------------------ + + @property + def id(self) -> str: + return self.model or "default" + + @property + def provider_name(self) -> str: + return self.kind + + async def stream( + self, + messages: list[messages_.Message], + *, + tools: Sequence[tools_.Tool] | None = None, + output_type: type[pydantic.BaseModel] | None = None, + params: Any = None, + ) -> AsyncGenerator[events_.Event]: + """Answer `messages` with one assistant message. + + Use `ai.stream(worker, messages)`, as with a model. The message ends + in one of two ways: + + - `finish_reason="tool_call"`: the CLI called `ai` tools from + `tools=`. The message holds them as `ToolCallPart`s. Run them and + call again with the results; the CLI waits until then. + - Anything else: the CLI's turn is over. + + `params` is ignored: the CLI chooses its own. + """ + rt = await self._open() + await rt.lock.acquire() + paused = False + try: + if self.approve: + try: + hooks.get_hook_registry() + runtime_.get_runtime() + except LookupError: + raise errors.WorkerError( + "approve=True asks through ai.hook, which needs a " + "run: use the worker in ai.Agent.run()" + ) from None + rt.context = contextvars.copy_context() + plan = self._plan(messages) + rt.bridge.set_tools( + [t for t in tools or () if t.kind == "function"] + ) + if rt.pending: + if plan.results: + self._answer(plan.results) + else: + await self._abandon() + if plan.prompt: + if rt.in_session and plan.system: + text = "\n\n".join(plan.system) + "\n\n" + plan.prompt.insert(0, messages_.TextPart(text=text)) + if rt.queue is not None: + # Tool results came with a new user message. The CLI is + # still in its turn: the message is guidance for it. + await rt.adapter.steer(base.text_of(plan.prompt)) + else: + await self._ensure_session(plan) + self._start(plan.prompt, output_type) + if rt.queue is None: + raise ValueError( + "stream(): no new user message or tool result to send" + ) + + stamp = messages_.Message(role="assistant", parts=[]) + hydrator = events_.MessageHydrator() + + def out(event: events_.Event) -> events_.Event: + event = event.model_copy( + update={ + "message": messages_.Message( + id=stamp.id, role="assistant", parts=[] + ) + } + ) + hydrator.feed(event) + return event + + yield out(events_.StreamStart()) + # Text after the last CLI tool call: the answer, for output_type. + answer: list[str] = [] + while True: + item = await rt.queue.get() + if isinstance(item, _Failed): + self._end_turn() + raise item.error + 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: + # Not ours to handle here: put it back. + 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 + ) + ) + paused = True + yield out( + events_.StreamEnd( + finish_reason="tool_call", + provider_metadata=self._metadata(None), + ) + ) + break + if isinstance(item, events_.StreamEnd): + self._end_turn() + usage = item.usage + if output_type is not None: + text, usage = await self._output( + "".join(answer), output_type, usage + ) + yield out(events_.TextStart(block_id="output")) + yield out( + events_.TextDelta(chunk=text, block_id="output") + ) + yield out(events_.TextEnd(block_id="output")) + finish = item.finish_reason + yield out( + events_.StreamEnd( + finish_reason=( + "other" if finish == "cancelled" else finish + ), + usage=usage, + provider_metadata={ + **(item.provider_metadata or {}), + **self._metadata(finish), + }, + ) + ) + break + for event in self._visible(item): + if output_type is not None and isinstance( + event, + events_.TextStart | events_.TextDelta | events_.TextEnd, + ): + # Narration is not the output. Keep only the text + # after the last tool call, and send it once parsed. + if isinstance(event, events_.TextDelta): + answer.append(event.chunk) + continue + if isinstance(event, events_.BuiltinToolStart): + answer.clear() + yield out(event) + # Committed only now: a call that failed can be sent again. + self.messages = [*plan.transcript, hydrator.message] + except (GeneratorExit, asyncio.CancelledError): + if not paused: + # Nobody reads this turn any more: end it in the CLI too. + await self._abandon() + raise + finally: + rt.lock.release() + + # -- the conversation ----------------------------------------------------- + + def _plan(self, messages: list[messages_.Message]) -> _Plan: + """Compare `messages` with the transcript; return what is new.""" + known = [m.id for m in self.messages] + given = [m.id for m in messages] + plan = _Plan() + system = [m.text for m in messages if m.role == "system"] + plan.instructions = "\n\n".join(system) or None + if known: + if given[: len(known)] != known: + raise errors.TranscriptMismatchError( + f"{self.kind}: these messages do not continue this " + "worker's conversation; start a new worker" + ) + new = messages[len(known) :] + plan.transcript = list(self.messages) + elif self.session_id is not None: + # A stored conversation the worker has not loaded: the CLI holds + # the past, so everything given is new. `load()` reads the past. + new = list(messages) + else: + # A new conversation. What comes before the last user turn is + # its past; the CLI is seeded with it before the first turn. + cut = len(messages) + while cut and messages[cut - 1].role in ("user", "system", "tool"): + cut -= 1 + plan.seed = [m for m in messages[:cut] if m.role != "system"] + new = messages[cut:] + plan.transcript = list(messages[:cut]) + for message in new: + 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( + f"{self.kind}: a {message.role} message the worker did " + "not write; only user, system and tool messages can " + "follow its last answer (load() reads a stored past)" + ) + plan.transcript.extend(new) + return plan + + async def _ensure_session(self, plan: _Plan) -> None: + rt = self._require_runtime() + if rt.in_session: + return + self.session_id = await rt.adapter.open( + session_id=self.session_id, + fork=self.fork, + seed=plan.seed if self.session_id is None and plan.seed else None, + instructions=plan.instructions, + ) + self.fork = False + rt.in_session = True + + def _start( + self, + prompt: list[messages_.TextPart | messages_.FilePart], + output_type: type[pydantic.BaseModel] | None, + ) -> None: + rt = self._require_runtime() + if output_type is not None: + schema = json.dumps(TypeAdapter(output_type).json_schema()) + prompt = [ + *prompt, + messages_.TextPart(text=OUTPUT_INSTRUCTION + schema), + ] + queue: asyncio.Queue[Any] = asyncio.Queue() + adapter = rt.adapter + + async def pump() -> None: + try: + async for event in adapter.turn(prompt): + queue.put_nowait(event) + except asyncio.CancelledError: + raise + except BaseException as exc: + queue.put_nowait(_Failed(exc)) + + rt.queue = queue + rt.pump = asyncio.create_task(pump()) + + def _end_turn(self) -> None: + rt = self._require_runtime() + rt.queue = None + rt.pump = None + rt.hidden.clear() + + def _answer(self, results: list[messages_.ToolResultPart]) -> None: + rt = self._require_runtime() + for part in results: + 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 + text = value if isinstance(value, str) else _dump(value) + call.answer.set_result((text, part.result_kind == "error")) + for call in rt.pending.values(): + # A call the caller did not answer: tell the CLI, do not hang. + if not call.answer.done(): + call.answer.set_result(("no result was given", True)) + rt.pending.clear() + + async def _abandon(self) -> None: + """End the running turn: the caller moved on without it.""" + rt = self._runtime + if rt is None: + return + for call in rt.pending.values(): + if not call.answer.done(): + call.answer.set_result(("cancelled by the caller", True)) + rt.pending.clear() + pump = rt.pump + if pump is None: + return + with contextlib.suppress(Exception): + await rt.adapter.interrupt() + pump.cancel() + with contextlib.suppress(BaseException): + await pump + self._end_turn() + + async def _on_call( + self, name: str, arguments: dict[str, Any] + ) -> tuple[str, bool]: + """Hand a bridge call to the caller, and wait for the result.""" + rt = self._runtime + if rt is None or rt.queue is None: + return ("no turn is running", True) + 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]: + """Ask about one of the CLI's own tool calls, through `ai.hook`.""" + if self._is_bridge_tool(tool_name): + # An `ai` tool: the agent gates it itself, if it is gated. + return True, "" + rt = self._runtime + if rt is None or rt.context is None: + return False, "no run to ask in; denied" + + async def ask() -> tuple[bool, str]: + 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, + ) + return approval.granted, approval.reason or "denied" + + # In the caller's context: that is where the run's hooks live. + task = asyncio.create_task(ask(), context=rt.context) + try: + return await task + except asyncio.CancelledError: + current = asyncio.current_task() + if current is not None and current.cancelling(): + raise + return False, "the approval was cancelled" + except Exception as exc: + return False, f"approval failed ({type(exc).__name__}); denied" + + def _is_bridge_tool(self, tool_name: str) -> bool: + """Whether a tool the CLI reports is a bridge call. + + Those reach the caller as `ToolCallPart`s, so the CLI's own report + of them is hidden. Claude Code names an MCP tool + `mcp____`; codex uses the bare name, or the server's + name when the tool name is missing (measured: codex 0.160). How pi + names them is not measured yet: the forms it may use are accepted. + """ + rt = self._runtime + if rt is None: + return False + 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]: + """Drop StreamStart and the CLI's own report of bridge calls.""" + rt = self._require_runtime() + match event: + case events_.StreamStart(): + return [] # a worker message has its own + case events_.BuiltinToolStart(): + if self._is_bridge_tool(event.tool_name): + rt.hidden.add(event.tool_call_id) + 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, + ) -> tuple[str, usage_.Usage | None]: + """Parse the answer, asking again when it does not validate.""" + adapter = self._require_runtime().adapter + parsed, error = _parse(text, output_type) + attempt = 0 + while error is not None and attempt < OUTPUT_RETRIES: + attempt += 1 + retry = messages_.TextPart( + text=f"Your previous reply failed validation: {error}\n" + "Reply again with ONLY the corrected JSON." + ) + chunks: list[str] = [] + async for event in adapter.turn([retry]): + if isinstance(event, events_.BuiltinToolStart): + chunks.clear() + elif isinstance(event, events_.TextDelta): + chunks.append(event.chunk) + elif isinstance(event, events_.StreamEnd) and event.usage: + usage = usage + event.usage if usage else event.usage + text = "".join(chunks) + parsed, error = _parse(text, output_type) + return (parsed.model_dump_json() if parsed else text), usage + + def _metadata(self, finish: str | None) -> dict[str, Any]: + meta: dict[str, Any] = {"kind": self.kind} + if self.session_id: + meta["session_id"] = self.session_id + if finish is not None: + meta["finish_reason"] = finish + return {"worker": meta} + + # -- lifecycle ------------------------------------------------------------ + + async def _open(self) -> _Runtime: + if self._runtime is not None: + return self._runtime + bridge = _bridge.Bridge(self._on_call) + await bridge.start() + servers = { + **self.mcp_servers, + _bridge.SERVER_NAME: {"type": "http", "url": bridge.url}, + } + adapter = self._make_adapter( + servers, self._approve if self.approve else None + ) + try: + await adapter.start() + except BaseException: + await bridge.close() + raise + self._runtime = _Runtime(adapter=adapter, bridge=bridge) + return self._runtime + + async def close(self) -> None: + """End the turn, the CLI and the bridge. The fields stay as they are. + + A closed worker opens again on its next use, and resumes its + conversation. + """ + rt = self._runtime + if rt is None: + return + await self._abandon() + self._runtime = None + try: + await rt.adapter.close() + finally: + await rt.bridge.close() + + async def __aenter__(self) -> Self: + await self._open() + return self + + async def __aexit__(self, *exc_info: object) -> None: + await self.close() + + def _require_runtime(self) -> _Runtime: + if self._runtime is None: + raise errors.WorkerError(f"{self.kind} worker is not open") + return self._runtime + + @property + def version(self) -> str | None: + """What the CLI's `--version` printed, once the worker is open.""" + return self._runtime.adapter.version if self._runtime else None + + # -- what only a CLI has -------------------------------------------------- + + async def load(self) -> None: + """Read the stored conversation `session_id` names into `messages`. + + Also after a person worked in the CLI's TUI (see `tui()`). + """ + if self.session_id is None: + raise errors.WorkerError(f"{self.kind}: no session_id to load") + rt = await self._open() + self.messages = await rt.adapter.history(self.session_id) + + async def steer(self, text: str) -> None: + """Send guidance to the turn that runs now; the agent acts on it. + + For use from another task while `stream()` runs. The text is not + added to `messages`; `load()` reads it back from the CLI. + """ + rt = self._require_runtime() + if rt.queue is None: + raise errors.WorkerError(f"{self.kind}: no turn is running") + await rt.adapter.steer(text) + + def tui_command(self) -> tuple[list[str], dict[str, str]]: + """Return the CLI's own TUI command for this conversation. + + Run it in `cwd`, with the env added to yours:: + + argv, env = worker.tui_command() + subprocess.run(argv, cwd=worker.cwd, env={**os.environ, **env}) + + A worker with no conversation yet gets a new one, when the CLI lets + us choose its id (Claude Code, Pi). Close the worker first: one + writer per conversation. + """ + if self.fork: + raise errors.WorkerError( + f"{self.kind}: run a turn first; the fork happens on first use" + ) + rt = self._runtime + adapter = ( + rt.adapter if rt else self._make_adapter(self.mcp_servers, None) + ) + argv, env, minted = adapter.tui_command(self.session_id) + if self.session_id is None: + if minted is None: + raise errors.WorkerError( + f"{self.kind} picks its own session id: run a turn " + "first, or pass session_id=" + ) + self.session_id = minted + return argv, env + + async def tui(self) -> int: + """Hand the conversation to a person, in this terminal. + + Runs the CLI's TUI on it and returns its exit code once the person + quits. The worker then reads the conversation back (`load()`) and + goes on headless. + """ + await self.close() + argv, env = self.tui_command() + proc = await asyncio.create_subprocess_exec( + *argv, cwd=self.cwd, env={**os.environ, **env} + ) + code = await proc.wait() + await self.load() + return code + + @classmethod + async def list_sessions(cls, **fields: Any) -> list[base.SessionInfo]: + """Return the conversations the CLI has stored for a directory. + + Takes the worker's fields: `cwd=`, `env=`, `executable=`. + """ + worker = cls(**fields) + adapter = worker._make_adapter({}, None) + await adapter.start() + try: + return await adapter.list_sessions() + finally: + await adapter.close() + + +def _parse( + text: str, output_type: type[pydantic.BaseModel] +) -> 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: + """Best effort: the model was told "only JSON", but fences happen.""" + 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/tests/workers/__init__.py b/tests/workers/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/tests/workers/_adapters/__init__.py b/tests/workers/_adapters/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/tests/workers/_adapters/test_codex.py b/tests/workers/_adapters/test_codex.py new file mode 100644 index 00000000..de1fedb9 --- /dev/null +++ b/tests/workers/_adapters/test_codex.py @@ -0,0 +1,384 @@ +"""The codex adapter against a scripted `codex app-server`, offline.""" + +from __future__ import annotations + +import asyncio +import json +from collections.abc import Callable +from typing import Any, cast + +import pytest + +from ai import workers +from ai.types import events +from ai.types import messages as m +from ai.workers._adapters import codex, jsonrpc + +from .. import fakes + +THREAD = "T" +CWD = "/w" + + +class AppServer: + """Answers like `codex app-server`. `turn` plays out after turn/start.""" + + def __init__(self, turn: list[dict[str, Any]] | None = None) -> None: + self.process = fakes.FakeProcess(self.answer) + self.turn = turn or [] + self.on_turn: Callable[[], None] | None = None + self.threads: dict[str, dict[str, Any]] = { + THREAD: {"id": THREAD, "cwd": CWD, "turns": []} + } + + def says(self, method: str, **params: Any) -> None: + self.process.server_says({"method": method, "params": params}) + + def answer(self, message: dict[str, Any]) -> Any: + method = message.get("method") + params = message.get("params") or {} + if method == "turn/start": + if self.on_turn is not None: + self.on_turn() + for record in self.turn: + self.process.server_says(record) + return {"turn": {"id": "turn-1"}} + if method == "turn/interrupt": + self.says( + "turn/completed", + threadId=THREAD, + turn={"id": "turn-1", "status": "interrupted"}, + ) + return {} + if method == "thread/read": + return {"thread": self.threads.get(str(params.get("threadId")), {})} + if method in ("thread/start", "thread/fork"): + return {"thread": {"id": "new"}} + if method == "thread/resume": + return {"thread": {"id": params["threadId"]}} + if "method" in message and "id" in message: + return {} + return None + + def sent(self, method: str) -> list[dict[str, Any]]: + return [w for w in self.process.written if w.get("method") == method] + + +def note(method: str, **params: Any) -> dict[str, Any]: + return { + "method": method, + "params": {"threadId": THREAD, "turnId": "turn-1", **params}, + } + + +COMMAND = { + "type": "commandExecution", + "id": "c1", + "command": "/bin/zsh -lc 'cat secret.txt'", + "aggregatedOutput": "the word is HERON\n", + "exitCode": 0, + "status": "completed", +} + +TURN = [ + note("item/reasoning/summaryTextDelta", itemId="r1", delta="plan"), + note("item/completed", item={"type": "reasoning", "id": "r1"}), + note("item/started", item={**COMMAND, "aggregatedOutput": None}), + note("item/completed", item=COMMAND), + note("item/agentMessage/delta", itemId="a1", delta="HER"), + note("item/agentMessage/delta", itemId="a1", delta="ON"), + note("item/completed", item={"type": "agentMessage", "id": "a1"}), + note( + "thread/tokenUsage/updated", + tokenUsage={"lastTurn": {"inputTokens": 10, "outputTokens": 4}}, + ), + note("turn/completed", turn={"id": "turn-1", "status": "completed"}), +] + + +def _adapter( + server: AppServer, approve: Any = None, **options: Any +) -> codex.CodexAdapter: + adapter = codex.CodexAdapter( + cwd=CWD, + env={}, + executable="codex", + model=None, + mcp_servers=options.pop("mcp_servers", {}), + approve=approve, + sandbox=None, + config={}, + ) + peer = jsonrpc.JsonRpcPeer(cast("Any", server.process), kind="codex") + adapter._process = cast("Any", server.process) + adapter._peer = peer + adapter._thread = THREAD + peer.start( + adapter._on_notify, adapter._on_request, on_crash=adapter._on_crash + ) + return adapter + + +async def _turn(adapter: codex.CodexAdapter, text: str = "go") -> list[Any]: + async with asyncio.timeout(5): + return [e async for e in adapter.turn([m.TextPart(text=text)])] + + +async def test_a_turn_streams_in_the_model_view() -> None: + adapter = _adapter(AppServer(TURN)) + seen = await _turn(adapter) + assert [type(e).__name__ for e in seen] == [ + "StreamStart", + "ReasoningStart", + "ReasoningDelta", + "ReasoningEnd", + "BuiltinToolStart", + "BuiltinToolDelta", + "BuiltinToolEnd", + "BuiltinToolResult", + "TextStart", + "TextDelta", + "TextDelta", + "TextEnd", + "StreamEnd", + ] + result = next(e for e in seen if isinstance(e, events.BuiltinToolResult)) + # codex 0.160 reports a command's output as `aggregatedOutput`. + assert result.result.result == "the word is HERON\n" + end = seen[-1] + assert end.finish_reason == "stop" + assert end.usage.input_tokens == 10 + hydrator = events.MessageHydrator() + for event in seen: + hydrator.feed(event) + assert [type(p).__name__ for p in hydrator.message.parts] == [ + "ReasoningPart", + "BuiltinToolCallPart", + "BuiltinToolReturnPart", + "TextPart", + ] + + +async def test_a_message_that_was_never_streamed_still_arrives() -> None: + server = AppServer( + [ + note( + "item/completed", + item={"type": "agentMessage", "id": "a1", "text": "PONG"}, + ), + note( + "turn/completed", turn={"id": "turn-1", "status": "completed"} + ), + ] + ) + seen = await _turn(_adapter(server)) + assert [e.chunk for e in seen if isinstance(e, events.TextDelta)] == [ + "PONG" + ] + + +async def test_another_turns_notifications_are_not_this_turns() -> None: + server = AppServer( + [ + { + "method": "turn/completed", + "params": {"threadId": THREAD, "turn": {"id": "old"}}, + }, + { + "method": "item/agentMessage/delta", + "params": {"threadId": "other", "itemId": "x", "delta": "no"}, + }, + note( + "turn/completed", turn={"id": "turn-1", "status": "completed"} + ), + ] + ) + seen = await _turn(_adapter(server)) + assert [type(e).__name__ for e in seen] == ["StreamStart", "StreamEnd"] + + +async def test_a_failed_turn_without_a_key_is_not_authenticated() -> None: + server = AppServer( + [ + note("error", error={"message": "401 Unauthorized"}), + note("turn/completed", turn={"id": "turn-1", "status": "failed"}), + ] + ) + with pytest.raises(workers.NotAuthenticatedError): + await _turn(_adapter(server)) + + +@pytest.mark.parametrize("granted", [True, False]) +async def test_approvals_ask_and_answer(granted: bool) -> None: + server = AppServer() + asked: list[tuple[str, str, dict[str, Any]]] = [] + + async def approve( + call_id: str, name: str, tool_input: dict[str, Any] + ) -> tuple[bool, str]: + asked.append((call_id, name, tool_input)) + return granted, "no" + + def ask() -> None: + server.process.server_says( + { + "id": 500, + "method": "item/commandExecution/requestApproval", + "params": { + "threadId": THREAD, + "turnId": "turn-1", + "itemId": "i1", + "command": "rm -rf /", + }, + } + ) + + def complete(message: dict[str, Any]) -> Any: + if message.get("id") == 500: + server.says( + "turn/completed", + threadId=THREAD, + turn={"id": "turn-1", "status": "completed"}, + ) + return None + return AppServer.answer(server, message) + + server.on_turn = ask + server.process.answer = complete + adapter = _adapter(server, approve) + assert adapter._thread_params()["approvalPolicy"] == "untrusted" + await _turn(adapter) + assert asked == [("i1", "commandExecution", {"command": "rm -rf /"})] + answer = next(w for w in server.process.written if w.get("id") == 500) + assert answer["result"] == {"decision": "accept" if granted else "decline"} + + +async def test_without_a_gate_codex_never_asks() -> None: + adapter = _adapter(AppServer()) + assert adapter._thread_params() == { + "sandbox": "danger-full-access", + "approvalPolicy": "never", + } + + +async def test_an_interrupted_turn_ends_as_cancelled() -> None: + server = AppServer() + adapter = _adapter(server) + turn = adapter.turn([m.TextPart(text="go")]) + assert isinstance(await anext(turn), events.StreamStart) + reader = asyncio.ensure_future(_rest(turn)) + await asyncio.sleep(0) + await adapter.interrupt() + seen = await asyncio.wait_for(reader, 5) + assert seen[-1].finish_reason == "cancelled" + assert server.sent("turn/interrupt")[0]["params"] == { + "threadId": THREAD, + "turnId": "turn-1", + } + + +async def _rest(turn: Any) -> list[Any]: + return [e async for e in turn] + + +async def test_opening_a_new_thread_seeds_it() -> None: + server = AppServer() + adapter = _adapter(server) + seed = [ + m.Message(role="user", parts=[m.TextPart(text="earlier")]), + m.Message(role="assistant", parts=[m.TextPart(text="answer")]), + ] + assert ( + await adapter.open( + session_id=None, fork=False, seed=seed, instructions="Be terse." + ) + == "new" + ) + started = server.sent("thread/start")[0]["params"] + assert started["cwd"] == CWD + assert started["developerInstructions"] == "Be terse." + injected = server.sent("thread/inject_items")[0]["params"] + assert injected["threadId"] == "new" + assert [i["role"] for i in injected["items"]] == ["user", "assistant"] + + +async def test_a_fork_is_native() -> None: + server = AppServer() + adapter = _adapter(server) + forked = await adapter.open( + session_id=THREAD, fork=True, seed=None, instructions=None + ) + assert forked == "new" + assert server.sent("thread/fork")[0]["params"]["threadId"] == THREAD + + +async def test_a_thread_from_another_directory_is_refused() -> None: + server = AppServer() + server.threads["elsewhere"] = {"id": "elsewhere", "cwd": "/other"} + adapter = _adapter(server) + with pytest.raises(workers.WorkerError, match="/other"): + await adapter.open( + session_id="elsewhere", fork=False, seed=None, instructions=None + ) + + +async def test_history_is_the_model_view() -> None: + server = AppServer() + server.threads[THREAD]["turns"] = [ + { + "items": [ + { + "type": "userMessage", + "content": [{"type": "text", "text": "q"}], + }, + COMMAND, + {"type": "agentMessage", "text": "HERON"}, + ] + } + ] + history = await _adapter(server).history(THREAD) + assert [x.role for x in history] == ["user", "assistant", "assistant"] + call, result = history[1].parts + assert isinstance(call, m.BuiltinToolCallPart) + assert json.loads(call.tool_args)["command"].endswith("'cat secret.txt'") + assert isinstance(result, m.BuiltinToolReturnPart) + assert result.result == "the word is HERON\n" + + +async def test_listing_asks_for_this_directory_and_reads_every_page() -> None: + """`thread/list` is paged, and the store is the whole machine's.""" + asked: list[dict[str, Any]] = [] + pages = { + None: ({"id": "t1", "cwd": CWD}, "p2"), + "p2": ({"id": "t2", "cwd": CWD}, None), + } + server = AppServer() + + def answer(message: dict[str, Any]) -> Any: + if message.get("method") != "thread/list": + return AppServer.answer(server, message) + params = message["params"] + asked.append(params) + thread, cursor = pages[params.get("cursor")] + return {"data": [thread], "nextCursor": cursor} + + server.process.answer = answer + infos = await _adapter(server).list_sessions() + assert [i.session_id for i in infos] == ["t1", "t2"] + assert all(p["cwd"] == CWD for p in asked) + assert [p.get("cursor") for p in asked] == [None, "p2"] + + +async def test_the_tui_gets_no_bridge() -> None: + adapter = _adapter( + AppServer(), + mcp_servers={ + "ai_sdk": {"url": "http://127.0.0.1:1/mcp"}, + "docs": {"command": "docs-mcp"}, + }, + ) + argv, _, minted = adapter.tui_command(THREAD) + assert argv[:3] == ["codex", "resume", THREAD] + assert 'mcp_servers.docs.command="docs-mcp"' in argv + assert not any("ai_sdk" in arg for arg in argv) + assert minted is None # codex picks its own ids diff --git a/tests/workers/_adapters/test_handoff.py b/tests/workers/_adapters/test_handoff.py new file mode 100644 index 00000000..4f55dadd --- /dev/null +++ b/tests/workers/_adapters/test_handoff.py @@ -0,0 +1,234 @@ +"""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). The CLI's own tools arrive as built-in parts. +""" + +from __future__ import annotations + +import json + +from ai.types.messages import ( + BuiltinToolCallPart, + BuiltinToolReturnPart, + Message, + ReasoningPart, + TextPart, + ToolCallPart, + ToolResultPart, +) +from ai.workers._adapters import _handoff + +HISTORY = [ + 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, the way a worker holds it. +MODEL_VIEW = [ + HISTORY[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} + ), + ], + ), + HISTORY[3], +] + + +def test_codex_items_follow_the_rule() -> None: + items = _handoff.to_codex_items(HISTORY) + 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(_handoff.NOTE_PREFIX) + assert "Write is the tool" in note + + +def test_the_model_view_seeds_the_same_items() -> None: + assert _handoff.to_codex_items(MODEL_VIEW) == _handoff.to_codex_items( + HISTORY + ) + + +def test_claude_records_follow_the_rule() -> None: + recs = _handoff.to_claude_records(MODEL_VIEW, "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(MODEL_VIEW) == 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 = _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_model_view_and_harness_view_are_inverse() -> None: + model = _handoff.model_view(HISTORY) + assert [m.role for m in model] == ["user", "assistant", "assistant"] + parts = model[1].parts + assert isinstance(parts[2], BuiltinToolCallPart) + assert isinstance(parts[3], BuiltinToolReturnPart) + assert parts[3].result == {"ok": True} + back = _handoff.harness_view(model) + assert [m.role for m in back] == ["user", "assistant", "tool", "assistant"] + assert isinstance(back[2].parts[0], ToolResultPart) + + +def test_text_after_a_cli_tool_stays_after_its_result() -> None: + 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."), + ], + ) + first, result, after = _handoff.harness_view([one]) + assert (first.role, result.role, after.role) == ( + "assistant", + "tool", + "assistant", + ) + assert first.id == one.id and after.id != one.id + assert after.text == "It says x." + + +def test_a_stored_result_without_a_name_takes_its_calls() -> None: + stored = [ + Message( + role="assistant", + parts=[ + ToolCallPart(tool_call_id="c", tool_name="Read", tool_args="") + ], + ), + Message( + role="tool", + parts=[ToolResultPart(tool_call_id="c", tool_name="", result="x")], + ), + ] + (message,) = _handoff.model_view(stored) + result = message.parts[1] + assert isinstance(result, BuiltinToolReturnPart) + assert result.tool_name == "Read" + + +def test_reasoning_is_never_the_agents_own_thought() -> None: + """No thinking block, no reasoning item: both were measured to fail, + one rejected, one silently ignored. It travels as a note, or not at all.""" + items = _handoff.to_codex_items(HISTORY) + assert not any(i["type"] == "reasoning" for i in items) + blocks = [ + b + for r in _handoff.to_claude_records(HISTORY, "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 _handoff.to_codex_items(blank) == [] + empty = [Message(role="assistant", parts=[ReasoningPart(text="")])] + assert _handoff.to_claude_records(empty, "s", "/w") == [] diff --git a/tests/workers/_adapters/test_jsonrpc.py b/tests/workers/_adapters/test_jsonrpc.py new file mode 100644 index 00000000..a6849316 --- /dev/null +++ b/tests/workers/_adapters/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._adapters 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..51ed6b6c --- /dev/null +++ b/tests/workers/fakes.py @@ -0,0 +1,231 @@ +"""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._adapters import base + + +@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 [ + *base.builtin_call(call_id, name, args, started=set()), + base.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: base.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() + + 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: + return f"{session_id}-fork" + return session_id or "s1" + + async def turn(self, prompt: base.Prompt) -> AsyncIterator[events.Event]: + self.turns.append(base.text_of(prompt)) + self._resume.clear() + yield events.StreamStart() + for step in self.script(base.text_of(prompt)): + if isinstance(step, Pause): + await self._resume.wait() + yield events.StreamEnd(finish_reason="cancelled") + return + if isinstance(step, Run): + await step.fn() + elif isinstance(step, Ask): + assert self.approve is not None + self.answers.append( + await self.approve( + step.tool_call_id, step.tool_name, step.tool_input + ) + ) + else: + yield step + yield events.StreamEnd( + finish_reason="stop", + usage=usage_.Usage(input_tokens=3, output_tokens=2), + ) + + async def steer(self, text: str) -> None: + self.steers.append(text) + + async def interrupt(self) -> None: + self.interrupts += 1 + self._resume.set() + + async def history(self, session_id: str) -> list[m.Message]: + return self.stored.get(session_id, []) + + async def list_sessions(self) -> list[base.SessionInfo]: + return [base.SessionInfo(session_id="s1", title="first")] + + def tui_command( + self, 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.""" + + kind: Literal["fake"] = "fake" + _script: Script = pydantic.PrivateAttr(default_factory=lambda: reply) + _fake: FakeAdapter | None = pydantic.PrivateAttr(default=None) + _servers: dict[str, dict[str, Any]] = pydantic.PrivateAttr( + default_factory=dict + ) + + def _make_adapter( + self, + mcp_servers: dict[str, dict[str, Any]], + approve: base.Approve | None, + ) -> base.Adapter: + self._fake = FakeAdapter(self._run, approve) + self._servers = mcp_servers + return self._fake + + 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]] = [] + self.pid = 0 + + 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/test_worker.py b/tests/workers/test_worker.py new file mode 100644 index 00000000..299cf600 --- /dev/null +++ b/tests/workers/test_worker.py @@ -0,0 +1,569 @@ +"""`ai.workers.Worker` over a scripted adapter: no real CLI runs here.""" + +from __future__ import annotations + +import asyncio +import json +from collections.abc import 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 _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.fake.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_a_failed_call_can_be_sent_again( + worker: fakes.FakeWorker, +) -> None: + def boom(prompt: str) -> list[fakes.Step]: + raise RuntimeError("boom") + + worker.script(boom) + messages = [ai.user_message("one")] + async with worker: + with pytest.raises(RuntimeError, match="boom"): + await ai.experimental_generate(worker, messages) + assert worker.messages == [] + worker.script(fakes.reply) + again = await ai.experimental_generate(worker, messages) + assert again.text == "one" + + +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_kind_is_refused() -> None: + with pytest.raises(pydantic.ValidationError): + workers.Worker.model_validate({"kind": "nope"}) + + +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_load_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.load() + assert worker.messages == stored + await ai.experimental_generate( + worker, [*worker.messages, ai.user_message("now")] + ) + assert worker.fake.turns == ["now"] + + +async def test_a_copy_with_fork_branches_natively( + worker: fakes.FakeWorker, +) -> None: + async with worker: + await ai.experimental_generate(worker, [ai.user_message("one")]) + branch = worker.model_copy(update={"fork": True}) + async with branch: + assert branch.fake is not worker.fake # a CLI of its own + await ai.experimental_generate( + branch, [*branch.messages, ai.user_message("two")] + ) + assert branch.fake.opens[0] == { + "session_id": "s1", + "fork": True, + "seed": None, + "instructions": None, + } + assert branch.session_id == "s1-fork" + assert branch.fork is False + assert 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"]["kind"] == "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" + + +# -- 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 + + +async def test_approve_needs_a_run() -> None: + worker = fakes.FakeWorker(approve=True) + async with worker: + with pytest.raises(workers.WorkerError, match=r"ai\.Agent\.run"): + await ai.experimental_generate(worker, [ai.user_message("go")]) + + +# -- steer, the TUI, the store ------------------------------------------------ + + +async def test_steer_reaches_the_running_turn( + worker: fakes.FakeWorker, +) -> None: + worker.script(lambda prompt: [*fakes.text("working"), fakes.Pause()]) + async with worker: + with pytest.raises(workers.WorkerError): + await worker.steer("too early") + async with ai.stream(worker, [ai.user_message("go")]) as s: + async for event in s: + if isinstance(event, events.TextEnd): + await worker.steer("use tabs") + await worker.fake.interrupt() + assert worker.fake.steers == ["use tabs"] + + +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.load() + 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() From 07e84618e5914befcdb01af6a6795c83fb9cf2d8 Mon Sep 17 00:00:00 2001 From: Andrey Buzin Date: Thu, 5 Nov 2026 19:04:58 -0800 Subject: [PATCH 3/6] Add Claude Code and Pi workers --- examples/workers/agent_tools.py | 6 +- examples/workers/approvals.py | 6 +- examples/workers/streaming.py | 6 +- pyproject.toml | 11 + src/ai/providers/_optional.py | 16 +- src/ai/workers/__init__.py | 10 +- src/ai/workers/_adapters/claude.py | 631 ++++++++++++ src/ai/workers/_adapters/pi.py | 1111 ++++++++++++++++++++++ src/ai/workers/_adapters/pi_extension.js | 88 ++ src/ai/workers/_kinds.py | 75 +- src/ai/workers/_worker.py | 4 +- tests/workers/_adapters/test_claude.py | 317 ++++++ tests/workers/_adapters/test_pi.py | 554 +++++++++++ tests/workers/test_live.py | 137 +++ uv.lock | 41 +- 15 files changed, 2994 insertions(+), 19 deletions(-) create mode 100644 src/ai/workers/_adapters/claude.py create mode 100644 src/ai/workers/_adapters/pi.py create mode 100644 src/ai/workers/_adapters/pi_extension.js create mode 100644 tests/workers/_adapters/test_claude.py create mode 100644 tests/workers/_adapters/test_pi.py create mode 100644 tests/workers/test_live.py diff --git a/examples/workers/agent_tools.py b/examples/workers/agent_tools.py index 3885abe7..f56bef4c 100644 --- a/examples/workers/agent_tools.py +++ b/examples/workers/agent_tools.py @@ -3,7 +3,7 @@ The CLI calls `lookup_order`. The worker hands the call to the agent, the agent runs the tool, and the CLI gets the result and goes on. - uv run python examples/workers/agent_tools.py [codex] + uv run python examples/workers/agent_tools.py [claude-code|codex|pi] """ import asyncio @@ -14,7 +14,9 @@ from ai import workers KINDS: dict[str, Callable[..., workers.Worker]] = { + "claude-code": workers.ClaudeCode, "codex": workers.Codex, + "pi": workers.Pi, } @@ -47,4 +49,4 @@ async def main(kind: str) -> None: print([m.role for m in run.messages]) -asyncio.run(main(sys.argv[1] if len(sys.argv) > 1 else "codex")) +asyncio.run(main(sys.argv[1] if len(sys.argv) > 1 else "claude-code")) diff --git a/examples/workers/approvals.py b/examples/workers/approvals.py index 348a47b2..0d71f625 100644 --- a/examples/workers/approvals.py +++ b/examples/workers/approvals.py @@ -3,7 +3,7 @@ With `approve=True`, every tool call the CLI makes becomes a `ToolApproval` hook. Answer it with `ai.resolve_hook`, the way any tool approval is. - uv run python examples/workers/approvals.py [codex] + uv run python examples/workers/approvals.py [claude-code|codex|pi] """ import asyncio @@ -14,7 +14,9 @@ from ai import workers KINDS: dict[str, Callable[..., workers.Worker]] = { + "claude-code": workers.ClaudeCode, "codex": workers.Codex, + "pi": workers.Pi, } @@ -39,4 +41,4 @@ async def main(kind: str) -> None: print() -asyncio.run(main(sys.argv[1] if len(sys.argv) > 1 else "codex")) +asyncio.run(main(sys.argv[1] if len(sys.argv) > 1 else "claude-code")) diff --git a/examples/workers/streaming.py b/examples/workers/streaming.py index a5239cd3..feb01d65 100644 --- a/examples/workers/streaming.py +++ b/examples/workers/streaming.py @@ -1,6 +1,6 @@ """A worker where a model goes: stream it, then continue the conversation. -uv run python examples/workers/streaming.py [codex] +uv run python examples/workers/streaming.py [claude-code|codex|pi] """ import asyncio @@ -11,7 +11,9 @@ from ai import workers KINDS: dict[str, Callable[..., workers.Worker]] = { + "claude-code": workers.ClaudeCode, "codex": workers.Codex, + "pi": workers.Pi, } @@ -49,4 +51,4 @@ async def main(kind: str) -> None: print(reply.text) -asyncio.run(main(sys.argv[1] if len(sys.argv) > 1 else "codex")) +asyncio.run(main(sys.argv[1] if len(sys.argv) > 1 else "claude-code")) diff --git a/pyproject.toml b/pyproject.toml index 2bbe0863..a22eab04 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -35,6 +35,7 @@ dependencies = [ [project.optional-dependencies] anthropic = ["anthropic>=0.83.0,<2.0.0"] +claude-code = ["claude-agent-sdk>=0.2.144,<0.3"] mcp = ["mcp>=2.0.0,<3.0.0"] openai = ["openai>=2.34.0,<4.0.0"] otel = [ @@ -69,6 +70,7 @@ bump = true [dependency-groups] dev = [ "anthropic>=0.83.0", + "claude-agent-sdk>=0.2.144,<0.3", "mcp>=2.0.0,<3.0.0", "python-dotenv>=1.2.1", "pytest>=8.0", @@ -82,6 +84,7 @@ dev = [ "vercel-oidc>=0.8.0", "opentelemetry-sdk>=1.43.0", "opentelemetry-exporter-otlp-proto-http>=1.43.0", + "pytest-timeout>=2.3", "typesafe-sdk>=0.7.2", ] @@ -115,6 +118,14 @@ exclude = [ [tool.pytest.ini_options] asyncio_mode = "auto" testpaths = ["tests"] +# Live worker tests drive real agent CLIs, so they are opt-in: +# `uv run pytest -m live tests/workers` (a later -m overrides this one). +addopts = "-m 'not live'" +# A live test drives a real agent; hanging must be a failure. +timeout = 300 +markers = [ + "live: drives a real Claude Code, Codex or Pi (deselect with -m 'not live')", +] filterwarnings = [ "ignore:'asyncio\\.DefaultEventLoopPolicy' is deprecated.*:DeprecationWarning:async_solipsism\\.loop", ] diff --git a/src/ai/providers/_optional.py b/src/ai/providers/_optional.py index d3f48140..5ee15265 100644 --- a/src/ai/providers/_optional.py +++ b/src/ai/providers/_optional.py @@ -12,17 +12,25 @@ def import_optional_sdk( - module_name: str, *, provider: str, extra: str + module_name: str, + *, + provider: str | None = None, + extra: str, + feature: str | None = None, ) -> ModuleType: - """Import an optional upstream SDK or raise a helpful installation error.""" + """Import an optional upstream SDK or raise a helpful installation error. + + ``feature`` names what needs the SDK when it is not a provider. + """ root_module = module_name.partition(".")[0] + feature = feature or f"the {provider} provider" try: return importlib.import_module(module_name) except ModuleNotFoundError as exc: if exc.name not in {module_name, root_module}: raise raise ai_errors.InstallationError( - f"could not import `{root_module}`, which is required to use the " - f"{provider} provider, you can install it with `pip install " + f"could not import `{root_module}`, which is required to use " + f"{feature}, you can install it with `pip install " f'"ai[{extra}]"` or `uv add "ai[{extra}]"`' ) from exc diff --git a/src/ai/workers/__init__.py b/src/ai/workers/__init__.py index 058a3b95..2b66dac4 100644 --- a/src/ai/workers/__init__.py +++ b/src/ai/workers/__init__.py @@ -1,4 +1,4 @@ -"""Coding-agent CLIs as workers. +"""Coding-agent CLIs as workers: Claude Code, Codex and Pi. Experimental: not part of the stable API, may change or be removed. @@ -7,7 +7,7 @@ import ai from ai import workers - async with workers.Codex(model="gpt-5.5") as worker: + async with workers.ClaudeCode(model="sonnet") as worker: async with ai.stream(worker, [ai.user_message("Fix the tests")]) as s: async for event in s: ... @@ -20,7 +20,7 @@ A worker is a pydantic model: `worker.model_dump()` saves the conversation, `workers.Worker.model_validate(data)` continues it, `worker.model_copy()` is -a new worker on the same settings, and `Codex(session_id=...)` resumes +a new worker on the same settings, and `ClaudeCode(session_id=...)` resumes a conversation the CLI has stored. """ @@ -31,13 +31,15 @@ TranscriptMismatchError, WorkerError, ) -from ._kinds import Codex +from ._kinds import ClaudeCode, Codex, Pi from ._worker import Worker __all__ = [ + "ClaudeCode", "Codex", "ExecutableMissingError", "NotAuthenticatedError", + "Pi", "SessionInfo", "TranscriptMismatchError", "Worker", diff --git a/src/ai/workers/_adapters/claude.py b/src/ai/workers/_adapters/claude.py new file mode 100644 index 00000000..7ca08b65 --- /dev/null +++ b/src/ai/workers/_adapters/claude.py @@ -0,0 +1,631 @@ +"""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 AsyncIterator +from typing import Any + +import claude_agent_sdk + +from ...types import events as events_ +from ...types import messages as messages_ +from ...types import usage as usage_ +from .. import _bridge +from .. import _errors as errors +from . import _handoff, base + +KIND = "claude-code" +INSTALL = "npm install -g @anthropic-ai/claude-code" +VERIFIED_VERSION = "2.1.289" +"""The CLI the live tests last passed against. Older ones get a warning.""" + +APPROVAL_TIMEOUT = 24 * 3600 +"""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.""" + +AUTH_HINT = ( + "claude-code uses your own login: run `claude` once and sign in, or " + "pass env={'ANTHROPIC_API_KEY': ...}." +) + + +class ClaudeAdapter: + def __init__( + self, + *, + cwd: str, + env: dict[str, str], + executable: str, + model: str | None, + effort: str | None, + mcp_servers: dict[str, Any], + approve: base.Approve | None, + allowed_tools: list[str] | None, + disallowed_tools: list[str] | None, + max_turns: int | None, + ) -> None: + # The CLI keys its store by the real path of its directory. + self._cwd = os.path.realpath(cwd) + self._env = env + self._executable = executable + self._model = model + self._effort = effort + self._mcp_servers = mcp_servers + self._approve = approve + self._allowed_tools = allowed_tools + self._disallowed_tools = disallowed_tools + self._max_turns = max_turns + self._instructions: str | None = None + self._client: Any = None + self._session_id: str | None = None + # We interrupted the turn. The CLI reports an error result after an + # interrupt, and a stop we asked for must not raise as a failure. + self._interrupted = False + # A turn is running: prompted, no ResultMessage yet. A steer outside + # one would start a turn of its own (measured). + self._running = False + self.version: str | None = None + + async def start(self) -> None: + self.version = await base.probe( + KIND, + self._executable, + install=INSTALL, + verified=VERIFIED_VERSION, + cwd=self._cwd, + env=self._env, + ) + + async def close(self) -> None: + client, self._client = self._client, None + if client is not None: + with contextlib.suppress(Exception): + await client.disconnect() + + # -- the conversation ----------------------------------------------------- + + async def 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) + 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) + self._session_id = 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.""" + 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. + """ + 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: + options: dict[str, Any] = { + "cwd": self._cwd, + # 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: + options["model"] = self._model + 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._approve 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._approve is not None + granted, reason = await self._approve( + 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: + assert self._approve is not None + granted, reason = await self._approve( + 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 turn(self, prompt: base.Prompt) -> AsyncIterator[events_.Event]: + base.check_files(prompt, KIND, ("image/", "application/pdf")) + client = self._client + assert client is not None + # An interrupted turn leaves its trailing result unread: the CLI + # still emits one after the interrupt. Read it first, or THIS turn + # would settle on the previous turn's ending. + 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._running = True + try: + # StreamStart once the CLI answers: its first message proves it + # read the prompt. + started = False + async for message in _guard(client.receive_response()): + if not started: + started = True + yield events_.StreamStart() + if isinstance(message, claude_agent_sdk.StreamEvent): + # Text and reasoning stream here, token by token. The + # AssistantMessage that follows repeats them, so only + # tool calls are taken from it. + 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 base.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 base.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): + self._running = False + interrupted, self._interrupted = self._interrupted, False + yield events_.StreamEnd( + usage=_usage(message), + finish_reason=_finish_reason( + message, interrupted=interrupted + ), + ) + finally: + self._running = False + + async def _drain_interrupted(self) -> None: + if not self._interrupted or self._client is None: + return + self._interrupted = False + with contextlib.suppress(Exception): + async with asyncio.timeout(30): + async for message in self._client.receive_response(): + if isinstance(message, claude_agent_sdk.ResultMessage): + break + + async def steer(self, text: str) -> None: + # `query()` writes straight to the CLI's stdin, so a message can + # land while the turn is still running. + if not self._running or self._client is None: + raise errors.WorkerError(f"{KIND}: no turn is running to steer") + await self._client.query(text) + + async def 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 history(self, session_id: str) -> list[messages_.Message]: + """Read the CLI's own transcript, every content block included.""" + await self._require_known(session_id) + stored = await asyncio.to_thread( + claude_agent_sdk.get_session_messages, session_id, self._cwd + ) + out: list[messages_.Message] = [] + for record in stored: + out.extend(_stored_to_messages(record)) + return _handoff.model_view(out) + + async def list_sessions(self) -> list[base.SessionInfo]: + infos = await asyncio.to_thread( + claude_agent_sdk.list_sessions, self._cwd + ) + return [ + base.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 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: + argv += ["--model", self._model] + 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 + + +async def _content(prompt: base.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 base.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 base.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.""" + 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.""" + try: + 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 _stored_to_messages(record: Any) -> list[messages_.Message]: + """One stored transcript record -> messages, shaped like a live turn's. + + Tool results become their own `tool` message; `_handoff.model_view` + then folds them into the model view. + """ + 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] = [] + tool_results: list[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_.ToolCallPart( + tool_call_id=block.get("id", ""), + tool_name=block.get("name", ""), + tool_args=json.dumps(block.get("input") or {}), + ) + ) + elif kind == "tool_result": + tool_results.append( + messages_.ToolResultPart( + tool_call_id=block.get("tool_use_id", ""), + tool_name="", + result=block.get("content"), + result_kind="error" if block.get("is_error") else "json", + ) + ) + out: list[messages_.Message] = [] + if parts and role in ("user", "assistant"): + out.append(messages_.Message(role=role, parts=parts)) + if tool_results: + out.append(messages_.Message(role="tool", parts=tool_results)) + return out diff --git a/src/ai/workers/_adapters/pi.py b/src/ai/workers/_adapters/pi.py new file mode 100644 index 00000000..6c64c731 --- /dev/null +++ b/src/ai/workers/_adapters/pi.py @@ -0,0 +1,1111 @@ +"""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 (`pi_extension.js`): its `tool_call` handler asks through an +RPC dialog, and this adapter 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 AsyncIterator +from typing import Any + +from ...types import events as events_ +from ...types import messages as messages_ +from ...types import usage as usage_ +from .. import _bridge +from .. import _errors as errors +from . import _handoff, base + +KIND = "pi" +INSTALL = "npm install -g @earendil-works/pi-coding-agent" +VERIFIED_VERSION = "1.3.0" +"""The CLI the live tests last passed against. Older ones get a warning.""" +EXTENSION = str(pathlib.Path(__file__).with_name("pi_extension.js")) +APPROVE = "ai-python:approve" +"""The dialog title the extension asks approvals under.""" +READY = "ai-python-ready" +"""The command the extension registers last: proof that it loaded.""" +CONFIG_VAR = "AI_PYTHON_PI" +"""The environment variable that configures the extension.""" +SESSION_ID = re.compile(r"[A-Za-z0-9](?:[A-Za-z0-9._-]{0,198}[A-Za-z0-9])?\Z") +"""pi's rule for a session id: letters, digits, `.`, `_` and `-`, starting +and ending with a letter or digit. Never a path.""" +DIALOGS = ("select", "confirm", "input", "editor") +"""Extension UI methods that wait for an answer; the rest are notices.""" +CRASHED = "__crashed__" +CLOSED = "__closed__" + +AUTH_HINT = ( + "pi uses its own login (`/login`, auth.json) or a provider key in the " + "environment: pass env={'ANTHROPIC_API_KEY': ...}." +) + + +class PiAdapter: + def __init__( + self, + *, + cwd: str, + env: dict[str, str], + executable: str, + model: str | None, + effort: str | None, + mcp_servers: dict[str, Any], + approve: base.Approve | None, + allowed_tools: list[str] | None, + disallowed_tools: list[str] | None, + ) -> None: + self._cwd = cwd + self._env = env + self._executable = executable + self._model = model + self._effort = effort + self._mcp_servers = mcp_servers + self._approve = approve + self._allowed_tools = allowed_tools + self._disallowed_tools = disallowed_tools + self._instructions: str | None = None + self._agent: _Agent | None = None + # We ended the turn: it settles as cancelled. + self._interrupted = False + # A prompt was accepted and no `agent_settled` came yet. + self._running = False + self.version: str | None = None + + async def start(self) -> None: + self.version = await base.probe( + KIND, + self._executable, + install=INSTALL, + verified=VERIFIED_VERSION, + cwd=self._cwd, + env=self._env, + ) + + async def close(self) -> None: + agent, self._agent = self._agent, None + self._running = False + 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: + args += ["--model", self._model] + 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 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 base.spawn( + [self._executable, "--mode", "rpc", *args, *self._args()], + cwd=self._cwd, + env=self._extension_env( + approve=self._approve 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._approve 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._approve( + 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 turn(self, prompt: base.Prompt) -> AsyncIterator[events_.Event]: + base.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 + command = await _prompt_command(prompt) + 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"): + 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 base.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": + 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 steer(self, text: str) -> None: + """Queue guidance for the running turn. + + pi delivers it once the current message's tool calls are done, + before its next model call. + """ + if not self._running or self._agent is None: + raise errors.WorkerError(f"{KIND}: no turn is running to steer") + try: + await self._agent.call({"type": "steer", "message": text}) + except _CommandError as exc: + raise errors.WorkerError(f"{KIND}: steer rejected: {exc}") from exc + + async def 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 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) + stored: list[messages_.Message] = [] + for record in _active_branch(text): + stored.extend(_stored_to_messages(record)) + return _handoff.model_view(stored) + + async def list_sessions(self) -> list[base.SessionInfo]: + return [ + base.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 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, + ) + + +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: base.Process, *, on_dialog: Any) -> None: + self.process = process + self.events: asyncio.Queue[dict[str, Any]] = asyncio.Queue() + self.dead: str | None = None + 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: + 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: base.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 base.as_text(part)) + else: + images.append( + { + "type": "image", + "data": base64.b64encode(await base.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 += base.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 += base.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": + parts.append(_tool_call(block)) + 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 _stored_to_messages(entry: dict[str, Any]) -> list[messages_.Message]: + """One session entry -> messages, CLI tools as tool calls. + + 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), + ) + ] + if role == "toolResult": + result = messages_.ToolResultPart( + tool_call_id=str(message.get("toolCallId") or ""), + tool_name=str(message.get("toolName") or ""), + result=_tool_result(message), + result_kind="error" if message.get("isError") else "json", + ) + return [messages_.Message(role="tool", parts=[result])] + 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/src/ai/workers/_adapters/pi_extension.js b/src/ai/workers/_adapters/pi_extension.js new file mode 100644 index 00000000..164712c0 --- /dev/null +++ b/src/ai/workers/_adapters/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/_kinds.py b/src/ai/workers/_kinds.py index 69285dc0..e12c875f 100644 --- a/src/ai/workers/_kinds.py +++ b/src/ai/workers/_kinds.py @@ -1,4 +1,4 @@ -"""The workers, one per CLI. +"""The workers: Claude Code, Codex and Pi. Each adds its CLI's own options to `Worker` and builds its adapter. """ @@ -9,8 +9,50 @@ import pydantic +from ..providers import _optional from . import _bridge, _worker -from ._adapters import base, codex +from ._adapters import base, codex, pi + + +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"`. + """ + + kind: Literal["claude-code"] = "claude-code" + allowed_tools: list[str] | None = None + disallowed_tools: list[str] | None = None + max_turns: int | None = None + + def _make_adapter( + self, + mcp_servers: dict[str, dict[str, Any]], + approve: base.Approve | None, + ) -> base.Adapter: + _optional.import_optional_sdk( + "claude_agent_sdk", + extra="claude-code", + feature="ai.workers.ClaudeCode", + ) + # Imported here: the adapter needs claude_agent_sdk at import time. + from ._adapters import claude # noqa: PLC0415 + + return claude.ClaudeAdapter( + cwd=self.cwd, + env=dict(self.env), + executable=self.executable or "claude", + model=self.model, + effort=self.effort, + mcp_servers=dict(mcp_servers), + approve=approve, + allowed_tools=self.allowed_tools, + disallowed_tools=self.disallowed_tools, + max_turns=self.max_turns, + ) class Codex(_worker.Worker): @@ -55,3 +97,32 @@ def _make_adapter( sandbox=self.sandbox, config=config, ) + + +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. + """ + + kind: Literal["pi"] = "pi" + allowed_tools: list[str] | None = None + disallowed_tools: list[str] | None = None + + def _make_adapter( + self, + mcp_servers: dict[str, dict[str, Any]], + approve: base.Approve | None, + ) -> base.Adapter: + return pi.PiAdapter( + cwd=self.cwd, + env=dict(self.env), + executable=self.executable or "pi", + model=self.model, + effort=self.effort, + mcp_servers=dict(mcp_servers), + approve=approve, + allowed_tools=self.allowed_tools, + disallowed_tools=self.disallowed_tools, + ) diff --git a/src/ai/workers/_worker.py b/src/ai/workers/_worker.py index 89aa3994..4670fa65 100644 --- a/src/ai/workers/_worker.py +++ b/src/ai/workers/_worker.py @@ -1,6 +1,6 @@ """`ai.workers.Worker`: a coding-agent CLI that goes where a model goes. -A worker is ONE conversation with one coding-agent CLI, such as Codex. It is +A worker is ONE conversation with one CLI: Claude Code, Codex or Pi. It is a pydantic model: its fields are its settings, the CLI's `session_id` and the conversation so far (`messages`). Dump it, store it, and validate it again later; it continues the same conversation. @@ -112,7 +112,7 @@ class _Runtime: class Worker(pydantic.BaseModel): - """Base class of the workers, such as `Codex`. + """Base class of `ClaudeCode`, `Codex` and `Pi`. `Worker.model_validate(data)` builds the kind that `data["kind"]` names. """ diff --git a/tests/workers/_adapters/test_claude.py b/tests/workers/_adapters/test_claude.py new file mode 100644 index 00000000..6854d5e4 --- /dev/null +++ b/tests/workers/_adapters/test_claude.py @@ -0,0 +1,317 @@ +"""The claude adapter 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 typing import Any + +import pytest + +claude_agent_sdk = pytest.importorskip("claude_agent_sdk") + +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._adapters import claude # 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_response(self) -> AsyncIterator[Any]: + for message in self.replies.pop(0): + yield message + + async def interrupt(self) -> None: + self.interrupted = True + + async def disconnect(self) -> None: + pass + + +def _adapter(tmp_path: Path, **options: Any) -> claude.ClaudeAdapter: + return claude.ClaudeAdapter( + cwd=str(tmp_path), + env={"CLAUDE_CONFIG_DIR": str(tmp_path / "config")}, + executable="claude", + model=options.get("model"), + effort=None, + mcp_servers=options.get("mcp_servers", {}), + approve=None, + allowed_tools=None, + disallowed_tools=None, + max_turns=None, + ) + + +async def _turn(adapter: claude.ClaudeAdapter, *prompt: Any) -> list[Any]: + async with asyncio.timeout(5): + return [e async for e in adapter.turn(list(prompt))] + + +async def test_a_turn_streams_in_the_model_view(tmp_path: Path) -> None: + adapter = _adapter(tmp_path) + adapter._client = Client(TURN) + seen = await _turn(adapter, 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 adapter._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: + adapter = _adapter(tmp_path) + adapter._client = Client([_result()]) + png = m.FilePart(data=b"\x89PNG", media_type="image/png") + await _turn(adapter, m.TextPart(text="look"), png) + (sent,) = adapter._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: + adapter = _adapter(tmp_path) + adapter._client = Client([_result()]) + zipped = m.FilePart(data=b"PK", media_type="application/zip") + with pytest.raises(workers.WorkerError, match="application/zip"): + await _turn(adapter, zipped) + + +async def test_finish_reasons(tmp_path: Path) -> None: + adapter = _adapter(tmp_path) + adapter._client = Client([_result(subtype="error_max_turns")]) + assert (await _turn(adapter, m.TextPart(text="x")))[-1].finish_reason == ( + "length" + ) + adapter._client = Client( + [_result(is_error=True, result="Invalid API key · Please run /login")] + ) + with pytest.raises(workers.NotAuthenticatedError): + await _turn(adapter, m.TextPart(text="x")) + adapter._client = Client([_result(is_error=True, result="overloaded")]) + with pytest.raises(workers.WorkerError, match="overloaded"): + await _turn(adapter, m.TextPart(text="x")) + + +async def test_an_interrupted_turn_is_cancelled_not_failed( + tmp_path: Path, +) -> None: + adapter = _adapter(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()]) + adapter._client = client + adapter._running = True # a turn was running when it was interrupted + await adapter.interrupt() + assert client.interrupted + seen = await _turn(adapter, 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: + adapter = _adapter(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 adapter._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_transcript_reads_as_the_model_view() -> None: + 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, + ), + ] + from ai.workers._adapters import _handoff + + stored = [msg for r in records for msg in claude._stored_to_messages(r)] + history = _handoff.model_view(stored) + 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: + adapter = _adapter( + tmp_path, + model="sonnet", + mcp_servers={ + "ai_sdk": {"type": "http", "url": "http://127.0.0.1:1/mcp"}, + "docs": {"command": "docs-mcp"}, + }, + ) + argv, env, minted = adapter.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 = adapter.tui_command(None) + assert argv[1] == "--session-id" and argv[2] == minted diff --git a/tests/workers/_adapters/test_pi.py b/tests/workers/_adapters/test_pi.py new file mode 100644 index 00000000..86f99ccb --- /dev/null +++ b/tests/workers/_adapters/test_pi.py @@ -0,0 +1,554 @@ +"""The pi adapter 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._adapters import pi + +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 + + def says(self, record: dict[str, Any]) -> None: + 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.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}) + 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 _adapter( + server: Pi | None = None, approve: Any = None, cwd: str = "/w", **env: str +) -> pi.PiAdapter: + adapter = pi.PiAdapter( + cwd=cwd, + env=env, + executable="pi", + model=None, + effort=None, + mcp_servers={}, + approve=approve, + allowed_tools=None, + disallowed_tools=None, + ) + if server is not None: + agent = pi._Agent( + cast("Any", server.process), on_dialog=adapter._on_dialog + ) + agent.start() + adapter._agent = agent + return adapter + + +async def _turn(adapter: pi.PiAdapter, *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 adapter.turn(parts)] + + +async def test_a_turn_streams_in_the_model_view() -> None: + server = Pi() + seen = await _turn(_adapter(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(_adapter(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(_adapter(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(_adapter(server)) + + +def _ask(server: Pi) -> None: + server.says( + { + "type": "extension_ui_request", + "id": "ui-1", + "method": "input", + "title": pi.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(_adapter(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() + adapter = _adapter(server) + assert adapter._agent is not None + await adapter._on_dialog( + adapter._agent, {"id": "x", "method": "confirm", "title": "Clear?"} + ) + await adapter._on_dialog( + adapter._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([]) + adapter = _adapter(server) + turn = adapter.turn([m.TextPart(text="go")]) + assert isinstance(await anext(turn), events.StreamStart) + reader = asyncio.ensure_future(_rest(turn)) + await adapter.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(_adapter(server)) + + +async def test_a_run_an_extension_command_starts_is_followed() -> 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": True}) + else: + Pi.answer(server, message) + + server.process.answer = answer + seen = await _turn(_adapter(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(_adapter(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 = [ + msg + for entry in pi._active_branch(text) + for msg in pi._stored_to_messages(entry) + ] + assert [msg.role for msg in stored] == ["user", "assistant", "tool"] + result = stored[2].parts[0] + assert isinstance(result, m.ToolResultPart) + assert (result.result, result.result_kind) == ("hi", "error") + + +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() + adapter = _adapter(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 adapter._stage(seed) + infos = await adapter.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 adapter.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 adapter.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() + adapter = _adapter(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")]), + *pi._stored_to_messages(stored), + ] + session_id = await adapter._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: + adapter = pi.PiAdapter( + cwd="/w", + env={"K": "v"}, + executable="pi", + model="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=None, + allowed_tools=[], + disallowed_tools=["bash"], + ) + argv, env, minted = adapter.tui_command(None) + assert argv[:3] == ["pi", "--session-id", minted] + assert argv[3:5] == ["-e", pi.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[pi.CONFIG_VAR]) == { + "approve": False, + "mcp": {"docs": {"command": "docs-mcp"}}, + } diff --git a/tests/workers/test_live.py b/tests/workers/test_live.py new file mode 100644 index 00000000..6c89aa8c --- /dev/null +++ b/tests/workers/test_live.py @@ -0,0 +1,137 @@ +"""Workers against the real CLIs. Opt-in: `uv run pytest -m live tests/workers`. + +Each test runs once per CLI installed here, in a fresh directory, with the +CLI's own login. They cost tokens. +""" + +from __future__ import annotations + +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 + +KINDS: dict[str, tuple[str, Callable[..., workers.Worker]]] = { + "claude-code": ("claude", workers.ClaudeCode), + "codex": ("codex", workers.Codex), + "pi": ("pi", workers.Pi), +} + + +@pytest.fixture(params=list(KINDS)) +def kind(request: pytest.FixtureRequest) -> str: + kind = str(request.param) + executable, _ = KINDS[kind] + if shutil.which(executable) is None: + pytest.skip(f"{executable} is not installed") + if kind == "claude-code" and not importlib.util.find_spec( + "claude_agent_sdk" + ): + pytest.skip("claude-agent-sdk is not installed") + return kind + + +@pytest.fixture +def make(kind: str, tmp_path: Path) -> Callable[..., workers.Worker]: + """Build a worker of this kind, in a fresh directory.""" + _, cls = KINDS[kind] + return lambda **fields: cls(cwd=str(tmp_path), **fields) + + +async def test_a_turn_and_a_resume(make: Any) -> None: + async with make() as worker: + first = await ai.experimental_generate( + worker, + [ai.user_message("Reply with the word PONG and nothing else.")], + ) + assert "PONG" in first.text + assert worker.session_id + again = workers.Worker.model_validate_json(worker.model_dump_json()) + async with again: + 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_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 = worker.model_copy(update={"fork": True}) + async with branch: + 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( + kind: str, make: Any, tmp_path: Path +) -> None: + if kind == "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() 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" From 8ac61fd9fcf89ad13f9d5f4dce56a591694347ed Mon Sep 17 00:00:00 2001 From: Andrey Buzin Date: Fri, 6 Nov 2026 13:36:04 -0800 Subject: [PATCH 4/6] Arrange ai.workers like providers: core files, a directory per CLI --- examples/workers/agent_tools.py | 52 -- examples/workers/approvals.py | 36 +- examples/workers/claude_code/agent_tools.py | 46 ++ examples/workers/codex/agent_tools.py | 46 ++ examples/workers/pi/agent_tools.py | 46 ++ src/ai/workers/__init__.py | 6 +- src/ai/workers/_adapter.py | 139 +++++ src/ai/workers/_adapters/_handoff.py | 504 ------------------ src/ai/workers/_adapters/base.py | 333 ------------ src/ai/workers/_bridge.py | 6 +- src/ai/workers/_convert.py | 116 ++++ src/ai/workers/_handoff.py | 218 ++++++++ src/ai/workers/_kinds.py | 128 ----- src/ai/workers/_worker.py | 19 +- src/ai/workers/claude_code/__init__.py | 3 + .../claude.py => claude_code/adapter.py} | 42 +- src/ai/workers/claude_code/handoff.py | 106 ++++ src/ai/workers/claude_code/worker.py | 49 ++ src/ai/workers/codex/__init__.py | 3 + .../{_adapters/codex.py => codex/adapter.py} | 44 +- src/ai/workers/codex/handoff.py | 86 +++ .../workers/{_adapters => codex}/jsonrpc.py | 96 +++- src/ai/workers/codex/worker.py | 54 ++ src/ai/workers/pi/__init__.py | 3 + .../{_adapters/pi.py => pi/adapter.py} | 142 ++++- .../pi_extension.js => pi/extension.js} | 0 src/ai/workers/pi/handoff.py | 148 +++++ src/ai/workers/pi/worker.py | 37 ++ .../workers/claude_code}/__init__.py | 0 .../test_adapter.py} | 12 +- .../workers/{_adapters => codex}/__init__.py | 0 .../test_codex.py => codex/test_adapter.py} | 9 +- .../{_adapters => codex}/test_jsonrpc.py | 2 +- tests/workers/fakes.py | 27 +- tests/workers/pi/__init__.py | 0 .../test_pi.py => pi/test_adapter.py} | 24 +- tests/workers/{_adapters => }/test_handoff.py | 27 +- 37 files changed, 1441 insertions(+), 1168 deletions(-) delete mode 100644 examples/workers/agent_tools.py create mode 100644 examples/workers/claude_code/agent_tools.py create mode 100644 examples/workers/codex/agent_tools.py create mode 100644 examples/workers/pi/agent_tools.py create mode 100644 src/ai/workers/_adapter.py delete mode 100644 src/ai/workers/_adapters/_handoff.py delete mode 100644 src/ai/workers/_adapters/base.py create mode 100644 src/ai/workers/_convert.py create mode 100644 src/ai/workers/_handoff.py delete mode 100644 src/ai/workers/_kinds.py create mode 100644 src/ai/workers/claude_code/__init__.py rename src/ai/workers/{_adapters/claude.py => claude_code/adapter.py} (95%) create mode 100644 src/ai/workers/claude_code/handoff.py create mode 100644 src/ai/workers/claude_code/worker.py create mode 100644 src/ai/workers/codex/__init__.py rename src/ai/workers/{_adapters/codex.py => codex/adapter.py} (95%) create mode 100644 src/ai/workers/codex/handoff.py rename src/ai/workers/{_adapters => codex}/jsonrpc.py (68%) create mode 100644 src/ai/workers/codex/worker.py create mode 100644 src/ai/workers/pi/__init__.py rename src/ai/workers/{_adapters/pi.py => pi/adapter.py} (89%) rename src/ai/workers/{_adapters/pi_extension.js => pi/extension.js} (100%) create mode 100644 src/ai/workers/pi/handoff.py create mode 100644 src/ai/workers/pi/worker.py rename {src/ai/workers/_adapters => tests/workers/claude_code}/__init__.py (100%) rename tests/workers/{_adapters/test_claude.py => claude_code/test_adapter.py} (96%) rename tests/workers/{_adapters => codex}/__init__.py (100%) rename tests/workers/{_adapters/test_codex.py => codex/test_adapter.py} (98%) rename tests/workers/{_adapters => codex}/test_jsonrpc.py (99%) create mode 100644 tests/workers/pi/__init__.py rename tests/workers/{_adapters/test_pi.py => pi/test_adapter.py} (97%) rename tests/workers/{_adapters => }/test_handoff.py (90%) diff --git a/examples/workers/agent_tools.py b/examples/workers/agent_tools.py deleted file mode 100644 index f56bef4c..00000000 --- a/examples/workers/agent_tools.py +++ /dev/null @@ -1,52 +0,0 @@ -"""A worker as the model of an `ai.Agent`: the agent's tools reach it by MCP. - -The CLI calls `lookup_order`. The worker hands the call to the agent, the -agent runs the tool, and the CLI gets the result and goes on. - - uv run python examples/workers/agent_tools.py [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, -} - - -@ai.tool -async def lookup_order(order_id: str) -> str: - """Look up the status of an order by its id.""" - return f"order {order_id}: shipped on 2026-11-02" - - -async def main(kind: str) -> None: - agent = ai.Agent(tools=[lookup_order]) - messages = [ - ai.user_message( - "Use the lookup_order tool for order A-17, then tell me its " - "status in one sentence." - ) - ] - async with KINDS[kind]() as worker: - async with agent.run(worker, messages) as run: - async for event in run: - match event: - case ai.events.ToolEnd(): # the agent runs this one - call = event.tool_call - print(f"[agent tool] {call.tool_name} {call.tool_args}") - case ai.events.BuiltinToolEnd(): # the CLI's own tool - print(f"[cli tool] {event.tool_call.tool_name}") - case ai.events.TextDelta(): - print(event.chunk, end="", flush=True) - print() - print([m.role for m in run.messages]) - - -asyncio.run(main(sys.argv[1] if len(sys.argv) > 1 else "claude-code")) diff --git a/examples/workers/approvals.py b/examples/workers/approvals.py index 0d71f625..16e4fc47 100644 --- a/examples/workers/approvals.py +++ b/examples/workers/approvals.py @@ -22,23 +22,25 @@ async def main(kind: str) -> None: messages = [ai.user_message("Create notes.txt containing 'hello'.")] - async with KINDS[kind](approve=True) as worker: - async with ai.Agent().run(worker, messages) as run: - async for event in run: - match event: - case ai.events.PendingHookEvent(hook=hook): - meta = hook.metadata - answer = await asyncio.to_thread( - input, - f"allow {meta['tool']} {meta['kwargs']}? [y/N] ", - ) - granted = answer.strip().lower() == "y" - ai.resolve_hook( - hook, {"granted": granted, "reason": "user said no"} - ) - case ai.events.TextDelta(): - print(event.chunk, end="", flush=True) - print() + 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/src/ai/workers/__init__.py b/src/ai/workers/__init__.py index 2b66dac4..4ad6b7bc 100644 --- a/src/ai/workers/__init__.py +++ b/src/ai/workers/__init__.py @@ -24,15 +24,17 @@ a conversation the CLI has stored. """ -from ._adapters.base import SessionInfo +from ._adapter import SessionInfo from ._errors import ( ExecutableMissingError, NotAuthenticatedError, TranscriptMismatchError, WorkerError, ) -from ._kinds import ClaudeCode, Codex, Pi from ._worker import Worker +from .claude_code import ClaudeCode +from .codex import Codex +from .pi import Pi __all__ = [ "ClaudeCode", diff --git a/src/ai/workers/_adapter.py b/src/ai/workers/_adapter.py new file mode 100644 index 00000000..fd34f25b --- /dev/null +++ b/src/ai/workers/_adapter.py @@ -0,0 +1,139 @@ +"""The adapter protocol: what `Worker` needs from each CLI. + +An adapter drives ONE conversation with one CLI. It speaks the model view +both ways: `turn()` yields the events of one assistant message, with the +CLI's own tools as `BuiltinTool*` events, and ends with a `StreamEnd`; a +history it reads or is seeded with is a plain `list[Message]`. +""" + +from __future__ import annotations + +import asyncio +import os +import re +import warnings +from collections.abc import AsyncIterator, Awaitable, Callable, Mapping +from typing import Any, Protocol + +import pydantic + +from ..types import events +from ..types import messages as messages_ +from . import _errors as errors + +Prompt = list[messages_.TextPart | messages_.FilePart] + +# `approve(tool_call_id, tool_name, tool_input)` returns `(granted, reason)`. +# +# Never raises: the worker answers a failure with a denial. +Approve = Callable[[str, str, dict[str, Any]], Awaitable[tuple[bool, str]]] + + +class SessionInfo(pydantic.BaseModel): + """A conversation in a CLI's own store.""" + + session_id: str + title: str | None = None + cwd: str | None = None + created_at: int | None = None + """Milliseconds since the epoch, when the CLI records it.""" + updated_at: int | None = None + + +class CLIAdapter(Protocol): + version: str | None + """What ` --version` printed, once started.""" + + async def start(self) -> None: + """Check the CLI runs, and start what it needs (codex: a server).""" + ... + + async def close(self) -> None: ... + + async def open( + self, + *, + session_id: str | None, + fork: bool, + seed: list[messages_.Message] | None, + instructions: str | None, + ) -> str: + """Open the conversation and return its session id. + + A new one (seeded with a past when `seed` is given), the stored one + `session_id` names, or a native fork of it. + """ + ... + + def turn(self, prompt: Prompt) -> AsyncIterator[events.Event]: + """Send a prompt; yield one assistant message, ending in StreamEnd.""" + ... + + async def steer(self, text: str) -> None: + """Send guidance to the turn that runs now.""" + ... + + async def interrupt(self) -> None: + """End the running turn. The CLI keeps its transcript.""" + ... + + async def history(self, session_id: str) -> list[messages_.Message]: + """Read a stored conversation.""" + ... + + async def list_sessions(self) -> list[SessionInfo]: ... + + def tui_command( + self, session_id: str | None + ) -> tuple[list[str], dict[str, str], str | None]: + """Return the CLI's interactive command, its env, and its session id. + + The session id is minted here for a new conversation when the CLI + lets us choose it, else None. + """ + ... + + +async def probe( + kind: str, + executable: str, + *, + install: str, + verified: str, + cwd: str, + env: Mapping[str, str], +) -> str: + """Check that the CLI runs, and return its version. + + Warns when it is older than the version the adapter was verified with: + the adapters lean on CLI behavior that is measured, not documented. + """ + try: + proc = await asyncio.create_subprocess_exec( + executable, + "--version", + cwd=cwd, + env={**os.environ, **env}, + stdout=asyncio.subprocess.PIPE, + stderr=asyncio.subprocess.PIPE, + ) + async with asyncio.timeout(60): + stdout, _ = await proc.communicate() + except (OSError, TimeoutError) as exc: + raise errors.ExecutableMissingError(kind, executable, install) from exc + if proc.returncode != 0: + raise errors.ExecutableMissingError(kind, executable, install) + version = (stdout.decode(errors="replace").strip().splitlines() or [""])[0] + have, want = _version(version), _version(verified) + if have is not None and want is not None and have < want: + warnings.warn( + f"{kind} {version} is older than {verified}, the version this " + "SDK was verified with; update it if something misbehaves", + stacklevel=2, + ) + return version + + +def _version(text: str | None) -> tuple[int, ...] | None: + found = re.search(r"\d+(?:\.\d+)+", text or "") + return tuple(int(n) for n in found.group(0).split(".")) if found else None diff --git a/src/ai/workers/_adapters/_handoff.py b/src/ai/workers/_adapters/_handoff.py deleted file mode 100644 index 873a0b6c..00000000 --- a/src/ai/workers/_adapters/_handoff.py +++ /dev/null @@ -1,504 +0,0 @@ -"""Seeding a CLI with a past: one rendering rule, every CLI. - -A worker given `[*past, user_message]` on its first turn starts a new -conversation from `past`. Each CLI stores it natively so the agent truly -has the context, and the rule for what becomes what is the same everywhere: - -- text: verbatim, same role. -- tool calls and results: the NATIVE tool items, original name and - arguments unaltered. Measured: the receiving agent reads them as history - and acts with its own tools; it does not try to call a tool it lacks. - Names are not translated — mapping `Write` to `fileChange` would be the - invented taxonomy this SDK refuses everywhere else. Nor are PATHS: a call - that wrote /Users/x/proj/recipe.txt says so, and that is where it was - written. Across machines the receiver must be told where things are now - (or the workspace copied to the same path) — as any colleague would be. -- reasoning: a user-role handoff note after the turn it belonged to — where - the destination accepts it. Measured: fed back as the agent's OWN thoughts - it is rejected (Claude signs thinking blocks) or silently ignored (codex - accepts a reasoning item and never reads it). As a note, codex uses it. - Claude does NOT accept it in any form: Anthropic's safeguards flag real - model reasoning replayed as user content (`[reasoning_extraction]`) — - hand-written notes passed, genuine Opus thinking was refused. So the - Claude renderer omits reasoning, and the adapter warns with the count, - because dropping context silently is the one thing this SDK never does. - Pi omits it too, for both reasons: pi drops thinking another model wrote, - and pi often runs Claude. -- files: images go to every harness, as the image input each takes (pi - takes bytes, so an image known only by URL becomes a note naming it); - PDFs to Claude as documents. Anything else (a PDF into codex, a text - file) is left out and counted (`unsupported_files`), and the adapter - warns, like it does for reasoning into Claude. -""" - -from __future__ import annotations - -import datetime -import json -import uuid -import warnings -from typing import Any - -from ...types import media -from ...types import messages as messages_ - -NOTE_PREFIX = "[Handoff from a previous session — earlier reasoning: " -AUTHOR = ("api", "provider", "model") -"""What names a reply's author in a pi session: its API and model.""" -SYSTEM_PREFIX = "[Handoff from a previous session — instructions it was given: " - - -def _text(value: Any) -> str: - return value if isinstance(value, str) else json.dumps(value) - - -def _note(reasoning: list[str]) -> str: - return ( - NOTE_PREFIX + " ".join(r.strip() for r in reasoning if r.strip()) + "]" - ) - - -def _image_url(part: messages_.FilePart) -> str: - """Return an http(s) URL as it is, anything else as a data URL.""" - return media.data_to_data_url(part.data, part.media_type) - - -def _source(part: messages_.FilePart) -> dict[str, Any]: - """Return an Anthropic content-block source for a file.""" - if isinstance(part.data, str) and media.is_downloadable_url(part.data): - return {"type": "url", "url": part.data} - return { - "type": "base64", - "media_type": part.media_type, - "data": media.data_to_base64(part.data), - } - - -def harness_view(history: list[messages_.Message]) -> list[messages_.Message]: - """Return a past with the CLI's own tools as ordinary tool calls. - - A worker's messages hold the tools a CLI ran itself as - `BuiltinToolCallPart`/`BuiltinToolReturnPart`, the way a provider's web - search is. A CLI's store holds them as tool calls, each with its result - in a `tool` message after it. The renderers below read that shape. - """ - out: list[messages_.Message] = [] - for message in history: - parts: list[messages_.Part] = [] - results: list[messages_.Part] = [] - first = True - for part in message.parts: - if results and not isinstance( - part, messages_.BuiltinToolReturnPart - ): - # What follows a result comes after it: a new message. - if parts: - out.append(_split(message, parts, first=first)) - first = False - out.append(messages_.Message(role="tool", parts=results)) - parts, results = [], [] - if isinstance(part, messages_.BuiltinToolCallPart): - parts.append( - messages_.ToolCallPart( - tool_call_id=part.tool_call_id, - tool_name=part.tool_name, - tool_args=part.tool_args or "{}", - provider_metadata=part.provider_metadata, - ) - ) - elif isinstance(part, messages_.BuiltinToolReturnPart): - results.append( - messages_.ToolResultPart( - tool_call_id=part.tool_call_id, - tool_name=part.tool_name, - result=part.result, - result_kind="error" if part.is_error else "json", - ) - ) - else: - parts.append(part) - if parts: - out.append(_split(message, parts, first=first)) - if results: - out.append(messages_.Message(role="tool", parts=results)) - return out - - -def _split( - message: messages_.Message, parts: list[messages_.Part], *, first: bool -) -> messages_.Message: - """One piece of a message: the first keeps its id, the rest get new ones.""" - if first: - return message.model_copy(update={"parts": parts}) - return messages_.Message( - role=message.role, - parts=parts, - provider_metadata=message.provider_metadata, - ) - - -def model_view(stored: list[messages_.Message]) -> list[messages_.Message]: - """Return a stored conversation the way a worker shows it. - - The reverse of `harness_view`: the CLI's tool calls become built-in - parts, and each result joins the assistant message of its call. - """ - out: list[messages_.Message] = [] - owner: dict[str, int] = {} # tool_call_id -> index in `out` - for message in stored: - if message.role == "assistant": - parts: list[messages_.Part] = [] - for part in message.parts: - if isinstance(part, messages_.ToolCallPart): - owner[part.tool_call_id] = len(out) - parts.append( - messages_.BuiltinToolCallPart( - tool_call_id=part.tool_call_id, - tool_name=part.tool_name, - tool_args=part.tool_args, - provider_metadata=part.provider_metadata, - ) - ) - else: - parts.append(part) - out.append(message.model_copy(update={"parts": parts})) - elif message.role == "tool": - for result in message.tool_results: - index = owner.get(result.tool_call_id) - if index is None: - continue - target = out[index] - out[index] = target.model_copy( - update={ - "parts": [ - *target.parts, - messages_.BuiltinToolReturnPart( - tool_call_id=result.tool_call_id, - tool_name=result.tool_name - or _name_of(target, result.tool_call_id), - result=result.result, - is_error=result.result_kind == "error", - ), - ] - } - ) - else: - out.append(message) - return out - - -def _name_of(message: messages_.Message, tool_call_id: str) -> str: - return next( - ( - p.tool_name - for p in message.parts - if isinstance(p, messages_.BuiltinToolCallPart) - and p.tool_call_id == tool_call_id - ), - "", - ) - - -def warn_unsupported_files( - messages: list[messages_.Message], kind: str -) -> None: - """Say how many files a history held that `kind` was not given.""" - left = unsupported_files(messages, kind) - if left: - warnings.warn( - f"{left} file(s) in the history were not carried into {kind}: " - + "it takes images" - + (" and PDFs" if kind == "claude-code" else "") - + " from a history. Text, tool calls and images were carried.", - stacklevel=3, - ) - - -def unsupported_files(messages: list[messages_.Message], kind: str) -> int: - """Count files a history holds that `kind` cannot take as input.""" - return sum( - 1 - for m in messages - for p in m.parts - if isinstance(p, messages_.FilePart) - and not p.media_type.startswith("image/") - and not (kind == "claude-code" and p.media_type == "application/pdf") - ) - - -def to_codex_items(messages: list[messages_.Message]) -> list[dict[str, Any]]: - """Responses API items for `thread/inject_items`.""" - items: list[dict[str, Any]] = [] - for m in harness_view(messages): - reasoning: list[str] = [] - for p in m.parts: - if isinstance(p, messages_.TextPart) and p.text.strip(): - ctype = "input_text" if m.role == "user" else "output_text" - items.append( - { - "type": "message", - "role": m.role, - "content": [{"type": ctype, "text": p.text}], - } - ) - elif ( - isinstance(p, messages_.FilePart) - and m.role == "user" - and p.media_type.startswith("image/") - ): - items.append( - { - "type": "message", - "role": "user", - "content": [ - {"type": "input_image", "image_url": _image_url(p)} - ], - } - ) - elif isinstance(p, messages_.ToolCallPart): - items.append( - { - "type": "function_call", - "call_id": p.tool_call_id or p.id, - "name": p.tool_name, - "arguments": p.tool_args or "{}", - } - ) - elif isinstance(p, messages_.ToolResultPart): - items.append( - { - "type": "function_call_output", - "call_id": p.tool_call_id, - "output": _text(p.result), - } - ) - elif isinstance(p, messages_.ReasoningPart) and p.text.strip(): - reasoning.append(p.text) - if reasoning: - items.append( - { - "type": "message", - "role": "user", - "content": [ - {"type": "input_text", "text": _note(reasoning)} - ], - } - ) - return items - - -def reasoning_count(messages: list[messages_.Message]) -> int: - return sum( - 1 - for m in messages - for p in m.parts - if isinstance(p, messages_.ReasoningPart) and p.text.strip() - ) - - -def to_claude_records( - messages: list[messages_.Message], session_id: str, cwd: str -) -> list[dict[str, Any]]: - """Build Claude Code transcript records for the CLI's store. - - Chained by parentUuid. - - Reasoning parts are omitted: see the module docstring. Callers report - the omission — `reasoning_count()` says how many. - """ - records: list[dict[str, Any]] = [] - parent: str | None = None - - def add(role: str, content: Any) -> None: - nonlocal parent - uid = str(uuid.uuid4()) - ts = ( - datetime.datetime.now(datetime.UTC) - .isoformat() - .replace("+00:00", "Z") - ) - records.append( - { - "parentUuid": parent, - "isSidechain": False, - "type": role, - "message": {"role": role, "content": content}, - "uuid": uid, - "timestamp": ts, - "sessionId": session_id, - "cwd": cwd, - } - ) - parent = uid - - for m in harness_view(messages): - blocks: list[dict[str, Any]] = [] - for p in m.parts: - if isinstance(p, messages_.TextPart) and p.text.strip(): - blocks.append({"type": "text", "text": p.text}) - elif isinstance(p, messages_.FilePart) and m.role == "user": - if p.media_type.startswith("image/"): - blocks.append({"type": "image", "source": _source(p)}) - elif p.media_type == "application/pdf": - blocks.append({"type": "document", "source": _source(p)}) - elif isinstance(p, messages_.ToolCallPart): - try: - args = json.loads(p.tool_args) if p.tool_args else {} - except json.JSONDecodeError: - args = {"raw": p.tool_args} - blocks.append( - { - "type": "tool_use", - "id": p.tool_call_id or p.id, - "name": p.tool_name, - "input": args, - } - ) - elif isinstance(p, messages_.ToolResultPart): - blocks.append( - { - "type": "tool_result", - "tool_use_id": p.tool_call_id, - "content": _text(p.result), - **( - {"is_error": True} - if p.result_kind == "error" - else {} - ), - } - ) - # ReasoningPart: omitted on purpose — Anthropic's safeguards - # refuse replayed reasoning. The adapter warns with the count. - if blocks: - # Tool results live in role="tool" messages in the IR; on disk - # the CLI keeps them as user records with tool_result blocks. - add("user" if m.role in ("user", "tool") else "assistant", blocks) - return records - - -def to_pi_messages( - messages: list[messages_.Message], *, timestamp: int -) -> list[dict[str, Any]]: - """Build pi `AgentMessage`s for a session file. - - Assistant messages pi wrote keep their author (`provider_metadata["pi"]`): - pi restores a session's model from it. Any other is attributed to a - model pi does not run (`ai-python/handoff`), so pi treats it as another - model's — it keeps its text and tool calls and normalizes the call ids - for its own provider. Consecutive assistant messages are merged, the way one - model response holds text and calls together. Reasoning is omitted: see - the module docstring. - """ - out: list[dict[str, Any]] = [] - usage = { - "input": 0, - "output": 0, - "cacheRead": 0, - "cacheWrite": 0, - "totalTokens": 0, - "cost": { - "input": 0, - "output": 0, - "cacheRead": 0, - "cacheWrite": 0, - "total": 0, - }, - } - for m in harness_view(messages): - if m.role == "tool": - for p in m.parts: - if isinstance(p, messages_.ToolResultPart): - out.append( - { - "role": "toolResult", - "toolCallId": p.tool_call_id, - "toolName": p.tool_name, - "content": [ - {"type": "text", "text": _text(p.result)} - ], - "isError": p.result_kind == "error", - "timestamp": timestamp, - } - ) - continue - blocks: list[dict[str, Any]] = [] - for p in m.parts: - if isinstance(p, messages_.TextPart) and p.text.strip(): - blocks.append({"type": "text", "text": p.text}) - elif ( - isinstance(p, messages_.FilePart) - and m.role == "user" - and p.media_type.startswith("image/") - ): - if isinstance(p.data, str) and media.is_downloadable_url( - p.data - ): - blocks.append( - {"type": "text", "text": f"[image: {p.data}]"} - ) - else: - blocks.append( - { - "type": "image", - "data": media.data_to_base64(p.data), - "mimeType": p.media_type, - } - ) - elif ( - isinstance(p, messages_.ToolCallPart) and m.role == "assistant" - ): - try: - args = json.loads(p.tool_args) if p.tool_args else {} - except json.JSONDecodeError: - args = {"raw": p.tool_args} - blocks.append( - { - "type": "toolCall", - "id": p.tool_call_id or p.id, - "name": p.tool_name, - "arguments": args if isinstance(args, dict) else {}, - } - ) - if not blocks: - continue - if m.role == "system": - # Measured (pi 1.3.0): a system message in a session file is - # pi's own prompt state, and replaying one REPLACED pi's system - # prompt and its tools. So instructions travel as what they are - # to the agent — the caller's words — never as its own output. - text = " ".join(b["text"] for b in blocks if b["type"] == "text") - blocks = [{"type": "text", "text": SYSTEM_PREFIX + text + "]"}] - if m.role in ("user", "system"): - out.append( - {"role": "user", "content": blocks, "timestamp": timestamp} - ) - continue - if out and out[-1]["role"] == "assistant": - out[-1]["content"] += blocks - else: - # A reply pi wrote keeps its author: pi restores a session's model - # from its last reply's, and a model it does not know (ours) - # put the conversation on pi's default one (measured). - author = (m.provider_metadata or {}).get("pi") or {} - known = all(isinstance(author.get(k), str) for k in AUTHOR) - out.append( - { - "role": "assistant", - "content": blocks, - **( - {k: author[k] for k in AUTHOR} - if known - else { - "api": "ai-python", - "provider": "ai-python", - "model": "handoff", - } - ), - "usage": usage, - "stopReason": "stop", - "timestamp": timestamp, - } - ) - if any(b["type"] == "toolCall" for b in out[-1]["content"]): - out[-1]["stopReason"] = "toolUse" - return out diff --git a/src/ai/workers/_adapters/base.py b/src/ai/workers/_adapters/base.py deleted file mode 100644 index 10d09016..00000000 --- a/src/ai/workers/_adapters/base.py +++ /dev/null @@ -1,333 +0,0 @@ -"""What every adapter shares: its protocol, local processes, prompt files. - -An adapter drives ONE conversation with one CLI. It speaks the model view -both ways: `turn()` yields the events of one assistant message, with the -CLI's own tools as `BuiltinTool*` events, and ends with a `StreamEnd`; a -history it reads or is seeded with is a plain `list[Message]`. -""" - -from __future__ import annotations - -import asyncio -import base64 -import contextlib -import os -import re -import warnings -from collections.abc import ( - AsyncIterator, - Awaitable, - Callable, - Mapping, - Sequence, -) -from typing import Any, Protocol - -import pydantic - -from ...models.core.helpers import files -from ...types import events, media -from ...types import messages as messages_ -from .. import _errors as errors - -Prompt = list[messages_.TextPart | messages_.FilePart] - -Approve = Callable[[str, str, dict[str, Any]], Awaitable[tuple[bool, str]]] -"""`approve(tool_call_id, tool_name, tool_input)` returns `(granted, reason)`. - -Never raises: the worker answers a failure with a denial.""" - -LINE_LIMIT = 256 * 1024 * 1024 -"""Longest line a CLI may write. The protocols are JSON lines, and one line -can be megabytes (a codex `thread/read` of a long thread). With asyncio's -default (64 KiB) such a line failed as if the CLI had crashed.""" - -TERM_GRACE = 3.0 -"""Seconds a CLI gets to exit after SIGTERM, before SIGKILL.""" - - -class SessionInfo(pydantic.BaseModel): - """A conversation in a CLI's own store.""" - - session_id: str - title: str | None = None - cwd: str | None = None - created_at: int | None = None - """Milliseconds since the epoch, when the CLI records it.""" - updated_at: int | None = None - - -class Adapter(Protocol): - version: str | None - """What ` --version` printed, once started.""" - - async def start(self) -> None: - """Check the CLI runs, and start what it needs (codex: a server).""" - ... - - async def close(self) -> None: ... - - async def open( - self, - *, - session_id: str | None, - fork: bool, - seed: list[messages_.Message] | None, - instructions: str | None, - ) -> str: - """Open the conversation and return its session id. - - A new one (seeded with a past when `seed` is given), the stored one - `session_id` names, or a native fork of it. - """ - ... - - def turn(self, prompt: Prompt) -> AsyncIterator[events.Event]: - """Send a prompt; yield one assistant message, ending in StreamEnd.""" - ... - - async def steer(self, text: str) -> None: - """Send guidance to the turn that runs now.""" - ... - - async def interrupt(self) -> None: - """End the running turn. The CLI keeps its transcript.""" - ... - - async def history(self, session_id: str) -> list[messages_.Message]: - """Read a stored conversation.""" - ... - - async def list_sessions(self) -> list[SessionInfo]: ... - - def tui_command( - self, session_id: str | None - ) -> tuple[list[str], dict[str, str], str | None]: - """Return the CLI's interactive command, its env, and its session id. - - The session id is minted here for a new conversation when the CLI - lets us choose it, else None. - """ - ... - - -# -- local processes ----------------------------------------------------------- - - -class Process: - """A CLI started by `spawn`: JSON lines on stdin and stdout.""" - - def __init__(self, proc: asyncio.subprocess.Process) -> None: - self._proc = proc - - @property - def pid(self) -> int: - return self._proc.pid - - async def write(self, data: str) -> None: - assert self._proc.stdin is not None - self._proc.stdin.write(data.encode()) - await self._proc.stdin.drain() - - async def readline(self) -> str: - assert self._proc.stdout is not None - return (await self._proc.stdout.readline()).decode() - - async def read_stderr(self) -> str: - if self._proc.stderr is None: - return "" - return (await self._proc.stderr.read()).decode(errors="replace") - - async def wait(self) -> int: - return await self._proc.wait() - - async def terminate(self) -> None: - """Stop the process group: SIGTERM, then SIGKILL.""" - if self._proc.returncode is not None: - return - with contextlib.suppress(ProcessLookupError): - os.killpg(os.getpgid(self._proc.pid), 15) - try: - async with asyncio.timeout(TERM_GRACE): - await self._proc.wait() - except TimeoutError: - with contextlib.suppress(ProcessLookupError): - os.killpg(os.getpgid(self._proc.pid), 9) - with contextlib.suppress(Exception): - await self._proc.wait() - - async def death_note(self) -> str: - """Say how the process ended, and its last words.""" - code: int | None = None - tail = "" - with contextlib.suppress(Exception): - async with asyncio.timeout(2): - code = await self.wait() - with contextlib.suppress(Exception): - async with asyncio.timeout(2): - tail = (await self.read_stderr()).strip() - how = f"exit code {code}" if code is not None else "exited" - if code in (137, -9): - how += " (SIGKILL, typically the kernel's OOM killer)" - return f"{how}; stderr: {tail[-800:]}" if tail else f"{how}; no stderr" - - -async def spawn( - argv: Sequence[str], *, cwd: str, env: Mapping[str, str] -) -> Process: - """Start a CLI in its own process group, with pipes for stdio.""" - try: - proc = await asyncio.create_subprocess_exec( - *argv, - cwd=cwd, - env={**os.environ, **env}, - stdin=asyncio.subprocess.PIPE, - stdout=asyncio.subprocess.PIPE, - stderr=asyncio.subprocess.PIPE, - # Own the whole tree, so teardown reaches grandchildren too. - start_new_session=True, - limit=LINE_LIMIT, - ) - except OSError as exc: - raise errors.WorkerError(f"cannot start {argv[0]!r}: {exc}") from exc - return Process(proc) - - -async def probe( - kind: str, - executable: str, - *, - install: str, - verified: str, - cwd: str, - env: Mapping[str, str], -) -> str: - """Check that the CLI runs, and return its version. - - Warns when it is older than the version the adapter was verified with: - the adapters lean on CLI behavior that is measured, not documented. - """ - try: - proc = await asyncio.create_subprocess_exec( - executable, - "--version", - cwd=cwd, - env={**os.environ, **env}, - stdout=asyncio.subprocess.PIPE, - stderr=asyncio.subprocess.PIPE, - ) - async with asyncio.timeout(60): - stdout, _ = await proc.communicate() - except (OSError, TimeoutError) as exc: - raise errors.ExecutableMissingError(kind, executable, install) from exc - if proc.returncode != 0: - raise errors.ExecutableMissingError(kind, executable, install) - version = (stdout.decode(errors="replace").strip().splitlines() or [""])[0] - have, want = _version(version), _version(verified) - if have is not None and want is not None and have < want: - warnings.warn( - f"{kind} {version} is older than {verified}, the version this " - "SDK was verified with; update it if something misbehaves", - stacklevel=2, - ) - return version - - -def _version(text: str | None) -> tuple[int, ...] | None: - found = re.search(r"\d+(?:\.\d+)+", text or "") - return tuple(int(n) for n in found.group(0).split(".")) if found else None - - -# -- files in a prompt --------------------------------------------------------- -# -# Files are turned into bytes HERE: a URL is downloaded with the SDK's own -# SSRF-checked downloader, not handed to the CLI. Measured: Claude Code drops -# an image given by URL without a word. - - -async def data(part: messages_.FilePart) -> bytes: - """Return a file's bytes, downloading a URL first.""" - if isinstance(part.data, bytes): - return part.data - if media.is_downloadable_url(part.data): - body, _ = await files.download(part.data) - return body - return base64.b64decode(media.data_to_base64(part.data)) - - -async def as_text(part: messages_.FilePart) -> str: - """Return a text file as text a CLI reads inline, named if it has one.""" - body = (await data(part)).decode("utf-8", errors="replace") - name = part.filename or "attached file" - return f"\n{body}\n" - - -def check_files(prompt: Prompt, kind: str, accepts: Sequence[str]) -> None: - """Refuse a file the CLI cannot take, before anything runs. - - Text files (`text/*`) go everywhere, as text. `accepts` lists the other - media type prefixes the CLI takes. - """ - for part in prompt: - if isinstance(part, messages_.FilePart) and not any( - part.media_type.startswith(p) for p in ("text/", *accepts) - ): - raise errors.WorkerError( - f"{kind} does not take {part.media_type} files" - ) - - -def text_of(prompt: Prompt) -> str: - return "\n\n".join( - p.text for p in prompt if isinstance(p, messages_.TextPart) - ) - - -def builtin_call( - tool_call_id: str, - tool_name: str, - tool_args: str, - *, - started: set[str], -) -> list[events.Event]: - """Return the events of one finished CLI tool call. - - `started` holds the calls whose start was already sent: the start is - sent here otherwise, because the hydrator only completes a call it saw - start. The arguments travel as a delta: the hydrator builds a call's - arguments only from its deltas. - """ - out: list[events.Event] = [] - if tool_call_id not in started: - started.add(tool_call_id) - out.append( - events.BuiltinToolStart( - tool_call_id=tool_call_id, tool_name=tool_name - ) - ) - return [ - *out, - events.BuiltinToolDelta(tool_call_id=tool_call_id, chunk=tool_args), - events.BuiltinToolEnd( - tool_call_id=tool_call_id, - tool_call=messages_.BuiltinToolCallPart( - tool_call_id=tool_call_id, - tool_name=tool_name, - tool_args=tool_args, - ), - ), - ] - - -def builtin_result( - tool_call_id: str, tool_name: str, result: Any, *, is_error: bool -) -> events.BuiltinToolResult: - return events.BuiltinToolResult( - tool_call_id=tool_call_id, - result=messages_.BuiltinToolReturnPart( - tool_call_id=tool_call_id, - tool_name=tool_name, - result=result, - is_error=is_error, - ), - ) diff --git a/src/ai/workers/_bridge.py b/src/ai/workers/_bridge.py index f32f5a59..ef0bb5b8 100644 --- a/src/ai/workers/_bridge.py +++ b/src/ai/workers/_bridge.py @@ -26,14 +26,14 @@ if TYPE_CHECKING: from ..types import tools as tools_ +# The MCP server name the CLI sees. Claude Code calls a tool +# `mcp__ai_sdk__`. SERVER_NAME = "ai_sdk" -"""The MCP server name the CLI sees. Claude Code calls a tool -`mcp__ai_sdk__`.""" PROTOCOL_VERSION = "2025-06-18" +# `on_call(name, arguments)` returns `(text, is_error)`. OnCall = Callable[[str, dict[str, Any]], Awaitable[tuple[str, bool]]] -"""`on_call(name, arguments)` returns `(text, is_error)`.""" class Bridge: diff --git a/src/ai/workers/_convert.py b/src/ai/workers/_convert.py new file mode 100644 index 00000000..62e6f88b --- /dev/null +++ b/src/ai/workers/_convert.py @@ -0,0 +1,116 @@ +"""What every adapter converts the same way. + +Prompt files go in as bytes or text. The CLI's own tool calls come out as +`BuiltinTool*` events. +""" + +from __future__ import annotations + +import base64 +from collections.abc import Sequence +from typing import Any + +from ..models.core.helpers import files +from ..types import events, media +from ..types import messages as messages_ +from . import _adapter +from . import _errors as errors + +# -- files in a prompt --------------------------------------------------------- +# +# Files are turned into bytes HERE: a URL is downloaded with the SDK's own +# SSRF-checked downloader, not handed to the CLI. Measured: Claude Code drops +# an image given by URL without a word. + + +async def data(part: messages_.FilePart) -> bytes: + """Return a file's bytes, downloading a URL first.""" + if isinstance(part.data, bytes): + return part.data + if media.is_downloadable_url(part.data): + body, _ = await files.download(part.data) + return body + return base64.b64decode(media.data_to_base64(part.data)) + + +async def as_text(part: messages_.FilePart) -> str: + """Return a text file as text a CLI reads inline, named if it has one.""" + body = (await data(part)).decode("utf-8", errors="replace") + name = part.filename or "attached file" + return f"\n{body}\n" + + +def check_files( + prompt: _adapter.Prompt, kind: str, accepts: Sequence[str] +) -> None: + """Refuse a file the CLI cannot take, before anything runs. + + Text files (`text/*`) go everywhere, as text. `accepts` lists the other + media type prefixes the CLI takes. + """ + for part in prompt: + if isinstance(part, messages_.FilePart) and not any( + part.media_type.startswith(p) for p in ("text/", *accepts) + ): + raise errors.WorkerError( + f"{kind} does not take {part.media_type} files" + ) + + +def text_of(prompt: _adapter.Prompt) -> str: + return "\n\n".join( + p.text for p in prompt if isinstance(p, messages_.TextPart) + ) + + +# -- the CLI's own tools as events -------------------------------------------- + + +def builtin_call( + tool_call_id: str, + tool_name: str, + tool_args: str, + *, + started: set[str], +) -> list[events.Event]: + """Return the events of one finished CLI tool call. + + `started` holds the calls whose start was already sent: the start is + sent here otherwise, because the hydrator only completes a call it saw + start. The arguments travel as a delta: the hydrator builds a call's + arguments only from its deltas. + """ + out: list[events.Event] = [] + if tool_call_id not in started: + started.add(tool_call_id) + out.append( + events.BuiltinToolStart( + tool_call_id=tool_call_id, tool_name=tool_name + ) + ) + return [ + *out, + events.BuiltinToolDelta(tool_call_id=tool_call_id, chunk=tool_args), + events.BuiltinToolEnd( + tool_call_id=tool_call_id, + tool_call=messages_.BuiltinToolCallPart( + tool_call_id=tool_call_id, + tool_name=tool_name, + tool_args=tool_args, + ), + ), + ] + + +def builtin_result( + tool_call_id: str, tool_name: str, result: Any, *, is_error: bool +) -> events.BuiltinToolResult: + return events.BuiltinToolResult( + tool_call_id=tool_call_id, + result=messages_.BuiltinToolReturnPart( + tool_call_id=tool_call_id, + tool_name=tool_name, + result=result, + is_error=is_error, + ), + ) diff --git a/src/ai/workers/_handoff.py b/src/ai/workers/_handoff.py new file mode 100644 index 00000000..62f0479d --- /dev/null +++ b/src/ai/workers/_handoff.py @@ -0,0 +1,218 @@ +"""Seeding a CLI with a past: one rendering rule, every CLI. + +A worker given `[*past, user_message]` on its first turn starts a new +conversation from `past`. Each CLI stores it natively so the agent truly +has the context, and the rule for what becomes what is the same everywhere: + +- text: verbatim, same role. +- tool calls and results: the NATIVE tool items, original name and + arguments unaltered. Measured: the receiving agent reads them as history + and acts with its own tools; it does not try to call a tool it lacks. + Names are not translated — mapping `Write` to `fileChange` would be the + invented taxonomy this SDK refuses everywhere else. Nor are PATHS: a call + that wrote /Users/x/proj/recipe.txt says so, and that is where it was + written. Across machines the receiver must be told where things are now + (or the workspace copied to the same path) — as any colleague would be. +- reasoning: a user-role handoff note after the turn it belonged to — where + the destination accepts it. Measured: fed back as the agent's OWN thoughts + it is rejected (Claude signs thinking blocks) or silently ignored (codex + accepts a reasoning item and never reads it). As a note, codex uses it. + Claude does NOT accept it in any form: Anthropic's safeguards flag real + model reasoning replayed as user content (`[reasoning_extraction]`) — + hand-written notes passed, genuine Opus thinking was refused. So the + Claude renderer omits reasoning, and the adapter warns with the count, + because dropping context silently is the one thing this SDK never does. + Pi omits it too, for both reasons: pi drops thinking another model wrote, + and pi often runs Claude. +- files: images go to every harness, as the image input each takes (pi + takes bytes, so an image known only by URL becomes a note naming it); + PDFs to Claude as documents. Anything else (a PDF into codex, a text + file) is left out and counted (`unsupported_files`), and the adapter + warns, like it does for reasoning into Claude. +""" + +from __future__ import annotations + +import 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) + + +# -- the two views of a past --------------------------------------------------- +# +# A worker's messages hold two kinds of tool calls. The tools an `ai.Agent` +# runs (through the bridge) are `ToolCallPart`s with their results in `tool` +# messages, like a model's. The tools the CLI runs itself are built-in +# parts, with the result in the same assistant message, like a provider's +# web search. A CLI's store holds both kinds the same way: a call, then its +# result in a message of its own. `harness_view` gives the renderers that +# one shape, so each renderer handles one kind of tool call, not two; +# `model_view` is its reverse, for a history read back from a store. + + +def harness_view(history: list[messages_.Message]) -> list[messages_.Message]: + """Return a past with the CLI's own tools as ordinary tool calls. + + A worker's messages hold the tools a CLI ran itself as + `BuiltinToolCallPart`/`BuiltinToolReturnPart`, the way a provider's web + search is. A CLI's store holds them as tool calls, each with its result + in a `tool` message after it. The renderers below read that shape. + """ + out: list[messages_.Message] = [] + for message in history: + parts: list[messages_.Part] = [] + results: list[messages_.Part] = [] + first = True + for part in message.parts: + if results and not isinstance( + part, messages_.BuiltinToolReturnPart + ): + # What follows a result comes after it: a new message. + if parts: + out.append(_split(message, parts, first=first)) + first = False + out.append(messages_.Message(role="tool", parts=results)) + parts, results = [], [] + if isinstance(part, messages_.BuiltinToolCallPart): + parts.append( + messages_.ToolCallPart( + tool_call_id=part.tool_call_id, + tool_name=part.tool_name, + tool_args=part.tool_args or "{}", + provider_metadata=part.provider_metadata, + ) + ) + elif isinstance(part, messages_.BuiltinToolReturnPart): + results.append( + messages_.ToolResultPart( + tool_call_id=part.tool_call_id, + tool_name=part.tool_name, + result=part.result, + result_kind="error" if part.is_error else "json", + ) + ) + else: + parts.append(part) + if parts: + out.append(_split(message, parts, first=first)) + if results: + out.append(messages_.Message(role="tool", parts=results)) + return out + + +def _split( + message: messages_.Message, parts: list[messages_.Part], *, first: bool +) -> messages_.Message: + """One piece of a message: the first keeps its id, the rest get new ones.""" + if first: + return message.model_copy(update={"parts": parts}) + return messages_.Message( + role=message.role, + parts=parts, + provider_metadata=message.provider_metadata, + ) + + +def model_view(stored: list[messages_.Message]) -> list[messages_.Message]: + """Return a stored conversation the way a worker shows it. + + The reverse of `harness_view`: the CLI's tool calls become built-in + parts, and each result joins the assistant message of its call. + """ + out: list[messages_.Message] = [] + owner: dict[str, int] = {} # tool_call_id -> index in `out` + for message in stored: + if message.role == "assistant": + parts: list[messages_.Part] = [] + for part in message.parts: + if isinstance(part, messages_.ToolCallPart): + owner[part.tool_call_id] = len(out) + parts.append( + messages_.BuiltinToolCallPart( + tool_call_id=part.tool_call_id, + tool_name=part.tool_name, + tool_args=part.tool_args, + provider_metadata=part.provider_metadata, + ) + ) + else: + parts.append(part) + out.append(message.model_copy(update={"parts": parts})) + elif message.role == "tool": + for result in message.tool_results: + index = owner.get(result.tool_call_id) + if index is None: + continue + target = out[index] + out[index] = target.model_copy( + update={ + "parts": [ + *target.parts, + messages_.BuiltinToolReturnPart( + tool_call_id=result.tool_call_id, + tool_name=result.tool_name + or _name_of(target, result.tool_call_id), + result=result.result, + is_error=result.result_kind == "error", + ), + ] + } + ) + else: + out.append(message) + return out + + +def _name_of(message: messages_.Message, tool_call_id: str) -> str: + return next( + ( + p.tool_name + for p in message.parts + if isinstance(p, messages_.BuiltinToolCallPart) + and p.tool_call_id == tool_call_id + ), + "", + ) + + +def warn_unsupported_files( + messages: list[messages_.Message], kind: str +) -> None: + """Say how many files a history held that `kind` was not given.""" + left = unsupported_files(messages, kind) + if left: + warnings.warn( + f"{left} file(s) in the history were not carried into {kind}: " + + "it takes images" + + (" and PDFs" if kind == "claude-code" else "") + + " from a history. Text, tool calls and images were carried.", + stacklevel=3, + ) + + +def unsupported_files(messages: list[messages_.Message], kind: str) -> int: + """Count files a history holds that `kind` cannot take as input.""" + return sum( + 1 + for m in messages + for p in m.parts + if isinstance(p, messages_.FilePart) + and not p.media_type.startswith("image/") + and not (kind == "claude-code" and p.media_type == "application/pdf") + ) + + +def reasoning_count(messages: list[messages_.Message]) -> int: + return sum( + 1 + for m in messages + for p in m.parts + if isinstance(p, messages_.ReasoningPart) and p.text.strip() + ) diff --git a/src/ai/workers/_kinds.py b/src/ai/workers/_kinds.py deleted file mode 100644 index e12c875f..00000000 --- a/src/ai/workers/_kinds.py +++ /dev/null @@ -1,128 +0,0 @@ -"""The workers: Claude Code, Codex and Pi. - -Each adds its CLI's own options to `Worker` and builds its adapter. -""" - -from __future__ import annotations - -from typing import Any, Literal - -import pydantic - -from ..providers import _optional -from . import _bridge, _worker -from ._adapters import base, codex, pi - - -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"`. - """ - - kind: Literal["claude-code"] = "claude-code" - allowed_tools: list[str] | None = None - disallowed_tools: list[str] | None = None - max_turns: int | None = None - - def _make_adapter( - self, - mcp_servers: dict[str, dict[str, Any]], - approve: base.Approve | None, - ) -> base.Adapter: - _optional.import_optional_sdk( - "claude_agent_sdk", - extra="claude-code", - feature="ai.workers.ClaudeCode", - ) - # Imported here: the adapter needs claude_agent_sdk at import time. - from ._adapters import claude # noqa: PLC0415 - - return claude.ClaudeAdapter( - cwd=self.cwd, - env=dict(self.env), - executable=self.executable or "claude", - model=self.model, - effort=self.effort, - mcp_servers=dict(mcp_servers), - approve=approve, - allowed_tools=self.allowed_tools, - disallowed_tools=self.disallowed_tools, - max_turns=self.max_turns, - ) - - -class Codex(_worker.Worker): - """Codex, over `codex app-server`. - - `sandbox` is Codex's own sandbox mode: `"read-only"`, - `"workspace-write"` or `"danger-full-access"` (the default). `config` - takes Codex `-c` overrides. - """ - - kind: Literal["codex"] = "codex" - sandbox: ( - Literal["read-only", "workspace-write", "danger-full-access"] | None - ) = None - config: dict[str, Any] = pydantic.Field(default_factory=dict) - - def _make_adapter( - self, - mcp_servers: dict[str, dict[str, Any]], - approve: base.Approve | None, - ) -> base.Adapter: - config = dict(self.config) - if self.effort is not None: - config.setdefault( - "model_reasoning_effort", - "xhigh" if self.effort == "max" else self.effort, - ) - if _bridge.SERVER_NAME in mcp_servers: - # Codex's default wait for an MCP tool (60s) is too short for a - # tool an `ai.Agent` runs, maybe after an approval. - config.setdefault( - f"mcp_servers.{_bridge.SERVER_NAME}.tool_timeout_sec", - 24 * 3600, - ) - return codex.CodexAdapter( - cwd=self.cwd, - env=dict(self.env), - executable=self.executable or "codex", - model=self.model, - mcp_servers=dict(mcp_servers), - approve=approve, - sandbox=self.sandbox, - config=config, - ) - - -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. - """ - - kind: Literal["pi"] = "pi" - allowed_tools: list[str] | None = None - disallowed_tools: list[str] | None = None - - def _make_adapter( - self, - mcp_servers: dict[str, dict[str, Any]], - approve: base.Approve | None, - ) -> base.Adapter: - return pi.PiAdapter( - cwd=self.cwd, - env=dict(self.env), - executable=self.executable or "pi", - model=self.model, - effort=self.effort, - mcp_servers=dict(mcp_servers), - approve=approve, - allowed_tools=self.allowed_tools, - disallowed_tools=self.disallowed_tools, - ) diff --git a/src/ai/workers/_worker.py b/src/ai/workers/_worker.py index 4670fa65..e4f462b6 100644 --- a/src/ai/workers/_worker.py +++ b/src/ai/workers/_worker.py @@ -38,18 +38,17 @@ from ..types import messages as messages_ from ..types import tools as tools_ from ..types import usage as usage_ -from . import _bridge +from . import _adapter, _bridge, _convert from . import _errors as errors -from ._adapters import base Effort = Literal["low", "medium", "high", "max"] +# Seconds to wait for more bridge calls before handing a batch to the caller. A +# CLI that calls tools in parallel sends them close together. BATCH_WINDOW = 0.05 -"""Seconds to wait for more bridge calls before handing a batch to the -caller. A CLI that calls tools in parallel sends them close together.""" +# How many times to ask again for output that does not validate. OUTPUT_RETRIES = 2 -"""How many times to ask again for output that does not validate.""" OUTPUT_INSTRUCTION = ( "\n\nRespond with ONLY a JSON value matching this schema, " @@ -96,7 +95,7 @@ class _Plan: class _Runtime: """What lives only while a worker is open. Never copied, never dumped.""" - adapter: base.Adapter + adapter: _adapter.CLIAdapter bridge: _bridge.Bridge lock: asyncio.Lock = dataclasses.field(default_factory=asyncio.Lock) in_session: bool = False @@ -184,8 +183,8 @@ def __deepcopy__(self, memo: dict[int, Any] | None = None) -> Self: def _make_adapter( self, mcp_servers: dict[str, dict[str, Any]], - approve: base.Approve | None, - ) -> base.Adapter: + approve: _adapter.Approve | None, + ) -> _adapter.CLIAdapter: raise NotImplementedError # -- ModelLike ------------------------------------------------------------ @@ -248,7 +247,7 @@ async def stream( if rt.queue is not None: # Tool results came with a new user message. The CLI is # still in its turn: the message is guidance for it. - await rt.adapter.steer(base.text_of(plan.prompt)) + await rt.adapter.steer(_convert.text_of(plan.prompt)) else: await self._ensure_session(plan) self._start(plan.prompt, output_type) @@ -752,7 +751,7 @@ async def tui(self) -> int: return code @classmethod - async def list_sessions(cls, **fields: Any) -> list[base.SessionInfo]: + async def list_sessions(cls, **fields: Any) -> list[_adapter.SessionInfo]: """Return the conversations the CLI has stored for a directory. Takes the worker's fields: `cwd=`, `env=`, `executable=`. 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/_adapters/claude.py b/src/ai/workers/claude_code/adapter.py similarity index 95% rename from src/ai/workers/_adapters/claude.py rename to src/ai/workers/claude_code/adapter.py index 7ca08b65..dae66044 100644 --- a/src/ai/workers/_adapters/claude.py +++ b/src/ai/workers/claude_code/adapter.py @@ -25,18 +25,18 @@ from ...types import events as events_ from ...types import messages as messages_ from ...types import usage as usage_ -from .. import _bridge +from .. import _adapter, _bridge, _convert, _handoff from .. import _errors as errors -from . import _handoff, base +from . import handoff 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" -"""The CLI the live tests last passed against. Older ones get a warning.""" +# 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 -"""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.""" AUTH_HINT = ( "claude-code uses your own login: run `claude` once and sign in, or " @@ -54,7 +54,7 @@ def __init__( model: str | None, effort: str | None, mcp_servers: dict[str, Any], - approve: base.Approve | None, + approve: _adapter.Approve | None, allowed_tools: list[str] | None, disallowed_tools: list[str] | None, max_turns: int | None, @@ -82,7 +82,7 @@ def __init__( self.version: str | None = None async def start(self) -> None: - self.version = await base.probe( + self.version = await _adapter.probe( KIND, self._executable, install=INSTALL, @@ -153,7 +153,7 @@ async def _stage(self, history: list[messages_.Message]) -> str: ) 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) + records = handoff.to_claude_records(history, session_id, self._cwd) text = "".join( json.dumps(r, separators=(",", ":")) + "\n" for r in records ) @@ -281,8 +281,10 @@ async def _can_use_tool( # -- turns ---------------------------------------------------------------- - async def turn(self, prompt: base.Prompt) -> AsyncIterator[events_.Event]: - base.check_files(prompt, KIND, ("image/", "application/pdf")) + async def turn( + self, prompt: _adapter.Prompt + ) -> AsyncIterator[events_.Event]: + _convert.check_files(prompt, KIND, ("image/", "application/pdf")) client = self._client assert client is not None # An interrupted turn leaves its trailing result unread: the CLI @@ -318,7 +320,7 @@ async def turn(self, prompt: base.Prompt) -> AsyncIterator[events_.Event]: for block in message.content: if isinstance(block, claude_agent_sdk.ToolUseBlock): names[block.id] = block.name - for event in base.builtin_call( + for event in _convert.builtin_call( block.id, block.name, json.dumps(block.input), @@ -333,7 +335,7 @@ async def turn(self, prompt: base.Prompt) -> AsyncIterator[events_.Event]: ) for block in content_blocks: if isinstance(block, claude_agent_sdk.ToolResultBlock): - yield base.builtin_result( + yield _convert.builtin_result( block.tool_use_id, names.get(block.tool_use_id, ""), block.content, @@ -390,12 +392,12 @@ async def history(self, session_id: str) -> list[messages_.Message]: out.extend(_stored_to_messages(record)) return _handoff.model_view(out) - async def list_sessions(self) -> list[base.SessionInfo]: + async def list_sessions(self) -> list[_adapter.SessionInfo]: infos = await asyncio.to_thread( claude_agent_sdk.list_sessions, self._cwd ) return [ - base.SessionInfo( + _adapter.SessionInfo( session_id=i.session_id, title=i.custom_title or i.summary or i.first_prompt, cwd=i.cwd, @@ -436,7 +438,7 @@ def tui_command( return argv, env, running_as -async def _content(prompt: base.Prompt) -> str | list[dict[str, Any]]: +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). @@ -448,7 +450,9 @@ async def _content(prompt: base.Prompt) -> str | list[dict[str, Any]]: if isinstance(part, messages_.TextPart): blocks.append({"type": "text", "text": part.text}) elif part.media_type.startswith("text/"): - blocks.append({"type": "text", "text": await base.as_text(part)}) + blocks.append( + {"type": "text", "text": await _convert.as_text(part)} + ) else: kind = ( "image" if part.media_type.startswith("image/") else "document" @@ -459,9 +463,9 @@ async def _content(prompt: base.Prompt) -> str | list[dict[str, Any]]: "source": { "type": "base64", "media_type": part.media_type, - "data": base64.b64encode(await base.data(part)).decode( - "ascii" - ), + "data": base64.b64encode( + await _convert.data(part) + ).decode("ascii"), }, } ) diff --git a/src/ai/workers/claude_code/handoff.py b/src/ai/workers/claude_code/handoff.py new file mode 100644 index 00000000..91245a3b --- /dev/null +++ b/src/ai/workers/claude_code/handoff.py @@ -0,0 +1,106 @@ +"""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 _handoff.harness_view(messages): + blocks: list[dict[str, Any]] = [] + for p in m.parts: + if isinstance(p, messages_.TextPart) and p.text.strip(): + blocks.append({"type": "text", "text": p.text}) + elif isinstance(p, messages_.FilePart) and m.role == "user": + if p.media_type.startswith("image/"): + blocks.append({"type": "image", "source": _source(p)}) + elif p.media_type == "application/pdf": + blocks.append({"type": "document", "source": _source(p)}) + elif isinstance(p, messages_.ToolCallPart): + try: + args = json.loads(p.tool_args) if p.tool_args else {} + except json.JSONDecodeError: + args = {"raw": p.tool_args} + blocks.append( + { + "type": "tool_use", + "id": p.tool_call_id or p.id, + "name": p.tool_name, + "input": args, + } + ) + elif isinstance(p, messages_.ToolResultPart): + blocks.append( + { + "type": "tool_result", + "tool_use_id": p.tool_call_id, + "content": _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: + # Tool results live in role="tool" messages in the IR; on disk + # the CLI keeps them as user records with tool_result blocks. + add("user" if m.role in ("user", "tool") else "assistant", blocks) + return records diff --git a/src/ai/workers/claude_code/worker.py b/src/ai/workers/claude_code/worker.py new file mode 100644 index 00000000..23af2612 --- /dev/null +++ b/src/ai/workers/claude_code/worker.py @@ -0,0 +1,49 @@ +"""`ClaudeCode`: Claude Code as a worker.""" + +from __future__ import annotations + +from typing import Any, Literal + +from ...providers import _optional +from .. import _adapter, _worker + + +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"`. + """ + + kind: Literal["claude-code"] = "claude-code" + allowed_tools: list[str] | None = None + disallowed_tools: list[str] | None = None + max_turns: int | None = None + + def _make_adapter( + self, + mcp_servers: dict[str, dict[str, Any]], + approve: _adapter.Approve | None, + ) -> _adapter.CLIAdapter: + _optional.import_optional_sdk( + "claude_agent_sdk", + extra="claude-code", + feature="ai.workers.ClaudeCode", + ) + # Imported here: the adapter needs claude_agent_sdk at import time. + from . import adapter # noqa: PLC0415 + + return adapter.ClaudeAdapter( + cwd=self.cwd, + env=dict(self.env), + executable=self.executable or "claude", + model=self.model, + effort=self.effort, + mcp_servers=dict(mcp_servers), + approve=approve, + allowed_tools=self.allowed_tools, + disallowed_tools=self.disallowed_tools, + max_turns=self.max_turns, + ) 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/_adapters/codex.py b/src/ai/workers/codex/adapter.py similarity index 95% rename from src/ai/workers/_adapters/codex.py rename to src/ai/workers/codex/adapter.py index 84dc8809..68bcb4b2 100644 --- a/src/ai/workers/_adapters/codex.py +++ b/src/ai/workers/codex/adapter.py @@ -22,19 +22,19 @@ from ...types import events as events_ from ...types import messages as messages_ from ...types import usage as usage_ -from .. import _bridge +from .. import _adapter, _bridge, _convert, _handoff from .. import _errors as errors -from . import _handoff, base, jsonrpc +from . import handoff, jsonrpc KIND = "codex" INSTALL = "npm install -g @openai/codex" +# The CLI the live tests last passed against. Older ones get a warning. VERIFIED_VERSION = "0.160.1" -"""The CLI the live tests last passed against. Older ones get a warning.""" +# Put on the turn's queue when app-server dies. CRASHED = "__crashed__" -"""Put on the turn's queue when app-server dies.""" LIST_PAGE_SIZE = 100 +# `list_sessions()` reads at most this many pages of threads. LIST_PAGES = 50 -"""`list_sessions()` reads at most this many pages of threads.""" APPROVAL_METHODS = ( "item/commandExecution/requestApproval", @@ -44,6 +44,7 @@ "applyPatchApproval", ) +# Item types that are the agent doing something, rather than speaking. TOOL_ITEMS = ( "fileChange", "commandExecution", @@ -51,7 +52,6 @@ "webSearch", "toolCall", ) -"""Item types that are the agent doing something, rather than speaking.""" AUTH_HINT = ( "codex uses your own login: run `codex login`, or pass " @@ -69,7 +69,7 @@ def __init__( executable: str, model: str | None, mcp_servers: dict[str, Any], - approve: base.Approve | None, + approve: _adapter.Approve | None, sandbox: str | None, config: dict[str, Any], ) -> None: @@ -88,7 +88,7 @@ def __init__( # CLI takes. An explicit config wins over the MCP servers. self._config = {**mcp_config(mcp_servers), **config} self._instructions: str | None = None - self._process: base.Process | None = None + self._process: jsonrpc.Process | None = None self._peer: jsonrpc.JsonRpcPeer | None = None self._thread: str | None = None self._turn: str | None = None @@ -98,7 +98,7 @@ def __init__( self.version: str | None = None async def start(self) -> None: - self.version = await base.probe( + self.version = await _adapter.probe( KIND, self._executable, install=INSTALL, @@ -106,7 +106,7 @@ async def start(self) -> None: cwd=self._cwd, env=self._env, ) - self._process = await base.spawn( + self._process = await jsonrpc.spawn( [self._executable, "app-server", *_config_args(self._config)], cwd=self._cwd, env=self._env, @@ -206,7 +206,7 @@ async def open( _handoff.warn_unsupported_files(seed, KIND) await self._rpc().call( "thread/inject_items", - {"threadId": thread, "items": _handoff.to_codex_items(seed)}, + {"threadId": thread, "items": handoff.to_codex_items(seed)}, ) return thread @@ -277,8 +277,10 @@ async def _on_request( # -- turns ---------------------------------------------------------------- - async def turn(self, prompt: base.Prompt) -> AsyncIterator[events_.Event]: - base.check_files(prompt, KIND, ("image/",)) + async def turn( + self, prompt: _adapter.Prompt + ) -> AsyncIterator[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() @@ -366,14 +368,14 @@ async def turn(self, prompt: base.Prompt) -> AsyncIterator[events_.Event]: open_reasoning.discard(item_id) yield events_.ReasoningEnd(block_id=item_id) elif kind in TOOL_ITEMS: - for event in base.builtin_call( + for event in _convert.builtin_call( item_id, _tool_name(item), json.dumps(_tool_args(item)), started=started, ): yield event - yield base.builtin_result( + yield _convert.builtin_result( item_id, _tool_name(item), _item_result(item), @@ -452,7 +454,7 @@ async def history(self, session_id: str) -> list[messages_.Message]: stored.extend(_item_to_messages(item)) return _handoff.model_view(stored) - async def list_sessions(self) -> list[base.SessionInfo]: + async def list_sessions(self) -> list[_adapter.SessionInfo]: # Asked for THIS directory, page by page: one unfiltered page of the # machine's store (measured: 3159 threads) missed threads from here. threads: list[dict[str, Any]] = [] @@ -471,7 +473,7 @@ async def list_sessions(self) -> list[base.SessionInfo]: if not cursor: break return [ - base.SessionInfo( + _adapter.SessionInfo( session_id=t.get("id", ""), title=t.get("name") or t.get("preview") or None, cwd=t.get("cwd"), @@ -507,7 +509,7 @@ def tui_command( return argv, dict(self._env), None -async def _input_items(prompt: base.Prompt) -> list[dict[str, Any]]: +async def _input_items(prompt: _adapter.Prompt) -> list[dict[str, Any]]: """Return a prompt as app-server's `UserInput` items. An image travels as a data URL, built here from its bytes. @@ -517,9 +519,11 @@ async def _input_items(prompt: base.Prompt) -> list[dict[str, Any]]: if isinstance(part, messages_.TextPart): items.append({"type": "text", "text": part.text}) elif part.media_type.startswith("text/"): - items.append({"type": "text", "text": await base.as_text(part)}) + items.append({"type": "text", "text": await _convert.as_text(part)}) else: - encoded = base64.b64encode(await base.data(part)).decode("ascii") + encoded = base64.b64encode(await _convert.data(part)).decode( + "ascii" + ) items.append( { "type": "image", diff --git a/src/ai/workers/codex/handoff.py b/src/ai/workers/codex/handoff.py new file mode 100644 index 00000000..ea637d78 --- /dev/null +++ b/src/ai/workers/codex/handoff.py @@ -0,0 +1,86 @@ +"""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]) -> str: + return ( + NOTE_PREFIX + " ".join(r.strip() for r in reasoning if r.strip()) + "]" + ) + + +def _image_url(part: messages_.FilePart) -> str: + """Return an http(s) URL as it is, anything else as a data URL.""" + return media.data_to_data_url(part.data, part.media_type) + + +def to_codex_items(messages: list[messages_.Message]) -> list[dict[str, Any]]: + """Responses API items for `thread/inject_items`.""" + items: list[dict[str, Any]] = [] + for m in _handoff.harness_view(messages): + reasoning: list[str] = [] + for p in m.parts: + if isinstance(p, messages_.TextPart) and p.text.strip(): + ctype = "input_text" if m.role == "user" else "output_text" + items.append( + { + "type": "message", + "role": m.role, + "content": [{"type": ctype, "text": p.text}], + } + ) + elif ( + isinstance(p, messages_.FilePart) + and m.role == "user" + and p.media_type.startswith("image/") + ): + items.append( + { + "type": "message", + "role": "user", + "content": [ + {"type": "input_image", "image_url": _image_url(p)} + ], + } + ) + elif isinstance(p, messages_.ToolCallPart): + items.append( + { + "type": "function_call", + "call_id": p.tool_call_id or p.id, + "name": p.tool_name, + "arguments": p.tool_args or "{}", + } + ) + elif isinstance(p, messages_.ToolResultPart): + items.append( + { + "type": "function_call_output", + "call_id": p.tool_call_id, + "output": _handoff.result_text(p.result), + } + ) + elif isinstance(p, messages_.ReasoningPart) and p.text.strip(): + reasoning.append(p.text) + if reasoning: + items.append( + { + "type": "message", + "role": "user", + "content": [ + {"type": "input_text", "text": _note(reasoning)} + ], + } + ) + return items diff --git a/src/ai/workers/_adapters/jsonrpc.py b/src/ai/workers/codex/jsonrpc.py similarity index 68% rename from src/ai/workers/_adapters/jsonrpc.py rename to src/ai/workers/codex/jsonrpc.py index 14837088..f5b0a8c1 100644 --- a/src/ai/workers/_adapters/jsonrpc.py +++ b/src/ai/workers/codex/jsonrpc.py @@ -1,4 +1,4 @@ -"""A small JSON-RPC 2.0 peer over a CLI's stdio. +"""The transport to `codex app-server`: its process, and JSON-RPC over stdio. Line-delimited JSON, request/response futures, and two callbacks for what a server can start. Nothing here is protocol-specific: the Codex adapter @@ -10,13 +10,19 @@ import asyncio import contextlib import json -from collections.abc import Awaitable, Callable -from typing import TYPE_CHECKING, Any +import os +from collections.abc import Awaitable, Callable, Mapping, Sequence +from typing import Any from .. import _errors as errors -if TYPE_CHECKING: - from . import base +# Longest line app-server may write. One JSON line can be megabytes (a +# `thread/read` of a long thread). With asyncio's default (64 KiB) such a line +# failed as if the CLI had crashed. +LINE_LIMIT = 256 * 1024 * 1024 + +# Seconds app-server gets to exit after SIGTERM, before SIGKILL. +TERM_GRACE = 3.0 NotifyHandler = Callable[[str, dict[str, Any]], Awaitable[None]] RequestHandler = Callable[[Any, str, dict[str, Any]], Awaitable[None]] @@ -30,7 +36,7 @@ def __init__(self, error: dict[str, Any]) -> None: class JsonRpcPeer: - def __init__(self, process: base.Process, *, kind: str) -> None: + def __init__(self, process: Process, *, kind: str) -> None: self._process = process self._kind = kind self._next_id = 0 @@ -208,3 +214,81 @@ def _resolve(self, message: dict[str, Any]) -> None: future.set_exception(JsonRpcError(message["error"])) else: future.set_result(message.get("result")) + + +# -- the process ------------------------------------------------------------- + + +class Process: + """A CLI started by `spawn`: JSON lines on stdin and stdout.""" + + def __init__(self, proc: asyncio.subprocess.Process) -> None: + self._proc = proc + + async def write(self, data: str) -> None: + assert self._proc.stdin is not None + self._proc.stdin.write(data.encode()) + await self._proc.stdin.drain() + + async def readline(self) -> str: + assert self._proc.stdout is not None + return (await self._proc.stdout.readline()).decode() + + async def read_stderr(self) -> str: + if self._proc.stderr is None: + return "" + return (await self._proc.stderr.read()).decode(errors="replace") + + async def wait(self) -> int: + return await self._proc.wait() + + async def terminate(self) -> None: + """Stop the process group: SIGTERM, then SIGKILL.""" + if self._proc.returncode is not None: + return + with contextlib.suppress(ProcessLookupError): + os.killpg(os.getpgid(self._proc.pid), 15) + try: + async with asyncio.timeout(TERM_GRACE): + await self._proc.wait() + except TimeoutError: + with contextlib.suppress(ProcessLookupError): + os.killpg(os.getpgid(self._proc.pid), 9) + with contextlib.suppress(Exception): + await self._proc.wait() + + async def death_note(self) -> str: + """Say how the process ended, and its last words.""" + code: int | None = None + tail = "" + with contextlib.suppress(Exception): + async with asyncio.timeout(2): + code = await self.wait() + with contextlib.suppress(Exception): + async with asyncio.timeout(2): + tail = (await self.read_stderr()).strip() + how = f"exit code {code}" if code is not None else "exited" + if code in (137, -9): + how += " (SIGKILL, typically the kernel's OOM killer)" + return f"{how}; stderr: {tail[-800:]}" if tail else f"{how}; no stderr" + + +async def spawn( + argv: Sequence[str], *, cwd: str, env: Mapping[str, str] +) -> Process: + """Start a CLI in its own process group, with pipes for stdio.""" + try: + proc = await asyncio.create_subprocess_exec( + *argv, + cwd=cwd, + env={**os.environ, **env}, + stdin=asyncio.subprocess.PIPE, + stdout=asyncio.subprocess.PIPE, + stderr=asyncio.subprocess.PIPE, + # Own the whole tree, so teardown reaches grandchildren too. + start_new_session=True, + limit=LINE_LIMIT, + ) + except OSError as exc: + raise errors.WorkerError(f"cannot start {argv[0]!r}: {exc}") from exc + return Process(proc) diff --git a/src/ai/workers/codex/worker.py b/src/ai/workers/codex/worker.py new file mode 100644 index 00000000..f0293481 --- /dev/null +++ b/src/ai/workers/codex/worker.py @@ -0,0 +1,54 @@ +"""`Codex`: Codex as a worker.""" + +from __future__ import annotations + +from typing import Any, Literal + +import pydantic + +from .. import _adapter, _bridge, _worker +from . import adapter + + +class Codex(_worker.Worker): + """Codex, over `codex app-server`. + + `sandbox` is Codex's own sandbox mode: `"read-only"`, + `"workspace-write"` or `"danger-full-access"` (the default). `config` + takes Codex `-c` overrides. + """ + + kind: Literal["codex"] = "codex" + sandbox: ( + Literal["read-only", "workspace-write", "danger-full-access"] | None + ) = None + config: dict[str, Any] = pydantic.Field(default_factory=dict) + + def _make_adapter( + self, + mcp_servers: dict[str, dict[str, Any]], + approve: _adapter.Approve | None, + ) -> _adapter.CLIAdapter: + config = dict(self.config) + if self.effort is not None: + config.setdefault( + "model_reasoning_effort", + "xhigh" if self.effort == "max" else self.effort, + ) + if _bridge.SERVER_NAME in mcp_servers: + # Codex's default wait for an MCP tool (60s) is too short for a + # tool an `ai.Agent` runs, maybe after an approval. + config.setdefault( + f"mcp_servers.{_bridge.SERVER_NAME}.tool_timeout_sec", + 24 * 3600, + ) + return adapter.CodexAdapter( + cwd=self.cwd, + env=dict(self.env), + executable=self.executable or "codex", + model=self.model, + mcp_servers=dict(mcp_servers), + approve=approve, + sandbox=self.sandbox, + config=config, + ) diff --git a/src/ai/workers/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/_adapters/pi.py b/src/ai/workers/pi/adapter.py similarity index 89% rename from src/ai/workers/_adapters/pi.py rename to src/ai/workers/pi/adapter.py index 6c64c731..bd44d73e 100644 --- a/src/ai/workers/_adapters/pi.py +++ b/src/ai/workers/pi/adapter.py @@ -5,7 +5,7 @@ the same conversation in pi's own TUI. pi has no permission prompt. Approval is an extension loaded into every pi -a worker starts (`pi_extension.js`): its `tool_call` handler asks through an +a worker starts (`extension.js`): its `tool_call` handler asks through an RPC dialog, and this adapter answers it. The protocol shapes here were measured against a real pi (see VERIFIED_VERSION). """ @@ -22,35 +22,43 @@ import re import uuid import warnings -from collections.abc import AsyncIterator +from collections.abc import AsyncIterator, Mapping, Sequence from typing import Any from ...types import events as events_ from ...types import messages as messages_ from ...types import usage as usage_ -from .. import _bridge +from .. import _adapter, _bridge, _convert, _handoff from .. import _errors as errors -from . import _handoff, base +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" -"""The CLI the live tests last passed against. Older ones get a warning.""" -EXTENSION = str(pathlib.Path(__file__).with_name("pi_extension.js")) +EXTENSION = str(pathlib.Path(__file__).with_name("extension.js")) +# The dialog title the extension asks approvals under. APPROVE = "ai-python:approve" -"""The dialog title the extension asks approvals under.""" +# The command the extension registers last: proof that it loaded. READY = "ai-python-ready" -"""The command the extension registers last: proof that it loaded.""" +# The environment variable that configures the extension. CONFIG_VAR = "AI_PYTHON_PI" -"""The environment variable that configures the extension.""" +# 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") -"""pi's rule for a session id: letters, digits, `.`, `_` and `-`, starting -and ending with a letter or digit. Never a path.""" +# Extension UI methods that wait for an answer; the rest are notices. DIALOGS = ("select", "confirm", "input", "editor") -"""Extension UI methods that wait for an answer; the rest are notices.""" 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': ...}." @@ -67,7 +75,7 @@ def __init__( model: str | None, effort: str | None, mcp_servers: dict[str, Any], - approve: base.Approve | None, + approve: _adapter.Approve | None, allowed_tools: list[str] | None, disallowed_tools: list[str] | None, ) -> None: @@ -89,7 +97,7 @@ def __init__( self.version: str | None = None async def start(self) -> None: - self.version = await base.probe( + self.version = await _adapter.probe( KIND, self._executable, install=INSTALL, @@ -169,7 +177,7 @@ async def _spawn(self, session_id: str, args: list[str]) -> None: A pi that cannot start (an unknown model, a bad flag) exits at once, and the handshake reports its last words. """ - process = await base.spawn( + process = await spawn( [self._executable, "--mode", "rpc", *args, *self._args()], cwd=self._cwd, env=self._extension_env( @@ -264,7 +272,7 @@ async def _stage(self, history: list[messages_.Message]) -> str: *changes, *( {"type": "message", "message": message} - for message in _handoff.to_pi_messages( + for message in handoff.to_pi_messages( history, timestamp=int(now.timestamp() * 1000) ) ), @@ -331,8 +339,10 @@ async def _on_dialog(self, agent: _Agent, request: dict[str, Any]) -> None: # -- turns ---------------------------------------------------------------- - async def turn(self, prompt: base.Prompt) -> AsyncIterator[events_.Event]: - base.check_files(prompt, KIND, ("image/",)) + async def turn( + self, prompt: _adapter.Prompt + ) -> AsyncIterator[events_.Event]: + _convert.check_files(prompt, KIND, ("image/",)) agent = self._agent assert agent is not None if agent.dead is not None: @@ -421,7 +431,7 @@ async def turn(self, prompt: base.Prompt) -> AsyncIterator[events_.Event]: # transcript: only the tool that made it reports it. call_id = str(event.get("toolCallId") or "") name = str(event.get("toolName") or "") - yield base.builtin_result( + yield _convert.builtin_result( call_id, name, _tool_result(event.get("result") or {}), @@ -554,9 +564,9 @@ async def history(self, session_id: str) -> list[messages_.Message]: stored.extend(_stored_to_messages(record)) return _handoff.model_view(stored) - async def list_sessions(self) -> list[base.SessionInfo]: + async def list_sessions(self) -> list[_adapter.SessionInfo]: return [ - base.SessionInfo( + _adapter.SessionInfo( session_id=s["id"], title=s.get("title"), cwd=s.get("cwd"), @@ -584,6 +594,84 @@ def tui_command( ) +# -- 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`.""" @@ -597,7 +685,7 @@ class _Agent: including the reply to an `abort` sent from inside it. """ - def __init__(self, process: base.Process, *, on_dialog: Any) -> None: + 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 @@ -730,7 +818,7 @@ def _resolve(self, record: dict[str, Any]) -> None: future.set_result(record.get("data")) -async def _prompt_command(prompt: base.Prompt) -> dict[str, Any]: +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]] = [] @@ -738,12 +826,12 @@ async def _prompt_command(prompt: base.Prompt) -> dict[str, Any]: if isinstance(part, messages_.TextPart): texts.append(part.text) elif part.media_type.startswith("text/"): - texts.append(await base.as_text(part)) + texts.append(await _convert.as_text(part)) else: images.append( { "type": "image", - "data": base64.b64encode(await base.data(part)).decode( + "data": base64.b64encode(await _convert.data(part)).decode( "ascii" ), "mimeType": part.media_type, @@ -795,7 +883,7 @@ def _stream_events( ) elif kind == "toolcall_end": call = _tool_call(update.get("toolCall") or {}) - out += base.builtin_call( + out += _convert.builtin_call( call.tool_call_id, call.tool_name, call.tool_args, started=started ) return out @@ -832,7 +920,7 @@ def _unstreamed( ] elif kind == "toolCall" and str(block.get("id")) not in started: call = _tool_call(block) - out += base.builtin_call( + out += _convert.builtin_call( call.tool_call_id, call.tool_name, call.tool_args, diff --git a/src/ai/workers/_adapters/pi_extension.js b/src/ai/workers/pi/extension.js similarity index 100% rename from src/ai/workers/_adapters/pi_extension.js rename to src/ai/workers/pi/extension.js diff --git a/src/ai/workers/pi/handoff.py b/src/ai/workers/pi/handoff.py new file mode 100644 index 00000000..5f4d20c6 --- /dev/null +++ b/src/ai/workers/pi/handoff.py @@ -0,0 +1,148 @@ +"""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, + }, + } + for m in _handoff.harness_view(messages): + if m.role == "tool": + for p in m.parts: + if isinstance(p, messages_.ToolResultPart): + out.append( + { + "role": "toolResult", + "toolCallId": p.tool_call_id, + "toolName": p.tool_name, + "content": [ + { + "type": "text", + "text": _handoff.result_text(p.result), + } + ], + "isError": p.result_kind == "error", + "timestamp": timestamp, + } + ) + continue + blocks: list[dict[str, Any]] = [] + for p in m.parts: + if isinstance(p, messages_.TextPart) and p.text.strip(): + blocks.append({"type": "text", "text": p.text}) + elif ( + isinstance(p, messages_.FilePart) + and m.role == "user" + and p.media_type.startswith("image/") + ): + if isinstance(p.data, str) and media.is_downloadable_url( + p.data + ): + blocks.append( + {"type": "text", "text": f"[image: {p.data}]"} + ) + else: + blocks.append( + { + "type": "image", + "data": media.data_to_base64(p.data), + "mimeType": p.media_type, + } + ) + elif ( + isinstance(p, messages_.ToolCallPart) and m.role == "assistant" + ): + try: + args = json.loads(p.tool_args) if p.tool_args else {} + except json.JSONDecodeError: + args = {"raw": p.tool_args} + blocks.append( + { + "type": "toolCall", + "id": p.tool_call_id or p.id, + "name": p.tool_name, + "arguments": args if isinstance(args, dict) else {}, + } + ) + if not blocks: + continue + if m.role == "system": + # Measured (pi 1.3.0): a system message in a session file is + # pi's own prompt state, and replaying one REPLACED pi's system + # prompt and its tools. So instructions travel as what they are + # to the agent — the caller's words — never as its own output. + text = " ".join(b["text"] for b in blocks if b["type"] == "text") + blocks = [{"type": "text", "text": SYSTEM_PREFIX + text + "]"}] + if m.role in ("user", "system"): + out.append( + {"role": "user", "content": blocks, "timestamp": timestamp} + ) + continue + if out and out[-1]["role"] == "assistant": + out[-1]["content"] += blocks + else: + # A reply pi wrote keeps its author: pi restores a session's model + # from its last reply's, and a model it does not know (ours) + # put the conversation on pi's default one (measured). + author = (m.provider_metadata or {}).get("pi") or {} + known = all(isinstance(author.get(k), str) for k in AUTHOR) + out.append( + { + "role": "assistant", + "content": blocks, + **( + {k: author[k] for k in AUTHOR} + if known + else { + "api": "ai-python", + "provider": "ai-python", + "model": "handoff", + } + ), + "usage": usage, + "stopReason": "stop", + "timestamp": timestamp, + } + ) + if any(b["type"] == "toolCall" for b in out[-1]["content"]): + out[-1]["stopReason"] = "toolUse" + return out diff --git a/src/ai/workers/pi/worker.py b/src/ai/workers/pi/worker.py new file mode 100644 index 00000000..0bde399f --- /dev/null +++ b/src/ai/workers/pi/worker.py @@ -0,0 +1,37 @@ +"""`Pi`: pi as a worker.""" + +from __future__ import annotations + +from typing import Any, Literal + +from .. import _adapter, _worker +from . import adapter + + +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. + """ + + kind: Literal["pi"] = "pi" + allowed_tools: list[str] | None = None + disallowed_tools: list[str] | None = None + + def _make_adapter( + self, + mcp_servers: dict[str, dict[str, Any]], + approve: _adapter.Approve | None, + ) -> _adapter.CLIAdapter: + return adapter.PiAdapter( + cwd=self.cwd, + env=dict(self.env), + executable=self.executable or "pi", + model=self.model, + effort=self.effort, + mcp_servers=dict(mcp_servers), + approve=approve, + allowed_tools=self.allowed_tools, + disallowed_tools=self.disallowed_tools, + ) diff --git a/src/ai/workers/_adapters/__init__.py b/tests/workers/claude_code/__init__.py similarity index 100% rename from src/ai/workers/_adapters/__init__.py rename to tests/workers/claude_code/__init__.py diff --git a/tests/workers/_adapters/test_claude.py b/tests/workers/claude_code/test_adapter.py similarity index 96% rename from tests/workers/_adapters/test_claude.py rename to tests/workers/claude_code/test_adapter.py index 6854d5e4..a8d4d801 100644 --- a/tests/workers/_adapters/test_claude.py +++ b/tests/workers/claude_code/test_adapter.py @@ -15,7 +15,7 @@ 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._adapters import claude # noqa: E402 +from ai.workers.claude_code import adapter as adapter_ # noqa: E402 def _stream(event: dict[str, Any]) -> Any: @@ -109,8 +109,8 @@ async def disconnect(self) -> None: pass -def _adapter(tmp_path: Path, **options: Any) -> claude.ClaudeAdapter: - return claude.ClaudeAdapter( +def _adapter(tmp_path: Path, **options: Any) -> adapter_.ClaudeAdapter: + return adapter_.ClaudeAdapter( cwd=str(tmp_path), env={"CLAUDE_CONFIG_DIR": str(tmp_path / "config")}, executable="claude", @@ -124,7 +124,7 @@ def _adapter(tmp_path: Path, **options: Any) -> claude.ClaudeAdapter: ) -async def _turn(adapter: claude.ClaudeAdapter, *prompt: Any) -> list[Any]: +async def _turn(adapter: adapter_.ClaudeAdapter, *prompt: Any) -> list[Any]: async with asyncio.timeout(5): return [e async for e in adapter.turn(list(prompt))] @@ -286,9 +286,9 @@ def test_a_stored_transcript_reads_as_the_model_view() -> None: parent_tool_use_id=None, ), ] - from ai.workers._adapters import _handoff + from ai.workers import _handoff - stored = [msg for r in records for msg in claude._stored_to_messages(r)] + stored = [msg for r in records for msg in adapter_._stored_to_messages(r)] history = _handoff.model_view(stored) assert [x.role for x in history] == ["user", "assistant"] call, result = history[1].parts diff --git a/tests/workers/_adapters/__init__.py b/tests/workers/codex/__init__.py similarity index 100% rename from tests/workers/_adapters/__init__.py rename to tests/workers/codex/__init__.py diff --git a/tests/workers/_adapters/test_codex.py b/tests/workers/codex/test_adapter.py similarity index 98% rename from tests/workers/_adapters/test_codex.py rename to tests/workers/codex/test_adapter.py index de1fedb9..16e82303 100644 --- a/tests/workers/_adapters/test_codex.py +++ b/tests/workers/codex/test_adapter.py @@ -12,7 +12,8 @@ from ai import workers from ai.types import events from ai.types import messages as m -from ai.workers._adapters import codex, jsonrpc +from ai.workers.codex import adapter as adapter_ +from ai.workers.codex import jsonrpc from .. import fakes @@ -98,8 +99,8 @@ def note(method: str, **params: Any) -> dict[str, Any]: def _adapter( server: AppServer, approve: Any = None, **options: Any -) -> codex.CodexAdapter: - adapter = codex.CodexAdapter( +) -> adapter_.CodexAdapter: + adapter = adapter_.CodexAdapter( cwd=CWD, env={}, executable="codex", @@ -119,7 +120,7 @@ def _adapter( return adapter -async def _turn(adapter: codex.CodexAdapter, text: str = "go") -> list[Any]: +async def _turn(adapter: adapter_.CodexAdapter, text: str = "go") -> list[Any]: async with asyncio.timeout(5): return [e async for e in adapter.turn([m.TextPart(text=text)])] diff --git a/tests/workers/_adapters/test_jsonrpc.py b/tests/workers/codex/test_jsonrpc.py similarity index 99% rename from tests/workers/_adapters/test_jsonrpc.py rename to tests/workers/codex/test_jsonrpc.py index a6849316..23deb002 100644 --- a/tests/workers/_adapters/test_jsonrpc.py +++ b/tests/workers/codex/test_jsonrpc.py @@ -9,7 +9,7 @@ import pytest from ai import workers -from ai.workers._adapters import jsonrpc +from ai.workers.codex import jsonrpc from .. import fakes diff --git a/tests/workers/fakes.py b/tests/workers/fakes.py index 51ed6b6c..200e8525 100644 --- a/tests/workers/fakes.py +++ b/tests/workers/fakes.py @@ -15,7 +15,7 @@ from ai.types import events from ai.types import messages as m from ai.types import usage as usage_ -from ai.workers._adapters import base +from ai.workers import _adapter, _convert @dataclasses.dataclass @@ -56,8 +56,8 @@ def tool( ) -> list[Step]: """One of the CLI's own tool calls, start to result.""" return [ - *base.builtin_call(call_id, name, args, started=set()), - base.builtin_result(call_id, name, result, is_error=False), + *_convert.builtin_call(call_id, name, args, started=set()), + _convert.builtin_result(call_id, name, result, is_error=False), ] @@ -67,7 +67,9 @@ def reply(prompt: str) -> list[Step]: class FakeAdapter: - def __init__(self, script: Script, approve: base.Approve | None) -> None: + def __init__( + self, script: Script, approve: _adapter.Approve | None + ) -> None: self.script = script self.approve = approve self.version: str | None = None @@ -106,11 +108,13 @@ async def open( return f"{session_id}-fork" return session_id or "s1" - async def turn(self, prompt: base.Prompt) -> AsyncIterator[events.Event]: - self.turns.append(base.text_of(prompt)) + async def turn( + self, prompt: _adapter.Prompt + ) -> AsyncIterator[events.Event]: + self.turns.append(_convert.text_of(prompt)) self._resume.clear() yield events.StreamStart() - for step in self.script(base.text_of(prompt)): + for step in self.script(_convert.text_of(prompt)): if isinstance(step, Pause): await self._resume.wait() yield events.StreamEnd(finish_reason="cancelled") @@ -141,8 +145,8 @@ async def interrupt(self) -> None: async def history(self, session_id: str) -> list[m.Message]: return self.stored.get(session_id, []) - async def list_sessions(self) -> list[base.SessionInfo]: - return [base.SessionInfo(session_id="s1", title="first")] + async def list_sessions(self) -> list[_adapter.SessionInfo]: + return [_adapter.SessionInfo(session_id="s1", title="first")] def tui_command( self, session_id: str | None @@ -167,8 +171,8 @@ class FakeWorker(workers.Worker): def _make_adapter( self, mcp_servers: dict[str, dict[str, Any]], - approve: base.Approve | None, - ) -> base.Adapter: + approve: _adapter.Approve | None, + ) -> _adapter.CLIAdapter: self._fake = FakeAdapter(self._run, approve) self._servers = mcp_servers return self._fake @@ -203,7 +207,6 @@ def __init__( self._lines: asyncio.Queue[str] = asyncio.Queue() self.answer = answer or (lambda message: {}) self.written: list[dict[str, Any]] = [] - self.pid = 0 def server_says(self, message: dict[str, Any]) -> None: self._lines.put_nowait(json.dumps(message) + "\n") diff --git a/tests/workers/pi/__init__.py b/tests/workers/pi/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/tests/workers/_adapters/test_pi.py b/tests/workers/pi/test_adapter.py similarity index 97% rename from tests/workers/_adapters/test_pi.py rename to tests/workers/pi/test_adapter.py index 86f99ccb..a3ce5e9d 100644 --- a/tests/workers/_adapters/test_pi.py +++ b/tests/workers/pi/test_adapter.py @@ -16,7 +16,7 @@ from ai import workers from ai.types import events from ai.types import messages as m -from ai.workers._adapters import pi +from ai.workers.pi import adapter as adapter_ from .. import fakes @@ -147,8 +147,8 @@ def sent(self, kind: str) -> list[dict[str, Any]]: def _adapter( server: Pi | None = None, approve: Any = None, cwd: str = "/w", **env: str -) -> pi.PiAdapter: - adapter = pi.PiAdapter( +) -> adapter_.PiAdapter: + adapter = adapter_.PiAdapter( cwd=cwd, env=env, executable="pi", @@ -160,7 +160,7 @@ def _adapter( disallowed_tools=None, ) if server is not None: - agent = pi._Agent( + agent = adapter_._Agent( cast("Any", server.process), on_dialog=adapter._on_dialog ) agent.start() @@ -168,7 +168,7 @@ def _adapter( return adapter -async def _turn(adapter: pi.PiAdapter, *prompt: Any) -> list[Any]: +async def _turn(adapter: adapter_.PiAdapter, *prompt: Any) -> list[Any]: parts: list[m.TextPart | m.FilePart] = list(prompt) or [ m.TextPart(text="go") ] @@ -251,7 +251,7 @@ def _ask(server: Pi) -> None: "type": "extension_ui_request", "id": "ui-1", "method": "input", - "title": pi.APPROVE, + "title": adapter_.APPROVE, "placeholder": json.dumps( { "toolCallId": "toolu_1", @@ -423,8 +423,8 @@ def test_history_follows_the_active_branch_only() -> None: text = "\n".join(json.dumps(line) for line in lines) stored = [ msg - for entry in pi._active_branch(text) - for msg in pi._stored_to_messages(entry) + for entry in adapter_._active_branch(text) + for msg in adapter_._stored_to_messages(entry) ] assert [msg.role for msg in stored] == ["user", "assistant", "tool"] result = stored[2].parts[0] @@ -501,7 +501,7 @@ async def test_a_seeded_pi_conversation_stays_on_its_model( } seed = [ m.Message(role="user", parts=[m.TextPart(text="hello")]), - *pi._stored_to_messages(stored), + *adapter_._stored_to_messages(stored), ] session_id = await adapter._stage(seed) (written,) = agent_dir.glob(f"sessions/*/*_{session_id}.jsonl") @@ -525,7 +525,7 @@ async def test_a_seeded_pi_conversation_stays_on_its_model( def test_options_reach_pi_in_its_own_spelling() -> None: - adapter = pi.PiAdapter( + adapter = adapter_.PiAdapter( cwd="/w", env={"K": "v"}, executable="pi", @@ -541,14 +541,14 @@ def test_options_reach_pi_in_its_own_spelling() -> None: ) argv, env, minted = adapter.tui_command(None) assert argv[:3] == ["pi", "--session-id", minted] - assert argv[3:5] == ["-e", pi.EXTENSION] + assert argv[3:5] == ["-e", adapter_.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[pi.CONFIG_VAR]) == { + assert json.loads(env[adapter_.CONFIG_VAR]) == { "approve": False, "mcp": {"docs": {"command": "docs-mcp"}}, } diff --git a/tests/workers/_adapters/test_handoff.py b/tests/workers/test_handoff.py similarity index 90% rename from tests/workers/_adapters/test_handoff.py rename to tests/workers/test_handoff.py index 4f55dadd..7dcdf1fd 100644 --- a/tests/workers/_adapters/test_handoff.py +++ b/tests/workers/test_handoff.py @@ -19,7 +19,10 @@ ToolCallPart, ToolResultPart, ) -from ai.workers._adapters import _handoff +from ai.workers import _handoff +from ai.workers.claude_code import handoff as claude_handoff +from ai.workers.codex import handoff as codex_handoff +from ai.workers.pi import handoff as pi_handoff HISTORY = [ Message(role="user", parts=[TextPart(text="Create recipe.txt")]), @@ -76,7 +79,7 @@ def test_codex_items_follow_the_rule() -> None: - items = _handoff.to_codex_items(HISTORY) + items = codex_handoff.to_codex_items(HISTORY) kinds = [(i["type"], i.get("role")) for i in items] assert kinds == [ ("message", "user"), @@ -94,18 +97,18 @@ def test_codex_items_follow_the_rule() -> None: assert out["call_id"] == "call_1" assert out["output"] == json.dumps({"ok": True}) note = items[3]["content"][0]["text"] - assert note.startswith(_handoff.NOTE_PREFIX) + assert note.startswith(codex_handoff.NOTE_PREFIX) assert "Write is the tool" in note def test_the_model_view_seeds_the_same_items() -> None: - assert _handoff.to_codex_items(MODEL_VIEW) == _handoff.to_codex_items( - HISTORY - ) + assert codex_handoff.to_codex_items( + MODEL_VIEW + ) == codex_handoff.to_codex_items(HISTORY) def test_claude_records_follow_the_rule() -> None: - recs = _handoff.to_claude_records(MODEL_VIEW, "sid-1", "/w") + recs = claude_handoff.to_claude_records(MODEL_VIEW, "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] == [ @@ -133,7 +136,7 @@ def test_claude_records_follow_the_rule() -> None: def test_pi_merges_assistant_messages_and_keeps_tool_results() -> None: - rendered = _handoff.to_pi_messages( + rendered = pi_handoff.to_pi_messages( [ Message(role="user", parts=[TextPart(text="hi")]), Message(role="assistant", parts=[TextPart(text="one")]), @@ -216,11 +219,11 @@ def test_a_stored_result_without_a_name_takes_its_calls() -> None: def test_reasoning_is_never_the_agents_own_thought() -> None: """No thinking block, no reasoning item: both were measured to fail, one rejected, one silently ignored. It travels as a note, or not at all.""" - items = _handoff.to_codex_items(HISTORY) + items = codex_handoff.to_codex_items(HISTORY) assert not any(i["type"] == "reasoning" for i in items) blocks = [ b - for r in _handoff.to_claude_records(HISTORY, "s", "/w") + for r in claude_handoff.to_claude_records(HISTORY, "s", "/w") if isinstance(r["message"]["content"], list) for b in r["message"]["content"] ] @@ -229,6 +232,6 @@ def test_reasoning_is_never_the_agents_own_thought() -> None: def test_empty_parts_produce_nothing() -> None: blank = [Message(role="assistant", parts=[TextPart(text=" ")])] - assert _handoff.to_codex_items(blank) == [] + assert codex_handoff.to_codex_items(blank) == [] empty = [Message(role="assistant", parts=[ReasoningPart(text="")])] - assert _handoff.to_claude_records(empty, "s", "/w") == [] + assert claude_handoff.to_claude_records(empty, "s", "/w") == [] From 4f358b36c86d61f1708ba7b0e8cb4ec4b946b309 Mon Sep 17 00:00:00 2001 From: Andrey Buzin Date: Fri, 6 Nov 2026 14:14:15 -0800 Subject: [PATCH 5/6] Handle CLI tool calls in each adapter, built-in parts everywhere else --- src/ai/workers/_adapter.py | 13 +- src/ai/workers/_handoff.py | 137 --------------------- src/ai/workers/claude_code/adapter.py | 71 +++++++---- src/ai/workers/claude_code/handoff.py | 35 +++++- src/ai/workers/codex/adapter.py | 25 ++-- src/ai/workers/codex/handoff.py | 45 ++++--- src/ai/workers/pi/adapter.py | 60 +++++++--- src/ai/workers/pi/handoff.py | 139 ++++++++++++---------- tests/workers/claude_code/test_adapter.py | 8 +- tests/workers/codex/test_adapter.py | 2 +- tests/workers/pi/test_adapter.py | 15 +-- tests/workers/test_handoff.py | 97 +++++++-------- 12 files changed, 307 insertions(+), 340 deletions(-) diff --git a/src/ai/workers/_adapter.py b/src/ai/workers/_adapter.py index fd34f25b..ef5dce7d 100644 --- a/src/ai/workers/_adapter.py +++ b/src/ai/workers/_adapter.py @@ -1,9 +1,14 @@ """The adapter protocol: what `Worker` needs from each CLI. -An adapter drives ONE conversation with one CLI. It speaks the model view -both ways: `turn()` yields the events of one assistant message, with the -CLI's own tools as `BuiltinTool*` events, and ends with a `StreamEnd`; a -history it reads or is seeded with is a plain `list[Message]`. +An adapter drives ONE conversation with one CLI. Outside it, the CLI's own +tools are built-in tools, and nothing else: `turn()` yields them as +`BuiltinTool*` events, and a history it reads holds them as built-in parts, +each result in the assistant message of its call. A seed holds them the +same way, next to the calls and `tool` messages of the tools an `ai.Agent` +ran. How the CLI stores a tool call is the adapter's business alone. + +`turn()` yields the events of one assistant message and ends with a +`StreamEnd`. """ from __future__ import annotations diff --git a/src/ai/workers/_handoff.py b/src/ai/workers/_handoff.py index 62f0479d..e51f1bc6 100644 --- a/src/ai/workers/_handoff.py +++ b/src/ai/workers/_handoff.py @@ -45,143 +45,6 @@ def result_text(value: Any) -> str: return value if isinstance(value, str) else json.dumps(value) -# -- the two views of a past --------------------------------------------------- -# -# A worker's messages hold two kinds of tool calls. The tools an `ai.Agent` -# runs (through the bridge) are `ToolCallPart`s with their results in `tool` -# messages, like a model's. The tools the CLI runs itself are built-in -# parts, with the result in the same assistant message, like a provider's -# web search. A CLI's store holds both kinds the same way: a call, then its -# result in a message of its own. `harness_view` gives the renderers that -# one shape, so each renderer handles one kind of tool call, not two; -# `model_view` is its reverse, for a history read back from a store. - - -def harness_view(history: list[messages_.Message]) -> list[messages_.Message]: - """Return a past with the CLI's own tools as ordinary tool calls. - - A worker's messages hold the tools a CLI ran itself as - `BuiltinToolCallPart`/`BuiltinToolReturnPart`, the way a provider's web - search is. A CLI's store holds them as tool calls, each with its result - in a `tool` message after it. The renderers below read that shape. - """ - out: list[messages_.Message] = [] - for message in history: - parts: list[messages_.Part] = [] - results: list[messages_.Part] = [] - first = True - for part in message.parts: - if results and not isinstance( - part, messages_.BuiltinToolReturnPart - ): - # What follows a result comes after it: a new message. - if parts: - out.append(_split(message, parts, first=first)) - first = False - out.append(messages_.Message(role="tool", parts=results)) - parts, results = [], [] - if isinstance(part, messages_.BuiltinToolCallPart): - parts.append( - messages_.ToolCallPart( - tool_call_id=part.tool_call_id, - tool_name=part.tool_name, - tool_args=part.tool_args or "{}", - provider_metadata=part.provider_metadata, - ) - ) - elif isinstance(part, messages_.BuiltinToolReturnPart): - results.append( - messages_.ToolResultPart( - tool_call_id=part.tool_call_id, - tool_name=part.tool_name, - result=part.result, - result_kind="error" if part.is_error else "json", - ) - ) - else: - parts.append(part) - if parts: - out.append(_split(message, parts, first=first)) - if results: - out.append(messages_.Message(role="tool", parts=results)) - return out - - -def _split( - message: messages_.Message, parts: list[messages_.Part], *, first: bool -) -> messages_.Message: - """One piece of a message: the first keeps its id, the rest get new ones.""" - if first: - return message.model_copy(update={"parts": parts}) - return messages_.Message( - role=message.role, - parts=parts, - provider_metadata=message.provider_metadata, - ) - - -def model_view(stored: list[messages_.Message]) -> list[messages_.Message]: - """Return a stored conversation the way a worker shows it. - - The reverse of `harness_view`: the CLI's tool calls become built-in - parts, and each result joins the assistant message of its call. - """ - out: list[messages_.Message] = [] - owner: dict[str, int] = {} # tool_call_id -> index in `out` - for message in stored: - if message.role == "assistant": - parts: list[messages_.Part] = [] - for part in message.parts: - if isinstance(part, messages_.ToolCallPart): - owner[part.tool_call_id] = len(out) - parts.append( - messages_.BuiltinToolCallPart( - tool_call_id=part.tool_call_id, - tool_name=part.tool_name, - tool_args=part.tool_args, - provider_metadata=part.provider_metadata, - ) - ) - else: - parts.append(part) - out.append(message.model_copy(update={"parts": parts})) - elif message.role == "tool": - for result in message.tool_results: - index = owner.get(result.tool_call_id) - if index is None: - continue - target = out[index] - out[index] = target.model_copy( - update={ - "parts": [ - *target.parts, - messages_.BuiltinToolReturnPart( - tool_call_id=result.tool_call_id, - tool_name=result.tool_name - or _name_of(target, result.tool_call_id), - result=result.result, - is_error=result.result_kind == "error", - ), - ] - } - ) - else: - out.append(message) - return out - - -def _name_of(message: messages_.Message, tool_call_id: str) -> str: - return next( - ( - p.tool_name - for p in message.parts - if isinstance(p, messages_.BuiltinToolCallPart) - and p.tool_call_id == tool_call_id - ), - "", - ) - - def warn_unsupported_files( messages: list[messages_.Message], kind: str ) -> None: diff --git a/src/ai/workers/claude_code/adapter.py b/src/ai/workers/claude_code/adapter.py index dae66044..d4964c3d 100644 --- a/src/ai/workers/claude_code/adapter.py +++ b/src/ai/workers/claude_code/adapter.py @@ -18,7 +18,7 @@ import uuid import warnings from collections.abc import AsyncIterator -from typing import Any +from typing import Any, Literal import claude_agent_sdk @@ -387,10 +387,7 @@ async def history(self, session_id: str) -> list[messages_.Message]: stored = await asyncio.to_thread( claude_agent_sdk.get_session_messages, session_id, self._cwd ) - out: list[messages_.Message] = [] - for record in stored: - out.extend(_stored_to_messages(record)) - return _handoff.model_view(out) + return _read(stored) async def list_sessions(self) -> list[_adapter.SessionInfo]: infos = await asyncio.to_thread( @@ -574,11 +571,47 @@ def _stream_events( return out -def _stored_to_messages(record: Any) -> list[messages_.Message]: - """One stored transcript record -> messages, shaped like a live turn's. +def _read(records: list[Any]) -> list[messages_.Message]: + """Read stored transcript records as messages, like a live turn's. - Tool results become their own `tool` message; `_handoff.model_view` - then folds them into the model view. + 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 @@ -588,7 +621,7 @@ def _stored_to_messages(record: Any) -> list[messages_.Message]: else: blocks = content if isinstance(content, list) else [] parts: list[Any] = [] - tool_results: list[Any] = [] + results: list[dict[str, Any]] = [] for block in blocks: if not isinstance(block, dict): continue @@ -612,24 +645,12 @@ def _stored_to_messages(record: Any) -> list[messages_.Message]: parts.append(messages_.ReasoningPart(text=block["thinking"])) elif kind == "tool_use": parts.append( - messages_.ToolCallPart( + 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": - tool_results.append( - messages_.ToolResultPart( - tool_call_id=block.get("tool_use_id", ""), - tool_name="", - result=block.get("content"), - result_kind="error" if block.get("is_error") else "json", - ) - ) - out: list[messages_.Message] = [] - if parts and role in ("user", "assistant"): - out.append(messages_.Message(role=role, parts=parts)) - if tool_results: - out.append(messages_.Message(role="tool", parts=tool_results)) - return out + results.append(block) + return (role if role in ("user", "assistant") else None), parts, results diff --git a/src/ai/workers/claude_code/handoff.py b/src/ai/workers/claude_code/handoff.py index 91245a3b..15800dc4 100644 --- a/src/ai/workers/claude_code/handoff.py +++ b/src/ai/workers/claude_code/handoff.py @@ -61,9 +61,30 @@ def add(role: str, content: Any) -> None: ) parent = uid - for m in _handoff.harness_view(messages): + 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": @@ -71,7 +92,9 @@ def add(role: str, content: Any) -> None: 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): + elif isinstance( + p, messages_.ToolCallPart | messages_.BuiltinToolCallPart + ): try: args = json.loads(p.tool_args) if p.tool_args else {} except json.JSONDecodeError: @@ -85,6 +108,8 @@ def add(role: str, content: Any) -> None: } ) 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", @@ -100,7 +125,7 @@ def add(role: str, content: Any) -> None: # ReasoningPart: omitted on purpose — Anthropic's safeguards # refuse replayed reasoning. The adapter warns with the count. if blocks: - # Tool results live in role="tool" messages in the IR; on disk - # the CLI keeps them as user records with tool_result blocks. - add("user" if m.role in ("user", "tool") else "assistant", blocks) + add(role, blocks) + if results: + add("user", results) return records diff --git a/src/ai/workers/codex/adapter.py b/src/ai/workers/codex/adapter.py index 68bcb4b2..47a176a1 100644 --- a/src/ai/workers/codex/adapter.py +++ b/src/ai/workers/codex/adapter.py @@ -448,11 +448,11 @@ async def history(self, session_id: str) -> list[messages_.Message]: "thread/read", {"threadId": session_id, "includeTurns": True, "itemsView": "full"}, ) - stored: list[messages_.Message] = [] + out: list[messages_.Message] = [] for turn in ((result or {}).get("thread") or {}).get("turns") or []: for item in turn.get("items") or []: - stored.extend(_item_to_messages(item)) - return _handoff.model_view(stored) + out.extend(_item_to_messages(item)) + return out async def list_sessions(self) -> list[_adapter.SessionInfo]: # Asked for THIS directory, page by page: one unfiltered page of the @@ -585,7 +585,11 @@ def _reasoning_text(item: dict[str, Any]) -> str: def _item_to_messages(item: dict[str, Any]) -> list[messages_.Message]: - """One stored thread item -> messages, CLI tools as tool calls.""" + """One stored thread item -> messages, shaped like a live turn's. + + A tool item holds the call and its result: one assistant message with + both, as built-in parts. + """ kind = item.get("type") if kind == "userMessage": # A user item carries `content` blocks, its `UserInput`s. @@ -619,21 +623,18 @@ def _item_to_messages(item: dict[str, Any]) -> list[messages_.Message]: ) ] if kind in TOOL_ITEMS: - call = messages_.ToolCallPart( + call = messages_.BuiltinToolCallPart( tool_call_id=item.get("id", ""), tool_name=_tool_name(item), tool_args=json.dumps(_tool_args(item)), ) - result = messages_.ToolResultPart( - tool_call_id=item.get("id", ""), + result = messages_.BuiltinToolReturnPart( + tool_call_id=call.tool_call_id, tool_name=call.tool_name, result=_item_result(item), - result_kind="error" if item.get("status") == "failed" else "json", + is_error=item.get("status") == "failed", ) - return [ - messages_.Message(role="assistant", parts=[call]), - messages_.Message(role="tool", parts=[result]), - ] + return [messages_.Message(role="assistant", parts=[call, result])] return [] diff --git a/src/ai/workers/codex/handoff.py b/src/ai/workers/codex/handoff.py index ea637d78..796f9937 100644 --- a/src/ai/workers/codex/handoff.py +++ b/src/ai/workers/codex/handoff.py @@ -14,10 +14,14 @@ NOTE_PREFIX = "[Handoff from a previous session — earlier reasoning: " -def _note(reasoning: list[str]) -> str: - return ( - NOTE_PREFIX + " ".join(r.strip() for r in reasoning if r.strip()) + "]" - ) +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: @@ -26,9 +30,17 @@ def _image_url(part: messages_.FilePart) -> str: def to_codex_items(messages: list[messages_.Message]) -> list[dict[str, Any]]: - """Responses API items for `thread/inject_items`.""" + """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 _handoff.harness_view(messages): + for m in messages: reasoning: list[str] = [] for p in m.parts: if isinstance(p, messages_.TextPart) and p.text.strip(): @@ -54,7 +66,9 @@ def to_codex_items(messages: list[messages_.Message]) -> list[dict[str, Any]]: ], } ) - elif isinstance(p, messages_.ToolCallPart): + elif isinstance( + p, messages_.ToolCallPart | messages_.BuiltinToolCallPart + ): items.append( { "type": "function_call", @@ -63,7 +77,12 @@ def to_codex_items(messages: list[messages_.Message]) -> list[dict[str, Any]]: "arguments": p.tool_args or "{}", } ) - elif isinstance(p, messages_.ToolResultPart): + elif isinstance( + p, messages_.ToolResultPart | messages_.BuiltinToolReturnPart + ): + if reasoning: + items.append(_note(reasoning)) + reasoning = [] items.append( { "type": "function_call_output", @@ -74,13 +93,5 @@ def to_codex_items(messages: list[messages_.Message]) -> list[dict[str, Any]]: elif isinstance(p, messages_.ReasoningPart) and p.text.strip(): reasoning.append(p.text) if reasoning: - items.append( - { - "type": "message", - "role": "user", - "content": [ - {"type": "input_text", "text": _note(reasoning)} - ], - } - ) + items.append(_note(reasoning)) return items diff --git a/src/ai/workers/pi/adapter.py b/src/ai/workers/pi/adapter.py index bd44d73e..96d6d53d 100644 --- a/src/ai/workers/pi/adapter.py +++ b/src/ai/workers/pi/adapter.py @@ -559,10 +559,7 @@ async def history(self, session_id: str) -> list[messages_.Message]: """ found = await self._find(session_id) text = await asyncio.to_thread(pathlib.Path(found["path"]).read_text) - stored: list[messages_.Message] = [] - for record in _active_branch(text): - stored.extend(_stored_to_messages(record)) - return _handoff.model_view(stored) + return _read(_active_branch(text)) async def list_sessions(self) -> list[_adapter.SessionInfo]: return [ @@ -962,7 +959,14 @@ def _assistant_parts(content: Any) -> list[messages_.Part]: elif kind == "thinking" and block.get("thinking"): parts.append(messages_.ReasoningPart(text=block["thinking"])) elif kind == "toolCall": - parts.append(_tool_call(block)) + 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 @@ -1030,8 +1034,44 @@ def _active_branch(text: str) -> list[dict[str, Any]]: 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, CLI tools as tool calls. + """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 @@ -1078,14 +1118,6 @@ def _stored_to_messages(entry: dict[str, Any]) -> list[messages_.Message]: provider_metadata=_written_by(message), ) ] - if role == "toolResult": - result = messages_.ToolResultPart( - tool_call_id=str(message.get("toolCallId") or ""), - tool_name=str(message.get("toolName") or ""), - result=_tool_result(message), - result_kind="error" if message.get("isError") else "json", - ) - return [messages_.Message(role="tool", parts=[result])] return [] diff --git a/src/ai/workers/pi/handoff.py b/src/ai/workers/pi/handoff.py index 5f4d20c6..65b94e39 100644 --- a/src/ai/workers/pi/handoff.py +++ b/src/ai/workers/pi/handoff.py @@ -45,66 +45,24 @@ def to_pi_messages( "total": 0, }, } - for m in _handoff.harness_view(messages): - if m.role == "tool": - for p in m.parts: - if isinstance(p, messages_.ToolResultPart): - out.append( - { - "role": "toolResult", - "toolCallId": p.tool_call_id, - "toolName": p.tool_name, - "content": [ - { - "type": "text", - "text": _handoff.result_text(p.result), - } - ], - "isError": p.result_kind == "error", - "timestamp": timestamp, - } - ) - continue - blocks: list[dict[str, Any]] = [] - for p in m.parts: - if isinstance(p, messages_.TextPart) and p.text.strip(): - blocks.append({"type": "text", "text": p.text}) - elif ( - isinstance(p, messages_.FilePart) - and m.role == "user" - and p.media_type.startswith("image/") - ): - if isinstance(p.data, str) and media.is_downloadable_url( - p.data - ): - blocks.append( - {"type": "text", "text": f"[image: {p.data}]"} - ) - else: - blocks.append( - { - "type": "image", - "data": media.data_to_base64(p.data), - "mimeType": p.media_type, - } - ) - elif ( - isinstance(p, messages_.ToolCallPart) and m.role == "assistant" - ): - try: - args = json.loads(p.tool_args) if p.tool_args else {} - except json.JSONDecodeError: - args = {"raw": p.tool_args} - blocks.append( - { - "type": "toolCall", - "id": p.tool_call_id or p.id, - "name": p.tool_name, - "arguments": args if isinstance(args, dict) else {}, - } - ) + + 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: - continue + 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 @@ -116,7 +74,7 @@ def to_pi_messages( out.append( {"role": "user", "content": blocks, "timestamp": timestamp} ) - continue + return if out and out[-1]["role"] == "assistant": out[-1]["content"] += blocks else: @@ -145,4 +103,65 @@ def to_pi_messages( ) 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/tests/workers/claude_code/test_adapter.py b/tests/workers/claude_code/test_adapter.py index a8d4d801..85788f51 100644 --- a/tests/workers/claude_code/test_adapter.py +++ b/tests/workers/claude_code/test_adapter.py @@ -247,7 +247,8 @@ async def test_a_seed_is_written_where_the_cli_reads(tmp_path: Path) -> None: assert records[2]["message"]["content"][0]["type"] == "tool_result" -def test_a_stored_transcript_reads_as_the_model_view() -> None: +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", @@ -286,10 +287,7 @@ def test_a_stored_transcript_reads_as_the_model_view() -> None: parent_tool_use_id=None, ), ] - from ai.workers import _handoff - - stored = [msg for r in records for msg in adapter_._stored_to_messages(r)] - history = _handoff.model_view(stored) + history = adapter_._read(records) assert [x.role for x in history] == ["user", "assistant"] call, result = history[1].parts assert isinstance(call, m.BuiltinToolCallPart) diff --git a/tests/workers/codex/test_adapter.py b/tests/workers/codex/test_adapter.py index 16e82303..8f06b630 100644 --- a/tests/workers/codex/test_adapter.py +++ b/tests/workers/codex/test_adapter.py @@ -323,7 +323,7 @@ async def test_a_thread_from_another_directory_is_refused() -> None: ) -async def test_history_is_the_model_view() -> None: +async def test_history_has_the_cli_tools_as_builtin_parts() -> None: server = AppServer() server.threads[THREAD]["turns"] = [ { diff --git a/tests/workers/pi/test_adapter.py b/tests/workers/pi/test_adapter.py index a3ce5e9d..191c013f 100644 --- a/tests/workers/pi/test_adapter.py +++ b/tests/workers/pi/test_adapter.py @@ -421,15 +421,12 @@ def test_history_follows_the_active_branch_only() -> None: {"type": "label", "id": "e", "parentId": "d"}, ] text = "\n".join(json.dumps(line) for line in lines) - stored = [ - msg - for entry in adapter_._active_branch(text) - for msg in adapter_._stored_to_messages(entry) - ] - assert [msg.role for msg in stored] == ["user", "assistant", "tool"] - result = stored[2].parts[0] - assert isinstance(result, m.ToolResultPart) - assert (result.result, result.result_kind) == ("hi", "error") + stored = adapter_._read(adapter_._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: diff --git a/tests/workers/test_handoff.py b/tests/workers/test_handoff.py index 7dcdf1fd..8746525d 100644 --- a/tests/workers/test_handoff.py +++ b/tests/workers/test_handoff.py @@ -3,7 +3,9 @@ Text verbatim; tool calls as native items with the ORIGINAL name and arguments; tool results as strings bound to their call; reasoning as a user-role note after the turn it belonged to (codex), or not at all -(claude, pi). The CLI's own tools arrive as built-in parts. +(claude, pi). A worker holds a tool an `ai.Agent` ran as a call and a +`tool` message, and a tool the CLI ran as built-in parts in one message: +each renderer takes both, and both seed the same. """ from __future__ import annotations @@ -24,7 +26,8 @@ from ai.workers.codex import handoff as codex_handoff from ai.workers.pi import handoff as pi_handoff -HISTORY = [ +# Write as a tool an `ai.Agent` ran: its result in a `tool` message. +AGENT_TOOL = [ Message(role="user", parts=[TextPart(text="Create recipe.txt")]), Message( role="assistant", @@ -54,9 +57,9 @@ Message(role="assistant", parts=[TextPart(text="Done.")]), ] -# The same conversation, the way a worker holds it. -MODEL_VIEW = [ - HISTORY[0], +# The same conversation, Write as a tool the CLI ran: built-in parts. +CLI_TOOL = [ + AGENT_TOOL[0], Message( role="assistant", parts=[ @@ -74,12 +77,12 @@ ), ], ), - HISTORY[3], + AGENT_TOOL[3], ] def test_codex_items_follow_the_rule() -> None: - items = codex_handoff.to_codex_items(HISTORY) + items = codex_handoff.to_codex_items(AGENT_TOOL) kinds = [(i["type"], i.get("role")) for i in items] assert kinds == [ ("message", "user"), @@ -101,14 +104,24 @@ def test_codex_items_follow_the_rule() -> None: assert "Write is the tool" in note -def test_the_model_view_seeds_the_same_items() -> None: - assert codex_handoff.to_codex_items( - MODEL_VIEW - ) == codex_handoff.to_codex_items(HISTORY) +def test_both_shapes_seed_the_same() -> None: + assert codex_handoff.to_codex_items(CLI_TOOL) == ( + codex_handoff.to_codex_items(AGENT_TOOL) + ) + assert pi_handoff.to_pi_messages(CLI_TOOL, timestamp=1) == ( + pi_handoff.to_pi_messages(AGENT_TOOL, timestamp=1) + ) + assert [ + (r["type"], r["message"]) + for r in claude_handoff.to_claude_records(CLI_TOOL, "s", "/w") + ] == [ + (r["type"], r["message"]) + for r in claude_handoff.to_claude_records(AGENT_TOOL, "s", "/w") + ] def test_claude_records_follow_the_rule() -> None: - recs = claude_handoff.to_claude_records(MODEL_VIEW, "sid-1", "/w") + recs = claude_handoff.to_claude_records(CLI_TOOL, "sid-1", "/w") # user prompt, assistant (text + tool_use), tool result, assistant; NO # reasoning note: Claude's safeguards refuse replayed reasoning. assert [r["type"] for r in recs] == [ @@ -125,7 +138,7 @@ def test_claude_records_follow_the_rule() -> None: result = recs[2]["message"]["content"][0] assert result["type"] == "tool_result" assert result["tool_use_id"] == "call_1" - assert _handoff.reasoning_count(MODEL_VIEW) == 1 # what is warned about + assert _handoff.reasoning_count(CLI_TOOL) == 1 # what is warned about # a real chain, in the CLI's own store shape assert recs[0]["parentUuid"] is None assert all( @@ -164,19 +177,9 @@ def test_pi_merges_assistant_messages_and_keeps_tool_results() -> None: assert rendered[2]["isError"] is True -def test_model_view_and_harness_view_are_inverse() -> None: - model = _handoff.model_view(HISTORY) - assert [m.role for m in model] == ["user", "assistant", "assistant"] - parts = model[1].parts - assert isinstance(parts[2], BuiltinToolCallPart) - assert isinstance(parts[3], BuiltinToolReturnPart) - assert parts[3].result == {"ok": True} - back = _handoff.harness_view(model) - assert [m.role for m in back] == ["user", "assistant", "tool", "assistant"] - assert isinstance(back[2].parts[0], ToolResultPart) - - def test_text_after_a_cli_tool_stays_after_its_result() -> None: + """Claude and pi keep a result in a message of its own: the message + with the call ends there, and what follows comes after the result.""" one = Message( role="assistant", parts=[ @@ -187,43 +190,35 @@ def test_text_after_a_cli_tool_stays_after_its_result() -> None: TextPart(text="It says x."), ], ) - first, result, after = _handoff.harness_view([one]) - assert (first.role, result.role, after.role) == ( + recs = claude_handoff.to_claude_records([one], "s", "/w") + assert [r["type"] for r in recs] == ["assistant", "user", "assistant"] + assert recs[1]["message"]["content"][0]["type"] == "tool_result" + assert recs[2]["message"]["content"] == [ + {"type": "text", "text": "It says x."} + ] + rendered = pi_handoff.to_pi_messages([one], timestamp=1) + assert [r["role"] for r in rendered] == [ "assistant", - "tool", + "toolResult", "assistant", - ) - assert first.id == one.id and after.id != one.id - assert after.text == "It says x." - - -def test_a_stored_result_without_a_name_takes_its_calls() -> None: - stored = [ - Message( - role="assistant", - parts=[ - ToolCallPart(tool_call_id="c", tool_name="Read", tool_args="") - ], - ), - Message( - role="tool", - parts=[ToolResultPart(tool_call_id="c", tool_name="", result="x")], - ), ] - (message,) = _handoff.model_view(stored) - result = message.parts[1] - assert isinstance(result, BuiltinToolReturnPart) - assert result.tool_name == "Read" + assert rendered[2]["content"] == [{"type": "text", "text": "It says x."}] + items = codex_handoff.to_codex_items([one]) + assert [i["type"] for i in items] == [ + "function_call", + "function_call_output", + "message", + ] def test_reasoning_is_never_the_agents_own_thought() -> None: """No thinking block, no reasoning item: both were measured to fail, one rejected, one silently ignored. It travels as a note, or not at all.""" - items = codex_handoff.to_codex_items(HISTORY) + items = codex_handoff.to_codex_items(AGENT_TOOL) assert not any(i["type"] == "reasoning" for i in items) blocks = [ b - for r in claude_handoff.to_claude_records(HISTORY, "s", "/w") + for r in claude_handoff.to_claude_records(AGENT_TOOL, "s", "/w") if isinstance(r["message"]["content"], list) for b in r["message"]["content"] ] From 182feb1ef4f7a87e9a3cd230be0651a0df61f736 Mon Sep 17 00:00:00 2001 From: Andrey Buzin Date: Mon, 9 Nov 2026 09:16:52 -0800 Subject: [PATCH 6/6] Rework ai.workers into one object per CLI session --- WORKERS.md | 143 +++ examples/workers/approvals.py | 7 +- src/ai/agents/agent.py | 4 +- src/ai/agents/hooks.py | 12 +- src/ai/workers/__init__.py | 51 +- src/ai/workers/_adapter.py | 85 +- src/ai/workers/_errors.py | 4 + src/ai/workers/_handoff.py | 4 +- src/ai/workers/_worker.py | 1132 ++++++++++-------- src/ai/workers/claude_code/adapter.py | 656 ----------- src/ai/workers/claude_code/worker.py | 762 +++++++++++- src/ai/workers/codex/adapter.py | 696 ----------- src/ai/workers/codex/worker.py | 732 +++++++++++- src/ai/workers/pi/adapter.py | 1231 -------------------- src/ai/workers/pi/worker.py | 1294 ++++++++++++++++++++- tests/agents/test_hooks.py | 82 ++ tests/workers/claude_code/test_adapter.py | 745 +++++++++++- tests/workers/codex/test_adapter.py | 416 ++++++- tests/workers/fakes.py | 133 ++- tests/workers/pi/test_adapter.py | 416 ++++++- tests/workers/test_live.py | 113 +- tests/workers/test_output.py | 233 ++++ tests/workers/test_session_sync.py | 49 + tests/workers/test_worker.py | 770 +++++++++++- 24 files changed, 6307 insertions(+), 3463 deletions(-) create mode 100644 WORKERS.md delete mode 100644 src/ai/workers/claude_code/adapter.py delete mode 100644 src/ai/workers/codex/adapter.py delete mode 100644 src/ai/workers/pi/adapter.py create mode 100644 tests/workers/test_output.py create mode 100644 tests/workers/test_session_sync.py diff --git a/WORKERS.md b/WORKERS.md new file mode 100644 index 00000000..15c93d0b --- /dev/null +++ b/WORKERS.md @@ -0,0 +1,143 @@ +# Workers: one object, one CLI session + +`ai.workers` is experimental. `ClaudeCode`, `Codex`, and `Pi` share one session +API. They also work with `ai.stream`, `ai.experimental_generate`, and +`ai.Agent.run`. The CLI store owns the transcript; `worker.messages` is its +Python mirror. + +## Direct control + +```python +import contextlib + +import ai +from ai import workers + +async def main(): + async with workers.ClaudeCode(model_name="sonnet", approve=True) as worker: + await worker.send("Inspect this directory and summarize it.") + async with contextlib.aclosing(worker.events()) as feed: + async for event in feed: + if isinstance(event, ai.events.PendingHookEvent): + ai.resolve_hook( + event.hook, + {"granted": False, "reason": "No tool access today."}, + registry=worker.hook_registry, + ) + elif isinstance(event, ai.events.TextDelta): + print(event.chunk, end="") + elif isinstance(event, ai.events.StreamEnd): + break +``` + +- `open()` starts the transport once. Session creation is lazy until input. + The context manager and input/output methods call `open()` automatically. +- `send()` takes a string or a list of `TextPart | FilePart`. It waits for + transport acceptance, not an answer. During a turn, it sends guidance. +- `events()` is one feed across turns. Only one reader is permitted. A second + reader, including an overlapping model stream, raises `WorkerError`. +- `interrupt()` requests a clean turn end. Keep reading to receive the end event. +- `close()` stops the CLI and unblocks the reader. The saved fields remain. + Use `contextlib.aclosing` if you leave a reader early; it stops active work. + +The feed type is `workers.SessionEvent`: + +| Event | Meaning | +| --- | --- | +| `StreamStart`, `StreamEnd` | Assistant response boundaries | +| `UserMessageAccepted` | Transport accepted input; reading this event updates the mirror | +| `Text*`, `Reasoning*`, `BuiltinTool*` | Output and CLI-owned tool activity | +| `HookEvent` | An approval is pending, resolved, or cancelled | + +Direct approvals work without Agent. Pass `registry=worker.hook_registry` to +`ai.resolve_hook`. Inside Agent, its current registry is used, including when +the CLI transport was opened before the run. Approval coverage depends on the +native policy; `approve=True` is not a sandbox. Bare model streaming outside +Agent cannot deliver hook events: use the direct feed or Agent for approvals. + +## Model use + +```python +async def model_use(): + async with workers.Codex() as worker: + answer = await ai.experimental_generate( + worker, [ai.user_message("Explain the tests.")] + ) + follow_up = await ai.experimental_generate( + worker, [*worker.messages, ai.user_message("Give a short summary.")] + ) + return answer, follow_up +``` + +`stream()` sends only new input, then reads `events()` through one assistant +message. To add Python tools, use `ai.Agent(tools=[...]).run(worker, messages)`. +The MCP bridge passes these calls to Agent. CLI tools remain built-in events +and are not executed again by Agent. Direct `send()` does not take Python tools. + +The request must preserve the known history. Changed ids, roles, or parts raise +`TranscriptMismatchError`; a mismatch never silently creates a new session. +Structured output keeps native parts in the mirror and saves the model-facing +parts in message metadata. Validation retries also remain in native history, +but are hidden from the model-facing view. Both complete views can continue the +session, including after dump/validate. After `sync()`, use the new native mirror. + +Read pending direct events before switching to model use. Alternatively, once +the turn is idle, `sync()` replaces the mirror and discards superseded events. + +## State, fork, and TUI + +- `model_dump()` / `Worker.model_validate()` save and restore settings, + `session_id`, and `messages`. They do not save processes or pending hooks. +- `sync()` reads authoritative native history. It requires a session id and + no active turn or reader. Store normalization can change message ids/parts. +- `fork()` creates an already-open native branch with a different session id + and loaded history. It requires an idle session with no reader. Close the + returned worker, or manage it with `async with`. +- `model_copy()` resets private transport state but retains the session id. + It is **not a fork**. Do not use two copies as concurrent writers. +- `tui_command()` returns `(argv, env)`. Close the worker before running that + command in `worker.cwd`; call `sync()` when the person finishes. `tui()` + handles those steps. `ConcreteWorker.list_sessions(cwd=...)` lists sessions. +- Unsupported operations raise `UnsupportedError`. There is no capabilities + object or adapter instance. Concrete workers own private CLI state and + `_cli_*` methods; common `send()` / `events()` logic stays in the base. + +## Migration + +| Old API | New API | +| --- | --- | +| `kind` | `worker_class_id` | +| `model` | `model_name` | +| `fork=True` | `await worker.fork()` | +| `load()` | `await worker.sync()` | +| `steer()` | `await worker.send(prompt)` | + +Old field names have no aliases. Rename saved keys and remove the old fork flag +before validation. If it was true, explicitly create a native fork. +`executable` remains a string: a PATH command or filesystem path. + +A fresh worker can import history on its first model call. This is **lossy +seeding**, not a native fork. Unsupported reasoning/files are omitted or rendered +as notes with warnings. Native ids and arbitrary metadata are not guaranteed. + +## CLI limits and verification + +Acceptance is transport-level. Claude confirms an SDK input write; Codex confirms +a start/steer RPC; Pi confirms a prompt that can be queued or extension-handled. +This does not prove native storage or expose universal input-to-turn correlation. +Only `sync()` reconciles the mirror with the CLI store. Claude's response counting +assumes one terminal result per accepted query; native coalescing and background +responses need live verification. Pi has no public follow-up selector. + +Offline verification includes workers, Agent hooks, and model integration: + +```sh +uv run --frozen pytest -q tests/workers tests/agents tests/models --timeout=15 --tb=short +uv run --frozen ruff format --check src tests examples +uv run --frozen ruff check src tests examples +uv run --frozen mypy +uv run --frozen ty check +``` + +Live tests were updated but not run. They use real CLI logins and paid model +calls. Historical `VERIFIED_VERSION` comments do not verify this rework. diff --git a/examples/workers/approvals.py b/examples/workers/approvals.py index 16e4fc47..044d70f4 100644 --- a/examples/workers/approvals.py +++ b/examples/workers/approvals.py @@ -1,7 +1,8 @@ -"""Approve each of the CLI's own tool calls, as `ai.Agent` tool approvals. +"""Answer CLI approval requests through `ai.Agent` tool approvals. -With `approve=True`, every tool call the CLI makes becomes a `ToolApproval` -hook. Answer it with `ai.resolve_hook`, the way any tool approval is. +With `approve=True`, native approval requests become `ToolApproval` hooks. +Coverage depends on the CLI's policy; this is not a sandbox. Answer each +request with `ai.resolve_hook`, the way any tool approval is. uv run python examples/workers/approvals.py [claude-code|codex|pi] """ diff --git a/src/ai/agents/agent.py b/src/ai/agents/agent.py index 0b5933bb..3e89a06b 100644 --- a/src/ai/agents/agent.py +++ b/src/ai/agents/agent.py @@ -1041,12 +1041,12 @@ async def _iterate(self) -> AsyncGenerator[events_.ToolCallResult]: def _validate_model(value: Any) -> models.ModelLike: # Another model-like (an ai.workers.Worker) is kept as it is. A dict - # from JSON with a worker's `kind` is a worker; any other is an ai.Model. + # JSON with `worker_class_id` is a worker; any other dict is an ai.Model. if isinstance(value, models.ModelLike) and not isinstance( value, models.Model ): return value - if isinstance(value, dict) and "kind" in value: + if isinstance(value, dict) and "worker_class_id" in value: from .. import workers # noqa: PLC0415 return workers.Worker.model_validate(value) diff --git a/src/ai/agents/hooks.py b/src/ai/agents/hooks.py index 049ac0ae..ec990abe 100644 --- a/src/ai/agents/hooks.py +++ b/src/ai/agents/hooks.py @@ -40,7 +40,7 @@ class HookRegistry: """Holds hook state: live suspensions and pre-registered resolutions. ``_live_hooks``: - Populated by ``hook()`` when it suspends inside a running agent. + Populated by ``hook()`` when it suspends. Maps hook label -> (future, metadata dict, Runtime). Consumed by ``resolve_hook()`` / ``cancel_hook()`` to unblock the awaiting coroutine. Each entry is removed by the suspended hook @@ -154,9 +154,15 @@ async def hook[T: pydantic.BaseModel]( metadata: dict[str, Any] | None = None, tool_call_id: str | None = None, registry: HookRegistry | None = None, + runtime: runtime_.Runtime | None = None, ) -> T: """Create a hook suspension point and await its resolution. + Outside an Agent run, pass an explicit ``registry`` and ``runtime``. + The runtime emits hook events; a Runtime subclass can override + ``put_event()`` to forward them to its own queue. Resolve or cancel + the hook using the same registry. + Args: hook: Unique identifier for this hook instance, or a HookPart whose ``hook_id`` supplies it. @@ -172,9 +178,11 @@ async def hook[T: pydantic.BaseModel]( custom gating wrappers should pass it too. registry: The :class:`HookRegistry` to register the hook in. Defaults to the current registry. + runtime: The Runtime that emits pending, resolved, and cancelled + hook events. Defaults to the current runtime. """ - rt = runtime_.get_runtime() + rt = runtime if runtime is not None else runtime_.get_runtime() registry = _registry(registry) label = _label(hook) hook_metadata = dict(metadata or {}) diff --git a/src/ai/workers/__init__.py b/src/ai/workers/__init__.py index 4ad6b7bc..be01ec18 100644 --- a/src/ai/workers/__init__.py +++ b/src/ai/workers/__init__.py @@ -1,27 +1,50 @@ -"""Coding-agent CLIs as workers: Claude Code, Codex and Pi. +"""Coding-agent CLI sessions: Claude Code, Codex and Pi. Experimental: not part of the stable API, may change or be removed. -A worker goes where a model goes, and it keeps its conversation:: +Use a worker as a model, continuing from its current message mirror:: import ai from ai import workers - async with workers.ClaudeCode(model="sonnet") as worker: + async with workers.ClaudeCode(model_name="sonnet") as worker: async with ai.stream(worker, [ai.user_message("Fix the tests")]) as s: async for event in s: ... + reply = await ai.experimental_generate( + worker, [*worker.messages, ai.user_message("Summarize the fix.")] + ) - # an ai.Agent's tools reach the CLI through MCP - async with ai.Agent(tools=[search_docs]).run(worker, messages) as run: - ... +Or use ``await worker.send(prompt)`` and ``worker.events()`` directly. +``SessionEvent`` includes model events (``StreamStart``/``StreamEnd``), +``UserMessageAccepted`` and ``HookEvent``. The feed spans turns until close; +there is exactly one reader, including ``stream()`` or ``ai.Agent.run()``. +Explicitly close a reader when leaving it early (``contextlib.aclosing``). -The CLI's own tools come back as `ai.events.BuiltinTool*` events. +With ``approve=True``, direct consumers answer ``PendingHookEvent`` outside +Agent using ``ai.resolve_hook(event.hook, {"granted": False}, +registry=worker.hook_registry)``. Bare model streaming cannot deliver these +approvals: use the direct feed or Agent. Python tools run only through +``ai.Agent(tools=[...]).run(worker, messages)`` and reach the CLI via MCP; +CLI-owned tools appear as ``ai.events.BuiltinTool*`` events. -A worker is a pydantic model: `worker.model_dump()` saves the conversation, -`workers.Worker.model_validate(data)` continues it, `worker.model_copy()` is -a new worker on the same settings, and `ClaudeCode(session_id=...)` resumes -a conversation the CLI has stored. +``send()`` waits for transport acceptance, not an answer or durable storage. +The reader updates ``messages``; once the turn and reader stop, ``sync()`` +replaces that mirror from the authoritative CLI store (also after TUI use). +``interrupt()`` requests a clean turn end. ``await worker.fork()`` returns +an open native branch with a new session id; close it when done. Copying +preserves the same session id and is not a fork. + +Dump/validate with ``model_dump()`` / ``Worker.model_validate()`` to resume +settings and the mirror; native storage is still required. Migrate old +``kind``/``model`` keys to ``worker_class_id``/``model_name`` and remove the +old ``fork`` field; no legacy aliases exist. ``executable`` remains a string +(PATH command or filesystem path), or None for the CLI default. A mismatched +history raises ``TranscriptMismatchError`` instead of silently reseeding. +Importing history into a fresh worker is lossy, unlike a native fork. + +Concrete classes own private CLI transport hooks; adapter objects are gone. +See WORKERS.md for examples, migration details and protocol limitations. """ from ._adapter import SessionInfo @@ -29,9 +52,10 @@ ExecutableMissingError, NotAuthenticatedError, TranscriptMismatchError, + UnsupportedError, WorkerError, ) -from ._worker import Worker +from ._worker import SessionEvent, UserMessageAccepted, Worker from .claude_code import ClaudeCode from .codex import Codex from .pi import Pi @@ -42,8 +66,11 @@ "ExecutableMissingError", "NotAuthenticatedError", "Pi", + "SessionEvent", "SessionInfo", "TranscriptMismatchError", + "UnsupportedError", + "UserMessageAccepted", "Worker", "WorkerError", ] diff --git a/src/ai/workers/_adapter.py b/src/ai/workers/_adapter.py index ef5dce7d..b0a6b153 100644 --- a/src/ai/workers/_adapter.py +++ b/src/ai/workers/_adapter.py @@ -1,15 +1,4 @@ -"""The adapter protocol: what `Worker` needs from each CLI. - -An adapter drives ONE conversation with one CLI. Outside it, the CLI's own -tools are built-in tools, and nothing else: `turn()` yields them as -`BuiltinTool*` events, and a history it reads holds them as built-in parts, -each result in the assistant message of its call. A seed holds them the -same way, next to the calls and `tool` messages of the tools an `ai.Agent` -ran. How the CLI stores a tool call is the adapter's business alone. - -`turn()` yields the events of one assistant message and ends with a -`StreamEnd`. -""" +"""Shared CLI data and executable probing; no adapter objects.""" from __future__ import annotations @@ -17,88 +6,28 @@ import os import re import warnings -from collections.abc import AsyncIterator, Awaitable, Callable, Mapping -from typing import Any, Protocol +from collections.abc import Awaitable, Callable, Mapping +from typing import Any import pydantic -from ..types import events from ..types import messages as messages_ from . import _errors as errors Prompt = list[messages_.TextPart | messages_.FilePart] - -# `approve(tool_call_id, tool_name, tool_input)` returns `(granted, reason)`. -# -# Never raises: the worker answers a failure with a denial. Approve = Callable[[str, str, dict[str, Any]], Awaitable[tuple[bool, str]]] class SessionInfo(pydantic.BaseModel): - """A conversation in a CLI's own store.""" + """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 - """Milliseconds since the epoch, when the CLI records it.""" updated_at: int | None = None -class CLIAdapter(Protocol): - version: str | None - """What ` --version` printed, once started.""" - - async def start(self) -> None: - """Check the CLI runs, and start what it needs (codex: a server).""" - ... - - async def close(self) -> None: ... - - async def open( - self, - *, - session_id: str | None, - fork: bool, - seed: list[messages_.Message] | None, - instructions: str | None, - ) -> str: - """Open the conversation and return its session id. - - A new one (seeded with a past when `seed` is given), the stored one - `session_id` names, or a native fork of it. - """ - ... - - def turn(self, prompt: Prompt) -> AsyncIterator[events.Event]: - """Send a prompt; yield one assistant message, ending in StreamEnd.""" - ... - - async def steer(self, text: str) -> None: - """Send guidance to the turn that runs now.""" - ... - - async def interrupt(self) -> None: - """End the running turn. The CLI keeps its transcript.""" - ... - - async def history(self, session_id: str) -> list[messages_.Message]: - """Read a stored conversation.""" - ... - - async def list_sessions(self) -> list[SessionInfo]: ... - - def tui_command( - self, session_id: str | None - ) -> tuple[list[str], dict[str, str], str | None]: - """Return the CLI's interactive command, its env, and its session id. - - The session id is minted here for a new conversation when the CLI - lets us choose it, else None. - """ - ... - - async def probe( kind: str, executable: str, @@ -108,11 +37,7 @@ async def probe( cwd: str, env: Mapping[str, str], ) -> str: - """Check that the CLI runs, and return its version. - - Warns when it is older than the version the adapter was verified with: - the adapters lean on CLI behavior that is measured, not documented. - """ + """Check the CLI and warn if its version is older than tested.""" try: proc = await asyncio.create_subprocess_exec( executable, diff --git a/src/ai/workers/_errors.py b/src/ai/workers/_errors.py index 21baddee..0b57650e 100644 --- a/src/ai/workers/_errors.py +++ b/src/ai/workers/_errors.py @@ -13,6 +13,10 @@ class WorkerError(errors.AIError): """A worker or its CLI failed.""" +class UnsupportedError(WorkerError): + """The CLI does not support the requested operation.""" + + class ExecutableMissingError(WorkerError): """The CLI is not installed, or `executable=` does not run.""" diff --git a/src/ai/workers/_handoff.py b/src/ai/workers/_handoff.py index e51f1bc6..36039d87 100644 --- a/src/ai/workers/_handoff.py +++ b/src/ai/workers/_handoff.py @@ -20,14 +20,14 @@ Claude does NOT accept it in any form: Anthropic's safeguards flag real model reasoning replayed as user content (`[reasoning_extraction]`) — hand-written notes passed, genuine Opus thinking was refused. So the - Claude renderer omits reasoning, and the adapter warns with the count, + 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 adapter + file) is left out and counted (`unsupported_files`), and the worker warns, like it does for reasoning into Claude. """ diff --git a/src/ai/workers/_worker.py b/src/ai/workers/_worker.py index e4f462b6..60cc22eb 100644 --- a/src/ai/workers/_worker.py +++ b/src/ai/workers/_worker.py @@ -1,32 +1,18 @@ -"""`ai.workers.Worker`: a coding-agent CLI that goes where a model goes. - -A worker is ONE conversation with one CLI: Claude Code, Codex or Pi. It is -a pydantic model: its fields are its settings, the CLI's `session_id` and -the conversation so far (`messages`). Dump it, store it, and validate it -again later; it continues the same conversation. - -It follows the model protocol: `stream(messages, tools=, output_type=)` -yields the events of one assistant message, so `ai.stream`, -`ai.experimental_generate` and `ai.Agent.run` take a worker where they take -a model. The CLI runs its own loop and its own tools; those come back as -`BuiltinTool*` events, so an `ai.Agent` does not run them again. The tools -of an `ai.Agent` reach the CLI through the MCP bridge (see `_bridge`) and -come back as normal tool calls, for the agent to run. - -A worker has state, a model does not. `stream()` still receives the whole -conversation on every call. The worker compares it with `messages` and -sends the CLI only what is new (see `_plan`). +"""One serializable CLI session, with direct control and the model protocol. + +The CLI owns the transcript. Input and output are separate: ``send`` accepts +input, and one reader consumes ``events`` across turns. ``stream`` uses those +same primitives to expose one assistant message to the model API. """ from __future__ import annotations import asyncio import contextlib -import contextvars import dataclasses import json import os -from collections.abc import AsyncGenerator, Sequence +from collections.abc import AsyncGenerator, AsyncIterator, Sequence from typing import Any, ClassVar, Literal, Self import pydantic @@ -38,28 +24,34 @@ from ..types import messages as messages_ from ..types import tools as tools_ from ..types import usage as usage_ -from . import _adapter, _bridge, _convert +from . import _adapter, _bridge from . import _errors as errors Effort = Literal["low", "medium", "high", "max"] - -# Seconds to wait for more bridge calls before handing a batch to the caller. A -# CLI that calls tools in parallel sends them close together. BATCH_WINDOW = 0.05 - -# How many times to ask again for output that does not validate. 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: - """A call from the CLI to an `ai` tool, through the bridge.""" - tool_call_id: str name: str arguments: dict[str, Any] @@ -72,212 +64,375 @@ class _Failed: @dataclasses.dataclass -class _Plan: - """What one `stream()` call must do, from the messages it was given.""" +class _Accepted: + messages: list[messages_.Message] + +@dataclasses.dataclass +class _Plan: seed: list[messages_.Message] = dataclasses.field(default_factory=list) instructions: str | None = None results: list[messages_.ToolResultPart] = dataclasses.field( default_factory=list ) system: list[str] = dataclasses.field(default_factory=list) - """System text that arrived after the conversation began.""" - prompt: list[messages_.TextPart | messages_.FilePart] = dataclasses.field( - default_factory=list - ) + prompt: _adapter.Prompt = dataclasses.field(default_factory=list) transcript: list[messages_.Message] = dataclasses.field( default_factory=list ) - """The transcript once this call succeeds, before its answer.""" + + +class _HookRuntime(runtime_.Runtime): + """Route hooks into the same session feed as CLI output.""" + + def __init__(self, queue: asyncio.Queue[Any]) -> None: + super().__init__() + self.queue = queue + + async def put_event(self, event: events_.AgentEvent) -> None: + self.queue.put_nowait(event) @dataclasses.dataclass class _Runtime: - """What lives only while a worker is open. Never copied, never dumped.""" - - adapter: _adapter.CLIAdapter bridge: _bridge.Bridge - lock: asyncio.Lock = dataclasses.field(default_factory=asyncio.Lock) + queue: asyncio.Queue[Any] = dataclasses.field(default_factory=asyncio.Queue) + send_lock: asyncio.Lock = dataclasses.field(default_factory=asyncio.Lock) in_session: bool = False - # The running turn: its pump task and the queue it fills. - queue: asyncio.Queue[Any] | None = None + closed: bool = False + reader: bool = False + stream_owner: asyncio.Task[Any] | None = None + model_ready: asyncio.Event = dataclasses.field( + default_factory=asyncio.Event + ) pump: asyncio.Task[None] | None = None - # Bridge calls handed to the caller, waiting for their results. pending: dict[str, _Call] = dataclasses.field(default_factory=dict) - # CLI tool ids that are bridge calls, hidden from the stream. hidden: set[str] = dataclasses.field(default_factory=set) - # The context of the latest `stream()` call: approvals ask in it. - context: contextvars.Context | None = None + submission: list[messages_.Message] | None = None + registry: hooks.HookRegistry = dataclasses.field( + default_factory=hooks.HookRegistry + ) + approvals: set[asyncio.Task[Any]] = dataclasses.field(default_factory=set) class Worker(pydantic.BaseModel): - """Base class of `ClaudeCode`, `Codex` and `Pi`. + """Base of ClaudeCode, Codex and Pi. One object represents one session. - `Worker.model_validate(data)` builds the kind that `data["kind"]` names. + Dump and validate to resume a session. Use ``await worker.fork()`` to + create an independent native session; copying is not a fork. """ - kind: str - model: str | None = None - """The CLI's model. None: the CLI's own default.""" + model_config = pydantic.ConfigDict(extra="forbid") + + worker_class_id: str + model_name: str | None = None # None selects the CLI default. cwd: str = pydantic.Field(default_factory=os.getcwd) - """Where the CLI runs and keeps its sessions.""" - env: dict[str, str] = {} - """Added to the CLI's environment: keys, base URLs, config dirs.""" - executable: str | None = None + env: dict[str, str] = pydantic.Field(default_factory=dict) + executable: str | None = None # A PATH command or a filesystem path. effort: Effort | None = None - mcp_servers: dict[str, dict[str, Any]] = {} - """MCP servers for the CLI. - - `{"name": {"command": ..., "args": [...]}}` or `{"name": {"url": ...}}`. - """ - approve: bool = False - """Ask before each of the CLI's own tool calls, through `ai.hook`. - - False: the CLI's own permission settings decide (`allowed_tools`, - Codex's `sandbox`). True: each call becomes a `ToolApproval` hook, which - `ai.resolve_hook` and UIs answer as they answer any tool approval. Needs - an `ai.Agent.run()`, where hooks live. - """ + mcp_servers: dict[str, dict[str, Any]] = pydantic.Field( + default_factory=dict + ) + approve: bool = False # ToolApproval hooks, also available outside Agent. session_id: str | None = None - """The CLI's own id for the conversation. Set it to resume one.""" - fork: bool = False - """With `session_id`: fork that conversation natively on first use.""" - messages: list[messages_.Message] = [] - """The conversation so far. Send it back with the next user message.""" + messages: list[messages_.Message] = pydantic.Field(default_factory=list) - _kinds: ClassVar[dict[str, type[Worker]]] = {} + _classes: ClassVar[dict[str, type[Worker]]] = {} _runtime: _Runtime | None = pydantic.PrivateAttr(default=None) + _cli_version: str | None = pydantic.PrivateAttr(default=None) + _open_lock: asyncio.Lock = pydantic.PrivateAttr( + default_factory=asyncio.Lock + ) @classmethod def __pydantic_init_subclass__(cls, **kwargs: Any) -> None: # noqa: PLW3201 super().__pydantic_init_subclass__(**kwargs) - kind = cls.model_fields["kind"].default - if isinstance(kind, str): - Worker._kinds[kind] = cls + name = cls.model_fields["worker_class_id"].default + if isinstance(name, str): + Worker._classes[name] = cls @pydantic.model_validator(mode="wrap") @classmethod - def _of_kind( + def _of_class( cls, data: Any, handler: pydantic.ValidatorFunctionWrapHandler ) -> Any: if cls is Worker and isinstance(data, dict): - kind = Worker._kinds.get(str(data.get("kind"))) - if kind is None: - raise ValueError(f"no worker of kind {data.get('kind')!r}") - return kind.model_validate(data) + worker_class = Worker._classes.get(str(data.get("worker_class_id"))) + if worker_class is None: + raise ValueError( + f"unknown worker class {data.get('worker_class_id')!r}" + ) + return worker_class.model_validate(data) return handler(data) def __copy__(self) -> Self: - # A copy is a new worker: it opens a CLI of its own. - copied = super().__copy__() - copied._runtime = None - return copied + # Revalidation resets ALL private transport state, not just the base. + return type(self).model_validate(self.model_dump()) def __deepcopy__(self, memo: dict[int, Any] | None = None) -> Self: - copied = super().__deepcopy__(memo) - copied._runtime = None - return copied + return self.__copy__() - # -- subclass point ------------------------------------------------------- + # Private transport operations. Concrete workers own their CLI processes. + async def _cli_start(self, mcp_servers: dict[str, dict[str, Any]]) -> None: + raise errors.UnsupportedError("this worker cannot start a CLI") + + async def _cli_close(self) -> None: + pass - def _make_adapter( + async def _cli_open( self, - mcp_servers: dict[str, dict[str, Any]], - approve: _adapter.Approve | None, - ) -> _adapter.CLIAdapter: - raise NotImplementedError + *, + session_id: str | None, + fork: bool, + seed: list[messages_.Message] | None, + instructions: str | None, + ) -> str: + raise errors.UnsupportedError("this worker cannot open a session") + + def _cli_turn( + self, prompt: _adapter.Prompt + ) -> AsyncIterator[events_.Event]: + raise errors.UnsupportedError("this worker cannot send input") + + async def _cli_send_running(self, prompt: _adapter.Prompt) -> bool: + raise errors.UnsupportedError("this worker cannot send during a turn") + + async def _cli_interrupt(self) -> None: + raise errors.UnsupportedError("this worker cannot interrupt") + + async def _cli_history(self, session_id: str) -> list[messages_.Message]: + raise errors.UnsupportedError("this worker cannot read history") - # -- ModelLike ------------------------------------------------------------ + async def _cli_list_sessions(self) -> list[_adapter.SessionInfo]: + raise errors.UnsupportedError("this worker cannot list sessions") + + def _cli_tui_command( + self, + session_id: str | None, + ) -> tuple[list[str], dict[str, str], str | None]: + raise errors.UnsupportedError("this worker has no TUI command") @property def id(self) -> str: - return self.model or "default" + return self.model_name or "default" @property def provider_name(self) -> str: - return self.kind + return self.worker_class_id - async def stream( - self, - messages: list[messages_.Message], - *, - tools: Sequence[tools_.Tool] | None = None, - output_type: type[pydantic.BaseModel] | None = None, - params: Any = None, - ) -> AsyncGenerator[events_.Event]: - """Answer `messages` with one assistant message. + @property + def version(self) -> str | None: + return self._cli_version - Use `ai.stream(worker, messages)`, as with a model. The message ends - in one of two ways: + @property + def hook_registry(self) -> hooks.HookRegistry: + """Pass to ``ai.resolve_hook(..., registry=worker.hook_registry)``.""" + return self._require_runtime().registry + + async def open(self) -> None: + """Start the CLI transport once. A session opens on first input.""" + async with self._open_lock: + if self._runtime is not None: + return + bridge = _bridge.Bridge(self._on_call) + await bridge.start() + rt = _Runtime(bridge=bridge) + self._runtime = rt + try: + await self._cli_start( + { + **self.mcp_servers, + _bridge.SERVER_NAME: { + "type": "http", + "url": bridge.url, + }, + } + ) + except BaseException: + self._runtime = None + try: + await self._cli_close() + finally: + await bridge.close() + raise - - `finish_reason="tool_call"`: the CLI called `ai` tools from - `tools=`. The message holds them as `ToolCallPart`s. Run them and - call again with the results; the CLI waits until then. - - Anything else: the CLI's turn is over. + async def close(self) -> None: + """Stop the CLI and unblock the reader. Keep serializable state.""" + async with self._open_lock: + rt = self._runtime + if rt is None: + return + await self._abandon() + rt.closed = True + rt.queue.put_nowait(None) + try: + await self._cli_close() + finally: + self._runtime = None + await rt.bridge.close() - `params` is ignored: the CLI chooses its own. - """ - rt = await self._open() - await rt.lock.acquire() - paused = False - try: - if self.approve: - try: - hooks.get_hook_registry() - runtime_.get_runtime() - except LookupError: - raise errors.WorkerError( - "approve=True asks through ai.hook, which needs a " - "run: use the worker in ai.Agent.run()" - ) from None - rt.context = contextvars.copy_context() - plan = self._plan(messages) - rt.bridge.set_tools( - [t for t in tools or () if t.kind == "function"] + async def __aenter__(self) -> Self: + await self.open() + return self + + async def __aexit__(self, *exc_info: object) -> None: + await self.close() + + def _require_runtime(self) -> _Runtime: + if self._runtime is None: + raise errors.WorkerError( + f"{self.worker_class_id} worker is not open" ) - if rt.pending: - if plan.results: - self._answer(plan.results) - else: - await self._abandon() - if plan.prompt: - if rt.in_session and plan.system: - text = "\n\n".join(plan.system) + "\n\n" - plan.prompt.insert(0, messages_.TextPart(text=text)) - if rt.queue is not None: - # Tool results came with a new user message. The CLI is - # still in its turn: the message is guidance for it. - await rt.adapter.steer(_convert.text_of(plan.prompt)) - else: - await self._ensure_session(plan) - self._start(plan.prompt, output_type) - if rt.queue is None: - raise ValueError( - "stream(): no new user message or tool result to send" - ) + return self._runtime - stamp = messages_.Message(role="assistant", parts=[]) - hydrator = events_.MessageHydrator() + async def _ensure_session(self, plan: _Plan | None = None) -> None: + rt = self._require_runtime() + if rt.in_session: + return + plan = plan or _Plan() + self.session_id = await self._cli_open( + session_id=self.session_id, + fork=False, + seed=plan.seed if self.session_id is None and plan.seed else None, + instructions=plan.instructions, + ) + rt.in_session = True - def out(event: events_.Event) -> events_.Event: - event = event.model_copy( - update={ - "message": messages_.Message( - id=stamp.id, role="assistant", parts=[] + async def send(self, prompt: str | _adapter.Prompt) -> None: + """Submit input and wait for transport acceptance, not the answer. + + While a turn runs this is guidance; when idle it starts a turn. + Read ``events`` to observe acceptance and update ``messages``. + """ + parts: _adapter.Prompt = ( + [messages_.TextPart(text=prompt)] + if isinstance(prompt, str) + else list(prompt) + ) + if not parts: + raise ValueError("send(): prompt must not be empty") + await self.open() + rt = self._require_runtime() + if ( + rt.stream_owner is not None + and rt.stream_owner is not asyncio.current_task() + ): + # Initial model input must open the session before another task + # can steer it. Otherwise both paths can create a native session. + await rt.model_ready.wait() + async with rt.send_lock: + accepted = rt.submission + rt.submission = None + if accepted is None: + accepted = [messages_.Message(role="user", parts=list(parts))] + await self._ensure_session() + if rt.pump is not None and not rt.pump.done(): + if await self._cli_send_running(parts): + rt.queue.put_nowait(_Accepted(accepted)) + return + # The CLI confirmed idle without writing. Let the old reader + # finish its terminal event before starting another turn. + await rt.pump + ready: asyncio.Future[None] = ( + asyncio.get_running_loop().create_future() + ) + + async def pump() -> None: + try: + async for event in self._cli_turn(parts): + if ( + isinstance(event, events_.StreamStart) + and not ready.done() + ): + rt.queue.put_nowait(_Accepted(accepted)) + ready.set_result(None) + rt.queue.put_nowait(event) + if not ready.done(): + raise errors.WorkerError( + "CLI ended before accepting input" ) - } - ) - hydrator.feed(event) - return event + except asyncio.CancelledError: + if not ready.done(): + ready.cancel() + raise + except BaseException as exc: + if not ready.done(): + ready.set_exception(exc) + else: + rt.queue.put_nowait(_Failed(exc)) + + rt.pump = asyncio.create_task(pump()) + try: + await ready + except asyncio.CancelledError: + await self._abandon() + raise - yield out(events_.StreamStart()) - # Text after the last CLI tool call: the answer, for output_type. - answer: list[str] = [] + async def events(self) -> AsyncGenerator[SessionEvent]: + """Read the session feed until close; exactly one reader is allowed. + + StreamStart/StreamEnd mark assistant messages. UserMessageAccepted + records input. HookEvent carries approvals. Closing/cancelling a + reader interrupts a running turn, except when Agent tools must run. + """ + await self.open() + rt = self._require_runtime() + if rt.reader or ( + rt.stream_owner is not None + and rt.stream_owner is not asyncio.current_task() + ): + raise errors.WorkerError( + "events(): this session already has a reader" + ) + rt.reader = True + hydrator: events_.MessageHydrator | None = None + + def out(event: events_.Event) -> events_.Event: + nonlocal hydrator + if hydrator is None: + hydrator = events_.MessageHydrator() + event = event.model_copy(update={"message": hydrator.message}) + hydrator.feed(event) + if all(m.id != hydrator.message.id for m in self.messages): + self.messages.append(hydrator.message) + return event + + try: while True: item = await rt.queue.get() + if item is None: + return if isinstance(item, _Failed): - self._end_turn() raise item.error + if isinstance(item, _Accepted): + known = {m.id for m in self.messages} + for message in item.messages: + if message.id not in known: + # Guidance belongs before the in-progress answer, + # not after the final answer in the model history. + if ( + hydrator is not None + and hydrator.message in self.messages + ): + self.messages.insert( + self.messages.index(hydrator.message), + message, + ) + else: + self.messages.append(message) + known.add(message.id) + if message.role == "user": + yield UserMessageAccepted(message=message) + continue + if isinstance(item, events_.HookEvent): + yield item + continue + if isinstance(item, events_.StreamStart): + hydrator = None + yield out(item) + continue + if hydrator is None: + yield out(events_.StreamStart()) if isinstance(item, _Call): calls = [item] with contextlib.suppress(TimeoutError): @@ -287,7 +442,6 @@ def out(event: events_.Event) -> events_.Event: if isinstance(more, _Call): calls.append(more) else: - # Not ours to handle here: put it back. rt.queue.put_nowait(more) break for call in calls: @@ -314,94 +468,336 @@ def out(event: events_.Event) -> events_.Event: tool_call_id=part.tool_call_id, tool_call=part ) ) - paused = True yield out( events_.StreamEnd( finish_reason="tool_call", provider_metadata=self._metadata(None), ) ) - break + hydrator = None + continue if isinstance(item, events_.StreamEnd): - self._end_turn() - usage = item.usage - if output_type is not None: - text, usage = await self._output( - "".join(answer), output_type, usage - ) - yield out(events_.TextStart(block_id="output")) - yield out( - events_.TextDelta(chunk=text, block_id="output") - ) - yield out(events_.TextEnd(block_id="output")) finish = item.finish_reason + rt.hidden.clear() yield out( - events_.StreamEnd( - finish_reason=( - "other" if finish == "cancelled" else finish - ), - usage=usage, - provider_metadata={ - **(item.provider_metadata or {}), - **self._metadata(finish), - }, + item.model_copy( + update={ + "finish_reason": "other" + if finish == "cancelled" + else finish, + "provider_metadata": { + **(item.provider_metadata or {}), + **self._metadata(finish), + }, + } ) ) - break + hydrator = None + continue for event in self._visible(item): + yield out(event) + finally: + rt.reader = False + if not rt.closed and not rt.pending: + await self._abandon() + + async def interrupt(self) -> None: + """Request a clean turn end. The current reader receives StreamEnd.""" + rt = self._runtime + if rt is None or rt.pump is None or rt.pump.done(): + return + for task in list(rt.approvals): + task.cancel() + self._answer([]) + await self._cli_interrupt() + + async def _abandon(self) -> None: + rt = self._runtime + if rt is None: + return + for task in list(rt.approvals): + task.cancel() + self._answer([]) + pump = rt.pump + if pump is not None and not pump.done(): + with contextlib.suppress(Exception): + await self._cli_interrupt() + pump.cancel() + with contextlib.suppress(asyncio.CancelledError): + await pump + rt.pump = None + # A cancelled reader must not hand its queued terminal event to the + # next model request. The partial mirror remains until sync(). + while not rt.queue.empty(): + item = rt.queue.get_nowait() + if isinstance(item, _Call) and not item.answer.done(): + item.answer.set_result(("cancelled by the caller", True)) + rt.hidden.clear() + + async def sync(self) -> None: + """Replace the mirror from the CLI store, for example after TUI use.""" + await self.open() + rt = self._require_runtime() + if rt.reader or (rt.pump is not None and not rt.pump.done()): + raise errors.WorkerError("sync(): stop the turn and reader first") + if self.session_id is None: + raise errors.WorkerError("sync(): no session_id to read") + self.messages = await self._cli_history(self.session_id) + # Native history supersedes output queued before synchronization. + await self._abandon() + + async def fork(self) -> Self: + """Create a native session with a new id. Never fork a running turn.""" + if self.session_id is None: + raise errors.WorkerError("fork(): no session_id to fork") + rt = self._runtime + if rt is not None and ( + rt.reader or (rt.pump is not None and not rt.pump.done()) + ): + raise errors.WorkerError("fork(): stop the turn and reader first") + branch = self.__copy__() + try: + await branch.open() + branch.session_id = await branch._cli_open( + session_id=self.session_id, + fork=True, + seed=None, + instructions=None, + ) + if branch.session_id == self.session_id: + raise errors.WorkerError( + "fork(): CLI did not create a new session id" + ) + branch._require_runtime().in_session = True + branch.messages = await branch._cli_history(branch.session_id) + return branch + except BaseException: + await branch.close() + raise + + def tui_command(self) -> tuple[list[str], dict[str, str]]: + """Return argv and env. Close this worker before starting the TUI.""" + argv, env, minted = self._cli_tui_command(self.session_id) + if self.session_id is None: + if minted is None: + raise errors.WorkerError( + "CLI chooses its session id: send input first" + ) + self.session_id = minted + return argv, env + + async def tui(self) -> int: + await self.close() + argv, env = self.tui_command() + proc = await asyncio.create_subprocess_exec( + *argv, cwd=self.cwd, env={**os.environ, **env} + ) + code = await proc.wait() + await self.sync() + return code + + @classmethod + async def list_sessions( + cls, cwd: str, **fields: Any + ) -> list[_adapter.SessionInfo]: + worker = cls(cwd=cwd, **fields) + async with worker: + return await worker._cli_list_sessions() + + async def stream( + self, + messages: list[messages_.Message], + *, + tools: Sequence[tools_.Tool] | None = None, + output_type: type[pydantic.BaseModel] | None = None, + params: Any = None, + ) -> AsyncGenerator[events_.Event]: + """Send only new input and read one assistant message via events().""" + await self.open() + rt = self._require_runtime() + if rt.reader or rt.stream_owner is not None: + raise errors.WorkerError( + "stream(): this session already has a reader" + ) + if not rt.queue.empty() and not rt.pending: + raise errors.WorkerError( + "stream(): unread session events; " + "consume events() or sync() first" + ) + rt.stream_owner = asyncio.current_task() + rt.model_ready.clear() + # Transport reader tasks can predate Agent.run(). Use the current + # consumer's registry, not the callback task's inherited context. + with contextlib.suppress(LookupError): + rt.registry = hooks.get_hook_registry() + try: + plan = self._plan(messages) + rt.bridge.set_tools( + [t for t in tools or () if t.kind == "function"] + ) + if rt.pending: + self._answer(plan.results) + for message in plan.transcript: + if all(m.id != message.id for m in self.messages): + self.messages.append(message) + if plan.prompt: + if rt.in_session and plan.system: + plan.prompt.insert( + 0, + messages_.TextPart( + text="\n\n".join(plan.system) + "\n\n" + ), + ) + await self._ensure_session(plan) + rt.submission = plan.transcript + prompt = list(plan.prompt) + if output_type is not None: + prompt.append( + messages_.TextPart( + text=OUTPUT_INSTRUCTION + + json.dumps(TypeAdapter(output_type).json_schema()) + ) + ) + await self.send(prompt) + elif not plan.results: + raise ValueError( + "stream(): no new user message or tool result to send" + ) + rt.model_ready.set() + + answer: list[str] = [] + # events() owns the native mirror; model output must hydrate a + # separate message, retaining the native id even across retries. + projection = events_.MessageHydrator() + async with contextlib.aclosing(self.events()) as feed: + async for event in feed: + if isinstance(event, UserMessageAccepted): + continue + if isinstance(event, events_.HookEvent): + # Agent's outer runtime carries hook events, while the + # direct path exposes them in events(). + try: + runtime = runtime_.get_runtime() + except LookupError: + raise errors.WorkerError( + "approval requires events() or ai.Agent.run(); " + "resolve with worker.hook_registry" + ) from None + await runtime.put_event(event) + continue + if isinstance(event, events_.StreamEnd): + if ( + output_type is not None + and event.finish_reason != "tool_call" + ): + text, usage = await self._output( + "".join(answer), output_type, event.usage, feed + ) + yield projection.feed( + events_.TextStart( + block_id="output", message=event.message + ) + ) + yield projection.feed( + events_.TextDelta( + chunk=text, + block_id="output", + message=event.message, + ) + ) + yield projection.feed( + events_.TextEnd( + block_id="output", message=event.message + ) + ) + event = event.model_copy(update={"usage": usage}) + native = event.message + event = projection.feed(event) + if output_type is not None: + # Persist all emitted parts, including builtin and + # Agent tools, not just the validated output text. + metadata = native.provider_metadata or {} + native.provider_metadata = { + **metadata, + "worker": { + **metadata.get("worker", {}), + "model_parts": event.message.model_dump( + mode="json" + )["parts"], + }, + } + yield event + break if output_type is not None and isinstance( event, events_.TextStart | events_.TextDelta | events_.TextEnd, ): - # Narration is not the output. Keep only the text - # after the last tool call, and send it once parsed. if isinstance(event, events_.TextDelta): answer.append(event.chunk) continue if isinstance(event, events_.BuiltinToolStart): answer.clear() - yield out(event) - # Committed only now: a call that failed can be sent again. - self.messages = [*plan.transcript, hydrator.message] - except (GeneratorExit, asyncio.CancelledError): - if not paused: - # Nobody reads this turn any more: end it in the CLI too. - await self._abandon() - raise + yield projection.feed(event) finally: - rt.lock.release() - - # -- the conversation ----------------------------------------------------- + rt.stream_owner = None + rt.submission = None + rt.model_ready.set() def _plan(self, messages: list[messages_.Message]) -> _Plan: - """Compare `messages` with the transcript; return what is new.""" known = [m.id for m in self.messages] given = [m.id for m in messages] plan = _Plan() - system = [m.text for m in messages if m.role == "system"] - plan.instructions = "\n\n".join(system) or None + plan.instructions = ( + "\n\n".join(m.text for m in messages if m.role == "system") or None + ) if known: - if given[: len(known)] != known: + projected: list[messages_.Message] = [] + for message in self.messages: + metadata = (message.provider_metadata or {}).get("worker", {}) + if metadata.get("model_hidden"): + continue + parts = metadata.get("model_parts") + projected.append( + message + if parts is None + else message.model_copy( + update={ + "parts": TypeAdapter( + list[messages_.Part] + ).validate_python(parts) + } + ) + ) + matched_ids = False + for history in (self.messages, projected): + if given[: len(history)] != [m.id for m in history]: + continue + matched_ids = True + # Accept either complete view, never arbitrary per-message + # substitutions. Matching ids must not conceal changed parts. + if all( + old.role == new.role and old.parts == new.parts + for old, new in zip(history, messages, strict=False) + ): + new_messages = messages[len(history) :] + break + else: raise errors.TranscriptMismatchError( - f"{self.kind}: these messages do not continue this " - "worker's conversation; start a new worker" + "stored message content was changed" + if matched_ids + else f"{self.worker_class_id}: messages do not continue " + "this session; use a new worker" ) - new = messages[len(known) :] - plan.transcript = list(self.messages) elif self.session_id is not None: - # A stored conversation the worker has not loaded: the CLI holds - # the past, so everything given is new. `load()` reads the past. - new = list(messages) + new_messages = list(messages) else: - # A new conversation. What comes before the last user turn is - # its past; the CLI is seeded with it before the first turn. cut = len(messages) while cut and messages[cut - 1].role in ("user", "system", "tool"): cut -= 1 plan.seed = [m for m in messages[:cut] if m.role != "system"] - new = messages[cut:] + new_messages = messages[cut:] plan.transcript = list(messages[:cut]) - for message in new: + for message in new_messages: if message.role == "tool": plan.results.extend(message.tool_results) elif message.role == "system": @@ -414,59 +810,12 @@ def _plan(self, messages: list[messages_.Message]) -> _Plan: ) else: raise errors.TranscriptMismatchError( - f"{self.kind}: a {message.role} message the worker did " - "not write; only user, system and tool messages can " - "follow its last answer (load() reads a stored past)" + "only user, system and tool messages may follow " + "the last answer" ) - plan.transcript.extend(new) + plan.transcript.extend(new_messages) return plan - async def _ensure_session(self, plan: _Plan) -> None: - rt = self._require_runtime() - if rt.in_session: - return - self.session_id = await rt.adapter.open( - session_id=self.session_id, - fork=self.fork, - seed=plan.seed if self.session_id is None and plan.seed else None, - instructions=plan.instructions, - ) - self.fork = False - rt.in_session = True - - def _start( - self, - prompt: list[messages_.TextPart | messages_.FilePart], - output_type: type[pydantic.BaseModel] | None, - ) -> None: - rt = self._require_runtime() - if output_type is not None: - schema = json.dumps(TypeAdapter(output_type).json_schema()) - prompt = [ - *prompt, - messages_.TextPart(text=OUTPUT_INSTRUCTION + schema), - ] - queue: asyncio.Queue[Any] = asyncio.Queue() - adapter = rt.adapter - - async def pump() -> None: - try: - async for event in adapter.turn(prompt): - queue.put_nowait(event) - except asyncio.CancelledError: - raise - except BaseException as exc: - queue.put_nowait(_Failed(exc)) - - rt.queue = queue - rt.pump = asyncio.create_task(pump()) - - def _end_turn(self) -> None: - rt = self._require_runtime() - rt.queue = None - rt.pump = None - rt.hidden.clear() - def _answer(self, results: list[messages_.ToolResultPart]) -> None: rt = self._require_runtime() for part in results: @@ -476,40 +825,23 @@ def _answer(self, results: list[messages_.ToolResultPart]) -> None: value = part.model_input if value is messages_.MODEL_INPUT_UNSET: value = part.result - text = value if isinstance(value, str) else _dump(value) - call.answer.set_result((text, part.result_kind == "error")) + call.answer.set_result( + ( + value if isinstance(value, str) else _dump(value), + part.result_kind == "error", + ) + ) for call in rt.pending.values(): - # A call the caller did not answer: tell the CLI, do not hang. if not call.answer.done(): call.answer.set_result(("no result was given", True)) rt.pending.clear() - async def _abandon(self) -> None: - """End the running turn: the caller moved on without it.""" - rt = self._runtime - if rt is None: - return - for call in rt.pending.values(): - if not call.answer.done(): - call.answer.set_result(("cancelled by the caller", True)) - rt.pending.clear() - pump = rt.pump - if pump is None: - return - with contextlib.suppress(Exception): - await rt.adapter.interrupt() - pump.cancel() - with contextlib.suppress(BaseException): - await pump - self._end_turn() - async def _on_call( self, name: str, arguments: dict[str, Any] ) -> tuple[str, bool]: - """Hand a bridge call to the caller, and wait for the result.""" rt = self._runtime - if rt is None or rt.queue is None: - return ("no turn is running", True) + if rt is None or rt.pump is None: + return "no turn is running", True answer: asyncio.Future[tuple[str, bool]] = ( asyncio.get_running_loop().create_future() ) @@ -521,44 +853,33 @@ async def _on_call( async def _approve( self, tool_call_id: str, tool_name: str, tool_input: dict[str, Any] ) -> tuple[bool, str]: - """Ask about one of the CLI's own tool calls, through `ai.hook`.""" if self._is_bridge_tool(tool_name): - # An `ai` tool: the agent gates it itself, if it is gated. return True, "" rt = self._runtime - if rt is None or rt.context is None: - return False, "no run to ask in; denied" - - async def ask() -> tuple[bool, str]: + if rt is None or rt.closed: + return False, "session is closed" + task = asyncio.current_task() + if task is not None: + rt.approvals.add(task) + try: approval = await hooks.hook( f"approve_{tool_call_id}", payload=hooks.ToolApproval, metadata={"tool": tool_name, "kwargs": tool_input}, tool_call_id=tool_call_id, + registry=rt.registry, + runtime=_HookRuntime(rt.queue), ) return approval.granted, approval.reason or "denied" - - # In the caller's context: that is where the run's hooks live. - task = asyncio.create_task(ask(), context=rt.context) - try: - return await task except asyncio.CancelledError: - current = asyncio.current_task() - if current is not None and current.cancelling(): - raise return False, "the approval was cancelled" except Exception as exc: return False, f"approval failed ({type(exc).__name__}); denied" + finally: + if task is not None: + rt.approvals.discard(task) def _is_bridge_tool(self, tool_name: str) -> bool: - """Whether a tool the CLI reports is a bridge call. - - Those reach the caller as `ToolCallPart`s, so the CLI's own report - of them is hidden. Claude Code names an MCP tool - `mcp____`; codex uses the bare name, or the server's - name when the tool name is missing (measured: codex 0.160). How pi - names them is not measured yet: the forms it may use are accepted. - """ rt = self._runtime if rt is None: return False @@ -570,11 +891,8 @@ def _is_bridge_tool(self, tool_name: str) -> bool: ) def _visible(self, event: events_.Event) -> list[events_.Event]: - """Drop StreamStart and the CLI's own report of bridge calls.""" rt = self._require_runtime() match event: - case events_.StreamStart(): - return [] # a worker message has its own case events_.BuiltinToolStart(): if self._is_bridge_tool(event.tool_name): rt.hidden.add(event.tool_call_id) @@ -595,175 +913,52 @@ async def _output( text: str, output_type: type[pydantic.BaseModel], usage: usage_.Usage | None, + feed: AsyncIterator[SessionEvent], ) -> tuple[str, usage_.Usage | None]: - """Parse the answer, asking again when it does not validate.""" - adapter = self._require_runtime().adapter parsed, error = _parse(text, output_type) attempt = 0 while error is not None and attempt < OUTPUT_RETRIES: attempt += 1 - retry = messages_.TextPart( - text=f"Your previous reply failed validation: {error}\n" + await self.send( + f"Your previous reply failed validation: {error}\n" "Reply again with ONLY the corrected JSON." ) chunks: list[str] = [] - async for event in adapter.turn([retry]): - if isinstance(event, events_.BuiltinToolStart): - chunks.clear() - elif isinstance(event, events_.TextDelta): + async for event in feed: + if isinstance(event, UserMessageAccepted | events_.ModelEvent): + # Retry input and answers remain in the native mirror, but + # are not separate messages in the caller's model view. + # Reapply on StreamEnd, which installs native metadata. + metadata = event.message.provider_metadata or {} + event.message.provider_metadata = { + **metadata, + "worker": { + **metadata.get("worker", {}), + "model_hidden": True, + }, + } + if isinstance(event, events_.TextDelta): chunks.append(event.chunk) - elif isinstance(event, events_.StreamEnd) and event.usage: - usage = usage + event.usage if usage else event.usage + elif isinstance(event, events_.BuiltinToolStart): + chunks.clear() + elif isinstance(event, events_.StreamEnd): + if event.usage: + usage = usage + event.usage if usage else event.usage + break + elif isinstance(event, events_.HookEvent): + await runtime_.get_runtime().put_event(event) text = "".join(chunks) parsed, error = _parse(text, output_type) return (parsed.model_dump_json() if parsed else text), usage def _metadata(self, finish: str | None) -> dict[str, Any]: - meta: dict[str, Any] = {"kind": self.kind} + meta: dict[str, Any] = {"worker_class_id": self.worker_class_id} if self.session_id: meta["session_id"] = self.session_id if finish is not None: meta["finish_reason"] = finish return {"worker": meta} - # -- lifecycle ------------------------------------------------------------ - - async def _open(self) -> _Runtime: - if self._runtime is not None: - return self._runtime - bridge = _bridge.Bridge(self._on_call) - await bridge.start() - servers = { - **self.mcp_servers, - _bridge.SERVER_NAME: {"type": "http", "url": bridge.url}, - } - adapter = self._make_adapter( - servers, self._approve if self.approve else None - ) - try: - await adapter.start() - except BaseException: - await bridge.close() - raise - self._runtime = _Runtime(adapter=adapter, bridge=bridge) - return self._runtime - - async def close(self) -> None: - """End the turn, the CLI and the bridge. The fields stay as they are. - - A closed worker opens again on its next use, and resumes its - conversation. - """ - rt = self._runtime - if rt is None: - return - await self._abandon() - self._runtime = None - try: - await rt.adapter.close() - finally: - await rt.bridge.close() - - async def __aenter__(self) -> Self: - await self._open() - return self - - async def __aexit__(self, *exc_info: object) -> None: - await self.close() - - def _require_runtime(self) -> _Runtime: - if self._runtime is None: - raise errors.WorkerError(f"{self.kind} worker is not open") - return self._runtime - - @property - def version(self) -> str | None: - """What the CLI's `--version` printed, once the worker is open.""" - return self._runtime.adapter.version if self._runtime else None - - # -- what only a CLI has -------------------------------------------------- - - async def load(self) -> None: - """Read the stored conversation `session_id` names into `messages`. - - Also after a person worked in the CLI's TUI (see `tui()`). - """ - if self.session_id is None: - raise errors.WorkerError(f"{self.kind}: no session_id to load") - rt = await self._open() - self.messages = await rt.adapter.history(self.session_id) - - async def steer(self, text: str) -> None: - """Send guidance to the turn that runs now; the agent acts on it. - - For use from another task while `stream()` runs. The text is not - added to `messages`; `load()` reads it back from the CLI. - """ - rt = self._require_runtime() - if rt.queue is None: - raise errors.WorkerError(f"{self.kind}: no turn is running") - await rt.adapter.steer(text) - - def tui_command(self) -> tuple[list[str], dict[str, str]]: - """Return the CLI's own TUI command for this conversation. - - Run it in `cwd`, with the env added to yours:: - - argv, env = worker.tui_command() - subprocess.run(argv, cwd=worker.cwd, env={**os.environ, **env}) - - A worker with no conversation yet gets a new one, when the CLI lets - us choose its id (Claude Code, Pi). Close the worker first: one - writer per conversation. - """ - if self.fork: - raise errors.WorkerError( - f"{self.kind}: run a turn first; the fork happens on first use" - ) - rt = self._runtime - adapter = ( - rt.adapter if rt else self._make_adapter(self.mcp_servers, None) - ) - argv, env, minted = adapter.tui_command(self.session_id) - if self.session_id is None: - if minted is None: - raise errors.WorkerError( - f"{self.kind} picks its own session id: run a turn " - "first, or pass session_id=" - ) - self.session_id = minted - return argv, env - - async def tui(self) -> int: - """Hand the conversation to a person, in this terminal. - - Runs the CLI's TUI on it and returns its exit code once the person - quits. The worker then reads the conversation back (`load()`) and - goes on headless. - """ - await self.close() - argv, env = self.tui_command() - proc = await asyncio.create_subprocess_exec( - *argv, cwd=self.cwd, env={**os.environ, **env} - ) - code = await proc.wait() - await self.load() - return code - - @classmethod - async def list_sessions(cls, **fields: Any) -> list[_adapter.SessionInfo]: - """Return the conversations the CLI has stored for a directory. - - Takes the worker's fields: `cwd=`, `env=`, `executable=`. - """ - worker = cls(**fields) - adapter = worker._make_adapter({}, None) - await adapter.start() - try: - return await adapter.list_sessions() - finally: - await adapter.close() - def _parse( text: str, output_type: type[pydantic.BaseModel] @@ -775,7 +970,6 @@ def _parse( def _extract_json(text: str) -> str: - """Best effort: the model was told "only JSON", but fences happen.""" candidate = text.strip() if candidate.startswith("```"): parts = candidate.split("```") diff --git a/src/ai/workers/claude_code/adapter.py b/src/ai/workers/claude_code/adapter.py deleted file mode 100644 index d4964c3d..00000000 --- a/src/ai/workers/claude_code/adapter.py +++ /dev/null @@ -1,656 +0,0 @@ -"""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 AsyncIterator -from typing import Any, Literal - -import claude_agent_sdk - -from ...types import events as events_ -from ...types import messages as messages_ -from ...types import usage as usage_ -from .. import _adapter, _bridge, _convert, _handoff -from .. import _errors as errors -from . import handoff - -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 ClaudeAdapter: - def __init__( - self, - *, - cwd: str, - env: dict[str, str], - executable: str, - model: str | None, - effort: str | None, - mcp_servers: dict[str, Any], - approve: _adapter.Approve | None, - allowed_tools: list[str] | None, - disallowed_tools: list[str] | None, - max_turns: int | None, - ) -> None: - # The CLI keys its store by the real path of its directory. - self._cwd = os.path.realpath(cwd) - self._env = env - self._executable = executable - self._model = model - self._effort = effort - self._mcp_servers = mcp_servers - self._approve = approve - self._allowed_tools = allowed_tools - self._disallowed_tools = disallowed_tools - self._max_turns = max_turns - self._instructions: str | None = None - self._client: Any = None - self._session_id: str | None = None - # We interrupted the turn. The CLI reports an error result after an - # interrupt, and a stop we asked for must not raise as a failure. - self._interrupted = False - # A turn is running: prompted, no ResultMessage yet. A steer outside - # one would start a turn of its own (measured). - self._running = False - self.version: str | None = None - - async def start(self) -> None: - self.version = await _adapter.probe( - KIND, - self._executable, - install=INSTALL, - verified=VERIFIED_VERSION, - cwd=self._cwd, - env=self._env, - ) - - async def close(self) -> None: - client, self._client = self._client, None - if client is not None: - with contextlib.suppress(Exception): - await client.disconnect() - - # -- the conversation ----------------------------------------------------- - - async def 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) - 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) - self._session_id = 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.""" - 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. - """ - 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: - options: dict[str, Any] = { - "cwd": self._cwd, - # 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: - options["model"] = self._model - 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._approve 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._approve is not None - granted, reason = await self._approve( - 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: - assert self._approve is not None - granted, reason = await self._approve( - 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 turn( - self, prompt: _adapter.Prompt - ) -> AsyncIterator[events_.Event]: - _convert.check_files(prompt, KIND, ("image/", "application/pdf")) - client = self._client - assert client is not None - # An interrupted turn leaves its trailing result unread: the CLI - # still emits one after the interrupt. Read it first, or THIS turn - # would settle on the previous turn's ending. - 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._running = True - try: - # StreamStart once the CLI answers: its first message proves it - # read the prompt. - started = False - async for message in _guard(client.receive_response()): - if not started: - started = True - yield events_.StreamStart() - if isinstance(message, claude_agent_sdk.StreamEvent): - # Text and reasoning stream here, token by token. The - # AssistantMessage that follows repeats them, so only - # tool calls are taken from it. - 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): - self._running = False - interrupted, self._interrupted = self._interrupted, False - yield events_.StreamEnd( - usage=_usage(message), - finish_reason=_finish_reason( - message, interrupted=interrupted - ), - ) - finally: - self._running = False - - async def _drain_interrupted(self) -> None: - if not self._interrupted or self._client is None: - return - self._interrupted = False - with contextlib.suppress(Exception): - async with asyncio.timeout(30): - async for message in self._client.receive_response(): - if isinstance(message, claude_agent_sdk.ResultMessage): - break - - async def steer(self, text: str) -> None: - # `query()` writes straight to the CLI's stdin, so a message can - # land while the turn is still running. - if not self._running or self._client is None: - raise errors.WorkerError(f"{KIND}: no turn is running to steer") - await self._client.query(text) - - async def 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 history(self, session_id: str) -> list[messages_.Message]: - """Read the CLI's own transcript, every content block included.""" - 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 list_sessions(self) -> list[_adapter.SessionInfo]: - 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 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: - argv += ["--model", self._model] - 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 - - -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.""" - 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.""" - try: - 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/claude_code/worker.py b/src/ai/workers/claude_code/worker.py index 23af2612..5b3b74a8 100644 --- a/src/ai/workers/claude_code/worker.py +++ b/src/ai/workers/claude_code/worker.py @@ -1,11 +1,51 @@ -"""`ClaudeCode`: Claude Code as a worker.""" +"""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 -from typing import Any, Literal +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 .. import _adapter, _worker +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): @@ -17,33 +57,701 @@ class ClaudeCode(_worker.Worker): `finish_reason="length"`. """ - kind: Literal["claude-code"] = "claude-code" + 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 - def _make_adapter( + _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, - mcp_servers: dict[str, dict[str, Any]], - approve: _adapter.Approve | None, - ) -> _adapter.CLIAdapter: - _optional.import_optional_sdk( - "claude_agent_sdk", - extra="claude-code", - feature="ai.workers.ClaudeCode", - ) - # Imported here: the adapter needs claude_agent_sdk at import time. - from . import adapter # noqa: PLC0415 - - return adapter.ClaudeAdapter( - cwd=self.cwd, - env=dict(self.env), - executable=self.executable or "claude", - model=self.model, - effort=self.effort, - mcp_servers=dict(mcp_servers), - approve=approve, - allowed_tools=self.allowed_tools, - disallowed_tools=self.disallowed_tools, - max_turns=self.max_turns, + *, + 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/adapter.py b/src/ai/workers/codex/adapter.py deleted file mode 100644 index 47a176a1..00000000 --- a/src/ai/workers/codex/adapter.py +++ /dev/null @@ -1,696 +0,0 @@ -"""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 AsyncIterator -from typing import Any - -from ...types import events as events_ -from ...types import messages as messages_ -from ...types import usage as usage_ -from .. import _adapter, _bridge, _convert, _handoff -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 CodexAdapter: - def __init__( - self, - *, - cwd: str, - env: dict[str, str], - executable: str, - model: str | None, - mcp_servers: dict[str, Any], - approve: _adapter.Approve | None, - sandbox: str | None, - config: dict[str, Any], - ) -> None: - # Codex records a thread's directory as its real path (on macOS a - # temp dir is /var/..., recorded as /private/var/..., measured). - self._cwd = os.path.realpath(cwd) - self._env = env - self._executable = executable - self._model = model - self._approve = approve - # Full access by default, like claude without a gate: a worker is - # driven by a program, and a mode that silently refuses writes reads - # as an agent that did nothing. - self._sandbox = sandbox or "danger-full-access" - # Passed to app-server as `-c key=value`, the overrides the codex - # CLI takes. An explicit config wins over the MCP servers. - self._config = {**mcp_config(mcp_servers), **config} - self._instructions: str | None = None - self._process: jsonrpc.Process | None = None - self._peer: jsonrpc.JsonRpcPeer | None = None - self._thread: str | None = None - self._turn: str | None = None - self._queue: asyncio.Queue[tuple[str, dict[str, Any]]] | None = None - self._usage = usage_.Usage() - self._interrupted = False - self.version: str | None = None - - async def start(self) -> None: - self.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.close() - raise - - async def 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 - - 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, - # With a gate: ask about everything the policy can ask about. - # Without one the server never asks: a request nobody answers - # would freeze the agent (measured). - "approvalPolicy": "untrusted" if self._approve else "never", - **({"model": self._model} if self._model else {}), - **( - {"developerInstructions": self._instructions} - if self._instructions - else {} - ), - } - - # -- the conversation ----------------------------------------------------- - - async def 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._approve is None: - # Unknown, or unasked for: answer rather than hang the agent. - decision = "accept" if method in APPROVAL_METHODS else "decline" - await self._rpc().respond(request_id, {"decision": decision}) - return - granted, _ = await self._approve( - 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 turn( - self, prompt: _adapter.Prompt - ) -> AsyncIterator[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") - 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 steer(self, text: str) -> None: - if not self._turn: - raise errors.WorkerError(f"{KIND}: no turn is running to steer") - try: - await self._rpc().call( - "turn/steer", - { - "threadId": self._thread, - # A precondition: steering the wrong turn is worse than - # failing to steer. - "expectedTurnId": self._turn, - "input": [{"type": "text", "text": text}], - }, - ) - except jsonrpc.JsonRpcError as exc: - raise errors.WorkerError(f"{KIND}: steer rejected: {exc}") from exc - - async def 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 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 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 tui_command( - self, session_id: str | None - ) -> tuple[list[str], dict[str, str], str | None]: - config = { - k: v - for k, v in self._config.items() - 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: - argv += ["--model", self._model] - 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/codex/worker.py b/src/ai/workers/codex/worker.py index f0293481..eba362e2 100644 --- a/src/ai/workers/codex/worker.py +++ b/src/ai/workers/codex/worker.py @@ -1,13 +1,65 @@ -"""`Codex`: Codex as a worker.""" +"""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 .. import _adapter, _bridge, _worker -from . import adapter +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): @@ -18,17 +70,40 @@ class Codex(_worker.Worker): takes Codex `-c` overrides. """ - kind: Literal["codex"] = "codex" + 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) - def _make_adapter( - self, - mcp_servers: dict[str, dict[str, Any]], - approve: _adapter.Approve | None, - ) -> _adapter.CLIAdapter: + _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( @@ -36,19 +111,636 @@ def _make_adapter( "xhigh" if self.effort == "max" else self.effort, ) if _bridge.SERVER_NAME in mcp_servers: - # Codex's default wait for an MCP tool (60s) is too short for a - # tool an `ai.Agent` runs, maybe after an approval. + # 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, ) - return adapter.CodexAdapter( - cwd=self.cwd, - env=dict(self.env), - executable=self.executable or "codex", - model=self.model, - mcp_servers=dict(mcp_servers), - approve=approve, - sandbox=self.sandbox, - config=config, + # 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/adapter.py b/src/ai/workers/pi/adapter.py deleted file mode 100644 index 96d6d53d..00000000 --- a/src/ai/workers/pi/adapter.py +++ /dev/null @@ -1,1231 +0,0 @@ -"""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 this adapter 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 AsyncIterator, Mapping, Sequence -from typing import Any - -from ...types import events as events_ -from ...types import messages as messages_ -from ...types import usage as usage_ -from .. import _adapter, _bridge, _convert, _handoff -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 PiAdapter: - def __init__( - self, - *, - cwd: str, - env: dict[str, str], - executable: str, - model: str | None, - effort: str | None, - mcp_servers: dict[str, Any], - approve: _adapter.Approve | None, - allowed_tools: list[str] | None, - disallowed_tools: list[str] | None, - ) -> None: - self._cwd = cwd - self._env = env - self._executable = executable - self._model = model - self._effort = effort - self._mcp_servers = mcp_servers - self._approve = approve - self._allowed_tools = allowed_tools - self._disallowed_tools = disallowed_tools - self._instructions: str | None = None - self._agent: _Agent | None = None - # We ended the turn: it settles as cancelled. - self._interrupted = False - # A prompt was accepted and no `agent_settled` came yet. - self._running = False - self.version: str | None = None - - async def start(self) -> None: - self.version = await _adapter.probe( - KIND, - self._executable, - install=INSTALL, - verified=VERIFIED_VERSION, - cwd=self._cwd, - env=self._env, - ) - - async def close(self) -> None: - agent, self._agent = self._agent, None - self._running = False - 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: - args += ["--model", self._model] - 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 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._approve 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._approve 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._approve( - 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 turn( - self, prompt: _adapter.Prompt - ) -> AsyncIterator[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 - command = await _prompt_command(prompt) - 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"): - 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": - 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 steer(self, text: str) -> None: - """Queue guidance for the running turn. - - pi delivers it once the current message's tool calls are done, - before its next model call. - """ - if not self._running or self._agent is None: - raise errors.WorkerError(f"{KIND}: no turn is running to steer") - try: - await self._agent.call({"type": "steer", "message": text}) - except _CommandError as exc: - raise errors.WorkerError(f"{KIND}: steer rejected: {exc}") from exc - - async def 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 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 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 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._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: - 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/src/ai/workers/pi/worker.py b/src/ai/workers/pi/worker.py index 0bde399f..f0d3e581 100644 --- a/src/ai/workers/pi/worker.py +++ b/src/ai/workers/pi/worker.py @@ -1,11 +1,70 @@ -"""`Pi`: pi as a worker.""" +"""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 -from .. import _adapter, _worker -from . import adapter +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): @@ -15,23 +74,1224 @@ class Pi(_worker.Worker): none), and `disallowed_tools` takes some away. """ - kind: Literal["pi"] = "pi" + worker_class_id: Literal["pi"] = "pi" allowed_tools: list[str] | None = None disallowed_tools: list[str] | None = None - def _make_adapter( + _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, - mcp_servers: dict[str, dict[str, Any]], - approve: _adapter.Approve | None, - ) -> _adapter.CLIAdapter: - return adapter.PiAdapter( + *, + 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=dict(self.env), - executable=self.executable or "pi", - model=self.model, - effort=self.effort, - mcp_servers=dict(mcp_servers), - approve=approve, - allowed_tools=self.allowed_tools, - disallowed_tools=self.disallowed_tools, + env=self._extension_env( + approve=self._approval_callback is not None, + servers=self._mcp_servers, + ), + ) + agent = _Agent(process, on_dialog=self._on_dialog) + agent.start() + try: + state = await agent.call({"type": "get_state"}, timeout=60) + reported = (state or {}).get("sessionId") + if reported and reported != session_id: + raise errors.WorkerError( + f"{KIND} opened session {reported}, not {session_id}" + ) + # The approval gate must be there before any work is accepted: + # a gate that failed to load is a gate that fails open. + listed = await agent.call({"type": "get_commands"}, timeout=60) + names = { + c.get("name") for c in (listed or {}).get("commands") or [] + } + if READY not in names: + raise errors.WorkerError( + f"{KIND} did not load the SDK's extension ({EXTENSION}); " + "refusing to run without it" + ) + except BaseException: + await agent.close() + with contextlib.suppress(Exception): + await process.terminate() + raise + self._agent = agent + + async def _stage(self, history: list[messages_.Message]) -> str: + """Write a session file with this past; start nothing on it.""" + session_id = str(uuid.uuid4()) + _handoff.warn_unsupported_files(history, KIND) + dropped = _handoff.reasoning_count(history) + if dropped: + # pi drops thinking another model produced, and replaying it as + # user text is refused by Anthropic's safeguards. + warnings.warn( + f"{dropped} reasoning part(s) in the history were not carried " + "into pi: a model only reads its own reasoning. Text, tool " + "calls and images were carried in full.", + stacklevel=2, + ) + directory = self._session_dir() + now = datetime.datetime.now(datetime.UTC) + stamp = now.isoformat(timespec="milliseconds").replace("+00:00", "Z") + lines: list[dict[str, Any]] = [ + { + "type": "session", + "version": 3, + "id": session_id, + "timestamp": stamp, + "cwd": os.path.realpath(self.cwd), + } + ] + parent: str | None = None + # The model the conversation was on, as pi records a switch: pi + # restores a session's model from its last reply's author. Measured: + # without it, a seeded conversation ran on pi's default model. + written: dict[str, Any] = next( + ( + found + for m in reversed(history) + if m.role == "assistant" + and isinstance( + found := (m.provider_metadata or {}).get(KIND), dict + ) + ), + {}, + ) + changes: list[dict[str, Any]] = [] + if written.get("provider") and written.get("model"): + changes.append( + { + "type": "model_change", + "provider": written["provider"], + "modelId": written["model"], + } + ) + if written.get("thinkingLevel"): + changes.append( + { + "type": "thinking_level_change", + "thinkingLevel": written["thinkingLevel"], + } + ) + entries = [ + *changes, + *( + {"type": "message", "message": message} + for message in handoff.to_pi_messages( + history, timestamp=int(now.timestamp() * 1000) + ) + ), + ] + for entry in entries: + entry_id = uuid.uuid4().hex[:8] + lines.append( + { + **entry, + "id": entry_id, + "parentId": parent, + "timestamp": stamp, + } + ) + parent = entry_id + name = stamp.replace(":", "-").replace(".", "-") + path = directory / f"{name}_{session_id}.jsonl" + text = "".join(json.dumps(line) + "\n" for line in lines) + + def write() -> None: + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(text) + + await asyncio.to_thread(write) + return session_id + + # -- approval ------------------------------------------------------------- + + async def _on_dialog(self, agent: _Agent, request: dict[str, Any]) -> None: + if request.get("method") not in DIALOGS: + return # a notice: nothing waits for an answer + reply: dict[str, Any] = { + "type": "extension_ui_response", + "id": request.get("id"), + } + if ( + request.get("method") != "input" + or request.get("title") != APPROVE + or self._approval_callback is None + or self._interrupted + ): + # Another extension asking a person, who is not there; or the + # turn is being stopped, and `abort` would wait on the question. + agent.pending.pop(str(request.get("id")), None) + await agent.send({**reply, "cancelled": True}) + return + try: + payload = json.loads(request.get("placeholder") or "{}") + except json.JSONDecodeError: + payload = {} + granted, reason = await self._approval_callback( + str(payload.get("toolCallId") or ""), + str(payload.get("toolName") or ""), + dict(payload.get("input") or {}), + ) + decision = ( + {"decision": "allow"} + if granted + else {"decision": "deny", "reason": reason} + ) + # Answered from here on: `dismiss` must not withdraw it too. + agent.pending.pop(str(request.get("id")), None) + await agent.send({**reply, "value": json.dumps(decision)}) + + # -- turns ---------------------------------------------------------------- + + async def _cli_turn( + self, prompt: _adapter.Prompt + ) -> AsyncGenerator[events_.Event]: + _convert.check_files(prompt, KIND, ("image/",)) + agent = self._agent + assert agent is not None + if agent.dead is not None: + raise errors.WorkerError(f"{KIND} crashed: {agent.dead}") + # What the last turn left behind (a stopped turn's tail) is not this + # turn's: `abort` answers only once pi is idle, so it has all arrived. + while not agent.events.empty(): + agent.events.get_nowait() + self._interrupted = False + self._continued_runs = 0 + self._settled_count = agent.settled_count + command = await _prompt_command(prompt) + runs_started = agent.runs_started + try: + accepted = await agent.call(command) + except _CommandError as exc: + raise errors.turn_failed(KIND, str(exc), AUTH_HINT) from exc + if (accepted or {}).get("disposition") == "handled": + # An extension command consumed it. It may start a run of its own + # (measured: then pi is already streaming, and that run is ours). + state = await agent.call({"type": "get_state"}) + if ( + not (state or {}).get("isStreaming") + and agent.runs_started == runs_started + ): + yield events_.StreamStart() + yield events_.StreamEnd(finish_reason="stop") + return + self._running = True + usage = usage_.Usage() + cost = 0.0 + started: set[str] = set() + streamed: set[str] = set() + open_blocks: dict[str, str] = {} + message_no = 0 + last: dict[str, Any] = {} + retry_error = "" + settled: dict[str, Any] = {} + try: + yield events_.StreamStart() + while True: + event = await agent.events.get() + kind = event.get("type") + if kind == CRASHED: + raise errors.WorkerError( + f"{KIND} crashed: {event.get('detail')}" + ) + if kind == CLOSED: + raise errors.WorkerError( + f"{KIND}: the worker closed while its turn ran" + ) + message = event.get("message") or {} + if kind == "message_start" and message.get("role") == ( + "assistant" + ): + message_no += 1 + elif kind == "message_update": + for out in _stream_events( + event.get("assistantMessageEvent") or {}, + f"{message_no}", + open_blocks, + started, + ): + if isinstance( + out, events_.TextStart | events_.ReasoningStart + ): + streamed.add(out.block_id) + yield out + elif kind == "message_end" and message.get("role") == ( + "assistant" + ): + last = message + raw = message.get("usage") or {} + usage = usage + _usage(raw) + cost += float((raw.get("cost") or {}).get("total") or 0) + for out in _close_blocks(open_blocks): + yield out + if message.get("stopReason") != "error": + # What the message holds that was never streamed (a + # run an extension command started, measured). + for out in _unstreamed( + message.get("content"), + f"{message_no}", + streamed, + started, + ): + yield out + elif kind == "tool_execution_end" and not event.get( + "parentToolCallId" + ): + # A nested call (a codemode script's) is not in the + # transcript: only the tool that made it reports it. + call_id = str(event.get("toolCallId") or "") + name = str(event.get("toolName") or "") + yield _convert.builtin_result( + call_id, + name, + _tool_result(event.get("result") or {}), + is_error=bool(event.get("isError")), + ) + elif kind == "auto_retry_end" and not event.get("success"): + retry_error = str(event.get("finalError") or "") + elif kind == "agent_settled": + async with self._input_lock: + self._settled_count += 1 + if self._continued_runs: + # An input raced this completion and started a + # new native run. Its events are already queued; + # keep this reader alive to consume them once. + self._continued_runs -= 1 + continue + self._running = False + settled = event + break + finally: + self._running = False + interrupted = self._interrupted or bool(settled.get("aborted")) + self._interrupted = False + stop = last.get("stopReason") + if stop == "error" and not interrupted: + raise errors.turn_failed( + KIND, + str(last.get("errorMessage") or retry_error), + AUTH_HINT, + ) + yield events_.StreamEnd( + # Cost has no home in Usage; pi's own number rides in `raw`. + usage=usage.model_copy(update={"raw": {"cost_usd": cost}}), + finish_reason=( + "cancelled" + if interrupted or stop == "aborted" + else "length" + if stop == "length" + else "stop" + ), + provider_metadata=_written_by(last), + ) + + async def _cli_send_running(self, prompt: _adapter.Prompt) -> bool: + """Accept input without stranding a steer on a just-finished run.""" + _convert.check_files(prompt, KIND, ("image/",)) + command = await _prompt_command(prompt) + async with self._input_lock: + agent = self._agent + if agent is None: + raise errors.WorkerError(f"{KIND}: RPC process is not running") + state = await agent.call({"type": "get_state"}) + if (state or {}).get("isStreaming") is False: + # No input was submitted. The base can finish draining the + # old turn and submit this prompt as a new one. + return False + if not self._running: + raise errors.WorkerError( + f"{KIND}: no turn reader for the running CLI" + ) + try: + # `steer` queues even when idle. `prompt` chooses atomically + # between queueing and starting, including after async input + # hooks. Never clear_queue: it returns text only, losing files. + accepted = await agent.call( + {**command, "streamingBehavior": "steer"} + ) + except _CommandError as exc: + raise errors.turn_failed(KIND, str(exc), AUTH_HINT) from exc + disposition = (accepted or {}).get("disposition") + if disposition == "started": + self._continued_runs += 1 + elif disposition == "handled": + # Extension commands may start independent work, even after + # the old run settled. Follow it, including fast completions. + state = await agent.call({"type": "get_state"}) + latest = agent.last_start_settled + if (state or {}).get("isStreaming"): + latest = max(latest, agent.settled_count) + self._continued_runs = max( + self._continued_runs, latest - self._settled_count + ) + elif disposition != "queued": + # An ambiguous acceptance must never be retried as a new turn. + raise errors.WorkerError( + f"{KIND}: unknown prompt disposition: {accepted}" + ) + return True + + async def _cli_interrupt(self) -> None: + self._interrupted = True + agent = self._agent + if agent is None or agent.dead is not None: + return + # A tool call waiting on approval keeps pi busy, and `abort` only + # answers once pi is idle (measured: the turn ran on). Withdraw the + # question first: the call is denied, and the abort lands at once. + await agent.dismiss() + with contextlib.suppress(Exception): + await agent.call({"type": "abort"}, timeout=30) + + # -- the store ------------------------------------------------------------ + + def _session_dir(self) -> pathlib.Path: + """Where pi keeps this directory's sessions, decided as pi does. + + The environment, then project settings, then global ones; else one + directory per working directory under the agent dir. + """ + env = {**os.environ, **self.env} + cwd = os.path.realpath(self.cwd) + agent = pathlib.Path( + os.path.expanduser(env.get("PI_CODING_AGENT_DIR") or "~/.pi/agent") + ) + custom = ( + env.get("PI_CODING_AGENT_SESSION_DIR") + or _setting(pathlib.Path(cwd, ".pi", "settings.json")) + or _setting(agent / "settings.json") ) + if custom: + return pathlib.Path(cwd, os.path.expanduser(custom)) + safe = cwd.lstrip("/\\") + for c in "/\\:": + safe = safe.replace(c, "-") + return agent / "sessions" / f"--{safe}--" + + def _scan(self, *, titles: bool) -> list[dict[str, Any]]: + """Describe the sessions of this directory, newest first.""" + directory = self._session_dir() + cwd = os.path.realpath(self.cwd) + out: list[dict[str, Any]] = [] + try: + paths = sorted(directory.glob("*.jsonl")) + except OSError: + return [] + for path in paths: + with contextlib.suppress(Exception): + info = _describe(path, (cwd, self.cwd), titles=titles) + if info is not None: + out.append(info) + return sorted(out, key=lambda s: -s["updated"]) + + async def _find(self, session_id: str) -> dict[str, Any]: + if not SESSION_ID.match(session_id): + raise errors.WorkerError( + f"{KIND}: {session_id!r} is not a pi session id" + ) + found = next( + ( + s + for s in await asyncio.to_thread(self._scan, titles=False) + if s["id"] == session_id + ), + None, + ) + if found is None: + raise errors.WorkerError( + f"{KIND}: no session {session_id} in {self.cwd}" + ) + return found + + async def _cli_history(self, session_id: str) -> list[messages_.Message]: + """Read the active branch of the session file. + + Every message on it, root to latest entry, including what a + compaction summarized away, which pi keeps on disk. + """ + found = await self._find(session_id) + text = await asyncio.to_thread(pathlib.Path(found["path"]).read_text) + return _read(_active_branch(text)) + + async def _cli_list_sessions(self) -> list[_adapter.SessionInfo]: + return [ + _adapter.SessionInfo( + session_id=s["id"], + title=s.get("title"), + cwd=s.get("cwd"), + created_at=s.get("created"), + updated_at=s.get("updated"), + ) + for s in await asyncio.to_thread(self._scan, titles=True) + ] + + def _cli_tui_command( + self, session_id: str | None + ) -> tuple[list[str], dict[str, str], str | None]: + running_as = session_id or str(uuid.uuid4()) + argv = [self._executable, "--session-id", running_as, *self._args()] + servers = { + k: v + for k, v in self.mcp_servers.items() + if k != _bridge.SERVER_NAME + } + # The person at the TUI is the gate: the extension asks nothing. + return ( + argv, + self._extension_env(approve=False, servers=servers), + running_as, + ) + + +# -- the process ------------------------------------------------------------- + + +class Process: + """A CLI started by `spawn`: JSON lines on stdin and stdout.""" + + def __init__(self, proc: asyncio.subprocess.Process) -> None: + self._proc = proc + + async def write(self, data: str) -> None: + assert self._proc.stdin is not None + self._proc.stdin.write(data.encode()) + await self._proc.stdin.drain() + + async def readline(self) -> str: + assert self._proc.stdout is not None + return (await self._proc.stdout.readline()).decode() + + async def read_stderr(self) -> str: + if self._proc.stderr is None: + return "" + return (await self._proc.stderr.read()).decode(errors="replace") + + async def wait(self) -> int: + return await self._proc.wait() + + async def terminate(self) -> None: + """Stop the process group: SIGTERM, then SIGKILL.""" + if self._proc.returncode is not None: + return + with contextlib.suppress(ProcessLookupError): + os.killpg(os.getpgid(self._proc.pid), 15) + try: + async with asyncio.timeout(TERM_GRACE): + await self._proc.wait() + except TimeoutError: + with contextlib.suppress(ProcessLookupError): + os.killpg(os.getpgid(self._proc.pid), 9) + with contextlib.suppress(Exception): + await self._proc.wait() + + async def death_note(self) -> str: + """Say how the process ended, and its last words.""" + code: int | None = None + tail = "" + with contextlib.suppress(Exception): + async with asyncio.timeout(2): + code = await self.wait() + with contextlib.suppress(Exception): + async with asyncio.timeout(2): + tail = (await self.read_stderr()).strip() + how = f"exit code {code}" if code is not None else "exited" + if code in (137, -9): + how += " (SIGKILL, typically the kernel's OOM killer)" + return f"{how}; stderr: {tail[-800:]}" if tail else f"{how}; no stderr" + + +async def spawn( + argv: Sequence[str], *, cwd: str, env: Mapping[str, str] +) -> Process: + """Start a CLI in its own process group, with pipes for stdio.""" + try: + proc = await asyncio.create_subprocess_exec( + *argv, + cwd=cwd, + env={**os.environ, **env}, + stdin=asyncio.subprocess.PIPE, + stdout=asyncio.subprocess.PIPE, + stderr=asyncio.subprocess.PIPE, + # Own the whole tree, so teardown reaches grandchildren too. + start_new_session=True, + limit=LINE_LIMIT, + ) + except OSError as exc: + raise errors.WorkerError(f"cannot start {argv[0]!r}: {exc}") from exc + return Process(proc) + + +class _CommandError(Exception): + """pi answered a command with `success: false`.""" + + +class _Agent: + """One `pi --mode rpc` process: its commands, its events, its dialogs. + + Responses resolve the command that asked (by id). Session events go on + `events`, in order. A dialog is answered in a task of its own: an + approval can take minutes, and the reader must keep reading meanwhile, + including the reply to an `abort` sent from inside it. + """ + + def __init__(self, process: Process, *, on_dialog: Any) -> None: + self.process = process + self.events: asyncio.Queue[dict[str, Any]] = asyncio.Queue() + self.dead: str | None = None + self.runs_started = 0 + self.settled_count = 0 + self.last_start_settled = 0 + self._on_dialog = on_dialog + self._waiters: dict[str, asyncio.Future[Any]] = {} + self._pump: asyncio.Task[None] | None = None + self._dialogs: set[asyncio.Task[None]] = set() + # Dialogs pi still waits on, by request id: what `dismiss` withdraws. + self.pending: dict[str, asyncio.Task[None]] = {} + + def start(self) -> None: + self._pump = asyncio.create_task(self._read()) + + async def call( + self, command: dict[str, Any], *, timeout: float = 120 + ) -> Any: + if self.dead is not None: + raise errors.WorkerError(f"{KIND} crashed: {self.dead}") + request_id = uuid.uuid4().hex + future: asyncio.Future[Any] = asyncio.get_running_loop().create_future() + self._waiters[request_id] = future + try: + await self.send({**command, "id": request_id}) + async with asyncio.timeout(timeout): + return await future + finally: + self._waiters.pop(request_id, None) + + async def send(self, record: dict[str, Any]) -> None: + try: + await self.process.write(json.dumps(record) + "\n") + except Exception as exc: + raise errors.WorkerError( + f"{KIND}: could not write to pi: {exc}" + ) from exc + + def _track(self, request_id: str, task: asyncio.Task[None]) -> None: + self.pending[request_id] = task + + def forget(_: asyncio.Task[None]) -> None: + if self.pending.get(request_id) is task: + del self.pending[request_id] + + task.add_done_callback(forget) + + async def dismiss(self) -> None: + """Withdraw every question pi still waits on. + + The approval deciding it is cancelled, and pi hears `cancelled`: the + extension then blocks the call. + """ + for request_id, task in list(self.pending.items()): + self.pending.pop(request_id, None) + task.cancel() + with contextlib.suppress(asyncio.CancelledError, Exception): + await task + with contextlib.suppress(Exception): + await self.send( + { + "type": "extension_ui_response", + "id": request_id, + "cancelled": True, + } + ) + + async def close(self) -> None: + if self._pump is not None: + self._pump.cancel() + with contextlib.suppress(asyncio.CancelledError, Exception): + await self._pump + self._pump = None + for task in list(self._dialogs): + task.cancel() + for task in list(self._dialogs): + with contextlib.suppress(asyncio.CancelledError, Exception): + await task + self._dialogs.clear() + self._fail("connection closed") + # A turn reading events must hear it too: the producer is gone. + self.events.put_nowait({"type": CLOSED}) + + def _fail(self, detail: str) -> None: + self.dead = self.dead or detail + for future in self._waiters.values(): + if not future.done(): + future.set_exception( + errors.WorkerError(f"{KIND} crashed: {detail}") + ) + self._waiters.clear() + + async def _read(self) -> None: + try: + while True: + line = await self.process.readline() + if not line: + detail = await self.process.death_note() + self._fail(detail) + self.events.put_nowait({"type": CRASHED, "detail": detail}) + return + try: + record = json.loads(line) + except json.JSONDecodeError: + continue # stdout is protocol only; tolerate noise + if not isinstance(record, dict): + continue + kind = record.get("type") + if kind == "response": + self._resolve(record) + elif kind == "extension_ui_request": + task = asyncio.create_task(self._on_dialog(self, record)) + self._dialogs.add(task) + task.add_done_callback(self._dialogs.discard) + if record.get("method") in DIALOGS: + self._track(str(record.get("id")), task) + else: + if kind == "agent_start": + self.runs_started += 1 + self.last_start_settled = self.settled_count + elif kind == "agent_settled": + self.settled_count += 1 + self.events.put_nowait(record) + except asyncio.CancelledError: + raise + except Exception as exc: + self._fail(str(exc)) + self.events.put_nowait({"type": CRASHED, "detail": str(exc)}) + + def _resolve(self, record: dict[str, Any]) -> None: + future = self._waiters.get(str(record.get("id"))) + if future is None or future.done(): + return + if record.get("success") is False: + future.set_exception(_CommandError(str(record.get("error") or ""))) + else: + future.set_result(record.get("data")) + + +async def _prompt_command(prompt: _adapter.Prompt) -> dict[str, Any]: + """Return a prompt as pi's `prompt` command: text, and images as base64.""" + texts: list[str] = [] + images: list[dict[str, Any]] = [] + for part in prompt: + if isinstance(part, messages_.TextPart): + texts.append(part.text) + elif part.media_type.startswith("text/"): + texts.append(await _convert.as_text(part)) + else: + images.append( + { + "type": "image", + "data": base64.b64encode(await _convert.data(part)).decode( + "ascii" + ), + "mimeType": part.media_type, + } + ) + command: dict[str, Any] = {"type": "prompt", "message": "\n\n".join(texts)} + if images: + command["images"] = images + return command + + +def _stream_events( + update: dict[str, Any], + message: str, + open_blocks: dict[str, str], + started: set[str], +) -> list[events_.Event]: + """One `assistantMessageEvent` -> events. + + Block ids are `.`: pi numbers content blocks per + assistant message, and a turn holds several. Tool-call arguments travel + as ONE delta, the final arguments, at `toolcall_end`: streamed fragments + are not guaranteed to add up to what pi settles on. + """ + kind = update.get("type") or "" + block = f"{message}.{update.get('contentIndex', 0)}" + out: list[events_.Event] = [] + if kind == "text_start": + open_blocks[block] = "text" + out.append(events_.TextStart(block_id=block)) + elif kind == "text_delta" and update.get("delta"): + out.append(events_.TextDelta(chunk=update["delta"], block_id=block)) + elif kind == "thinking_start": + open_blocks[block] = "thinking" + out.append(events_.ReasoningStart(block_id=block)) + elif kind == "thinking_delta" and update.get("delta"): + out.append( + events_.ReasoningDelta(chunk=update["delta"], block_id=block) + ) + elif kind in ("text_end", "thinking_end"): + out += _close_blocks(open_blocks, only=block) + elif kind == "toolcall_start" and update.get("id"): + started.add(update["id"]) + out.append( + events_.BuiltinToolStart( + tool_call_id=update["id"], + tool_name=update.get("toolName") or "", + ) + ) + elif kind == "toolcall_end": + call = _tool_call(update.get("toolCall") or {}) + out += _convert.builtin_call( + call.tool_call_id, call.tool_name, call.tool_args, started=started + ) + return out + + +def _unstreamed( + content: Any, message: str, streamed: set[str], started: set[str] +) -> list[events_.Event]: + """Return the events of a finished message's unstreamed blocks.""" + out: list[events_.Event] = [] + blocks = content if isinstance(content, list) else [] + for index, block in enumerate(blocks): + if not isinstance(block, dict): + continue + block_id = f"{message}.{index}" + kind = block.get("type") + if kind == "text" and block.get("text") and block_id not in streamed: + out += [ + events_.TextStart(block_id=block_id), + events_.TextDelta(chunk=block["text"], block_id=block_id), + events_.TextEnd(block_id=block_id), + ] + elif ( + kind == "thinking" + and block.get("thinking") + and block_id not in streamed + ): + out += [ + events_.ReasoningStart(block_id=block_id), + events_.ReasoningDelta( + chunk=block["thinking"], block_id=block_id + ), + events_.ReasoningEnd(block_id=block_id), + ] + elif kind == "toolCall" and str(block.get("id")) not in started: + call = _tool_call(block) + out += _convert.builtin_call( + call.tool_call_id, + call.tool_name, + call.tool_args, + started=started, + ) + return out + + +def _close_blocks( + open_blocks: dict[str, str], only: str | None = None +) -> list[events_.Event]: + """End the text and reasoning blocks still open (an aborted message's).""" + out: list[events_.Event] = [] + for block in [only] if only is not None else list(open_blocks): + opened = open_blocks.pop(block, None) + if opened == "text": + out.append(events_.TextEnd(block_id=block)) + elif opened == "thinking": + out.append(events_.ReasoningEnd(block_id=block)) + return out + + +def _tool_call(block: dict[str, Any]) -> messages_.ToolCallPart: + return messages_.ToolCallPart( + tool_call_id=str(block.get("id") or ""), + tool_name=str(block.get("name") or ""), + tool_args=json.dumps(block.get("arguments") or {}), + ) + + +def _assistant_parts(content: Any) -> list[messages_.Part]: + parts: list[messages_.Part] = [] + for block in content if isinstance(content, list) else []: + if not isinstance(block, dict): + continue + kind = block.get("type") + if kind == "text" and block.get("text"): + parts.append(messages_.TextPart(text=block["text"])) + elif kind == "thinking" and block.get("thinking"): + parts.append(messages_.ReasoningPart(text=block["thinking"])) + elif kind == "toolCall": + call = _tool_call(block) + parts.append( + messages_.BuiltinToolCallPart( + tool_call_id=call.tool_call_id, + tool_name=call.tool_name, + tool_args=call.tool_args, + ) + ) + return parts + + +def _content_parts(content: Any) -> list[messages_.Part]: + """Return a user message's parts: from a string, or text and images.""" + if isinstance(content, str): + return [messages_.TextPart(text=content)] if content else [] + parts: list[messages_.Part] = [] + for block in content if isinstance(content, list) else []: + if not isinstance(block, dict): + continue + if block.get("type") == "text" and block.get("text"): + parts.append(messages_.TextPart(text=block["text"])) + elif block.get("type") == "image" and block.get("data"): + parts.append( + messages_.FilePart( + data=str(block["data"]), + media_type=str(block.get("mimeType") or "image/png"), + ) + ) + return parts + + +def _tool_result(result: Any) -> Any: + """Return what a tool returned: its text, when that is all it is. + + pi tools return content blocks; text-only content (nearly every call) + reads as the string it is, anything else stays the blocks themselves. + """ + content = result.get("content") if isinstance(result, dict) else result + if isinstance(content, list) and all( + isinstance(b, dict) and b.get("type") == "text" for b in content + ): + content = "".join(b.get("text") or "" for b in content) + return content + + +def _active_branch(text: str) -> list[dict[str, Any]]: + """Return the session file's active branch: root to latest entry. + + A session is a tree (`id`/`parentId`); the leaf is the entry appended + last, and abandoned branches are not part of the conversation. + """ + entries: dict[str, dict[str, Any]] = {} + leaf: str | None = None + for line in text.splitlines(): + try: + entry = json.loads(line) + except json.JSONDecodeError: + continue + if ( + isinstance(entry, dict) + and entry.get("id") + and entry.get("type") != "session" + ): + entries[str(entry["id"])] = entry + leaf = str(entry["id"]) + path: list[dict[str, Any]] = [] + seen: set[str] = set() + while leaf is not None and leaf in entries and leaf not in seen: + seen.add(leaf) + path.append(entries[leaf]) + parent = entries[leaf].get("parentId") + leaf = str(parent) if parent is not None else None + return list(reversed(path)) + + +def _read(entries: list[dict[str, Any]]) -> list[messages_.Message]: + """Read session entries as messages, like a live turn's. + + The CLI's tools are built-in parts. pi keeps a tool result as a message + of its own (`toolResult`); here it joins the assistant message of its + call. + """ + out: list[messages_.Message] = [] + calls: dict[str, tuple[messages_.Message, messages_.BuiltinToolCallPart]] + calls = {} + for entry in entries: + message = entry.get("message") or {} + if entry.get("type") == "message" and message.get("role") == ( + "toolResult" + ): + found = calls.get(str(message.get("toolCallId") or "")) + if found is None: + continue # a result without its call: nothing to join + owner, call = found + owner.parts.append( + messages_.BuiltinToolReturnPart( + tool_call_id=call.tool_call_id, + tool_name=str(message.get("toolName") or call.tool_name), + result=_tool_result(message), + is_error=bool(message.get("isError")), + ) + ) + continue + for found_message in _stored_to_messages(entry): + out.append(found_message) + for part in found_message.parts: + if isinstance(part, messages_.BuiltinToolCallPart): + calls[part.tool_call_id] = (found_message, part) + return out + + +def _stored_to_messages(entry: dict[str, Any]) -> list[messages_.Message]: + """One session entry -> messages. A tool result is `_read`'s to join. + + Everything pi sends the model is kept: what an extension injected + (`custom_message`) and a `!` command's output (`bashExecution`) reach it + as user messages, and so they are user messages here; a branch summary + is the context pi carried over from an abandoned branch. + """ + kind = entry.get("type") + if kind == "custom_message": + parts = _content_parts(entry.get("content")) + return [messages_.Message(role="user", parts=parts)] if parts else [] + if kind == "branch_summary" and entry.get("summary"): + text = str(entry["summary"]) + return [ + messages_.Message( + role="user", parts=[messages_.TextPart(text=text)] + ) + ] + if kind != "message": + return [] + message = entry.get("message") or {} + role = message.get("role") + if role in ("custom", "user"): + parts = _content_parts(message.get("content")) + return [messages_.Message(role="user", parts=parts)] if parts else [] + if role == "bashExecution" and not message.get("excludeFromContext"): + # pi's own rendering of it for the model. + text = ( + f"Ran `{message.get('command', '')}`\n```\n" + f"{message.get('output', '')}\n```" + ) + return [ + messages_.Message( + role="user", parts=[messages_.TextPart(text=text)] + ) + ] + if role == "assistant": + parts = _assistant_parts(message.get("content")) + if not parts: + return [] + return [ + messages_.Message( + role="assistant", + parts=parts, + provider_metadata=_written_by(message), + ) + ] + return [] + + +def _written_by(message: dict[str, Any]) -> dict[str, Any] | None: + """Which provider and model wrote an assistant message, as pi says. + + Kept on the message (`provider_metadata["pi"]`) so a conversation + seeded into another pi continues on the model it was on. + """ + written = { + k: message[k] + for k in ("api", "provider", "model", "thinkingLevel") + if isinstance(message.get(k), str) + } + if not written or written.get("provider") == "ai-python": + return None + return {KIND: written} + + +def _usage(raw: dict[str, Any]) -> usage_.Usage: + """Return pi's per-message usage. pi's `input` excludes cached input.""" + + def count(name: str) -> int: + value = raw.get(name) + return value if isinstance(value, int) else 0 + + reasoning = raw.get("reasoning") + return usage_.Usage( + input_tokens=count("input") + count("cacheRead") + count("cacheWrite"), + output_tokens=count("output"), + cache_read_tokens=count("cacheRead"), + cache_write_tokens=count("cacheWrite"), + reasoning_tokens=reasoning if isinstance(reasoning, int) else None, + ) + + +def mcp_config(servers: dict[str, Any]) -> dict[str, Any]: + """MCP servers, in the shape claude takes, as pi registers them. + + pi validates the config, so only the keys it knows are passed. + """ + keys = ("command", "args", "env", "cwd", "url", "headers") + return { + name: {k: server[k] for k in keys if server.get(k) is not None} + for name, server in servers.items() + } + + +def _setting(path: pathlib.Path) -> str | None: + """Return the `sessionDir` a pi settings file names, if any.""" + try: + value = json.loads(path.read_text()).get("sessionDir") + except Exception: + return None + return value if isinstance(value, str) and value else None + + +def _describe( + path: pathlib.Path, cwds: tuple[str, ...], *, titles: bool +) -> dict[str, Any] | None: + """Describe one session file of this directory, or None. + + A session file can come from anyone (a project's settings choose the + directory), and its id becomes a CLI argument: one that breaks pi's + rule is not a session. + """ + with path.open() as f: + header = json.loads(f.readline() or "{}") + if header.get("type") != "session" or not SESSION_ID.match( + str(header.get("id") or "") + ): + return None + if header.get("cwd") not in cwds: + return None + created: int | None = None + with contextlib.suppress(ValueError): + when = datetime.datetime.strptime( + str(header.get("timestamp") or "")[:19], "%Y-%m-%dT%H:%M:%S" + ).replace(tzinfo=datetime.UTC) + created = int(when.timestamp() * 1000) + info: dict[str, Any] = { + "id": header["id"], + "path": str(path), + "cwd": header.get("cwd"), + "created": created, + "updated": int(path.stat().st_mtime * 1000), + } + if not titles: + return info + name: str | None = None + first: str | None = None + for line in f: + try: + entry = json.loads(line) + except ValueError: + continue + if entry.get("type") == "session_info": + name = entry.get("name") or None + elif first is None and entry.get("type") == "message": + message = entry.get("message") or {} + if message.get("role") == "user": + content = message.get("content") + if isinstance(content, list): + content = " ".join( + b.get("text", "") + for b in content + if isinstance(b, dict) and b.get("type") == "text" + ) + first = (content or "").strip()[:200] or None + info["title"] = name or first + return info diff --git a/tests/agents/test_hooks.py b/tests/agents/test_hooks.py index 2f449f36..af235e49 100644 --- a/tests/agents/test_hooks.py +++ b/tests/agents/test_hooks.py @@ -10,6 +10,7 @@ import pytest import ai +from ai.agents import runtime from ai.types import events as agent_events_ from ..conftest import MOCK_MODEL, Recorder, mock_llm, text_msg @@ -137,6 +138,87 @@ async def loop( assert resolved_value.approved is True +# -- Hooks outside Agent ----------------------------------------------------- + + +class QueueRuntime(runtime.Runtime): + def __init__(self) -> None: + super().__init__() + self.events: asyncio.Queue[agent_events_.AgentEvent] = asyncio.Queue() + + async def put_event(self, event: agent_events_.AgentEvent) -> None: + await self.events.put(event) + + +@pytest.mark.parametrize("cancel", [False, True]) +async def test_hook_outside_agent(cancel: bool) -> None: + reg = ai.HookRegistry() + rt = QueueRuntime() + with pytest.raises(LookupError): + runtime.get_runtime() + with pytest.raises(LookupError): + ai.agents.hooks.get_hook_registry() + + async with asyncio.TaskGroup() as tasks: + task = tasks.create_task( + ai.hook( + "approval", + payload=Confirmation, + metadata={"tool": "write_file"}, + tool_call_id="call_1", + registry=reg, + runtime=rt, + ) + ) + pending = await rt.events.get() + assert isinstance(pending, agent_events_.HookEvent) + assert pending.hook.hook_id == "approval" + assert pending.hook.hook_type == "Confirmation" + assert pending.hook.status == "pending" + assert pending.hook.metadata == {"tool": "write_file"} + assert pending.hook.tool_call_id == "call_1" + assert not task.done() + assert reg._live_hooks["approval"][2] is rt + + if cancel: + await ai.cancel_hook(pending.hook, reason="denied", registry=reg) + with pytest.raises(asyncio.CancelledError, match="denied"): + await task + else: + ai.resolve_hook(pending.hook, {"approved": True}, registry=reg) + assert await task == Confirmation(approved=True) + + completed = await rt.events.get() + assert isinstance(completed, agent_events_.HookEvent) + assert completed.hook.hook_id == "approval" + assert completed.hook.metadata == {"tool": "write_file"} + if cancel: + assert completed.hook.status == "cancelled" + else: + assert completed.hook.status == "resolved" + assert completed.hook.resolution == {"approved": True} + assert completed.hook.tool_call_id == "call_1" + + assert not reg._live_hooks + assert not reg._pending_resolutions + assert rt.events.empty() + + +async def test_pre_registered_hook_outside_agent() -> None: + reg = ai.HookRegistry() + rt = QueueRuntime() + ai.resolve_hook("approval", {"approved": True}, registry=reg) + + result = await ai.hook( + "approval", payload=Confirmation, registry=reg, runtime=rt + ) + + assert result == Confirmation(approved=True) + assert not reg._live_hooks + assert not reg._pending_resolutions + assert rt.events.empty() + + # -- Explicit HookRegistry --------------------------------------------------- diff --git a/tests/workers/claude_code/test_adapter.py b/tests/workers/claude_code/test_adapter.py index 85788f51..6a229041 100644 --- a/tests/workers/claude_code/test_adapter.py +++ b/tests/workers/claude_code/test_adapter.py @@ -1,4 +1,4 @@ -"""The claude adapter against a scripted claude-agent-sdk client, offline.""" +"""The Claude worker against a scripted claude-agent-sdk client, offline.""" from __future__ import annotations @@ -6,16 +6,21 @@ 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.claude_code import adapter as adapter_ # 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: @@ -98,9 +103,10 @@ def __init__(self, *replies: list[Any]) -> None: async def query(self, prompt: Any) -> None: self.queries.append(prompt) - async def receive_response(self) -> AsyncIterator[Any]: - for message in self.replies.pop(0): - yield message + 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 @@ -109,30 +115,23 @@ async def disconnect(self) -> None: pass -def _adapter(tmp_path: Path, **options: Any) -> adapter_.ClaudeAdapter: - return adapter_.ClaudeAdapter( +def _worker(tmp_path: Path, **options: Any) -> workers.ClaudeCode: + return workers.ClaudeCode( cwd=str(tmp_path), env={"CLAUDE_CONFIG_DIR": str(tmp_path / "config")}, - executable="claude", - model=options.get("model"), - effort=None, - mcp_servers=options.get("mcp_servers", {}), - approve=None, - allowed_tools=None, - disallowed_tools=None, - max_turns=None, + **options, ) -async def _turn(adapter: adapter_.ClaudeAdapter, *prompt: Any) -> list[Any]: +async def _turn(worker: workers.ClaudeCode, *prompt: Any) -> list[Any]: async with asyncio.timeout(5): - return [e async for e in adapter.turn(list(prompt))] + 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: - adapter = _adapter(tmp_path) - adapter._client = Client(TURN) - seen = await _turn(adapter, m.TextPart(text="what is here?")) + 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", @@ -147,7 +146,7 @@ async def test_a_turn_streams_in_the_model_view(tmp_path: Path) -> None: "TextEnd", "StreamEnd", ] - assert adapter._client.queries == ["what is here?"] + assert worker._client.queries == ["what is here?"] end = seen[-1] assert end.finish_reason == "stop" assert end.usage.input_tokens == 7 @@ -159,11 +158,11 @@ async def test_a_turn_streams_in_the_model_view(tmp_path: Path) -> None: async def test_files_travel_as_base64_blocks(tmp_path: Path) -> None: - adapter = _adapter(tmp_path) - adapter._client = Client([_result()]) + worker = _worker(tmp_path) + worker._client = Client([_result()]) png = m.FilePart(data=b"\x89PNG", media_type="image/png") - await _turn(adapter, m.TextPart(text="look"), png) - (sent,) = adapter._client.queries + 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] == { @@ -177,47 +176,89 @@ async def test_files_travel_as_base64_blocks(tmp_path: Path) -> None: async def test_an_unknown_file_is_refused(tmp_path: Path) -> None: - adapter = _adapter(tmp_path) - adapter._client = Client([_result()]) + 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(adapter, zipped) + await _turn(worker, zipped) async def test_finish_reasons(tmp_path: Path) -> None: - adapter = _adapter(tmp_path) - adapter._client = Client([_result(subtype="error_max_turns")]) - assert (await _turn(adapter, m.TextPart(text="x")))[-1].finish_reason == ( + worker = _worker(tmp_path) + worker._client = Client([_result(subtype="error_max_turns")]) + assert (await _turn(worker, m.TextPart(text="x")))[-1].finish_reason == ( "length" ) - adapter._client = Client( + worker._client = Client( [_result(is_error=True, result="Invalid API key · Please run /login")] ) with pytest.raises(workers.NotAuthenticatedError): - await _turn(adapter, m.TextPart(text="x")) - adapter._client = Client([_result(is_error=True, result="overloaded")]) + 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(adapter, m.TextPart(text="x")) + 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: - adapter = _adapter(tmp_path) + 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()]) - adapter._client = client - adapter._running = True # a turn was running when it was interrupted - await adapter.interrupt() + worker._client = client + worker._running = True # a turn was running when it was interrupted + await worker._cli_interrupt() assert client.interrupted - seen = await _turn(adapter, m.TextPart(text="again")) + 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: - adapter = _adapter(tmp_path) + worker = _worker(tmp_path) seed = [ m.Message(role="user", parts=[m.TextPart(text="earlier")]), m.Message( @@ -233,7 +274,7 @@ async def test_a_seed_is_written_where_the_cli_reads(tmp_path: Path) -> None: ], ), ] - session_id = await adapter._stage(seed) + 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()] @@ -287,7 +328,7 @@ def test_a_stored_result_joins_the_message_of_its_call() -> None: parent_tool_use_id=None, ), ] - history = adapter_._read(records) + history = worker_._read(records) assert [x.role for x in history] == ["user", "assistant"] call, result = history[1].parts assert isinstance(call, m.BuiltinToolCallPart) @@ -296,20 +337,630 @@ def test_a_stored_result_joins_the_message_of_its_call() -> None: def test_the_tui_command(tmp_path: Path) -> None: - adapter = _adapter( + worker = _worker( tmp_path, - model="sonnet", + model_name="sonnet", mcp_servers={ "ai_sdk": {"type": "http", "url": "http://127.0.0.1:1/mcp"}, "docs": {"command": "docs-mcp"}, }, ) - argv, env, minted = adapter.tui_command("abc") + 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 = adapter.tui_command(None) + 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/test_adapter.py b/tests/workers/codex/test_adapter.py index 8f06b630..aba4165c 100644 --- a/tests/workers/codex/test_adapter.py +++ b/tests/workers/codex/test_adapter.py @@ -1,4 +1,4 @@ -"""The codex adapter against a scripted `codex app-server`, offline.""" +"""The Codex worker transport against a scripted `codex app-server`, offline.""" from __future__ import annotations @@ -12,7 +12,7 @@ from ai import workers from ai.types import events from ai.types import messages as m -from ai.workers.codex import adapter as adapter_ +from ai.workers import _adapter from ai.workers.codex import jsonrpc from .. import fakes @@ -97,37 +97,27 @@ def note(method: str, **params: Any) -> dict[str, Any]: ] -def _adapter( - server: AppServer, approve: Any = None, **options: Any -) -> adapter_.CodexAdapter: - adapter = adapter_.CodexAdapter( - cwd=CWD, - env={}, - executable="codex", - model=None, - mcp_servers=options.pop("mcp_servers", {}), - approve=approve, - sandbox=None, - config={}, - ) +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") - adapter._process = cast("Any", server.process) - adapter._peer = peer - adapter._thread = THREAD - peer.start( - adapter._on_notify, adapter._on_request, on_crash=adapter._on_crash - ) - return adapter + 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(adapter: adapter_.CodexAdapter, text: str = "go") -> list[Any]: +async def _turn(worker: workers.Codex, text: str = "go") -> list[Any]: async with asyncio.timeout(5): - return [e async for e in adapter.turn([m.TextPart(text=text)])] + return [e async for e in worker._cli_turn([m.TextPart(text=text)])] async def test_a_turn_streams_in_the_model_view() -> None: - adapter = _adapter(AppServer(TURN)) - seen = await _turn(adapter) + worker = _worker(AppServer(TURN)) + seen = await _turn(worker) assert [type(e).__name__ for e in seen] == [ "StreamStart", "ReasoningStart", @@ -172,7 +162,7 @@ async def test_a_message_that_was_never_streamed_still_arrives() -> None: ), ] ) - seen = await _turn(_adapter(server)) + seen = await _turn(_worker(server)) assert [e.chunk for e in seen if isinstance(e, events.TextDelta)] == [ "PONG" ] @@ -194,7 +184,7 @@ async def test_another_turns_notifications_are_not_this_turns() -> None: ), ] ) - seen = await _turn(_adapter(server)) + seen = await _turn(_worker(server)) assert [type(e).__name__ for e in seen] == ["StreamStart", "StreamEnd"] @@ -206,7 +196,7 @@ async def test_a_failed_turn_without_a_key_is_not_authenticated() -> None: ] ) with pytest.raises(workers.NotAuthenticatedError): - await _turn(_adapter(server)) + await _turn(_worker(server)) @pytest.mark.parametrize("granted", [True, False]) @@ -246,17 +236,17 @@ def complete(message: dict[str, Any]) -> Any: server.on_turn = ask server.process.answer = complete - adapter = _adapter(server, approve) - assert adapter._thread_params()["approvalPolicy"] == "untrusted" - await _turn(adapter) + 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: - adapter = _adapter(AppServer()) - assert adapter._thread_params() == { + worker = _worker(AppServer()) + assert worker._thread_params() == { "sandbox": "danger-full-access", "approvalPolicy": "never", } @@ -264,12 +254,12 @@ async def test_without_a_gate_codex_never_asks() -> None: async def test_an_interrupted_turn_ends_as_cancelled() -> None: server = AppServer() - adapter = _adapter(server) - turn = adapter.turn([m.TextPart(text="go")]) + 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 adapter.interrupt() + await worker._cli_interrupt() seen = await asyncio.wait_for(reader, 5) assert seen[-1].finish_reason == "cancelled" assert server.sent("turn/interrupt")[0]["params"] == { @@ -284,13 +274,13 @@ async def _rest(turn: Any) -> list[Any]: async def test_opening_a_new_thread_seeds_it() -> None: server = AppServer() - adapter = _adapter(server) + worker = _worker(server) seed = [ m.Message(role="user", parts=[m.TextPart(text="earlier")]), m.Message(role="assistant", parts=[m.TextPart(text="answer")]), ] assert ( - await adapter.open( + await worker._cli_open( session_id=None, fork=False, seed=seed, instructions="Be terse." ) == "new" @@ -305,8 +295,8 @@ async def test_opening_a_new_thread_seeds_it() -> None: async def test_a_fork_is_native() -> None: server = AppServer() - adapter = _adapter(server) - forked = await adapter.open( + worker = _worker(server) + forked = await worker._cli_open( session_id=THREAD, fork=True, seed=None, instructions=None ) assert forked == "new" @@ -316,9 +306,9 @@ async def test_a_fork_is_native() -> None: async def test_a_thread_from_another_directory_is_refused() -> None: server = AppServer() server.threads["elsewhere"] = {"id": "elsewhere", "cwd": "/other"} - adapter = _adapter(server) + worker = _worker(server) with pytest.raises(workers.WorkerError, match="/other"): - await adapter.open( + await worker._cli_open( session_id="elsewhere", fork=False, seed=None, instructions=None ) @@ -337,7 +327,7 @@ async def test_history_has_the_cli_tools_as_builtin_parts() -> None: ] } ] - history = await _adapter(server).history(THREAD) + 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) @@ -364,22 +354,350 @@ def answer(message: dict[str, Any]) -> Any: return {"data": [thread], "nextCursor": cursor} server.process.answer = answer - infos = await _adapter(server).list_sessions() + 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"] -async def test_the_tui_gets_no_bridge() -> None: - adapter = _adapter( - AppServer(), +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 = adapter.tui_command(THREAD) + 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/fakes.py b/tests/workers/fakes.py index 200e8525..6196bd89 100644 --- a/tests/workers/fakes.py +++ b/tests/workers/fakes.py @@ -81,6 +81,7 @@ def __init__( 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" @@ -105,51 +106,69 @@ async def open( } ) if fork: - return f"{session_id}-fork" - return session_id or "s1" + fork_id = f"{session_id}-fork" + self.stored[fork_id] = await self.history(session_id or "") + return fork_id + opened = session_id or "s1" + if seed is not None: + self.stored[opened] = [ + message.model_copy(deep=True) for message in seed + ] + return opened async def turn( self, prompt: _adapter.Prompt ) -> AsyncIterator[events.Event]: self.turns.append(_convert.text_of(prompt)) self._resume.clear() - yield events.StreamStart() - for step in self.script(_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 + self.running = True + try: + yield events.StreamStart() + for step in self.script(_convert.text_of(prompt)): + if isinstance(step, Pause): + await self._resume.wait() + yield events.StreamEnd(finish_reason="cancelled") + return + if isinstance(step, Run): + await step.fn() + elif isinstance(step, Ask): + assert self.approve is not None + self.answers.append( + await self.approve( + step.tool_call_id, step.tool_name, step.tool_input + ) ) - ) - else: - yield step - yield events.StreamEnd( - finish_reason="stop", - usage=usage_.Usage(input_tokens=3, output_tokens=2), - ) - - async def steer(self, text: str) -> None: - self.steers.append(text) + else: + yield step + yield events.StreamEnd( + finish_reason="stop", + usage=usage_.Usage(input_tokens=3, output_tokens=2), + ) + finally: + self.running = False + + async def send_running(self, prompt: _adapter.Prompt) -> bool: + if not self.running: + return False + self.steers.append(_convert.text_of(prompt)) + return True async def interrupt(self) -> None: self.interrupts += 1 self._resume.set() async def history(self, session_id: str) -> list[m.Message]: - return self.stored.get(session_id, []) + return [ + message.model_copy(deep=True) + for message in self.stored.get(session_id, []) + ] async def list_sessions(self) -> list[_adapter.SessionInfo]: return [_adapter.SessionInfo(session_id="s1", title="first")] + @staticmethod def tui_command( - self, session_id: str | None + session_id: str | None, ) -> tuple[list[str], dict[str, str], str | None]: return ( [sys.executable, "-c", "pass"], @@ -161,21 +180,65 @@ def tui_command( class FakeWorker(workers.Worker): """A worker whose CLI is a `FakeAdapter`, run by a script.""" - kind: Literal["fake"] = "fake" + worker_class_id: Literal["fake"] = "fake" _script: Script = pydantic.PrivateAttr(default_factory=lambda: reply) _fake: FakeAdapter | None = pydantic.PrivateAttr(default=None) _servers: dict[str, dict[str, Any]] = pydantic.PrivateAttr( default_factory=dict ) - def _make_adapter( - self, - mcp_servers: dict[str, dict[str, Any]], - approve: _adapter.Approve | None, - ) -> _adapter.CLIAdapter: - self._fake = FakeAdapter(self._run, approve) + async def _cli_start(self, mcp_servers: dict[str, dict[str, Any]]) -> None: + self._fake = FakeAdapter( + self._run, self._approve if self.approve else None + ) self._servers = mcp_servers - return self._fake + # A resumed/native-forked fake has the serialized mirror in its store. + # History reads and forks must not alias the stored messages. + if self.session_id is not None: + self.fake.stored[self.session_id] = [ + message.model_copy(deep=True) for message in self.messages + ] + await self.fake.start() + self._cli_version = self.fake.version + + async def _cli_close(self) -> None: + if self._fake is not None: + await self.fake.close() + + async def _cli_open( + self, + *, + session_id: str | None, + fork: bool, + seed: list[m.Message] | None, + instructions: str | None, + ) -> str: + return await self.fake.open( + session_id=session_id, + fork=fork, + seed=seed, + instructions=instructions, + ) + + def _cli_turn(self, prompt: _adapter.Prompt) -> AsyncIterator[events.Event]: + return self.fake.turn(prompt) + + async def _cli_send_running(self, prompt: _adapter.Prompt) -> bool: + return await self.fake.send_running(prompt) + + async def _cli_interrupt(self) -> None: + await self.fake.interrupt() + + async def _cli_history(self, session_id: str) -> list[m.Message]: + return await self.fake.history(session_id) + + async def _cli_list_sessions(self) -> list[_adapter.SessionInfo]: + return await self.fake.list_sessions() + + def _cli_tui_command( + self, session_id: str | None + ) -> tuple[list[str], dict[str, str], str | None]: + return FakeAdapter.tui_command(session_id) def _run(self, prompt: str) -> Iterable[Step]: return self._script(prompt) diff --git a/tests/workers/pi/test_adapter.py b/tests/workers/pi/test_adapter.py index 191c013f..fe8ee0ce 100644 --- a/tests/workers/pi/test_adapter.py +++ b/tests/workers/pi/test_adapter.py @@ -1,4 +1,4 @@ -"""The pi adapter against a scripted `pi --mode rpc`, offline. +"""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. """ @@ -16,7 +16,7 @@ from ai import workers from ai.types import events from ai.types import messages as m -from ai.workers.pi import adapter as adapter_ +from ai.workers.pi import worker as worker_ from .. import fakes @@ -107,8 +107,13 @@ def __init__( 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: @@ -127,6 +132,7 @@ def answer(self, message: dict[str, Any]) -> None: 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() @@ -137,7 +143,17 @@ def answer(self, message: dict[str, Any]) -> None: self.says({"type": "agent_settled", "aborted": True}) self.respond(message, success=True) elif kind == "get_state": - self.respond(message, success=True, data={"sessionId": SID}) + 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) @@ -145,40 +161,31 @@ def sent(self, kind: str) -> list[dict[str, Any]]: return [w for w in self.process.written if w.get("type") == kind] -def _adapter( +def _worker( server: Pi | None = None, approve: Any = None, cwd: str = "/w", **env: str -) -> adapter_.PiAdapter: - adapter = adapter_.PiAdapter( - cwd=cwd, - env=env, - executable="pi", - model=None, - effort=None, - mcp_servers={}, - approve=approve, - allowed_tools=None, - disallowed_tools=None, - ) +) -> worker_.Pi: + worker = worker_.Pi(cwd=cwd, env=env, approve=approve is not None) + worker._approval_callback = approve if server is not None: - agent = adapter_._Agent( - cast("Any", server.process), on_dialog=adapter._on_dialog + agent = worker_._Agent( + cast("Any", server.process), on_dialog=worker._on_dialog ) agent.start() - adapter._agent = agent - return adapter + worker._agent = agent + return worker -async def _turn(adapter: adapter_.PiAdapter, *prompt: Any) -> list[Any]: +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 adapter.turn(parts)] + 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(_adapter(server), m.TextPart(text="say done")) + seen = await _turn(_worker(server), m.TextPart(text="say done")) assert [type(e).__name__ for e in seen] == [ "StreamStart", "ReasoningStart", @@ -215,7 +222,7 @@ async def test_a_turn_streams_in_the_model_view() -> None: async def test_images_travel_as_base64() -> None: server = Pi() png = m.FilePart(data=b"\x89PNG", media_type="image/png") - await _turn(_adapter(server), m.TextPart(text="look"), png) + await _turn(_worker(server), m.TextPart(text="look"), png) assert server.sent("prompt")[0]["images"] == [ {"type": "image", "data": "iVBORw==", "mimeType": "image/png"} ] @@ -225,7 +232,7 @@ 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(_adapter(server)) + await _turn(_worker(server)) async def test_a_failed_model_call_fails_the_turn() -> None: @@ -242,7 +249,7 @@ async def test_a_failed_model_call_fails_the_turn() -> None: ] ) with pytest.raises(workers.WorkerError, match="overloaded"): - await _turn(_adapter(server)) + await _turn(_worker(server)) def _ask(server: Pi) -> None: @@ -251,7 +258,7 @@ def _ask(server: Pi) -> None: "type": "extension_ui_request", "id": "ui-1", "method": "input", - "title": adapter_.APPROVE, + "title": worker_.APPROVE, "placeholder": json.dumps( { "toolCallId": "toolu_1", @@ -283,7 +290,7 @@ def answer(message: dict[str, Any]) -> None: server.on_prompt = lambda: _ask(server) server.process.answer = answer - seen = await _turn(_adapter(server, approve)) + 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" @@ -298,13 +305,13 @@ def answer(message: dict[str, Any]) -> None: async def test_another_extensions_dialog_is_dismissed() -> None: """Nobody is at a terminal to answer it; the agent must not wait.""" server = Pi() - adapter = _adapter(server) - assert adapter._agent is not None - await adapter._on_dialog( - adapter._agent, {"id": "x", "method": "confirm", "title": "Clear?"} + worker = _worker(server) + assert worker._agent is not None + await worker._on_dialog( + worker._agent, {"id": "x", "method": "confirm", "title": "Clear?"} ) - await adapter._on_dialog( - adapter._agent, {"id": "y", "method": "notify", "message": "hello"} + 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} @@ -313,11 +320,11 @@ async def test_another_extensions_dialog_is_dismissed() -> None: async def test_an_interrupted_turn_ends_as_cancelled() -> None: server = Pi([]) - adapter = _adapter(server) - turn = adapter.turn([m.TextPart(text="go")]) + 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 adapter.interrupt() + await worker._cli_interrupt() seen = await asyncio.wait_for(reader, 5) assert seen[-1].finish_reason == "cancelled" @@ -330,10 +337,13 @@ 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(_adapter(server)) + await _turn(_worker(server)) -async def test_a_run_an_extension_command_starts_is_followed() -> None: +@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( @@ -356,12 +366,14 @@ def answer(message: dict[str, Any]) -> None: for record in server.turn: server.says(record) elif message.get("type") == "get_state": - server.respond(message, success=True, data={"isStreaming": True}) + server.respond( + message, success=True, data={"isStreaming": still_streaming} + ) else: Pi.answer(server, message) server.process.answer = answer - seen = await _turn(_adapter(server), m.TextPart(text="/ask PONG")) + seen = await _turn(_worker(server), m.TextPart(text="/ask PONG")) assert [e.chunk for e in seen if isinstance(e, events.TextDelta)] == [ "PONG" ] @@ -381,7 +393,7 @@ def answer(message: dict[str, Any]) -> None: Pi.answer(server, message) server.process.answer = answer - seen = await _turn(_adapter(server), m.TextPart(text="/noop")) + seen = await _turn(_worker(server), m.TextPart(text="/noop")) assert [type(e).__name__ for e in seen] == ["StreamStart", "StreamEnd"] @@ -421,7 +433,7 @@ def test_history_follows_the_active_branch_only() -> None: {"type": "label", "id": "e", "parentId": "d"}, ] text = "\n".join(json.dumps(line) for line in lines) - stored = adapter_._read(adapter_._active_branch(text)) + 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) @@ -434,7 +446,7 @@ async def test_a_seed_is_listed_and_read_back(tmp_path: Path) -> None: agent_dir = tmp_path / "agent" project = tmp_path / "project" project.mkdir() - adapter = _adapter(cwd=str(project), PI_CODING_AGENT_DIR=str(agent_dir)) + 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( @@ -455,15 +467,15 @@ async def test_a_seed_is_listed_and_read_back(tmp_path: Path) -> None: m.Message(role="assistant", parts=[m.TextPart(text="It says milk.")]), ] with pytest.warns(UserWarning, match="reasoning"): - session_id = await adapter._stage(seed) - infos = await adapter.list_sessions() + 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 adapter.history(session_id) + 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) @@ -473,7 +485,7 @@ async def test_a_seed_is_listed_and_read_back(tmp_path: Path) -> None: assert result.result == "milk" assert back[2].text == "It says milk." with pytest.raises(workers.WorkerError): - await adapter.history("not-a-session") + await worker._cli_history("not-a-session") async def test_a_seeded_pi_conversation_stays_on_its_model( @@ -485,7 +497,7 @@ async def test_a_seeded_pi_conversation_stays_on_its_model( agent_dir = tmp_path / "agent" project = tmp_path / "project" project.mkdir() - adapter = _adapter(cwd=str(project), PI_CODING_AGENT_DIR=str(agent_dir)) + worker = _worker(cwd=str(project), PI_CODING_AGENT_DIR=str(agent_dir)) stored = { "type": "message", "message": { @@ -498,9 +510,9 @@ async def test_a_seeded_pi_conversation_stays_on_its_model( } seed = [ m.Message(role="user", parts=[m.TextPart(text="hello")]), - *adapter_._stored_to_messages(stored), + *worker_._stored_to_messages(stored), ] - session_id = await adapter._stage(seed) + 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] == [ @@ -522,30 +534,320 @@ async def test_a_seeded_pi_conversation_stays_on_its_model( def test_options_reach_pi_in_its_own_spelling() -> None: - adapter = adapter_.PiAdapter( + worker = worker_.Pi( cwd="/w", env={"K": "v"}, executable="pi", - model="anthropic/claude-sonnet-4.6", + 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=None, + approve=False, allowed_tools=[], disallowed_tools=["bash"], ) - argv, env, minted = adapter.tui_command(None) + argv, env, minted = worker._cli_tui_command(None) assert argv[:3] == ["pi", "--session-id", minted] - assert argv[3:5] == ["-e", adapter_.EXTENSION] + 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[adapter_.CONFIG_VAR]) == { + 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_live.py b/tests/workers/test_live.py index 6c89aa8c..61a8f752 100644 --- a/tests/workers/test_live.py +++ b/tests/workers/test_live.py @@ -1,11 +1,13 @@ -"""Workers against the real CLIs. Opt-in: `uv run pytest -m live tests/workers`. +"""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 cost tokens. +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 @@ -20,43 +22,56 @@ pytestmark = pytest.mark.live -KINDS: dict[str, tuple[str, Callable[..., workers.Worker]]] = { +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(KINDS)) -def kind(request: pytest.FixtureRequest) -> str: - kind = str(request.param) - executable, _ = KINDS[kind] +@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 kind == "claude-code" and not importlib.util.find_spec( + if worker_class_id == "claude-code" and not importlib.util.find_spec( "claude_agent_sdk" ): pytest.skip("claude-agent-sdk is not installed") - return kind + return worker_class_id @pytest.fixture -def make(kind: str, tmp_path: Path) -> Callable[..., workers.Worker]: - """Build a worker of this kind, in a fresh directory.""" - _, cls = KINDS[kind] +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(make: Any) -> None: - async with make() as worker: +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, [ @@ -68,14 +83,52 @@ async def test_a_turn_and_a_resume(make: Any) -> None: 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 = worker.model_copy(update={"fork": True}) + 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, [ @@ -117,9 +170,9 @@ async def lookup_order(order_id: str) -> str: async def test_a_denied_tool_call_does_not_run( - kind: str, make: Any, tmp_path: Path + worker_class_id: str, make: Any, tmp_path: Path ) -> None: - if kind == "codex": + 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." @@ -135,3 +188,29 @@ async def test_a_denied_tool_call_does_not_run( assert pending assert all(h.hook_type == "ToolApproval" for h in pending) assert not (tmp_path / "notes.txt").exists() + + +async def test_direct_approval_outside_agent( + worker_class_id: str, make: Any, tmp_path: Path +) -> None: + if worker_class_id == "codex": + pytest.skip("codex asks only when its own policy escalates") + pending: list[Any] = [] + async with make(approve=True) as worker: + await worker.send( + "Create a file named notes.txt containing hello. Use a tool." + ) + async with contextlib.aclosing(worker.events()) as feed: + async for event in feed: + if isinstance(event, events.PendingHookEvent): + pending.append(event.hook) + ai.resolve_hook( + event.hook, + {"granted": False, "reason": "not allowed here"}, + registry=worker.hook_registry, + ) + elif isinstance(event, events.StreamEnd): + break + assert pending + assert all(h.hook_type == "ToolApproval" for h in pending) + assert not (tmp_path / "notes.txt").exists() diff --git a/tests/workers/test_output.py b/tests/workers/test_output.py new file mode 100644 index 00000000..94cd1de0 --- /dev/null +++ b/tests/workers/test_output.py @@ -0,0 +1,233 @@ +"""Structured model output is a serializable view of the native transcript.""" + +from __future__ import annotations + +import json +from collections.abc import Iterator + +import pydantic +import pytest + +import ai +from ai import workers +from ai.types import events +from ai.types import messages as m + +from . import fakes + + +class Count(pydantic.BaseModel): + n: int + + +@pytest.mark.parametrize("retries", [0, 1, 2]) +@pytest.mark.parametrize("restore", [False, True]) +@pytest.mark.parametrize("native_prefix", [False, True]) +async def test_output_continuation( + retries: int, restore: bool, native_prefix: bool +) -> None: + worker = fakes.FakeWorker() + fields = set(worker.model_dump()) + attempts = 0 + + def script(prompt: str) -> list[fakes.Step]: + nonlocal attempts + attempts += 1 + return fakes.text( + "not JSON" if attempts <= retries else '```json\n{"n": 2}\n```' + ) + + worker.script(script) + first = ai.user_message("count") + async with worker: + async with ai.stream(worker, [first], output_type=Count) as stream: + seen = [event async for event in stream] + assert stream.output == Count(n=2) + assert len(worker.fake.turns) == retries + 1 + native = worker.messages[1] + assert native.id == stream.message.id + assert native is not stream.message + assert native.text == ( + "not JSON" if retries else '```json\n{"n": 2}\n```' + ) + assert native.parts[0].id == "t" + assert stream.message.parts[0].id == "output" + assert {event.message.id for event in seen} == {native.id} + assert len(worker.messages) == 2 + 2 * retries + assert stream.usage is not None + assert stream.usage.input_tokens == 3 * (retries + 1) + assert native.usage is not None and native.usage.input_tokens == 3 + for hidden in worker.messages[2:]: + assert hidden.provider_metadata is not None + assert hidden.provider_metadata["worker"]["model_hidden"] is True + before = worker.model_dump_json() + + if restore: + data = json.loads(before) + assert set(data) == fields + restored = workers.Worker.model_validate(data) + assert isinstance(restored, fakes.FakeWorker) + worker = restored + worker.script(lambda prompt: fakes.text('{"n": 3}')) + # Round-trip the caller's transcript independently, too. + history = ( + list(worker.messages) + if native_prefix + else [ + first, + m.Message.model_validate_json(stream.message.model_dump_json()), + ] + ) + second = ai.user_message("count again") + plan = worker._plan([*history, second]) + assert plan.transcript == [second] + assert plan.prompt == second.parts + async with worker: + async with ai.stream( + worker, [*history, second], output_type=Count + ) as continuation: + _ = [event async for event in continuation] + assert continuation.output == Count(n=3) + assert len(worker.fake.turns) == 1 + assert worker.fake.turns[0].startswith("count again") + assert ( + worker.messages[:-2] + == fakes.FakeWorker.model_validate_json(before).messages + ) + + +async def test_projection_keeps_builtin_parts_and_suppresses_narration() -> ( + None +): + worker = fakes.FakeWorker() + worker.script( + lambda prompt: [ + *fakes.text("Let me look."), + *fakes.tool("read", "Read", '{"path":"a.py"}', "contents"), + *fakes.text('{"n": 2}', block="answer"), + ] + ) + first = ai.user_message("count") + async with worker: + seen = [ + event async for event in worker.stream([first], output_type=Count) + ] + native = worker.messages[1] + projected = seen[-1].message + assert projected is not native + assert {event.message.id for event in seen} == {native.id} + assert all(event.message is projected for event in seen) + assert projected.text == '{"n":2}' + assert native.text == 'Let me look.{"n": 2}' + assert [part.kind for part in projected.parts] == [ + "builtin_tool_call", + "builtin_tool_return", + "text", + ] + assert projected.builtin_tool_calls == native.builtin_tool_calls + assert projected.builtin_tool_returns == native.builtin_tool_returns + metadata = native.provider_metadata + assert metadata is not None + assert ( + metadata["worker"]["model_parts"] + == projected.model_dump(mode="json")["parts"] + ) + next_message = ai.user_message("again") + assert worker._plan([first, projected, next_message]).transcript == [ + next_message + ] + + +@pytest.mark.parametrize("native_prefix", [False, True]) +@pytest.mark.parametrize("change", ["id", "role", "text", "part_id", "omit"]) +async def test_changed_output_history_is_rejected( + native_prefix: bool, change: str +) -> None: + worker = fakes.FakeWorker() + worker.script(lambda prompt: fakes.text('{"n": 2}')) + first = ai.user_message("count") + async with worker: + async with ai.stream(worker, [first], output_type=Count) as stream: + _ = [event async for event in stream] + history = [ + message.model_copy(deep=True) + for message in ( + worker.messages if native_prefix else [first, stream.message] + ) + ] + answer = history[-1] + if change == "id": + answer.id = "changed" + elif change == "role": + answer.role = "user" + elif change == "text": + assert isinstance(answer.parts[0], m.TextPart) + answer.parts[0].text = '{"n":999}' + elif change == "part_id": + assert isinstance(answer.parts[0], m.TextPart) + answer.parts[0].id = "changed" + else: + history.pop() + with pytest.raises(workers.TranscriptMismatchError): + async with ai.stream( + worker, [*history, ai.user_message("again")] + ) as continuation: + _ = [event async for event in continuation] + assert len(worker.fake.turns) == 1 + + +async def test_agent_output_tool_loop_with_narration() -> None: + worker = fakes.FakeWorker() + ran: list[int] = [] + answers: list[tuple[str, bool]] = [] + + @ai.tool + async def count(n: int) -> int: + """Return the count.""" + ran.append(n) + return n + + async def call() -> None: + answers.append(await worker._on_call("count", {"n": 2})) + + def script(prompt: str) -> Iterator[fakes.Step]: + yield from fakes.text("I will count with a tool.") + yield from fakes.tool("read", "Read") + yield fakes.Run(call) + yield from fakes.text('{"n": 2}') + + worker.script(script) + async with worker: + async with ai.Agent(tools=[count]).run( + worker, [ai.user_message("count")], output_type=Count + ) as run: + seen = [event async for event in run] + assert run.output == Count(n=2) + assert ran == [2] + assert answers == [("2", False)] + assert len(worker.fake.turns) == 1 + assert [message.role for message in run.messages] == [ + "user", + "assistant", + "tool", + "assistant", + ] + tool_message = run.messages[1] + assert tool_message.text == "" + assert [part.kind for part in tool_message.parts] == [ + "builtin_tool_call", + "builtin_tool_return", + "tool_call", + ] + assert worker.messages[1].text == "I will count with a tool." + assert worker.messages[1].id == tool_message.id + assert not any( + isinstance(event, events.TextDelta) and "I will" in event.chunk + for event in seen + ) + worker.script(lambda prompt: fakes.text('{"n": 3}')) + async with ai.stream( + worker, [*run.messages, ai.user_message("again")], output_type=Count + ) as continuation: + _ = [event async for event in continuation] + assert continuation.output == Count(n=3) diff --git a/tests/workers/test_session_sync.py b/tests/workers/test_session_sync.py new file mode 100644 index 00000000..4e8b9e00 --- /dev/null +++ b/tests/workers/test_session_sync.py @@ -0,0 +1,49 @@ +"""Switching from direct input to model use must not replay queued output.""" + +import contextlib + +import pytest + +import ai +from ai import workers +from ai.types import events + +from . import fakes + + +async def test_model_use_refuses_unread_direct_output() -> None: + async with fakes.FakeWorker() as worker: + await worker.send("one") + with pytest.raises(workers.WorkerError, match="unread session events"): + await ai.experimental_generate(worker, [ai.user_message("two")]) + assert worker.fake.turns == ["one"] + async with contextlib.aclosing(worker.events()) as feed: + async for event in feed: + if isinstance(event, events.StreamEnd): + break + answer = await ai.experimental_generate( + worker, [*worker.messages, ai.user_message("two")] + ) + assert answer.text == "two" + + +async def test_sync_replaces_unread_output_with_native_history() -> None: + async with fakes.FakeWorker() as worker: + await worker.send("one") + assert worker._runtime is not None + assert worker._runtime.pump is not None + await worker._runtime.pump + stored = [ai.user_message("one"), ai.assistant_message("native one")] + worker.fake.stored["s1"] = stored + await worker.sync() + assert worker.messages == stored + answer = await ai.experimental_generate( + worker, [*worker.messages, ai.user_message("two")] + ) + assert answer.text == "two" + assert [message.text for message in worker.messages] == [ + "one", + "native one", + "two", + "two", + ] diff --git a/tests/workers/test_worker.py b/tests/workers/test_worker.py index 299cf600..70409e71 100644 --- a/tests/workers/test_worker.py +++ b/tests/workers/test_worker.py @@ -3,8 +3,9 @@ from __future__ import annotations import asyncio +import contextlib import json -from collections.abc import Iterator +from collections.abc import AsyncIterator, Iterator from typing import Any import pydantic @@ -14,7 +15,7 @@ from ai import workers from ai.types import events from ai.types import messages as m -from ai.workers import _bridge +from ai.workers import _adapter, _bridge from . import fakes @@ -111,7 +112,7 @@ async def test_a_cancelled_turn_ends_as_other(worker: fakes.FakeWorker) -> None: async for event in stream: seen.append(event) if isinstance(event, events.TextEnd): - await worker.fake.interrupt() + await worker.interrupt() end = seen[-1] assert isinstance(end, events.StreamEnd) assert end.finish_reason == "other" @@ -180,21 +181,59 @@ async def test_a_rewritten_past_is_refused(worker: fakes.FakeWorker) -> None: await ai.experimental_generate(worker, [ai.user_message("other")]) -async def test_a_failed_call_can_be_sent_again( +async def test_failure_after_acceptance_keeps_the_accepted_user( worker: fakes.FakeWorker, ) -> None: def boom(prompt: str) -> list[fakes.Step]: raise RuntimeError("boom") worker.script(boom) - messages = [ai.user_message("one")] + message = ai.user_message("one") async with worker: with pytest.raises(RuntimeError, match="boom"): - await ai.experimental_generate(worker, messages) - assert worker.messages == [] + await ai.experimental_generate(worker, [message]) + assert worker.messages[0] == message + assert [x.role for x in worker.messages] == ["user", "assistant"] + assert worker.messages[1].parts == [] worker.script(fakes.reply) - again = await ai.experimental_generate(worker, messages) + with pytest.raises(ValueError, match="no new user message"): + await ai.experimental_generate(worker, list(worker.messages)) + again = await ai.experimental_generate( + worker, [*worker.messages, ai.user_message("two")] + ) + assert worker.fake.turns == ["one", "two"] + assert again.text == "two" + assert sum(x.id == message.id for x in worker.messages) == 1 + + +async def test_failure_before_acceptance_can_be_retried( + worker: fakes.FakeWorker, monkeypatch: pytest.MonkeyPatch +) -> None: + turn = fakes.FakeAdapter.turn + reject = True + + async def sometimes_reject( + adapter: fakes.FakeAdapter, prompt: _adapter.Prompt + ) -> AsyncIterator[events.Event]: + if reject: + raise RuntimeError("not accepted") + async for event in turn(adapter, prompt): + yield event + + monkeypatch.setattr(fakes.FakeAdapter, "turn", sometimes_reject) + message = ai.user_message("one") + async with worker: + with pytest.raises(RuntimeError, match="not accepted"): + await ai.experimental_generate(worker, [message]) + assert worker.messages == [] + assert worker._runtime is not None + assert worker._runtime.stream_owner is None + assert worker._runtime.submission is None + reject = False + again = await ai.experimental_generate(worker, [message]) + assert worker.fake.turns == ["one"] assert again.text == "one" + assert worker.messages[0] == message async def test_walking_away_interrupts_the_turn( @@ -269,9 +308,24 @@ async def test_a_dumped_worker_continues_its_conversation( assert again.fake.turns == ["two"] -async def test_an_unknown_kind_is_refused() -> None: - with pytest.raises(pydantic.ValidationError): - workers.Worker.model_validate({"kind": "nope"}) +async def test_an_unknown_worker_class_is_refused() -> None: + with pytest.raises(pydantic.ValidationError, match="unknown worker class"): + workers.Worker.model_validate({"worker_class_id": "nope"}) + + +def test_worker_identity_and_removed_fields() -> None: + worker = fakes.FakeWorker(model_name="test-model") + assert worker.id == "test-model" + assert worker.worker_class_id == worker.provider_name == "fake" + assert worker.version is None + data = worker.model_dump() + assert data["model_name"] == "test-model" + assert data["worker_class_id"] == "fake" + assert "fork" not in data + assert callable(worker.fork) + for field, value in (("kind", "fake"), ("model", "old"), ("fork", True)): + with pytest.raises(pydantic.ValidationError, match="Extra inputs"): + fakes.FakeWorker.model_validate({field: value}) async def test_resume_by_session_id() -> None: @@ -285,7 +339,7 @@ async def test_resume_by_session_id() -> None: assert worker.session_id == "old" -async def test_load_reads_the_stored_past() -> None: +async def test_sync_reads_the_stored_past() -> None: worker = fakes.FakeWorker(session_id="old") stored = [ ai.user_message("earlier"), @@ -293,33 +347,44 @@ async def test_load_reads_the_stored_past() -> None: ] async with worker: worker.fake.stored["old"] = stored - await worker.load() + await worker.sync() assert worker.messages == stored + assert worker.messages is not stored + assert worker.messages[0] is not stored[0] await ai.experimental_generate( worker, [*worker.messages, ai.user_message("now")] ) assert worker.fake.turns == ["now"] -async def test_a_copy_with_fork_branches_natively( - worker: fakes.FakeWorker, -) -> None: +async def test_fork_branches_natively(worker: fakes.FakeWorker) -> None: async with worker: await ai.experimental_generate(worker, [ai.user_message("one")]) - branch = worker.model_copy(update={"fork": True}) + branch = await worker.fork() async with branch: - assert branch.fake is not worker.fake # a CLI of its own + assert branch.fake is not worker.fake + assert branch.session_id == "s1-fork" + assert branch.messages == worker.messages + assert branch.messages is not worker.messages + assert branch.messages[0] is not worker.messages[0] + assert ( + branch.messages[0].parts[0] is not worker.messages[0].parts[0] + ) + stored = branch.fake.stored["s1-fork"] + assert branch.messages == stored + assert branch.messages[0] is not stored[0] await ai.experimental_generate( branch, [*branch.messages, ai.user_message("two")] ) - assert branch.fake.opens[0] == { - "session_id": "s1", - "fork": True, - "seed": None, - "instructions": None, - } - assert branch.session_id == "s1-fork" - assert branch.fork is False + assert branch.fake.opens == [ + { + "session_id": "s1", + "fork": True, + "seed": None, + "instructions": None, + } + ] + assert branch.fake.turns == ["two"] assert worker.session_id == "s1" assert len(worker.messages) == 2 assert len(branch.messages) == 4 @@ -328,7 +393,7 @@ async def test_a_copy_with_fork_branches_natively( async def test_a_worker_goes_in_a_context(worker: fakes.FakeWorker) -> None: context = ai.Context(model=worker, messages=[], tools=[]) data = json.loads(context.model_dump_json()) - assert data["model"]["kind"] == "fake" + assert data["model"]["worker_class_id"] == "fake" restored = ai.Context.model_validate(data) assert isinstance(restored.model, fakes.FakeWorker) @@ -346,6 +411,188 @@ async def test_close_keeps_the_fields(worker: fakes.FakeWorker) -> None: assert worker.fake.opens[0]["session_id"] == "s1" +@pytest.mark.parametrize("mode", ["resume", "copy", "deepcopy"]) +async def test_resume_and_copy_reset_all_private_state( + worker: fakes.FakeWorker, mode: str +) -> None: + async with worker: + await ai.experimental_generate(worker, [ai.user_message("one")]) + worker.script(lambda prompt: fakes.text("private script")) + if mode == "resume": + restored = workers.Worker.model_validate_json( + worker.model_dump_json() + ) + else: + restored = worker.model_copy(deep=mode == "deepcopy") + assert isinstance(restored, fakes.FakeWorker) + assert restored.model_dump() == worker.model_dump() + assert restored.messages is not worker.messages + assert restored.messages[0].parts[0] is not worker.messages[0].parts[0] + assert restored._runtime is None + assert restored._fake is None + assert restored._servers == {} + assert restored._script is fakes.reply + assert restored.version is None + assert restored._open_lock is not worker._open_lock + async with restored: + assert restored._runtime is not worker._runtime + assert restored.fake is not worker.fake + assert restored.hook_registry is not worker.hook_registry + answer = await ai.experimental_generate( + restored, [*restored.messages, ai.user_message("two")] + ) + assert answer.text == "two" + assert restored.fake.opens == [ + { + "session_id": "s1", + "fork": False, + "seed": None, + "instructions": None, + } + ] + assert not worker.fake.closed + assert len(worker.messages) == 2 + + +async def test_concurrent_open_starts_one_transport( + worker: fakes.FakeWorker, monkeypatch: pytest.MonkeyPatch +) -> None: + entered = asyncio.Event() + release = asyncio.Event() + second_entered = asyncio.Event() + starts: list[fakes.FakeAdapter] = [] + start = fakes.FakeAdapter.start + + async def slow_start(adapter: fakes.FakeAdapter) -> None: + starts.append(adapter) + entered.set() + await release.wait() + await start(adapter) + + async def second_open() -> None: + second_entered.set() + await worker.open() + + monkeypatch.setattr(fakes.FakeAdapter, "start", slow_start) + try: + async with asyncio.timeout(5), asyncio.TaskGroup() as tasks: + first = tasks.create_task(worker.open()) + await entered.wait() + second = tasks.create_task(second_open()) + await second_entered.wait() + assert not first.done() + assert not second.done() + assert len(starts) == 1 + release.set() + assert starts == [worker.fake] + assert worker.version == "fake 1.0" + runtime = worker._runtime + await worker.open() + assert worker._runtime is runtime + assert len(starts) == 1 + message = await ai.experimental_generate( + worker, [ai.user_message("one")] + ) + assert message.text == "one" + assert len(worker.fake.opens) == 1 + finally: + release.set() + await worker.close() + assert starts[0].closed + + +async def test_initial_stream_and_send_open_once_and_preserve_input( + worker: fakes.FakeWorker, monkeypatch: pytest.MonkeyPatch +) -> None: + opening = asyncio.Event() + release_open = asyncio.Event() + sending = asyncio.Event() + reading = asyncio.Event() + finish = asyncio.Event() + native_open = fakes.FakeAdapter.open + initial = ai.user_message("one") + + async def slow_open( + adapter: fakes.FakeAdapter, + *, + session_id: str | None, + fork: bool, + seed: list[m.Message] | None, + instructions: str | None, + ) -> str: + opened = await native_open( + adapter, + session_id=session_id, + fork=fork, + seed=seed, + instructions=instructions, + ) + opening.set() + await release_open.wait() + return opened + + async def read() -> list[events.Event]: + seen = [] + async with contextlib.aclosing(worker.stream([initial])) as feed: + async for event in feed: + seen.append(event) + if isinstance(event, events.StreamStart): + reading.set() + return seen + + async def send_guidance() -> None: + sending.set() + await worker.send("use tabs") + + async def wait_for_finish() -> None: + await finish.wait() + + monkeypatch.setattr(fakes.FakeAdapter, "open", slow_open) + worker.script( + lambda prompt: [fakes.Run(wait_for_finish), *fakes.text("done")] + ) + async with worker, asyncio.timeout(5): + reader = asyncio.create_task(read()) + sender: asyncio.Task[None] | None = None + try: + await opening.wait() + assert worker._runtime is not None + assert worker._runtime.stream_owner is reader + # The stream has reserved the reader, but its native session and + # initial input are not ready. A public send must wait, then steer. + sender = asyncio.create_task(send_guidance()) + await sending.wait() + assert not sender.done() + assert len(worker.fake.opens) == 1 + assert worker.fake.turns == [] + release_open.set() + await sender + await reading.wait() + finish.set() + seen = await reader + assert len(worker.fake.opens) == 1 + assert worker.fake.turns == ["one"] + assert worker.fake.steers == ["use tabs"] + users = [ + message for message in worker.messages if message.role == "user" + ] + assert [message.text for message in users] == ["one", "use tabs"] + assert users[0].id == initial.id + assert users[1].id != initial.id + assert worker.messages[-1].text == "done" + assert isinstance(seen[-1], events.StreamEnd) + assert seen[-1].finish_reason == "stop" + finally: + release_open.set() + finish.set() + reader.cancel() + tasks: list[asyncio.Task[Any]] = [reader] + if sender is not None: + sender.cancel() + tasks.append(sender) + await asyncio.gather(*tasks, return_exceptions=True) + + # -- ai.Agent tools, through the bridge --------------------------------------- @@ -461,29 +708,470 @@ async def test_approvals_are_tool_approval_hooks(granted: bool) -> None: assert answers[0][1] == "not today" # the reason the agent reads -async def test_approve_needs_a_run() -> None: +@pytest.mark.parametrize("granted", [True, False]) +async def test_agent_resolves_approval_from_a_preexisting_task( + granted: bool, +) -> None: worker = fakes.FakeWorker(approve=True) - async with worker: - with pytest.raises(workers.WorkerError, match=r"ai\.Agent\.run"): - await ai.experimental_generate(worker, [ai.user_message("go")]) + requested = asyncio.Event() + answered = asyncio.Event() + + async def external_callback() -> tuple[bool, str]: + await requested.wait() + approve = worker.fake.approve + assert approve is not None + answer = await approve("c1", "Bash", {"command": "ls"}) + answered.set() + return answer + + async def request_approval() -> None: + requested.set() + await answered.wait() + + worker.script( + lambda prompt: [fakes.Run(request_approval), *fakes.text("done")] + ) + async with worker, asyncio.timeout(5): + # CLI readers are often created before Agent.run establishes its + # context. The callback must use the stream's registry, not its own. + callback = asyncio.create_task(external_callback()) + seen: list[events.HookEvent] = [] + try: + async with ai.Agent().run(worker, [ai.user_message("go")]) as run: + async for event in run: + if isinstance(event, events.HookEvent): + seen.append(event) + if isinstance(event, events.PendingHookEvent): + assert event.hook.tool_call_id == "c1" + assert event.hook.metadata == { + "tool": "Bash", + "kwargs": {"command": "ls"}, + } + # Deliberately use the Agent context, without registry=. + ai.resolve_hook( + event.hook, + {"granted": granted, "reason": "user decision"}, + ) + done, _ = await asyncio.wait({callback}, timeout=1) + assert callback in done, ( + "Agent resolution did not reach the approval " + "callback created before Agent.run" + ) + assert callback.result() == (granted, "user decision") + assert [type(event) for event in seen] == [ + events.PendingHookEvent, + events.ResolvedHookEvent, + ] + assert run.messages[-1].text == "done" + assert worker.hook_registry._live_hooks == {} + assert worker._runtime is not None + assert worker._runtime.approvals == set() + finally: + callback.cancel() + with contextlib.suppress(asyncio.CancelledError): + await callback + + +@pytest.mark.parametrize("granted", [True, False]) +async def test_direct_approvals_use_the_worker_registry(granted: bool) -> None: + worker = fakes.FakeWorker(approve=True) + worker.script( + lambda prompt: [ + fakes.Ask("c1", "Bash", {"command": "ls"}), + *fakes.text("done"), + ] + ) + seen: list[workers.SessionEvent] = [] + async with worker, contextlib.aclosing(worker.events()) as feed: + async with asyncio.timeout(5): + await worker.send("go") + async for event in feed: + seen.append(event) + if isinstance(event, events.PendingHookEvent): + assert worker.fake.answers == [] + assert event.hook.tool_call_id == "c1" + assert event.hook.hook_type == "ToolApproval" + assert event.hook.metadata == { + "tool": "Bash", + "kwargs": {"command": "ls"}, + } + ai.resolve_hook( + event.hook, + {"granted": granted, "reason": "user decision"}, + registry=worker.hook_registry, + ) + if isinstance(event, events.StreamEnd): + break + assert worker.fake.answers == [(granted, "user decision")] + assert [ + type(event) for event in seen if isinstance(event, events.HookEvent) + ] == [events.PendingHookEvent, events.ResolvedHookEvent] + assert worker.hook_registry._live_hooks == {} + assert worker._runtime is not None + assert worker._runtime.approvals == set() + assert worker.messages[-1].text == "done" + + +@pytest.mark.parametrize("action", ["interrupt", "cancel"]) +async def test_stopping_a_pending_approval_cleans_up(action: str) -> None: + worker = fakes.FakeWorker(approve=True) + worker.script(lambda prompt: [fakes.Ask("c1", "Bash"), fakes.Pause()]) + pending = asyncio.Event() + seen: list[workers.SessionEvent] = [] + + async def read() -> None: + async with contextlib.aclosing(worker.events()) as feed: + async for event in feed: + seen.append(event) + if isinstance(event, events.PendingHookEvent): + pending.set() + if isinstance(event, events.StreamEnd): + return + + async with worker, asyncio.timeout(5): + await worker.send("one") + reader = asyncio.create_task(read()) + try: + await pending.wait() + registry = worker.hook_registry + assert len(registry._live_hooks) == 1 + if action == "interrupt": + await worker.interrupt() + await reader + assert isinstance(seen[-1], events.StreamEnd) + assert seen[-1].finish_reason == "other" + else: + reader.cancel() + with pytest.raises(asyncio.CancelledError): + await reader + finally: + if not reader.done(): + reader.cancel() + with contextlib.suppress(asyncio.CancelledError): + await reader + assert worker.fake.answers == [(False, "the approval was cancelled")] + assert registry._live_hooks == {} + assert not worker.fake.running + assert worker._runtime is not None + assert not worker._runtime.reader + assert worker._runtime.pump is None + assert worker._runtime.approvals == set() + worker.script(fakes.reply) + answer = await ai.experimental_generate( + worker, [*worker.messages, ai.user_message("two")] + ) + assert answer.text == "two" + assert worker.messages[-2].text == "two" + assert worker.fake.turns == ["one", "two"] -# -- steer, the TUI, the store ------------------------------------------------ +async def test_approve_without_a_hook_does_not_require_an_agent() -> None: + async with fakes.FakeWorker(approve=True) as worker: + message = await ai.experimental_generate( + worker, [ai.user_message("go")] + ) + assert message.text == "go" + + +# -- direct control, the TUI, the store --------------------------------------- + + +async def test_send_reaches_the_running_turn(worker: fakes.FakeWorker) -> None: + worker.script(lambda prompt: [*fakes.text("working"), fakes.Pause()]) + async with worker, contextlib.aclosing(worker.events()) as feed: + async with asyncio.timeout(5): + await worker.send("go") + accepted = [] + async for event in feed: + if isinstance(event, workers.UserMessageAccepted): + accepted.append(event.message.text) + if event.message.text == "use tabs": + await worker.interrupt() + if isinstance(event, events.TextEnd): + await worker.send("use tabs") + assert [ + x.text for x in worker.messages if x.role == "user" + ] == ["go"] + if isinstance(event, events.StreamEnd): + assert event.finish_reason == "other" + break + assert accepted == ["go", "use tabs"] + assert worker.fake.turns == ["go"] + assert worker.fake.steers == ["use tabs"] -async def test_steer_reaches_the_running_turn( +async def test_one_persistent_feed_mirrors_multiple_sends( worker: fakes.FakeWorker, +) -> None: + async with worker, contextlib.aclosing(worker.events()) as feed: + async with asyncio.timeout(5): + for index, prompt in enumerate(("one", "two")): + await worker.send(prompt) + # Acceptance is queued, but send() must not mutate the mirror. + assert len(worker.messages) == index * 2 + accepted = await anext(feed) + assert isinstance(accepted, workers.UserMessageAccepted) + assert accepted.message.text == prompt + assert worker.messages[-1] is accepted.message + assert len(worker.messages) == index * 2 + 1 + seen = [] + async for event in feed: + seen.append(event) + if isinstance(event, events.StreamEnd): + break + assert [type(event) for event in seen] == [ + events.StreamStart, + events.TextStart, + events.TextDelta, + events.TextEnd, + events.StreamEnd, + ] + assert len(worker.messages) == (index + 1) * 2 + assert worker.messages[-1].text == prompt + assert all( + event.message is worker.messages[-1] for event in seen + ) + assert worker.fake.turns == ["one", "two"] + assert len(worker.fake.opens) == 1 + await worker.close() + with pytest.raises(StopAsyncIteration): + await anext(feed) + assert [message.role for message in worker.messages] == [ + "user", + "assistant", + "user", + "assistant", + ] + assert len({message.id for message in worker.messages}) == 4 + + +@pytest.mark.parametrize("owner", ["direct", "stream"]) +@pytest.mark.parametrize("challenger", ["direct", "stream"]) +async def test_one_reader_guard_across_direct_and_model_apis( + worker: fakes.FakeWorker, owner: str, challenger: str ) -> None: worker.script(lambda prompt: [*fakes.text("working"), fakes.Pause()]) async with worker: - with pytest.raises(workers.WorkerError): - await worker.steer("too early") - async with ai.stream(worker, [ai.user_message("go")]) as s: - async for event in s: + if owner == "direct": + await worker.send("one") + feed = worker.events() + else: + feed = worker.stream([ai.user_message("one")]) + async with contextlib.aclosing(feed): + await anext(feed) + other = ( + worker.events() + if challenger == "direct" + else worker.stream([*worker.messages, ai.user_message("two")]) + ) + async with contextlib.aclosing(other): + with pytest.raises( + workers.WorkerError, match="already has a reader" + ): + await anext(other) + assert worker.fake.turns == ["one"] + assert worker.fake.interrupts == 0 + async with asyncio.timeout(5): + await worker.interrupt() + async for event in feed: + if isinstance(event, events.StreamEnd): + assert event.finish_reason == "other" + break + assert worker._runtime is not None + assert not worker._runtime.reader + assert worker._runtime.stream_owner is None + + +async def test_stream_reserves_the_reader_before_send_acceptance( + worker: fakes.FakeWorker, monkeypatch: pytest.MonkeyPatch +) -> None: + entered = asyncio.Event() + release = asyncio.Event() + turn = fakes.FakeAdapter.turn + + async def slow_turn( + adapter: fakes.FakeAdapter, prompt: _adapter.Prompt + ) -> AsyncIterator[events.Event]: + entered.set() + await release.wait() + async for event in turn(adapter, prompt): + yield event + + monkeypatch.setattr(fakes.FakeAdapter, "turn", slow_turn) + async with worker, asyncio.timeout(5), asyncio.TaskGroup() as tasks: + first = tasks.create_task( + collect(worker.stream([ai.user_message("one")])) + ) + await entered.wait() + try: + for other in ( + worker.events(), + worker.stream([ai.user_message("two")]), + ): + async with contextlib.aclosing(other): + with pytest.raises( + workers.WorkerError, match="already has a reader" + ): + await anext(other) + finally: + release.set() + assert isinstance(first.result()[-1], events.StreamEnd) + assert [message.text for message in worker.messages] == ["one", "one"] + + +async def test_cancellation_before_acceptance_cleans_up( + worker: fakes.FakeWorker, monkeypatch: pytest.MonkeyPatch +) -> None: + entered = asyncio.Event() + release = asyncio.Event() + exited = asyncio.Event() + turn = fakes.FakeAdapter.turn + + async def slow_turn( + adapter: fakes.FakeAdapter, prompt: _adapter.Prompt + ) -> AsyncIterator[events.Event]: + entered.set() + try: + await release.wait() + async for event in turn(adapter, prompt): + yield event + finally: + exited.set() + + monkeypatch.setattr(fakes.FakeAdapter, "turn", slow_turn) + async with worker, asyncio.timeout(5): + reader = asyncio.create_task( + collect(worker.stream([ai.user_message("one")])) + ) + try: + await entered.wait() + finally: + reader.cancel() + with pytest.raises(asyncio.CancelledError): + await reader + assert exited.is_set() + assert worker.messages == [] + assert worker.fake.interrupts == 1 + assert worker._runtime is not None + assert worker._runtime.pump is None + assert not worker._runtime.reader + assert worker._runtime.stream_owner is None + assert worker._runtime.submission is None + release.set() + answer = await ai.experimental_generate( + worker, [ai.user_message("one")] + ) + assert answer.text == "one" + assert worker.fake.turns == ["one"] + + +async def test_interrupt_ends_a_turn_but_not_the_session_feed( + worker: fakes.FakeWorker, +) -> None: + worker.script(lambda prompt: [*fakes.text("partial"), fakes.Pause()]) + async with worker, contextlib.aclosing(worker.events()) as feed: + async with asyncio.timeout(5): + await worker.send("one") + async for event in feed: if isinstance(event, events.TextEnd): - await worker.steer("use tabs") - await worker.fake.interrupt() - assert worker.fake.steers == ["use tabs"] + await worker.interrupt() + if isinstance(event, events.StreamEnd): + assert event.finish_reason == "other" + assert event.provider_metadata is not None + assert ( + event.provider_metadata["worker"]["finish_reason"] + == "cancelled" + ) + break + assert worker.fake.interrupts == 1 + assert worker.messages[-1].text == "partial" + worker.script(fakes.reply) + await worker.send("two") + accepted = await anext(feed) + assert isinstance(accepted, workers.UserMessageAccepted) + assert accepted.message.text == "two" + async for event in feed: + if isinstance(event, events.StreamEnd): + assert event.finish_reason == "stop" + break + assert worker.messages[-1].text == "two" + assert worker.fake.turns == ["one", "two"] + + +@pytest.mark.parametrize("api", ["direct", "stream"]) +async def test_cancelling_a_reader_cleans_up_and_allows_another_turn( + worker: fakes.FakeWorker, api: str +) -> None: + waiting = asyncio.Event() + worker.script(lambda prompt: [*fakes.text("partial"), fakes.Pause()]) + + async def read() -> None: + if api == "direct": + await worker.send("one") + feed = worker.events() + else: + feed = worker.stream([ai.user_message("one")]) + async with contextlib.aclosing(feed): + async for event in feed: + if isinstance(event, events.TextEnd): + waiting.set() + + async with worker, asyncio.timeout(5): + reader = asyncio.create_task(read()) + try: + await waiting.wait() + finally: + reader.cancel() + with pytest.raises(asyncio.CancelledError): + await reader + assert worker.fake.interrupts == 1 + assert not worker.fake.running + assert worker._runtime is not None + assert worker._runtime.pump is None + assert not worker._runtime.reader + assert worker._runtime.stream_owner is None + assert worker._runtime.pending == {} + assert worker._runtime.approvals == set() + assert [message.text for message in worker.messages] == [ + "one", + "partial", + ] + worker.script(fakes.reply) + answer = await ai.experimental_generate( + worker, [*worker.messages, ai.user_message("two")] + ) + assert answer.text == "two" + assert worker.fake.turns == ["one", "two"] + + +async def test_sync_and_fork_require_an_idle_session( + worker: fakes.FakeWorker, +) -> None: + async with worker: + for action in (worker.sync, worker.fork): + with pytest.raises(workers.WorkerError, match="no session_id"): + await action() + worker.script(lambda prompt: [fakes.Pause()]) + await worker.send("one") + for action in (worker.sync, worker.fork): + with pytest.raises( + workers.WorkerError, match="stop the turn and reader" + ): + await action() + async with ( + contextlib.aclosing(worker.events()) as feed, + asyncio.timeout(5), + ): + await worker.interrupt() + async for event in feed: + if isinstance(event, events.StreamEnd): + break + # Even between turns a live reader owns the mirror. + for action in (worker.sync, worker.fork): + with pytest.raises( + workers.WorkerError, match="stop the turn and reader" + ): + await action() async def test_tui_command_mints_a_session(worker: fakes.FakeWorker) -> None: @@ -503,7 +1191,7 @@ async def test_tui_hands_over_and_reads_back() -> None: assert await worker.tui() == 0 # tui() closed the worker's CLI, ran the TUI, and opened again. worker.fake.stored["s1"] = stored - await worker.load() + await worker.sync() assert worker.messages == stored