indusagi-coding-agent 0.1.59 → 0.1.60

package/dist/types/conductor/contract.d.ts

@@ -0,0 +1,547 @@
+/**
+ * Conductor contract — the FROZEN type surface of Phase 2 (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 `indusagi/agent`). It declares *only* shapes
+ * plus two tiny inert helpers — no behavior, no I/O, no orchestration. Every
+ * later conductor module (the signal hub, the transcript store, the model
+ * catalog/matcher, the credential vault, the conductor factory, and the
+ * `SessionConductor` itself) is written against the names declared here, so the
+ * file is intentionally small, append-mostly, and stable.
+ *
+ * Design stance:
+ *   - 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
+ *     {@link 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** ({@link ConductorFault}), never
+ *     string sentinels. A consumer switches on `fault.kind`, not on substring
+ *     matching of a message.
+ *   - Persistence uses a **fresh on-disk vocabulary** ({@link TranscriptEntry},
+ *     {@link SessionHead}, {@link 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** ({@link ConductorState});
+ *     consumers read it, they never mutate it.
+ *
+ * Framework anchors (all from the `indusagi` package — the sibling rebuilt
+ * framework this app targets):
+ *   - `AgentMessage`, `ThinkingLevel`, `AgentTool` ← `indusagi/agent`
+ *   - `Model`, `Usage`, `KnownProvider`           ← `indusagi/ai`
+ *
+ * The conductor never re-declares these; it composes them.
+ */
+import type { AgentMessage, AgentTool, ThinkingLevel } from "indusagi/agent";
+import type { KnownProvider, Model, Usage } from "indusagi/ai";
+/** Re-exported framework vocabulary that conductor consumers routinely need. */
+export type { AgentMessage, AgentTool, ThinkingLevel, Model, Usage, KnownProvider };
+/**
+ * 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 {@link SessionConductor.abort}.
+ *   - `overflow`    — the context window was exceeded and could not be condensed.
+ */
+export type FaultKind = "model" | "tool" | "persistence" | "aborted" | "overflow";
+/**
+ * A typed, discriminated failure value emitted on the {@link SessionSignal}
+ * stream and attached to faulted states.
+ *
+ * The `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.
+ */
+export interface ConductorFault {
+    /** Failure category — the discriminant consumers switch on. */
+    readonly kind: FaultKind;
+    /** Human-readable, single-line summary of what went wrong. */
+    readonly message: string;
+    /** Underlying error or structured detail, if any. */
+    readonly cause?: unknown;
+}
+/**
+ * Construct a {@link 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
+ */
+export declare function conductorFault(kind: FaultKind, message: string, cause?: unknown): ConductorFault;
+/**
+ * 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.
+ *
+ *   - `prompt`    — 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.
+ *   - `text`      — a chunk of assistant answer text streamed in.
+ *   - `thinking`  — a chunk of reasoning/thinking text streamed in.
+ *   - `tool_start`— a tool invocation began (correlate by `id`).
+ *   - `tool_end`  — a tool invocation finished (`ok` = no error).
+ *   - `turn_end`  — the assistant turn settled; `usage` reports token spend.
+ *   - `persisted` — the latest node was committed to the transcript (`entryId`).
+ *   - `compacted` — the transcript was condensed to fit the context window.
+ *   - `fault`     — a typed {@link ConductorFault} occurred.
+ *   - `queue`     — the pending-input queue changed; `count` is its new depth.
+ *   - `idle`      — the conductor has no in-flight work and is ready for input.
+ */
+export type SessionSignal = {
+    readonly kind: "prompt";
+    readonly text: string;
+} | {
+    readonly kind: "text";
+    readonly delta: string;
+} | {
+    readonly kind: "thinking";
+    readonly delta: string;
+} | {
+    readonly kind: "tool_start";
+    readonly id: string;
+    readonly name: string;
+} | {
+    readonly kind: "tool_end";
+    readonly id: string;
+    readonly ok: boolean;
+} | {
+    readonly kind: "turn_end";
+    readonly usage: Usage;
+} | {
+    readonly kind: "persisted";
+    readonly entryId: string;
+} | {
+    readonly kind: "compacted";
+} | {
+    readonly kind: "fault";
+    readonly fault: ConductorFault;
+} | {
+    readonly kind: "queue";
+    readonly count: number;
+} | {
+    readonly kind: "idle";
+};
+/** The discriminant literals of {@link SessionSignal}, for filtering/logging. */
+export type SignalKind = SessionSignal["kind"];
+/** Extract a single member of {@link SessionSignal} by its `kind`. */
+export type SignalOf<K extends SignalKind> = Extract<SessionSignal, {
+    kind: K;
+}>;
+/** A subscriber callback registered with {@link SessionConductor.subscribe}. */
+export type SignalHandler = (signal: SessionSignal) => void;
+/**
+ * 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.
+ */
+export declare const TRANSCRIPT_SCHEMA: "indus/transcript@1";
+/** The literal type of {@link TRANSCRIPT_SCHEMA}. */
+export type TranscriptSchema = typeof TRANSCRIPT_SCHEMA;
+/**
+ * The conversational role a {@link 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.
+ */
+export type TranscriptRole = "user" | "assistant" | "tool" | "system" | "condense" | "note";
+/**
+ * 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: null`), and the active leaf is tracked separately in
+ * {@link SessionHead}. Branching is moving the head to an earlier node; the next
+ * append becomes that node's child. `content` holds the framework
+ * {@link 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.
+ */
+export interface TranscriptEntry {
+    /** Stable unique node id (e.g. a ULID). */
+    readonly id: string;
+    /** Parent node id, or `null` for the transcript root. */
+    readonly parent: string | null;
+    /** Conversational role of this node. */
+    readonly role: TranscriptRole;
+    /** The framework message payload this node persists. */
+    readonly content: AgentMessage;
+    /** ISO-8601 creation timestamp. */
+    readonly createdAt: string;
+    /** Optional, non-LLM annotations keyed by name. */
+    readonly meta?: Readonly<Record<string, unknown>>;
+}
+/**
+ * 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.
+ * `null` means an empty transcript (no nodes yet).
+ */
+export interface SessionHead {
+    /** Stable identifier of the session this transcript belongs to. */
+    readonly sessionId: string;
+    /** Id of the active leaf node, or `null` for an empty transcript. */
+    readonly leaf: string | null;
+}
+/**
+ * A lightweight, resolved reference to one model card in the catalog.
+ *
+ * This is the *display/identity* projection of a framework {@link 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.
+ */
+export interface ModelCardRef {
+    /** Canonical `"provider/modelId"` identifier (the catalog key). */
+    readonly id: string;
+    /** Owning provider. */
+    readonly provider: KnownProvider | string;
+    /** Provider-scoped model id (e.g. `"claude-sonnet-4"`). */
+    readonly modelId: string;
+    /** Human-readable display name. */
+    readonly name: string;
+    /** Whether this model exposes a reasoning/thinking budget. */
+    readonly reasoning: boolean;
+}
+/**
+ * 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 are optional so an empty query means "the default candidate".
+ */
+export interface MatchQuery {
+    /** Free-form selector: an id, an alias, or a glob pattern. */
+    readonly pattern?: string;
+    /** Restrict candidates to this provider. */
+    readonly provider?: KnownProvider | string;
+    /** Pin a specific provider-scoped model id (used with {@link provider}). */
+    readonly modelId?: string;
+    /** Require reasoning/thinking support. */
+    readonly reasoning?: boolean;
+    /** Require image input support. */
+    readonly supportsImageInput?: boolean;
+}
+/**
+ * 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 {@link ConductorFault}.
+ */
+export type ConductorPhase = "idle" | "streaming" | "tooling" | "condensing" | "faulted";
+/**
+ * An immutable snapshot of the conductor's observable state.
+ *
+ * Returned by {@link SessionConductor.snapshot} and resolved by
+ * {@link SessionConductor.submit}. It is a value, not a live view: every field
+ * is read-only and the object reflects the instant it was taken. Re-read with a
+ * fresh `snapshot()` to observe later changes.
+ */
+export interface ConductorState {
+    /** Coarse lifecycle phase at snapshot time. */
+    readonly phase: ConductorPhase;
+    /** The active transcript head (session id + current leaf). */
+    readonly head: SessionHead;
+    /** Cumulative token/cost spend across the session so far. */
+    readonly usage: Usage;
+    /** Canonical id of the model currently bound to the session. */
+    readonly modelId: string;
+    /** The fault from the most recent turn, when {@link phase} is `"faulted"`. */
+    readonly fault?: ConductorFault;
+}
+/**
+ * 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 ends.
+ *
+ * The conductor enqueues input under one of these modes when {@link SessionConductor.submit}
+ * is called while a turn is in flight, then drains the queue in order.
+ */
+export type QueueMode = "steer" | "followUp";
+/**
+ * One entry in the conductor's pending-input queue: the {@link QueueMode} it was
+ * filed under and the raw user `text`. Surfaced by
+ * {@link SessionConductor.pendingInputs} so a UI can render what is waiting.
+ */
+export interface QueuedInput {
+    /** How this input will rejoin the conversation when drained. */
+    readonly mode: QueueMode;
+    /** The raw user message text held for a later turn. */
+    readonly text: string;
+}
+/**
+ * A point-in-time tally of the active session: message counts by role, tool
+ * activity, cumulative token spend, and total cost. Computed by
+ * {@link SessionConductor.stats} from the live message list plus the running
+ * usage carried on {@link ConductorState}.
+ */
+export interface SessionStats {
+    /** Identifier of the session these figures describe. */
+    readonly sessionId: string;
+    /** Number of user-role messages in the active branch. */
+    readonly userMessages: number;
+    /** Number of assistant-role messages in the active branch. */
+    readonly assistantMessages: number;
+    /** Number of tool invocations the assistant issued. */
+    readonly toolCalls: number;
+    /** Number of tool-result messages produced in reply. */
+    readonly toolResults: number;
+    /** Total message count across all roles. */
+    readonly totalMessages: number;
+    /** Cumulative token spend, broken out by category and totalled. */
+    readonly tokens: {
+        readonly input: number;
+        readonly output: number;
+        readonly cacheRead: number;
+        readonly cacheWrite: number;
+        readonly total: number;
+    };
+    /** Cumulative monetary cost of the session so far. */
+    readonly cost: number;
+}
+/** Options for {@link SessionConductor.executeBash}. */
+export interface ExecuteBashOptions {
+    /**
+     * When `true`, the command's output is *not* recorded as a transcript note,
+     * so it never re-enters the agent's context. Defaults to `false`.
+     */
+    readonly excludeFromContext?: boolean;
+}
+/** The settled result of {@link SessionConductor.executeBash}. */
+export interface BashOutcome {
+    /** Combined stdout + stderr of the command. */
+    readonly output: string;
+    /** Process exit code (`0` on success; non-zero, or `1` on a thrown error). */
+    readonly exitCode: number;
+}
+/**
+ * Options that configure a {@link SessionConductor} at assembly time.
+ *
+ * Only {@link 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.
+ */
+export interface SessionConductorOptions {
+    /** Canonical id of the model to bind the session to. */
+    readonly modelId: string;
+    /** Initial system prompt seeding the conversation. */
+    readonly system?: string;
+    /** Tools made available to the agent for this session. */
+    readonly tools?: AgentTool[];
+    /** Initial reasoning effort for models that support it. */
+    readonly thinking?: ThinkingLevel;
+    /** Working directory the session is scoped to (defaults to process cwd). */
+    readonly workspace?: string;
+    /**
+     * Directory to persist the transcript into. When set, the conductor backs its
+     * {@link TranscriptStore} with a filesystem backend rooted here (one
+     * `<sessionId>.ndjson` per session) so the conversation survives the process
+     * and can be resumed. Absent (or when a `store` dep is injected) keeps the
+     * default in-memory store — nothing is written to disk.
+     */
+    readonly sessionsDir?: string;
+    /** Condense the transcript automatically when it nears the window (default on). */
+    readonly autoCompact?: boolean;
+    /**
+     * 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 (e.g.
+     * `openai-codex`) can be refreshed and providers with no env-var mapping still
+     * authenticate. Returning `undefined` lets the framework fall back to its own
+     * environment lookup. May be sync or async.
+     */
+    readonly getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
+}
+/**
+ * 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 {@link SessionSignal} stream, abort the in-flight turn, read an immutable
+ * {@link ConductorState} snapshot, resume a persisted session, and optionally
+ * rotate the active model. This is the surface all three run modes drive.
+ */
+export interface SessionConductor {
+    /**
+     * Submit user input as a new turn and run the agent to settle.
+     *
+     * Streams {@link SessionSignal}s to subscribers as the turn progresses and
+     * resolves to the immutable {@link ConductorState} once the turn settles
+     * (success or fault).
+     *
+     * When a turn is already in flight the input is **not** dropped: it is handed
+     * to {@link 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.
+     *
+     * @param input the user message text for this turn
+     */
+    submit(input: string): Promise<ConductorState>;
+    /**
+     * Queue an input to run as a future turn. Used directly, or reached via
+     * {@link submit} when the conductor is busy. Queued items drain in order after
+     * the active turn settles, each running as its own turn. Emits a
+     * `{ kind: "queue" }` signal so a UI can reflect the new depth.
+     *
+     * @param input the user message text to hold for a later turn
+     * @param mode  how it rejoins the conversation when drained (default `"followUp"`)
+     */
+    enqueue(input: string, mode?: QueueMode): void;
+    /** How many inputs are currently waiting in the pending-input queue. */
+    pendingCount(): number;
+    /** A read-only view of the queued inputs, oldest first. */
+    pendingInputs(): readonly QueuedInput[];
+    /** Discard every queued input. Emits a `{ kind: "queue" }` signal. */
+    clearQueue(): void;
+    /**
+     * Remove and return the text of the most-recently queued input, or `undefined`
+     * when the queue is empty. Lets a UI pop the last entry back into its prompt.
+     */
+    dequeueLast(): string | undefined;
+    /**
+     * 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 array is the
+     * current contents at call time; re-read to observe later turns.
+     */
+    messages(): readonly AgentMessage[];
+    /**
+     * The full framework {@link Model} object currently bound to the session, or
+     * `undefined` when none could be resolved. Tracks the active selection across
+     * {@link selectModel}/{@link cycleModel} changes.
+     */
+    model(): Model<any> | undefined;
+    /** Whether a turn is currently in flight (guards re-entrant submit). */
+    isBusy(): boolean;
+    /**
+     * The model catalog entries a picker lists, best-first. Derived from the
+     * configured model matcher; returns `[]` when no matcher is wired in.
+     */
+    availableModels(): ModelCardRef[];
+    /**
+     * Bind a model by canonical id for subsequent turns. The companion of
+     * {@link cycleModel}; both route through the same selection path.
+     *
+     * @param id canonical id of the model to switch to
+     */
+    selectModel(id: string): void;
+    /**
+     * 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.
+     */
+    condense(): Promise<void>;
+    /**
+     * 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.
+     *
+     * @param entryId the transcript node to branch from
+     */
+    fork(entryId: string): Promise<void>;
+    /**
+     * 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.
+     *
+     * @param nodeId the transcript node to make the active leaf
+     */
+    navigateTree(nodeId: string): Promise<void>;
+    /**
+     * 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 throws: a spawn/exec failure resolves to a non-zero {@link BashOutcome}.
+     *
+     * @param command the shell command to execute
+     * @param opts    execution options
+     */
+    executeBash(command: string, opts?: ExecuteBashOptions): Promise<BashOutcome>;
+    /** A point-in-time {@link SessionStats} tally for the active session. */
+    stats(): SessionStats;
+    /** The reasoning effort currently applied to the session. */
+    thinkingLevel(): ThinkingLevel;
+    /**
+     * 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.
+     *
+     * @param level the reasoning effort to apply
+     */
+    setThinkingLevel(level: ThinkingLevel): void;
+    /**
+     * Advance the reasoning effort to the next level in the cycle, applying it, and
+     * return the newly-selected level.
+     */
+    cycleThinkingLevel(): ThinkingLevel;
+    /** The human-readable session name, or `undefined` when none is set. */
+    sessionName(): string | undefined;
+    /**
+     * Assign a human-readable name to the session.
+     *
+     * @param name the display name to store
+     */
+    setSessionName(name: string): void;
+    /**
+     * Register a handler for the {@link SessionSignal} stream.
+     *
+     * @param handler invoked for every emitted signal
+     * @returns an unsubscribe function that removes the handler
+     */
+    subscribe(handler: SignalHandler): () => void;
+    /** Cancel the in-flight turn, if any; emits an `aborted` fault signal. */
+    abort(): void;
+    /** Read an immutable snapshot of the current {@link ConductorState}. */
+    snapshot(): ConductorState;
+    /**
+     * Restore a previously persisted session, replacing the current transcript
+     * and rebinding the agent to the restored model/leaf.
+     *
+     * @param sessionId the persisted session to resume
+     */
+    resume(sessionId: string): Promise<void>;
+    /**
+     * 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.
+     */
+    newSession(): Promise<void>;
+    /**
+     * Rotate the active model for subsequent turns. Optional: not every assembly
+     * supports mid-session model changes.
+     *
+     * @param id canonical id of the model to switch to
+     */
+    cycleModel?(id: string): void;
+}

