induscode 0.1.0__py3-none-any.whl

induscode/channels/contract.py

@@ -0,0 +1,585 @@
+"""Channels contract — the FROZEN type surface of the non-interactive drivers
+(port of TS ``src/channels/contract.ts``).
+
+A *channel* is a way to talk to a
+:class:`~induscode.conductor.contract.SessionConductor` from outside the
+interactive terminal. Two channels share this contract:
+
+- the **oneshot** channel runs a single request to settlement and writes the
+  result to a stream (clean text, or a streamed NDJSON event log);
+- the **link** channel is a long-lived, bidirectional JSON-RPC 2.0 server plus
+  a typed driver (client) that drives a child process over NDJSON.
+
+This module declares *only* shapes and a handful of inert, pure helpers — no
+I/O, no process plumbing, no dispatch. The server, the driver, the framer, and
+the oneshot runner are each written against the names declared here, so the
+file is intentionally small, append-mostly, and stable.
+
+Design stance (ported):
+
+- The protocol is **one declarative operation registry**, not a hand-written
+  dispatch ladder mirrored by hand-written client methods. An :class:`Op`
+  pairs a wire ``method`` name with a typed ``handle``; an :data:`OpRegistry`
+  (the result of :func:`define_ops`) is consumed by *both* the server
+  (data-driven dispatch) and the link driver (a generated client whose method
+  set is derived from the same registry).
+- The wire envelope is **JSON-RPC 2.0**: a request carries
+  ``{jsonrpc, id?, method, params?}``, a reply carries ``{jsonrpc, id,
+  result}`` or ``{jsonrpc, id, error}``. Decoded frames are plain mappings
+  (what :func:`json.loads` yields); :func:`is_reply_ok` discriminates the
+  reply arms and :data:`OP_ERROR` pins the error codes.
+- Framing is **NDJSON**, one JSON value per line. The framer (the
+  ``encode_line`` / ``decode_lines`` pair bundled as :class:`NdjsonFramer`)
+  is correct by construction: it escapes the two line separators (U+2028,
+  U+2029) that are valid inside a JSON string but break a naive line
+  splitter, and it pulls lines with an async generator rather than an event
+  callback.
+- The transport is **injectable**. A :class:`ChannelContext` carries the
+  conductor plus the streams and the dialog primitives, so tests drive the
+  channels over in-memory pipes with no real stdio.
+
+Port notes
+----------
+- TS wire-frame interfaces (``OpRequest`` / ``ReplyOk`` / ``ReplyErr``) were
+  structural views over plain parsed objects; in Python the decoded frames
+  *are* plain dicts, so the envelope is documented here (and pinned by
+  :data:`OP_ERROR` / :data:`PROTOCOL_VERSION` / :func:`is_reply_ok`) while the
+  consumer-facing frames that cross Python API boundaries (:class:`Ask`,
+  :class:`AskAnswer`, :class:`Tell`, :class:`Signal`, :class:`OpError`) stay
+  typed frozen dataclasses.
+- Wire field names/casing are kept **verbatim** from TS (``jsonrpc``,
+  ``method``, ``params``, ``result``, ``error``, ``sessionId``,
+  ``autoCondense``, ``messageCount``, ``queuedCount``, …) for cross-host
+  compatibility — a TS driver must be able to speak to a Python server and
+  vice versa. :data:`LINK_SNAPSHOT_FIELDS` pins the snapshot vocabulary.
+- ``signal_to_wire`` is a Python-only helper: TS ``JSON.stringify`` serialized
+  a :data:`SessionSignal` verbatim, but the Python signal dataclasses carry
+  their ``kind`` tag as a ``ClassVar`` which the one app-wide codec
+  (:func:`~induscode.conductor.serialize.message_to_dict`, plan rule 2) does
+  not emit — this helper re-attaches it. No second serializer is introduced.
+- Timings stay in **milliseconds** with the TS camelCase field names; asyncio
+  call sites divide by 1000.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterable, Awaitable, Callable, Mapping
+from dataclasses import dataclass, replace
+from types import MappingProxyType
+from typing import Any, ClassVar, Final, Literal, Protocol, TypeAlias, TypeVar
+
+from induscode.conductor.contract import (
+    ConductorState,
+    SessionConductor,
+    SessionSignal,
+    ThinkingLevel,
+    Usage,
+)
+from induscode.conductor.serialize import message_to_dict
+
+__all__ = [
+    "Ask",
+    "AskAnswer",
+    "ChannelContext",
+    "ChannelTimings",
+    "ConductorState",
+    "DEFAULT_CHANNEL_TIMINGS",
+    "DialogBridge",
+    "LINK_SNAPSHOT_FIELDS",
+    "LinkSnapshot",
+    "NdjsonFramer",
+    "OP_ERROR",
+    "OneshotRequest",
+    "OneshotShape",
+    "OneshotStrategy",
+    "Op",
+    "OpError",
+    "OpRegistry",
+    "PROTOCOL_VERSION",
+    "REQUEST_ID_PREFIX",
+    "ReadableChunks",
+    "RequestId",
+    "SessionConductor",
+    "Signal",
+    "Tell",
+    "ThinkingLevel",
+    "Usage",
+    "WritableLine",
+    "define_ops",
+    "is_reply_ok",
+    "mint_wire_id",
+    "resolve_timings",
+    "signal_to_wire",
+]
+
+_T = TypeVar("_T")
+
+
+# ---------------------------------------------------------------------------
+# JSON-RPC 2.0 envelope
+# ---------------------------------------------------------------------------
+
+#: The protocol version literal stamped on every framed envelope.
+PROTOCOL_VERSION: Final[str] = "2.0"
+
+#: The id correlating a request to its reply.
+#:
+#: A request with an id expects exactly one reply bearing the same id; a
+#: request without an id is a notification and is never replied to. Numeric
+#: ids are accepted on the wire but the driver mints string ids.
+RequestId: TypeAlias = str | int
+
+
+@dataclass(frozen=True, slots=True)
+class OpError:
+    """A typed error returned by a failed operation.
+
+    The ``code`` is a small integer category (negative values follow the
+    JSON-RPC reserved ranges); ``message`` is a single-line human summary; the
+    optional ``data`` carries structured detail for logging without parsing
+    the message. On the wire this frames as ``{"code", "message", "data"?}``.
+    """
+
+    #: Numeric error category.
+    code: int
+    #: Human-readable, single-line summary.
+    message: str
+    #: Optional structured detail.
+    data: Any = None
+
+
+def is_reply_ok(reply: Mapping[str, Any]) -> bool:
+    """Whether a decoded reply frame is the success arm (``result`` present).
+
+    The reply envelope is either ``{jsonrpc, id, result}`` or ``{jsonrpc, id,
+    error}``; this discriminates by presence of the ``result`` key — the same
+    rule the TS ``isReplyOk`` guard applied.
+    """
+    return "result" in reply
+
+
+#: The closed set of error codes the channels mint (JSON-RPC reserved values,
+#: exact — cross-cutting plan rule 8).
+OP_ERROR: Final[Mapping[str, int]] = MappingProxyType(
+    {
+        # The framed line was not valid JSON.
+        "parse": -32700,
+        # The frame was not a well-formed request.
+        "invalidRequest": -32600,
+        # No operation is registered under the requested `method`.
+        "unknownOp": -32601,
+        # The `params` failed the operation schema.
+        "invalidParams": -32602,
+        # The operation handler threw.
+        "handlerFailed": -32000,
+    }
+)
+
+
+# ---------------------------------------------------------------------------
+# Streams & transport
+# ---------------------------------------------------------------------------
+
+
+class WritableLine(Protocol):
+    """The minimal writable surface a channel emits onto.
+
+    Pinning the dependency to this one method (rather than an asyncio stream
+    writer) is what lets a test capture output into a list while production
+    passes a real stdout adapter. (The TS optional drain callback is dropped —
+    asyncio writers expose no such hook; flushing is the embedder's concern.)
+    """
+
+    def write(self, chunk: str) -> object:
+        """Write one already-framed chunk."""
+        ...
+
+
+#: The minimal readable surface a channel consumes: an async-iterable of
+#: string or byte chunks — exactly what a stdio reader and an in-memory pipe
+#: both satisfy. The framer turns this chunk stream into a line stream;
+#: nothing else reads it directly.
+ReadableChunks: TypeAlias = AsyncIterable[str | bytes]
+
+
+# ---------------------------------------------------------------------------
+# NDJSON framer
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class NdjsonFramer:
+    """The NDJSON framer pair: the two halves of the line transport.
+
+    Bundled so the server, the driver, and the oneshot channel all share one
+    correct implementation rather than re-deriving framing at each call site.
+    The concrete pair lives in :mod:`induscode.channels.framer`; an embedder
+    may inject an alternate framer through the driver / server options.
+    """
+
+    #: Serialize one value to a newline-terminated, separator-safe line.
+    encode_line: Callable[[Any], str]
+    #: Pull parsed values from a chunk stream, one per ``\n`` (an async
+    #: generator function over a :data:`ReadableChunks`).
+    decode_lines: Callable[[ReadableChunks], Any]
+
+
+# ---------------------------------------------------------------------------
+# Dialog primitives (ask / tell)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class Ask:
+    """A blocking request from the agent to whoever is driving the channel.
+
+    ``ask`` is the round-trip dialog primitive: the server emits an ``ask``
+    frame and suspends until a matching answer arrives (or the deadline
+    lapses). The ``kind`` names the interaction (a choice, a confirm, a
+    free-text prompt, an editor session); ``payload`` carries the
+    kind-specific options; the ``id`` correlates the eventual answer. Wire
+    form: ``{"type": "ask", "id", "kind", "payload"?}``.
+    """
+
+    #: Frame discriminant on the wire.
+    type: ClassVar[Literal["ask"]] = "ask"
+    #: Correlation id for the answer.
+    id: str
+    #: The interaction kind (e.g. ``"select"``, ``"confirm"``, ``"input"``).
+    kind: str
+    #: Kind-specific options for the interaction.
+    payload: Any = None
+
+
+@dataclass(frozen=True, slots=True)
+class AskAnswer:
+    """The answer to an :class:`Ask`, correlated by its ``id``. Wire form:
+    ``{"type": "answer", "id", "value"}``."""
+
+    #: Frame discriminant on the wire.
+    type: ClassVar[Literal["answer"]] = "answer"
+    #: The id of the :class:`Ask` this answers.
+    id: str
+    #: The supplied value (kind-specific; ``None`` when dismissed).
+    value: Any = None
+
+
+@dataclass(frozen=True, slots=True)
+class Tell:
+    """A one-way notice from the agent to the driver — no answer expected.
+
+    ``tell`` is the fire-and-forget dialog primitive: status updates, a
+    flashed notification, a title change. Wire form: ``{"type": "tell",
+    "kind", "payload"?}``.
+    """
+
+    #: Frame discriminant on the wire.
+    type: ClassVar[Literal["tell"]] = "tell"
+    #: The notice kind (e.g. ``"notify"``, ``"status"``, ``"title"``).
+    kind: str
+    #: Kind-specific detail.
+    payload: Any = None
+
+
+class DialogBridge(Protocol):
+    """The dialog seam a channel exposes to the agent/extension layer.
+
+    One generic round-trip primitive (:meth:`ask`) plus one fire-and-forget
+    primitive (:meth:`tell`); every concrete dialog method (select, confirm,
+    input, notify, set-status, …) is expressed in terms of these two, so there
+    is no per-method choreography to repeat.
+    """
+
+    async def ask(self, kind: str, payload: Any, fallback: _T) -> _T:
+        """Emit an :class:`Ask` and resolve with the matching answer value.
+
+        Resolves with ``fallback`` if no answer arrives before the deadline,
+        so a disconnected or non-interactive driver never wedges the agent.
+
+        :param kind: the interaction kind
+        :param payload: kind-specific options
+        :param fallback: value to resolve with on timeout / dismissal
+        """
+        ...
+
+    def tell(self, kind: str, payload: Any = None) -> None:
+        """Emit a :class:`Tell` and return immediately.
+
+        :param kind: the notice kind
+        :param payload: kind-specific detail
+        """
+        ...
+
+
+# ---------------------------------------------------------------------------
+# Channel context
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelContext:
+    """The execution context handed to every :attr:`Op.handle` and shared by
+    both channels.
+
+    It bundles the :class:`SessionConductor` an operation delegates to, the
+    framed transport (``out`` to emit, ``framer`` to encode), and the
+    :class:`DialogBridge` for blocking/fire-and-forget interaction. Everything
+    is injected, so a test supplies a fake conductor, a list-backed
+    :class:`WritableLine`, and an in-memory dialog bridge with no real process
+    attached.
+    """
+
+    #: The session this channel drives; every op delegates to it.
+    conductor: SessionConductor
+    #: The framed output sink for replies, signals, and dialog frames.
+    out: WritableLine
+    #: The shared NDJSON framer.
+    framer: NdjsonFramer
+    #: The dialog round-trip / notice bridge.
+    dialog: DialogBridge
+
+
+# ---------------------------------------------------------------------------
+# Operation registry
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class Op:
+    """A single named operation in the link protocol.
+
+    An op binds a wire ``method`` name to a typed ``handle``: given the
+    request ``params`` (the decoded wire payload — ``None`` when the op takes
+    none) and the :class:`ChannelContext`, it produces a result. The server
+    invokes ``handle`` on a matching request and frames its resolved value
+    into a reply; the link driver exposes a method of the same name that
+    round-trips params to result. One declaration drives both halves.
+    """
+
+    #: The wire method name; the registry key and the driver method name.
+    method: str
+    #: Run the operation against the live session.
+    handle: Callable[[Any, ChannelContext], Awaitable[Any]]
+
+
+#: A map of operation name to its :class:`Op` declaration — what
+#: :func:`define_ops` produces and what both the server and the link driver
+#: consume. Keyed by the same string used as each op's ``method``, so dispatch
+#: is a single lookup and the driver's method set is exactly the key set.
+OpRegistry: TypeAlias = Mapping[str, Op]
+
+
+def define_ops(ops: Mapping[str, Op]) -> OpRegistry:
+    """Freeze a set of operation declarations into an :data:`OpRegistry`.
+
+    The lone sanctioned way to mint a registry, so the dispatch map and the
+    driver method set always derive from one frozen source. Each entry's key
+    is the wire method name; the value is the :class:`Op`. The result is a
+    read-only mapping so neither half can mutate the protocol at runtime.
+
+    :param ops: a record of method-name → :class:`Op`
+    :returns: the frozen registry
+    """
+    return MappingProxyType(dict(ops))
+
+
+# ---------------------------------------------------------------------------
+# Session-state projection
+# ---------------------------------------------------------------------------
+
+#: The session-state projection sent over the link.
+#:
+#: A flat, serializable snapshot of everything a driver needs to mirror the
+#: session without holding a live conductor: which model is bound, the
+#: reasoning effort, the busy flags, the persisted location, and the queue
+#: depth. It is the link's own vocabulary — derived from the conductor's
+#: :class:`ConductorState` but shaped for the wire, not a passthrough of the
+#: internal state object. On the wire (and in Python) it is a plain dict whose
+#: keys are exactly :data:`LINK_SNAPSHOT_FIELDS`, produced by
+#: :func:`induscode.channels.session_ops.project_snapshot`.
+LinkSnapshot: TypeAlias = dict[str, Any]
+
+#: The verbatim TS wire field names of a :data:`LinkSnapshot`, pinned for
+#: cross-host compatibility (``sessionFile`` is optional and absent when the
+#: session is not persisted).
+LINK_SNAPSHOT_FIELDS: Final[tuple[str, ...]] = (
+    "model",
+    "thinking",
+    "streaming",
+    "condensing",
+    "faulted",
+    "sessionId",
+    "sessionFile",
+    "autoCondense",
+    "messageCount",
+    "queuedCount",
+    "usage",
+)
+
+
+# ---------------------------------------------------------------------------
+# Signals
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class Signal:
+    """An uncorrelated event frame streamed from server to driver.
+
+    Distinct from a reply (which answers a specific request): a signal is
+    pushed as the turn progresses and carries no ``id``. The driver fans
+    signals out to its listener; the oneshot NDJSON shape writes them straight
+    to the sink. Wire form: ``{"type": "signal", "name", "body"}``.
+    """
+
+    #: Frame discriminant on the wire.
+    type: ClassVar[Literal["signal"]] = "signal"
+    #: The signal name (the conductor signal kind, projected to the wire).
+    name: str
+    #: The signal's payload.
+    body: Any = None
+
+
+def signal_to_wire(signal: SessionSignal) -> dict[str, Any]:
+    """Project a conductor :data:`SessionSignal` to its wire dict.
+
+    TS serialized the signal object verbatim (its ``kind`` is a plain
+    property); the Python signal dataclasses carry ``kind`` as a ``ClassVar``
+    which the one app-wide codec
+    (:func:`~induscode.conductor.serialize.message_to_dict`) does not emit, so
+    this helper re-attaches the discriminant. The field payload still flows
+    through that codec — no second serializer (plan rule 2).
+    """
+    body = message_to_dict(signal)
+    wire: dict[str, Any] = {"kind": signal.kind}
+    if isinstance(body, Mapping):
+        for key, value in body.items():
+            wire[key] = value
+    return wire
+
+
+# ---------------------------------------------------------------------------
+# Oneshot channel
+# ---------------------------------------------------------------------------
+
+#: The two output shapes the oneshot channel can produce.
+OneshotShape: TypeAlias = Literal["text", "ndjson"]
+
+
+@dataclass(frozen=True, slots=True)
+class OneshotRequest:
+    """The request the oneshot channel runs.
+
+    One or more prompts run sequentially to settlement; ``images`` ride along
+    with the first. ``shape`` selects between clean final text and a streamed
+    NDJSON event log.
+    """
+
+    #: Output shape: clean final text, or a streamed NDJSON event log.
+    shape: OneshotShape
+    #: The prompts to run, in order.
+    prompts: tuple[str, ...]
+    #: Images attached to the first prompt, if any (framework
+    #: ``indusagi.ai.ImageContent`` values).
+    images: tuple[Any, ...] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class OneshotStrategy:
+    """A pluggable per-shape strategy for the oneshot channel.
+
+    Each shape (:data:`OneshotShape`) supplies one of these: ``on_start`` runs
+    once before the prompts (e.g. emit a header line for NDJSON),
+    ``on_signal`` reacts to each conductor signal (NDJSON emits; text
+    ignores), and ``finish`` turns the settled state into the process exit
+    code (0 ok, 1 on fault). Selecting a shape is choosing a strategy object —
+    there are no shape branches sprinkled through the runner body. ``on_start``
+    and ``finish`` may be sync or return an awaitable (the TS
+    ``void | Promise<void>`` / ``number | Promise<number>`` latitude).
+    """
+
+    #: Produce the exit code from the settled state once all prompts resolve.
+    finish: Callable[[ConductorState, ChannelContext], Any]
+    #: Run once before any prompt is submitted.
+    on_start: Callable[[ChannelContext], Any] | None = None
+    #: React to one streamed signal as the turn progresses.
+    on_signal: Callable[[SessionSignal, ChannelContext], None] | None = None
+
+
+# ---------------------------------------------------------------------------
+# Driver / server configuration
+# ---------------------------------------------------------------------------
+
+#: The request-id prefix the driver stamps on outgoing requests.
+REQUEST_ID_PREFIX: Final[str] = "lnk-"
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelTimings:
+    """Timeouts and intervals the channels need, sourced from config rather
+    than hard-coded at the call sites.
+
+    Every duration is in **milliseconds** (field names and units verbatim from
+    TS; asyncio call sites divide by 1000). Defaults are supplied by
+    :data:`DEFAULT_CHANNEL_TIMINGS`; an embedder may override any of them when
+    it constructs a driver or server.
+    """
+
+    #: How long to wait for a spawned child to report ready before failing.
+    startupMs: int
+    #: Grace period after a soft terminate before a hard kill.
+    shutdownMs: int
+    #: How long a sent request waits for its reply before rejecting.
+    requestMs: int
+    #: How long :meth:`DialogBridge.ask` waits before resolving its fallback.
+    dialogMs: int
+
+
+#: The default :class:`ChannelTimings` — deliberately distinct values, owned
+#: here and overridable, not a copied constant set scattered across runners.
+DEFAULT_CHANNEL_TIMINGS: Final[ChannelTimings] = ChannelTimings(
+    startupMs=1_500,
+    shutdownMs=1_200,
+    requestMs=45_000,
+    dialogMs=90_000,
+)
+
+
+def resolve_timings(overrides: Mapping[str, int] | None = None) -> ChannelTimings:
+    """Merge partial timing overrides onto the frozen defaults.
+
+    (TS kept a private copy of this in both the server and the driver; the
+    Python port hosts the one merge here.)
+
+    :param overrides: any subset of :class:`ChannelTimings` field names
+    """
+    if overrides is None or len(overrides) == 0:
+        return DEFAULT_CHANNEL_TIMINGS
+    return replace(DEFAULT_CHANNEL_TIMINGS, **dict(overrides))
+
+
+# ---------------------------------------------------------------------------
+# Id minting
+# ---------------------------------------------------------------------------
+
+_BASE36_DIGITS: Final[str] = "0123456789abcdefghijklmnopqrstuvwxyz"
+
+
+def _base36(n: int) -> str:
+    """Lowercase base-36 rendering of a non-negative int (TS ``toString(36)``)."""
+    if n <= 0:
+        return "0"
+    out: list[str] = []
+    while n > 0:
+        n, r = divmod(n, 36)
+        out.append(_BASE36_DIGITS[r])
+    return "".join(reversed(out))
+
+
+def mint_wire_id(prefix: str, now_ms: int, seq: int) -> str:
+    """Mint a process-unique correlation id: ``<prefix><now36>-<seq36>``.
+
+    The same shape the TS driver (``lnk-…``) and dialog bridge (``ask-…``)
+    minted with ``Date.now().toString(36)`` + a sequence counter.
+    """
+    return f"{prefix}{_base36(now_ms)}-{_base36(seq)}"