langgraph-acp 0.1.0__py3-none-any.whl

langgraph_acp/__init__.py

@@ -0,0 +1,134 @@
+"""ACP-compatible agents as first-class LangGraph nodes.
+
+The boundary this package exists to hold:
+
+    LangGraph owns orchestration and workflow durability.
+    ACP owns the agent conversation and agent-side session state.
+    langgraph-acp owns the binding between the two.
+
+What is here is the vocabulary, the connection beneath it, and the first node
+that joins the two halves: `ACPNode` resolves an agent, opens and initializes a
+connection, starts a session, runs a prompt, and returns an `ACPResult`.
+
+    ACPAgentRegistry -> ACPAgentProvider -> ACPClient -> ACPSession
+         "codex"          how to reach      one live     one conversation
+                             an agent       connection      and its turns
+
+    ACPSessionStore     (thread_id, session_key) -> "sess_abc123"
+                        the binding, and only ever the binding
+
+Naming an agent is confined to `langgraph_acp.providers`. Everything else --
+every core type, the registry, the client, the session -- is written without
+knowing whether it is talking to Codex or to something released next year, and
+`"codex"` is a string a registry resolves rather than an import anyone makes.
+
+Serialization follows one rule, so "does this have a `to_dict`?" has an answer
+that does not need looking up. Types that leave the process serialize:
+`ACPEvent` into a stream, `ACPResult` into LangGraph state. Types that only
+configure a node -- `ACPSessionSpec`, `ACPWorkspace`, `ACPConfig`,
+`ACPRequirements` -- do not: they are written in Python beside the graph, and a
+graph definition is code rather than data.
+
+Every field is annotated with what the constructor *accepts*, not with what it
+stores: `__post_init__` normalizes, so a `Path` becomes a `str`, a list becomes
+a tuple, and `"reuse"` becomes `ACPSessionStrategy.REUSE`. The stored value is
+always an instance of the declared type but usually a narrower one. A stdlib
+dataclass has no way to declare the two separately, and since `py.typed` ships
+here, the spelling a caller writes is the one the annotation has to admit.
+
+Containers handed in are copied, and so are containers handed back out by
+`to_dict`. The copy is deep, because ACP payloads are nested and a shallow one
+would leave the interesting part shared.
+"""
+
+from langgraph_acp._json import JSONObject, JSONValue
+from langgraph_acp.agent import (
+    ACPAgentProvider,
+    ACPAgentRegistry,
+    StdioACPProvider,
+    default_registry,
+)
+from langgraph_acp.client import PROTOCOL_VERSION, ACPCapabilities, ACPClient
+from langgraph_acp.config import ACPConfig, ACPRequirements, UnsupportedOption
+from langgraph_acp.continuation import ACPContinuation, resume_continuation
+from langgraph_acp.elicitation import (
+    ACPElicitationHandler,
+    ACPElicitationRequest,
+    ACPElicitationResponse,
+)
+from langgraph_acp.errors import (
+    ACPAgentCapabilityError,
+    ACPAgentNotFoundError,
+    ACPConnectionError,
+    ACPError,
+    ACPSessionError,
+)
+from langgraph_acp.events import EVENT_NAMESPACE, ACPEvent, ACPEventType
+from langgraph_acp.node import ACPNode
+from langgraph_acp.permissions import (
+    CANCELLED,
+    ACPPermissionHandler,
+    ACPPermissionOption,
+    ACPPermissionOutcome,
+    ACPPermissionRequest,
+    deny_permission,
+)
+from langgraph_acp.providers.claude import CLAUDE_ACP_COMMAND, ClaudeACPProvider
+from langgraph_acp.providers.codex import CODEX_ACP_COMMAND, CodexACPProvider
+from langgraph_acp.result import ACPResult, ACPUsage
+from langgraph_acp.session import (
+    ACPPrompt,
+    ACPSession,
+    ACPSessionSpec,
+    ACPSessionStrategy,
+)
+from langgraph_acp.store import ACPSessionStore, InMemoryACPSessionStore
+from langgraph_acp.workspace import ACPWorkspace
+
+__all__ = [
+    "ACPAgentCapabilityError",
+    "ACPAgentNotFoundError",
+    "ACPAgentProvider",
+    "ACPAgentRegistry",
+    "ACPCapabilities",
+    "ACPClient",
+    "ACPConfig",
+    "ACPConnectionError",
+    "ACPContinuation",
+    "ACPElicitationHandler",
+    "ACPElicitationRequest",
+    "ACPElicitationResponse",
+    "ACPError",
+    "ACPEvent",
+    "ACPEventType",
+    "ACPNode",
+    "ACPPermissionHandler",
+    "ACPPermissionOption",
+    "ACPPermissionOutcome",
+    "ACPPermissionRequest",
+    "ACPPrompt",
+    "ACPRequirements",
+    "ACPResult",
+    "ACPSession",
+    "ACPSessionError",
+    "ACPSessionSpec",
+    "ACPSessionStore",
+    "ACPSessionStrategy",
+    "ACPUsage",
+    "ACPWorkspace",
+    "CANCELLED",
+    "CLAUDE_ACP_COMMAND",
+    "CODEX_ACP_COMMAND",
+    "ClaudeACPProvider",
+    "CodexACPProvider",
+    "EVENT_NAMESPACE",
+    "InMemoryACPSessionStore",
+    "JSONObject",
+    "JSONValue",
+    "PROTOCOL_VERSION",
+    "StdioACPProvider",
+    "UnsupportedOption",
+    "default_registry",
+    "deny_permission",
+    "resume_continuation",
+]