package/dist/types/conductor/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Conductor subsystem — public barrel.
+ *
+ * Re-exports the FROZEN Phase-2 contract: the product-level signal stream
+ * ({@link SessionSignal}), the typed fault model ({@link ConductorFault} +
+ * {@link conductorFault}), the on-disk transcript schema ({@link TranscriptEntry},
+ * {@link SessionHead}, {@link TRANSCRIPT_SCHEMA}), the model catalog/matcher
+ * reference types ({@link ModelCardRef}, {@link MatchQuery}), the immutable
+ * state snapshot ({@link ConductorState}), and the {@link SessionConductor}
+ * interface plus its {@link SessionConductorOptions}.
+ *
+ * Behavior modules (signal hub, transcript store, model catalog/matcher,
+ * conductor factory, the conductor itself) are added to this barrel as they
+ * land; consumers import the conductor surface from `src/conductor` rather than
+ * reaching into individual modules.
+ */
+export type { FaultKind, ConductorFault, SessionSignal, SignalKind, SignalOf, SignalHandler, TranscriptSchema, TranscriptRole, TranscriptEntry, SessionHead, ModelCardRef, MatchQuery, ConductorPhase, ConductorState, QueueMode, QueuedInput, SessionStats, ExecuteBashOptions, BashOutcome, SessionConductor, SessionConductorOptions, AgentMessage, AgentTool, ThinkingLevel, Model, Usage, KnownProvider, } from "./contract";
+export { conductorFault, TRANSCRIPT_SCHEMA } from "./contract";
+export { createSessionConductor, reduceState, noopCondense, type AgentLike, type ConductorDeps, type CondenseFn, type RetryPolicy, } from "./conductor";
+export { SignalHub, translateAgentEvent, type SignalHubOptions } from "./signal-hub";
+export { ModelCatalog, ModelMatcher, canonicalId, toCardRef, type CatalogCard, type CatalogSource, type ResolveInput, } from "./catalog";
+export { TranscriptStore, memoryBackend, fsBackend, replay, type TranscriptBackend, type TranscriptState, type TranscriptClock, type TranscriptStoreOptions, } from "./transcript-store";
+export { parseSkillInvocation, type SkillInvocation } from "./skill-parse";

