induscode 0.1.0__py3-none-any.whl

induscode/conductor/contract.py

@@ -0,0 +1,1035 @@
+"""Conductor contract — the FROZEN type surface of the agent runtime core.
+
+This module is the single typed seam between the coding-agent *product* (the
+UI/channels that drive a session) and the framework ``Agent`` (the raw LLM
+conversation loop, published by :mod:`indusagi.agent`). It declares *only*
+shapes plus two tiny inert helpers (:func:`conductor_fault` and the pure
+:func:`reduce_state` transition) — no I/O, no orchestration. Every later
+conductor module (the signal hub, the transcript store, the model
+catalog/matcher, the conductor factory, and the :class:`SessionConductor`
+itself) is written against the names declared here, so the file is
+intentionally small, append-mostly, and stable.
+
+Design stance (ported from TS ``src/conductor/contract.ts``):
+
+- The conductor *wraps* the framework ``Agent``. The framework emits a
+  fine-grained ``AgentEvent`` stream for its own loop; the conductor consumes
+  that internally and **re-emits a distinct, product-level**
+  :data:`SessionSignal` **stream** to consumers. The two are deliberately not
+  the same union: ``SessionSignal`` is the stable surface the app renders,
+  free to evolve independently of the framework's loop events.
+- Faults are **typed discriminated values** (:class:`ConductorFault`), never
+  string sentinels. A consumer switches on ``fault.kind``, not on substring
+  matching of a message.
+- Persistence uses a **fresh on-disk vocabulary** (:class:`TranscriptEntry`,
+  :class:`SessionHead`, :data:`TRANSCRIPT_SCHEMA`). The node is a
+  ``parent``-linked tree, the version is a namespaced string, and the field
+  names are the conductor's own — not the framework's session-manager schema.
+- State is exposed as an **immutable snapshot** (:class:`ConductorState`);
+  consumers read it, they never mutate it. Every transition runs through the
+  pure :func:`reduce_state` reducer, which always returns a brand-new object.
+
+Port notes
+----------
+- TS discriminated unions become frozen ``slots`` dataclasses carrying a
+  ``ClassVar`` ``Literal`` tag (``kind`` for signals/faults, ``type`` for
+  reducer actions) — the same tag spelling as TS, so a ``match`` on the tag
+  reads like the TS ``switch``. Exhaustiveness moved compiler → test (see
+  the key-coverage tests in ``tests/conductor``).
+- Field names keep the TS camelCase spelling (``contextTokens``,
+  ``createdAt``, ``entryId``, ``modelId`` …) — matching the framework's own
+  camelCase dataclasses so the two vocabularies read alike. Functions are
+  snake_case.
+- TS ``SignalOf<K>`` (type-level Extract) has no Python analogue; the
+  runtime equivalent is an ``isinstance`` check against the variant class,
+  and :data:`SIGNAL_KINDS` names the closed kind set for guards/tests.
+- ``reduce_state`` and the ``AgentLike`` / ``CondenseFn`` / ``RetryPolicy``
+  seams live in TS ``conductor.ts``; they are *types-and-pure-logic*, so the
+  Python port hosts them here in the contract — the wave-2 ``conductor.py``
+  (turn loop, queue drain, retry, persist tail) imports them from this
+  module.
+
+Framework anchors (all from the ``indusagi`` package — the sibling rebuilt
+framework this app targets):
+
+- ``AgentEvent``, ``AgentTool``, ``ThinkingLevel`` ← ``indusagi.agent``
+- ``AgentMessage``, ``Model``, ``Usage``, ``KnownProvider`` ← ``indusagi.ai``
+  (note: ``AgentMessage`` lives in ``indusagi.ai`` in the Python framework,
+  not ``indusagi.agent`` as in TS)
+
+The conductor never re-declares these; it composes them.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Mapping, Sequence
+from dataclasses import dataclass, replace
+from typing import Any, ClassVar, Final, Literal, Protocol, TypeAlias
+
+from indusagi.agent import AgentEvent, AgentTool, ThinkingLevel
+from indusagi.ai import AgentMessage, KnownProvider, Model, Usage
+
+__all__ = [
+    "AgentLike",
+    "AgentMessage",
+    "AgentStateLike",
+    "AgentTool",
+    "BashOutcome",
+    "CompactedSignal",
+    "CondenseFn",
+    "ConductorFault",
+    "ConductorPhase",
+    "ConductorState",
+    "ExecuteBashOptions",
+    "FAULT_KINDS",
+    "FaultAction",
+    "FaultKind",
+    "FaultSignal",
+    "HeadAction",
+    "IdleSignal",
+    "KnownProvider",
+    "MatchQuery",
+    "Model",
+    "ModelAction",
+    "ModelCardRef",
+    "PersistedSignal",
+    "PhaseAction",
+    "PromptSignal",
+    "QUEUE_MODES",
+    "QueueMode",
+    "QueueSignal",
+    "QueuedInput",
+    "RetryPolicy",
+    "SIGNAL_KINDS",
+    "SessionConductor",
+    "SessionConductorOptions",
+    "SessionHead",
+    "SessionSignal",
+    "SessionStats",
+    "SettledAction",
+    "SignalHandler",
+    "SignalKind",
+    "StateAction",
+    "TRANSCRIPT_ROLES",
+    "TRANSCRIPT_SCHEMA",
+    "TextSignal",
+    "ThinkingLevel",
+    "ThinkingSignal",
+    "TokenTally",
+    "ToolEndSignal",
+    "ToolStartSignal",
+    "TranscriptEntry",
+    "TranscriptRole",
+    "TranscriptSchema",
+    "TurnEndSignal",
+    "Usage",
+    "UsageAction",
+    "conductor_fault",
+    "reduce_state",
+]
+
+
+# ---------------------------------------------------------------------------
+# Faults
+# ---------------------------------------------------------------------------
+
+#: The closed set of failure categories the conductor can surface.
+#:
+#: Each is a distinct recovery story, so the kind is a discriminant — not a
+#: free-form string:
+#:
+#: - ``model``       — the LLM call itself failed (transport, provider, decode).
+#: - ``tool``        — a tool invocation threw or returned a hard error.
+#: - ``persistence`` — writing/reading the on-disk transcript failed.
+#: - ``aborted``     — the caller cancelled the in-flight turn via abort.
+#: - ``overflow``    — the context window was exceeded and not condensable.
+FaultKind: TypeAlias = Literal["model", "tool", "persistence", "aborted", "overflow"]
+
+#: Every :data:`FaultKind` value, as a frozen tuple for guards and tests.
+FAULT_KINDS: Final[tuple[FaultKind, ...]] = (
+    "model",
+    "tool",
+    "persistence",
+    "aborted",
+    "overflow",
+)
+
+
+@dataclass(frozen=True, slots=True)
+class ConductorFault:
+    """A typed, discriminated failure value emitted on the
+    :data:`SessionSignal` stream and attached to faulted states.
+
+    ``kind`` selects the category; ``message`` is a human-readable summary;
+    the optional ``cause`` carries the underlying error (or any structured
+    detail) for logging without forcing consumers to parse the message
+    string. It is a *value*, never raised — construct one with
+    :func:`conductor_fault`.
+    """
+
+    #: Failure category — the discriminant consumers switch on.
+    kind: FaultKind
+    #: Human-readable, single-line summary of what went wrong.
+    message: str
+    #: Underlying error or structured detail, if any (TS optional ``cause``).
+    cause: object | None = None
+
+
+def conductor_fault(
+    kind: FaultKind, message: str, cause: object | None = None
+) -> ConductorFault:
+    """Construct a :class:`ConductorFault`. The single sanctioned way to mint
+    a fault, so the shape stays uniform across every producer.
+
+    :param kind: the failure category
+    :param message: a human-readable, single-line summary
+    :param cause: optional underlying error or structured detail
+    """
+    return ConductorFault(kind=kind, message=message, cause=cause)
+
+
+# ---------------------------------------------------------------------------
+# Product-level signal stream
+# ---------------------------------------------------------------------------
+#
+# The product-level event stream the conductor emits to its consumers (the
+# interactive UI, the print/JSON mode, the JSON-RPC link). This is the
+# conductor's **re-emitted surface** — distinct from the framework
+# ``AgentEvent`` union. The conductor subscribes to the raw framework loop,
+# layers persistence / auto-condense / fault handling on top, and projects the
+# result down to this small, stable set of discriminated signals. Consumers
+# switch on ``kind`` and never see a framework loop event directly.
+
+
+@dataclass(frozen=True, slots=True)
+class PromptSignal:
+    """The user's turn was committed to the conversation; ``text`` is the
+    submitted prompt. Emitted the instant the turn is accepted (before the
+    model replies) so a UI can echo the user message immediately rather than
+    waiting for the first assistant token."""
+
+    kind: ClassVar[Literal["prompt"]] = "prompt"
+    text: str
+
+
+@dataclass(frozen=True, slots=True)
+class TextSignal:
+    """A chunk of assistant answer text streamed in."""
+
+    kind: ClassVar[Literal["text"]] = "text"
+    delta: str
+
+
+@dataclass(frozen=True, slots=True)
+class ThinkingSignal:
+    """A chunk of reasoning/thinking text streamed in."""
+
+    kind: ClassVar[Literal["thinking"]] = "thinking"
+    delta: str
+
+
+@dataclass(frozen=True, slots=True)
+class ToolStartSignal:
+    """A tool invocation began (correlate by ``id``)."""
+
+    kind: ClassVar[Literal["tool_start"]] = "tool_start"
+    id: str
+    name: str
+
+
+@dataclass(frozen=True, slots=True)
+class ToolEndSignal:
+    """A tool invocation finished (``ok`` = no error)."""
+
+    kind: ClassVar[Literal["tool_end"]] = "tool_end"
+    id: str
+    ok: bool
+
+
+@dataclass(frozen=True, slots=True)
+class TurnEndSignal:
+    """The assistant turn settled; ``usage`` reports token spend."""
+
+    kind: ClassVar[Literal["turn_end"]] = "turn_end"
+    usage: Usage
+
+
+@dataclass(frozen=True, slots=True)
+class PersistedSignal:
+    """The latest node was committed to the transcript (``entryId``)."""
+
+    kind: ClassVar[Literal["persisted"]] = "persisted"
+    entryId: str
+
+
+@dataclass(frozen=True, slots=True)
+class CompactedSignal:
+    """The transcript was condensed to fit the context window."""
+
+    kind: ClassVar[Literal["compacted"]] = "compacted"
+
+
+@dataclass(frozen=True, slots=True)
+class FaultSignal:
+    """A typed :class:`ConductorFault` occurred."""
+
+    kind: ClassVar[Literal["fault"]] = "fault"
+    fault: ConductorFault
+
+
+@dataclass(frozen=True, slots=True)
+class QueueSignal:
+    """The pending-input queue changed; ``count`` is its new depth."""
+
+    kind: ClassVar[Literal["queue"]] = "queue"
+    count: int
+
+
+@dataclass(frozen=True, slots=True)
+class IdleSignal:
+    """The conductor has no in-flight work and is ready for input."""
+
+    kind: ClassVar[Literal["idle"]] = "idle"
+
+
+#: The product-level signal union — the conductor's stable consumer surface.
+SessionSignal: TypeAlias = (
+    PromptSignal
+    | TextSignal
+    | ThinkingSignal
+    | ToolStartSignal
+    | ToolEndSignal
+    | TurnEndSignal
+    | PersistedSignal
+    | CompactedSignal
+    | FaultSignal
+    | QueueSignal
+    | IdleSignal
+)
+
+#: The discriminant literals of :data:`SessionSignal`, for filtering/logging.
+SignalKind: TypeAlias = Literal[
+    "prompt",
+    "text",
+    "thinking",
+    "tool_start",
+    "tool_end",
+    "turn_end",
+    "persisted",
+    "compacted",
+    "fault",
+    "queue",
+    "idle",
+]
+
+#: Every :data:`SignalKind` value, in declaration order (the runtime stand-in
+#: for TS ``SignalOf`` extraction — pair with an ``isinstance`` check).
+SIGNAL_KINDS: Final[tuple[SignalKind, ...]] = (
+    "prompt",
+    "text",
+    "thinking",
+    "tool_start",
+    "tool_end",
+    "turn_end",
+    "persisted",
+    "compacted",
+    "fault",
+    "queue",
+    "idle",
+)
+
+#: A subscriber callback registered with :meth:`SessionConductor.subscribe`.
+SignalHandler: TypeAlias = Callable[[SessionSignal], None]
+
+
+# ---------------------------------------------------------------------------
+# On-disk transcript schema
+# ---------------------------------------------------------------------------
+
+#: The on-disk transcript schema namespace + version.
+#:
+#: A namespaced string (not a bare integer) so the format is self-describing
+#: and can evolve without colliding with any other versioned artifact in the
+#: app. This is deliberately the conductor's own vocabulary.
+TRANSCRIPT_SCHEMA: Final[str] = "indus/transcript@1"
+
+#: The literal type of :data:`TRANSCRIPT_SCHEMA`.
+TranscriptSchema: TypeAlias = Literal["indus/transcript@1"]
+
+#: The conversational role a :class:`TranscriptEntry` node carries.
+#:
+#: Spans both the LLM-facing turns (``user``/``assistant``/``tool``) and the
+#: conductor's own bookkeeping nodes (``system`` seed, ``condense`` markers,
+#: and ``note`` for app-injected context). Kept open at the product layer so
+#: the transcript can hold more than the framework's message roles.
+TranscriptRole: TypeAlias = Literal["user", "assistant", "tool", "system", "condense", "note"]
+
+#: Every :data:`TranscriptRole` value, as a frozen tuple for guards and tests.
+TRANSCRIPT_ROLES: Final[tuple[TranscriptRole, ...]] = (
+    "user",
+    "assistant",
+    "tool",
+    "system",
+    "condense",
+    "note",
+)
+
+
+@dataclass(frozen=True, slots=True)
+class TranscriptEntry:
+    """A single node in the on-disk transcript tree.
+
+    The transcript is an append-only **tree**: every node names its
+    ``parent`` (a root has ``parent = None``), and the active leaf is tracked
+    separately in :class:`SessionHead`. Branching is moving the head to an
+    earlier node; the next append becomes that node's child. ``content``
+    holds the framework ``AgentMessage`` payload so the node round-trips back
+    into the agent loop; ``meta`` carries optional, non-LLM annotations
+    (labels, condense bookkeeping, model/reasoning markers).
+
+    Field names are the conductor's own (``parent``, ``createdAt``, ``meta``)
+    — not the framework's persistence schema.
+    """
+
+    #: Stable unique node id (e.g. a ULID).
+    id: str
+    #: Parent node id, or ``None`` for the transcript root.
+    parent: str | None
+    #: Conversational role of this node.
+    role: TranscriptRole
+    #: The framework message payload this node persists.
+    content: AgentMessage
+    #: ISO-8601 creation timestamp.
+    createdAt: str
+    #: Optional, non-LLM annotations keyed by name.
+    meta: Mapping[str, Any] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class SessionHead:
+    """The head record of a persisted transcript: which session, and where
+    its active leaf currently points.
+
+    The ``leaf`` is the id of the most recently appended (or branched-to)
+    node; walking ``parent`` links from ``leaf`` to a root reconstructs the
+    active branch. ``None`` means an empty transcript (no nodes yet).
+    """
+
+    #: Stable identifier of the session this transcript belongs to.
+    sessionId: str
+    #: Id of the active leaf node, or ``None`` for an empty transcript.
+    leaf: str | None
+
+
+# ---------------------------------------------------------------------------
+# Model catalog / matcher
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class ModelCardRef:
+    """A lightweight, resolved reference to one model card in the catalog.
+
+    This is the *display/identity* projection of a framework ``Model`` — the
+    minimum a UI needs to list, label, and select a model without holding the
+    full model object. The matcher produces these; the conductor resolves the
+    chosen one back to a full ``Model`` when it configures the agent.
+    """
+
+    #: Canonical ``"provider/modelId"`` identifier (the catalog key).
+    id: str
+    #: Owning provider (a :data:`KnownProvider` or any provider string).
+    provider: str
+    #: Provider-scoped model id (e.g. ``"claude-sonnet-4"``).
+    modelId: str
+    #: Human-readable display name.
+    name: str
+    #: Whether this model exposes a reasoning/thinking budget.
+    reasoning: bool
+
+
+@dataclass(frozen=True, slots=True)
+class MatchQuery:
+    """A query against the model catalog/matcher.
+
+    Resolution is a prioritized candidate pipeline: an explicit
+    ``provider`` + ``modelId`` pins a single card; otherwise ``pattern`` is
+    matched (exact id, ``provider/`` prefix, then glob/fuzzy) and narrowed by
+    the optional capability filters. All fields default to ``None`` so an
+    empty query means "the default candidate".
+    """
+
+    #: Free-form selector: an id, an alias, or a glob pattern.
+    pattern: str | None = None
+    #: Restrict candidates to this provider.
+    provider: str | None = None
+    #: Pin a specific provider-scoped model id (used with ``provider``).
+    modelId: str | None = None
+    #: Require reasoning/thinking support.
+    reasoning: bool | None = None
+    #: Require image input support.
+    supportsImageInput: bool | None = None
+
+
+# ---------------------------------------------------------------------------
+# Conductor lifecycle phase & state
+# ---------------------------------------------------------------------------
+
+#: The coarse lifecycle phase of the conductor at a point in time.
+#:
+#: - ``idle``       — assembled and ready; no turn in flight.
+#: - ``streaming``  — an assistant turn is producing text/thinking.
+#: - ``tooling``    — a tool invocation is executing mid-turn.
+#: - ``condensing`` — the transcript is being condensed to fit the window.
+#: - ``faulted``    — the last turn ended in a :class:`ConductorFault`.
+ConductorPhase: TypeAlias = Literal["idle", "streaming", "tooling", "condensing", "faulted"]
+
+
+@dataclass(frozen=True, slots=True)
+class ConductorState:
+    """An immutable snapshot of the conductor's observable state.
+
+    Returned by :meth:`SessionConductor.snapshot` and resolved by
+    :meth:`SessionConductor.submit`. It is a value, not a live view: the
+    dataclass is frozen and the object reflects the instant it was taken.
+    Re-read with a fresh ``snapshot()`` to observe later changes.
+    """
+
+    #: Coarse lifecycle phase at snapshot time.
+    phase: ConductorPhase
+    #: The active transcript head (session id + current leaf).
+    head: SessionHead
+    #: Cumulative token/cost spend across the session so far.
+    usage: Usage
+    #: Tokens occupying the model's context window as of the most recent turn
+    #: — the last assistant turn's reported usage, NOT the cumulative session
+    #: spend. This is what the footer's ``ctx:%`` divides by the context
+    #: window; ``usage.totalTokens`` grows unbounded across turns and would
+    #: inflate it.
+    contextTokens: int
+    #: Canonical id of the model currently bound to the session.
+    modelId: str
+    #: The fault from the most recent turn, when ``phase`` is ``"faulted"``.
+    fault: ConductorFault | None = None
+
+
+# ---------------------------------------------------------------------------
+# Immutable state reducer
+# ---------------------------------------------------------------------------
+#
+# The transitions the reducer understands — fresh vocabulary, all typed.
+# (TS hosts these in conductor.ts; they are pure shapes + a pure function, so
+# the Python port keeps them on the contract for the wave-2 conductor to
+# import.)
+
+
+@dataclass(frozen=True, slots=True)
+class PhaseAction:
+    """Move to a new lifecycle phase."""
+
+    type: ClassVar[Literal["phase"]] = "phase"
+    phase: ConductorPhase
+
+
+@dataclass(frozen=True, slots=True)
+class HeadAction:
+    """Point the state at a new transcript head."""
+
+    type: ClassVar[Literal["head"]] = "head"
+    head: SessionHead
+
+
+@dataclass(frozen=True, slots=True)
+class UsageAction:
+    """Record the cumulative usage *and* the latest turn's context occupancy.
+
+    ``usage`` is the running cumulative total (grows unbounded across turns);
+    ``contextTokens`` is the latest turn's window occupancy and **replaces**
+    the prior value rather than accumulating — the ``ctx:%`` fix.
+    """
+
+    type: ClassVar[Literal["usage"]] = "usage"
+    usage: Usage
+    contextTokens: int
+
+
+@dataclass(frozen=True, slots=True)
+class ModelAction:
+    """Bind a different canonical model id."""
+
+    type: ClassVar[Literal["model"]] = "model"
+    modelId: str
+
+
+@dataclass(frozen=True, slots=True)
+class FaultAction:
+    """Record a fault and flip the phase to ``faulted``."""
+
+    type: ClassVar[Literal["fault"]] = "fault"
+    fault: ConductorFault
+
+
+@dataclass(frozen=True, slots=True)
+class SettledAction:
+    """Turn ended cleanly: clear any prior fault, go idle."""
+
+    type: ClassVar[Literal["settled"]] = "settled"
+
+
+#: The reducer's action union.
+StateAction: TypeAlias = (
+    PhaseAction | HeadAction | UsageAction | ModelAction | FaultAction | SettledAction
+)
+
+
+def reduce_state(prev: ConductorState, action: StateAction) -> ConductorState:
+    """Pure transition over :class:`ConductorState`.
+
+    Always returns a brand-new object; the previous state is never mutated.
+    ``settled`` clears a stale fault and returns to ``idle``; ``fault``
+    records the fault and flips to ``faulted``.
+
+    :param prev: the state to transition from (left untouched)
+    :param action: the typed transition to apply
+    :raises ValueError: on an action outside :data:`StateAction` (the TS
+        ``switch`` was compiler-exhaustive; the Python port fails loud)
+    """
+    tag = action.type
+    if tag == "phase":
+        return replace(prev, phase=action.phase)
+    if tag == "head":
+        return replace(prev, head=action.head)
+    if tag == "usage":
+        return replace(prev, usage=action.usage, contextTokens=action.contextTokens)
+    if tag == "model":
+        return replace(prev, modelId=action.modelId)
+    if tag == "fault":
+        return replace(prev, phase="faulted", fault=action.fault)
+    if tag == "settled":
+        return replace(prev, phase="idle", fault=None)
+    raise ValueError(f"unknown state action: {tag!r}")
+
+
+# ---------------------------------------------------------------------------
+# Pending-input queue
+# ---------------------------------------------------------------------------
+
+#: How a queued input rejoins the conversation once the active turn settles.
+#:
+#: - ``steer``    — interrupt-style input meant to redirect the agent;
+#:   drained ahead of plain follow-ups.
+#: - ``followUp`` — input that simply waits its turn after the current one.
+#:
+#: The conductor enqueues input under one of these modes when
+#: :meth:`SessionConductor.submit` is called while a turn is in flight, then
+#: drains the queue in order. (Deliberately the conductor's own vocabulary —
+#: distinct from the framework's ``indusagi.agent.QueueMode``.)
+QueueMode: TypeAlias = Literal["steer", "followUp"]
+
+#: Every :data:`QueueMode` value, as a frozen tuple for guards and tests.
+QUEUE_MODES: Final[tuple[QueueMode, ...]] = ("steer", "followUp")
+
+
+@dataclass(frozen=True, slots=True)
+class QueuedInput:
+    """One entry in the conductor's pending-input queue: the
+    :data:`QueueMode` it was filed under and the raw user ``text``. Surfaced
+    by :meth:`SessionConductor.pending_inputs` so a UI can render what is
+    waiting."""
+
+    #: How this input will rejoin the conversation when drained.
+    mode: QueueMode
+    #: The raw user message text held for a later turn.
+    text: str
+
+
+# ---------------------------------------------------------------------------
+# Session statistics
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class TokenTally:
+    """Cumulative token spend, broken out by category and totalled (the
+    anonymous ``tokens`` object on the TS ``SessionStats``)."""
+
+    input: int
+    output: int
+    cacheRead: int
+    cacheWrite: int
+    total: int
+
+
+@dataclass(frozen=True, slots=True)
+class SessionStats:
+    """A point-in-time tally of the active session: message counts by role,
+    tool activity, cumulative token spend, and total cost. Computed by
+    :meth:`SessionConductor.stats` from the live message list plus the
+    running usage carried on :class:`ConductorState`."""
+
+    #: Identifier of the session these figures describe.
+    sessionId: str
+    #: Number of user-role messages in the active branch.
+    userMessages: int
+    #: Number of assistant-role messages in the active branch.
+    assistantMessages: int
+    #: Number of tool invocations the assistant issued.
+    toolCalls: int
+    #: Number of tool-result messages produced in reply.
+    toolResults: int
+    #: Total message count across all roles.
+    totalMessages: int
+    #: Cumulative token spend, broken out by category and totalled.
+    tokens: TokenTally
+    #: Cumulative monetary cost of the session so far.
+    cost: float
+
+
+# ---------------------------------------------------------------------------
+# Bash execution
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class ExecuteBashOptions:
+    """Options for :meth:`SessionConductor.execute_bash`."""
+
+    #: When ``True``, the command's output is *not* recorded as a transcript
+    #: note, so it never re-enters the agent's context.
+    excludeFromContext: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class BashOutcome:
+    """The settled result of :meth:`SessionConductor.execute_bash`."""
+
+    #: Combined stdout + stderr of the command.
+    output: str
+    #: Process exit code (``0`` on success; non-zero, or ``1`` on a thrown
+    #: error).
+    exitCode: int
+
+
+# ---------------------------------------------------------------------------
+# Injectable agent surface
+# ---------------------------------------------------------------------------
+
+
+class AgentStateLike(Protocol):
+    """The slice of the framework ``AgentState`` the conductor reads
+    (message list, bound model, streaming flag). Field names are the
+    framework's own camelCase."""
+
+    @property
+    def messages(self) -> Sequence[AgentMessage]: ...
+
+    @property
+    def model(self) -> Any: ...
+
+    @property
+    def isStreaming(self) -> bool: ...
+
+
+class AgentLike(Protocol):
+    """The slice of the framework ``Agent`` the conductor drives.
+
+    The real ``Agent`` from :mod:`indusagi.agent` satisfies this
+    structurally; tests pass a scripted fake exposing the same
+    submit/subscribe/event surface with no network. Keeping the dependency to
+    a Protocol (not the concrete class) is what makes the conductor
+    unit-testable.
+
+    Port note: TS also declared an optional ``setThinkingLevel?``. A Python
+    Protocol cannot mark a method optional, so it is omitted here; the
+    conductor probes for ``set_thinking_level`` with ``getattr`` and, when
+    the agent lacks it, stores the level and applies it on the next model
+    bind — same behavior as TS.
+    """
+
+    def subscribe(self, fn: Callable[[AgentEvent], None]) -> Callable[[], None]:
+        """Subscribe to the raw framework event stream; returns an
+        unsubscribe thunk."""
+        ...
+
+    async def prompt(self, input: str) -> None:
+        """Run one prompt turn to settlement."""
+        ...
+
+    def abort(self) -> None:
+        """Cancel the in-flight turn, if any."""
+        ...
+
+    @property
+    def state(self) -> AgentStateLike:
+        """The agent's current state (message list, bound model, streaming
+        flag)."""
+        ...
+
+    def replace_messages(self, messages: Sequence[AgentMessage]) -> None:
+        """Replace the agent's message list (used on resume)."""
+        ...
+
+    def set_model(self, model: Any) -> None:
+        """Bind a different model for subsequent turns."""
+        ...
+
+    def set_system_prompt(self, prompt: str) -> None:
+        """Seed/replace the system prompt."""
+        ...
+
+    def set_tools(self, tools: Sequence[AgentTool]) -> None:
+        """Set the tools available to the loop."""
+        ...
+
+
+# ---------------------------------------------------------------------------
+# Condense seam + retry policy
+# ---------------------------------------------------------------------------
+
+
+class CondenseFn(Protocol):
+    """The pluggable condense hook. Given the active branch's messages, it
+    returns the (smaller) message list to replace it with — synchronously or
+    as an awaitable. The real window-budget engine
+    (:mod:`induscode.window_budget`) is *structurally* one of these; the
+    default in the wave-2 conductor is an identity no-op.
+
+    Note: the framework's own ``runtime.memory`` compactor is **never** wired
+    in here — the two compaction engines stay distinct (plan rule 6).
+    """
+
+    def __call__(
+        self, messages: Sequence[AgentMessage], force: bool = False
+    ) -> Sequence[AgentMessage] | Awaitable[Sequence[AgentMessage]]: ...
+
+
+@dataclass(frozen=True, slots=True)
+class RetryPolicy:
+    """Tuning for the transient-fault auto-retry."""
+
+    #: Maximum retry attempts after the first try (default 2 at assembly).
+    maxAttempts: int
+    #: Base backoff in ms; doubled per attempt (default 250 at assembly).
+    baseDelayMs: int
+
+
+# ---------------------------------------------------------------------------
+# The conductor
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class SessionConductorOptions:
+    """Options that configure a :class:`SessionConductor` at assembly time.
+
+    Only ``modelId`` is required; everything else has a sensible default
+    resolved by the conductor factory. The shape is intentionally small —
+    richer wiring (MCP, memory, provider routing) is attached by the factory,
+    not passed through this surface.
+    """
+
+    #: Canonical id of the model to bind the session to.
+    modelId: str
+    #: Initial system prompt seeding the conversation.
+    system: str | None = None
+    #: Tools made available to the agent for this session.
+    tools: Sequence[AgentTool] | None = None
+    #: Initial reasoning effort for models that support it.
+    thinking: ThinkingLevel | None = None
+    #: Working directory the session is scoped to (defaults to process cwd).
+    workspace: str | None = None
+    #: Directory to persist the transcript into. When set, the conductor
+    #: backs its transcript store with a filesystem backend rooted here (one
+    #: ``<sessionId>.ndjson`` per session) so the conversation survives the
+    #: process and can be resumed. ``None`` (or an injected ``store`` dep)
+    #: keeps the default in-memory store — nothing is written to disk.
+    sessionsDir: str | None = None
+    #: Condense the transcript automatically when it nears the window
+    #: (default on; ``None`` means "factory default").
+    autoCompact: bool | None = None
+    #: Resolve the credential for a provider on each call. Threaded to the
+    #: framework ``Agent``, which calls it per request so short-lived OAuth
+    #: access tokens can be refreshed and providers with no env-var mapping
+    #: still authenticate. Returning ``None`` lets the framework fall back to
+    #: its own environment lookup. May be sync or async.
+    getApiKey: Callable[[str], Awaitable[str | None] | str | None] | None = None
+
+
+class SessionConductor(Protocol):
+    """The conductor of a single coding-agent session.
+
+    It owns the framework ``Agent``, threads persistence and auto-condense
+    through the turn loop, and exposes a small product API: submit input,
+    subscribe to the :data:`SessionSignal` stream, abort the in-flight turn,
+    read an immutable :class:`ConductorState` snapshot, resume a persisted
+    session, and optionally rotate the active model. This is the surface all
+    three run modes drive.
+
+    Port note: TS declared ``cycleModel?`` as optional; the Python Protocol
+    includes ``cycle_model`` and assemblies that do not support mid-session
+    model changes may leave it unimplemented — callers probe with ``getattr``.
+    """
+
+    async def submit(self, input: str) -> ConductorState:
+        """Submit user input as a new turn and run the agent to settle.
+
+        Streams :data:`SessionSignal` values to subscribers as the turn
+        progresses and resolves to the immutable :class:`ConductorState`
+        once the turn settles (success or fault).
+
+        When a turn is already in flight the input is **not** dropped: it is
+        handed to :meth:`enqueue` and run automatically as a later turn once
+        the current one settles. In that case ``submit`` resolves immediately
+        with the current snapshot rather than waiting for the queued turn.
+        """
+        ...
+
+    def enqueue(self, input: str, mode: QueueMode = "followUp") -> None:
+        """Queue an input to run as a future turn. Used directly, or reached
+        via :meth:`submit` when the conductor is busy. Queued items drain in
+        order after the active turn settles, each running as its own turn.
+        Emits a ``queue`` signal so a UI can reflect the new depth."""
+        ...
+
+    def pending_count(self) -> int:
+        """How many inputs are currently waiting in the pending-input
+        queue."""
+        ...
+
+    def pending_inputs(self) -> Sequence[QueuedInput]:
+        """A read-only view of the queued inputs, oldest first."""
+        ...
+
+    def clear_queue(self) -> None:
+        """Discard every queued input. Emits a ``queue`` signal."""
+        ...
+
+    def dequeue_last(self) -> str | None:
+        """Remove and return the text of the most-recently queued input, or
+        ``None`` when the queue is empty. Lets a UI pop the last entry back
+        into its prompt."""
+        ...
+
+    def messages(self) -> Sequence[AgentMessage]:
+        """The live transcript messages for the active branch.
+
+        A read-through onto the wrapped agent's running message list — what
+        the interactive UI renders as the conversation. The returned sequence
+        is the current contents at call time; re-read to observe later
+        turns."""
+        ...
+
+    def model(self) -> Model | None:
+        """The full framework ``Model`` object currently bound to the
+        session, or ``None`` when none could be resolved. Tracks the active
+        selection across :meth:`select_model` / ``cycle_model`` changes."""
+        ...
+
+    def is_busy(self) -> bool:
+        """Whether a turn is currently in flight (guards re-entrant
+        submit)."""
+        ...
+
+    def available_models(self) -> list[ModelCardRef]:
+        """The model catalog entries a picker lists, best-first. Derived from
+        the configured model matcher; returns ``[]`` when no matcher is wired
+        in."""
+        ...
+
+    def select_model(self, id: str) -> None:
+        """Bind a model by canonical id for subsequent turns. The companion
+        of ``cycle_model``; both route through the same selection path."""
+        ...
+
+    async def condense(self) -> None:
+        """Manually run the same transcript-condense path the auto-compactor
+        uses, emitting the existing ``compacted`` signal. Safe to call when
+        idle; a no-op when the condense hook returns the branch unchanged."""
+        ...
+
+    async def fork(self, entryId: str) -> None:
+        """Branch the transcript from a prior node. A new branch is opened
+        whose parent is ``entryId``; the agent's message list is rebound to
+        that branch's root→leaf path. The conductor's head advances onto the
+        chosen node."""
+        ...
+
+    async def navigate_tree(self, nodeId: str) -> None:
+        """Move the active leaf to ``nodeId``, rebuild that branch's
+        root→leaf path, and rebind the agent's message list to it. Used to
+        walk between existing branches without forking a new one."""
+        ...
+
+    async def execute_bash(
+        self, command: str, opts: ExecuteBashOptions | None = None
+    ) -> BashOutcome:
+        """Run a shell command in the session workspace, returning its
+        combined stdout+stderr and exit code. Unless
+        ``opts.excludeFromContext`` is set, the output is recorded as a
+        transcript note so it re-enters the agent's context. Never raises: a
+        spawn/exec failure resolves to a non-zero :class:`BashOutcome`."""
+        ...
+
+    def stats(self) -> SessionStats:
+        """A point-in-time :class:`SessionStats` tally for the active
+        session."""
+        ...
+
+    def thinking_level(self) -> ThinkingLevel:
+        """The reasoning effort currently applied to the session."""
+        ...
+
+    def set_thinking_level(self, level: ThinkingLevel) -> None:
+        """Set the reasoning effort for subsequent turns. Applied to the
+        agent when it exposes a setter; otherwise stored and applied on the
+        next model bind."""
+        ...
+
+    def cycle_thinking_level(self) -> ThinkingLevel:
+        """Advance the reasoning effort to the next level in the cycle,
+        applying it, and return the newly-selected level."""
+        ...
+
+    def session_name(self) -> str | None:
+        """The human-readable session name, or ``None`` when none is set."""
+        ...
+
+    def set_session_name(self, name: str) -> None:
+        """Assign a human-readable name to the session."""
+        ...
+
+    def subscribe(self, handler: SignalHandler) -> Callable[[], None]:
+        """Register a handler for the :data:`SessionSignal` stream. Returns
+        an unsubscribe function that removes the handler."""
+        ...
+
+    def abort(self) -> None:
+        """Cancel the in-flight turn, if any; emits an ``aborted`` fault
+        signal."""
+        ...
+
+    def snapshot(self) -> ConductorState:
+        """Read an immutable snapshot of the current
+        :class:`ConductorState`."""
+        ...
+
+    async def resume(self, sessionId: str) -> None:
+        """Restore a previously persisted session, replacing the current
+        transcript and rebinding the agent to the restored model/leaf."""
+        ...
+
+    async def new_session(self) -> None:
+        """Abandon the current conversation and start a fresh, empty session.
+
+        Drops the agent's message history, opens a new session id (so later
+        turns persist separately, leaving the prior transcript intact on
+        disk), zeroes the usage tally, clears the pending-input queue and
+        session name, and settles to ``idle``. Emits an ``idle`` signal so a
+        subscribed UI re-renders the now-empty conversation. This is what
+        ``/clear`` (and ``/new``) drive."""
+        ...
+
+    def cycle_model(self, id: str) -> None:
+        """Rotate the active model for subsequent turns. Optional in TS: not
+        every assembly supports mid-session model changes."""
+        ...