indusagi-coding-agent 0.1.59 → 0.1.61

package/dist/types/addons/sandbox.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Addon sandbox — the SINGLE jiti-backed {@link ModuleLoader}.
+ *
+ * This module turns a path on disk into a loaded {@link AddonManifest}. It is the
+ * one place the app reaches a TypeScript-on-the-fly importer (`jiti`), and it is
+ * the one place the framework namespaces an addon may `import` are bridged into
+ * the addon's module graph. Two facts shape the design:
+ *
+ *   1. **A compiled binary has no `node_modules`.** When the app ships as a
+ *      single-file executable the framework code (`indusagi/agent`, `indusagi/ai`,
+ *      `indusagi/tui`) and `@sinclair/typebox` are already *inside* the binary —
+ *      an addon's `import "indusagi/agent"` cannot resolve against a directory
+ *      that does not exist on the host. The sandbox satisfies those specifiers
+ *      from the host's own statically-imported namespace objects (jiti's
+ *      `virtualModules`), so the addon shares the host's exact module instances
+ *      rather than loading a second copy.
+ *
+ *   2. **An interpreted launch has real files.** Under Node (or `bun run` over
+ *      source) the same specifiers resolve to real paths on disk; the sandbox
+ *      feeds those resolved paths to jiti as `alias` entries so the importer
+ *      finds them without re-walking `node_modules`.
+ *
+ * The literal set of bridged specifiers is the contract's {@link BUNDLED_NAMESPACES};
+ * this module owns only the *mechanism* that maps each one to either a live
+ * namespace object (virtual-module mode) or a resolved file path (alias mode).
+ *
+ * The loader is deliberately injectable: {@link createJitiLoader} is the default
+ * {@link ModuleLoader}, but every consumer takes the interface, so a test can
+ * inject a scripted fake that returns a manifest with no jiti and no disk.
+ *
+ * Path inputs are normalized through this module's own {@link expandPath} /
+ * {@link resolvePath} helpers — home-directory expansion plus a from-scratch
+ * invisible-whitespace scrub — written here rather than imported, so the loader
+ * owns its full input-hygiene story.
+ */
+import { type ModuleLoader } from "./contract";
+/**
+ * Strip invisible / non-standard whitespace from a path string and trim ordinary
+ * leading and trailing ASCII whitespace.
+ *
+ * Walks the string by code point (so astral characters survive intact), dropping
+ * any member of {@link INVISIBLE_SET}, then trims the plain ASCII edges. Written
+ * as an explicit scan rather than a regex so the exact handled set is visible at
+ * the call site.
+ *
+ * @param raw the path as supplied (possibly carrying invisible characters)
+ */
+export declare function scrubInvisible(raw: string): string;
+/**
+ * Expand a leading `~` (or `~/`) to the user's home directory.
+ *
+ * Only a `~` that begins the (already-scrubbed) string is treated as the home
+ * marker; a `~` anywhere else is an ordinary character. `~` alone becomes the
+ * home directory; `~/x` becomes `<home>/x`. A `home` override is accepted for
+ * tests and embedding so the function never reads the environment implicitly.
+ *
+ * @param raw  the path, possibly beginning with a home marker
+ * @param home the home directory to expand against; defaults to {@link homedir}
+ */
+export declare function expandPath(raw: string, home?: string): string;
+/**
+ * Resolve a path to an absolute, invisible-free path.
+ *
+ * Scrubs invisible whitespace, expands a leading home marker, then anchors the
+ * result against `base` (the working directory) when it is not already absolute.
+ * The single normalizer every loader entry funnels through, so input hygiene is
+ * applied in exactly one place.
+ *
+ * @param raw  the path as supplied
+ * @param base the directory a relative path resolves against; defaults to `process.cwd()`
+ * @param home the home directory `~` expands against; defaults to {@link homedir}
+ */
+export declare function resolvePath(raw: string, base?: string, home?: string): string;
+/**
+ * Options for {@link createJitiLoader}.
+ *
+ * All optional — the defaults wire the live runtime — but each is overridable so
+ * a test can pin the working directory or home without touching the process. The
+ * jiti instance itself is constructed from {@link jitiOptionsForRuntime}; these
+ * options only steer how a supplied path is normalized before it is imported.
+ */
+export interface JitiLoaderOptions {
+    /** Directory a relative addon path resolves against; defaults to `process.cwd()`. */
+    readonly base?: string;
+    /** Home directory a leading `~` expands against; defaults to {@link homedir}. */
+    readonly home?: string;
+}
+/**
+ * Construct the default jiti-backed {@link ModuleLoader}.
+ *
+ * Creates one jiti instance — configured with the bridged framework namespaces
+ * appropriate to the runtime (virtual modules in a compiled binary, resolved
+ * aliases under Node) — and returns a loader whose {@link ModuleLoader.load}
+ * normalizes the supplied path, imports it through jiti, and extracts the
+ * {@link AddonManifest}. A module that does not expose a callable `register` is
+ * rejected, so the host converts the rejection into a load fault.
+ *
+ * This is the production loader; tests inject a fake implementing the same
+ * interface, exercising the registry/host without any real jiti or disk.
+ *
+ * @param options optional path-normalization overrides
+ */
+export declare function createJitiLoader(options?: JitiLoaderOptions): ModuleLoader;

