indusagi 0.12.32 → 0.12.33

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

@@ -0,0 +1,77 @@
+/**
+ * The concrete boot stages, in the order they run.
+ *
+ * This module instantiates the generic {@link Stage} pipeline for the shell
+ * application's {@link BootContext}. The five stages, in order:
+ *
+ *   1. {@link resolveLocator}    — bind the path/branding locator.
+ *   2. {@link loadConfiguration} — read & merge settings, then apply idempotent
+ *      startup upgrades.
+ *   3. {@link resolveModel}      — pick the model id (invocation ▸ settings ▸
+ *      fallback) and validate it against the catalog.
+ *   4. {@link assembleTools}     — build the built-in tool box for the chosen
+ *      collection and, when MCP servers are configured, mount the protocol
+ *      bridge and merge the remote box with the built-in box into one composite
+ *      {@link ToolBox} (registering the fleet's teardown as a closable).
+ *   5. {@link buildAgentFactory} — close over the composite box, the model, and
+ *      the system preamble to expose a ready {@link BootContext.makeAgent}.
+ *
+ * Every integration with the rest of the codebase happens through the four
+ * published seams: {@link createAgent} (runtime), {@link toolBox} (capabilities),
+ * {@link mountProtocolBridge} (interop), and {@link getCard} (llmgateway). No
+ * stage mutates the context it receives; each returns a new one.
+ */
+import type { ToolBox } from "../../runtime";
+import type { Invocation } from "../invocation/parse";
+import type { Stage } from "./pipeline";
+import type { BootContext, BootIo } from "./context";
+/**
+ * The internal, in-progress shape the pipeline reduces over.
+ *
+ * It is the public {@link BootContext} plus the one intermediate value the
+ * stages must hand off but the runners never see: the assembled composite
+ * {@link ToolBox}. Keeping it private to this module lets {@link buildBootContext}
+ * return the narrower {@link BootContext} to callers while the stages share the
+ * wider draft.
+ */
+interface BootDraft extends BootContext {
+    /** The composite tool box, set by {@link assembleTools}, read by the factory. */
+    toolBox?: ToolBox;
+}
+/**
+ * Merge several {@link ToolBox}es into one composite box.
+ *
+ * The composite advertises every constituent box's descriptors, concatenated in
+ * the order the boxes were given (so the built-in tools precede any remote ones).
+ * Its runner routes each {@link ToolCall} to the box that owns the named tool: a
+ * lookup table is built once from each box's descriptors, mapping a tool name to
+ * the runner that fulfils it. A call for an unknown tool resolves to an error
+ * outcome rather than throwing, so one stray name never sinks a whole batch.
+ *
+ * When two boxes advertise the same tool name, the *first* box to claim it wins
+ * the route — built-in tools therefore shadow a remote tool of the same name,
+ * which is the safe default. (The protocol bridge already qualifies remote names
+ * as `"<server>__<tool>"`, so genuine collisions are rare by construction.)
+ *
+ * @param boxes the boxes to compose, in precedence order (earliest wins a tie).
+ * @returns a single {@link ToolBox} over the union.
+ */
+export declare function composeToolBoxes(...boxes: readonly ToolBox[]): ToolBox;
+/** The boot stages, in the order they run. */
+export declare const BOOT_STAGES: readonly Stage<BootDraft>[];
+/**
+ * Build a fully-assembled {@link BootContext} from a parsed invocation and the
+ * I/O seams.
+ *
+ * Seeds an initial draft from the invocation (its `--cwd` flag overrides the
+ * process working directory) and the supplied I/O, then runs every
+ * {@link BOOT_STAGES} stage in order. The resolved draft is returned narrowed to
+ * the public {@link BootContext}; its internal `toolBox` field stays an
+ * implementation detail the runners never touch.
+ *
+ * @param invocation the parsed CLI invocation the stages read from.
+ * @param io the output sink and input source the runners will use.
+ * @returns the assembled boot context.
+ */
+export declare function buildBootContext(invocation: Invocation, io: BootIo): Promise<BootContext>;
+export {};

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

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/**
+ * The command-line entry point — where an `argv` slice becomes a running agent.
+ *
+ * This module is the thin seam between the operating system and the shell app's
+ * machinery. It owns exactly four concerns and delegates everything else:
+ *
+ *   1. Parse the raw `argv` into a structured {@link Invocation} (the
+ *      {@link tokenizeInvocation} table-driven parser).
+ *   2. Short-circuit the two output-only modes — `help` (rendered from the flag
+ *      table) and `version` (read from `package.json`) — without ever standing up
+ *      an agent.
+ *   3. For every running mode, assemble a {@link BootContext} (settings, model,
+ *      tools, agent factory, I/O streams, teardown list) and hand it to the
+ *      {@link selectRunner | selected} runner, returning its exit code.
+ *   4. Run the context's {@link BootContext.closables} on the way out — always,
+ *      success or failure — so MCP fleets and other resources close cleanly.
+ *
+ * It calls neither `process.exit` (the runner resolves an exit code; we set
+ * `process.exitCode` instead) nor any UI toolkit. The interactive surface is a
+ * minimal readline view supplied by the REPL runner. When loaded as the process
+ * entry point, the bottom of the file drives {@link main} and records its result.
+ */
+import type { Invocation } from "./invocation/parse";
+import type { Closable } from "./boot";
+import type { BootContext } from "./runners";
+/** The raw stream pair the CLI feeds the runners. */
+export interface CliStreams {
+    /** Where the runner reads its input (stdin in production). */
+    readonly input: NodeJS.ReadableStream;
+    /** Where the runner writes its output (stdout in production). */
+    readonly output: NodeJS.WritableStream;
+    /** Where diagnostics are routed; defaults to stderr. */
+    readonly error?: NodeJS.WritableStream;
+}
+/**
+ * Assemble the {@link BootContext} a runner consumes from a parsed invocation and
+ * the process streams.
+ *
+ * The boot pipeline (settings → model → tools → agent factory) is shared with the
+ * line-seam boot module; this wrapper threads the real streams onto the resulting
+ * context so the stream-oriented runners (one-shot, wire, repl) can drive it, and
+ * carries the boot pipeline's {@link Closable} list through so the caller can tear
+ * resources down on exit.
+ *
+ * @param invocation the parsed CLI invocation the stages read from.
+ * @param streams the input/output (and optional error) streams the runner uses.
+ * @returns a runner-ready boot context whose `closables` the caller must run.
+ */
+export declare function buildBootContext(invocation: Invocation, streams: CliStreams): Promise<BootContext & {
+    readonly closables: Closable[];
+}>;
+/** Build the full `--help` text from the flag table and the brand name. */
+export declare function renderUsage(): string;
+/**
+ * Resolve the package version, reading `package.json` next to the compiled
+ * bundle and falling back to a constant when it cannot be found (e.g. when the
+ * file is bundled away). Never throws.
+ */
+export declare function resolveVersion(): string;
+/**
+ * Drive one CLI invocation to an exit code.
+ *
+ * Parses `argv`, dispatches the output-only `help`/`version` modes directly, and
+ * for every running mode assembles a {@link BootContext} and hands it to the
+ * selected runner. The context's {@link BootContext.closables} are always run in
+ * a `finally`, in reverse registration order, so teardown happens whether the run
+ * succeeded, failed, or threw. Resolves the process exit code (never calls
+ * `process.exit`).
+ *
+ * @param argv the argument slice after the runtime + script names. Defaults to
+ *   `process.argv.slice(2)`.
+ * @returns the exit code: 0 on success, non-zero on failure.
+ */
+export declare function main(argv?: readonly string[]): Promise<number>;

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

