induscode 0.1.0__py3-none-any.whl

induscode/runtime_bridge/bridges/claude_cli.py

@@ -0,0 +1,198 @@
+"""``claude-cli`` bridge — drives an Anthropic-flavoured CLI that emits
+line-delimited stream-json content blocks (port of TS
+``src/runtime-bridge/bridges/claude-cli.ts``).
+
+Wire dialect (each inbound ``ChildMessage.payload`` is one parsed JSON line
+of the CLI's NDJSON stdout):
+
+- ``{"type": "system", "subtype": "init", "session_id": …}`` — the CLI
+  announces the session id it allocated; surfaced as a ``resume`` event so
+  the broker can persist it and reattach the same CLI session later.
+- ``{"type": "content_block_start", "content_block": {"type": …}}`` — a
+  block opens; a ``tool_use`` block carries ``{id, name, input}`` which
+  becomes a fully formed tool call immediately (the CLI batches the input).
+- ``{"type": "content_block_delta", "delta": {"type", "text" | "thinking"}}``
+  — a ``text_delta`` / ``thinking_delta`` chunk; mapped to a ``text`` /
+  ``thinking`` normalized event. ``input_json_delta`` chunks (streamed tool
+  arguments) are ignored here because the bridge emits the tool call from
+  the terminal ``content_block_stop`` snapshot.
+- ``{"type": "message_delta", "delta": {"stop_reason": …}}`` — carries the
+  final stop reason, recorded for the eventual ``finish``.
+- ``{"type": "message_stop"}`` / ``{"type": "result"}`` — the turn is over;
+  finish with the recorded reason.
+- ``{"type": "error", "error": {"message": …}}`` — a runtime fault.
+
+The opening request is the user turn forwarded as the CLI's prompt body; the
+spec's binary/args/env are the broker's concern when it builds the
+transport, so this bridge only formats the protocol body.
+
+The child process is reached exclusively through the injected
+``ChildTransport``; no ``claude`` binary is spawned here.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, Final
+
+from induscode.runtime_bridge.contract import (
+    AssistantMessageEventStream,
+    BridgeEventSink,
+    BridgeFailure,
+    ChildMessage,
+    ChildRequest,
+    ChildTransport,
+    Context,
+    ExchangeOptions,
+    ExternalRuntimeSpec,
+    FinishReason,
+    Model,
+    ResumeEvent,
+    RuntimeAdapterId,
+    RuntimeBridge,
+    ToolCall,
+)
+
+from ._drive import CONTINUE, DONE, ChildParser, ParseStep, as_record, drive_exchange, str_field
+
+__all__ = [
+    "claude_cli_bridge",
+]
+
+#: The adapter id this bridge answers to.
+_ADAPTER: Final = "claude-cli"
+
+
+def _map_stop_reason(raw: str | None) -> FinishReason:
+    """Map an Anthropic ``stop_reason`` string onto a normalized
+    :data:`~induscode.runtime_bridge.contract.FinishReason`."""
+    if raw == "max_tokens":
+        return "length"
+    if raw == "tool_use":
+        return "toolUse"
+    # "end_turn" / "stop_sequence" / anything else settles as a plain stop.
+    return "stop"
+
+
+def _tool_call_from_block(block: Mapping[str, Any]) -> ToolCall | None:
+    """Extract a fully-formed ``ToolCall`` from a ``tool_use`` content block."""
+    id_ = str_field(block, "id")
+    name = str_field(block, "name")
+    if id_ is None or name is None:
+        return None
+    input_ = as_record(block.get("input")) or {}
+    return ToolCall(id=id_, name=name, arguments=input_)
+
+
+def _make_parser() -> ChildParser:
+    """Parse one stream-json line into sink emissions. Records the last-seen
+    stop reason on a small per-exchange closure so ``message_stop`` can
+    finish with it."""
+    stop_reason: FinishReason = "stop"
+
+    def parse(message: ChildMessage, sink: BridgeEventSink) -> ParseStep:
+        nonlocal stop_reason
+        payload = as_record(message.payload)
+        if payload is None:
+            return CONTINUE
+        type_ = str_field(payload, "type")
+
+        match type_:
+            case "system":
+                # Session init: surface the allocated session id as a resume token.
+                if str_field(payload, "subtype") == "init":
+                    session_id = str_field(payload, "session_id")
+                    if session_id is not None:
+                        sink.emit(ResumeEvent(resumeToken=session_id))
+                return CONTINUE
+
+            case "content_block_start":
+                block = as_record(payload.get("content_block"))
+                if block is not None and str_field(block, "type") == "tool_use":
+                    call = _tool_call_from_block(block)
+                    if call is not None:
+                        sink.tool_call(call)
+                return CONTINUE
+
+            case "content_block_delta":
+                delta = as_record(payload.get("delta"))
+                if delta is None:
+                    return CONTINUE
+                delta_type = str_field(delta, "type")
+                if delta_type == "text_delta":
+                    text = str_field(delta, "text")
+                    if text is not None:
+                        sink.text(text)
+                elif delta_type == "thinking_delta":
+                    thinking = str_field(delta, "thinking")
+                    if thinking is not None:
+                        sink.thinking(thinking)
+                # input_json_delta is intentionally dropped — see module header.
+                return CONTINUE
+
+            case "message_delta":
+                delta = as_record(payload.get("delta"))
+                stop_reason = _map_stop_reason(
+                    str_field(delta, "stop_reason") if delta is not None else None
+                )
+                return CONTINUE
+
+            case "error":
+                error = as_record(payload.get("error"))
+                detail = (
+                    str_field(error, "message") if error is not None else None
+                ) or "claude-cli error"
+                sink.finish_error(BridgeFailure(message=detail, cause=payload.get("error")))
+                return DONE
+
+            case "message_stop" | "result":
+                sink.finish_success(stop_reason)
+                return DONE
+
+            case _:
+                return CONTINUE
+
+    return parse
+
+
+def _opening_request(context: Context, opts: ExchangeOptions) -> ChildRequest:
+    """Build the opening request: forward the conversation context as the CLI
+    prompt body, threading the resume token / cwd through so the transport
+    layer can attach the right CLI session."""
+    return ChildRequest(
+        body={
+            "type": "user",
+            "context": context,
+            "resume": opts.resume,
+            "cwd": opts.cwd,
+            "sessionId": opts.sessionId,
+        }
+    )
+
+
+class _ClaudeCliBridge:
+    """The ``claude-cli`` :class:`RuntimeBridge`. Stateless on the contract
+    surface: it parses the injected transport's stream-json into the sink and
+    returns the framework push stream."""
+
+    adapter: RuntimeAdapterId = _ADAPTER
+
+    def run_exchange(
+        self,
+        model: Model,
+        context: Context,
+        opts: ExchangeOptions,
+        transport: ChildTransport,
+    ) -> AssistantMessageEventStream:
+        return drive_exchange(
+            model, opts, transport, _opening_request(context, opts), _make_parser()
+        )
+
+    def requires_credential(self, spec: ExternalRuntimeSpec) -> bool:
+        # An external CLI that owns its own login needs no key on disk; an
+        # api-key spec still resolves a credential from the vault.
+        return spec.authMode == "api-key"
+
+
+#: The shipped ``claude-cli`` bridge singleton.
+claude_cli_bridge: RuntimeBridge = _ClaudeCliBridge()

induscode/runtime_bridge/bridges/codex_cli.py

@@ -0,0 +1,203 @@
+"""``codex-cli`` bridge — drives an OpenAI-flavoured CLI emitting ``--json``
+turn/item events (port of TS ``src/runtime-bridge/bridges/codex-cli.ts``).
+
+Wire dialect (each inbound ``ChildMessage.payload`` is one parsed ``--json``
+event object):
+
+- ``{"type": "thread.started", "thread_id": …}`` — the CLI opened a thread;
+  surfaced as a ``resume`` event so the broker can persist the thread id and
+  continue it on a later exchange.
+- ``{"type": "response.output_text.delta", "delta": …}`` — a chunk of answer
+  text.
+- ``{"type": "response.reasoning_text.delta" | "response.reasoning.delta",
+  "delta": …}`` — a chunk of reasoning text.
+- ``{"type": "response.output_item.done", "item": …}`` /
+  ``{"type": "item.completed", "item": …}`` — a completed item; a
+  ``function_call`` / ``tool_call`` item becomes a fully-formed tool call
+  (its ``arguments`` string is parsed into an object).
+- ``{"type": "turn.completed" | "response.completed"}`` — the turn settled;
+  finish (tool-bearing turns settle as ``toolUse``, else ``stop``).
+- ``{"type": "error" | "turn.failed", "error" | "message": …}`` — a runtime
+  fault.
+
+Item-level ``*.delta`` text is preferred; if a CLI variant only emits whole
+items, the completed-item handler still surfaces the text. The injected
+``ChildTransport`` carries the events — no ``codex`` binary is spawned here.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from typing import Any, Final
+
+from induscode.runtime_bridge.contract import (
+    AssistantMessageEventStream,
+    BridgeEventSink,
+    BridgeFailure,
+    ChildMessage,
+    ChildRequest,
+    ChildTransport,
+    Context,
+    ExchangeOptions,
+    ExternalRuntimeSpec,
+    FinishReason,
+    Model,
+    ResumeEvent,
+    RuntimeAdapterId,
+    RuntimeBridge,
+    ToolCall,
+)
+
+from ._drive import CONTINUE, DONE, ChildParser, ParseStep, as_record, drive_exchange, str_field
+
+__all__ = [
+    "codex_cli_bridge",
+]
+
+#: The adapter id this bridge answers to.
+_ADAPTER: Final = "codex-cli"
+
+
+def _parse_arguments(value: Any) -> Mapping[str, Any]:
+    """Parse a ``--json`` item's ``arguments`` (a JSON string or an object)
+    into a record."""
+    if isinstance(value, str):
+        if len(value) == 0:
+            return {}
+        try:
+            parsed: Any = json.loads(value)
+        except (ValueError, TypeError):
+            return {}
+        return as_record(parsed) or {}
+    return as_record(value) or {}
+
+
+def _tool_call_from_item(item: Mapping[str, Any]) -> ToolCall | None:
+    """Build a ``ToolCall`` from a completed ``function_call`` /
+    ``tool_call`` item."""
+    name = str_field(item, "name")
+    if name is None:
+        return None
+    id_ = str_field(item, "call_id") or str_field(item, "id") or name
+    return ToolCall(id=id_, name=name, arguments=_parse_arguments(item.get("arguments")))
+
+
+def _is_tool_item(item: Mapping[str, Any]) -> bool:
+    """True when a completed item is a tool invocation."""
+    item_type = str_field(item, "type")
+    return item_type == "function_call" or item_type == "tool_call"
+
+
+def _make_parser() -> ChildParser:
+    """Parse one ``--json`` event into sink emissions. Tracks whether any
+    tool call was surfaced so the terminal ``turn.completed`` can settle as
+    ``toolUse``."""
+    saw_tool_call = False
+
+    def handle_completed_item(item: Mapping[str, Any], sink: BridgeEventSink) -> None:
+        nonlocal saw_tool_call
+        if _is_tool_item(item):
+            call = _tool_call_from_item(item)
+            if call is not None:
+                sink.tool_call(call)
+                saw_tool_call = True
+            return
+        # A non-tool completed item may carry the full text for CLI variants
+        # that do not stream `output_text.delta`; surface it if present and
+        # non-empty.
+        text = str_field(item, "text")
+        if text is not None and len(text) > 0:
+            sink.text(text)
+
+    def parse(message: ChildMessage, sink: BridgeEventSink) -> ParseStep:
+        payload = as_record(message.payload)
+        if payload is None:
+            return CONTINUE
+        type_ = str_field(payload, "type")
+
+        match type_:
+            case "thread.started":
+                thread_id = str_field(payload, "thread_id")
+                if thread_id is not None:
+                    sink.emit(ResumeEvent(resumeToken=thread_id))
+                return CONTINUE
+
+            case "response.output_text.delta":
+                delta = str_field(payload, "delta")
+                if delta is not None:
+                    sink.text(delta)
+                return CONTINUE
+
+            case "response.reasoning_text.delta" | "response.reasoning.delta":
+                delta = str_field(payload, "delta")
+                if delta is not None:
+                    sink.thinking(delta)
+                return CONTINUE
+
+            case "response.output_item.done" | "item.completed":
+                item = as_record(payload.get("item"))
+                if item is not None:
+                    handle_completed_item(item, sink)
+                return CONTINUE
+
+            case "error" | "turn.failed":
+                error = as_record(payload.get("error"))
+                detail = (
+                    (str_field(error, "message") if error is not None else None)
+                    or str_field(payload, "message")
+                    or "codex-cli error"
+                )
+                cause = payload.get("error")
+                sink.finish_error(
+                    BridgeFailure(message=detail, cause=cause if cause is not None else payload)
+                )
+                return DONE
+
+            case "turn.completed" | "response.completed":
+                reason: FinishReason = "toolUse" if saw_tool_call else "stop"
+                sink.finish_success(reason)
+                return DONE
+
+            case _:
+                return CONTINUE
+
+    return parse
+
+
+def _opening_request(context: Context, opts: ExchangeOptions) -> ChildRequest:
+    """Build the opening request: the conversation context as the CLI turn
+    input."""
+    return ChildRequest(
+        body={
+            "type": "turn",
+            "context": context,
+            "thread": opts.resume,
+            "cwd": opts.cwd,
+            "sessionId": opts.sessionId,
+        }
+    )
+
+
+class _CodexCliBridge:
+    """The ``codex-cli`` :class:`RuntimeBridge`."""
+
+    adapter: RuntimeAdapterId = _ADAPTER
+
+    def run_exchange(
+        self,
+        model: Model,
+        context: Context,
+        opts: ExchangeOptions,
+        transport: ChildTransport,
+    ) -> AssistantMessageEventStream:
+        return drive_exchange(
+            model, opts, transport, _opening_request(context, opts), _make_parser()
+        )
+
+    def requires_credential(self, spec: ExternalRuntimeSpec) -> bool:
+        return spec.authMode == "api-key"
+
+
+#: The shipped ``codex-cli`` bridge singleton.
+codex_cli_bridge: RuntimeBridge = _CodexCliBridge()

