a2claude 0.1.0__py3-none-any.whl

a2claude/__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"]

a2claude/backends/__init__.py

@@ -0,0 +1,47 @@
+"""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.
+
+    ``claude`` is imported lazily so the echo backend works without the Claude
+    Agent SDK's runtime dependencies present.
+    """
+    if name == "echo":
+        return EchoBackend()
+    if name == "claude":
+        from .claude import ClaudeBackend
+
+        return ClaudeBackend(**kwargs)
+    raise ValueError(f"unknown backend: {name!r} (expected 'echo' or 'claude')")

a2claude/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."""
+        ...

a2claude/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 — are 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)

a2claude/backends/diff.py

@@ -0,0 +1,70 @@
+"""Synthesize unified diffs from Claude Code's file-editing tool calls.
+
+The tool input describes the intended change, so the diff is the proposed edit
+rather than a post-hoc comparison of disk state — which is what a caller wants
+to see streamed while the work is still in progress.
+"""
+
+from __future__ import annotations
+
+import difflib
+from typing import Any
+
+from .base import FileChange
+
+_EDIT_TOOLS = {"Write", "Edit", "MultiEdit"}
+
+
+def _unified(path: str, before: str, after: str) -> str:
+    before_lines = before.splitlines(keepends=True) if before else []
+    after_lines = after.splitlines(keepends=True) if after else []
+    diff = "".join(
+        difflib.unified_diff(
+            before_lines, after_lines, fromfile=f"a/{path}", tofile=f"b/{path}"
+        )
+    )
+    if diff and not diff.endswith("\n"):
+        diff += "\n"
+    return diff
+
+
+def _text(value: Any) -> str:
+    """Coerce a tool-input field to text, treating a missing/null value as empty.
+
+    ``dict.get(key, "")`` returns ``None`` when the key is present but null, so
+    plain ``str(...)`` would yield the literal ``"None"``.
+    """
+    return "" if value is None else str(value)
+
+
+def file_changes(tool_name: str, tool_input: dict[str, Any]) -> list[FileChange]:
+    """Return the file changes a tool call would make, if any."""
+    if tool_name not in _EDIT_TOOLS:
+        return []
+    path = tool_input.get("file_path") or tool_input.get("path")
+    if not path:
+        return []
+
+    if tool_name == "Write":
+        diff = _unified(path, "", _text(tool_input.get("content")))
+    elif tool_name == "Edit":
+        diff = _unified(
+            path,
+            _text(tool_input.get("old_string")),
+            _text(tool_input.get("new_string")),
+        )
+    else:  # MultiEdit — edits may be malformed; tolerate anything non-dict.
+        edits = tool_input.get("edits")
+        if not isinstance(edits, list):
+            return []
+        diff = "".join(
+            _unified(
+                path,
+                _text(edit.get("old_string")),
+                _text(edit.get("new_string")),
+            )
+            for edit in edits
+            if isinstance(edit, dict)
+        )
+
+    return [FileChange(path=str(path), diff=diff)] if diff else []

a2claude/backends/echo.py

@@ -0,0 +1,47 @@
+"""Echo backend.
+
+Needs no API key and no Claude install. It exists so the server, the protocol
+mapping, and the CLI can be exercised end to end offline. It emits the same
+event shapes a real run produces, and when the prompt contains ``sudo`` it asks
+for permission first — which lets the full ``input-required`` round trip be
+verified without a live Claude session.
+"""
+
+from __future__ import annotations
+
+from .base import Result, RunRequest, TextDelta, ToolUse
+from .session import BackendSession
+
+
+class EchoBackend:
+    name = "echo"
+
+    async def drive(self, session: BackendSession, request: RunRequest) -> None:
+        await session.emit(
+            ToolUse(
+                name="Echo",
+                tool_input={"prompt": request.prompt},
+                tool_use_id="echo-1",
+            )
+        )
+
+        if "sudo" in request.prompt.lower():
+            decision = await session.request_permission(
+                "Bash", {"command": request.prompt}, f"$ {request.prompt}"
+            )
+            if not decision.allow:
+                await session.emit(TextDelta("permission denied; nothing run"))
+                await session.emit(self._result(request))
+                return
+
+        for word in request.prompt.split():
+            await session.emit(TextDelta(word + " "))
+        await session.emit(self._result(request))
+
+    @staticmethod
+    def _result(request: RunRequest) -> Result:
+        return Result(
+            session_id=request.context_id or "echo-session",
+            cost_usd=0.0,
+            num_turns=1,
+        )

a2claude/backends/session.py

@@ -0,0 +1,128 @@
+"""Session machinery shared by all backends.
+
+A backend's ``drive`` coroutine runs in a background task and pushes events onto
+the session. The consumer (the executor) reads them with ``drain``, which stops
+either when the run finishes or when it surfaces a permission request — at which
+point the background task is parked inside ``request_permission`` waiting for a
+decision. A later ``resolve`` un-parks it. This decoupling is what allows the
+A2A ``input-required`` round trip to span two separate ``execute`` calls while
+the Claude session stays alive in between.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator, Awaitable, Callable
+from contextlib import suppress
+from dataclasses import dataclass
+from typing import Any
+from uuid import uuid4
+
+from .base import BackendEvent, PermissionDecision, PermissionRequest
+
+
+@dataclass(slots=True)
+class _Error:
+    exc: BaseException
+
+
+_DONE = object()
+
+# The event loop holds only a weak reference to tasks created with
+# create_task; keep a strong one so a runner can't be garbage-collected
+# mid-flight (e.g. after its session is dropped on a client disconnect).
+_RUNNERS: set[asyncio.Task[None]] = set()
+
+
+class BackendSession:
+    def __init__(self) -> None:
+        self._queue: asyncio.Queue[Any] = asyncio.Queue()
+        self._pending: dict[str, asyncio.Future[PermissionDecision]] = {}
+        self._runner: asyncio.Task[None] | None = None
+        self.last_request_id: str | None = None
+        self.done = False
+
+    @property
+    def is_parked(self) -> bool:
+        """Whether the run is currently waiting for a permission decision."""
+        return (
+            self.last_request_id is not None and self.last_request_id in self._pending
+        )
+
+    def start(self, driver: Callable[[BackendSession], Awaitable[None]]) -> None:
+        async def runner() -> None:
+            try:
+                await driver(self)
+            except asyncio.CancelledError:
+                raise
+            except BaseException as exc:  # noqa: BLE001 — relayed to consumer
+                # put_nowait (the queue is unbounded) so a pending cancellation
+                # cannot stop the sentinel from reaching a blocked drain().
+                self._queue.put_nowait(_Error(exc))
+            finally:
+                self._queue.put_nowait(_DONE)
+
+        self._runner = asyncio.create_task(runner())
+        _RUNNERS.add(self._runner)
+        self._runner.add_done_callback(_RUNNERS.discard)
+
+    async def emit(self, event: BackendEvent) -> None:
+        await self._queue.put(event)
+
+    async def request_permission(
+        self, tool_name: str, tool_input: dict[str, Any], description: str = ""
+    ) -> PermissionDecision:
+        request_id = uuid4().hex
+        future: asyncio.Future[PermissionDecision] = (
+            asyncio.get_running_loop().create_future()
+        )
+        self._pending[request_id] = future
+        await self._queue.put(
+            PermissionRequest(request_id, tool_name, dict(tool_input), description)
+        )
+        return await future
+
+    def resolve(self, decision: PermissionDecision) -> None:
+        future = self._pending.pop(decision.request_id, None)
+        if future is None:
+            # Fail fast: a no-op would leave the driver parked and hang drain().
+            raise ValueError(f"no pending permission request {decision.request_id!r}")
+        if not future.done():
+            future.set_result(decision)
+
+    async def drain(self) -> AsyncIterator[BackendEvent]:
+        """Yield events until the run ends or a permission request is surfaced.
+
+        A permission request is yielded and then stops the iteration, leaving the
+        background task parked until ``resolve`` is called and ``drain`` resumes.
+        """
+        while True:
+            item = await self._queue.get()
+            if item is _DONE:
+                self.done = True
+                return
+            if isinstance(item, _Error):
+                self.done = True
+                raise item.exc
+            yield item
+            if isinstance(item, PermissionRequest):
+                self.last_request_id = item.request_id
+                return
+
+    def abort(self) -> None:
+        """Cancel the background runner without awaiting — safe to call from a
+        cancelled context (e.g. an interrupted ``execute``)."""
+        if self._runner is not None and not self._runner.done():
+            self._runner.cancel()
+
+    async def close(self) -> None:
+        try:
+            if self._runner is not None and not self._runner.done():
+                self._runner.cancel()
+                with suppress(asyncio.CancelledError):
+                    await self._runner
+        finally:
+            for future in self._pending.values():
+                if not future.done():
+                    future.cancel()
+            self._pending.clear()