langgraph_acp/_json.py

@@ -0,0 +1,136 @@
+"""JSON-shaped values: the copies that isolate them, and the reads that check them.
+
+ACP speaks JSON-RPC, so a few fields here carry whatever the agent sent: event
+payloads, result content, config values. Typing those as `JSONValue` states that
+honestly rather than inventing a richer type before the tickets that normalize
+them exist.
+
+Mappings and sequences are copied on the way in and on the way out. These
+objects end up in LangGraph state and in streamed events, where a container
+still shared with the caller is a mutation arriving from somewhere else
+entirely. The copy is *deep*, because the shape this data actually has is
+nested -- an ACP `session/update` is `{"update": {...}}`, and a shallow copy
+would leave the interesting part shared while the docstring claimed otherwise.
+The cost is proportional to the number of containers, not to the text inside
+them: strings are immutable and are shared rather than duplicated.
+
+The copies produce plain `dict` and `tuple` rather than read-only views because
+LangGraph checkpointing pickles what it stores, and `MappingProxyType` cannot be
+pickled.
+
+A lone `str` is refused wherever a sequence is expected. It is iterable, so
+without the guard `additional_directories="/repos/docs"` becomes eleven
+single-character roots and the mistake surfaces as a bad ACP request much later.
+
+The `as_*` readers exist for `from_dict`, where the input is whatever a store or
+a checkpoint handed back. They check rather than coerce: a token count that
+returns as `"1200"` should fail at the boundary it crossed, not as an arithmetic
+error in whatever later sums it.
+"""
+
+from collections.abc import Iterable, Mapping
+from copy import deepcopy
+from typing import TypeAlias, TypeVar
+
+JSONValue: TypeAlias = (
+    str
+    | int
+    | float
+    | bool
+    | None
+    | Iterable["JSONValue"]
+    | Mapping[str, "JSONValue"]
+)
+
+#: What a `to_dict` returns: a mapping the caller may keep and mutate freely.
+JSONObject: TypeAlias = dict[str, JSONValue]
+
+T = TypeVar("T")
+
+
+def copied_mapping(values: Mapping[str, JSONValue] | None) -> JSONObject:
+    """A private `dict`, nested containers included, holding what `values` held."""
+    return deepcopy(dict(values or {}))
+
+
+def checked_sequence(values: Iterable[T] | None, *, field: str) -> tuple[T, ...]:
+    """The values as a tuple, refusing the string that is quietly a sequence."""
+    if isinstance(values, (str, bytes)):
+        raise TypeError(
+            f"{field} takes a sequence of values, not the single "
+            f"{type(values).__name__} {values!r}: iterating one yields a "
+            "separate entry per character, which is never what was meant"
+        )
+    return tuple(values or ())
+
+
+def copied_sequence(
+    values: Iterable[JSONValue] | None, *, field: str
+) -> tuple[JSONValue, ...]:
+    """A private tuple, nested containers included, holding what `values` held."""
+    return tuple(deepcopy(value) for value in checked_sequence(values, field=field))
+
+
+def _wrong(field: str, expected: str, value: object) -> TypeError:
+    return TypeError(
+        f"{field} must be {expected}, not the {type(value).__name__} {value!r}"
+    )
+
+
+def as_str(value: object, *, field: str) -> str:
+    """`value` as the string it should already be."""
+    if isinstance(value, str):
+        return value
+    raise _wrong(field, "a string", value)
+
+
+def as_optional_str(value: object, *, field: str) -> str | None:
+    return None if value is None else as_str(value, field=field)
+
+
+def as_optional_int(value: object, *, field: str) -> int | None:
+    # `bool` is an `int` in Python, and is never a token count.
+    if value is None or (isinstance(value, int) and not isinstance(value, bool)):
+        return value
+    raise _wrong(field, "a whole number", value)
+
+
+def as_optional_float(value: object, *, field: str) -> float | None:
+    if value is None:
+        return None
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        return float(value)
+    raise _wrong(field, "a number", value)
+
+
+def as_mapping(value: object, *, field: str) -> JSONObject:
+    """`value` as a private mapping. A missing key reads as an empty one."""
+    if value is None:
+        return {}
+    if isinstance(value, Mapping):
+        return copied_mapping(value)
+    raise _wrong(field, "a mapping", value)
+
+
+def as_sequence(value: object, *, field: str) -> tuple[JSONValue, ...]:
+    """`value` as a private tuple. A missing key reads as an empty one."""
+    if value is None:
+        return ()
+    if not isinstance(value, Iterable):
+        raise _wrong(field, "a sequence of values", value)
+    return copied_sequence(value, field=field)
+
+
+__all__ = [
+    "JSONObject",
+    "JSONValue",
+    "as_mapping",
+    "as_optional_float",
+    "as_optional_int",
+    "as_optional_str",
+    "as_sequence",
+    "as_str",
+    "checked_sequence",
+    "copied_mapping",
+    "copied_sequence",
+]

