indusagi 0.12.32 → 0.12.33

package/dist/types/runtime/ledger/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Ledger — the run event hub and snapshot accumulator.
+ *
+ * {@link RunLedger} fans published {@link import("../contract").RunEvent}s out to
+ * subscribers; {@link SnapshotAccumulator} folds the snapshot-bearing ones into a
+ * single readable latest state. Together they are the seam between the pure loop
+ * and any host that renders or persists progress.
+ */
+export { RunLedger } from "./bus";
+export type { RunEventHandler, Unsubscribe } from "./bus";
+export { SnapshotAccumulator } from "./accumulator";

package/dist/types/runtime/memory/compactor.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Context condensation.
+ *
+ * When a conversation's estimated footprint approaches the model's window, the
+ * oldest stretch of history is replaced by a single dense summary turn while a
+ * verbatim tail of recent turns is preserved. This module decides *whether* to
+ * condense ({@link shouldCompact}), *where* the boundary falls without severing
+ * a tool call from its result ({@link findCutPoint}), *how* the prefix is
+ * distilled into one turn ({@link summarize}), and finally stitches the two
+ * together ({@link compact}).
+ */
+import type { ModelCard, Turn } from "../../llmgateway/contract";
+import type { CompactionPolicy } from "../contract";
+import type { ModelInvoker } from "../contract";
+/**
+ * Decide whether the history has grown enough to warrant condensation.
+ *
+ * Compares the estimated token footprint against `triggerRatio` of the model's
+ * context window. Returns `false` for a non-positive window (nothing meaningful
+ * to compare against) so callers never condense on a misconfigured card.
+ */
+export declare function shouldCompact(messages: readonly Turn[], model: ModelCard, cfg?: CompactionPolicy): boolean;
+/**
+ * Locate the boundary index separating the prefix to condense from the tail to
+ * preserve.
+ *
+ * The tail starts at `length - keepRecent`, clamped into range. The boundary is
+ * then nudged *forward* (shrinking the tail, enlarging the condensed prefix)
+ * while the candidate first-preserved turn carries tool results, so a
+ * `tool_call`/`tool_result` pair is never split across the boundary. Returns the
+ * index of the first turn that survives verbatim: `0` means nothing is
+ * condensed; `length` means everything is.
+ */
+export declare function findCutPoint(messages: readonly Turn[], keepRecent: number): number;
+/**
+ * Distill a stretch of history into one synthetic turn.
+ *
+ * Builds a conversation whose system preamble is the {@link DISTILL_INSTRUCTION}
+ * and whose single user turn is the rendered transcript of `messages`, invokes
+ * the injected model, and folds the streamed response into a `user`-role turn.
+ * Filing the summary under the `user` role keeps it valid input for the next
+ * invocation regardless of which provider follows, and marks it visibly with
+ * {@link SUMMARY_HEADING}.
+ */
+export declare function summarize(messages: readonly Turn[], invoke: ModelInvoker): Promise<Turn>;
+/**
+ * Condense a history: replace its older prefix with a single distilled turn and
+ * keep the recent tail verbatim.
+ *
+ * Resolves the policy (falling back to {@link DEFAULT_POLICY}), finds the
+ * tool-safe cut point, and — when there is a prefix worth condensing — invokes
+ * {@link summarize} on it. The result is `[summary, ...tail]`. When the cut
+ * point is `0` (nothing old enough to drop) the original history is returned
+ * unchanged, so `compact` is safe to call unconditionally.
+ */
+export declare function compact(messages: readonly Turn[], model: ModelCard, cfg: CompactionPolicy | undefined, invoke: ModelInvoker): Promise<readonly Turn[]>;

package/dist/types/runtime/memory/estimate.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Cheap context-size estimation.
+ *
+ * Before any model invocation the loop needs a rough sense of how much of the
+ * window the accumulated history occupies. A real tokenizer is provider-specific
+ * and costly to run on every turn, so this module uses a coarse heuristic: it
+ * serializes each turn's textual content and divides the character count by an
+ * average characters-per-token ratio. The estimate is intentionally an
+ * over-approximation in spirit — it errs toward triggering condensation a little
+ * early rather than overflowing the window.
+ */
+import type { Turn } from "../../llmgateway/contract";
+/**
+ * Estimate the token footprint of an entire history.
+ *
+ * Sums the character counts of every block across every turn, converts to
+ * tokens via {@link CHARS_PER_TOKEN}, and adds a small fixed surcharge per turn
+ * for role/message framing. The result is a non-negative integer suitable for
+ * comparison against a model's context window.
+ */
+export declare function estimateContextTokens(messages: readonly Turn[]): number;

