Something went wrong. Try again.
MCP based ACP agent
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318"""Which protocol does this agent speak? Ask it.
``initialize`` is the negotiation: the client sends the latest version itsupports and the agent replies with the version it chose — the same one if itcan speak it, otherwise the latest it does. That answer decides which clientstack drives the connection, so an ``agent_servers`` entry never has to declarea protocol. An entry is a command, and the command says what it speaks thefirst time you talk to it. A config field asserting the same thing is a secondsource of truth whose only talent is disagreeing with the first: it is how anagent that works gets launched by a client speaking the other version, whichhangs with no error on either side.
The probe IS the connection, not a prelude to one. It spawns the child once andhands the live, already-handshaked streams to whichever stack the versionselects, so discovery costs one round trip rather than a second process.
One request serves both versions because ``initialize`` is the one method whoseparams they still share a shape for: v1 reads ``clientInfo`` and``clientCapabilities`` and ignores the rest, v2 requires ``info`` and ignoresthe rest. Sending the union means each agent sees exactly the fields its ownclient would have sent — v1's ``terminal: false`` included, which is what makesthe agent's terminal tool fall through to its own MCP supply rather than aclient-side PTY — and only ``protocolVersion`` has to be read back."""
from __future__ import annotations
import asyncioimport collectionsimport contextlibimport jsonimport loggingimport osfrom contextlib import asynccontextmanagerfrom dataclasses import dataclass, fieldfrom typing import Any, AsyncIterator, Optional
from acp import PROTOCOL_VERSION as V1_VERSIONfrom acp.experimental import v2from acp.schema import ClientCapabilities, Implementationfrom acp.stdio import spawn_stdio_transport
from crow_cli import __version__from crow_cli.agents import V1, V2, AgentServer
logger = logging.getLogger("crow-discover")
#: How long the handshake gets. This is a spawn budget, not a network one:#: ``uv run`` cold-starts an interpreter and imports crow before the agent can#: answer, and a cold cache makes that slow rather than broken.PROBE_TIMEOUT = 120.0
#: How much of the child's stderr to keep. The drain exists so the pipe cannot#: fill and deadlock the child; the tail is what an error about a dead child#: needs, and it is the only evidence that will ever exist.STDERR_LINES = 200
#: The latest version this client speaks, which the spec says the request MUST#: carry. An agent that speaks it answers with it; one that does not answers#: with the latest it does.LATEST = v2.PROTOCOL_VERSION
#: An answered version, and the client stack it selects.BY_VERSION = {V1_VERSION: V1, LATEST: V2}
CLIENT_NAME = "crow-client"CLIENT_TITLE = "Crow Client"
#: The handshake's JSON-RPC id. Nothing else is in flight when it is sent, so#: it is the only reply that can arrive. Reusing 0 is safe even though the#: SDK's own connection also starts counting at 0: JSON-RPC ids only have to#: distinguish requests that are outstanding together, and this one is#: answered before the stack sends anything._REQUEST_ID = 0
class ProtocolError(Exception): """The agent never answered the handshake, or answered one we cannot speak.
The message carries the child's stderr tail: an agent that fails at startup says why there and nowhere else. """
def handshake_params() -> dict[str, Any]: """One ``initialize`` params object that both protocol versions accept.
Each half is what that version's own client sends, so neither agent sees a capability it would not have been offered anyway. """ info = Implementation( name=CLIENT_NAME, title=CLIENT_TITLE, version=__version__ ).model_dump(mode="json", by_alias=True, exclude_none=True) return { "protocolVersion": LATEST, # v2 reads these two and ignores the rest. "info": info, "capabilities": {}, # v1 reads these two and ignores the rest. terminal=False is what # connect_client sends and is load-bearing, not decoration. "clientInfo": info, "clientCapabilities": ClientCapabilities(terminal=False).model_dump( mode="json", by_alias=True, exclude_none=True ), }
@dataclass(frozen=True)class Connection: """A spawned agent, the protocol it speaks, and whether it handshook.
``initialized`` is False when the entry declared its protocol and the stack must do its own handshake exactly as it always has; True when this module already did it and the stack would be doing it twice. """
protocol: str reader: Any writer: Any proc: Any initialized: bool response: Optional[dict[str, Any]] = None stderr: collections.deque = field( default_factory=lambda: collections.deque(maxlen=STDERR_LINES) ) drainer: Optional[asyncio.Task] = None
def stderr_tail(self) -> str: """What the child said on stderr, for the error that reports it died.""" return "".join(self.stderr).strip()
def adopt_v2(conn: Any, response: dict[str, Any]) -> None: """Tell a v2 client connection that the handshake already happened.
``ClientSideConnection.initialize`` does two things at once: it moves the connection's local ``InitializationState`` to ``initialized``, and it sends the request. Every later method calls ``state.require(method)`` first, so a connection this module already negotiated is refused *locally* — and sending ``initialize`` again is refused by the agent, which allows exactly one per connection. The SDK exposes no way to adopt a negotiated connection, so this drives the same two state transitions ``initialize`` does, minus the wire. ``tests/unit/test_discover.py`` pins it, so an SDK that renames the private state fails a test instead of failing a session. """ parsed = v2.schema.InitializeResponse.model_validate(response) request = v2.schema.InitializeRequest( protocol_version=v2.PROTOCOL_VERSION, info=parsed.info ) conn._state.begin(request) conn._state.complete(parsed)
@asynccontextmanagerasync def agent_connection( server: AgentServer, cwd: str, *, timeout: float = PROBE_TIMEOUT,) -> AsyncIterator[Connection]: """Spawn ``server`` once and yield it, handshaked if we had to ask.
A declared protocol is honored without asking — crow's own entries know what they are — and the child is yielded un-initialized so the chosen stack handshakes itself. An undeclared one is asked, and the child is yielded already handshaked.
``env`` is an overlay on this process's environment, never a substitution: an entry's env is its extra variables, and dropping PATH or HOME would break the child's own subprocesses.
Raises: ProtocolError: the child died, stayed silent, or speaks a version this client does not. """ async with spawn_stdio_transport( *server.argv, env={**os.environ, **server.env}, cwd=cwd, ) as (reader, writer, proc): stderr: collections.deque = collections.deque(maxlen=STDERR_LINES) drainer = asyncio.create_task( _drain_stderr(proc, stderr), name="crow-discover-stderr" ) try: if server.protocol is None: response = await _handshake( writer, reader, proc, drainer, stderr, timeout ) version = response.get("protocolVersion") protocol = BY_VERSION.get(version) if protocol is None: raise ProtocolError( f"{server.title} answered initialize with protocol " f"version {version!r}; this client speaks " f"{', '.join(str(v) for v in sorted(BY_VERSION))}." ) logger.info("initialize: %s speaks protocol %s", server.title, version) yield Connection( protocol, reader, writer, proc, True, response, stderr, drainer ) else: yield Connection( server.protocol, reader, writer, proc, False, None, stderr, drainer ) finally: drainer.cancel() with contextlib.suppress(asyncio.CancelledError): await drainer
async def _drain_stderr(proc: Any, sink: collections.deque) -> None: """Keep the child's stderr pipe empty.
``spawn_stdio_transport`` gives the child a PIPE, and a child that logs more than the buffer holds blocks on the write and hangs with no error on either side. """ stream = getattr(proc, "stderr", None) if stream is None: return while True: line = await stream.readline() if not line: return sink.append(line.decode(errors="replace"))
async def _handshake( writer: Any, reader: Any, proc: Any, drainer: asyncio.Task, stderr: collections.deque, timeout: float,) -> dict[str, Any]: """Send the union initialize and return the agent's result object.""" request = { "jsonrpc": "2.0", "id": _REQUEST_ID, "method": "initialize", "params": handshake_params(), } try: payload = json.dumps(request, separators=(",", ":")) + "\n" writer.write(payload.encode()) await writer.drain() except OSError: # The child was already gone — a bad config or a missing module kills # an agent before it reads anything, and that is the commonest failure # there is. It gets the same error as one that dies after reading, # with its stderr on it, not a BrokenPipeError nobody can act on. raise ProtocolError( await _silent(proc, drainer, stderr, "died before it could be asked") ) from None
loop = asyncio.get_running_loop() deadline = loop.time() + timeout while True: left = deadline - loop.time() if left <= 0: raise ProtocolError( await _silent(proc, drainer, stderr, f"no answer within {timeout:g}s") ) try: line = await asyncio.wait_for(reader.readline(), left) except asyncio.TimeoutError: raise ProtocolError( await _silent(proc, drainer, stderr, f"no answer within {timeout:g}s") ) from None if not line: raise ProtocolError( await _silent(proc, drainer, stderr, "closed stdout without answering") ) stripped = line.strip() if not stripped: continue try: message = json.loads(stripped) except json.JSONDecodeError: # Not ours. An agent that banners on stdout is rude but survivable, # and refusing to look past it turns a cosmetic habit into a hang. continue if not isinstance(message, dict) or message.get("id") != _REQUEST_ID: continue if message.get("error") is not None: err = message["error"] or {} raise ProtocolError( f"initialize failed: {err.get('message')} " f"(code {err.get('code')})" ) result = message.get("result") if not isinstance(result, dict): raise ProtocolError(f"initialize returned {result!r}, not an object") return result
async def _silent( proc: Any, drainer: asyncio.Task, stderr: collections.deque, what: str) -> str: """The error for a child that did not answer, with its last words on it.""" if not drainer.done(): # The child is gone or silent; let the drain reach EOF so the tail is # whole rather than cut mid-line. with contextlib.suppress(Exception): await asyncio.wait_for(asyncio.shield(drainer), 2.0) if getattr(proc, "returncode", None) is None: # Nobody has reaped the child, and "it died" without the code it died # with is half an answer. One that closed both pipes is already gone # so this returns at once; a live but silent one costs the bound, # which is nothing next to the wait that got us here. with contextlib.suppress(Exception): await asyncio.wait_for(proc.wait(), 2.0) tail = "".join(stderr).strip() code = getattr(proc, "returncode", None) exit_note = "" if code is None else f"; child exited {code}" return f"agent {what}{exit_note}" + (f":\n{tail[-2000:]}" if tail else "")