indusagi 0.12.32 → 0.12.34

package/dist/types/shell-app/config/settings.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Settings resolution for the shell application.
+ *
+ * Settings arrive from three places, lowest precedence first: the built-in
+ * {@link DEFAULT_SETTINGS}, the per-user global file (under the profile
+ * directory), and the per-project file (under the working directory). They are
+ * merged shallowly with the rule "later wins", so a project file overrides the
+ * global file, which overrides the defaults.
+ *
+ * The loader is deliberately forgiving. A missing file, an unreadable file, or a
+ * file holding malformed/invalid JSON is treated as "no settings supplied at
+ * this layer" — never an exception. Configuration problems must not stop the
+ * agent from booting; the worst case is that the user falls back to defaults.
+ *
+ * Model selection is resolved separately by {@link resolveModelId}, which layers
+ * an explicit per-invocation override on top of the configured default and a
+ * hard-coded final fallback, validating each candidate against the catalog.
+ */
+import type { ServerConfig } from "../../interop";
+import type { Locator } from "./locator";
+/**
+ * Which built-in tool collection the agent exposes to the model.
+ *
+ *   - `read-only` — observe-only tools (read, ls, grep, find, web).
+ *   - `coding`    — read-only plus mutating/stateful tools (write, edit, bash…).
+ *   - `all`       — every registered tool.
+ *
+ * Mirrors the `ToolCollection` names the capabilities layer defines; kept as a
+ * standalone literal so settings need not import the capabilities package.
+ */
+export type ToolCollectionName = "read-only" | "coding" | "all";
+/** Tool-related preferences. */
+export interface ToolSettings {
+    /** Which built-in collection to expose; absent leaves the choice to the host. */
+    readonly collection?: ToolCollectionName;
+}
+/** History-condensation preferences, mirroring the runtime's policy shape. */
+export interface CompactionSettings {
+    /** Fraction of the context window (0..1) at which condensation triggers. */
+    readonly triggerRatio?: number;
+    /** Number of trailing turns kept untouched during condensation. */
+    readonly keepRecent?: number;
+}
+/**
+ * The user-tunable configuration surface.
+ *
+ * Every field is optional: an empty object is a valid {@link Settings}. Unknown
+ * keys read off disk are tolerated and discarded during normalization.
+ */
+export interface Settings {
+    /** The model id bound to runs when no per-invocation override is given. */
+    readonly defaultModel?: string;
+    /** A system preamble prepended to every model invocation. */
+    readonly systemPrompt?: string;
+    /** Tool exposure preferences. */
+    readonly tools?: ToolSettings;
+    /** External MCP servers to connect on start-up. */
+    readonly mcpServers?: readonly ServerConfig[];
+    /** History-condensation tuning. */
+    readonly compaction?: CompactionSettings;
+}
+/**
+ * The built-in baseline every layer is merged on top of.
+ *
+ * Intentionally minimal: it names a sensible default collection and leaves model
+ * selection to {@link resolveModelId}'s fallback so the catalog stays the single
+ * source of truth for valid model ids.
+ */
+export declare const DEFAULT_SETTINGS: Settings;
+/**
+ * Resolve the effective settings for a working directory.
+ *
+ * Merges three layers in increasing precedence — built-in defaults, the global
+ * profile file, then the project file under `cwd` — and returns the result.
+ * Never throws: any layer that cannot be read or parsed simply contributes
+ * nothing. Reads run concurrently; the merge order is fixed regardless.
+ */
+export declare function loadSettings(locator: Locator, cwd: string): Promise<Settings>;
+/**
+ * Decide which model id a run should bind to.
+ *
+ * Precedence, highest first:
+ *   1. `invocationModel` — an explicit per-invocation override (e.g. a CLI flag),
+ *      used when it names a model the catalog knows.
+ *   2. `settings.defaultModel` — the configured default, used when valid.
+ *   3. {@link FALLBACK_MODEL_ID} — a catalog-guaranteed last resort.
+ *
+ * Each candidate is validated with {@link getCard}; an unknown id is skipped
+ * rather than honored, so a stale or mistyped model never reaches the gateway.
+ */
+export declare function resolveModelId(settings: Settings, invocationModel?: string): string;

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