package/dist/types/runtime/memory/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Context compaction engine — public surface.
+ *
+ * The runtime reaches condensation through this barrel: a cheap token estimator
+ * and the four-part condensation flow (decide, locate, distill, stitch).
+ */
+export { estimateContextTokens } from "./estimate";
+export { shouldCompact, findCutPoint, summarize, compact, } from "./compactor";

package/dist/types/runtime/runtime.test.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Behavioral-parity tests for the agent runtime.
+ *
+ * Every test drives a real {@link createAgent} but injects a *scripted*
+ * {@link ModelInvoker} so no network is touched: each model turn is a
+ * pre-recorded list of {@link Emission}s replayed as a {@link Channel}. Tools are
+ * fulfilled by a tiny in-memory {@link ToolBox}. The four scenarios cover the
+ * load-bearing behaviours of the conductor:
+ *
+ *   1. a multi-turn tool loop settling cleanly;
+ *   2. an abort mid-stream faulting with kind `aborted`;
+ *   3. branch/resume reconstructing a persisted message path;
+ *   4. compaction firing under a tiny trigger ratio and shrinking history.
+ */
+export {};

package/dist/types/runtime/store/dag.d.ts

@@ -0,0 +1,72 @@
+/**
+ * In-memory session DAG.
+ *
+ * {@link SessionGraph} holds the content-addressed nodes of one session and a
+ * moving head. Appending a turn chains a fresh node onto the current head and
+ * advances the head to it; branching points the head back at an older node so a
+ * subsequent append forks a new line of history. The linear context handed to a
+ * model is the path from a chosen leaf back to the root, reversed into
+ * root→leaf order.
+ */
+import type { Turn } from "../../llmgateway/contract";
+import type { SessionNode } from "../contract";
+/** Source of wall-clock timestamps, injectable for deterministic tests. */
+export type Clock = () => number;
+/**
+ * A mutable, branchable graph of {@link SessionNode}s for a single session.
+ *
+ * Nodes are immutable once added and keyed by their content hash. The graph
+ * tracks a `head` — the node a fresh {@link SessionGraph.append} will chain
+ * onto — which starts unset for an empty session.
+ */
+export declare class SessionGraph {
+    readonly sessionId: string;
+    private readonly nodes;
+    private head;
+    private readonly clock;
+    constructor(sessionId: string, clock?: Clock);
+    /**
+     * Rebuild a graph from previously persisted nodes plus its leaf pointer.
+     *
+     * Nodes may arrive in any order; parents are not required to precede children.
+     * The provided `leaf` becomes the head, or the loner node if exactly one
+     * exists and no leaf is named.
+     */
+    static hydrate(sessionId: string, nodes: readonly SessionNode[], leaf: string | null, clock?: Clock): SessionGraph;
+    /** The id of the node a fresh append will chain onto, or `null` if empty. */
+    get leaf(): string | null;
+    /** Total number of nodes across every branch. */
+    get size(): number;
+    /** Look up a node by its content hash. */
+    get(nodeId: string): SessionNode | undefined;
+    /** Every node in the graph, in insertion order. */
+    all(): SessionNode[];
+    /**
+     * Chain a new turn onto the current head and advance the head to it.
+     *
+     * Returns the freshly minted node. If the content hash collides with an
+     * existing node (identical lineage, turn, and timestamp), the head simply
+     * advances to that node without duplicating it.
+     */
+    append(turn: Turn): SessionNode;
+    /**
+     * Move the head to an existing node so the next append forks from there.
+     *
+     * Throws if `nodeId` is not part of this graph.
+     */
+    branchFrom(nodeId: string): SessionNode;
+    /**
+     * Resolve the linear context ending at `leaf`, ordered root→leaf.
+     *
+     * Walks parent pointers from the leaf back to a root, then reverses. Throws if
+     * `leaf` is unknown or the chain references a missing parent.
+     */
+    pathTo(leaf: string): Turn[];
+    /**
+     * Adopt `leaf` as the head and return its full root→leaf turn context.
+     *
+     * Convenience for re-entering a session at a chosen tip: combines {@link
+     * branchFrom} (positioning) with {@link pathTo} (context).
+     */
+    resume(leaf: string): Turn[];
+}

