a2acode 0.4.0__py3-none-any.whl

a2acode/__init__.py

@@ -0,0 +1,9 @@
+"""Run Claude Code as an A2A protocol agent server."""
+
+from __future__ import annotations
+
+from .card import build_card
+from .executor import ClaudeCodeExecutor
+from .server import build_app
+
+__all__ = ["build_app", "build_card", "ClaudeCodeExecutor"]

a2acode/auth.py

@@ -0,0 +1,87 @@
+"""Caller authentication.
+
+A server that answers on behalf of other agents should be able to require a
+credential. This is a pure-ASGI middleware (not ``BaseHTTPMiddleware``) so it
+passes the request straight through to the inner app when authorized, leaving
+streaming and server-sent events untouched; it only short-circuits with a 401
+when a token is missing or wrong.
+
+The agent card stays public: a caller fetches it to learn the auth scheme
+*before* it has a credential, so discovery paths under ``/.well-known/`` are
+exempt while the task endpoints are protected.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+from collections.abc import Awaitable, Callable
+
+Receive = Callable[[], Awaitable[dict]]
+Send = Callable[[dict], Awaitable[None]]
+ASGIApp = Callable[[dict, Receive, Send], Awaitable[None]]
+
+_PUBLIC_PREFIXES = ("/.well-known/",)
+
+
+class BearerAuthMiddleware:
+    """Require ``Authorization: Bearer <token>`` on non-discovery requests."""
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        *,
+        token: str,
+        public_prefixes: tuple[str, ...] = _PUBLIC_PREFIXES,
+    ) -> None:
+        if not token.strip():
+            raise ValueError("auth token must not be empty")
+        self.app = app
+        # Compare SHA-256 digests rather than the tokens themselves: the
+        # constant-time compare is then always over a fixed 32 bytes, so it
+        # cannot leak the token length, and the raw secret is not kept around.
+        self._token_digest = hashlib.sha256(token.encode("utf-8")).digest()
+        self._public = public_prefixes
+
+    async def __call__(self, scope: dict, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http" or self._is_public(scope.get("path", "")):
+            await self.app(scope, receive, send)
+            return
+        if self._authorized(scope):
+            await self.app(scope, receive, send)
+            return
+        await self._reject(send)
+
+    def _is_public(self, path: str) -> bool:
+        return any(path.startswith(p) for p in self._public)
+
+    def _authorized(self, scope: dict) -> bool:
+        # Scan the headers list for the one we need instead of materializing a
+        # dict on every request.
+        raw = b""
+        for key, value in scope.get("headers") or []:
+            if key == b"authorization":
+                raw = value
+                break
+        # split(None, 1) tolerates extra whitespace between scheme and token.
+        parts = raw.split(None, 1)
+        if len(parts) != 2 or parts[0].lower() != b"bearer":
+            return False
+        presented = hashlib.sha256(parts[1].strip()).digest()
+        return hmac.compare_digest(presented, self._token_digest)
+
+    @staticmethod
+    async def _reject(send: Send) -> None:
+        body = b'{"error": "unauthorized"}'
+        await send(
+            {
+                "type": "http.response.start",
+                "status": 401,
+                "headers": [
+                    (b"content-type", b"application/json"),
+                    (b"www-authenticate", b"Bearer"),
+                    (b"content-length", str(len(body)).encode()),
+                ],
+            }
+        )
+        await send({"type": "http.response.body", "body": body})

a2acode/backends/__init__.py

@@ -0,0 +1,51 @@
+"""Backends drive Claude Code and emit normalized events."""
+
+from __future__ import annotations
+
+from .base import (
+    Backend,
+    BackendEvent,
+    FileChange,
+    PermissionDecision,
+    PermissionRequest,
+    Result,
+    RunRequest,
+    TextDelta,
+    ToolUse,
+)
+from .echo import EchoBackend
+from .session import BackendSession
+
+__all__ = [
+    "Backend",
+    "BackendEvent",
+    "BackendSession",
+    "FileChange",
+    "PermissionDecision",
+    "PermissionRequest",
+    "Result",
+    "RunRequest",
+    "TextDelta",
+    "ToolUse",
+    "EchoBackend",
+    "make_backend",
+]
+
+
+def make_backend(name: str, **kwargs) -> Backend:
+    """Construct a backend by name.
+
+    ``acp`` and ``claude`` are imported lazily so the echo backend works without
+    their runtime dependencies (the ACP SDK / the Claude Agent SDK) present.
+    """
+    if name == "echo":
+        return EchoBackend()
+    if name == "acp":
+        from .acp import ACPBackend
+
+        return ACPBackend(**kwargs)
+    if name == "claude":
+        from .claude import ClaudeBackend
+
+        return ClaudeBackend(**kwargs)
+    raise ValueError(f"unknown backend: {name!r} (expected 'acp', 'claude', or 'echo')")

a2acode/backends/acp.py

@@ -0,0 +1,291 @@
+"""ACP backend.
+
+Drives any agent that speaks Zed's Agent Client Protocol (ACP) — Claude Code,
+Gemini CLI, Codex, OpenHands, ... — as a subprocess, and normalizes its
+``session/update`` stream into backend events. This is the seam that makes the
+server vendor-neutral: one ACP client backend instead of one SDK adapter per
+agent. Swapping the underlying coding agent becomes a launch-command change, not
+a new backend.
+
+ACP maps almost one-to-one onto the backend event vocabulary:
+
+    agent_message_chunk          -> TextDelta
+    tool_call / tool_call_update -> ToolUse (+ FileChange for diff content)
+    session/request_permission   -> PermissionRequest (the input-required pause)
+    PromptResponse usage + cost  -> Result
+
+The permission round trip lands exactly on the session seam: the agent calls
+back into the client's ``request_permission``, which awaits
+``session.request_permission`` and parks until the A2A caller answers — the same
+parked-across-two-execute-calls behavior the Claude backend gets through
+``can_use_tool``.
+
+``events_from_update`` and ``select_option`` are pure and side-effect free so the
+protocol translation is unit-testable without launching an agent subprocess.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from collections.abc import Iterator, Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+from acp import PROTOCOL_VERSION, Client, spawn_agent_process, text_block
+from acp import schema as s
+
+from .base import BackendEvent, FileChange, Result, RunRequest, TextDelta, ToolUse
+from .diff import unified_diff
+from .session import BackendSession
+
+# How to launch each known ACP agent adapter as a subprocess. A preset is just a
+# default command; pass an explicit ``command``/``args`` to drive any other ACP
+# agent (or a pinned/locally installed adapter).
+_AGENTS: dict[str, tuple[str, tuple[str, ...]]] = {
+    "claude": ("npx", ("-y", "@zed-industries/claude-agent-acp")),
+    "gemini": ("gemini", ("--experimental-acp",)),
+    "codex": ("codex-acp", ()),
+}
+
+
+def events_from_update(update: object) -> Iterator[BackendEvent]:
+    """Map one ACP ``session/update`` to normalized backend events.
+
+    Pure and side-effect free so the translation can be unit tested without a
+    live agent subprocess. ``usage_update`` yields nothing here; cost/usage is
+    folded into the terminal ``Result`` by the backend.
+    """
+    if isinstance(update, s.AgentMessageChunk):
+        text = getattr(update.content, "text", None)
+        if text:
+            yield TextDelta(text=text)
+    elif isinstance(update, s.ToolCallStart):
+        yield ToolUse(
+            name=update.title or (update.kind or "tool"),
+            tool_input=_as_dict(update.raw_input),
+            tool_use_id=update.tool_call_id,
+        )
+        yield from _file_changes(update.content)
+    elif isinstance(update, s.ToolCallProgress):
+        # A diff is often not ready when the tool call opens; later progress
+        # updates carry it. The ToolUse was already emitted on the start event.
+        yield from _file_changes(update.content)
+
+
+def select_option(options: Sequence[s.PermissionOption], *, allow: bool) -> str | None:
+    """Pick the option id that matches the caller's allow/deny decision.
+
+    ACP returns the binding choice as an ``optionId``; ``kind`` is only a UI
+    hint. Prefer a one-shot option (allow_once / reject_once) over a sticky one,
+    then fall back to any option of the right polarity. ``None`` means the agent
+    offered no option of that polarity.
+    """
+    preferred = (
+        ("allow_once", "allow_always") if allow else ("reject_once", "reject_always")
+    )
+    for kind in preferred:
+        for opt in options:
+            if opt.kind == kind:
+                return opt.option_id
+    prefix = "allow" if allow else "reject"
+    for opt in options:
+        if (opt.kind or "").startswith(prefix):
+            return opt.option_id
+    return None
+
+
+def _as_dict(value: Any) -> dict[str, Any]:
+    return dict(value) if isinstance(value, Mapping) else {}
+
+
+def _file_changes(content: Sequence[object] | None) -> Iterator[FileChange]:
+    for item in content or []:
+        if isinstance(item, s.FileEditToolCallContent):
+            yield FileChange(
+                path=item.path,
+                diff=unified_diff(item.path, item.old_text or "", item.new_text or ""),
+            )
+
+
+class _BridgeClient(Client):
+    """ACP client that forwards agent output onto a BackendSession.
+
+    The agent's notifications and permission requests arrive on the ACP
+    connection's reader task; this translates each onto the session queue, and
+    parks a permission request on ``session.request_permission`` until the A2A
+    caller answers.
+    """
+
+    def __init__(self, session: BackendSession, cwd: str = ".") -> None:
+        self._session = session
+        # Resolved workspace root: every fs read/write is confined under it so a
+        # buggy or hostile agent can't reach arbitrary files via the capability
+        # we advertise. ACP paths are absolute, but we still contain them.
+        self._cwd = Path(cwd).resolve()
+        self.cost_usd: float | None = None
+
+    def _safe_path(self, path: str) -> Path:
+        target = Path(path)
+        if not target.is_absolute():
+            target = self._cwd / target
+        target = target.resolve()
+        if not target.is_relative_to(self._cwd):
+            raise PermissionError(f"path escapes workspace {self._cwd}: {path!r}")
+        return target
+
+    async def session_update(self, session_id: str, update: Any, **_: Any) -> None:
+        if isinstance(update, s.UsageUpdate) and update.cost is not None:
+            self.cost_usd = update.cost.amount
+        for event in events_from_update(update):
+            await self._session.emit(event)
+
+    async def request_permission(
+        self,
+        options: list[s.PermissionOption],
+        session_id: str,
+        tool_call: s.ToolCallUpdate,
+        **_: Any,
+    ) -> s.RequestPermissionResponse:
+        name = tool_call.title or (tool_call.kind or "tool")
+        decision = await self._session.request_permission(
+            name, _as_dict(tool_call.raw_input), name
+        )
+        option_id = select_option(options, allow=decision.allow)
+        if option_id is None:
+            # The agent offered no option of the requested polarity; cancelling
+            # is the only safe answer (selecting the wrong one could run a tool
+            # the caller denied).
+            return s.RequestPermissionResponse(
+                outcome=s.DeniedOutcome(outcome="cancelled")
+            )
+        return s.RequestPermissionResponse(
+            outcome=s.AllowedOutcome(outcome="selected", option_id=option_id)
+        )
+
+    async def read_text_file(
+        self,
+        path: str,
+        session_id: str,
+        limit: int | None = None,
+        line: int | None = None,
+        **_: Any,
+    ) -> s.ReadTextFileResponse:
+        # We advertise fs.readTextFile, so serve reads from disk. There are no
+        # unsaved editor buffers on a server; the file on disk is the truth.
+        target = self._safe_path(path)
+        if limit is not None and limit <= 0:
+            return s.ReadTextFileResponse(content="")
+        # A non-positive line number reads from the top.
+        start = (line - 1) if (line and line > 0) else 0
+
+        def _read() -> str:
+            if line is None and limit is None:
+                return target.read_text(encoding="utf-8")
+            # Stream so a small windowed read doesn't pull a huge file into
+            # memory just to slice a few lines out of it.
+            end = (start + limit) if limit is not None else None
+            out: list[str] = []
+            with target.open(encoding="utf-8") as f:
+                for i, text_line in enumerate(f):
+                    if i >= start:
+                        out.append(text_line)
+                    if end is not None and i >= end - 1:
+                        break
+            return "".join(out)
+
+        # Offloaded to a thread so the synchronous read can't stall the event
+        # loop the ACP connection runs on.
+        text = await asyncio.to_thread(_read)
+        return s.ReadTextFileResponse(content=text)
+
+    async def write_text_file(
+        self, content: str, path: str, session_id: str, **_: Any
+    ) -> None:
+        target = self._safe_path(path)
+
+        def _write() -> None:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(content, encoding="utf-8")
+
+        # Offloaded so the blocking mkdir/write can't stall the event loop.
+        await asyncio.to_thread(_write)
+        return None
+
+
+class ACPBackend:
+    name = "acp"
+
+    def __init__(
+        self,
+        *,
+        agent: str = "claude",
+        command: str | None = None,
+        args: Sequence[str] | None = None,
+        cwd: str | None = None,
+        env: Mapping[str, str] | None = None,
+    ) -> None:
+        if command is None:
+            preset = _AGENTS.get(agent)
+            if preset is None:
+                known = ", ".join(sorted(_AGENTS))
+                raise ValueError(
+                    f"unknown ACP agent {agent!r} (known: {known}); "
+                    "pass command=... to launch any other ACP agent"
+                )
+            command, default_args = preset
+            args = default_args if args is None else args
+        self.agent = agent
+        self.command = command
+        self.args = list(args or [])
+        self.cwd = os.path.abspath(cwd or os.getcwd())
+        # Overrides layered onto the server's own environment so the adapter
+        # still inherits PATH and any provider credentials (ANTHROPIC_API_KEY,
+        # GEMINI_API_KEY, ...) it needs to authenticate.
+        self.env = {**os.environ, **(env or {})}
+
+    async def drive(self, session: BackendSession, request: RunRequest) -> None:
+        # The ACP Client base declares terminal/* and ext_* with empty bodies as
+        # optional overrides; we advertise no terminal capability, so the agent
+        # never calls them. mypy reads the empty bodies as abstract, hence the
+        # scoped ignore.
+        client = _BridgeClient(session, self.cwd)  # type: ignore[abstract]
+        async with spawn_agent_process(
+            client, self.command, *self.args, env=self.env, cwd=self.cwd
+        ) as (conn, _process):
+            init = await conn.initialize(
+                protocol_version=PROTOCOL_VERSION,
+                client_capabilities=s.ClientCapabilities(
+                    fs=s.FileSystemCapabilities(
+                        read_text_file=True, write_text_file=True
+                    )
+                ),
+            )
+            session_id = await self._open_session(conn, init, request)
+            response = await conn.prompt(
+                prompt=[text_block(request.prompt)], session_id=session_id
+            )
+            usage = response.usage.model_dump() if response.usage else None
+            await session.emit(
+                Result(
+                    session_id=session_id,
+                    cost_usd=client.cost_usd,
+                    num_turns=None,
+                    usage=usage,
+                )
+            )
+
+    async def _open_session(
+        self, conn: Any, init: s.InitializeResponse, request: RunRequest
+    ) -> str:
+        can_load = bool(getattr(init.agent_capabilities, "load_session", False))
+        if request.resume and can_load:
+            await conn.load_session(
+                cwd=self.cwd, session_id=request.resume, mcp_servers=[]
+            )
+            return request.resume
+        # No resume, or the agent can't reload a session: start fresh. The
+        # executor learns the new session id from the Result and maps the A2A
+        # context onto it for the next turn.
+        response = await conn.new_session(cwd=self.cwd, mcp_servers=[])
+        return response.session_id