@@ -0,0 +1,26 @@
+/**
+ * The shell application — public surface.
+ *
+ * One import site for everything that turns a command line into a running agent:
+ * the {@link main} entry point and the {@link buildBootContext} assembler, the
+ * runner registry and its {@link selectRunner | selector}, the parser
+ * ({@link tokenizeInvocation}) and its {@link Invocation} shape, the path/branding
+ * {@link Locator}/{@link Brand}, the settings loader, the idempotent upgrade
+ * runner, and the `auth` subcommand. A host embedding the shell — or a test
+ * driving it — imports from here rather than reaching into submodules.
+ */
+export { main, buildBootContext, renderUsage, resolveVersion } from "./cli";
+export type { CliStreams } from "./cli";
+export { OneShotRunner, WireRunner, ReplRunner, TextView, RUNNERS, selectRunner, NoRunnerError, EndOfInput, } from "./runners";
+export type { Runner, BootContext, AgentDeps, InteractiveView, } from "./runners";
+export { Locator, BRAND, envName } from "./locate";
+export type { Brand, LocatorOverrides } from "./locate";
+export { tokenizeInvocation, FLAG_SPECS } from "./invocation/parse";
+export type { Invocation, RunnerMode } from "./invocation/parse";
+export type { FlagSpec, FlagValue, FlagKind } from "./invocation/flags";
+export { loadSettings, resolveModelId, DEFAULT_SETTINGS } from "./config";
+export type { Settings } from "./config";
+export { applyUpgrades, UPGRADES } from "./upgrade";
+export type { Upgrade } from "./upgrade";
+export { runAuthCommand } from "./auth-cli";
+export type { AuthIO } from "./auth-cli";

package/dist/types/shell-app/invocation/flags.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The declarative flag-spec table.
+ *
+ * This module is the single source of truth for the shell app's command-line
+ * vocabulary. Rather than scatter the knowledge of "what flags exist, what they
+ * mean, and how to read their values" across a hand-written argument loop, every
+ * flag is described once, as data, in {@link FLAG_SPECS}. The generic parser in
+ * `parse.ts` reads this table; the help renderer derives its text from it; and a
+ * new flag is added by appending one row here, never by editing parser branches.
+ *
+ * A {@link FlagSpec} pins down four things about a flag:
+ *   - its canonical long name and any aliases (short or long) the user may type;
+ *   - its {@link FlagKind} — whether it carries no value (`boolean`), a free
+ *     string, or a number;
+ *   - a one-line description used to generate `--help`;
+ *   - an optional default that seeds the parsed result when the flag is absent;
+ *   - an optional `repeatable` marker for flags that may appear many times and
+ *     accumulate (e.g. `--mcp`), collected into a string array by the parser.
+ *
+ * Nothing here touches `process`, the filesystem, or the network — it is plain
+ * data plus a couple of pure lookup helpers, so it is trivially testable and
+ * shareable between the parser and any tooling that wants to reason about flags.
+ */
+/** The three value shapes a flag can carry. */
+export type FlagKind = "boolean" | "string" | "number";
+/**
+ * The parsed value a flag contributes to an {@link Invocation}. Booleans land as
+ * `true`/`false`, strings as themselves, numbers as parsed numerics, and
+ * repeatable flags accumulate into a `string[]`.
+ */
+export type FlagValue = boolean | string | number | string[];
+/**
+ * One row of the flag table: the complete, declarative description of a single
+ * command-line flag.
+ */
+export interface FlagSpec {
+    /**
+     * The canonical long name, written *without* leading dashes (e.g. `"model"`).
+     * This is the key the flag's value is filed under in the parsed result.
+     */
+    readonly name: string;
+    /**
+     * Every other spelling the user may type, each *with* its leading dashes
+     * (e.g. `["-m"]` or `["--rpc", "--wire"]`). Both short (`-x`) and long
+     * (`--xyz`) aliases are permitted. The canonical `--<name>` spelling is always
+     * accepted and need not be listed here.
+     */
+    readonly aliases?: readonly string[];
+    /** Whether the flag carries no value, a string, or a number. */
+    readonly kind: FlagKind;
+    /** A one-line summary used when rendering `--help`. */
+    readonly description: string;
+    /**
+     * The value to seed the parsed result with when the flag is never supplied.
+     * Omit for flags that should simply be absent when unused.
+     */
+    readonly default?: FlagValue;
+    /**
+     * When `true`, the flag may be given more than once; each occurrence is pushed
+     * onto a `string[]` rather than overwriting the previous value. Only
+     * meaningful for `string`-kind flags.
+     */
+    readonly repeatable?: boolean;
+}
+/**
+ * The canonical flag table.
+ *
+ * Order matters only for help rendering (flags are shown top-to-bottom in this
+ * order); parsing is driven by name/alias lookup, not position. Every spelling
+ * across this table is unique — the lookup helpers below assume that.
+ */
+export declare const FLAG_SPECS: readonly FlagSpec[];
+/**
+ * Resolve a complete token (e.g. `"--model"`, `"-m"`, `"--rpc"`) to its spec, or
+ * `undefined` if no flag claims that spelling.
+ */
+export declare function findFlagBySpelling(spelling: string): FlagSpec | undefined;
+/**
+ * Resolve a single clustered short letter (e.g. `"v"` from `-iv`) to its spec,
+ * by matching against the `-x` form. Returns `undefined` if no flag uses that
+ * short letter.
+ */
+export declare function findShortFlag(letter: string): FlagSpec | undefined;
+/**
+ * The seed result, holding the `default` of every spec that declares one. The
+ * parser starts from a copy of this so absent-but-defaulted flags are present in
+ * the output and repeatable flags begin as empty arrays.
+ */
+export declare function defaultFlags(): Record<string, FlagValue>;