package/dist/types/conductor/signal-hub/hub.d.ts

@@ -0,0 +1,83 @@
+/**
+ * SignalHub — the conductor's product-event fan-out.
+ *
+ * A tiny, synchronous publish/subscribe bus over the {@link SessionSignal}
+ * stream. The conductor owns one hub per session: behavior modules (the turn
+ * loop, the persistence layer, the auto-condense pass) push signals in via
+ * {@link SignalHub.emit}, and every registered consumer handler receives them in
+ * registration order.
+ *
+ * Design (deliberately the conductor's own, not the framework's loop emitter):
+ *   - Handlers live in an insertion-ordered `Set`, so registration order is the
+ *     delivery order and duplicate handler identities collapse to one slot.
+ *   - {@link SignalHub.subscribe} returns an unsubscribe thunk; calling it (even
+ *     during a dispatch, even more than once) is safe and idempotent.
+ *   - {@link SignalHub.emit} fans out over a *snapshot* of the handler set, so a
+ *     handler that subscribes or unsubscribes mid-dispatch never corrupts the
+ *     in-progress iteration — the change takes effect on the next emit.
+ *   - A throwing handler is isolated: its error is routed to the optional
+ *     {@link SignalHubOptions.onHandlerError} sink and the remaining handlers
+ *     still run. One bad consumer never silences the others.
+ *
+ * The hub is transport-agnostic: it knows nothing about the framework `Agent`,
+ * persistence, or how signals are produced. The {@link module:translate}
+ * translator is what turns raw framework events into the {@link SessionSignal}s
+ * that flow through here.
+ */
+import type { SessionSignal, SignalHandler } from "../contract";
+/** Tuning hooks for a {@link SignalHub}. All optional. */
+export interface SignalHubOptions {
+    /**
+     * Invoked when a subscribed handler throws during {@link SignalHub.emit}.
+     *
+     * Lets the owner observe/log faults in consumer code without aborting the
+     * fan-out. If omitted, handler errors are swallowed so a misbehaving consumer
+     * cannot break signal delivery to the others. This sink is itself guarded —
+     * if it throws, the throw is ignored.
+     *
+     * @param error   the value the handler threw
+     * @param signal  the signal that was being delivered when it threw
+     */
+    readonly onHandlerError?: (error: unknown, signal: SessionSignal) => void;
+}
+/**
+ * A synchronous fan-out bus for {@link SessionSignal}s.
+ *
+ * Construct one per session; subscribe consumers; emit signals. Not a framework
+ * type and not wired to one — purely the conductor's own event surface.
+ */
+export declare class SignalHub {
+    /** Insertion-ordered live set of subscribed handlers. */
+    private readonly handlers;
+    private readonly onHandlerError?;
+    constructor(options?: SignalHubOptions);
+    /**
+     * Register a handler to receive every subsequently emitted signal.
+     *
+     * Registering the same function reference twice is a no-op (the `Set`
+     * collapses it). The returned thunk removes the handler; it is idempotent and
+     * safe to call during a dispatch.
+     *
+     * @param handler the consumer callback
+     * @returns an unsubscribe function
+     */
+    subscribe(handler: SignalHandler): () => void;
+    /**
+     * Fan a signal out to every currently-subscribed handler, in registration
+     * order.
+     *
+     * Iterates a snapshot of the handler set, so subscribe/unsubscribe performed
+     * by a handler mid-dispatch affects only later emits. A throwing handler is
+     * isolated via {@link SignalHubOptions.onHandlerError}; the remaining handlers
+     * still run.
+     *
+     * @param signal the signal to deliver
+     */
+    emit(signal: SessionSignal): void;
+    /** Number of currently-subscribed handlers. */
+    get size(): number;
+    /** Remove every handler. Subsequent {@link emit} calls deliver to no one. */
+    clear(): void;
+    /** Route a handler error to the sink, guarding the sink itself. */
+    private report;
+}

package/dist/types/conductor/signal-hub/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * signal-hub — the conductor's product-event hub + framework-event translator.
+ *
+ * Two cooperating pieces sitting between the framework `Agent` loop and the
+ * conductor's consumers:
+ *
+ *   - {@link SignalHub} — a synchronous, insertion-ordered fan-out bus over the
+ *     {@link SessionSignal} stream. Behavior modules emit into it; UI/print/RPC
+ *     consumers subscribe to it.
+ *   - {@link translateAgentEvent} — the pure projection that turns a single
+ *     framework {@link AgentEvent} into the zero-or-more {@link SessionSignal}s
+ *     that flow through the hub. {@link TRANSLATOR_TABLE} is the underlying,
+ *     exhaustiveness-checked dispatch table (exported for inspection/testing).
+ *
+ * Typical wiring: subscribe the framework loop, run each raw event through
+ * `translateAgentEvent`, and `emit` the results on a `SignalHub`.
+ */
+export { SignalHub, type SignalHubOptions } from "./hub";
+export { translateAgentEvent, TRANSLATOR_TABLE } from "./translate";