package/dist/types/addons/surface.d.ts

@@ -0,0 +1,42 @@
+/**
+ * AddonSurface implementation — the recording registration API.
+ *
+ * This module realizes the contract's central design stance: an addon's
+ * `register` entry point is handed a {@link AddonSurface} and *records* its
+ * intent — event subscriptions, tool interceptors, slash commands, contributed
+ * tools — rather than mutating any shared runtime. Each surface is a small,
+ * per-addon accumulator: every `on` / `interceptTool` / `addCommand` / `addTool`
+ * call appends to a private list, and {@link RecordingSurface.manifest} reads the
+ * accumulated {@link RegisteredManifest} back out for the host to fold.
+ *
+ * Because registration is pure recording, the host stays in control of *what to
+ * do* with the contributions. The surface only:
+ *
+ *   - stamps every recorded shape with the owning {@link AddonId} (so a later
+ *     fault is attributable) and fills the `match` / `name` fields the surface
+ *     methods take separately from the handler object;
+ *   - threads the host-supplied {@link FrameworkHandles} through unchanged, so an
+ *     addon can act at registration time and the same handles reach its command
+ *     contexts; and
+ *   - returns an immutable snapshot from {@link RecordingSurface.manifest}, so a
+ *     read after `register` settles cannot be mutated by a stray later call.
+ *
+ * The surface performs no dispatch, no loading, and no conflict resolution —
+ * those are the host's job once it has folded every addon's manifest. Keeping the
+ * surface this thin is what makes registration a description of capability rather
+ * than a side effect on the agent.
+ */
+import type { AddonId, AddonSurface, FrameworkHandles } from "./contract";
+/**
+ * Mint a fresh {@link AddonSurface} for one addon.
+ *
+ * The host calls this once per addon, scoping the surface to that addon's
+ * {@link AddonId} and the session's {@link FrameworkHandles}, then passes the
+ * surface to the addon's `register`. After `register` settles the host reads
+ * {@link AddonSurface.manifest} to obtain the contributions to fold.
+ *
+ * @param id      the addon the surface is scoped to
+ * @param handles the framework handles the addon (and its commands) may act through
+ * @param version optional addon version carried into the recorded manifest
+ */
+export declare function createSurface(id: AddonId, handles: FrameworkHandles, version?: string): AddonSurface;