package/dist/types/runtime/store/hash.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Content addressing for session nodes.
+ *
+ * A node's identity is derived purely from its content: the parent hash it
+ * chains onto, the turn it carries, and its creation time. Two nodes built from
+ * identical lineage and content collapse to the same id, which is what makes the
+ * session history a content-addressed DAG rather than a mutable list.
+ */
+import type { Turn } from "../../llmgateway/contract";
+/**
+ * Compute the content hash that serves as a node's id.
+ *
+ * The hash is a SHA-256 over a canonical encoding of the parent id, the turn,
+ * and the creation timestamp, rendered as hex and truncated to {@link
+ * HASH_WIDTH} characters. A `null` parent (a root) is encoded distinctly from
+ * any real hash so roots never collide with chained nodes.
+ */
+export declare function hashNode(parent: string | null, turn: Turn, createdAt: number): string;

package/dist/types/runtime/store/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Session store — public surface.
+ *
+ * A content-addressed, branchable session DAG with a JSONL-on-disk backing.
+ * `hashNode` derives node ids from content; `SessionGraph` is the in-memory DAG
+ * (append / branch / path / resume); `SessionStore` persists and reloads
+ * sessions, applying a migrator pipeline on load.
+ */
+export { hashNode } from "./hash";
+export { SessionGraph } from "./dag";
+export type { Clock } from "./dag";
+export { SessionStore } from "./persist";

package/dist/types/runtime/store/persist.d.ts

@@ -0,0 +1,49 @@
+/**
+ * On-disk session store.
+ *
+ * Each session lives in its own append-only JSONL file under a sessions root.
+ * Every line is one record: either a node (the full content-addressed {@link
+ * SessionNode}) or a head marker naming the current leaf. Appending a node
+ * writes its record and a fresh head marker; loading a session replays the file,
+ * runs each raw record through the {@link Migrator} pipeline, and reconstructs
+ * an in-memory {@link SessionGraph}.
+ */
+import type { Migrator, SessionNode } from "../contract";
+import { SessionGraph } from "./dag";
+/**
+ * A filesystem-backed store of branchable session DAGs.
+ *
+ * The store owns a root directory; sessions are files within it. A migrator
+ * pipeline is applied to every record on load so older on-disk schemas upgrade
+ * forward transparently.
+ */
+export declare class SessionStore {
+    private readonly root;
+    private readonly migrators;
+    constructor(root: string, migrators?: readonly Migrator[]);
+    /** Absolute path of a session's JSONL file. */
+    private fileFor;
+    /** Ensure the sessions root directory exists. */
+    private ensureRoot;
+    /**
+     * Append one node to a session and advance its persisted head.
+     *
+     * Writes the node record followed by a head record pointing at it, so the last
+     * head marker in the file always names the live leaf.
+     */
+    appendNode(sessionId: string, node: SessionNode): Promise<void>;
+    /**
+     * Load a session from disk into a {@link SessionGraph}.
+     *
+     * Replays every line, upgrades it through the migrator pipeline, collects the
+     * node records, and tracks the last head marker as the leaf. Blank lines are
+     * skipped. A missing session file yields an empty graph.
+     */
+    loadSession(sessionId: string): Promise<SessionGraph>;
+    /**
+     * List the ids of every session present in the store.
+     *
+     * Returns an empty list if the root does not yet exist.
+     */
+    listSessions(): Promise<string[]>;
+}