@@ -0,0 +1,11 @@
+/**
+ * Shell-application configuration — public surface.
+ *
+ * Two concerns live here: *where* state is stored ({@link Locator} / {@link Brand})
+ * and *what* the user has configured ({@link Settings} and its loader). Downstream
+ * boot stages import both from this one site.
+ */
+export { BRAND, NodeLocator, } from "./locator";
+export type { Brand, Locator } from "./locator";
+export { DEFAULT_SETTINGS, loadSettings, resolveModelId, } from "./settings";
+export type { Settings, ToolSettings, ToolCollectionName, CompactionSettings, } from "./settings";

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

@@ -0,0 +1,85 @@
+/**
+ * Path & branding resolution for the shell application.
+ *
+ * Every user-visible name — the product name, the on-disk config directory, the
+ * environment-variable prefix — derives from a single {@link Brand} object, so a
+ * rebrand touches exactly one constant. The {@link Locator} interface is the
+ * narrow seam the rest of the shell uses to discover *where* things live on
+ * disk: the profile directory and the files beneath it. It is an interface
+ * (not a concrete class) so tests can hand a fake rooted at a temp directory and
+ * the production binding can memoize.
+ *
+ * This module owns no I/O. {@link NodeLocator} resolves paths against the user's
+ * home directory using `node:os` and `node:path` but never touches the
+ * filesystem; the upgrade and settings layers do the reading and writing.
+ */
+/**
+ * The single source of truth for every user-visible name.
+ *
+ * All on-disk locations and environment-variable names derive from these
+ * fields, so changing the product's identity is a one-line edit here rather
+ * than a hunt through scattered string literals.
+ */
+export interface Brand {
+    /** The product name (e.g. shown in `--version`, process title). */
+    readonly name: string;
+    /** The dotted directory under the user's home that holds all state. */
+    readonly configDir: string;
+    /** Prefix for environment variables this app reads (e.g. `INDUSAGI`). */
+    readonly envPrefix: string;
+}
+/** The default brand identity for this build. */
+export declare const BRAND: Brand;
+/**
+ * Resolves the absolute on-disk locations the shell reads and writes.
+ *
+ * The shape mirrors the layout under the profile directory:
+ *
+ *   <home>/<brand.configDir>/             ← profileDir()
+ *     settings.json                       ← settingsPath()
+ *     auth.json                           ← authPath()
+ *     sessions/                           ← sessionsDir()
+ *     upgrades.json                       ← upgradeMarkerPath()
+ *
+ * A separate project-scoped settings file lives in the working directory under
+ * the same config-dir name; {@link projectSettingsPath} resolves it.
+ *
+ * Implementations must be pure path computation — no filesystem access — so they
+ * are cheap to call repeatedly and trivial to fake in tests.
+ */
+export interface Locator {
+    /** The brand identity these paths derive from. */
+    readonly brand: Brand;
+    /** The per-user profile directory: `<home>/<configDir>`. */
+    profileDir(): string;
+    /** The global settings file inside the profile directory. */
+    settingsPath(): string;
+    /** The project-scoped settings file under `<cwd>/<configDir>`. */
+    projectSettingsPath(cwd: string): string;
+    /** The credential store inside the profile directory. */
+    authPath(): string;
+    /** The directory holding persisted sessions. */
+    sessionsDir(): string;
+    /** The marker file recording which upgrades have already run. */
+    upgradeMarkerPath(): string;
+}
+/**
+ * The production {@link Locator}, rooted at the user's home directory.
+ *
+ * All paths hang off a single `under(...segments)` helper so the layout is
+ * declared once. `home` is injectable purely to make the class testable; it
+ * defaults to {@link homedir}.
+ */
+export declare class NodeLocator implements Locator {
+    readonly brand: Brand;
+    private readonly home;
+    constructor(brand?: Brand, home?: string);
+    /** Join segments under the profile directory. */
+    private under;
+    profileDir(): string;
+    settingsPath(): string;
+    projectSettingsPath(cwd: string): string;
+    authPath(): string;
+    sessionsDir(): string;
+    upgradeMarkerPath(): string;
+}

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";