indusagi 0.12.31 → 0.12.33

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;

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

@@ -0,0 +1,34 @@
+/**
+ * The runner registry — the data-driven replacement for a mode if/else.
+ *
+ * Every concrete {@link Runner} is listed once in {@link RUNNERS}; selecting the
+ * right one for an invocation is a linear scan that returns the first whose
+ * {@link Runner.accepts | accepts} is true. Adding a new way to drive the agent
+ * means appending an entry here — no dispatch ladder to edit.
+ *
+ * Note the registry covers only the *running* modes. The `help` and `version`
+ * modes are pure, output-only concerns the boot/CLI layer renders directly from
+ * the flag table and package metadata, so no runner accepts them and they never
+ * reach {@link selectRunner}.
+ */
+import type { Invocation, Runner } from "./contract";
+/**
+ * The ordered list of runners. Order is significant only as a tie-break: the
+ * three modes are mutually exclusive, so at most one accepts any invocation, but
+ * the scan stops at the first match either way.
+ */
+export declare const RUNNERS: readonly Runner[];
+/**
+ * Thrown when no registered runner can handle an invocation. This is a launcher
+ * bug (e.g. a non-running mode reached the registry), not a user error.
+ */
+export declare class NoRunnerError extends Error {
+    constructor(mode: string);
+}
+/**
+ * Pick the runner for an invocation: the first in {@link RUNNERS} that accepts
+ * it. Throws {@link NoRunnerError} if none match — which should only happen for
+ * the `help`/`version` modes the boot layer is expected to short-circuit before
+ * ever calling here.
+ */
+export declare function selectRunner(invocation: Invocation): Runner;

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

@@ -0,0 +1,51 @@
+/**
+ * The REPL runner — a minimal interactive loop behind the {@link InteractiveView}
+ * seam.
+ *
+ * This is the runner behind the default interactive launch (`repl` mode): read a
+ * line, submit it to the agent, stream the answer back, repeat until the user
+ * leaves or input ends. It is deliberately *minimal* — a plain readline loop
+ * with line-oriented console output and no cursor tricks, colours, or layout.
+ *
+ * The presentation lives entirely behind the {@link InteractiveView} seam. This
+ * file ships one trivial implementation, {@link TextView}, that does plain text
+ * writes over a readline interface. THIS IS A PLACEHOLDER: a richer terminal UI
+ * is expected to implement the same `render`/`prompt`/`close` interface and be
+ * injected via {@link BootContext.view}, at which point this runner drives it
+ * unchanged. Keeping the loop UI-agnostic is the whole point — nothing here
+ * imports a UI toolkit, and nothing here will need to change when one arrives.
+ */
+import { type InteractiveView, type RunEvent, type Runner } from "./contract";
+/**
+ * The default plain-text {@link InteractiveView}.
+ *
+ * A thin wrapper over `node:readline`: {@link prompt} asks for one line and
+ * resolves it (rejecting with {@link EndOfInput} on EOF / Ctrl-D), and
+ * {@link render} writes streamed text deltas inline and a single newline once a
+ * turn settles. It owns nothing the agent needs to know about — it is the
+ * stand-in the seam exists for.
+ */
+export declare class TextView implements InteractiveView {
+    private readonly input;
+    private readonly output;
+    private readonly rl;
+    /** Set once the underlying stream signals end-of-input. */
+    private ended;
+    /** True while we are mid-assistant-turn, so settle knows to break the line. */
+    private midTurn;
+    constructor(input: NodeJS.ReadableStream, output: NodeJS.WritableStream);
+    /** Present one run event as plain text. */
+    render(event: RunEvent): void;
+    /**
+     * Ask for one line of input, rejecting with {@link EndOfInput} once the input
+     * stream has closed.
+     */
+    prompt(): Promise<string>;
+    /** Tear down the readline interface. Safe to call more than once. */
+    close(): void;
+}
+/**
+ * The interactive runner. Accepts the `repl` mode the parser derives for an
+ * attended, prompt-less launch.
+ */
+export declare const ReplRunner: Runner;

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

