a2acode 0.4.0__py3-none-any.whl

a2acode/backends/diff.py

@@ -0,0 +1,79 @@
+"""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 unified_diff(path: str, before: str, after: str) -> str:
+    """Build a unified diff from full before/after file text.
+
+    Used by the ACP backend, whose diff tool-call content carries the complete
+    old and new file contents rather than an edit description.
+    """
+    return _unified(path, before, after)
+
+
+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 []

a2acode/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,
+        )

a2acode/backends/session.py

@@ -0,0 +1,132 @@
+"""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
+        # Set when the executor drops this session to free a capacity slot, so
+        # the session's own consumer can fail its task instead of completing it
+        # with whatever partial output it had buffered.
+        self.evicted = 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()

a2acode/card.py

@@ -0,0 +1,187 @@
+"""Agent card construction.
+
+The card advertises the coding agent's abilities as discrete A2A skills so that
+calling agents can route to it deliberately rather than treating it as an opaque
+chat box. The name identifies which agent is fronted; the skills are the same
+generation/refactor/debug/review/test/explain set regardless of backend.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _package_version
+from pathlib import Path
+
+from a2a.types import (
+    AgentCapabilities,
+    AgentCard,
+    AgentInterface,
+    AgentSkill,
+    SecurityRequirement,
+)
+from a2a.utils.constants import PROTOCOL_VERSION_CURRENT, TransportProtocol
+
+# The id used for the bearer scheme in the card's security_schemes map and in
+# each security requirement that references it.
+BEARER_SCHEME = "bearer"
+
+try:
+    # The agent card version tracks the package version, read from installed
+    # metadata so there is one source of truth (pyproject) and it cannot drift.
+    VERSION = _package_version("a2acode")
+except PackageNotFoundError:  # running from a source tree without an install
+    VERSION = "0.0.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,
+    require_auth: bool = False,
+) -> AgentCard:
+    card = AgentCard(
+        name=name,
+        description=description
+        or "A coding agent on an A2A mesh: generation, refactoring, "
+        "debugging, review, testing, and explanation over a real project "
+        "workspace.",
+        version=VERSION,
+        capabilities=AgentCapabilities(
+            streaming=streaming,
+            push_notifications=push_notifications,
+        ),
+        # The server mounts both JSON-RPC and REST (HTTP+JSON) routes, so the
+        # card advertises both bindings; a caller picks whichever its client
+        # speaks instead of assuming JSON-RPC.
+        supported_interfaces=[
+            AgentInterface(
+                url=url,
+                protocol_binding=TransportProtocol.JSONRPC,
+                protocol_version=PROTOCOL_VERSION_CURRENT,
+            ),
+            AgentInterface(
+                url=url,
+                protocol_binding=TransportProtocol.HTTP_JSON,
+                protocol_version=PROTOCOL_VERSION_CURRENT,
+            ),
+        ],
+        skills=SKILLS,
+        default_input_modes=["text/plain"],
+        default_output_modes=["text/plain"],
+    )
+    if require_auth:
+        # Declare an HTTP bearer scheme and require it, so a caller learns from
+        # the card that it must present a token before sending a task. A2A keeps
+        # the credential at the HTTP layer; the card only advertises the
+        # requirement.
+        card.security_schemes[BEARER_SCHEME].http_auth_security_scheme.scheme = "bearer"
+        requirement = SecurityRequirement()
+        # Reference the bearer scheme with no extra scopes (an empty scope list).
+        requirement.schemes[BEARER_SCHEME].SetInParent()
+        card.security_requirements.append(requirement)
+    return card
+
+
+def sign_card(
+    card: AgentCard,
+    *,
+    key: str | bytes,
+    kid: str,
+    alg: str = "ES256",
+    jku: str | None = None,
+) -> AgentCard:
+    """Attach a JWS signature to the agent card.
+
+    A2A signed Agent Cards let a receiving agent verify the card was issued by
+    the domain that owns the key (``kid``), rather than trusting whatever a
+    discovery endpoint happened to return. The signature covers the canonical
+    card minus the ``signatures`` field, so it can be appended in place.
+
+    ``key`` is the private signing material: a PEM string for asymmetric
+    algorithms (ES256, RS256) or a shared secret for HMAC (HS256). ``jku``, if
+    given, is the JWK Set URL a verifier can fetch the public key from.
+    """
+    from a2a.utils.signing import ProtectedHeader, create_agent_card_signer
+
+    header: ProtectedHeader = {"kid": kid, "alg": alg, "jku": jku, "typ": "JOSE"}
+    signer = create_agent_card_signer(signing_key=key, protected_header=header)
+    return signer(card)
+
+
+def signer_from_key_file(
+    path: str, *, kid: str, alg: str = "ES256", jku: str | None = None
+) -> Callable[[AgentCard], AgentCard]:
+    """Build a card-signing function that reads its key from ``path``.
+
+    The file holds a PEM private key (asymmetric algorithms) or a raw shared
+    secret (HMAC). The key is read once, as bytes so a binary secret does not
+    trip a decode error, and the key/algorithm pair is validated up front by
+    signing a throwaway card, so a misconfigured key fails at startup rather
+    than on the first discovery request.
+    """
+    key = Path(path).read_bytes().strip()
+    if not key:
+        raise ValueError(f"signing key file is empty: {path}")
+
+    def signer(card: AgentCard) -> AgentCard:
+        return sign_card(card, key=key, kid=kid, alg=alg, jku=jku)
+
+    try:
+        signer(build_card("https://validation.invalid/"))
+    except Exception as e:  # noqa: BLE001 - any failure here is a key/alg misconfig
+        raise ValueError(
+            f"cannot sign agent card with the given key and {alg}: {e}"
+        ) from e
+    return signer