a2acode/backends/base.py

@@ -0,0 +1,96 @@
+"""Backend abstraction.
+
+A backend drives Claude Code and yields a normalized stream of events. The
+A2A layer never imports the Claude Agent SDK directly; it only consumes these
+events. That keeps the protocol mapping in one place and lets us swap the
+underlying driver (Agent SDK today, raw CLI later) without touching the server.
+
+Backends implement ``drive(session, request)``: they push events onto the
+session and, when a tool needs approval, call ``session.request_permission(...)``
+which parks until the A2A caller responds. This is what lets a permission prompt
+become an A2A ``input-required`` round trip rather than being silently skipped.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from .session import BackendSession
+
+
+@dataclass(slots=True)
+class TextDelta:
+    """A chunk of assistant-authored text."""
+
+    text: str
+
+
+@dataclass(slots=True)
+class ToolUse:
+    """The agent decided to run a tool (Bash, Edit, Read, ...)."""
+
+    name: str
+    tool_input: dict[str, Any]
+    tool_use_id: str
+
+
+@dataclass(slots=True)
+class FileChange:
+    """A file was written or edited during the run."""
+
+    path: str
+    diff: str
+
+
+@dataclass(slots=True)
+class PermissionRequest:
+    """A tool needs the caller's approval before it can run."""
+
+    request_id: str
+    tool_name: str
+    tool_input: dict[str, Any]
+    description: str = ""
+
+
+@dataclass(slots=True)
+class PermissionDecision:
+    """The caller's answer to a PermissionRequest."""
+
+    request_id: str
+    allow: bool
+    message: str = ""
+
+
+@dataclass(slots=True)
+class Result:
+    """Terminal event carrying run metadata."""
+
+    session_id: str | None = None
+    cost_usd: float | None = None
+    num_turns: int | None = None
+    usage: dict[str, Any] | None = None
+
+
+BackendEvent = TextDelta | ToolUse | FileChange | PermissionRequest | Result
+
+
+@dataclass(slots=True)
+class RunRequest:
+    """One turn of work handed to a backend."""
+
+    prompt: str
+    context_id: str | None = None
+    resume: str | None = None
+
+
+@runtime_checkable
+class Backend(Protocol):
+    """Anything that can drive Claude Code and emit normalized events."""
+
+    name: str
+
+    async def drive(self, session: BackendSession, request: RunRequest) -> None:
+        """Run one turn, emitting events onto ``session`` until it returns."""
+        ...