@@ -0,0 +1,34 @@
+/**
+ * The wire runner — a line-delimited JSON protocol over stdio.
+ *
+ * This is the machine-facing runner behind `--json` (a.k.a. `--rpc`/`--wire`):
+ * a host process speaks to the agent by writing one JSON request per line and
+ * reads back one JSON event per line. It is the integration seam for editors,
+ * orchestrators, and test harnesses that want structured access to the run
+ * rather than rendered prose.
+ *
+ * Protocol (every message is a single line of JSON, newline-terminated):
+ *
+ *   Requests (host → runner):
+ *     { "type": "submit", "input": "<prompt text>" }
+ *
+ *   Responses (runner → host):
+ *     { "type": "event",  "event": <RunEvent> }   — one per live run event
+ *     { "type": "result", "snapshot": <RunSnapshot> } — once per settled submit
+ *     { "type": "error",  "message": "<why>" }    — a protocol/parse failure
+ *
+ * The reader is robust to partial lines: bytes are accumulated into a buffer and
+ * only complete `\n`-delimited lines are parsed, so a request split across two
+ * chunks is handled correctly. Blank lines are ignored; a line that is not valid
+ * JSON, or not a recognised request, yields an `error` response and the loop
+ * continues rather than tearing down the connection.
+ *
+ * The runner resolves its exit code when the input stream ends (EOF): 0 in the
+ * normal case.
+ */
+import type { Runner } from "./contract";
+/**
+ * The line-delimited JSON runner. Accepts the `wire` mode the parser derives
+ * from `--json`/`--rpc`/`--wire`.
+ */
+export declare const WireRunner: Runner;

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

@@ -0,0 +1,14 @@
+/**
+ * Behavioural tests for the assembled shell application.
+ *
+ * Five scenarios cover the seams that turn a command line into a running agent,
+ * with no network anywhere: every model turn is a scripted {@link ModelInvoker}
+ * replayed as a {@link Channel}, injected through the agent factory's deps.
+ *
+ *   1. tokenizeInvocation — flag/mode derivation for the common spellings.
+ *   2. Locator + applyUpgrades — sandboxed path math and idempotent upgrades.
+ *   3. loadSettings — a project file overriding the built-in defaults.
+ *   4. OneShotRunner — a scripted "hello" streamed to a captured output stream.
+ *   5. WireRunner — one JSON submit line in, JSON event + result lines out.
+ */
+export {};

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

@@ -0,0 +1,9 @@
+/**
+ * Shell-application startup upgrades — public surface.
+ *
+ * Exposes the idempotent upgrade vocabulary ({@link Upgrade}), the declared set
+ * ({@link UPGRADES}), and the runner ({@link applyUpgrades}) the boot layer calls
+ * once on start-up.
+ */
+export { UPGRADES, applyUpgrades } from "./upgrades";
+export type { Upgrade } from "./upgrades";