package/dist/types/shell-app/invocation/parse.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The generic, table-driven invocation parser.
+ *
+ * {@link tokenizeInvocation} turns a raw `argv` slice (the words after the
+ * program name) into a structured {@link Invocation}: a bag of recognised flag
+ * values, the leftover positionals, a derived free-text `prompt`, and the single
+ * {@link RunnerMode} the launcher should dispatch to.
+ *
+ * The parser is fully driven by the {@link FLAG_SPECS} table in `flags.ts` — it
+ * contains no per-flag branches. It understands the conventions a Unix CLI user
+ * expects:
+ *
+ *   - long flags `--name`, with the value either glued on as `--name=value` or
+ *     taken from the following token (`--name value`);
+ *   - short flags `-x`, likewise `-x=value`, `-x value`, or glued `-xvalue` for
+ *     value-taking shorts;
+ *   - clustered short booleans, so `-ip` is `-i -p`, and a value-taking short may
+ *     end a cluster (`-ipm gpt` ⇒ `-i -p -m gpt`);
+ *   - a bare `--` terminator, after which every remaining token is a positional
+ *     even if it looks like a flag;
+ *   - repeatable flags (e.g. `--mcp`) that accumulate into an array.
+ *
+ * It is pure: it reads only the `argv` array passed in and never touches
+ * `process`, the environment, the filesystem, or a TTY. Whether the session is
+ * actually interactive is *not* probed here — the caller passes that fact in via
+ * {@link TokenizeOptions.attended} so the function stays deterministic and
+ * testable.
+ *
+ * On a malformed invocation (unknown flag, missing required value, unparseable
+ * number) it throws an {@link InvocationError}; the launcher catches it at the
+ * edge and reports it.
+ */
+import { FLAG_SPECS } from "./flags";
+import type { FlagValue } from "./flags";
+/**
+ * The runner the launcher should hand off to, derived from the parsed flags:
+ *   - `help`    — usage was requested (`--help`);
+ *   - `version` — the version was requested (`--version`);
+ *   - `wire`    — the JSON line protocol over stdio (`--json`);
+ *   - `print`   — a single-shot answer to stdout (a prompt plus `--print`);
+ *   - `repl`    — the interactive loop (the default when unattended decisions
+ *                 don't force one of the above).
+ */
+export type RunnerMode = "print" | "wire" | "repl" | "help" | "version";
+/**
+ * The structured result of parsing an `argv` slice.
+ */
+export interface Invocation {
+    /**
+     * Recognised flag values, keyed by each spec's canonical `name`. Booleans are
+     * present as `true`/`false`, strings/numbers as their parsed value, repeatable
+     * flags as a (possibly empty) `string[]`, and defaulted flags as their seed.
+     */
+    readonly flags: Record<string, FlagValue>;
+    /** Every non-flag token, in order, with the `--` terminator removed. */
+    readonly positionals: readonly string[];
+    /**
+     * The positionals joined into a single free-text prompt, or `undefined` when
+     * there were none. This is the message the user typed for one-shot/print runs.
+     */
+    readonly prompt?: string;
+    /** The single runner the launcher should dispatch to. */
+    readonly mode: RunnerMode;
+}
+/** Knobs the caller supplies that the pure parser cannot discover itself. */
+export interface TokenizeOptions {
+    /**
+     * Whether the process is attended by an interactive terminal (a TTY on
+     * stdin/stdout). The caller probes this and passes it in so the parser stays
+     * free of `process` access. Defaults to `false` (treat as unattended), which
+     * biases an ambiguous, prompt-less invocation toward a non-interactive run.
+     */
+    readonly attended?: boolean;
+}
+/** Thrown when an `argv` slice cannot be parsed into a valid invocation. */
+export declare class InvocationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse a raw `argv` slice into a structured {@link Invocation}.
+ *
+ * `argv` must already exclude the runtime and script names — pass
+ * `process.argv.slice(2)` from the launcher. The function performs a single
+ * left-to-right scan, classifying each token as a long flag, a short
+ * flag/cluster, the `--` terminator, or a positional.
+ */
+export declare function tokenizeInvocation(argv: readonly string[], options?: TokenizeOptions): Invocation;
+/** Re-export the spec table so callers can render help from one import site. */
+export { FLAG_SPECS };