package/dist/types/runtime/turn/driver.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The single-model-turn driver.
+ *
+ * A {@link Channel} is the raw streaming surface a {@link ModelInvoker} hands
+ * back: an async iterable of provider-neutral {@link Emission}s terminated by a
+ * `done` or `error`. {@link driveTurn} adapts that low-level stream into the
+ * {@link Signal} vocabulary the run state machine consumes. It is the thin,
+ * stateless seam between "bytes off the wire" and "inputs the reducer
+ * understands": every emission becomes an `emission` signal, the exhausted
+ * stream becomes a single terminal `stream_end`, and any thrown failure becomes
+ * a `fault` carrying a normalized {@link RunError}.
+ *
+ * The driver holds no run state and performs no folding — it only translates
+ * and forwards, leaving interpretation to the pure reducer downstream.
+ */
+import type { Channel } from "../../llmgateway/contract";
+import type { Signal } from "../contract";
+/**
+ * Drive one model invocation's {@link Channel} to completion as a stream of
+ * {@link Signal}s.
+ *
+ * Each {@link Emission} pulled from the channel is yielded as an `emission`
+ * signal in arrival order. When the channel is exhausted cleanly, a single
+ * terminal `stream_end` signal is yielded. If iterating the channel throws —
+ * including a {@link GatewayError} surfaced by the underlying connector — a
+ * `fault` signal carrying the mapped {@link RunError} is yielded instead, and no
+ * `stream_end` follows.
+ *
+ * @param channel The streaming emissions from a model invocation.
+ * @returns An async generator of the signals that advance the run.
+ */
+export declare function driveTurn(channel: Channel): AsyncGenerator<Signal>;

package/dist/types/runtime/turn/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Turn driver — public surface.
+ *
+ * Re-exports {@link driveTurn}, the adapter that converts a model invocation's
+ * {@link import("../../llmgateway/contract").Channel} into the run's
+ * {@link import("../contract").Signal} stream.
+ */
+export { driveTurn } from "./driver";

package/dist/types/runtime/wire/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Wire projection — public surface.
+ *
+ * Turns a runtime message list plus its {@link AgentConfig} into the gateway's
+ * provider-neutral {@link Conversation}. The registry of per-role projectors is
+ * exported for inspection and extension; most callers only need
+ * {@link buildConversation}.
+ */
+export type { ProjectionContext, Projector } from "./projectors";
+export { PROJECTORS, buildConversation } from "./projectors";

package/dist/types/runtime/wire/projectors.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Wire projection — runtime session messages → a gateway {@link Conversation}.
+ *
+ * The runtime keeps history as a flat list of {@link Turn}s. Before a model is
+ * invoked, that list plus the static {@link AgentConfig} must be assembled into
+ * the provider-neutral request payload the gateway accepts: a `system`
+ * preamble, the ordered turns, and the tool catalog.
+ *
+ * The assembly is table-driven. Each {@link Projector} owns exactly one turn
+ * role and decides how that role's turns appear on the wire. A registry — a
+ * `Map` keyed by role — dispatches each message to its projector. New roles are
+ * added by registering a projector, never by extending a branch ladder.
+ */
+import type { Conversation, Turn } from "../../llmgateway/contract";
+import type { AgentConfig } from "../contract";
+/**
+ * The ambient inputs a projector may consult beyond the turn itself.
+ *
+ * Projectors stay pure: they read from this context but never mutate it and
+ * never perform I/O. The context is built once per assembly and shared across
+ * every projector invocation.
+ */
+export interface ProjectionContext {
+    /** The static run setup driving this assembly. */
+    readonly config: AgentConfig;
+}
+/**
+ * Projects a single source turn of one role into the turns it contributes to
+ * the outgoing conversation.
+ *
+ * Returning a list (rather than a single turn) keeps the contract flexible: a
+ * role may expand into several wire turns or collapse to none, without changing
+ * the registry shape.
+ */
+export type Projector = (turn: Turn, ctx: ProjectionContext) => readonly Turn[];
+/**
+ * The projector registry: a role → projector table. This is the single
+ * extension point for wire shaping. Lookup is total over the {@link Turn} union
+ * because every role variant has an entry.
+ */
+export declare const PROJECTORS: ReadonlyMap<Turn["role"], Projector>;
+/**
+ * Assembles a provider-neutral {@link Conversation} from a runtime message list
+ * and its {@link AgentConfig}.
+ *
+ * The function is pure: it allocates a fresh conversation and never touches its
+ * inputs. Each message is dispatched through {@link PROJECTORS} by role and the
+ * contributed turns are concatenated in order. The `system` preamble and tool
+ * catalog are sourced from `cfg`. Optional fields are omitted entirely when
+ * empty so the emitted payload matches the gateway's `exactOptionalProperty`
+ * expectations.
+ */
+export declare function buildConversation(messages: readonly Turn[], cfg: AgentConfig): Conversation;