a2acode/backends/claude.py

@@ -0,0 +1,125 @@
+"""Claude backend.
+
+Drives Claude Code through the Claude Agent SDK's bidirectional client and
+normalizes its typed message stream into backend events. Tool calls, file edits,
+run cost, and the session id: everything the "text in, text out" wrappers
+discard is preserved for the A2A layer to map onto the protocol.
+
+Permission prompts are routed through ``can_use_tool`` into the session's
+``request_permission``, so the caller approves or denies a tool over A2A instead
+of the server skipping it.
+
+Authentication follows whatever the Claude CLI is configured with. For a server
+that answers on behalf of other agents that means an Anthropic API key (or
+Bedrock/Vertex); subscription credentials are not permitted for third-party
+serving.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterator
+
+from claude_agent_sdk import (
+    AssistantMessage,
+    ClaudeAgentOptions,
+    ClaudeSDKClient,
+    PermissionMode,
+    PermissionResultAllow,
+    PermissionResultDeny,
+    ResultMessage,
+    SettingSource,
+    TextBlock,
+    ToolUseBlock,
+)
+
+from .base import BackendEvent, Result, RunRequest, TextDelta, ToolUse
+from .diff import file_changes
+from .session import BackendSession
+
+
+def events_from_message(message: object) -> Iterator[BackendEvent]:
+    """Map one Claude Agent SDK message to normalized backend events.
+
+    Pure and side-effect free so the translation can be unit tested without a
+    live Claude session.
+    """
+    if isinstance(message, AssistantMessage):
+        for block in message.content:
+            if isinstance(block, TextBlock):
+                if block.text:
+                    yield TextDelta(text=block.text)
+            elif isinstance(block, ToolUseBlock):
+                tool_input = dict(block.input or {})
+                yield ToolUse(block.name, tool_input, block.id)
+                yield from file_changes(block.name, tool_input)
+    elif isinstance(message, ResultMessage):
+        yield Result(
+            session_id=message.session_id,
+            cost_usd=message.total_cost_usd,
+            num_turns=message.num_turns,
+            usage=message.usage,
+        )
+
+
+class ClaudeBackend:
+    name = "claude"
+
+    def __init__(
+        self,
+        *,
+        cwd: str | None = None,
+        allowed_tools: list[str] | None = None,
+        permission_mode: PermissionMode | None = None,
+        model: str | None = None,
+        max_budget_usd: float | None = None,
+        setting_sources: list[SettingSource] | None = None,
+    ) -> None:
+        self.cwd = os.path.abspath(cwd or os.getcwd())
+        self.allowed_tools = allowed_tools
+        self.permission_mode = permission_mode
+        self.model = model
+        self.max_budget_usd = max_budget_usd
+        # A server should not inherit a developer's personal tool allowlist:
+        # default to loading no settings so every tool routes through the A2A
+        # permission round trip. Pass e.g. ["project"] to opt back in.
+        self.setting_sources: list[SettingSource] = (
+            [] if setting_sources is None else setting_sources
+        )
+
+    def _options(self, request: RunRequest, can_use_tool) -> ClaudeAgentOptions:
+        options = ClaudeAgentOptions(
+            cwd=self.cwd,
+            can_use_tool=can_use_tool,
+            setting_sources=self.setting_sources,
+        )
+        if request.resume:
+            options.resume = request.resume
+        if self.allowed_tools:
+            options.allowed_tools = self.allowed_tools
+        if self.permission_mode:
+            options.permission_mode = self.permission_mode
+        if self.model:
+            options.model = self.model
+        if self.max_budget_usd is not None:
+            options.max_budget_usd = self.max_budget_usd
+        return options
+
+    async def drive(self, session: BackendSession, request: RunRequest) -> None:
+        async def can_use_tool(tool_name, tool_input, context):
+            description = getattr(context, "display_name", "") or tool_name
+            decision = await session.request_permission(
+                tool_name, dict(tool_input or {}), description
+            )
+            if decision.allow:
+                return PermissionResultAllow()
+            return PermissionResultDeny(
+                message=decision.message or "Denied by A2A caller"
+            )
+
+        options = self._options(request, can_use_tool)
+        async with ClaudeSDKClient(options=options) as client:
+            await client.query(request.prompt)
+            async for message in client.receive_response():
+                for event in events_from_message(message):
+                    await session.emit(event)