induscode 0.1.0__py3-none-any.whl

induscode/conductor/conductor.py

@@ -0,0 +1,1084 @@
+"""SessionConductor — the product-level orchestrator over the framework
+``Agent`` (port of TS ``src/conductor/conductor.ts``).
+
+The framework ``Agent`` (from :mod:`indusagi.agent`) is a raw LLM conversation
+loop: it streams a fine-grained ``AgentEvent`` surface and owns a flat message
+list. The :class:`SessionConductorImpl` wraps one such agent and turns it into
+a *coding-agent session*: it drives turns, projects the loop's events down to
+the stable :data:`~induscode.conductor.contract.SessionSignal` stream (via
+:func:`~induscode.conductor.signal_hub.translate_agent_event` + the
+:class:`~induscode.conductor.signal_hub.SignalHub`), persists every produced
+message into a branchable
+:class:`~induscode.conductor.transcript_store.TranscriptStore`, retries
+transient model faults, condenses the transcript when it nears the window, and
+resolves an immutable :class:`~induscode.conductor.contract.ConductorState`
+per turn.
+
+Design stance (the clean-room divergence, carried over from the TS source):
+
+- **Immutable state reducer.** The conductor never mutates a state object in
+  place. Each transition runs through
+  :func:`~induscode.conductor.contract.reduce_state`, which returns a fresh
+  ``ConductorState``; :meth:`SessionConductorImpl.snapshot` hands out that
+  value.
+- **Ordered in-flight tool list.** Live tool calls are tracked as an ordered
+  list (start appends, end removes) — not a set of pending ids.
+- **Typed discriminated faults.** Failures surface as a ``ConductorFault`` on
+  a ``fault`` signal — never as a fabricated assistant message and never as a
+  string sentinel.
+- **Pluggable condense seam.** Auto-compaction emits a ``compacted`` signal
+  and calls an injectable ``CondenseFn``; the real window-budget engine plugs
+  in as a non-default hook (the framework's own ``runtime.memory`` compactor
+  is *never* wired here — the two compaction engines stay distinct, plan
+  rule 6). The default :func:`noop_condense` is an identity transform.
+
+Everything heavy is injectable so tests run with no network and no disk: pass
+a scripted fake ``AgentLike`` (same submit/subscribe/event surface), an
+in-memory ``TranscriptStore``, a ``SignalHub``, a ``ModelMatcher`` over a
+stubbed catalog, and a counted no-op ``sleep``.
+
+Port notes
+----------
+- TS ``#private`` fields become ``_attrs``; the ``#sleep`` injectable becomes
+  an ``async def sleep(ms)`` callable so retry backoff never actually waits in
+  tests.
+- ``asyncio.CancelledError`` is **never swallowed**: every defensive
+  ``except Exception`` in the turn loop, persistence, condense, and bash paths
+  lets cancellation propagate (``CancelledError`` derives from
+  ``BaseException`` on 3.11+, and the bash runner re-raises it explicitly).
+- ``child_process.spawn`` becomes :func:`asyncio.create_subprocess_shell`
+  with stderr folded into stdout — the same merged-output contract.
+- The TS ``LazyAgent`` ``require``-style deferral is kept as a first-use
+  constructing wrapper, so the conductor module stays importable (and a
+  pure-fake test context never touches the live framework agent).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import os
+import random
+import time
+from collections.abc import Awaitable, Callable, Sequence
+from dataclasses import dataclass, replace
+from typing import Any
+
+from indusagi.agent import Agent, AgentEvent
+from indusagi.ai import UsageCost, UserMessage, create_zero_usage
+
+from induscode.conductor.catalog import ModelCatalog
+from induscode.conductor.contract import (
+    AgentLike,
+    AgentMessage,
+    BashOutcome,
+    CompactedSignal,
+    CondenseFn,
+    ConductorState,
+    ExecuteBashOptions,
+    FaultAction,
+    FaultSignal,
+    HeadAction,
+    IdleSignal,
+    ModelAction,
+    ModelCardRef,
+    PersistedSignal,
+    PhaseAction,
+    QueueMode,
+    QueueSignal,
+    QueuedInput,
+    RetryPolicy,
+    SessionConductor,
+    SessionConductorOptions,
+    SessionStats,
+    SettledAction,
+    SignalHandler,
+    StateAction,
+    ThinkingLevel,
+    TokenTally,
+    Usage,
+    UsageAction,
+    conductor_fault,
+    reduce_state,
+)
+from induscode.conductor.matcher import ModelMatcher
+from induscode.conductor.signal_hub import SignalHub, translate_agent_event
+from induscode.conductor.skill_parse import parse_skill_invocation
+from induscode.conductor.transcript_store import TranscriptStore, fs_backend
+
+__all__ = [
+    "ConductorDeps",
+    "DEFAULT_RETRY",
+    "LazyAgent",
+    "SessionConductorImpl",
+    "create_session_conductor",
+    "noop_condense",
+]
+
+
+# ---------------------------------------------------------------------------
+# Condense seam
+# ---------------------------------------------------------------------------
+
+
+def noop_condense(
+    messages: Sequence[AgentMessage], force: bool = False
+) -> Sequence[AgentMessage]:
+    """The default condense hook: returns the input unchanged (no-op)."""
+    return messages
+
+
+# ---------------------------------------------------------------------------
+# Retry policy + assembly defaults
+# ---------------------------------------------------------------------------
+
+#: Default transient-fault auto-retry tuning (TS ``DEFAULT_RETRY``).
+DEFAULT_RETRY: RetryPolicy = RetryPolicy(maxAttempts=2, baseDelayMs=250)
+
+#: Soft threshold (in branch length) past which auto-compaction is considered.
+_DEFAULT_COMPACT_AT = 200
+
+#: The reasoning-effort ladder the conductor cycles through. Ordered low→high
+#: so :meth:`SessionConductorImpl.cycle_thinking_level` advances and wraps
+#: predictably. The framework clamps an unsupported level to the active
+#: model's ceiling.
+_THINKING_LADDER: tuple[ThinkingLevel, ...] = ("off", "low", "medium", "high")
+
+#: Default reasoning effort when none is configured at assembly.
+_DEFAULT_THINKING: ThinkingLevel = "off"
+
+
+async def _default_sleep(ms: float) -> None:
+    """The live sleep primitive (tests inject a counted no-op instead)."""
+    await asyncio.sleep(ms / 1000)
+
+
+# ---------------------------------------------------------------------------
+# Dependency bundle
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class ConductorDeps:
+    """Injectable collaborators (TS ``ConductorDeps``). Every field is
+    optional; the factory supplies a live default (a real ``Agent``, an
+    in-memory ``TranscriptStore``, a fresh ``SignalHub``, a matcher over the
+    live catalog). Tests override exactly what they need."""
+
+    #: The framework agent (or a scripted fake).
+    agent: AgentLike | None = None
+    #: Where the transcript persists.
+    store: TranscriptStore | None = None
+    #: The product-signal fan-out.
+    hub: SignalHub | None = None
+    #: Resolves model ids/patterns to catalog cards.
+    matcher: ModelMatcher | None = None
+    #: The condense hook used by the auto-compaction seam.
+    condense: CondenseFn | None = None
+    #: Auto-retry tuning.
+    retry: RetryPolicy | None = None
+    #: Branch length past which auto-compaction fires (default 200).
+    compactAt: int | None = None
+    #: Sleep primitive in milliseconds (injected so tests don't actually
+    #: wait).
+    sleep: Callable[[float], Awaitable[None]] | None = None
+
+
+# ---------------------------------------------------------------------------
+# Usage accumulation
+# ---------------------------------------------------------------------------
+
+
+def _context_tokens_of(turn: Usage) -> int:
+    """Tokens occupying the context window as reported by a single turn's
+    usage.
+
+    Mirrors the framework's context-size accounting: a turn's ``totalTokens``
+    when present, else the sum of input + output + cache reads/writes. Applied
+    to the LATEST turn (not summed across turns), this is the live context
+    occupancy the footer's ``ctx:%`` reflects — distinct from the cumulative
+    session ``Usage``.
+    """
+    return turn.totalTokens or (
+        turn.input + turn.output + turn.cacheRead + turn.cacheWrite
+    )
+
+
+def _accumulate_usage(running: Usage, delta: Usage) -> Usage:
+    """Fold a per-turn ``Usage`` into a running cumulative total."""
+    return Usage(
+        input=running.input + delta.input,
+        output=running.output + delta.output,
+        cacheRead=running.cacheRead + delta.cacheRead,
+        cacheWrite=running.cacheWrite + delta.cacheWrite,
+        totalTokens=running.totalTokens + delta.totalTokens,
+        cost=UsageCost(
+            input=running.cost.input + delta.cost.input,
+            output=running.cost.output + delta.cost.output,
+            cacheRead=running.cost.cacheRead + delta.cost.cacheRead,
+            cacheWrite=running.cost.cacheWrite + delta.cost.cacheWrite,
+            total=running.cost.total + delta.cost.total,
+        ),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Transient-fault classification
+# ---------------------------------------------------------------------------
+
+_TRANSIENT_MARKERS: tuple[str, ...] = (
+    "429",
+    "rate limit",
+    "overloaded",
+    "timeout",
+    "timed out",
+    "econnreset",
+    "etimedout",
+    "503",
+    "502",
+    "500",
+    "unavailable",
+    "temporarily",
+)
+
+
+def _is_transient(error: object) -> bool:
+    """Heuristic: is this thrown error a transient model fault worth
+    retrying?"""
+    text = str(error).lower()
+    return any(marker in text for marker in _TRANSIENT_MARKERS)
+
+
+# ---------------------------------------------------------------------------
+# Tolerant event probing (raw events are frozen dataclasses from the live
+# loop, but may be dict-shaped in tests — same defensive stance as the
+# signal-hub translator)
+# ---------------------------------------------------------------------------
+
+
+def _event_field(event: Any, name: str, default: Any = None) -> Any:
+    if isinstance(event, dict):
+        return event.get(name, default)
+    return getattr(event, name, default)
+
+
+# ---------------------------------------------------------------------------
+# The conductor implementation
+# ---------------------------------------------------------------------------
+
+
+class SessionConductorImpl:
+    """The :class:`~induscode.conductor.contract.SessionConductor` of a single
+    coding-agent session (TS ``SessionConductorImpl``).
+
+    Construct through :func:`create_session_conductor`, which resolves every
+    collaborator; the class itself only orchestrates.
+    """
+
+    __slots__ = (
+        "_agent",
+        "_store",
+        "_hub",
+        "_matcher",
+        "_condense",
+        "_retry",
+        "_compact_at",
+        "_auto_compact",
+        "_sleep",
+        "_state",
+        "_in_flight_tools",
+        "_busy",
+        "_bound_model",
+        "_queue",
+        "_draining",
+        "_thinking",
+        "_session_name",
+        "_workspace",
+    )
+
+    def __init__(
+        self,
+        options: SessionConductorOptions,
+        deps: ConductorDeps,
+        agent: AgentLike,
+        store: TranscriptStore,
+    ) -> None:
+        self._agent = agent
+        self._store = store
+        self._hub = deps.hub if deps.hub is not None else SignalHub()
+        self._matcher = deps.matcher
+        self._condense = deps.condense if deps.condense is not None else noop_condense
+        self._retry = deps.retry if deps.retry is not None else DEFAULT_RETRY
+        self._compact_at = (
+            deps.compactAt if deps.compactAt is not None else _DEFAULT_COMPACT_AT
+        )
+        self._auto_compact = options.autoCompact if options.autoCompact is not None else True
+        self._sleep = deps.sleep if deps.sleep is not None else _default_sleep
+        self._thinking: ThinkingLevel = (
+            options.thinking if options.thinking is not None else _DEFAULT_THINKING
+        )
+        self._workspace = options.workspace if options.workspace is not None else os.getcwd()
+
+        # The single source of truth, swapped wholesale by `_dispatch`.
+        self._state = ConductorState(
+            phase="idle",
+            head=store.head,
+            usage=create_zero_usage(),
+            contextTokens=0,
+            modelId=options.modelId,
+            # no fault initially
+        )
+
+        # Ordered list of in-flight tool calls (start appends; end removes by
+        # id), as (id, name) pairs.
+        self._in_flight_tools: list[tuple[str, str]] = []
+        # Whether a turn is currently in flight (guards re-entrant submit).
+        self._busy = False
+        # Inputs awaiting a turn, oldest first. Drained after the active turn
+        # settles.
+        self._queue: list[QueuedInput] = []
+        # Whether the queue drain loop is already running (re-entrancy guard).
+        self._draining = False
+        # The optional human-readable session name.
+        self._session_name: str | None = None
+
+        # Resolve the full model object for the initial selection. Prefer the
+        # matcher's catalog record (carries the framework model), falling back
+        # to whatever the agent was assembled with.
+        initial = (
+            self._matcher.resolve_card(options.modelId)
+            if self._matcher is not None
+            else None
+        )
+        self._bound_model: Any = initial.model if initial is not None else agent.state.model
+
+    # ---- public surface ----
+
+    def subscribe(self, handler: SignalHandler) -> Callable[[], None]:
+        return self._hub.subscribe(handler)
+
+    def snapshot(self) -> ConductorState:
+        return self._state
+
+    def messages(self) -> Sequence[AgentMessage]:
+        return self._agent.state.messages
+
+    def model(self) -> Any:
+        return self._bound_model
+
+    def is_busy(self) -> bool:
+        return self._busy
+
+    def available_models(self) -> list[ModelCardRef]:
+        if self._matcher is None:
+            return []
+        # An empty selector yields the whole field as ranked card refs.
+        return list(self._matcher.resolve_all(""))
+
+    def abort(self) -> None:
+        self._agent.abort()
+        self._dispatch(
+            FaultAction(fault=conductor_fault("aborted", "turn aborted by caller"))
+        )
+        self._hub.emit(
+            FaultSignal(fault=conductor_fault("aborted", "turn aborted by caller"))
+        )
+        self._hub.emit(IdleSignal())
+
+    async def submit(self, input: str) -> ConductorState:
+        # Busy: do not drop the input and do not fault. Queue it to run as a
+        # later turn and hand back the current snapshot. The drain loop,
+        # started by the in-flight turn once it settles, runs it
+        # automatically.
+        if self._busy:
+            self.enqueue(input)
+            return self._state
+        self._busy = True
+        try:
+            state = await self._run_turn(input)
+            # The just-finished turn owns draining whatever piled up while it
+            # ran.
+            await self._drain_queue()
+            return state
+        finally:
+            self._busy = False
+
+    def enqueue(self, input: str, mode: QueueMode = "followUp") -> None:
+        self._queue.append(QueuedInput(mode=mode, text=input))
+        self._hub.emit(QueueSignal(count=len(self._queue)))
+
+    def pending_count(self) -> int:
+        return len(self._queue)
+
+    def pending_inputs(self) -> Sequence[QueuedInput]:
+        return list(self._queue)
+
+    def clear_queue(self) -> None:
+        if len(self._queue) == 0:
+            return
+        self._queue.clear()
+        self._hub.emit(QueueSignal(count=0))
+
+    def dequeue_last(self) -> str | None:
+        if len(self._queue) == 0:
+            return None
+        popped = self._queue.pop()
+        self._hub.emit(QueueSignal(count=len(self._queue)))
+        return popped.text
+
+    async def _drain_queue(self) -> None:
+        """Drain the pending-input queue in order, running each entry as its
+        own turn. ``steer``-mode entries are taken ahead of plain follow-ups
+        so an interrupt is honored first. Re-entrancy is guarded so a
+        ``submit`` that fires mid-drain (it merely enqueues) does not start a
+        second loop. Runs under the busy flag the active turn already holds.
+        """
+        if self._draining:
+            return
+        self._draining = True
+        try:
+            while len(self._queue) > 0:
+                next_input = self._take_next()
+                self._hub.emit(QueueSignal(count=len(self._queue)))
+                await self._run_turn(next_input.text)
+        finally:
+            self._draining = False
+
+    def _take_next(self) -> QueuedInput:
+        """Pop the next queued input, preferring a ``steer`` entry over a
+        follow-up."""
+        for at, queued in enumerate(self._queue):
+            if queued.mode == "steer":
+                return self._queue.pop(at)
+        return self._queue.pop(0)
+
+    async def _run_turn(self, input: str) -> ConductorState:
+        """Run a single prompt turn to settlement: unwrap a skill block, drive
+        the agent through the retry loop, then persist + condense + settle.
+        Returns the resulting state. Does not touch the busy flag or the
+        queue — those are the caller's concern."""
+        # A leading <skill …> block is a product-level invocation; we expand
+        # it to the body text the agent actually sends. (Routing the named
+        # skill to its handler is a higher layer's job; here we only unwrap
+        # the carried message.)
+        skill = parse_skill_invocation(input)
+        prompt = skill.body if skill is not None else input
+
+        self._in_flight_tools.clear()
+        self._dispatch(PhaseAction(phase="streaming"))
+
+        baseline = len(self._agent.state.messages)
+        clean = await self._run_with_retry(prompt)
+
+        # A faulted turn keeps its typed fault and stays `faulted`: we do NOT
+        # persist a partial tail, condense, or settle to idle on top of it.
+        # The caller reads `fault` off the returned state and decides what to
+        # do.
+        if not clean:
+            self._hub.emit(IdleSignal())
+            return self._state
+
+        await self._persist_tail(baseline)
+        await self._maybe_condense()
+
+        # Persistence/condense may themselves fault; only settle if still
+        # clean.
+        if self._state.phase != "faulted":
+            self._dispatch(SettledAction())
+            self._dispatch(HeadAction(head=self._store.head))
+        self._hub.emit(IdleSignal())
+        return self._state
+
+    async def new_session(self) -> None:
+        # Stop any in-flight stream so it cannot append into the session we
+        # are about to abandon (abort is a no-op when idle).
+        self._agent.abort()
+        self._busy = False
+        self._draining = False
+        self._queue.clear()
+        self._in_flight_tools.clear()
+
+        # Drop the conversation and open a brand-new session id; the prior
+        # transcript file is left untouched on disk.
+        self._agent.replace_messages([])
+        self._store.start_new_session(_new_session_id())
+        self._session_name = None
+
+        self._state = ConductorState(
+            phase="idle",
+            head=self._store.head,
+            usage=create_zero_usage(),
+            contextTokens=0,
+            modelId=self._state.modelId,
+        )
+
+        # Pulse the stream so a subscribed UI re-reads messages() (now empty)
+        # and the fresh idle state.
+        self._hub.emit(IdleSignal())
+
+    async def resume(self, sessionId: str) -> None:
+        loaded = await self._store.load(sessionId)
+        if not loaded:
+            fault = conductor_fault("persistence", f'no session "{sessionId}" to resume')
+            self._dispatch(FaultAction(fault=fault))
+            self._hub.emit(FaultSignal(fault=fault))
+            return
+        # Rehydrate the agent from the restored active branch.
+        branch = self._store.path_to()
+        self._agent.replace_messages([entry.content for entry in branch])
+        self._dispatch(HeadAction(head=self._store.head))
+        self._dispatch(SettledAction())
+        self._hub.emit(IdleSignal())
+
+    def cycle_model(self, id: str) -> None:
+        self._bind_model(id)
+
+    def select_model(self, id: str) -> None:
+        self._bind_model(id)
+
+    def _bind_model(self, id: str) -> None:
+        """Resolve a model by canonical id, bind it on the agent for
+        subsequent turns, track the full model object, and record the new id
+        in state. A miss surfaces a typed ``model`` fault and leaves the
+        current selection untouched."""
+        card = self._matcher.resolve_card(id) if self._matcher is not None else None
+        if card is None:
+            fault = conductor_fault("model", f'no model matches "{id}"')
+            self._dispatch(FaultAction(fault=fault))
+            self._hub.emit(FaultSignal(fault=fault))
+            return
+        self._agent.set_model(card.model)
+        self._bound_model = card.model
+        # Re-apply the tracked reasoning effort to the freshly bound model;
+        # the framework clamps it to the model's ceiling.
+        self._apply_thinking(self._thinking)
+        self._dispatch(ModelAction(modelId=card.id))
+
+    # ---- turn driving ----
+
+    async def _run_with_retry(self, prompt: str) -> bool:
+        """Run one prompt turn, retrying transient model faults with
+        exponential backoff. A non-transient raise, or exhausting the retry
+        budget, surfaces a typed ``ConductorFault`` (never a fabricated
+        assistant message) and ends the loop.
+
+        Returns ``True`` when the turn completed without a raised fault,
+        ``False`` when a terminal model fault was dispatched. (A streaming
+        ``error`` sub-event that does *not* raise is handled separately — it
+        dispatches a fault from :meth:`_on_agent_event` and the caller's
+        ``phase`` guard prevents a settle on top of it.)
+        ``asyncio.CancelledError`` always propagates — never retried, never
+        converted to a fault.
+        """
+        attempt = 0
+        while True:
+            unsubscribe = self._agent.subscribe(self._on_agent_event)
+            try:
+                await self._agent.prompt(prompt)
+            except asyncio.CancelledError:
+                unsubscribe()
+                raise
+            except Exception as error:  # noqa: BLE001 — classified below
+                unsubscribe()
+                if attempt < self._retry.maxAttempts and _is_transient(error):
+                    attempt += 1
+                    self._hub.emit(
+                        FaultSignal(
+                            fault=conductor_fault(
+                                "model", f"transient model fault; retry {attempt}", error
+                            )
+                        )
+                    )
+                    await self._sleep(self._retry.baseDelayMs * 2 ** (attempt - 1))
+                    continue
+                fault = conductor_fault("model", "model turn failed", error)
+                self._dispatch(FaultAction(fault=fault))
+                self._hub.emit(FaultSignal(fault=fault))
+                return False
+            else:
+                unsubscribe()
+                return True
+
+    def _on_agent_event(self, event: AgentEvent) -> None:
+        """Translate one raw framework event to product signals, emit them,
+        and keep the conductor's own bookkeeping (ordered in-flight tools,
+        cumulative usage, tooling/streaming phase) in step."""
+        # Phase + in-flight tracking driven off the raw event before
+        # projection.
+        event_type = _event_field(event, "type")
+        if event_type == "tool_execution_start":
+            self._in_flight_tools.append(
+                (_event_field(event, "toolCallId"), _event_field(event, "toolName"))
+            )
+            self._dispatch(PhaseAction(phase="tooling"))
+        elif event_type == "tool_execution_end":
+            tool_call_id = _event_field(event, "toolCallId")
+            for at, (tool_id, _name) in enumerate(self._in_flight_tools):
+                if tool_id == tool_call_id:
+                    del self._in_flight_tools[at]
+                    break
+            if len(self._in_flight_tools) == 0 and self._state.phase == "tooling":
+                self._dispatch(PhaseAction(phase="streaming"))
+
+        for signal in translate_agent_event(event):
+            if signal.kind == "turn_end":
+                self._dispatch(
+                    UsageAction(
+                        usage=_accumulate_usage(self._state.usage, signal.usage),
+                        contextTokens=_context_tokens_of(signal.usage),
+                    )
+                )
+            elif signal.kind == "fault":
+                self._dispatch(FaultAction(fault=signal.fault))
+            self._hub.emit(signal)
+
+    # ---- persistence ----
+
+    async def _persist_tail(self, baseline: int) -> None:
+        """Persist every message the turn appended beyond ``baseline`` into
+        the transcript store (user prompt, assistant turns, tool results).
+        Emits one ``persisted`` signal per committed node so consumers can
+        correlate."""
+        messages = self._agent.state.messages
+        for i in range(baseline, len(messages)):
+            message = messages[i]
+            try:
+                entry = await self._store.append(message)
+                self._hub.emit(PersistedSignal(entryId=entry.id))
+            except asyncio.CancelledError:
+                raise
+            except Exception as error:  # noqa: BLE001 — surfaced as a fault
+                fault = conductor_fault(
+                    "persistence", "failed to persist transcript node", error
+                )
+                self._dispatch(FaultAction(fault=fault))
+                self._hub.emit(FaultSignal(fault=fault))
+                return
+
+    # ---- auto-compaction seam ----
+
+    async def _maybe_condense(self) -> None:
+        """The auto-compaction seam. When enabled and the active branch has
+        grown past the soft threshold, emit a ``compacted`` signal, run the
+        pluggable condense hook over the branch messages, and (if it shrank
+        the list) rebind the agent's context to the condensed messages. The
+        real window-budget engine plugs in here as a non-default
+        ``CondenseFn``."""
+        if not self._auto_compact:
+            return
+        branch = self._store.path_to()
+        if len(branch) < self._compact_at:
+            return
+        await self._run_condense(False)
+
+    async def condense(self) -> None:
+        """Manually drive the same condense path the auto-compactor uses,
+        regardless of the auto-compaction flag or the soft threshold. Emits a
+        ``compacted`` signal and rebinds the agent's context when the hook
+        shrinks the branch. Safe to invoke while idle."""
+        # A manual `/compact` forces aggressive compaction regardless of size
+        # — the user explicitly asked to reclaim context, so the hook keeps
+        # only a small recent tail rather than waiting for the auto-compaction
+        # threshold.
+        await self._run_condense(True)
+
+    # ---- branch navigation ----
+
+    async def fork(self, entryId: str) -> None:
+        try:
+            await self._store.branch_at(entryId)
+        except asyncio.CancelledError:
+            raise
+        except Exception as error:  # noqa: BLE001 — surfaced as a fault
+            fault = conductor_fault("persistence", f'cannot fork from "{entryId}"', error)
+            self._dispatch(FaultAction(fault=fault))
+            self._hub.emit(FaultSignal(fault=fault))
+            return
+        self._rebind_branch()
+
+    async def navigate_tree(self, nodeId: str) -> None:
+        try:
+            await self._store.branch_at(nodeId)
+        except asyncio.CancelledError:
+            raise
+        except Exception as error:  # noqa: BLE001 — surfaced as a fault
+            fault = conductor_fault(
+                "persistence", f'cannot navigate to "{nodeId}"', error
+            )
+            self._dispatch(FaultAction(fault=fault))
+            self._hub.emit(FaultSignal(fault=fault))
+            return
+        self._rebind_branch()
+
+    def _rebind_branch(self) -> None:
+        """Rebuild the active root→leaf branch and replay it onto the agent,
+        then sync the head into state. Shared by :meth:`fork` and
+        :meth:`navigate_tree` after the store's leaf has moved."""
+        branch = self._store.path_to()
+        self._agent.replace_messages([entry.content for entry in branch])
+        self._dispatch(HeadAction(head=self._store.head))
+        self._dispatch(SettledAction())
+        self._hub.emit(IdleSignal())
+
+    # ---- shell ----
+
+    async def execute_bash(
+        self, command: str, opts: ExecuteBashOptions | None = None
+    ) -> BashOutcome:
+        options = opts if opts is not None else ExecuteBashOptions()
+        outcome = await _run_shell_command(command, self._workspace)
+        if not options.excludeFromContext:
+            try:
+                await self._store.append(
+                    _bash_note_message(command, outcome),
+                    "note",
+                    {"command": command, "exitCode": outcome.exitCode},
+                )
+                self._dispatch(HeadAction(head=self._store.head))
+            except asyncio.CancelledError:
+                raise
+            except Exception as error:  # noqa: BLE001 — surfaced as a fault
+                fault = conductor_fault(
+                    "persistence", "failed to record bash output", error
+                )
+                self._dispatch(FaultAction(fault=fault))
+                self._hub.emit(FaultSignal(fault=fault))
+        return outcome
+
+    # ---- statistics ----
+
+    def stats(self) -> SessionStats:
+        messages = self._agent.state.messages
+        user_messages = 0
+        assistant_messages = 0
+        tool_results = 0
+        tool_calls = 0
+        for message in messages:
+            role = _event_field(message, "role")
+            if role == "user":
+                user_messages += 1
+            elif role == "assistant":
+                assistant_messages += 1
+                content = _event_field(message, "content") or ()
+                if isinstance(content, Sequence) and not isinstance(content, str):
+                    for part in content:
+                        if _event_field(part, "type") == "toolCall":
+                            tool_calls += 1
+            elif role == "toolResult":
+                tool_results += 1
+        usage = self._state.usage
+        return SessionStats(
+            sessionId=self._state.head.sessionId,
+            userMessages=user_messages,
+            assistantMessages=assistant_messages,
+            toolCalls=tool_calls,
+            toolResults=tool_results,
+            totalMessages=len(messages),
+            tokens=TokenTally(
+                input=usage.input,
+                output=usage.output,
+                cacheRead=usage.cacheRead,
+                cacheWrite=usage.cacheWrite,
+                total=usage.totalTokens,
+            ),
+            cost=usage.cost.total,
+        )
+
+    # ---- reasoning effort ----
+
+    def thinking_level(self) -> ThinkingLevel:
+        return self._thinking
+
+    def set_thinking_level(self, level: ThinkingLevel) -> None:
+        self._thinking = level
+        self._apply_thinking(level)
+
+    def cycle_thinking_level(self) -> ThinkingLevel:
+        # TS `indexOf` yields -1 on a miss, advancing to the ladder's first
+        # rung; `.index` raises, so probe first.
+        at = (
+            _THINKING_LADDER.index(self._thinking)
+            if self._thinking in _THINKING_LADDER
+            else -1
+        )
+        next_level = _THINKING_LADDER[(at + 1) % len(_THINKING_LADDER)]
+        self.set_thinking_level(next_level)
+        return next_level
+
+    def _apply_thinking(self, level: ThinkingLevel) -> None:
+        """Apply a reasoning effort to the agent when it exposes a setter
+        (the TS optional ``setThinkingLevel?.()`` probe); otherwise the level
+        stays stored and is re-applied on the next model bind."""
+        setter = getattr(self._agent, "set_thinking_level", None)
+        if callable(setter):
+            setter(level)
+
+    # ---- session name ----
+
+    def session_name(self) -> str | None:
+        return self._session_name
+
+    def set_session_name(self, name: str) -> None:
+        self._session_name = name
+
+    async def _run_condense(self, force: bool) -> None:
+        """The shared condense body: flip to ``condensing``, emit the
+        ``compacted`` signal, run the pluggable hook over the active branch,
+        and rebind the agent's context when the hook returns a shorter list. A
+        raise surfaces an ``overflow`` fault."""
+        branch = self._store.path_to()
+        self._dispatch(PhaseAction(phase="condensing"))
+        self._hub.emit(CompactedSignal())
+        try:
+            before = [entry.content for entry in branch]
+            result = self._condense(before, force)
+            after = await result if inspect.isawaitable(result) else result
+            if len(after) < len(before):
+                self._agent.replace_messages(after)
+        except asyncio.CancelledError:
+            raise
+        except Exception as error:  # noqa: BLE001 — surfaced as a fault
+            fault = conductor_fault("overflow", "auto-condense failed", error)
+            self._dispatch(FaultAction(fault=fault))
+            self._hub.emit(FaultSignal(fault=fault))
+
+    # ---- reducer plumbing ----
+
+    def _dispatch(self, action: StateAction) -> None:
+        """Run an action through the immutable reducer and swap in the new
+        state."""
+        self._state = reduce_state(self._state, action)
+
+
+# ---------------------------------------------------------------------------
+# Factory
+# ---------------------------------------------------------------------------
+
+
+def create_session_conductor(
+    options: SessionConductorOptions,
+    deps: ConductorDeps | None = None,
+) -> SessionConductor:
+    """Construct a :class:`~induscode.conductor.contract.SessionConductor`.
+
+    Resolves (or accepts) every collaborator, then returns the orchestrator:
+
+    - **Agent** — ``deps.agent`` if supplied (the scripted-fake seam tests
+      use), else a live framework ``Agent`` bound to the model
+      ``options.modelId`` resolves to via the ``ModelMatcher`` over the
+      ``ModelCatalog``.
+    - **Store** — ``deps.store`` if supplied, else a fresh in-memory
+      ``TranscriptStore`` for a new session id (filesystem-backed when
+      ``options.sessionsDir`` is set).
+    - **Hub / matcher / condense / retry** — defaulted from ``deps`` or
+      fresh.
+
+    The conductor's public verbs (``submit``, ``subscribe``, ``abort``,
+    ``snapshot``, ``resume``, ``cycle_model``) all read against this assembly.
+
+    :param options: session configuration (``modelId`` required;
+        system/tools/thinking/workspace/autoCompact optional)
+    :param deps: injectable collaborators; all optional, live defaults
+        supplied
+    """
+    resolved = deps if deps is not None else ConductorDeps()
+    # Persist to disk when a sessions directory is supplied (the live CLI
+    # path), so the conversation can be resumed; otherwise keep the in-memory
+    # default (tests, headless probes, or an explicitly injected store).
+    store = (
+        resolved.store
+        if resolved.store is not None
+        else TranscriptStore(
+            _new_session_id(),
+            backend=fs_backend(options.sessionsDir)
+            if options.sessionsDir is not None
+            else None,
+        )
+    )
+    # On the live path (no injected agent) default a matcher over the
+    # framework catalog and thread it into the conductor instance — otherwise
+    # `_matcher` is None and `available_models()` / model switching come up
+    # empty. A test that injects its own agent keeps whatever matcher it
+    # passed (possibly none).
+    matcher = (
+        resolved.matcher
+        if resolved.matcher is not None
+        else (ModelMatcher(ModelCatalog()) if resolved.agent is None else None)
+    )
+    resolved_deps = replace(resolved, matcher=matcher)
+    agent = (
+        resolved.agent
+        if resolved.agent is not None
+        else _build_live_agent(options, resolved_deps)
+    )
+    # Seed the live agent's context (system/tools/thinking) from options when
+    # we own it.
+    if resolved.agent is None:
+        if options.system is not None:
+            agent.set_system_prompt(options.system)
+        if options.tools is not None:
+            agent.set_tools(options.tools)
+        if options.thinking is not None:
+            setter = getattr(agent, "set_thinking_level", None)
+            if callable(setter):
+                setter(options.thinking)
+    return SessionConductorImpl(options, resolved_deps, agent, store)
+
+
+# ---------------------------------------------------------------------------
+# Live-agent assembly (only reached when no agent is injected)
+# ---------------------------------------------------------------------------
+
+
+def _build_live_agent(
+    options: SessionConductorOptions, deps: ConductorDeps
+) -> AgentLike:
+    """Build a live framework ``Agent`` bound to the model ``options.modelId``
+    resolves to. The construction itself is deferred behind :class:`LazyAgent`
+    so a conductor assembled on the live path stays cheap until the first
+    turn."""
+    matcher = deps.matcher if deps.matcher is not None else ModelMatcher(ModelCatalog())
+    card = matcher.resolve_card(options.modelId)
+    if card is None:
+        raise ValueError(
+            f'create_session_conductor: no model matches "{options.modelId}"'
+        )
+    return LazyAgent(card.model, options)
+
+
+class LazyAgent:
+    """A thin ``AgentLike`` that constructs the real framework ``Agent`` on
+    first use (TS ``LazyAgent``). The wrapper presents the plain ``AgentLike``
+    surface the conductor expects; tests bypass it entirely by passing
+    ``deps.agent``."""
+
+    __slots__ = ("_real", "_model", "_options")
+
+    def __init__(self, model: Any, options: SessionConductorOptions) -> None:
+        self._real: AgentLike | None = None
+        self._model = model
+        self._options = options
+
+    def _ensure(self) -> AgentLike:
+        if self._real is None:
+            self._real = _make_agent(self._model, self._options)
+        return self._real
+
+    def subscribe(self, fn: Callable[[AgentEvent], None]) -> Callable[[], None]:
+        return self._ensure().subscribe(fn)
+
+    async def prompt(self, input: str) -> None:
+        await self._ensure().prompt(input)
+
+    def abort(self) -> None:
+        self._ensure().abort()
+
+    @property
+    def state(self) -> Any:
+        return self._ensure().state
+
+    def replace_messages(self, messages: Sequence[AgentMessage]) -> None:
+        self._ensure().replace_messages(messages)
+
+    def set_model(self, model: Any) -> None:
+        self._ensure().set_model(model)
+
+    def set_system_prompt(self, prompt: str) -> None:
+        self._ensure().set_system_prompt(prompt)
+
+    def set_tools(self, tools: Sequence[Any]) -> None:
+        self._ensure().set_tools(tools)
+
+    def set_thinking_level(self, level: ThinkingLevel) -> None:
+        setter = getattr(self._ensure(), "set_thinking_level", None)
+        if callable(setter):
+            setter(level)
+
+
+def _make_agent(model: Any, options: SessionConductorOptions) -> AgentLike:
+    """Instantiate the framework ``Agent`` and shape it to ``AgentLike``.
+
+    Constructed from :class:`indusagi.agent.Agent`, seeded with the resolved
+    model and the optional system/tools/thinking from ``options`` via
+    ``initial_state`` (the framework's ``AgentState`` field spellings).
+    ``get_api_key`` is threaded through so the framework can rotate
+    short-lived OAuth tokens and authenticate providers with no env-var
+    mapping; omitted entirely when no resolver was supplied so the framework
+    keeps its default env-only behaviour.
+    """
+    initial_state: dict[str, Any] = {"model": model}
+    if options.system is not None:
+        initial_state["systemPrompt"] = options.system
+    if options.tools is not None:
+        initial_state["tools"] = list(options.tools)
+    if options.thinking is not None:
+        initial_state["thinkingLevel"] = options.thinking
+    kwargs: dict[str, Any] = {}
+    if options.getApiKey is not None:
+        kwargs["get_api_key"] = options.getApiKey
+    agent = Agent(initial_state=initial_state, **kwargs)
+    # The framework class satisfies AgentLike structurally (the TS cast).
+    return agent  # type: ignore[return-value]
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+_BASE36_DIGITS = "0123456789abcdefghijklmnopqrstuvwxyz"
+
+
+def _to_base36(value: int) -> str:
+    """``Number.prototype.toString(36)`` for a non-negative integer."""
+    if value == 0:
+        return "0"
+    out: list[str] = []
+    while value > 0:
+        value, rem = divmod(value, 36)
+        out.append(_BASE36_DIGITS[rem])
+    return "".join(reversed(out))
+
+
+def _new_session_id() -> str:
+    """Mint a fresh session id (timestamp-sorted, TS
+    ``s_<epoch36>_<rand8>``)."""
+    stamp = _to_base36(int(time.time() * 1000))
+    suffix = "".join(random.choices(_BASE36_DIGITS, k=8))
+    return f"s_{stamp}_{suffix}"
+
+
+async def _run_shell_command(command: str, cwd: str) -> BashOutcome:
+    """Run a shell command in ``cwd``, resolving to its combined
+    stdout+stderr and exit code. Never raises (cancellation excepted): a
+    spawn failure (binary missing, permission) resolves to a non-zero
+    :class:`BashOutcome` carrying the error text."""
+    try:
+        process = await asyncio.create_subprocess_shell(
+            command,
+            cwd=cwd,
+            stdout=asyncio.subprocess.PIPE,
+            # Fold stderr into stdout — the TS runner concatenated both
+            # streams into one buffer.
+            stderr=asyncio.subprocess.STDOUT,
+        )
+        stdout, _stderr = await process.communicate()
+        output = stdout.decode("utf-8", errors="replace") if stdout else ""
+        exit_code = process.returncode if process.returncode is not None else 1
+        return BashOutcome(output=output, exitCode=exit_code)
+    except asyncio.CancelledError:
+        raise
+    except Exception as error:  # noqa: BLE001 — never-raise contract
+        return BashOutcome(output=_error_text(error), exitCode=1)
+
+
+def _error_text(error: object) -> str:
+    """Render a raised value to a single readable line."""
+    return str(error)
+
+
+def _bash_note_message(command: str, outcome: BashOutcome) -> AgentMessage:
+    """Build a user-role ``AgentMessage`` capturing a bash command and its
+    output, so a recorded run re-enters the agent's context as plain context
+    text."""
+    body = f"$ {command}\n{outcome.output}".rstrip()
+    return UserMessage(content=body, timestamp=int(time.time() * 1000))