package/dist/types/shell-app/locate/brand.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The single source of naming truth for the whole application.
+ *
+ * Every user-visible name the product imprints on the world — the spoken app
+ * name, the executable users type, the dot-directory it carves under `$HOME`,
+ * the `INDUSAGI_*` prefix on its environment variables, the basenames of its
+ * on-disk artifacts — is declared *once*, here. Nothing else in the codebase
+ * should hard-code any of these strings; everything derives from {@link BRAND}.
+ *
+ * The motivation is a clean rebrand: changing the product's identity should be a
+ * one-file edit, and the {@link Locator} (which computes filesystem locations)
+ * reads exclusively from this module so the directory layout follows the name
+ * automatically. Keeping the constants frozen and `readonly` means a stray
+ * assignment is a type error rather than a silent corruption of identity.
+ */
+/**
+ * The shape of the brand record. Spelled out as an interface (rather than
+ * inferred from the literal) so consumers can name the type and so the contract
+ * is documented field-by-field.
+ */
+export interface Brand {
+    /** The product's spoken name, used in help banners and prose. */
+    readonly appName: string;
+    /** The executable name users invoke on the command line. */
+    readonly binName: string;
+    /**
+     * The prefix stamped on every environment variable the app reads or writes,
+     * including the trailing underscore (e.g. `"INDUSAGI_"`). Compose a full
+     * variable name with {@link envName}.
+     */
+    readonly envPrefix: string;
+    /**
+     * The dot-directory carved directly under the user's home for all per-user
+     * state (e.g. `".indusagi"`). Leading dot included so it is hidden.
+     */
+    readonly profileDirName: string;
+    /** Basename of the global settings file inside the profile directory. */
+    readonly settingsFileName: string;
+    /** Basename of the credential/auth store file inside the profile directory. */
+    readonly authStoreFileName: string;
+    /** Subdirectory (under the profile) holding persisted conversation sessions. */
+    readonly sessionsDirName: string;
+    /** Subdirectory (under the profile) holding diagnostic and crash logs. */
+    readonly logsDirName: string;
+    /**
+     * Basename of the per-project settings file. Lives in a project's working
+     * directory (inside {@link projectDirName}), not under the home profile, so a
+     * repository can carry its own overrides.
+     */
+    readonly projectSettingsFileName: string;
+    /**
+     * The dot-directory a project keeps in its own root for project-scoped
+     * settings (e.g. `".indusagi"`). Mirrors {@link profileDirName} but is rooted
+     * at the working directory rather than `$HOME`.
+     */
+    readonly projectDirName: string;
+}
+/**
+ * The canonical brand for this build of the product. Frozen so the identity is
+ * immutable at runtime; `as const` so every field narrows to its literal type.
+ */
+export declare const BRAND: Brand;
+/**
+ * Compose a fully-qualified environment variable name from a bare suffix.
+ *
+ * The suffix is upper-cased and any internal whitespace or hyphens are folded to
+ * underscores, then the brand's {@link Brand.envPrefix} is prepended. So
+ * `envName("api key")` yields `"INDUSAGI_API_KEY"`. Centralizing this keeps env
+ * naming consistent and guarantees the prefix is never forgotten.
+ */
+export declare function envName(suffix: string, brand?: Brand): string;

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