langgraph_acp/_jsonrpc.py

@@ -0,0 +1,248 @@
+"""JSON-RPC 2.0 over a newline-delimited byte stream.
+
+ACP is JSON-RPC 2.0, one message per line, spoken over a child process's stdin
+and stdout. That is a small enough protocol to implement here, and implementing
+it here is what lets this package keep an empty dependency list while still
+talking to a real agent.
+
+The peer knows nothing about ACP. It correlates requests with responses,
+delivers notifications, answers incoming requests through a callback, and
+reports the one failure a pipe has: the far side stopped talking. Everything
+about sessions, prompts, and capabilities lives a layer up.
+
+Both directions carry requests. The agent asks the client for permission, for
+file contents, for a terminal; a peer that could only call outwards would be
+half a connection.
+"""
+
+import asyncio
+import json
+from collections.abc import Awaitable, Callable
+from itertools import count
+
+from langgraph_acp._json import JSONObject, JSONValue
+
+#: The JSON-RPC error codes this peer sends, from the specification's list.
+METHOD_NOT_FOUND = -32601
+INTERNAL_ERROR = -32603
+
+
+class JSONRPCError(Exception):
+    """An error *response*: the far side answered, and the answer was a refusal.
+
+    Distinct from a transport failure. This means the agent is alive and
+    declined; the caller above translates it into whichever `ACPError` describes
+    the operation that was refused.
+    """
+
+    def __init__(self, code: int, message: str, data: JSONValue = None) -> None:
+        super().__init__(f"{message} (code {code})")
+        self.code = code
+        self.message = message
+        self.data = data
+
+    def as_response_error(self) -> JSONObject:
+        error: JSONObject = {"code": self.code, "message": self.message}
+        if self.data is not None:
+            error["data"] = self.data
+        return error
+
+
+class JSONRPCPeer:
+    """One end of a JSON-RPC connection over a pair of asyncio streams."""
+
+    def __init__(
+        self,
+        reader: asyncio.StreamReader,
+        writer: asyncio.StreamWriter,
+        *,
+        on_request: Callable[[str, JSONObject], Awaitable[JSONValue]],
+        on_notification: Callable[[str, JSONObject], None],
+        on_closed: Callable[[], BaseException],
+        on_eof: Callable[[], Awaitable[None]] | None = None,
+    ) -> None:
+        self._reader = reader
+        self._writer = writer
+        self._on_request = on_request
+        self._on_notification = on_notification
+        self._on_closed = on_closed
+        self._on_eof = on_eof
+        self._pending: dict[int, asyncio.Future[JSONValue]] = {}
+        self._ids = count()
+        self._answering: set[asyncio.Task[None]] = set()
+        self._reading: asyncio.Task[None] | None = None
+        self._closed = False
+
+    def start(self) -> None:
+        """Begin reading. Nothing is delivered or correlated until this runs."""
+        if self._reading is None:
+            self._reading = asyncio.create_task(self._read_until_eof())
+
+    async def request(self, method: str, params: JSONObject) -> JSONValue:
+        """Call the far side and wait for its answer.
+
+        Raises `JSONRPCError` if the answer is an error response, or whatever
+        `on_closed` produces if the connection ends before one arrives.
+        """
+        if self._closed:
+            raise self._on_closed()
+        message_id = next(self._ids)
+        future: asyncio.Future[JSONValue] = asyncio.get_running_loop().create_future()
+        self._pending[message_id] = future
+        try:
+            await self._send(
+                {
+                    "jsonrpc": "2.0",
+                    "id": message_id,
+                    "method": method,
+                    "params": params,
+                }
+            )
+            return await future
+        finally:
+            # Popped on every exit, cancellation included: an abandoned turn must
+            # not leave an entry that a late response would resolve.
+            self._pending.pop(message_id, None)
+
+    async def notify(self, method: str, params: JSONObject) -> None:
+        """Tell the far side something. There is no answer to wait for."""
+        await self._send({"jsonrpc": "2.0", "method": method, "params": params})
+
+    def notify_nowait(self, method: str, params: JSONObject) -> None:
+        """Queue a notification without awaiting the write.
+
+        For the one case that cannot await: unwinding a cancelled turn, where
+        every suspension point is another chance to be cancelled again. A
+        notification is a few hundred bytes and the transport buffers it, so the
+        write itself does not block; only backpressure would, and this skips it.
+        """
+        try:
+            self._write({"jsonrpc": "2.0", "method": method, "params": params})
+        except (ConnectionError, RuntimeError):
+            # The pipe is already gone, which is the outcome this was asking for.
+            pass
+
+    async def aclose(self) -> None:
+        """Stop reading, close the write side, and fail anything still pending."""
+        self._closed = True
+        if self._reading is not None:
+            self._reading.cancel()
+            self._reading = None
+        for task in tuple(self._answering):
+            task.cancel()
+        self._fail_pending(None)
+        if not self._writer.is_closing():
+            self._writer.close()
+        try:
+            await self._writer.wait_closed()
+        except (ConnectionError, BrokenPipeError):
+            pass
+
+    def _write(self, message: JSONObject) -> None:
+        self._writer.write(json.dumps(message).encode() + b"\n")
+
+    async def _send(self, message: JSONObject) -> None:
+        if self._closed or self._writer.is_closing():
+            raise self._on_closed()
+        try:
+            self._write(message)
+            await self._writer.drain()
+        except (ConnectionError, RuntimeError) as exc:
+            raise self._on_closed() from exc
+
+    async def _read_until_eof(self) -> None:
+        try:
+            await self._read()
+        except Exception:
+            # A transport failure and a clean EOF are the same event to a caller
+            # waiting on a request: no answer is coming. `on_closed` describes
+            # both, and it can see the exit status and stderr that explain it.
+            pass
+        finally:
+            self._closed = True
+        # Only on the natural path. Cancellation means `aclose` is already
+        # unwinding this connection and will fail what is pending itself.
+        if self._on_eof is not None:
+            await self._on_eof()
+        self._fail_pending(None)
+
+    async def _read(self) -> None:
+        while True:
+            line = await self._reader.readline()
+            if not line:
+                return
+            stripped = line.strip()
+            if not stripped:
+                continue
+            try:
+                message = json.loads(stripped)
+            except json.JSONDecodeError:
+                # Agents write to stdout for reasons other than the protocol.
+                # A line that is not a message cannot be answered or correlated,
+                # and killing the connection over it would be a worse answer.
+                continue
+            if isinstance(message, dict):
+                self._dispatch(message)
+
+    def _dispatch(self, message: dict[str, JSONValue]) -> None:
+        method = message.get("method")
+        if isinstance(method, str):
+            raw_params = message.get("params")
+            params: JSONObject = dict(raw_params) if isinstance(raw_params, dict) else {}
+            message_id = message.get("id")
+            if message_id is None:
+                self._on_notification(method, params)
+            else:
+                task = asyncio.create_task(self._answer(message_id, method, params))
+                self._answering.add(task)
+                task.add_done_callback(self._answering.discard)
+            return
+        self._resolve(message)
+
+    def _resolve(self, message: dict[str, JSONValue]) -> None:
+        message_id = message.get("id")
+        if not isinstance(message_id, int) or isinstance(message_id, bool):
+            return
+        future = self._pending.pop(message_id, None)
+        if future is None or future.done():
+            return
+        error = message.get("error")
+        if isinstance(error, dict):
+            code = error.get("code")
+            detail = error.get("message")
+            future.set_exception(
+                JSONRPCError(
+                    code if isinstance(code, int) else INTERNAL_ERROR,
+                    detail if isinstance(detail, str) else "the agent reported an error",
+                    error.get("data"),
+                )
+            )
+            return
+        future.set_result(message.get("result"))
+
+    async def _answer(self, message_id: JSONValue, method: str, params: JSONObject) -> None:
+        try:
+            result = await self._on_request(method, params)
+        except asyncio.CancelledError:
+            raise
+        except JSONRPCError as exc:
+            reply: JSONObject = {"error": exc.as_response_error()}
+        except Exception as exc:
+            reply = {"error": {"code": INTERNAL_ERROR, "message": str(exc)}}
+        else:
+            reply = {"result": result}
+        try:
+            await self._send({"jsonrpc": "2.0", "id": message_id, **reply})
+        except Exception:
+            # Nothing is listening for this answer any more, and the request that
+            # provoked it has already failed on its own account.
+            pass
+
+    def _fail_pending(self, reason: BaseException | None) -> None:
+        for future in tuple(self._pending.values()):
+            if not future.done():
+                future.set_exception(reason or self._on_closed())
+        self._pending.clear()
+
+
+__all__ = ["INTERNAL_ERROR", "METHOD_NOT_FOUND", "JSONRPCError", "JSONRPCPeer"]