package/dist/types/boot/auth-vault.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Disk-backed credential vault — the boot-layer adapter that satisfies the
+ * launch {@link AuthVault} seam so the credential command can persist
+ * credentials before the concrete Phase-2 multi-account vault lands.
+ *
+ * The store is a single JSON file (`auth.json` under the profile directory),
+ * keyed provider → account → record. Each record is a discriminated union: it
+ * holds *either* a stored api key *or* a set of browser-sign-in credentials, plus
+ * a default marker. The adapter is deliberately small and self-contained: it
+ * reads / writes the whole file each time (the file is tiny and the operations
+ * are interactive, so atomic-rewrite simplicity beats incremental I/O).
+ *
+ * Two kinds of read are offered. The default-account lookup is plain bookkeeping;
+ * {@link AuthVault.readUsableKey} resolves a record to a live api-key string — for
+ * an api-key record it returns the stored key verbatim, and for a browser-sign-in
+ * record it asks the framework to refresh an expired token (persisting the
+ * rotated credentials back to disk) before handing back the usable key.
+ *
+ * This is *not* the Phase-2 vault — it is the minimal real persistence the
+ * launch wiring needs. When the concrete multi-account vault arrives it replaces
+ * this adapter at the one call site in {@link "./boot"}.
+ */
+import type { AuthVault } from "../launch";
+/**
+ * Build a disk-backed {@link AuthVault} persisting to `authPath`.
+ *
+ * @param authPath absolute path of the JSON credential store (e.g. `auth.json`)
+ */
+export declare function createAuthVault(authPath: string): AuthVault;

package/dist/types/boot/boot.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Boot orchestrator — the single function the OS entry point calls.
+ *
+ * {@link boot} owns the whole launch arc: it assembles the seed
+ * {@link BootContext} (resolved workspace + brand + a placeholder invocation),
+ * runs the ordered {@link runStages | stage pipeline} to resolve the rest
+ * (parse the command line, materialise directories, apply upgrades, build the
+ * startup-resource graph), handles the meta requests (`--help` / `--version`)
+ * that short-circuit before any runner, then dispatches to the
+ * {@link selectRunner | selected runner} and returns its exit code.
+ *
+ * Cleanup is guaranteed: every teardown callback accumulated in
+ * {@link BootContext.closables} is drained in a `finally`, latest-registered
+ * first, regardless of how the runner resolved. {@link boot} itself never throws
+ * to its caller for an expected failure — it maps problems to a non-zero exit
+ * code so the entry point can simply set `process.exitCode`.
+ */
+/**
+ * Boot the agent: resolve everything, dispatch to the chosen runner, and return
+ * the process exit code.
+ *
+ * @param argv The arguments the launch was invoked with, already sliced (no
+ *   node/exec path).
+ * @returns The exit code the process should adopt.
+ */
+export declare function boot(argv: string[]): Promise<number>;

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

@@ -0,0 +1,15 @@
+/**
+ * Phase-1 boot layer — unit tests.
+ *
+ * No network, no real home directory: every test that touches disk runs under a
+ * fresh sandbox home created in the OS temp dir and removed in `afterEach`. The
+ * tests pin the public seams of the boot layer:
+ *
+ *   - {@link tokenizeInvocation} maps flags to the right mode / prompt / model.
+ *   - `--help` is recognised and short-circuits {@link boot}.
+ *   - {@link createWorkspace} resolves all paths beneath an overridden home.
+ *   - {@link applyUpgrades} is idempotent (a second pass applies nothing).
+ *   - {@link runStages} produces a fully-resolved {@link BootContext}.
+ *   - {@link selectRunner} picks the placeholder runner for each mode.
+ */
+export {};

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