package/dist/types/shell-app/upgrade/upgrades.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Idempotent startup upgrades for the shell application.
+ *
+ * On boot the shell may need to perform one-time housekeeping: create a missing
+ * directory, move a file to a new location, rewrite a stale config shape. Each
+ * such chore is an {@link Upgrade} — a small object with a stable, human-chosen
+ * `id` and an `apply` step. The set is *keyed by id rather than by a sequential
+ * version number*: an upgrade runs at most once across the lifetime of an
+ * install, and adding, reordering, or removing entries never disturbs which
+ * other upgrades are considered "done".
+ *
+ * {@link applyUpgrades} reads a tiny marker file listing the ids that have
+ * already run, applies only the rest in declaration order, records each success,
+ * and returns the ids it applied this pass. Re-running it is a no-op once every
+ * upgrade is recorded, which is what makes startup cheap and safe to repeat.
+ *
+ * Failures are contained: if one upgrade throws, the ids that already succeeded
+ * this pass are still persisted, and the error propagates so the boot layer can
+ * decide how loud to be. The marker file itself is read forgivingly — a missing
+ * or corrupt marker is treated as "nothing has run yet".
+ */
+import type { Locator } from "../config/locator";
+/**
+ * One idempotent boot-time chore.
+ *
+ * `id` is the identity used to remember whether this upgrade has run; it must be
+ * stable forever once shipped (renaming an id re-runs the upgrade). `description`
+ * is for logs and humans only. `apply` performs the work and must itself be safe
+ * to run on an already-upgraded install, since the marker file could be lost.
+ */
+export interface Upgrade {
+    /** Stable, unique identity used to record completion. Never renamed. */
+    readonly id: string;
+    /** Human-readable summary of what the upgrade does. */
+    readonly description: string;
+    /** Perform the upgrade. Should tolerate already-applied state. */
+    apply(locator: Locator): Promise<void>;
+}
+/**
+ * The ordered set of upgrades this build knows about.
+ *
+ * Order matters only for upgrades within a single boot that have not yet run;
+ * completion is tracked per-id, so inserting a new upgrade anywhere is safe.
+ *
+ * Seeded with two trivial, self-evidently-idempotent examples:
+ *   - `ensure-profile-dir`  — guarantee the per-user profile directory exists.
+ *   - `ensure-sessions-dir` — guarantee the sessions subdirectory exists.
+ */
+export declare const UPGRADES: readonly Upgrade[];
+/**
+ * Run every upgrade that has not yet been applied, in declaration order.
+ *
+ * Reads the marker, applies each {@link UPGRADES} entry whose id is absent,
+ * records each success immediately into the in-memory set, and flushes the
+ * marker once at the end. Returns the ids applied during *this* call (empty when
+ * the install is already fully upgraded).
+ *
+ * If an upgrade throws, the marker is still flushed with whatever succeeded
+ * before the failure, then the error is re-thrown — so a retry will skip the
+ * work already done.
+ */
+export declare function applyUpgrades(locator: Locator): Promise<string[]>;

package/dist/types/smithy/config/flag-reader.d.ts

