Something went wrong. Try again.
MCP based ACP agent
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598"""Headless ACP v2 client that drives one subagent subprocess.
The client half of the task system: pure protocol orchestration — spawn achild crow agent, handshake, ``session/new``, ``session/prompt``,``session/cancel``, teardown. No sqlite and no tool knowledge. The ``task``subtool owns state and lifecycle; this is the driver it uses, and the twocouple through the database, never in-process.
What v2 changed, and why this is not a mechanical port of:mod:`crow_cli.client.subagent`:
**``prompt`` no longer returns the outcome.** v1's ``PromptResponse`` carried``stop_reason``. v2's carries only ``field_meta``, and the outcome travels as a``state_update`` notification — which is the whole point of the v2 lifecycle,and the reason a wake can look exactly like a prompt. So somebody has to watchthe update stream for the idle. :class:`HeadlessClient` does, and:meth:`SubagentDriver.prompt` still returns a stop reason, because "launch achild and get its answer" is the contract the task system is written againstand nothing in v2 makes that contract wrong. The watch itself is:meth:`SubagentDriver.wait` and ``prompt`` is that plus the send — a splitthat lets a caller which ran out of patience hand the turn to a backgroundwaiter instead of killing a child that was about to answer.
**There is no client-side terminal or fs capability to decline.** v1 sent``ClientCapabilities(terminal=False)`` so the child's terminal tool would fallthrough to its own MCP supply. v2's ``ClientCapabilities`` has ``auth``,``elicitation``, ``nes`` and ``position_encodings`` and nothing else: the agentowns execution, so the choice no longer exists.
**``session/load`` is ``session/resume``**, and it replays history only whenasked. A headless driver does not ask — the child's transcript is in the sharedsqlite, and replaying it into a queue nobody reads is pure cost.
**Absent handlers already answer ``method_not_found``.** v2's ``MethodRouter``raises that for any request whose handler attribute is missing, so v1'sexplicit ``raise RequestError.method_not_found(...)`` stubs are deleted ratherthan ported. Omitting them produces the identical reply on the wire."""
from __future__ import annotations
import asyncioimport collectionsimport contextlibimport osimport sysfrom contextlib import AsyncExitStackfrom pathlib import Pathfrom typing import Any, Optional
from acp.experimental import v2from acp.stdio import spawn_stdio_transport
from crow_cli import __version__from crow_cli.discover import Connection, adopt_v2
#: How much of a child's stderr to keep. The drain exists so the pipe cannot#: fill and deadlock the child, not to archive its log, so it is bounded — and#: the tail is exactly what an error message about a dead child needs.STDERR_LINES = 200
#: How long to wait for the event loop to collect a child's exit status once its#: transport has closed. The status is already on its way — the pipe closed#: because the process did — and the bound is there so a child that closed its#: stdout and somehow kept running cannot park its owner forever, which is the#: one failure this driver exists to prevent.REAP_GRACE_S = 5.0
class ChildExited(RuntimeError): """The child process ended before its turn did.
Distinct from a transport error and from a timeout, because the caller's options differ: there is nothing to cancel, nothing to retry on the same session, and the stderr tail in the message is the only evidence that will ever exist. A task watcher turns this into a ``failed`` row. """
def child_config() -> dict[str, Path]: """Config context for a spawned child, forwarded from THIS process's env.
The child loads its own config in its own process, so without these it resolves a different config dir — and therefore a different database — than the caller that is about to read the child's transcript out of.
Duplicated from :mod:`crow_cli.client.subagent` rather than imported: that module speaks ACP v1 at import time and v1 is frozen, so importing one six-line function from it would drag the old protocol into every process that spawns a new one. """ kwargs: dict[str, Path] = {} if f := os.environ.get("CROW_CONFIG_FILE"): kwargs["config_file"] = Path(f) if d := os.environ.get("CROW_CONFIG_DIR"): kwargs["config_dir"] = Path(d) return kwargs
def agent_argv( model: Optional[str] = None, config_dir: Optional[Path] = None, config_file: Optional[Path] = None,) -> list[str]: """The argv that starts a v2 agent in this interpreter.
Two shapes, mirroring v1's ``spawn_agent_process``. In a frozen build ``sys.executable`` IS the ``crow-cli`` binary, so the agent is a subcommand of it; in a source checkout it is a module, because there is no binary and ``-m`` is the only thing that resolves against the checkout under test.
``acp2`` and :func:`crow_cli.cli.main.run_agent2` are two halves of one contract. Spawning ``acp`` here instead would produce a child that answers a v2 handshake with a v1 one — which is why this refused to guess for as long as the subcommand did not exist. """ args: list[str] = [] if config_dir: args += ["--config-dir", str(config_dir)] if config_file: args += ["--config-file", str(config_file)] if model: args += ["--model", model] if getattr(sys, "frozen", False): return [sys.executable, "acp2", *args] return [sys.executable, "-m", "crow_cli.agent2.main", *args]
def client_info(name: str = "crow-task", title: str = "Crow Task") -> Any: """The Implementation a driver names itself with in the handshake.
The agent logs it (``initialize: client <name> <version>``), so the task system and a human at a terminal stay distinguishable in the one place both are recorded. """ return v2.schema.Implementation(name=name, title=title, version=__version__)
def mcp_servers_to_models(servers: Optional[list]) -> list[Any]: """Wire JSON dicts -> v2 MCP server models, before the request is built.
The dicts come out of sqlite, where :func:`crow_cli.agent2.sessions. mcp_servers_to_wire` stored whatever a client originally sent. Building the models item by item is the lesson v1 learned the hard way: a list item that fails validation is dropped silently, and the child comes up toolless with no error anywhere. Here a bad shape raises at the caller.
``type`` is filled in rather than trusted, and ``sse`` is rewritten to ``http`` — v2 deleted ``SseMcpServer``, and an SSE endpoint is an HTTP endpoint, so rewriting it keeps an old stored server working where dropping it would not. """ out: list[Any] = [] for server in servers or (): if not isinstance(server, dict): out.append(server) # already a model continue data = dict(server) kind = data.pop("type", None) or ("stdio" if data.get("command") else "http") if kind == "sse": kind = "http" if kind == "stdio": model = v2.schema.StdioMcpServer.model_validate( {"type": "stdio", "args": [], "env": [], **data} ) elif kind == "http": model = v2.schema.HttpMcpServer.model_validate({"type": "http", **data}) elif kind == "acp": model = v2.schema.AcpMcpServer.model_validate({"type": "acp", **data}) else: model = v2.schema.OtherMcpServer.model_validate({"type": kind, **data}) out.append(model) return out
def config_to_servers(mcp_servers: Optional[dict[str, Any]]) -> list[dict[str, Any]]: """The config ``mcpServers`` MAP -> the wire LIST a v2 request carries.
Config keys a server by name and spells its transport ``transport``; the wire puts the name inside the entry and spells it ``type``. This is the client half of that translation, and it belongs to the client because the client owns tool supply: the agent never reads ``mcpServers`` itself, so what a client sends here is exactly what the session gets.
Duplicated from v1's ``agent.mcp_client.fastmcp_config_to_acp_servers`` rather than imported, for the reason :func:`child_config` is duplicated: that module speaks ACP v1 at import time and v1 is frozen.
``sse`` is passed through as written and rewritten to ``http`` by :func:`mcp_servers_to_models`, which is where that rule already lives. """ out: list[dict[str, Any]] = [] for name, cfg in (mcp_servers or {}).items(): if not isinstance(cfg, dict): raise ValueError( f"mcpServers.{name!r} must be a mapping, not {type(cfg).__name__}" ) kind = cfg.get("transport") or cfg.get("type") or ( "http" if cfg.get("url") else "stdio" ) entry: dict[str, Any] = {"type": kind, "name": name} if kind == "stdio": if not cfg.get("command"): raise ValueError(f"mcpServers.{name!r}: a stdio server needs a command") entry["command"] = str(cfg["command"]) entry["args"] = [str(a) for a in (cfg.get("args") or [])] entry["env"] = [ {"name": str(k), "value": str(v)} for k, v in (cfg.get("env") or {}).items() ] else: if not cfg.get("url"): raise ValueError(f"mcpServers.{name!r}: a {kind} server needs a url") entry["url"] = str(cfg["url"]) entry["headers"] = [ {"name": str(k), "value": str(v)} for k, v in (cfg.get("headers") or {}).items() ] out.append(entry) return out
class HeadlessClient: """The client face shown to a subagent: record updates, answer nothing.
Two jobs. ``updates`` is the record — the child's transcript is properly observable through the shared sqlite, so this is for debugging and for a caller that wants the wire rather than the database. ``stops`` is the part v2 makes necessary: one queue per session, fed by the idle ``state_update``, which is how a driver learns a turn ended now that the prompt response says nothing. """
def __init__(self) -> None: self.updates: list[Any] = [] self.stops: dict[str, asyncio.Queue] = {} self.running: set[str] = set()
def watch(self, session_id: str) -> asyncio.Queue: """The queue this session's stop reasons land in.
Called BEFORE the prompt is sent, not after: a turn that ends fast (a slash command, an empty prompt) can reach idle before ``prompt()`` returns its empty response, and registering afterwards would wait forever for a notification that already arrived. """ return self.stops.setdefault(session_id, asyncio.Queue())
async def session_update( self, session_id: str, update: Any, **kwargs: Any ) -> None: """One ``session/update``. The router hands over the notification's fields as keywords, not the model — see :mod:`crow_cli.agent2.agent`'s docstring for the two consequences that follow from it.""" self.updates.append(update) if getattr(update, "session_update", None) != "state_update": return state = getattr(update, "state", None) if state == "running" and session_id in self.stops: self.running.add(session_id) elif state == "idle" and session_id in self.running: self.running.remove(session_id) self.stops[session_id].put_nowait(getattr(update, "stop_reason", None))
class SubagentDriver: """Drives ONE v2 subagent: spawn -> handshake -> sessions -> turns."""
def __init__( self, client: Optional[HeadlessClient] = None, info: Optional[Any] = None, ) -> None: """``client`` is the face shown to the child — a caller that renders the update stream passes its own :class:`HeadlessClient` subclass rather than inheriting the recording one. ``info`` is the Implementation the handshake names; the agent logs it, so a client that is not the task system says so.""" self.client = client or HeadlessClient() self.info = info or client_info() self.conn: Optional[v2.ClientSideConnection] = None self.proc: Optional[Any] = None self.stderr: collections.deque = collections.deque(maxlen=STDERR_LINES) self._stack = AsyncExitStack() self._drainer: Optional[asyncio.Task] = None
@property def stderr_tail(self) -> str: """What the child said last. Empty when it said nothing.""" return "".join(self.stderr)
async def start( self, cwd: str, model: Optional[str] = None, config_dir: Optional[Path] = None, config_file: Optional[Path] = None, argv: Optional[list[str]] = None, env: Optional[dict[str, str]] = None, conn: Optional[Connection] = None, ) -> None: """Spawn the child, handshake, and be ready to open sessions.
``argv`` launches somebody else's agent: an ``agent_servers`` entry is a command the client honors exactly as written, so a driver that only ever spawned crow's own agent could not drive one. Omitted, it is :func:`agent_argv` — crow's v2 agent in this interpreter. ``env`` is merged OVER this process's environment, which is the entry's own extra variables; the base is inherited whole, for the reason spelled out below.
``conn`` is an already-spawned child somebody else asked: protocol discovery spawns once and hands the live streams to whichever stack the agent's answer selects, because a second spawn is a second cold start of the same process. Adopting one takes the stderr drain over by reference — two readers on one ``StreamReader`` would split the child's lines between them — and skips the handshake when the probe already did it. ``close()`` needs no matching change: the exit stack is empty for an adopted child, so the caller's context manager owns the shutdown. """ if conn is not None: reader, writer = conn.reader, conn.writer self.proc = conn.proc self.stderr = conn.stderr self._drainer = conn.drainer else: reader, writer, self.proc = await self._stack.enter_async_context( spawn_stdio_transport( *( argv or agent_argv( model=model, config_dir=config_dir, config_file=config_file ) ), # spawn_stdio_transport's default environment is the # MCP-best-practice trim — HOME, LOGNAME, PATH, SHELL, TERM, # USER — because it exists to launch other people's servers. # A crow child is not somebody else's server: v1 inherited the # whole environment, and the trim silently loses shell-exported # API keys, SEARXNG_URL, CROW_MEMORY_PORT and everything else # this process was built out of. child_config() forwards the # two config pointers as argv, which covers config resolution # and nothing else. env={**os.environ, **(env or {})}, cwd=cwd, ) ) self._drainer = asyncio.create_task( self._drain_stderr(), name="crow-subagent-stderr" ) self.conn = v2.ClientSideConnection(self.client, writer, reader) if conn is not None and conn.initialized: # Already negotiated on the wire. v2's connection also gates every # method on a LOCAL initialization state that only its own # initialize() moves, and a second initialize is refused by the # agent, so the state is adopted rather than the request repeated. adopt_v2(self.conn, conn.response) else: await self.conn.initialize( protocol_version=v2.PROTOCOL_VERSION, info=self.info )
async def _drain_stderr(self) -> None: """Keep the child's stderr pipe empty.
Not optional and not cosmetic: ``spawn_stdio_transport`` gives the child a PIPE, and a child that logs more than the 64KB buffer holds blocks on the write and hangs with no error on either side. v1 had this bug — it opened the pipe and never read it. """ stream = getattr(self.proc, "stderr", None) if stream is None: return while True: line = await stream.readline() if not line: return self.stderr.append(line.decode(errors="replace"))
async def new_session(self, cwd: str, mcp_servers: Optional[list] = None) -> str: response = await self.conn.new_session( cwd=cwd, mcp_servers=mcp_servers_to_models(mcp_servers) ) return response.session_id
async def resume_session( self, session_id: str, cwd: str, mcp_servers: Optional[list] = None, replay: bool = False, ) -> None: """Re-attach to a session whose turn ended, so it can be prompted again.
``replay_from`` is left off BY DEFAULT. Omitting it means no history comes back over the wire, and the child's transcript is already in the shared sqlite where ``query_session`` can read it: asking for ``{"type": "start"}`` would stream the whole conversation into ``HeadlessClient.updates`` for nobody. A client with a human watching is that somebody — it renders the replayed transcript — so it passes ``replay=True`` and gets the conversation before the first prompt. """ await self.conn.resume_session( session_id=session_id, cwd=cwd, mcp_servers=mcp_servers_to_models(mcp_servers), replay_from=(v2.schema.ReplayFromStartVariant() if replay else None), )
async def fork_session( self, session_id: str, cwd: str, mcp_servers: Optional[list] = None, *, message_offset: Optional[int] = None, rlm_depth: Optional[int] = None, ) -> str: """``session_id``'s history under a NEW wire id, which is the fork's own agent id — so it is also the key the fork's transcript is stored under, and reading that transcript back needs no handshake.
An empty ``mcp_servers`` means ZERO tools, which is what an interrogation fork wants and what a delegate that only has to answer a question does not need.
``message_offset`` and ``rlm_depth`` are not in the schema — v2's ``ForkSessionRequest`` carries the environment and nothing else — so they ride ``_meta``, which is what ``_meta`` is for and what v1 did with the same two. They are the delegation half of the fork contract: the offset steps the fork's history back over the call that made it, and the depth is persisted on the fork's agent row so the budget survives a resume in a different process. A delegate that forgets either is the infinity mirror. """ meta: dict[str, Any] = {} if message_offset is not None: meta["messageOffset"] = message_offset if rlm_depth is not None: meta["rlmDepth"] = rlm_depth # ``**meta``, not ``field_meta=meta``: the connection's trailing # ``**kwargs`` IS the request's ``_meta``, which is what lets a caller # name a field the schema does not have without building the model. response = await self.conn.fork_session( session_id=session_id, cwd=cwd, mcp_servers=mcp_servers_to_models(mcp_servers), **meta, ) return response.session_id
async def set_config_option( self, session_id: str, config_id: str, value: str ) -> Any: """Set one of the session's config options; returns the whole array.
A model choice rides this rather than the child's argv, because argv is crow's own agent's business while an ``agent_servers`` entry belongs to whoever wrote it. This is the one path that reaches every agent, which is why the client owns the choice. """ return await self.conn.set_config_option( config_id=config_id, session_id=session_id, value=value, type="id" )
async def prompt( self, session_id: str, text: str, *, timeout: Optional[float] = None ) -> Optional[str]: """Send one prompt and wait for the turn to end. Returns the stop reason.
The wait is the v2 part: ``PromptResponse`` is empty, so returning from ``conn.prompt`` means "accepted", not "finished". ``None`` comes back when the agent reported an idle with no stop reason, which per the spec means it is not reporting one.
``timeout`` is for a turn that never ends — a model that will not stop calling tools, or an agent that does not report idle at all. crow's own always does, including while a delegated task runs in the background: in v2 that is exactly what ``idle`` means.
Raises :class:`ChildExited` if the child dies, whether that lands during the send or during the wait, and :class:`TimeoutError` if the turn does not end. Both are the caller's to act on; neither leaves it parked. """ # Registered BEFORE the send, not after: a turn that ends fast (a slash # command, an empty prompt) can reach idle before ``conn.prompt`` # returns its empty response, and watching afterwards would wait # forever for a notification that already arrived. self.client.watch(session_id) try: await self.conn.prompt( session_id=session_id, prompt=[v2.schema.TextContentBlock(text=text)], ) except ConnectionError as exc: # The child died before it acknowledged. The transport closed with # the request still pending, so the send raises instead of returning # — and :meth:`wait`, the only other place ChildExited is raised, is # never reached. Callers distinguish the two: a dead child has # nothing to cancel and nothing to retry on the same session, and # the exit note carries the only stderr that will ever exist. with contextlib.suppress(TimeoutError): await asyncio.wait_for(self._exited(), timeout=REAP_GRACE_S) raise ChildExited(self._exit_note()) from exc return await self.wait(session_id, timeout=timeout)
async def wait( self, session_id: str, *, timeout: Optional[float] = None ) -> Optional[str]: """Wait for a turn that is ALREADY in flight. Returns the stop reason.
:meth:`prompt` is this plus the send, and the split is what lets a caller that ran out of patience hand the turn to a background task instead of killing it: the idle the first wait never saw is still coming, :meth:`HeadlessClient.watch` hands back the SAME queue, and a reason that landed in the gap is sitting on it — so a second wait finds it rather than waiting for a notification that already arrived.
Three things can end the wait, and only one of them is the answer:
* the idle ``state_update`` lands — the stop reason; * the child process ends — :class:`ChildExited`, because a dead child will never send another notification and the queue it would have sent it to is not going to fill. Waiting on it anyway is how a crashed subagent leaves its task row "running" forever, and its owner parked forever behind it; * ``timeout`` expires — :class:`TimeoutError`. """ stops = self.client.watch(session_id) stop = asyncio.ensure_future(stops.get()) died = asyncio.ensure_future(self._exited()) done, _ = await asyncio.wait( {stop, died}, timeout=timeout, return_when=asyncio.FIRST_COMPLETED ) if stop in done: died.cancel() with contextlib.suppress(asyncio.CancelledError): await died return stop.result() # Cancelling the getter leaves a reason that arrived in the meantime on # the queue, so a caller that looks again finds it instead of waiting. stop.cancel() died.cancel() for pending in (stop, died): with contextlib.suppress(asyncio.CancelledError): await pending if died.done() and not died.cancelled(): raise ChildExited(self._exit_note()) raise TimeoutError( f"session {session_id} did not end its turn within {timeout}s" )
async def _exited(self) -> None: """Return when the child process is gone (or immediately, if it never started — which is also "no notification will ever arrive").""" proc = self.proc if proc is None: return await proc.wait()
def _exit_note(self) -> str: proc = self.proc code = getattr(proc, "returncode", None) tail = self.stderr_tail.strip().splitlines()[-3:] note = f"child process exited with code {code}" if tail: note += "; its last words were: " + " | ".join( line.strip() for line in tail ) return note
async def cancel(self, session_id: str) -> None: """Kill the child's in-flight turn. The session survives it.
v2 cancellation is per-turn, so the child is still promptable afterwards — which is how a redirect works: cancel, then prompt again on the same session id. """ await self.conn.cancel_session(session_id=session_id)
async def close(self) -> None: """Tear down. Safe to call on a driver that never started.""" with contextlib.suppress(Exception): if self.conn is not None: await self.conn.close() if self._drainer is not None: self._drainer.cancel() with contextlib.suppress(asyncio.CancelledError): await self._drainer self._drainer = None # The stack owns spawn_stdio_transport's shutdown: stdin EOF, wait, # terminate, then kill. Hand-rolling that escalation is how v1 ended # up with a terminate/kill ladder of its own to keep in step. await self._stack.aclose() self.conn = None self.proc = None