induscode/runtime_bridge/bridges/indusagi_cli.py

@@ -0,0 +1,217 @@
+"""``indusagi-cli`` bridge — drives a peer agent over JSON-RPC (port of TS
+``src/runtime-bridge/bridges/indusagi-cli.ts``).
+
+Unlike the CLI bridges, the peer already speaks (a transport-framed form of)
+the framework event vocabulary, so its messages map onto
+:data:`~induscode.runtime_bridge.contract.NormalizedEvent` near-directly.
+Each inbound ``ChildMessage.payload`` is a JSON-RPC frame:
+
+- a **notification** ``{"method", "params"}`` streams one turn event:
+
+  - ``stream/text``     params ``{delta}``                 → ``text``
+  - ``stream/thinking`` params ``{delta}``                 → ``thinking``
+  - ``stream/toolCall`` params ``{id, name, arguments}``   → ``tool_call``
+  - ``session/resume``  params ``{resumeToken}``           → ``resume``
+  - ``stream/done``     params ``{reason}``                → ``finish``
+  - ``stream/error``    params ``{message, aborted}``      → ``failed``
+
+- a **response** ``{"id", "result" | "error"}`` to the opening
+  ``runExchange`` request: an ``error`` member fails the exchange; a
+  ``result`` is treated as a terminal acknowledgement (``finish``) if the
+  stream has not already settled.
+
+The opening request is a JSON-RPC ``runExchange`` call carrying the context,
+delegate provider, and resume token. The peer is reached only through the
+injected ``ChildTransport``; no peer process is spawned here.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, Final
+
+from induscode.runtime_bridge.contract import (
+    AssistantMessageEventStream,
+    BridgeEventSink,
+    BridgeFailure,
+    ChildMessage,
+    ChildRequest,
+    ChildTransport,
+    Context,
+    ExchangeOptions,
+    ExternalRuntimeSpec,
+    FinishReason,
+    Model,
+    ResumeEvent,
+    RuntimeAdapterId,
+    RuntimeBridge,
+    ToolCall,
+)
+
+from ._drive import CONTINUE, DONE, ChildParser, ParseStep, as_record, drive_exchange, str_field
+
+__all__ = [
+    "indusagi_cli_bridge",
+    "make_indusagi_cli_bridge",
+]
+
+#: The adapter id this bridge answers to.
+_ADAPTER: Final = "indusagi-cli"
+
+#: The JSON-RPC method invoked to start a peer exchange.
+_RPC_METHOD: Final = "runExchange"
+
+#: The peer's finish reasons are the framework's own; narrow defensively.
+_ALLOWED_REASONS: Final[tuple[FinishReason, ...]] = ("stop", "length", "toolUse")
+
+
+def _as_finish_reason(raw: str | None) -> FinishReason:
+    return raw if raw in _ALLOWED_REASONS else "stop"  # type: ignore[return-value]
+
+
+def _tool_call_from_params(params: Mapping[str, Any]) -> ToolCall | None:
+    """Build a ``ToolCall`` from a ``stream/toolCall`` notification's params."""
+    id_ = str_field(params, "id")
+    name = str_field(params, "name")
+    if id_ is None or name is None:
+        return None
+    return ToolCall(id=id_, name=name, arguments=as_record(params.get("arguments")) or {})
+
+
+def _handle_notification(
+    method: str,
+    params: Mapping[str, Any] | None,
+    sink: BridgeEventSink,
+) -> ParseStep:
+    """Dispatch one JSON-RPC notification by method."""
+    match method:
+        case "stream/text":
+            delta = str_field(params, "delta") if params is not None else None
+            if delta is not None:
+                sink.text(delta)
+            return CONTINUE
+        case "stream/thinking":
+            delta = str_field(params, "delta") if params is not None else None
+            if delta is not None:
+                sink.thinking(delta)
+            return CONTINUE
+        case "stream/toolCall":
+            call = _tool_call_from_params(params) if params is not None else None
+            if call is not None:
+                sink.tool_call(call)
+            return CONTINUE
+        case "session/resume":
+            token = str_field(params, "resumeToken") if params is not None else None
+            if token is not None:
+                sink.emit(ResumeEvent(resumeToken=token))
+            return CONTINUE
+        case "stream/done":
+            sink.finish_success(
+                _as_finish_reason(str_field(params, "reason") if params is not None else None)
+            )
+            return DONE
+        case "stream/error":
+            message = (
+                str_field(params, "message") if params is not None else None
+            ) or "indusagi-cli error"
+            aborted = params is not None and params.get("aborted") is True
+            sink.finish_error(BridgeFailure(message=message, aborted=aborted, cause=params))
+            return DONE
+        case _:
+            return CONTINUE
+
+
+def _parse_frame(message: ChildMessage, sink: BridgeEventSink) -> ParseStep:
+    """Parse one JSON-RPC frame (notification or response) into sink
+    emissions."""
+    frame = as_record(message.payload)
+    if frame is None:
+        return CONTINUE
+
+    # A notification carries a `method`; a response carries `result` / `error`.
+    method = str_field(frame, "method")
+    if method is not None:
+        return _handle_notification(method, as_record(frame.get("params")), sink)
+
+    # Response to the opening call.
+    if "error" in frame:
+        error = as_record(frame.get("error"))
+        detail = (
+            str_field(error, "message") if error is not None else None
+        ) or "indusagi-cli rpc error"
+        sink.finish_error(BridgeFailure(message=detail, cause=frame.get("error")))
+        return DONE
+    if "result" in frame:
+        # A bare result acknowledgement settles the exchange if streaming
+        # notifications did not already emit a terminal `stream/done`.
+        return DONE
+    return CONTINUE
+
+
+#: The reusable parser (no per-exchange state; the frame carries everything).
+_parser: ChildParser = _parse_frame
+
+
+def _opening_request(
+    context: Context, opts: ExchangeOptions, spec: ExternalRuntimeSpec
+) -> ChildRequest:
+    """Build the opening JSON-RPC ``runExchange`` request."""
+    return ChildRequest(
+        body={
+            "jsonrpc": "2.0",
+            "id": opts.sessionId if opts.sessionId is not None else _RPC_METHOD,
+            "method": _RPC_METHOD,
+            "params": {
+                "context": context,
+                "delegate": spec.delegate,
+                "resume": opts.resume,
+                "cwd": opts.cwd,
+                "sessionId": opts.sessionId,
+            },
+        }
+    )
+
+
+class _IndusagiCliBridge:
+    """An ``indusagi-cli`` :class:`RuntimeBridge` bound to one spec (so the
+    opening request can forward its ``delegate`` to the peer)."""
+
+    adapter: RuntimeAdapterId = _ADAPTER
+
+    __slots__ = ("_spec",)
+
+    def __init__(self, spec: ExternalRuntimeSpec) -> None:
+        self._spec = spec
+
+    def run_exchange(
+        self,
+        model: Model,
+        context: Context,
+        opts: ExchangeOptions,
+        transport: ChildTransport,
+    ) -> AssistantMessageEventStream:
+        return drive_exchange(
+            model, opts, transport, _opening_request(context, opts, self._spec), _parser
+        )
+
+    def requires_credential(self, spec: ExternalRuntimeSpec) -> bool:
+        return spec.authMode == "api-key"
+
+
+def make_indusagi_cli_bridge(spec: ExternalRuntimeSpec) -> RuntimeBridge:
+    """Build the ``indusagi-cli`` :class:`RuntimeBridge` (TS
+    ``makeIndusagiCliBridge``). The bound :class:`ExternalRuntimeSpec` is
+    captured so the opening request can forward its ``delegate`` to the peer;
+    the broker constructs one bridge per spec it routes to.
+
+    :param spec: the runtime annotation whose ``delegate`` the peer should target
+    """
+    return _IndusagiCliBridge(spec)
+
+
+#: A default ``indusagi-cli`` bridge bound to a spec with no delegate. Use
+#: :func:`make_indusagi_cli_bridge` when a delegate provider must be
+#: forwarded.
+indusagi_cli_bridge: RuntimeBridge = make_indusagi_cli_bridge(
+    ExternalRuntimeSpec(adapter=_ADAPTER, authMode="external-cli")
+)