a2claude/card.py

@@ -0,0 +1,93 @@
+"""Agent card construction.
+
+The card advertises Claude Code's coding abilities as discrete A2A skills so
+that calling agents can route to it deliberately rather than treating it as an
+opaque chat box.
+"""
+
+from __future__ import annotations
+
+from a2a.types import AgentCapabilities, AgentCard, AgentInterface, AgentSkill
+from a2a.utils.constants import PROTOCOL_VERSION_CURRENT, TransportProtocol
+
+VERSION = "0.1.0"
+
+SKILLS = [
+    AgentSkill(
+        id="code-generation",
+        name="Code generation",
+        description="Implement features, scaffold modules, and write new code "
+        "from a natural-language description.",
+        tags=["code", "generation"],
+        examples=["Add a /health endpoint that returns build info"],
+    ),
+    AgentSkill(
+        id="refactor",
+        name="Refactoring",
+        description="Restructure existing code without changing behavior — "
+        "extract functions, rename, split modules.",
+        tags=["code", "refactor"],
+        examples=["Split this 400-line file into cohesive modules"],
+    ),
+    AgentSkill(
+        id="debug",
+        name="Debugging",
+        description="Reproduce, locate, and fix defects, then verify the fix.",
+        tags=["code", "debug"],
+        examples=["The auth test fails intermittently — find and fix it"],
+    ),
+    AgentSkill(
+        id="review",
+        name="Code review",
+        description="Review a diff or file for correctness, edge cases, and "
+        "consistency with the surrounding code.",
+        tags=["code", "review"],
+        examples=["Review the changes on this branch"],
+    ),
+    AgentSkill(
+        id="test",
+        name="Testing",
+        description="Write or extend tests and run them to confirm they pass.",
+        tags=["code", "test"],
+        examples=["Add unit tests for the payment module"],
+    ),
+    AgentSkill(
+        id="explain",
+        name="Code explanation",
+        description="Explain how a codebase, file, or function works.",
+        tags=["code", "explain"],
+        examples=["Walk me through how request routing works here"],
+    ),
+]
+
+
+def build_card(
+    url: str,
+    *,
+    name: str = "Claude Code",
+    description: str | None = None,
+    streaming: bool = True,
+    push_notifications: bool = True,
+) -> AgentCard:
+    return AgentCard(
+        name=name,
+        description=description
+        or "Claude Code as an A2A agent — generation, refactoring, "
+        "debugging, review, testing, and explanation over a real project "
+        "workspace.",
+        version=VERSION,
+        capabilities=AgentCapabilities(
+            streaming=streaming,
+            push_notifications=push_notifications,
+        ),
+        supported_interfaces=[
+            AgentInterface(
+                url=url,
+                protocol_binding=TransportProtocol.JSONRPC,
+                protocol_version=PROTOCOL_VERSION_CURRENT,
+            )
+        ],
+        skills=SKILLS,
+        default_input_modes=["text/plain"],
+        default_output_modes=["text/plain"],
+    )