@@ -0,0 +1,128 @@
+/**
+ * `FlagReader` — a token-consuming state machine for Smithy's own CLI flags.
+ *
+ * Smithy (the agent-builder meta-tool) is launched with its own small slice of
+ * command-line options: which starter profile to seed from, where the generated
+ * agent should be written, an explicit model override, a non-interactive switch,
+ * and any number of pre-supplied interview answers. This module turns the raw
+ * `argv` slice into a {@link SmithyConfig}.
+ *
+ * Unlike the shell-app's stateless cursor-walk parser, this reader is an
+ * *explicit finite-state machine*. It walks the argv one token at a time and
+ * lives in exactly one of three states:
+ *
+ *   - `expectFlag`  — the resting state. The next token must name a flag (or be a
+ *                     glued `--flag=value`, or a bare `--` terminator). A boolean
+ *                     flag is settled here and we stay in `expectFlag`; a
+ *                     value-taking flag with no glued value advances to
+ *                     `expectValue`.
+ *   - `expectValue` — we have seen a value-taking flag and are owed its argument.
+ *                     The next token is consumed verbatim as that value and we
+ *                     fall back to `expectFlag`.
+ *   - `done`        — a bare `--` terminator was reached; every remaining token is
+ *                     ignored (Smithy takes no positionals).
+ *
+ * The set of recognised flags lives in one {@link FLAG_TABLE}, so adding a flag
+ * is a single table entry, never a new branch in the walk. The reader is pure: it
+ * reads only the array handed to it and never touches `process`, the
+ * environment, or the filesystem.
+ */
+/** The flags Smithy understands and how each one is shaped. */
+export type SmithyFlagName = "profile" | "out" | "model" | "non-interactive" | "answer";
+/** Whether a flag carries a value, and (if so) how its value is filed. */
+type FlagKind = 
+/** A bare switch: present ⇒ true. */
+"switch"
+/** A single value that overwrites (last spelling wins). */
+ | "single"
+/** A repeatable `key=value` pair folded into the answers map. */
+ | "pair";
+/** One row of the recognised-flag table. */
+interface FlagSpec {
+    /** The canonical flag name (without leading dashes). */
+    readonly name: SmithyFlagName;
+    /** Every spelling that selects this flag, e.g. `--out`, `-o`. */
+    readonly spellings: readonly string[];
+    /** Whether the flag takes a value and how it is recorded. */
+    readonly kind: FlagKind;
+}
+/**
+ * The single source of recognised flags. The walk below contains no per-flag
+ * branches — it only consults this table.
+ */
+declare const FLAG_TABLE: readonly FlagSpec[];
+/**
+ * The resolved Smithy launch configuration.
+ *
+ * Every field is optional except by intent: a launch with no flags yields an
+ * empty record, and each consumer applies its own default. `answers` collects any
+ * `--answer key=value` pairs the user pre-supplied so a non-interactive run can
+ * skip the interview.
+ */
+export interface SmithyConfig {
+    /** The starter profile to seed the blueprint from (e.g. `coder`). */
+    profile?: string;
+    /** Destination path for the generated agent file. */
+    out?: string;
+    /** An explicit model id, overriding whatever the profile would pick. */
+    model?: string;
+    /** When true, run without prompting — rely on `answers` and defaults. */
+    nonInteractive?: boolean;
+    /** Pre-supplied interview answers, keyed by question name. */
+    answers?: Record<string, string>;
+}
+/** Thrown when an argv slice cannot be read into a valid {@link SmithyConfig}. */
+export declare class FlagError extends Error {
+    constructor(message: string);
+}
+/**
+ * A token-consuming state machine that reads Smithy CLI flags.
+ *
+ * Construct one and call {@link read} with the argv slice (already stripped of
+ * the runtime and script names). The machine is single-use per `read` call —
+ * each call resets its internal state — and reports a malformed invocation by
+ * throwing {@link FlagError}.
+ */
+export declare class FlagReader {
+    /** Current position in the state machine. */
+    private state;
+    /** The flag awaiting its value while in `expectValue`. */
+    private pending;
+    /** The accumulating result, written as tokens are consumed. */
+    private config;
+    /**
+     * Read an argv slice into a {@link SmithyConfig}.
+     *
+     * Performs a single left-to-right pass, feeding each token to the active state.
+     * A trailing value-taking flag left without its argument is an error.
+     */
+    read(argv: readonly string[]): SmithyConfig;
+    /** Clear all state so the reader can be reused. */
+    private reset;
+    /**
+     * Handle a token while resting in `expectFlag`.
+     *
+     * Recognises the bare `--` terminator, a glued `--flag=value`, a value-taking
+     * flag (which arms `expectValue`), and a switch (settled immediately).
+     */
+    private onFlag;
+    /** Handle the token owed to the {@link pending} value-taking flag. */
+    private onValue;
+    /** Record a switch flag turning its slot on. */
+    private fileSwitch;
+    /** File a resolved value under the slot its spec names. */
+    private fileValue;
+    /**
+     * Fold one `key=value` interview answer into the answers map. A pair missing
+     * its `=` separator, or with an empty key, is rejected.
+     */
+    private fileAnswer;
+}
+/**
+ * Convenience entry point: read an argv slice into a {@link SmithyConfig} with a
+ * fresh {@link FlagReader}. Pass `process.argv.slice(2)` from a launcher.
+ */
+export declare function readFlags(argv: readonly string[]): SmithyConfig;
+/** Re-export the recognised-flag table for help rendering and tests. */
+export { FLAG_TABLE };
+export type { FlagSpec };

package/dist/types/smithy/config/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Smithy config layer — public surface.
+ *
+ * The flag state machine that reads Smithy's own CLI into a {@link SmithyConfig}.
+ * A launcher imports {@link FlagReader} (or the {@link readFlags} convenience) from
+ * here and nothing reaches into the module directly.
+ */
+export { FlagReader, FlagError, readFlags, FLAG_TABLE, } from "./flag-reader";
+export type { SmithyConfig, SmithyFlagName, FlagSpec } from "./flag-reader";