Something went wrong. Try again.
MCP based ACP agent
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538"""Crow ACP Client - A transparent, observable agent client.
This is our microscope. Our Frankenstein monitor. Full visibility into:- AgentSession state (database)- Message flow (what we send/receive)- Agent behavior (logs, tool calls)
Usage: # Single-shot mode (default) - send prompt, get response, exit crow-client "list the files in this directory"
# Interactive mode - REPL loop crow-client -i
# Load existing session crow-client -s lumpy-energetic-hyrax-of-opportunity-77bcbd
# Combine flags crow-client -i -s exuberant-grinning-nautilus-of-sunshine-9d3d35
# Inspect database crow-client inspect crow-client inspect --session lumpy-energetic-hyrax-of-opportunity-77bcbd"""
import asyncioimport jsonimport sysimport uuidfrom datetime import datetime, timezonefrom pathlib import Pathfrom typing import Any
from acp import ( PROTOCOL_VERSION, Client, RequestError, connect_to_agent,)from acp.core import ClientSideConnectionfrom acp.schema import ( AgentMessageChunk, AgentThoughtChunk, AudioContentBlock, ClientCapabilities, CreateTerminalResponse, EmbeddedResourceContentBlock, ImageContentBlock, Implementation, KillTerminalResponse, PermissionOption, ReadTextFileResponse, ReleaseTerminalResponse, ResourceContentBlock, TerminalExitStatus, TerminalOutputResponse, TextContentBlock, ToolCall, ToolCallProgress, ToolCallStart, UsageUpdate, WaitForTerminalExitResponse, WriteTextFileResponse,)from crow_cli import __version__from crow_cli.acp_helpers import text_blockfrom crow_cli.client.subagent import spawn_agent_process, spawn_argv_processfrom crow_cli.client.terminal import TerminalManagerfrom rich.console import Consolefrom rich.panel import Panelfrom rich.table import Tablefrom rich.text import Text
# Tool kind -> icon mappingTOOL_ICONS = { "read": "📖", "edit": "✏️", "write": "📝", "delete": "🗑️", "move": "📦", "search": "🔍", "fetch": "🌐", "execute": "⚡", "other": "🔧",}
# Status -> indicator mappingSTATUS_ICONS = { "pending": "⏳", "in_progress": "🔄", "completed": "✅", "failed": "❌",}
class CrowClient(Client): """ Minimal ACP client that streams agent output beautifully. """
_last_chunk: AgentMessageChunk | AgentThoughtChunk | None = None _console: Console _tool_calls: dict[str, dict] = {} # Track tool call metadata by ID _task_list: list[dict] = []
def __init__(self, console: Console): self._console = console self._task_list = [] self._terminals = TerminalManager() self._json_mode = False self._json_pending: tuple[str, list[str]] | None = None
# -- JSONL output (-j): one event per line, pipeable to jq --
def _emit_json(self, **event: Any) -> None: print(json.dumps(event), flush=True)
def _buffer_json(self, kind: str, text: str) -> None: if self._json_pending is None or self._json_pending[0] != kind: self._flush_json() self._json_pending = (kind, []) self._json_pending[1].append(text)
def _flush_json(self) -> None: if self._json_pending: kind, parts = self._json_pending self._emit_json(type=kind, text="".join(parts)) self._json_pending = None
async def request_permission( self, options: list[PermissionOption], session_id: str, tool_call: ToolCall, **kwargs: Any, ) -> Any: raise RequestError.method_not_found("session/request_permission")
async def write_text_file( self, content: str, path: str, session_id: str, **kwargs: Any ) -> WriteTextFileResponse | None: raise RequestError.method_not_found("fs/write_text_file")
async def read_text_file( self, path: str, session_id: str, **kwargs: Any ) -> ReadTextFileResponse: raise RequestError.method_not_found("fs/read_text_file")
async def session_update( self, session_id: str, update: AgentMessageChunk | AgentThoughtChunk | ToolCallStart | ToolCallProgress, **kwargs: Any, ) -> None: """Handle streaming updates from the agent.""" if self._json_mode: if isinstance(update, AgentMessageChunk): self._buffer_json("message", self._extract_text(update.content)) elif isinstance(update, AgentThoughtChunk): self._buffer_json("thinking", self._extract_text(update.content)) elif isinstance(update, ToolCallStart): self._flush_json() self._emit_json( type="tool_call", event="start", tool_call_id=getattr(update, "tool_call_id", None), title=update.title, kind=update.kind, status=update.status, ) elif isinstance(update, ToolCallProgress): self._flush_json() self._emit_json( type="tool_call", event="progress", tool_call_id=getattr(update, "tool_call_id", None), title=update.title, kind=update.kind, status=update.status, ) elif isinstance(update, UsageUpdate): self._flush_json() self._emit_json(type="usage", used=update.used, size=update.size) return
if isinstance(update, AgentMessageChunk): if ( self._last_chunk is None or isinstance(self._last_chunk, AgentThoughtChunk) or isinstance(self._last_chunk, (ToolCallStart, ToolCallProgress)) ): # Transition to message output self._console.print() self._console.rule("[bold purple]Assistant[/bold purple]") self._console.print()
self._last_chunk = update content = update.content text = self._extract_text(content) self._console.print(text, end="", style="purple", highlight=False)
elif isinstance(update, AgentThoughtChunk): if ( self._last_chunk is None or isinstance(self._last_chunk, AgentMessageChunk) or isinstance(self._last_chunk, (ToolCallStart, ToolCallProgress)) ): # Transition to thinking output self._console.print() self._console.rule("[dim green]Thinking[/dim green]") self._console.print()
self._last_chunk = update content = update.content text = self._extract_text(content) self._console.print(text, end="", style="dim green italic", highlight=False)
elif isinstance(update, ToolCallStart): # Tool call started self._last_chunk = update icon = TOOL_ICONS.get(update.kind, TOOL_ICONS["other"]) status = STATUS_ICONS.get(update.status, "⏳") self._console.print(f"\n{status} {icon} {update.title}", style="cyan")
elif isinstance(update, ToolCallProgress): # Tool call progress/completion self._last_chunk = update icon = TOOL_ICONS.get(update.kind, TOOL_ICONS["other"]) status = STATUS_ICONS.get(update.status, "⏳") style = ( "green" if update.status == "completed" else "red" if update.status == "failed" else "yellow" ) self._console.print( f"{status} {icon} {update.title or 'tool'}", style=style )
def _extract_text(self, content: Any) -> str: """Extract text from various content block types.""" if isinstance(content, TextContentBlock): return content.text elif isinstance(content, ImageContentBlock): return "<image>" elif isinstance(content, AudioContentBlock): return "<audio>" elif isinstance(content, ResourceContentBlock): return content.uri or "<resource>" elif isinstance(content, EmbeddedResourceContentBlock): return "<resource>" elif isinstance(content, dict): return content.get("text", "<content>") else: return "<content>"
async def ext_method(self, method: str, params: dict) -> dict: if method == "task/read": return self._task_read() elif method == "task/write": return self._task_write(params) raise RequestError.method_not_found(method)
async def ext_notification(self, method: str, params: dict) -> None: raise RequestError.method_not_found(method)
# ─── Task management (client-side) ────────────────────────────────────
def _task_read(self) -> dict: return { "tasks": self._task_list, "summary": self._format_task_summary(self._task_list), }
def _task_write(self, params: dict) -> dict: todos = params.get("todos", []) now = datetime.now(timezone.utc).isoformat() tasks = [] for i, todo in enumerate(todos): tasks.append({ "id": str(uuid.uuid4()), "title": todo.get("content") or todo.get("title") or f"Task {i + 1}", "description": None, "status": todo.get("status", "pending"), "priority": todo.get("priority", "medium"), "assigned_to": todo.get("assignedTo"), "created_at": now, "updated_at": now, }) self._task_list = tasks return {"tasks": tasks}
# ─── Client-side terminal (ACP terminal/* methods) ──────────────────── # The agent routes its `terminal` tool here once we advertise the # `terminal` capability (see connect_client). Commands run in a real PTY # so exit codes are correct and behavior roughly matches the IDE's # client-side terminals (lapce/zed).
async def create_terminal( self, command: str, session_id: str, args: list[str] | None = None, cwd: str | None = None, env: list | None = None, output_byte_limit: int | None = None, **kwargs: Any, ) -> CreateTerminalResponse: env_dict = {e.name: e.value for e in (env or [])} terminal_id = self._terminals.create( command, cwd, env_dict, output_byte_limit ) return CreateTerminalResponse(terminal_id=terminal_id)
async def terminal_output( self, session_id: str, terminal_id: str, **kwargs: Any ) -> TerminalOutputResponse: term = self._terminals.get(terminal_id) if term is None: return TerminalOutputResponse(output="", truncated=False) output, truncated = term.output() exit_status = None if term.exited(): exit_status = TerminalExitStatus( exit_code=term.exit_code, signal=term.signal_name ) return TerminalOutputResponse( output=output, truncated=truncated, exit_status=exit_status )
async def wait_for_terminal_exit( self, session_id: str, terminal_id: str, **kwargs: Any ) -> WaitForTerminalExitResponse: term = self._terminals.get(terminal_id) if term is None: return WaitForTerminalExitResponse(exit_code=None, signal=None) exit_code, signal_name = await term.wait_exit() return WaitForTerminalExitResponse(exit_code=exit_code, signal=signal_name)
async def kill_terminal( self, session_id: str, terminal_id: str, **kwargs: Any ) -> KillTerminalResponse: term = self._terminals.get(terminal_id) if term is not None: term.kill() return KillTerminalResponse()
async def release_terminal( self, session_id: str, terminal_id: str, **kwargs: Any ) -> ReleaseTerminalResponse: self._terminals.release(terminal_id) return ReleaseTerminalResponse()
async def spawn_agent( self, cwd: str, config_dir: Path | None = None, model: str | None = None, config_file: Path | None = None, argv: list[str] | None = None, env: dict[str, str] | None = None, ) -> asyncio.subprocess.Process: """Spawn the agent subprocess (shared machinery with the task system's SubagentDriver — crow_cli.client.subagent).
``argv`` overrides everything else: a resolved `agent_servers` entry is an arbitrary command, and crow's own flags mean nothing to it. """ try: if argv is not None: proc = await spawn_argv_process(argv, cwd, env=env) else: proc = await spawn_agent_process( cwd, config_dir=config_dir, model=model, config_file=config_file ) except RuntimeError as e: self._console.print(f"[red]{e}[/red]") raise SystemExit(1) # Store stderr reader for later error reporting proc._stderr_reader = asyncio.create_task(proc.stderr.read()) return proc
async def send_prompt( self, conn: ClientSideConnection, session_id: str, prompt: str, ) -> None: """Send a single prompt and wait for completion, then nag on incomplete tasks.""" if not self._json_mode: self._console.print() self._console.print( Panel( f"[bold]{prompt}[/bold]", title="[cyan]You[/cyan]", border_style="cyan" ) ) self._console.print()
await conn.prompt( session_id=session_id, prompt=[text_block(prompt)], )
if not self._json_mode: self._console.print()
# Nag loop: if the agent left incomplete tasks, keep prompting # until they're all done (or safety limit hit). for _ in range(50): incomplete = [ t for t in self._task_list if t["status"] in ("pending", "in_progress") ] if not incomplete: break
task_lines = "\n".join( f"- [{t['status']}] {t['title']}" for t in incomplete ) nag = ( f"You have {len(incomplete)} incomplete task(s):\n\n" f"{task_lines}\n\n" f'Call task_write with the full todos list, updating statuses ' f'for completed tasks to "completed".' )
if not self._json_mode: self._console.print() self._console.rule("[dim yellow]Nag[/dim yellow]") self._console.print()
await conn.prompt( session_id=session_id, prompt=[text_block(nag)], )
if not self._json_mode: self._console.print()
async def interactive_loop( self, conn: ClientSideConnection, session_id: str ) -> None: """Interactive REPL loop.""" self._console.print( Panel( "[bold]Crow Interactive Mode[/bold]\n\n" "Type your message and press Enter to send.\n" "Press Ctrl+D or Ctrl+C to exit.", title="[magenta]🪶 Crow Client[/magenta]", border_style="magenta", ) )
while True: try: # Use rich prompt self._console.print() prompt_text = Text("crow> ", style="bold magenta") line = await asyncio.get_running_loop().run_in_executor( None, lambda: self._console.input(prompt_text) ) except EOFError: self._console.print("\n[yellow]Goodbye![/yellow]") break except KeyboardInterrupt: self._console.print("\n[yellow]Goodbye![/yellow]") break
if not line.strip(): continue
await self.send_prompt(conn, session_id, line)
async def connect_client( proc: asyncio.subprocess.Process, client: CrowClient, initialized: bool = False,) -> ClientSideConnection: """Initialize ACP connection to agent.
``initialized`` says the caller already handshaked. Protocol discovery sends the one ``initialize`` both versions accept and reads the chosen version back, so a connection that arrives here already negotiated is one this function must not negotiate again. """ try: conn = connect_to_agent( client, proc.stdin, proc.stdout, # session/fork is UNSTABLE — both ends must opt in or the router # answers method_not_found. use_unstable_protocol=True, )
if not initialized: await conn.initialize( protocol_version=PROTOCOL_VERSION, # terminal=False: don't advertise the client-side PTY, so the # agent's `terminal` tool falls through to the crow-mcp MCP # terminal tool (agent-owned execution) instead of routing to # create_terminal below. client_capabilities=ClientCapabilities(terminal=False), client_info=Implementation( name="crow-client", title="Crow Client", version=__version__, ), ) return conn except Exception as e: # If connection fails, try to read stderr to show the actual error try: if hasattr(proc, "_stderr_reader") and not proc._stderr_reader.done(): # Wait a moment for stderr to be available await asyncio.sleep(0.1) stderr_output = await proc._stderr_reader if stderr_output: client._console.print() client._console.print("[red]═══ Agent subprocess failed ═══[/red]") client._console.print() client._console.print(stderr_output.decode()) client._console.print() client._console.print( "[yellow]The agent subprocess exited with an error. " "The traceback above shows what went wrong.[/yellow]" ) except Exception: # If we can't read stderr, just continue with the original error pass raise e