package/dist/types/shell-app/auth-cli/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The auth-cli module — public surface.
+ *
+ * Exposes {@link runAuthCommand}, the entry point for the `auth` subcommand, and
+ * the {@link AuthIO} terminal seam plus the credential-store types so a launcher
+ * (or tests) can wire in their own IO and inspect persisted credentials.
+ */
+export { runAuthCommand } from "./oauth-cli";
+export type { AuthIO, StoredCredential, CredentialStore } from "./oauth-cli";

package/dist/types/shell-app/auth-cli/oauth-cli.d.ts

@@ -0,0 +1,73 @@
+/**
+ * `auth` — a small OAuth helper command.
+ *
+ * A few providers (notably Anthropic and OpenAI) let a user sign in through a
+ * browser authorization-code flow rather than pasting a long-lived API key. This
+ * command drives that flow from the terminal and keeps the resulting tokens in
+ * the profile's credential store. It exposes three subcommands:
+ *
+ *   - `login <provider>`   — start the PKCE authorization-code flow: mint a PKCE
+ *                            pair, print the authorization URL for the user to
+ *                            open, accept the pasted authorization code, trade it
+ *                            for tokens, and persist them.
+ *   - `refresh <provider>` — use a stored refresh token to mint a fresh access
+ *                            token, then write the rotated credentials back.
+ *   - `status [provider]`  — report which providers currently hold stored
+ *                            credentials (and whether each looks expired).
+ *
+ * The PKCE math and the OAuth wire calls are imported from the gateway's
+ * credential layer; this module only owns the terminal choreography, the
+ * credential store on disk, and the help/error text.
+ *
+ * The interactive and network steps are intentionally thin. Reading the pasted
+ * code and the HTTP round-trips are funnelled through the {@link AuthIO} seam and
+ * the gateway helpers respectively, so this file stays deterministic, typed, and
+ * free of any direct `process`/TTY coupling beyond what the caller injects.
+ */
+import type { ProviderId } from "../../llmgateway";
+/**
+ * The minimal terminal surface the command needs. Kept as an interface so the
+ * launcher can hand in a real readline-backed implementation while tests pass a
+ * scripted stub. The command never touches `process.stdout`/`stdin` directly.
+ */
+export interface AuthIO {
+    /** Write one line of normal output (followed by a newline). */
+    print(line: string): void;
+    /** Write one line of diagnostic output (followed by a newline). */
+    warn(line: string): void;
+    /**
+     * Prompt the user and resolve with the line they typed (without the trailing
+     * newline). The `prompt` is shown verbatim before reading. Returns an empty
+     * string if the input stream closed without a line.
+     */
+    ask(prompt: string): Promise<string>;
+}
+/**
+ * One provider's persisted OAuth credentials, plus a little bookkeeping. This is
+ * a superset of {@link OAuthTokens} so a stored record round-trips cleanly
+ * through the gateway helpers.
+ */
+export interface StoredCredential {
+    readonly accessToken: string;
+    readonly refreshToken?: string;
+    /** Absolute epoch-millisecond expiry deadline, if the server supplied one. */
+    readonly expiresAt?: number;
+    /** Epoch-millisecond timestamp of the last successful write. */
+    readonly updatedAt: number;
+}
+/**
+ * The on-disk shape of the credential store: a map from provider id to its
+ * stored credential. Serialized as pretty JSON at {@link Locator.authStorePath}.
+ */
+export interface CredentialStore {
+    readonly providers: Partial<Record<ProviderId, StoredCredential>>;
+}
+/**
+ * Run the `auth` command.
+ *
+ * @param argv The argument slice *after* the `auth` word — e.g. for
+ *   `indusagi auth login anthropic`, pass `["login", "anthropic"]`.
+ * @param io   The terminal seam to read prompts from and write output to.
+ * @returns A process exit code: `0` success, `2` bad usage, `1` runtime failure.
+ */
+export declare function runAuthCommand(argv: readonly string[], io: AuthIO): Promise<number>;

