indusagi 0.12.32 → 0.12.34

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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;
+}