induscode 0.1.0__py3-none-any.whl

induscode/runtime_bridge/contract.py

@@ -0,0 +1,734 @@
+"""Runtime-bridge contract — the FROZEN type surface of provider *routing*
+(port of TS ``src/runtime-bridge/contract.ts`` + the type half of
+``broker.ts``).
+
+This module is the single typed seam that decides, per model, **where a turn
+is actually produced**: by the framework's own network stream
+(:func:`indusagi.ai.stream_simple` over an HTTP provider) or by an *external
+runtime* — a child coding-agent process driven over its own protocol (an
+Anthropic-flavoured CLI speaking line-delimited JSON, an OpenAI-flavoured CLI
+emitting ``--json`` items, or a peer agent reachable over JSON-RPC). The
+product never calls a bridge or the framework stream directly; it asks the
+:class:`RuntimeBroker` to route, and the broker picks the path.
+
+Design stance (unchanged from the TS source):
+
+- A model is *annotated*, not re-catalogued. The model catalog/matcher own
+  the model list; this layer only attaches an optional
+  :class:`ExternalRuntimeSpec` that says "this model is backed by a spawned
+  CLI / a peer agent, here is how to reach it and authenticate". A model
+  with no spec routes normally.
+- Every external runtime speaks a *different* wire dialect, but the broker
+  should not care. Each bridge is reduced to a **parser** that yields a
+  provider-neutral :data:`NormalizedEvent` stream, and the single
+  :class:`BridgeEventSink` translates those events into the framework's
+  :class:`~indusagi.ai.AssistantMessageEventStream` push shape. The
+  imperative ``push_start/push_text_delta/push_done`` idiom lives in exactly
+  one place (:mod:`induscode.runtime_bridge.sink`).
+- The child process / RPC peer a bridge drives is reached through an
+  **injectable** :class:`ChildTransport`, never a hard-coded spawn. Tests
+  hand the bridge a fake transport so no real ``claude``/``codex`` binary is
+  launched.
+- Authentication policy is data, not control flow:
+  :meth:`RuntimeBridge.requires_credential` answers "does this model need a
+  key on disk before it can be offered?" — a spawned-CLI runtime that owns
+  its own auth returns ``False``, letting the model appear available with no
+  key.
+
+Framework anchors (all from the sibling rebuilt framework, the ``indusagi``
+package) — consumed verbatim, never re-derived: ``Model``, ``Context``,
+``AssistantMessage``, ``AssistantMessageEventStream``, ``Api``,
+``StopReason``, ``ToolCall``, ``SimpleStreamOptions``, ``KnownProvider`` from
+:mod:`indusagi.ai`; ``stream_simple`` is the network fallback the broker
+routes to.
+
+Interface-dictated shapes preserved as-is: the ``bridge:<adapter>`` synthetic
+endpoint convention for runtime-backed models, and the external CLI protocol
+vocabularies — surfaced only as the opaque payloads a :class:`ChildTransport`
+carries, never re-expressed.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass, field
+from typing import Any, ClassVar, Final, Literal, Protocol, TypeAlias
+
+# Re-exported framework vocabulary routing consumers routinely compose.
+from indusagi.ai import (
+    Api,
+    AssistantMessage,
+    AssistantMessageEventStream,
+    Context,
+    KnownProvider,
+    Model,
+    SimpleStreamOptions,
+    StopReason,
+    ToolCall,
+)
+
+__all__ = [
+    "Api",
+    "AssistantMessage",
+    "AssistantMessageEventStream",
+    "BridgeEventSink",
+    "BridgeFailure",
+    "ChildMessage",
+    "ChildRequest",
+    "ChildTransport",
+    "ChildTransportFactory",
+    "Context",
+    "ExchangeOptions",
+    "ExternalRoute",
+    "ExternalRuntimeSpec",
+    "FailedEvent",
+    "FinishEvent",
+    "FinishReason",
+    "FrameworkRoute",
+    "FrameworkStream",
+    "KnownProvider",
+    "Model",
+    "NORMALIZED_EVENT_KINDS",
+    "NormalizedEvent",
+    "NormalizedEventKind",
+    "RUNTIME_ENDPOINT_SCHEME",
+    "RUNTIME_LINK_ENTRY",
+    "ResumeEvent",
+    "RuntimeAdapterId",
+    "RuntimeAuthMode",
+    "RuntimeBridge",
+    "RuntimeBroker",
+    "RuntimeEndpointScheme",
+    "RuntimeLink",
+    "RuntimeLinkEntryTag",
+    "RuntimeLinkStore",
+    "RuntimeRoute",
+    "SimpleStreamOptions",
+    "StopReason",
+    "TextEvent",
+    "ThinkingEvent",
+    "ToolCall",
+    "ToolCallEvent",
+    "TransportContext",
+    "runtime_endpoint",
+]
+
+
+# ---------------------------------------------------------------------------
+# External-runtime annotation
+# ---------------------------------------------------------------------------
+
+#: The set of bridge adapters this layer ships. Each value names a concrete
+#: :class:`RuntimeBridge` implementation and the wire dialect it speaks:
+#:
+#: - ``"claude-cli"``   — drives an Anthropic-flavoured CLI emitting
+#:   line-delimited stream-json content blocks.
+#: - ``"codex-cli"``    — drives an OpenAI-flavoured CLI emitting ``--json``
+#:   turn/item events.
+#: - ``"indusagi-cli"`` — drives a peer agent over JSON-RPC; the child
+#:   already speaks the framework event vocabulary, so its events map onto
+#:   :data:`NormalizedEvent` near-directly.
+#:
+#: Left open (TS ``(string & {})``) so an extension can register a further
+#: adapter without editing this alias, while the three shipped ids live in
+#: ``bridges.BUILTIN_ADAPTERS``.
+RuntimeAdapterId: TypeAlias = str
+
+#: How a model bound to an external runtime authenticates.
+#:
+#: - ``"external-cli"`` — the spawned child owns its own auth (its own login
+#:   / keychain); the product needs **no** key on disk, so the model can be
+#:   offered as available with an empty vault. This is the policy that makes
+#:   a CLI-backed model "just work" once the underlying tool is logged in.
+#: - ``"api-key"`` — the runtime still needs an API key resolved from the
+#:   credential vault, same as a normal HTTP provider; only the *transport*
+#:   differs.
+RuntimeAuthMode: TypeAlias = Literal["external-cli", "api-key"]
+
+
+@dataclass(frozen=True, slots=True)
+class ExternalRuntimeSpec:
+    """The annotation that turns an ordinary framework ``Model`` into an
+    external-runtime model (TS ``ExternalRuntimeSpec``).
+
+    Attached alongside a catalog card (it is *additive* metadata — the
+    catalog/matcher are unaware of it) and consulted by the
+    :class:`RuntimeBroker` to decide routing. All transport fields are
+    optional: a bridge may have a sensible default binary, take no extra
+    args, inherit the parent environment, and route to its own downstream
+    source. Only ``adapter`` is required, because it selects which
+    :class:`RuntimeBridge` owns the exchange. Field names keep the TS
+    spelling.
+    """
+
+    #: Which bridge owns this model's exchange (the :attr:`RuntimeBridge.adapter`).
+    adapter: RuntimeAdapterId
+    #: Whether the runtime needs a key on disk, or owns its own auth.
+    authMode: RuntimeAuthMode
+    #: Override for the child executable to launch (defaults to the bridge's own).
+    binaryPath: str | None = None
+    #: Extra command-line arguments prepended to the bridge's protocol flags.
+    args: tuple[str, ...] | None = None
+    #: Environment overrides merged into the child process environment.
+    env: Mapping[str, str] | None = None
+    #: For a bridge that fronts another source (e.g. a peer agent that itself
+    #: talks to a downstream provider), the provider slug the child should
+    #: target. Ignored by bridges that terminate the exchange themselves.
+    delegate: str | None = None
+
+
+#: The synthetic endpoint scheme stamped onto a runtime-backed model's
+#: ``baseUrl``. A model annotated with :class:`ExternalRuntimeSpec` carries
+#: ``baseUrl == f"{RUNTIME_ENDPOINT_SCHEME}{adapter}"`` so it has a stable,
+#: non-HTTP address that never resolves to a network host.
+RUNTIME_ENDPOINT_SCHEME: Final = "bridge:"
+
+#: The literal type of :data:`RUNTIME_ENDPOINT_SCHEME`.
+RuntimeEndpointScheme: TypeAlias = Literal["bridge:"]
+
+
+def runtime_endpoint(adapter: RuntimeAdapterId) -> str:
+    """Compose the synthetic ``bridge:<adapter>`` endpoint for a
+    runtime-backed model. Inert string helper; the single sanctioned way to
+    mint the convention so it stays uniform across the catalog annotation
+    and the broker's routing check.
+
+    :param adapter: the :attr:`RuntimeBridge.adapter` owning the model
+    """
+    return f"{RUNTIME_ENDPOINT_SCHEME}{adapter}"
+
+
+# ---------------------------------------------------------------------------
+# Normalized, provider-neutral event
+# ---------------------------------------------------------------------------
+#
+# A provider-neutral streamed event — the common currency between a bridge's
+# per-dialect parser and the BridgeEventSink. Each external runtime emits its
+# own wire vocabulary (Anthropic content blocks, OpenAI items, peer JSON-RPC
+# events). A bridge's only job is to map that vocabulary onto this small,
+# closed union; the sink then translates a NormalizedEvent into the matching
+# framework AssistantMessageEventStream push call. This is the seam that
+# removes the per-bridge `stream.push*` duplication.
+
+#: The terminal reasons an external exchange can settle on. A subset of the
+#: framework's ``StopReason`` — the non-error outcomes a bridge reports to
+#: the sink, which then emits the framework ``done`` event.
+FinishReason: TypeAlias = Literal["stop", "length", "toolUse"]
+
+
+@dataclass(frozen=True, slots=True)
+class BridgeFailure:
+    """A typed failure surfaced by a bridge when an external exchange breaks
+    (TS ``BridgeFailure``). The ``aborted`` flag distinguishes a
+    caller-cancelled exchange (the child was interrupted) from a genuine
+    fault, so the sink can emit the matching framework error reason
+    (``aborted`` vs ``error``)."""
+
+    #: Human-readable, single-line summary of what went wrong.
+    message: str
+    #: True when the exchange was cancelled rather than failing on its own.
+    aborted: bool = False
+    #: Underlying error or structured detail, if any.
+    cause: Any = None
+
+
+@dataclass(frozen=True, slots=True)
+class TextEvent:
+    """A chunk of assistant answer text."""
+
+    kind: ClassVar[Literal["text"]] = "text"
+    delta: str
+
+
+@dataclass(frozen=True, slots=True)
+class ThinkingEvent:
+    """A chunk of reasoning text (runtimes without a thinking channel simply
+    never emit this)."""
+
+    kind: ClassVar[Literal["thinking"]] = "thinking"
+    delta: str
+
+
+@dataclass(frozen=True, slots=True)
+class ToolCallEvent:
+    """A fully-formed tool invocation the child decided on."""
+
+    kind: ClassVar[Literal["tool_call"]] = "tool_call"
+    call: ToolCall
+
+
+@dataclass(frozen=True, slots=True)
+class ResumeEvent:
+    """The child reported a session/thread id the bridge can persist to
+    reattach the underlying CLI session after a restart. Informational on the
+    stream (the sink ignores it); the broker persists it out of band."""
+
+    kind: ClassVar[Literal["resume"]] = "resume"
+    resumeToken: str
+
+
+@dataclass(frozen=True, slots=True)
+class FinishEvent:
+    """The exchange settled successfully with a terminal reason."""
+
+    kind: ClassVar[Literal["finish"]] = "finish"
+    reason: FinishReason
+
+
+@dataclass(frozen=True, slots=True)
+class FailedEvent:
+    """The exchange ended in error."""
+
+    kind: ClassVar[Literal["failed"]] = "failed"
+    error: BridgeFailure
+
+
+#: The provider-neutral event union (TS ``NormalizedEvent``).
+NormalizedEvent: TypeAlias = (
+    TextEvent | ThinkingEvent | ToolCallEvent | ResumeEvent | FinishEvent | FailedEvent
+)
+
+#: The discriminant literals of :data:`NormalizedEvent`, for filtering/logging.
+NormalizedEventKind: TypeAlias = Literal[
+    "text", "thinking", "tool_call", "resume", "finish", "failed"
+]
+
+#: Every :data:`NormalizedEventKind` value, as a frozen tuple. The sink's
+#: dispatch table and the kind-coverage test both pin against this (the
+#: Python replacement for the TS mapped-type exhaustiveness).
+NORMALIZED_EVENT_KINDS: Final[tuple[NormalizedEventKind, ...]] = (
+    "text",
+    "thinking",
+    "tool_call",
+    "resume",
+    "finish",
+    "failed",
+)
+
+
+# ---------------------------------------------------------------------------
+# Bridge event sink
+# ---------------------------------------------------------------------------
+
+
+class BridgeEventSink(Protocol):
+    """The single push-stream helper every bridge writes through (TS
+    ``BridgeEventSink``).
+
+    It owns the accumulating ``AssistantMessage``, the content-block index
+    bookkeeping, and the lazily-started lifecycle (the first emission opens
+    the stream). A bridge never touches ``AssistantMessageEventStream``
+    directly; it constructs a sink, drives it with normalized events, and
+    returns the sink's :attr:`stream`. This centralizes the
+    ``start → push* → finish_success/finish_error`` idiom so the per-bridge
+    code is purely a parser. The convenience methods cover the common path;
+    :meth:`emit` accepts a raw :data:`NormalizedEvent` for parsers that
+    prefer to yield the union directly.
+    """
+
+    def start(self) -> None:
+        """Open the underlying stream and push the framework ``start`` event,
+        if it has not already started. Idempotent: safe to call before any
+        emission, and a no-op once started. The convenience emitters call it
+        implicitly."""
+        ...
+
+    def text(self, delta: str) -> None:
+        """Append a chunk of assistant answer text (opens a text block on
+        first call)."""
+        ...
+
+    def thinking(self, delta: str) -> None:
+        """Append a chunk of reasoning text (opens a thinking block on first
+        call)."""
+        ...
+
+    def tool_call(self, call: ToolCall) -> None:
+        """Emit a fully-formed tool call as its own content block."""
+        ...
+
+    def emit(self, event: NormalizedEvent) -> None:
+        """Map one :data:`NormalizedEvent` onto the matching push call. The
+        single entry point a parser can drive with the raw union; dispatches
+        to :meth:`text` / :meth:`thinking` / :meth:`tool_call` /
+        :meth:`finish_success` / :meth:`finish_error` by ``kind``. A
+        ``resume`` event is informational and does not touch the stream."""
+        ...
+
+    def finish_success(self, reason: FinishReason = "stop") -> None:
+        """Settle the exchange successfully: close any open block, finalize
+        the accumulated message, and push the framework ``done`` event with
+        ``reason``. Terminal — no further emissions are valid after this.
+
+        :param reason: the terminal stop reason (defaults to ``"stop"``)
+        """
+        ...
+
+    def finish_error(self, error: BridgeFailure) -> None:
+        """Settle the exchange in error: push the framework ``error`` event.
+        The :attr:`BridgeFailure.aborted` flag selects the framework error
+        reason (``aborted`` vs ``error``). Terminal.
+
+        :param error: the typed bridge failure
+        """
+        ...
+
+    @property
+    def stream(self) -> AssistantMessageEventStream:
+        """The framework push stream the broker hands back to its caller.
+        Populated asynchronously as the bridge drives the sink; consumers
+        iterate it exactly as they would the stream ``stream_simple``
+        returns."""
+        ...
+
+
+# ---------------------------------------------------------------------------
+# Injectable child transport
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class ChildMessage:
+    """A single message exchanged with the child runtime over its
+    :class:`ChildTransport` (TS ``ChildMessage``).
+
+    The ``payload`` is deliberately opaque: it is whatever the underlying
+    protocol carries — a parsed JSON line from a CLI's NDJSON stdout, a
+    JSON-RPC notification from a peer agent, a raw text chunk. The bridge
+    that owns the transport knows how to interpret it; the contract only
+    fixes the envelope so the transport interface itself is dialect-agnostic
+    and mockable.
+    """
+
+    #: The protocol payload (a parsed JSON value, a text line, an RPC frame).
+    payload: Any
+
+
+@dataclass(frozen=True, slots=True)
+class ChildRequest:
+    """A request sent *to* the child runtime (TS ``ChildRequest``). The
+    bridge formats the dialect-specific body; the transport only relays it.
+    ``body`` is opaque for the same reason :attr:`ChildMessage.payload` is."""
+
+    #: The dialect-specific request body the bridge constructed.
+    body: Any
+
+
+class ChildTransport(Protocol):
+    """The injectable boundary between a bridge and the actual child process
+    / RPC peer it drives (TS ``ChildTransport``).
+
+    A production transport wraps a spawned process (its stdin/stdout, or a
+    JSON-RPC client over that process); a test transport is a hand-written
+    fake that records ``send``\\ s and replays canned :class:`ChildMessage`\\ s
+    — so a bridge's parser can be exercised with **no real binary launched**.
+    The bridge depends only on this interface, never on a subprocess module
+    directly.
+    """
+
+    def send(self, request: ChildRequest) -> Awaitable[None]:
+        """Relay one :class:`ChildRequest` to the child (e.g. write a prompt
+        to stdin or issue a JSON-RPC call). Resolves once the request has
+        been handed off.
+
+        :param request: the dialect-specific request to deliver
+        """
+        ...
+
+    def on_message(self, listener: Callable[[ChildMessage], None]) -> Callable[[], None]:
+        """Register a listener for inbound :class:`ChildMessage`\\ s from the
+        child (stdout lines, RPC notifications). Returns an unsubscribe
+        function.
+
+        :param listener: invoked for each inbound message
+        :returns: a disposer that removes the listener
+        """
+        ...
+
+    def close(self) -> Awaitable[None]:
+        """Terminate the child and release the transport. Idempotent; safe to
+        call on an already-closed transport. After ``close``, ``send``
+        rejects and no further messages are delivered."""
+        ...
+
+
+# ---------------------------------------------------------------------------
+# Runtime exchange options
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ExchangeOptions(SimpleStreamOptions):
+    """Per-exchange options threaded into :meth:`RuntimeBridge.run_exchange`
+    (and the framework ``stream_simple`` fallback the broker also drives)
+    (TS ``ExchangeOptions``).
+
+    Extends the framework's :class:`~indusagi.ai.SimpleStreamOptions` (so
+    ``signal``, ``apiKey``, ``reasoning``, ``sessionId``, etc. flow straight
+    through to the network path) with the routing-layer extras a bridge
+    needs:
+
+    - ``sessionId`` (inherited) correlates the exchange with a persisted
+      runtime session so the bridge can resume the underlying CLI session.
+    - ``cwd`` is the working directory the child runtime is scoped to
+      (defaults to the process cwd).
+    - ``resume`` carries a previously-persisted token (e.g. a CLI session id
+      / thread id) the bridge reattaches to instead of starting fresh.
+    """
+
+    #: Working directory the child runtime is scoped to.
+    cwd: str | None = field(default=None, kw_only=True)
+    #: A resume token from a prior exchange to reattach the underlying session.
+    resume: str | None = field(default=None, kw_only=True)
+
+
+# ---------------------------------------------------------------------------
+# Runtime bridge
+# ---------------------------------------------------------------------------
+
+
+class RuntimeBridge(Protocol):
+    """One external-runtime adapter: the strategy that produces a turn for a
+    model whose :class:`ExternalRuntimeSpec` names it (TS ``RuntimeBridge``).
+
+    A bridge is the dialect specialist. Given the bound model, the framework
+    context, per-exchange :class:`ExchangeOptions`, and an **injected**
+    :class:`ChildTransport`, it drives the child and returns the framework
+    push stream the turn streams into. The transport is a parameter (not
+    constructed internally) precisely so tests pass a fake and no real CLI
+    is spawned. Bridges hold no per-session state on the contract surface;
+    live session handles and reuse/persistence are the
+    :class:`RuntimeBroker`'s concern.
+    """
+
+    @property
+    def adapter(self) -> RuntimeAdapterId:
+        """The adapter id this bridge answers to (matched against
+        :attr:`ExternalRuntimeSpec.adapter`)."""
+        ...
+
+    def run_exchange(
+        self,
+        model: Model,
+        context: Context,
+        opts: ExchangeOptions,
+        transport: ChildTransport,
+    ) -> AssistantMessageEventStream:
+        """Drive one exchange against the external runtime and return the
+        framework push stream it streams into. Returns the stream
+        **synchronously** (the stream is populated asynchronously as the
+        child emits), matching the shape of the framework's own
+        ``stream_simple``. The implementation reads inbound
+        :class:`ChildMessage`\\ s off ``transport``, parses them into
+        :data:`NormalizedEvent`\\ s, and feeds a :class:`BridgeEventSink`.
+
+        :param model: the bound framework model for this exchange
+        :param context: the framework conversation context
+        :param opts: per-exchange options (session id, cwd, resume, stream opts)
+        :param transport: the injected child boundary to drive
+        """
+        ...
+
+    def requires_credential(self, spec: ExternalRuntimeSpec) -> bool:
+        """Whether a model bound to this bridge needs a credential on disk
+        before it can be offered. Returns ``False`` for an ``"external-cli"``
+        spec whose child owns its own auth (so the model is available with an
+        empty vault), ``True`` for an ``"api-key"`` spec. The central
+        auth-routing predicate.
+
+        :param spec: the external-runtime annotation to evaluate
+        """
+        ...
+
+
+# ---------------------------------------------------------------------------
+# Runtime broker
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class ExternalRoute:
+    """An external runtime owns the exchange: carries the chosen
+    :class:`RuntimeBridge` and the resolved :class:`ExternalRuntimeSpec` the
+    broker will drive ``run_exchange`` with."""
+
+    target: ClassVar[Literal["external"]] = "external"
+    bridge: RuntimeBridge
+    spec: ExternalRuntimeSpec
+
+
+@dataclass(frozen=True, slots=True)
+class FrameworkRoute:
+    """The turn falls through to the framework network stream
+    (``stream_simple``) unchanged."""
+
+    target: ClassVar[Literal["framework"]] = "framework"
+
+
+#: The outcome of a routing decision (TS ``RuntimeRoute``).
+RuntimeRoute: TypeAlias = ExternalRoute | FrameworkRoute
+
+
+class RuntimeBroker(Protocol):
+    """The router and registry over :class:`RuntimeBridge`\\ s — the single
+    decision point for "external runtime vs framework stream" (TS
+    ``RuntimeBroker``).
+
+    The broker is asked to :meth:`route` every turn. If the model carries an
+    :class:`ExternalRuntimeSpec` whose adapter resolves to a registered
+    bridge, the broker returns an ``"external"`` route the caller drives via
+    the bridge's ``run_exchange``; otherwise it returns a ``"framework"``
+    route and the caller runs ``stream_simple``. Bridges are
+    :meth:`register`\\ ed at assembly time and looked up by adapter id.
+    """
+
+    def register(self, bridge: RuntimeBridge) -> None:
+        """Add a :class:`RuntimeBridge` to the registry, keyed by its
+        :attr:`RuntimeBridge.adapter`. Registering an adapter id that already
+        exists replaces the prior bridge.
+
+        :param bridge: the bridge to register
+        """
+        ...
+
+    def route(self, model: Model, context: Context, opts: ExchangeOptions) -> RuntimeRoute:
+        """Decide how to produce a turn for ``model``. Resolves the model's
+        :class:`ExternalRuntimeSpec` (via :meth:`resolve_spec`) and a matching
+        registered bridge; returns an ``"external"`` route when both are
+        present, else a ``"framework"`` route. The framework
+        ``context``/``opts`` are accepted so an implementation may factor
+        them into routing, even though the base decision keys on the model.
+
+        :param model: the model the turn is bound to
+        :param context: the framework conversation context for the turn
+        :param opts: per-exchange options
+        """
+        ...
+
+    def resolve_spec(self, model: Model) -> ExternalRuntimeSpec | None:
+        """Resolve the :class:`ExternalRuntimeSpec` annotated onto a model,
+        or ``None`` when the model is a plain HTTP-provider model. How the
+        spec is attached (a side-table keyed by canonical id, a field on a
+        catalog card, a ``bridge:<adapter>`` baseUrl decode) is the
+        implementation's choice; the contract only fixes the lookup.
+
+        :param model: the model to inspect for a runtime annotation
+        """
+        ...
+
+    def requires_credential(self, spec: ExternalRuntimeSpec) -> bool:
+        """Whether a runtime-annotated model needs a credential on disk
+        before it can be offered as available. Delegates to the owning
+        bridge's :meth:`RuntimeBridge.requires_credential`; falls back to the
+        spec's own ``authMode`` when no bridge is registered — so this
+        answers strictly the *runtime* credential question.
+
+        :param spec: the runtime annotation to evaluate
+        """
+        ...
+
+
+# ---------------------------------------------------------------------------
+# Resume-token persistence (type half of TS broker.ts)
+# ---------------------------------------------------------------------------
+
+#: The custom transcript-entry tag under which a runtime resume token is
+#: logged. The record this build writes is its own ``"external-runtime-link"``
+#: shape so the persisted log carries no inherited vocabulary. A consumer
+#: scanning the active branch backwards for a reattachable session matches on
+#: this tag.
+RUNTIME_LINK_ENTRY: Final = "external-runtime-link"
+
+#: The literal type of :data:`RUNTIME_LINK_ENTRY`.
+RuntimeLinkEntryTag: TypeAlias = Literal["external-runtime-link"]
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeLink:
+    """The serializable payload persisted under :data:`RUNTIME_LINK_ENTRY`
+    (TS ``RuntimeLink``).
+
+    The renamed shape: ``{source, bridge, resumeToken, at}``. ``source`` is
+    the model's provider slug, ``bridge`` is the owning
+    :attr:`RuntimeBridge.adapter`, ``resumeToken`` is the reattachable CLI
+    session id / thread id the child reported, and ``at`` is the ISO instant
+    it was captured. Reuse keys on
+    :func:`~induscode.runtime_bridge.broker.runtime_source_key`, derived from
+    ``source`` + model id + ``bridge``.
+    """
+
+    #: The model's provider slug (its ``source``).
+    source: str
+    #: The owning bridge adapter id.
+    bridge: str
+    #: The reattachable session id / thread id reported by the child runtime.
+    resumeToken: str
+    #: ISO-8601 instant the token was captured.
+    at: str
+
+
+class RuntimeLinkStore(Protocol):
+    """Injectable persistence boundary for resume tokens (TS
+    ``RuntimeLinkStore``). The conductor's transcript store binds a real
+    implementation (appending a :data:`RUNTIME_LINK_ENTRY` custom entry to
+    the active branch and scanning it backwards on lookup); tests pass an
+    in-memory fake. Both methods *may* be async to match a disk-backed
+    transcript — but see the sync-fast-path note on
+    :meth:`~induscode.runtime_bridge.broker._Broker.exchange`."""
+
+    def save(self, link: RuntimeLink) -> Awaitable[None] | None:
+        """Persist a captured resume token as a renamed custom transcript
+        entry. Called once per ``resume`` event a bridge surfaces during an
+        exchange.
+
+        :param link: the renamed link record to append
+        """
+        ...
+
+    def find(self, source_key: str) -> Awaitable[str | None] | str | None:
+        """Resolve the most recent reattachable token for a reuse key, or
+        ``None`` when the active branch holds no matching
+        :data:`RUNTIME_LINK_ENTRY`. The key is
+        :func:`~induscode.runtime_bridge.broker.runtime_source_key`.
+
+        :param source_key: the composite ``source|model|bridge`` reuse key
+        """
+        ...
+
+
+# ---------------------------------------------------------------------------
+# Transport factory (type half of TS broker.ts)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class TransportContext:
+    """The context handed to a :data:`ChildTransportFactory` when the broker
+    needs a transport for an external exchange (TS ``TransportContext``).
+    Carries everything a production factory needs to launch + wire the child
+    (the resolved spec's binary/args/env, the working directory, a resume
+    token to reattach) without the broker itself touching a subprocess
+    module."""
+
+    #: The resolved runtime spec (binary, args, env, delegate) for the child.
+    spec: ExternalRuntimeSpec
+    #: The bound model the exchange runs for.
+    model: Model
+    #: The per-exchange options (session id, cwd, resume, stream opts).
+    opts: ExchangeOptions
+    #: A persisted resume token resolved for this exchange, if any.
+    resume: str | None = None
+
+
+#: Mints a :class:`ChildTransport` for an external exchange (TS
+#: ``ChildTransportFactory``). The single seam the broker reaches the outside
+#: world through: a production factory spawns the process and adapts its
+#: stdio/RPC into the transport; a test factory returns a scripted fake. The
+#: broker calls it lazily, only on an external route.
+ChildTransportFactory: TypeAlias = Callable[[TransportContext], ChildTransport]
+
+#: The framework network-stream signature the broker falls through to (TS
+#: ``FrameworkStream``).
+FrameworkStream: TypeAlias = Callable[
+    [Model, Context, ExchangeOptions], AssistantMessageEventStream
+]