package/dist/types/shell-app/boot/context.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The boot context — the immutable value the {@link import("./pipeline").Stage}
+ * pipeline assembles and the runners consume.
+ *
+ * A {@link BootContext} is everything a runner needs to drive the agent and
+ * nothing it needs to recompute: the parsed {@link Invocation}, the resolved
+ * {@link Settings} and {@link Locator}, the chosen model id and working
+ * directory, a ready-to-call agent factory, the two I/O seams a runner talks to,
+ * and the list of resource teardowns to invoke on exit.
+ *
+ * The context is built up stage by stage. Early stages have only the seed fields
+ * populated; each later stage returns a copy with one more field filled in. By
+ * the time the pipeline finishes, every field is present. Rather than thread a
+ * dozen partially-filled variants through the type system, we model the context
+ * as a single fully-typed shape and rely on the stage order to populate it — the
+ * concrete builder seeds the I/O and invocation fields and lets the stages do
+ * the rest.
+ *
+ * The two I/O fields ({@link BootContext.output}, {@link BootContext.input}) are
+ * deliberately narrow seams, not concrete terminals. The shell app's interactive
+ * surface is out of scope for this phase; a richer terminal UI can later supply
+ * its own implementations of these interfaces without this module changing.
+ */
+import type { Invocation } from "../invocation/parse";
+import type { Locator, Settings } from "../config";
+import type { Agent, AgentDeps } from "../../runtime";
+/**
+ * A line-oriented output sink the runners write user-facing text to.
+ *
+ * Kept to the bare minimum a one-shot or wire runner needs. A production binding
+ * writes to a stream (stdout/stderr); a test binding captures lines in an array.
+ * The interactive runner layers a richer view on top of this seam rather than
+ * widening it.
+ */
+export interface OutputSink {
+    /** Emit one line of normal output (a trailing newline is implied). */
+    write(line: string): void;
+    /** Emit one line of diagnostic/error output, routed apart from normal output. */
+    writeError(line: string): void;
+}
+/**
+ * A line-oriented input source the interactive runner reads prompts from.
+ *
+ * `nextLine` resolves the next line the user supplied, or `null` at end of
+ * input (the stream closed / EOF). The production binding wraps a readline
+ * interface over stdin; a test binding replays a scripted list. Non-interactive
+ * runners (one-shot, wire) take their input from the invocation and never call
+ * this.
+ */
+export interface InputSource {
+    /** Resolve the next input line, or `null` once the source is exhausted. */
+    nextLine(): Promise<string | null>;
+}
+/**
+ * The pair of I/O seams a runner is given. Passed into the boot builder so the
+ * pipeline can thread them onto the context without reaching for `process`.
+ */
+export interface BootIo {
+    /** Where runners send user-facing and diagnostic output. */
+    readonly output: OutputSink;
+    /** Where the interactive runner reads its prompts. */
+    readonly input: InputSource;
+}
+/**
+ * A deferred teardown for a resource opened during boot.
+ *
+ * Stages that open long-lived resources (an MCP server fleet, a session store
+ * handle) push one of these onto {@link BootContext.closables}; the launcher
+ * invokes them in reverse order on shutdown. Each returns a promise so async
+ * teardown can be awaited.
+ */
+export type Closable = () => Promise<void>;
+/**
+ * The fully-assembled startup context.
+ *
+ * Produced by running the boot stages over a seed context. Once assembled, it is
+ * the single argument the runners (one-shot / wire / repl) need: it tells them
+ * what the user asked for, how the agent is wired, and where to read and write.
+ */
+export interface BootContext {
+    /** What the user invoked us with: parsed flags, positionals, prompt, mode. */
+    readonly invocation: Invocation;
+    /** The effective, merged configuration (defaults ← global ← project). */
+    readonly settings: Settings;
+    /** Where on-disk state lives; the single source of path truth. */
+    readonly locator: Locator;
+    /** The validated model id every run binds to. */
+    readonly modelId: string;
+    /** The absolute working directory the agent and tools are rooted at. */
+    readonly cwd: string;
+    /**
+     * Construct a fresh agent over the assembled configuration.
+     *
+     * `deps` lets a runner inject collaborators — most usefully a scripted model
+     * invoker or a session store — without the factory leaking how the agent is
+     * configured. Called once per logical session.
+     */
+    makeAgent(deps?: AgentDeps): Agent;
+    /** The output seam the runner writes to. */
+    readonly output: OutputSink;
+    /** The input seam the interactive runner reads from. */
+    readonly input: InputSource;
+    /**
+     * Resource teardowns to run on shutdown, in the order they were registered.
+     * The launcher invokes them (conventionally in reverse) before exiting.
+     */
+    readonly closables: Closable[];
+}

