a2acode 0.4.0__py3-none-any.whl

a2acode/cli.py

@@ -0,0 +1,295 @@
+"""Command line interface.
+
+Three commands, enough to run the server and exercise it by hand:
+
+    a2acode serve        start the A2A server
+    a2acode call TEXT    send a message and print the streamed events
+    a2acode card         fetch and print the agent card
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import shlex
+from uuid import uuid4
+
+import httpx
+import typer
+import uvicorn
+
+app = typer.Typer(
+    add_completion=False,
+    help="Serve a coding agent (Claude Code and other ACP agents) over A2A.",
+)
+
+# Human-facing card names for the ACP agents shipped with a launch preset.
+_AGENT_CARD_NAMES = {
+    "claude": "Claude Code",
+    "gemini": "Gemini CLI",
+    "codex": "Codex",
+}
+
+
+def _validate_permission_mode(value: str | None) -> None:
+    """Reject an invalid --permission-mode at startup.
+
+    Without this the bad value flows into ClaudeAgentOptions and only surfaces as
+    a generic "Claude Code run failed" on the first request, after the server is
+    already up. The valid set is read from the SDK's own literal so it cannot
+    drift; the import stays lazy so the echo backend needs no SDK at hand.
+
+    Skip validation rather than block startup when the accepted set cannot be
+    determined: the SDK absent (echo without it installed), or PermissionMode no
+    longer a Literal so get_args returns an empty tuple. In both cases the SDK
+    itself still rejects a genuinely bad value at run time.
+    """
+    if value is None:
+        return
+    from typing import get_args
+
+    try:
+        from claude_agent_sdk import PermissionMode
+    except ImportError:
+        return
+
+    # Keep only string members, so a non-Literal form (e.g. a Union with
+    # non-string args) neither breaks the join below nor is matched against.
+    valid = [v for v in get_args(PermissionMode) if isinstance(v, str)]
+    if valid and value not in valid:
+        raise typer.BadParameter(
+            f"invalid --permission-mode {value!r}; expected one of {', '.join(valid)}"
+        )
+
+
+def _local_url(host: str, port: int) -> str:
+    shown = "localhost" if host in ("0.0.0.0", "::") else host
+    return f"http://{shown}:{port}/"
+
+
+@app.command()
+def serve(
+    backend: str = typer.Option(
+        "acp", help="Backend: 'acp' (any ACP agent), 'claude' (Claude SDK), 'echo'."
+    ),
+    agent: str = typer.Option(
+        "claude",
+        help="ACP agent the 'acp' backend fronts: 'claude', 'gemini', 'codex', "
+        "or any agent reachable via --agent-command.",
+    ),
+    agent_command: str = typer.Option(
+        None,
+        help="Explicit launch command for an ACP agent, overriding --agent's "
+        "preset (e.g. 'npx -y @zed-industries/claude-agent-acp').",
+    ),
+    cwd: str = typer.Option(".", help="Project directory the coding agent works in."),
+    host: str = typer.Option("127.0.0.1"),
+    port: int = typer.Option(9100),
+    permission_mode: str = typer.Option(
+        None,
+        help="Claude permission mode (e.g. acceptEdits). Omit to use defaults.",
+    ),
+    max_budget_usd: float = typer.Option(
+        None, help="Hard cost ceiling per run, in USD."
+    ),
+    sign_key: str = typer.Option(
+        None,
+        help="Path to a file holding the signing key (a PEM private key, or a "
+        "shared secret for HS256) used to sign the agent card so callers can "
+        "verify who issued it.",
+    ),
+    sign_kid: str = typer.Option(
+        None, help="Key id (kid) recorded in the card signature."
+    ),
+    sign_alg: str = typer.Option(
+        "ES256", help="JWS algorithm for the card signature (e.g. ES256, RS256)."
+    ),
+    auth_token_file: str = typer.Option(
+        None,
+        help="Path to a file holding a bearer token. When set, callers must "
+        "send 'Authorization: Bearer <token>' and the card advertises it.",
+    ),
+) -> None:
+    """Start the A2A server."""
+    from pathlib import Path
+
+    from .backends import make_backend
+    from .server import build_app
+
+    kwargs: dict[str, object] = {}
+    card_name = None
+    if backend == "acp":
+        kwargs = {"agent": agent, "cwd": cwd}
+        if agent_command:
+            try:
+                parts = shlex.split(agent_command)
+            except ValueError as e:
+                raise typer.BadParameter(f"invalid --agent-command: {e}") from e
+            if not parts:
+                raise typer.BadParameter("--agent-command is empty or whitespace-only")
+            kwargs["command"], kwargs["args"] = parts[0], parts[1:]
+            # The identity of an arbitrary command is unknown, so don't advertise
+            # it under a preset name (which would default to "Claude Code").
+            card_name = "Coding Agent"
+        else:
+            card_name = _AGENT_CARD_NAMES.get(agent, agent.capitalize())
+    elif backend == "claude":
+        # Claude-only flag: validate it only on the Claude path so an ACP run
+        # isn't rejected for a flag it never uses.
+        _validate_permission_mode(permission_mode)
+        kwargs = {
+            "cwd": cwd,
+            "permission_mode": permission_mode,
+            "max_budget_usd": max_budget_usd,
+        }
+    drv = make_backend(backend, **kwargs)
+
+    card_signer = None
+    if sign_kid and not sign_key:
+        raise typer.BadParameter("--sign-key is required when --sign-kid is set")
+    if sign_key:
+        if not sign_kid:
+            raise typer.BadParameter("--sign-kid is required when --sign-key is set")
+        from .card import signer_from_key_file
+
+        try:
+            card_signer = signer_from_key_file(sign_key, kid=sign_kid, alg=sign_alg)
+        except (OSError, ValueError) as e:
+            raise typer.BadParameter(f"invalid --sign-key: {e}") from e
+
+    auth_token = None
+    if auth_token_file:
+        try:
+            auth_token = Path(auth_token_file).read_text(encoding="utf-8").strip()
+        except (OSError, ValueError) as e:
+            raise typer.BadParameter(f"invalid --auth-token-file: {e}") from e
+        if not auth_token:
+            raise typer.BadParameter("--auth-token-file is empty")
+
+    asgi_app = build_app(
+        drv,
+        url=_local_url(host, port),
+        card_name=card_name,
+        card_signer=card_signer,
+        auth_token=auth_token,
+    )
+    label = f"{backend}:{agent}" if backend == "acp" else backend
+    typer.echo(f"a2acode: backend={label} card={_local_url(host, port)}")
+    uvicorn.run(asgi_app, host=host, port=port, log_level="info")
+
+
+@app.command()
+def call(
+    text: str = typer.Argument(..., help="Message to send to the agent."),
+    url: str = typer.Option("http://localhost:9100/", help="Server URL."),
+    context: str = typer.Option(None, help="contextId to continue a conversation."),
+    task: str = typer.Option(
+        None, help="taskId to answer an input-required prompt (e.g. 'allow')."
+    ),
+) -> None:
+    """Send a message and print the streamed task events."""
+    asyncio.run(_call(text, url, context, task))
+
+
+@app.command()
+def card(url: str = typer.Option("http://localhost:9100/")) -> None:
+    """Fetch and print the agent card."""
+    base = url.rstrip("/")
+    resp = httpx.get(f"{base}/.well-known/agent-card.json", timeout=10)
+    resp.raise_for_status()
+    typer.echo(json.dumps(resp.json(), indent=2))
+
+
+def _parts_text(parts) -> str:
+    return "".join(p.text for p in parts if p.text)
+
+
+def _state_name(state) -> str:
+    from a2a.types import TaskState
+
+    return TaskState.Name(state).removeprefix("TASK_STATE_").lower()
+
+
+async def _call(text: str, url: str, context: str | None, task: str | None) -> None:
+    from a2a.client import create_client
+    from a2a.client.client import ClientConfig
+    from a2a.types import Message, Part, Role, SendMessageRequest
+
+    message = Message(
+        message_id=uuid4().hex,
+        role=Role.ROLE_USER,
+        parts=[Part(text=text)],
+    )
+    if context:
+        message.context_id = context
+    if task:
+        message.task_id = task
+
+    ids = {"task": task or "", "context": context or ""}
+    streaming = False
+    timeout = httpx.Timeout(600.0, connect=10.0)
+    async with httpx.AsyncClient(timeout=timeout) as http:
+        client = await create_client(
+            url, ClientConfig(streaming=True, httpx_client=http)
+        )
+        try:
+            request = SendMessageRequest(message=message)
+            async for event in client.send_message(request):
+                which = event.WhichOneof("payload")
+                if which == "task":
+                    t = event.task
+                    ids["task"], ids["context"] = t.id, t.context_id
+                    typer.echo(f"task {t.id}")
+                    typer.echo(f"context {t.context_id}\n")
+                elif which == "status_update":
+                    s = event.status_update.status
+                    line = _parts_text(s.message.parts) if s.message else ""
+                    state = _state_name(s.state)
+                    if streaming and state != "working":
+                        typer.echo("")
+                        streaming = False
+                    if state == "working" and line:
+                        typer.echo(f"  · {line}")
+                    elif state == "input_required":
+                        _render_input_required(line, ids, url)
+                    elif state != "working":
+                        meta = _format_meta(s.message) if s.message else ""
+                        typer.echo(f"[{state}] {meta}".rstrip())
+                elif which == "artifact_update":
+                    streaming = True
+                    parts = event.artifact_update.artifact.parts
+                    typer.echo(_parts_text(parts), nl=False)
+                elif which == "message":
+                    typer.echo(_parts_text(event.message.parts))
+        finally:
+            closer = client.close()
+            if closer is not None:
+                await closer
+
+
+def _render_input_required(line: str, ids: dict[str, str], url: str) -> None:
+    typer.echo(f"[input-required] {line}")
+    follow = (
+        f'a2acode call "allow" --task {ids["task"]} '
+        f"--context {ids['context']} --url {url}"
+    )
+    typer.echo(f"  reply: {follow}")
+    typer.echo('  (or "deny" to refuse)')
+
+
+def _format_meta(msg) -> str:
+    from google.protobuf.json_format import MessageToDict
+
+    meta = MessageToDict(msg).get("metadata") if msg else None
+    if not meta:
+        return ""
+    bits = []
+    if "cost_usd" in meta:
+        bits.append(f"${meta['cost_usd']}")
+    if "num_turns" in meta:
+        bits.append(f"{meta['num_turns']} turns")
+    return " · ".join(bits)
+
+
+if __name__ == "__main__":
+    app()

a2acode/executor.py

@@ -0,0 +1,365 @@
+"""Protocol mapping.
+
+Translates a backend's normalized event stream into A2A task lifecycle events:
+
+    text                -> a streamed artifact (append / last_chunk)
+    tool use            -> a working-state status update describing the action
+    file change         -> a named artifact carrying the diff
+    permission request  -> an input-required pause the caller answers
+    result              -> run metadata on the completion message + continuity
+
+A task that pauses on a permission request keeps its backend session alive in a
+registry; the caller's follow-up message (same task id) carries the decision and
+resumes the same session. Session ids are mapped to the A2A ``context_id`` so a
+new task in the same context resumes the same Claude conversation.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from dataclasses import dataclass, field
+from uuid import uuid4
+
+from a2a.server.agent_execution import AgentExecutor, RequestContext
+from a2a.server.events import EventQueue
+from a2a.server.tasks import TaskUpdater
+from a2a.types import Part, Task, TaskState, TaskStatus
+
+from .backends.base import (
+    Backend,
+    FileChange,
+    PermissionDecision,
+    PermissionRequest,
+    Result,
+    RunRequest,
+    TextDelta,
+    ToolUse,
+)
+from .backends.session import BackendSession
+from .tracing import span
+
+logger = logging.getLogger(__name__)
+
+_ALLOW_WORDS = {"allow", "yes", "y", "approve", "ok", "accept", "grant"}
+
+# Bound the in-memory maps so a long-running server cannot grow without limit
+# (e.g. from many contexts, or tasks left paused on a permission and never
+# answered). The continuity cache (_MAX_CONTEXTS) evicts its least-recently-used
+# entry; the live-session map (_MAX_LIVE) evicts a parked session first, else the
+# oldest entry.
+_MAX_CONTEXTS = 4096
+_MAX_LIVE = 256
+
+
+@dataclass
+class _Stream:
+    """Response-stream state for a task, persisted across permission pauses."""
+
+    artifact_id: str
+    chunks: list[str] = field(default_factory=list)
+    pending: str | None = None
+    sent_first: bool = False
+    metadata: dict[str, object] = field(default_factory=dict)
+
+
+def _build_prompt(context: RequestContext) -> str:
+    """Assemble the prompt from every part of the incoming message.
+
+    Text parts are concatenated; file, URL, and structured-data parts are
+    surfaced to Claude as labelled references so an attachment is not silently
+    dropped on the floor.
+    """
+    message = getattr(context, "message", None)
+    parts = getattr(message, "parts", None) if message is not None else None
+    if not parts:
+        return context.get_user_input() or ""
+
+    texts: list[str] = []
+    refs: list[str] = []
+    for part in parts:
+        which = part.WhichOneof("content")
+        if which == "text":
+            if part.text:
+                texts.append(part.text)
+        elif which == "url":
+            label = part.filename or part.url
+            refs.append(f"[attached {label} ({part.media_type or 'file'}): {part.url}]")
+        elif which == "raw":
+            name = part.filename or "unnamed"
+            kind = part.media_type or "application/octet-stream"
+            refs.append(f"[attached file {name} ({kind}, {len(part.raw)} bytes)]")
+        elif which == "data":
+            refs.append(f"[attached data ({part.media_type or 'application/json'})]")
+
+    prompt = "\n".join(texts)
+    if refs:
+        prompt = f"{prompt}\n\n" + "\n".join(refs)
+    return prompt.strip()
+
+
+def _describe_tool(event: ToolUse) -> str:
+    """A short, human-readable line for a tool invocation."""
+    i = event.tool_input
+    if event.name == "Bash":
+        return f"$ {str(i.get('command', '')).strip()[:120]}"
+    path = i.get("file_path") or i.get("path") or i.get("pattern")
+    if path:
+        return f"{event.name} {path}"
+    return event.name
+
+
+class ClaudeCodeExecutor(AgentExecutor):
+    def __init__(self, backend: Backend) -> None:
+        self._backend = backend
+        # context_id -> claude session id, for resuming a new task in a context.
+        self._session_ids: dict[str, str] = {}
+        # task_id -> live session, for resuming a task paused on a permission.
+        self._live: dict[str, BackendSession] = {}
+        # task_id -> response-stream state, kept across permission pauses.
+        self._streams: dict[str, _Stream] = {}
+        # Serializes capacity eviction with new-session registration so a burst
+        # of concurrent first-turn requests cannot each see a slot freed by one
+        # eviction and collectively overshoot _MAX_LIVE. Uncontended below
+        # capacity, where _evict_if_full returns without awaiting.
+        self._admit_lock = asyncio.Lock()
+
+    async def execute(self, context: RequestContext, event_queue: EventQueue) -> None:
+        # span() drops None-valued attributes, so no fallbacks are needed; the
+        # ids are populated by the SDK before execute is called.
+        with span(
+            "a2acode.execute",
+            **{
+                "a2a.task_id": context.task_id,
+                "a2a.context_id": context.context_id,
+                "a2acode.backend": self._backend.name,
+            },
+        ):
+            await self._execute(context, event_queue)
+
+    async def _execute(self, context: RequestContext, event_queue: EventQueue) -> None:
+        task_id, context_id = context.task_id, context.context_id
+        assert task_id is not None and context_id is not None
+        updater = TaskUpdater(event_queue, task_id, context_id)
+        session = self._live.get(task_id)
+
+        if session is None:
+            # The stream MUST open with a Task object before any status update.
+            await event_queue.enqueue_event(
+                Task(
+                    id=task_id,
+                    context_id=context_id,
+                    status=TaskStatus(state=TaskState.TASK_STATE_SUBMITTED),
+                )
+            )
+            await updater.start_work()
+            request = RunRequest(
+                prompt=_build_prompt(context),
+                context_id=context_id,
+                resume=self._session_ids.get(context_id),
+            )
+            async with self._admit_lock:
+                await self._evict_if_full()
+                session = BackendSession()
+                session.start(lambda s: self._backend.drive(s, request))
+                self._live[task_id] = session
+        else:
+            # Follow-up to an input-required pause: the message is the decision.
+            # Guard against a concurrent message arriving while the task is still
+            # running; resolving and pumping a non-parked session would put two
+            # consumers on the same queue and lose events.
+            if not session.is_parked:
+                raise RuntimeError(
+                    f"task {task_id} is already running and not awaiting input"
+                )
+            await updater.start_work()
+            session.resolve(self._decision(context, session))
+
+        await self._pump(updater, task_id, context_id, session)
+
+    async def _pump(
+        self,
+        updater: TaskUpdater,
+        task_id: str,
+        context_id: str,
+        session: BackendSession,
+    ) -> None:
+        # One stream of artifacts/text per task, kept across permission pauses so
+        # the response stays a single artifact and the completion text is whole.
+        stream = self._streams.setdefault(task_id, _Stream(artifact_id=uuid4().hex))
+
+        async def flush(text: str, *, last: bool) -> None:
+            await updater.add_artifact(
+                [Part(text=text)],
+                artifact_id=stream.artifact_id,
+                name="response",
+                append=stream.sent_first,
+                last_chunk=last,
+            )
+            stream.sent_first = True
+
+        try:
+            async for event in session.drain():
+                if isinstance(event, TextDelta):
+                    if stream.pending is not None:
+                        stream.chunks.append(stream.pending)
+                        await flush(stream.pending, last=False)
+                    stream.pending = event.text
+                elif isinstance(event, ToolUse):
+                    await updater.update_status(
+                        TaskState.TASK_STATE_WORKING,
+                        message=updater.new_agent_message(
+                            [Part(text=_describe_tool(event))]
+                        ),
+                    )
+                elif isinstance(event, FileChange):
+                    await updater.add_artifact(
+                        [Part(text=event.diff, media_type="text/x-diff")],
+                        name=event.path,
+                    )
+                elif isinstance(event, PermissionRequest):
+                    if stream.pending is not None:
+                        stream.chunks.append(stream.pending)
+                        await flush(stream.pending, last=False)
+                        stream.pending = None
+                    await self._request_input(updater, event)
+                elif isinstance(event, Result):
+                    stream.metadata = self._result_metadata(event)
+                    if event.session_id:
+                        self._remember_session(context_id, event.session_id)
+        except asyncio.CancelledError:
+            # Client disconnected / timed out: drop the session and its runner
+            # instead of leaking them. Synchronous cleanup since we are cancelled.
+            self._live.pop(task_id, None)
+            self._streams.pop(task_id, None)
+            session.abort()
+            raise
+        except Exception:  # noqa: BLE001 (surface failure without leaking details)
+            logger.exception("backend run failed for task %s", task_id)
+            await self._discard(task_id, session)
+            await updater.failed(
+                message=updater.new_agent_message(
+                    [Part(text="Claude Code run failed; see server logs.")]
+                )
+            )
+            return
+
+        if not session.done:
+            # Paused on a permission request; keep the stream for the follow-up.
+            return
+
+        if session.evicted:
+            # The session was dropped to free a capacity slot while still
+            # running, so its drain ended on the cancellation sentinel rather
+            # than a real result. Fail the task instead of presenting the partial
+            # buffer as a completed run.
+            await updater.failed(
+                message=updater.new_agent_message(
+                    [Part(text="Task evicted to free server capacity.")]
+                )
+            )
+            return
+
+        if stream.pending is not None:
+            stream.chunks.append(stream.pending)
+            await flush(stream.pending, last=True)
+        elif stream.sent_first:
+            # No new text this turn, but earlier chunks went out, so close the
+            # artifact so it is not left without a final chunk.
+            await flush("", last=True)
+
+        await self._discard(task_id, session)
+        full_text = "".join(stream.chunks) or "(no text output)"
+        await updater.complete(
+            message=updater.new_agent_message(
+                [Part(text=full_text)], metadata=stream.metadata or None
+            )
+        )
+
+    async def cancel(self, context: RequestContext, event_queue: EventQueue) -> None:
+        task_id, context_id = context.task_id, context.context_id
+        assert task_id is not None and context_id is not None
+        self._streams.pop(task_id, None)
+        session = self._live.pop(task_id, None)
+        if session is not None:
+            await session.close()
+        updater = TaskUpdater(event_queue, task_id, context_id)
+        await updater.cancel()
+
+    @staticmethod
+    async def _request_input(updater: TaskUpdater, event: PermissionRequest) -> None:
+        line = event.description or event.tool_name
+        await updater.requires_input(
+            message=updater.new_agent_message(
+                [Part(text=f"Permission requested for {event.tool_name}: {line}")],
+                metadata={
+                    "a2acode_permission": {
+                        "request_id": event.request_id,
+                        "tool": event.tool_name,
+                        "input": event.tool_input,
+                    }
+                },
+            )
+        )
+
+    @staticmethod
+    def _decision(
+        context: RequestContext, session: BackendSession
+    ) -> PermissionDecision:
+        text = (context.get_user_input() or "").strip().lower()
+        allow = text in _ALLOW_WORDS or text.startswith("allow")
+        return PermissionDecision(
+            request_id=session.last_request_id or "",
+            allow=allow,
+            message="" if allow else "Denied by A2A caller",
+        )
+
+    def _remember_session(self, context_id: str, session_id: str) -> None:
+        # Re-insert so the most recently used context moves to the end of the
+        # dict: a plain reassignment keeps an existing key in its original
+        # position, which would let an actively reused context be evicted before
+        # an idle, more-recently-created one. Pop-then-set makes eviction LRU.
+        self._session_ids.pop(context_id, None)
+        self._session_ids[context_id] = session_id
+        while len(self._session_ids) > _MAX_CONTEXTS:
+            oldest = next(iter(self._session_ids))
+            del self._session_ids[oldest]
+
+    async def _evict_if_full(self) -> None:
+        """Make room when at capacity.
+
+        Prefer evicting a parked session (an input-required task the caller
+        abandoned without answering) over one still actively running: a parked
+        task's ``_pump`` has already returned, so dropping it just closes a
+        stalled session. Only when nothing is parked do we fall back to the
+        oldest entry, which is a running task; mark it evicted so its ``_pump``
+        fails the task rather than completing it with partial output.
+        """
+        while len(self._live) >= _MAX_LIVE:
+            # Fall back lazily to the oldest entry: passing next(iter(...)) as the
+            # default would evaluate it even when a parked session is found.
+            victim = next((tid for tid, s in self._live.items() if s.is_parked), None)
+            if victim is None:
+                victim = next(iter(self._live))
+            logger.warning("evicting live task %s at capacity", victim)
+            session = self._live[victim]
+            session.evicted = True
+            await self._discard(victim, session)
+
+    async def _discard(self, task_id: str, session: BackendSession) -> None:
+        self._live.pop(task_id, None)
+        self._streams.pop(task_id, None)
+        await session.close()
+
+    @staticmethod
+    def _result_metadata(event: Result) -> dict[str, object]:
+        meta: dict[str, object] = {}
+        if event.session_id is not None:
+            meta["claude_session_id"] = event.session_id
+        if event.cost_usd is not None:
+            meta["cost_usd"] = event.cost_usd
+        if event.num_turns is not None:
+            meta["num_turns"] = event.num_turns
+        if event.usage is not None:
+            meta["usage"] = event.usage
+        return meta