@@ -0,0 +1,234 @@
+/**
+ * Boot-layer contract — the FROZEN type surface of Phase 1.
+ *
+ * This module is the single typed seam between the operating-system entry point
+ * (`entry.ts`) and everything that turns a command line into a running coding
+ * agent. It declares *only* shapes — no behavior, no I/O, no literals beyond the
+ * narrow string unions that pin the public modes. Every later boot module
+ * (workspace locator, upgrade registry, stage pipeline, runner registry) is
+ * written against the names declared here, so this file is intentionally small,
+ * append-mostly, and stable.
+ *
+ * Design stance:
+ *   - One immutable {@link BootContext} is threaded through an ordered list of
+ *     {@link Stage} transforms; a stage returns the next context (or the same
+ *     one) and never mutates in place.
+ *   - All branding lives in a single {@link Brand} record and all on-disk paths
+ *     in a single {@link Workspace} object — there are no scattered free getters
+ *     and no string literals duplicated across the codebase.
+ *   - Where the rebuilt framework already owns a concept (the model catalog, the
+ *     user-settings shape), the resolved-resource graph is typed against the
+ *     framework's published types rather than re-declaring them here.
+ *
+ * Framework anchors (all from the `indusagi` package):
+ *   - `ModelRegistry`  ← `indusagi/ai`     — the resolved model catalog.
+ *   - `Settings`       ← `indusagi/shell-app` — the user-tunable config shape.
+ *   - `ThinkingLevel`  ← `indusagi/agent`  — reasoning-effort vocabulary (re-exported
+ *                                            for convenience by boot consumers).
+ */
+import type { ModelRegistry } from "indusagi/ai";
+import type { Settings } from "indusagi/shell-app";
+import type { ThinkingLevel } from "indusagi/agent";
+/** Re-exported framework reasoning vocabulary, surfaced through the boot contract. */
+export type { ThinkingLevel };
+/**
+ * The single source of truth for every branding / identity literal.
+ *
+ * Nothing else in the app hard-codes the product name, the profile directory
+ * name, the bin names, the environment-variable namespace, or the share-viewer
+ * origin. Resolving these once into a frozen record means a rebrand touches one
+ * value, never a grep across the tree.
+ */
+export interface Brand {
+    /** Product name used in banners and `process.title` (e.g. `"indusagi"`). */
+    readonly name: string;
+    /** Display label for human-facing surfaces; defaults to {@link name}. */
+    readonly label: string;
+    /** Profile directory leaf under the user's home (e.g. `".indusagi"`). */
+    readonly profileDirName: string;
+    /** Sub-directory of the profile holding the agent's own state (e.g. `"agent"`). */
+    readonly stateDirName: string;
+    /** The executable names this app installs as (both point at one entry). */
+    readonly binNames: readonly [primary: string, alias: string];
+    /** Environment-variable name prefix shared by all app-scoped vars (e.g. `"INDUSAGI"`). */
+    readonly envPrefix: string;
+    /** Env var overriding the resolved profile directory (e.g. `"INDUSAGI_CODING_AGENT_DIR"`). */
+    readonly envProfileDir: string;
+    /** Env var that, when set, disables transport-noise log filtering (e.g. `"INDUSAGI_DEBUG"`). */
+    readonly envDebug: string;
+    /** Env var overriding the share-viewer origin (e.g. `"INDUSAGI_SHARE_VIEWER_URL"`). */
+    readonly envShareViewer: string;
+    /** Default origin a published transcript links to. */
+    readonly shareViewerUrl: string;
+}
+/**
+ * Every resolved on-disk location the app reads or writes, as one immutable
+ * record rather than a family of free `get*Path()` getters.
+ *
+ * All members are absolute paths already expanded against the user's home and
+ * the active {@link Brand}; consumers join nothing further. A single object also
+ * makes the layout trivially inspectable and swappable in tests.
+ */
+export interface Workspace {
+    /** Root profile directory, e.g. `~/.indusagi/agent`. */
+    readonly profileDir: string;
+    /** Merged-settings file (`settings.json`). */
+    readonly settingsPath: string;
+    /** Consolidated credential store (`auth.json`). */
+    readonly authPath: string;
+    /** Per-cwd transcript directory root (`sessions/`). */
+    readonly sessionsDir: string;
+    /** Custom model-catalog overrides (`models.json`). */
+    readonly modelsPath: string;
+    /** Provisioned native helper binaries (`bin/`, holds fd / rg). */
+    readonly toolsDir: string;
+    /** Alias for the managed-binary directory; equals {@link toolsDir}. */
+    readonly binDir: string;
+    /** User-authored prompt/command templates (`prompts/`). */
+    readonly promptsDir: string;
+    /** User-installed color themes (`themes/`). */
+    readonly themesDir: string;
+    /** Bundled HTML transcript-export template directory. */
+    readonly exportTemplateDir: string;
+    /** Verbose diagnostic log file path. */
+    readonly debugLogPath: string;
+    /** External MCP server configuration (`mcp-servers.json`). */
+    readonly mcpConfigPath: string;
+    /** Memory-feature configuration (`memory.json`). */
+    readonly memoryConfigPath: string;
+    /** Composio-integration configuration (`composio.json`). */
+    readonly composioConfigPath: string;
+    /** On-disk memory database (`memory.db`). */
+    readonly memoryDbPath: string;
+}
+/**
+ * The three top-level execution modes the boot layer can dispatch to.
+ *
+ *   - `repl`    — interactive terminal session.
+ *   - `oneshot` — single non-interactive request to stdout (text or JSON).
+ *   - `link`    — headless JSON-RPC link for a driving parent process.
+ */
+export type RunnerId = "repl" | "oneshot" | "link";
+/**
+ * The parsed command line, reduced to what the boot layer needs to choose and
+ * configure a {@link Runner}. This is the minimal Phase-1 shape; Phase 10 enriches
+ * it with the full declarative flag surface. Raw, un-consumed tokens survive in
+ * {@link rest} and loosely-typed switches in {@link flags} so nothing is lost
+ * before the richer parser lands.
+ */
+export interface Invocation {
+    /** Resolved execution mode. */
+    readonly mode: RunnerId;
+    /** First user message / request text, when supplied positionally or via stdin. */
+    readonly prompt?: string;
+    /** Explicit model selector from the command line, if any (`--model` / `-m`). */
+    readonly modelId?: string;
+    /** Working directory the run is scoped to; absent means the process cwd (`--cwd`). */
+    readonly cwd?: string;
+    /** Named credential account to authenticate with (`--account`). */
+    readonly account?: string;
+    /** Reasoning effort (`--thinking`): off / minimal / low / medium / high / xhigh. */
+    readonly thinking?: string;
+    /** Replacement system prompt (`--system`); a path is read as a file, else literal text. */
+    readonly system?: string;
+    /** Extra text appended after the system prompt (`--append-system`); path-or-literal. */
+    readonly appendSystem?: string;
+    /** Allow-list of built-in tool names (`--tools`); absent means the full deck. */
+    readonly tools?: readonly string[];
+    /** Disable every built-in tool (`--no-tools`). */
+    readonly noTools?: boolean;
+    /** External MCP endpoint config paths to attach (`--mcp`). */
+    readonly mcp?: readonly string[];
+    /** Open the resume picker before the session starts (`--resume` / `-r`). */
+    readonly resume?: boolean;
+    /** Auto-resume the most recent session in the cwd (`--continue` / `-c`). */
+    readonly continueLatest?: boolean;
+    /** Print the model catalog and exit (`--list-models`). */
+    readonly listModels?: boolean;
+    /** Optional substring filter for `--list-models`. */
+    readonly listModelsFilter?: string;
+    /** Parsed switches, keyed by canonical flag name (values intentionally loose). */
+    readonly flags: Record<string, unknown>;
+    /** Positional / pass-through tokens not consumed as flags. */
+    readonly rest: string[];
+}
+/**
+ * Placeholder for the resolved per-account credential graph.
+ *
+ * The rebuilt framework publishes no credential type, so the boot contract owns
+ * an opaque, forward-declared shape here; Phase 2 replaces it with the concrete
+ * multi-account credential vault. Kept deliberately structural (an indexable
+ * bag) so a stage may attach it without the vault module existing yet.
+ */
+export interface CredentialGraph {
+    readonly [account: string]: unknown;
+}
+/**
+ * The resolved settings / auth / model-registry graph assembled during startup.
+ *
+ * This is a Phase-1 placeholder: the fields are typed against the framework's
+ * own published types where one exists ({@link Settings}, {@link ModelRegistry}),
+ * and against an app-local placeholder ({@link CredentialGraph}) where the
+ * framework does not yet own the concept. Later phases attach the loaded
+ * extension/MCP graph onto the same object without changing these anchors.
+ */
+export interface StartupResources {
+    /** Merged user settings (framework-owned shape). */
+    readonly settings: Settings;
+    /** Resolved credentials per account (app-owned placeholder until Phase 2). */
+    readonly auth: CredentialGraph;
+    /** The resolved model catalog (framework-owned registry). */
+    readonly models: ModelRegistry;
+}
+/**
+ * The immutable value threaded through the {@link Stage} pipeline.
+ *
+ * Each stage receives a context and returns the next one; treat every field as
+ * read-only and produce successors by spreading rather than mutating. The
+ * resolved-resource graph is optional because early stages run before it exists.
+ * {@link closables} accumulates teardown callbacks (open files, servers, MCP
+ * clients) that the entry point drains in reverse on exit.
+ */
+export interface BootContext {
+    /** The process arguments the launch was invoked with (already sliced). */
+    readonly argv: string[];
+    /** Resolved on-disk layout. */
+    readonly workspace: Workspace;
+    /** Resolved identity literals. */
+    readonly brand: Brand;
+    /** Parsed command line. */
+    readonly invocation: Invocation;
+    /** Resolved settings/auth/model graph; absent until the resource stage runs. */
+    readonly resources?: StartupResources;
+    /** Teardown callbacks to drain on shutdown (latest-registered first). */
+    readonly closables: Array<() => Promise<void>>;
+}
+/**
+ * One step of the launch pipeline: a named, pure-ish transform over a context
+ * value of type `C` (defaulting to {@link BootContext}).
+ *
+ * A stage may return its result synchronously or asynchronously. It must not
+ * mutate its input; it returns the next context. The `name` is used for tracing
+ * and error attribution when a stage throws.
+ */
+export interface Stage<C = BootContext> {
+    /** Stable identifier for tracing and error messages. */
+    readonly name: string;
+    /** Transform the context, yielding its successor. */
+    apply(ctx: C): Promise<C> | C;
+}
+/**
+ * A terminal execution strategy for one {@link RunnerId} mode.
+ *
+ * The runner registry asks each runner whether it {@link accepts} a parsed
+ * {@link Invocation}; the first match runs. {@link run} drives the selected mode
+ * to completion and resolves to the process exit code.
+ */
+export interface Runner {
+    /** The mode this runner serves. */
+    readonly id: RunnerId;
+    /** Whether this runner handles the given invocation. */
+    accepts(inv: Invocation): boolean;
+    /** Execute the mode; resolves to the process exit code. */
+    run(ctx: BootContext): Promise<number>;
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Boot subsystem — public barrel.
+ *
+ * Re-exports the frozen Phase-1 contract type surface plus the assembled boot
+ * layer: the orchestrator ({@link boot}), the stage pipeline
+ * ({@link runStages} / {@link STAGES}), the invocation parser
+ * ({@link tokenizeInvocation}), the runner registry ({@link selectRunner} /
+ * {@link RUNNERS}), and the upgrade driver ({@link applyUpgrades}). Consumers
+ * import the boot type surface and behavior from `src/boot` rather than reaching
+ * into individual modules.
+ */
+export type { Brand, Workspace, Invocation, RunnerId, BootContext, Stage, Runner, StartupResources, CredentialGraph, ThinkingLevel, } from "./contract";
+export { boot } from "./boot";
+export { runStages, STAGES, locateWorkspace, upgrade, buildInvocation, resolveResources, selectRunnerStage, } from "./stages";
+export { tokenizeInvocation, wantsHelp, wantsVersion, } from "./invocation";
+export { replRunner, oneshotRunner, linkRunner, RUNNERS, selectRunner, } from "./runners";
+export type { Upgrade, UpgradeReport } from "./upgrade";
+export { applyUpgrades, UPGRADES } from "./upgrade";
+export { BRAND, createWorkspace, ensureDirs } from "../workspace";
+export type { WorkspaceOverrides } from "../workspace";

package/dist/types/boot/invocation.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Invocation reader for the boot layer — the adapter that drives the full
+ * Phase-10 declarative flag grammar and projects its rich result down onto the
+ * thin boot {@link Invocation} the runner pipeline routes on.
+ *
+ * The parsing itself is no longer owned here. {@link readInvocation} (from the
+ * `launch/` subsystem) walks the single declarative flag table and produces the
+ * full {@link LaunchInvocation}; this module's job is purely the *projection*:
+ * map the launch {@link OutputMode} onto the boot {@link RunnerId}, rename the
+ * resolved fields the boot layer reads (`model` → `modelId`, `positionals` →
+ * `rest`), and widen the typed flag bag back to the loose
+ * `Record<string, unknown>` the boot {@link Invocation} carries. The result is
+ * type-compatible with the rest of the boot pipeline, so the runner registry and
+ * the session helpers consume it unchanged.
+ *
+ *   - mode: `text` → `repl`, `json` → `oneshot`, `rpc` → `link`.
+ *   - the full flag bag survives on {@link Invocation.flags} so the meta checks
+ *     (`--help` / `--version`) and the oneshot output-shape probe (`json`) keep
+ *     reading the same canonical keys they always did.
+ *
+ * The parse is total and never throws: the launch reader tolerates unknown
+ * `--flags` as boolean switches in the flag bag rather than rejecting them, so
+ * nothing is silently dropped before a later phase can reinterpret it.
+ */
+import type { Invocation } from "./contract";
+/**
+ * Read a sliced `process.argv` into the boot {@link Invocation}.
+ *
+ * Delegates the actual grammar to the launch {@link readInvocation} (the one
+ * declarative flag table), then projects its result onto the boot shape. The
+ * boot layer thus shares one parser with the launch subsystem — help, parsing,
+ * and routing can no longer drift.
+ *
+ * @param argv The already-sliced argument vector (no node/exec path).
+ */
+export declare function tokenizeInvocation(argv: readonly string[]): Invocation;
+/** Whether the parsed invocation is asking for the help banner. */
+export declare function wantsHelp(inv: Invocation): boolean;
+/** Whether the parsed invocation is asking for the version string. */
+export declare function wantsVersion(inv: Invocation): boolean;

package/dist/types/boot/invocation.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Tests for the launch→boot invocation projection ({@link tokenizeInvocation}).
+ *
+ * The boot `Invocation` is what every runner consumes, so these assert that each
+ * CLI flag survives the parse + projection and lands on the typed field the
+ * runners read — the exact step where the full flag surface used to be dropped.
+ */
+export {};

package/dist/types/boot/runners/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Runners subsystem — public barrel.
+ *
+ * Surfaces the runner registry and the individual placeholder runners. Boot
+ * consumers dispatch through {@link selectRunner} / {@link RUNNERS}; the named
+ * runners are exported for tests and for explicit wiring.
+ */
+export { replRunner } from "./repl-runner";
+export { oneshotRunner } from "./oneshot-runner";
+export { linkRunner } from "./link-runner";
+export { RUNNERS, selectRunner } from "./registry";

package/dist/types/boot/runners/link-runner.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Runner: `link` — headless JSON-RPC link for a driving parent process.
+ *
+ * Drives the Phase-8 link channel: it assembles a {@link SessionConductor} for
+ * the invocation and serves the declarative {@link SESSION_OPS} registry over the
+ * process stdio pair via {@link createLinkServer}. Every framed request is
+ * dispatched through the registry (data-driven, not a command switch) and the
+ * reply is framed back; the runner resolves the success exit code once the
+ * inbound stream ends.
+ */
+import type { Runner } from "../contract";
+/**
+ * The headless-link runner.
+ *
+ * {@link Runner.accepts} matches invocations whose resolved mode is `link`.
+ * {@link Runner.run} assembles the conductor, starts a link server reading framed
+ * requests from stdin and writing framed replies to stdout, and resolves the
+ * success exit code when the inbound stream is exhausted.
+ */
+export declare const linkRunner: Runner;

package/dist/types/boot/runners/oneshot-runner.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Runner: `oneshot` — single non-interactive request to stdout.
+ *
+ * Drives the Phase-8 oneshot channel: it assembles a {@link SessionConductor}
+ * for the invocation, builds a {@link ChannelContext} over `process.stdout`
+ * (clean text, or a streamed NDJSON event log), runs every prompt to settlement
+ * via {@link runOneshot}, and resolves the channel exit code. The output shape is
+ * NDJSON when the invocation carries a `json` flag, otherwise clean text.
+ */
+import type { Runner } from "../contract";
+/**
+ * The one-shot runner.
+ *
+ * {@link Runner.accepts} matches invocations whose resolved mode is `oneshot`.
+ * {@link Runner.run} assembles the conductor and channel context, then delegates
+ * the run to {@link runOneshot} and returns its exit code. With no request text
+ * it writes a short notice and exits non-zero rather than mounting an empty run.
+ */
+export declare const oneshotRunner: Runner;

package/dist/types/boot/runners/registry.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Runner registry — the table-driven replacement for a mode `if/else` ladder.
+ *
+ * The boot pipeline ends by handing the resolved {@link Invocation} to exactly
+ * one {@link Runner}. Rather than branch on the mode string at the call site,
+ * dispatch is data: {@link RUNNERS} lists every available runner in priority
+ * order, and {@link selectRunner} returns the first whose {@link Runner.accepts}
+ * predicate matches. Adding or reordering modes is a one-line edit to the table,
+ * never a change to control flow.
+ *
+ * The interactive REPL is both first in the table and the guaranteed fallback:
+ * if no runner claims an invocation, {@link selectRunner} returns it, so a bare
+ * command line lands in the interactive session.
+ */
+import type { Invocation, Runner } from "../contract";
+/**
+ * Every runner the boot layer can dispatch to, in match-priority order.
+ *
+ * {@link selectRunner} scans this list front-to-back and returns the first
+ * accepting runner; `replRunner` leads the list and also serves as the default.
+ */
+export declare const RUNNERS: readonly Runner[];
+/**
+ * Choose the runner for a parsed {@link Invocation}.
+ *
+ * Returns the first runner in {@link RUNNERS} that {@link Runner.accepts | accepts}
+ * the invocation; if none does, falls back to the interactive REPL runner so
+ * dispatch is total and a runner is always returned.
+ */
+export declare function selectRunner(inv: Invocation): Runner;

package/dist/types/boot/runners/repl-runner.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Runner: `repl` — interactive terminal session.
+ *
+ * Mounts the Phase-7 console for a live session: it assembles a
+ * {@link SessionConductor} for the invocation and renders the interactive surface
+ * via {@link mountConsole}, seeding it with the positional prompt when one was
+ * supplied. The runner resolves the success exit code once the surface is
+ * dismissed.
+ */
+import type { Runner } from "../contract";
+/**
+ * The interactive-REPL runner.
+ *
+ * {@link Runner.accepts} matches invocations whose resolved mode is `repl`; it is
+ * also the registry default, so it is reached for the empty / interactive command
+ * line. {@link Runner.run} assembles the conductor, honours `--resume` /
+ * `--continue`, and mounts the console.
+ */
+export declare const replRunner: Runner;

package/dist/types/boot/runners/session-persist.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Integration test for session persistence + resume.
+ *
+ * Proves the loop that `-r` / `-c` depend on: a conductor built with a
+ * `sessionsDir` writes the transcript to a cwd-scoped `.ndjson` on disk, the
+ * {@link SessionLibrary} (what the resume flags read) finds it, and a fresh
+ * conductor can `resume` it by id. Before this wiring the conductor defaulted to
+ * an in-memory store, so nothing was ever saved and resume found nothing.
+ */
+export {};