package/dist/types/shell-app/boot/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shell-application boot — public surface.
+ *
+ * One import site for the startup machinery that replaces a monolithic `main()`:
+ * the generic {@link Stage} pipeline and its {@link runStages} reducer, the
+ * assembled {@link BootContext} and its I/O seams, the {@link composeToolBoxes}
+ * helper, and the {@link buildBootContext} entry point that threads an
+ * invocation through every stage to produce a ready context.
+ */
+export type { Stage } from "./pipeline";
+export { runStages } from "./pipeline";
+export type { BootContext, BootIo, OutputSink, InputSource, Closable, } from "./context";
+export { BOOT_STAGES, buildBootContext, composeToolBoxes, } from "./stages";

package/dist/types/shell-app/boot/pipeline.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The ordered Stage pipeline that assembles a boot context.
+ *
+ * Where a traditional program crams "read the flags, find the config, pick a
+ * model, stand up the tools, wire the agent" into one sprawling `main()`, this
+ * module factors that startup into a sequence of small, named {@link Stage}s.
+ * Each stage is a pure-ish transformation `C → C` over an immutable context
+ * value: it reads what earlier stages produced, computes one more piece, and
+ * returns a *new* context carrying that addition. {@link runStages} threads an
+ * initial context through the list, left to right, awaiting each.
+ *
+ * Two properties make this worth the indirection:
+ *
+ *   - **Immutability.** A stage never mutates the context it is handed; it
+ *     returns a fresh object (conventionally `{ ...ctx, field }`). The reducer
+ *     keeps only the latest value, so a stage that forgets to thread a field
+ *     forward is a visible bug, not a silent shared-state mutation.
+ *   - **Order is data.** The boot order lives in an array, not in the call
+ *     structure of a function body. Inserting, reordering, or removing a step is
+ *     an edit to a list — and each step carries a `name` for tracing and errors.
+ *
+ * The pipeline is generic over the context type `C`; the concrete
+ * {@link import("./context").BootContext} and the concrete stage list live in
+ * their own modules so this one stays a tiny, reusable reducer.
+ */
+/**
+ * One ordered step of a boot pipeline.
+ *
+ * A stage is the unit of startup work: it takes the context produced by every
+ * earlier stage and returns the context the next stage will see, having folded
+ * in whatever it is responsible for. It may be synchronous or asynchronous; the
+ * runner awaits either.
+ *
+ * @typeParam C the context type threaded through the pipeline.
+ */
+export interface Stage<C> {
+    /** A short, stable label for this step — used in tracing and error context. */
+    readonly name: string;
+    /**
+     * Fold this stage's contribution into the context.
+     *
+     * Implementations must treat `ctx` as immutable and return a *new* context
+     * rather than mutating the argument. Returning the same reference (when a
+     * stage is a genuine no-op) is permitted but discouraged for clarity.
+     */
+    apply(ctx: C): Promise<C> | C;
+}
+/**
+ * Reduce an initial context through an ordered list of stages.
+ *
+ * Each stage receives the output of the previous one; the resolved value of the
+ * final stage is the fully assembled context. Stages run strictly in order —
+ * never concurrently — because a later stage routinely depends on an earlier
+ * one's contribution (a model id needs the loaded settings; the agent factory
+ * needs the assembled tools).
+ *
+ * The `initial` context is treated as immutable along with every intermediate:
+ * the function holds a single `ctx` binding and reassigns it to each stage's
+ * return value, so the caller's original object is never written to.
+ *
+ * @typeParam C the context type threaded through the pipeline.
+ * @param initial the seed context the first stage receives.
+ * @param stages the ordered steps to apply.
+ * @returns the context produced by the last stage.
+ */
+export declare function runStages<C>(initial: C, stages: readonly Stage<C>[]): Promise<C>;