@@ -0,0 +1,12 @@
+/**
+ * The locate module — public surface.
+ *
+ * Two halves: {@link BRAND} (the single source of naming truth — app name, bin
+ * name, env-var prefix, directory names) and {@link Locator} (the one class that
+ * turns those names plus the home/cwd roots into concrete filesystem paths).
+ * Downstream code imports everything it needs from here.
+ */
+export { BRAND, envName } from "./brand";
+export type { Brand } from "./brand";
+export { Locator } from "./locator";
+export type { LocatorOverrides } from "./locator";

package/dist/types/shell-app/locate/locator.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Filesystem location resolution for the application.
+ *
+ * This module collapses what would otherwise be a scattered pile of free
+ * `getProfileDir()` / `getSettingsPath()` / `getSessionsDir()` path helpers into
+ * a single {@link Locator} class. Every location the app touches — the per-user
+ * profile directory, the global and per-project settings files, the sessions and
+ * logs directories, the credential store — is computed by one method, all
+ * deriving from two roots (the user's home and the current working directory)
+ * and the {@link BRAND} naming constants.
+ *
+ * The constructor takes optional overrides for `home`, `cwd`, and `env`, so a
+ * test (or an embedder) can sandbox the locator entirely: point `home` at a
+ * temp directory, hand it a synthetic `env`, and every resolved path lands
+ * inside the sandbox with no global state involved. With no overrides it falls
+ * back to {@link os.homedir}, {@link process.cwd}, and {@link process.env}.
+ *
+ * The path-returning methods are *pure* — they only join strings and never touch
+ * disk. The handful of `ensure*` helpers (backed by `fs/promises`) are the only
+ * members that perform I/O, and they exist purely so callers don't have to
+ * `mkdir -p` a directory before writing into it.
+ *
+ * Environment override:
+ *   - `INDUSAGI_HOME` (i.e. `<envPrefix>HOME`) — when set and non-empty, it
+ *     supersedes the OS home directory as the root of the profile. This lets a
+ *     user relocate all per-user state without touching `$HOME` itself.
+ */
+import { type Brand } from "./brand";
+/**
+ * Optional roots and environment a {@link Locator} resolves against. Anything
+ * omitted falls back to the live process: `home` → `os.homedir()`, `cwd` →
+ * `process.cwd()`, `env` → `process.env`.
+ */
+export interface LocatorOverrides {
+    /** Root for per-user state. Defaults to the OS home directory. */
+    readonly home?: string;
+    /** The working directory project paths resolve against. Defaults to `process.cwd()`. */
+    readonly cwd?: string;
+    /** The environment table consulted for overrides. Defaults to `process.env`. */
+    readonly env?: NodeJS.ProcessEnv;
+}
+/**
+ * Resolves every filesystem location the application uses from a small set of
+ * roots plus the {@link BRAND} naming constants.
+ *
+ * Construct one per process (or one per sandbox in tests). All path methods are
+ * pure and cheap; the `ensure*` methods are the only ones that touch disk.
+ */
+export declare class Locator {
+    private readonly home;
+    private readonly cwd;
+    private readonly env;
+    private readonly brand;
+    /**
+     * @param overrides Optional `home`/`cwd`/`env` to sandbox resolution. Each
+     *   field independently falls back to the live process when omitted.
+     * @param brand The naming source of truth. Defaults to the canonical
+     *   {@link BRAND}; injectable so an alternate identity can be resolved against
+     *   without mutating the global.
+     */
+    constructor(overrides?: LocatorOverrides, brand?: Brand);
+    /**
+     * Determine the home root, in precedence order:
+     *   1. an explicit `home` override passed to the constructor;
+     *   2. the `<envPrefix>HOME` environment variable, if present and non-empty;
+     *   3. the OS home directory from {@link os.homedir}.
+     */
+    private resolveHome;
+    /** Read an env var through the bound table, treating empty as absent. */
+    private readEnv;
+    /**
+     * The per-user profile directory — the dot-directory under the home root that
+     * holds all per-user state (e.g. `~/.indusagi`). Every home-rooted path below
+     * is computed relative to this.
+     */
+    profileDir(): string;
+    /** The global settings file inside the profile (e.g. `~/.indusagi/settings.json`). */
+    settingsPath(): string;
+    /**
+     * The per-project settings file for a given working directory.
+     *
+     * Resolves `cwd` against the locator's own working directory (so a relative
+     * argument is interpreted sensibly), then places the project settings file
+     * inside that project's dot-directory — e.g. `<project>/.indusagi/settings.json`.
+     *
+     * @param cwd The project root to resolve against. Defaults to the locator's
+     *   bound working directory.
+     */
+    projectSettingsPath(cwd?: string): string;
+    /** Directory holding persisted conversation sessions (e.g. `~/.indusagi/sessions`). */
+    sessionsDir(): string;
+    /** The credential/auth store file inside the profile (e.g. `~/.indusagi/auth.json`). */
+    authStorePath(): string;
+    /** Directory holding diagnostic and crash logs (e.g. `~/.indusagi/logs`). */
+    logsDir(): string;
+    /**
+     * Ensure the profile directory exists, creating it (and any missing parents)
+     * if absent. Returns the directory path for convenient chaining.
+     */
+    ensureProfileDir(): Promise<string>;
+    /**
+     * Ensure the sessions directory exists, creating it if absent. Returns the
+     * directory path.
+     */
+    ensureSessionsDir(): Promise<string>;
+    /**
+     * Ensure the logs directory exists, creating it if absent. Returns the
+     * directory path.
+     */
+    ensureLogsDir(): Promise<string>;
+    /**
+     * Ensure the parent directory of a file path exists, then return the original
+     * file path. Use before writing a file (settings, auth store) so the write
+     * never fails on a missing directory.
+     */
+    ensureParentOf(filePath: string): Promise<string>;
+    /**
+     * Create a directory (and any missing parents) idempotently, returning its
+     * path. The shared primitive behind every `ensure*` method above.
+     */
+    ensureDir(dir: string): Promise<string>;
+}

package/dist/types/shell-app/runners/contract.d.ts

@@ -0,0 +1,116 @@
+/**
+ * The runner contract — the data-driven replacement for a mode if/else.
+ *
+ * A {@link Runner} is one self-describing way to drive the agent: it knows the
+ * single {@link Invocation} shape it {@link Runner.accepts | accepts} and how to
+ * {@link Runner.run | run} a fully-prepared {@link BootContext} to an exit code.
+ * Selection is a linear scan over a registry (see `registry.ts`) — the first
+ * runner that accepts an invocation wins — so adding a new way to run the agent
+ * is a matter of appending one entry, never editing a dispatch ladder.
+ *
+ * The interactive surface is kept behind the {@link InteractiveView} seam: the
+ * REPL runner drives the agent through a `view` it never has to know the shape
+ * of, so a richer terminal UI can be slotted in later by implementing the
+ * interface — without this layer importing any UI toolkit.
+ */
+import type { Agent, RunEvent, RunSnapshot } from "../../runtime";
+import type { Settings } from "../config";
+import type { Invocation } from "../invocation/parse";
+/**
+ * The optional collaborators the boot module hands a runner.
+ *
+ * Re-declared here (rather than imported from `runtime`) so the runners layer
+ * owns its own seam vocabulary. It mirrors the runtime's `AgentDeps` loosely:
+ * the boot module is free to inject a scripted model, a store, or a ledger.
+ */
+export interface AgentDeps {
+    /** A model entrypoint override; absent uses the gateway default. */
+    readonly invokeModel?: unknown;
+    /** A durable session store; absent disables persistence. */
+    readonly store?: unknown;
+    /** An event ledger to publish on; absent uses a fresh internal one. */
+    readonly ledger?: unknown;
+}
+/**
+ * The fully-resolved context a runner needs, assembled by the boot module.
+ *
+ * Boot does the up-front work — parse the invocation, load settings, resolve the
+ * model id, probe the streams — and packages it here. A runner never re-derives
+ * any of it; it only builds an agent (via {@link makeAgent}) and drives it over
+ * the supplied streams.
+ *
+ * `view` is present only for the interactive runner; one-shot and wire runners
+ * talk to {@link output}/{@link input} directly and ignore it.
+ */
+export interface BootContext {
+    /** The parsed invocation this run was launched with. */
+    readonly invocation: Invocation;
+    /** The merged, normalized user settings. */
+    readonly settings: Settings;
+    /** The resolved model id every agent built here is bound to. */
+    readonly modelId: string;
+    /**
+     * Factory for the run's {@link Agent}. The boot module pre-binds the model,
+     * tools, and system prompt; a runner may pass optional {@link AgentDeps} to
+     * override the model entrypoint, store, or ledger.
+     */
+    readonly makeAgent: (deps?: AgentDeps) => Agent;
+    /** Where a runner writes its output (stdout in production). */
+    readonly output: NodeJS.WritableStream;
+    /** Where a runner reads its input (stdin in production). */
+    readonly input: NodeJS.ReadableStream;
+    /** The interactive seam, supplied only when an interactive runner will run. */
+    readonly view?: InteractiveView;
+}
+/**
+ * One self-describing way to drive the agent to an exit code.
+ *
+ * The registry holds many; {@link selectRunner} picks the first whose
+ * {@link accepts} returns true for an invocation. `run` resolves the process
+ * exit code (0 = success, non-zero = failure) — it must not call
+ * `process.exit` itself, so the boot module stays in control of teardown.
+ */
+export interface Runner {
+    /** A stable identifier, handy for logging and tests. */
+    readonly id: string;
+    /** Whether this runner handles the given invocation. */
+    accepts(invocation: Invocation): boolean;
+    /** Drive the prepared context to completion; resolves the exit code. */
+    run(ctx: BootContext): Promise<number>;
+}
+/**
+ * The seam a real interactive UI implements.
+ *
+ * The REPL runner owns the read-submit-render loop but knows nothing about *how*
+ * a turn is presented: it pushes each {@link RunEvent} at {@link render}, asks
+ * {@link prompt} for the next line of user input, and calls {@link close} once
+ * on teardown. A minimal plain-text view ships in `repl.ts`; a richer terminal
+ * UI can satisfy the same three methods later without touching this layer.
+ */
+export interface InteractiveView {
+    /** Present one run event (a delta, a tool lifecycle marker, a settle…). */
+    render(event: RunEvent): void;
+    /**
+     * Ask the user for their next line of input and resolve the typed line.
+     *
+     * End-of-input (the stream closed, or the user pressed Ctrl-D) is signalled by
+     * *rejecting* with {@link EndOfInput} rather than resolving a sentinel, so an
+     * empty line stays a legitimate, submittable value. The loop catches it and
+     * leaves cleanly.
+     */
+    prompt(): Promise<string>;
+    /** Release any resources (e.g. a readline interface). Called once. */
+    close(): void;
+}
+/**
+ * The rejection {@link InteractiveView.prompt} raises when input is exhausted.
+ *
+ * A typed marker (rather than a magic string return) keeps EOF distinguishable
+ * from a blank line and lets the REPL loop end on `instanceof` rather than value
+ * matching.
+ */
+export declare class EndOfInput extends Error {
+    constructor();
+}
+/** Re-exported for convenience so runner modules import from one site. */
+export type { Agent, RunEvent, RunSnapshot, Invocation, Settings };

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

@@ -0,0 +1,15 @@
+/**
+ * The runners layer — public surface.
+ *
+ * One import site for the registry and its contract: the boot module selects a
+ * {@link Runner} with {@link selectRunner}, assembles a {@link BootContext}, and
+ * calls `run`. The {@link InteractiveView} seam (and its default {@link TextView}
+ * placeholder) lives here too so a richer UI can be slotted in later without
+ * touching the boot layer.
+ */
+export type { Runner, BootContext, AgentDeps, InteractiveView, } from "./contract";
+export { EndOfInput } from "./contract";
+export { OneShotRunner } from "./one-shot";
+export { WireRunner } from "./wire";
+export { ReplRunner, TextView } from "./repl";
+export { RUNNERS, selectRunner, NoRunnerError } from "./registry";

package/dist/types/shell-app/runners/one-shot.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The one-shot runner.
+ *
+ * Drives a single prompt to settlement, streaming the assistant's prose to the
+ * output stream as plain text with no framing, then exits. This is the runner
+ * behind `--print`: pipe a question in, get the answer on stdout, suitable for
+ * scripting and composition with other tools.
+ *
+ * It subscribes to the agent's live {@link RunEvent} stream and forwards every
+ * incremental `text_delta` straight to {@link BootContext.output}, so output
+ * appears as it is generated rather than all at once at the end. A trailing
+ * newline is printed once the run settles so the final line is terminated. If
+ * the run faults, the failure is reported to stderr and the runner resolves a
+ * non-zero exit code.
+ */
+import type { Runner } from "./contract";
+/**
+ * The single-shot, plain-text output runner. Accepts the `print` mode the
+ * invocation parser derives for a prompt-bearing, non-interactive launch.
+ */
+export declare const OneShotRunner: Runner;