indusagi 0.13.7 → 0.13.8

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

package/dist/types/smithy/forge.d.ts

@@ -0,0 +1,135 @@
+/**
+ * `Forge` — the build session that assembles a new agent.
+ *
+ * The other Smithy layers are each one concern in isolation: the
+ * {@link FlagReader} reads a launch into a {@link SmithyConfig}, {@link defineAgent}
+ * merges a spec over a profile into a validated {@link AgentBlueprint},
+ * {@link toAgentConfig} bridges that blueprint into a runtime `AgentConfig`, the
+ * {@link ToolLedger} accounts for what the session did, and the
+ * {@link TranscriptModel} sanitizes the dialogue for display. The Forge is the
+ * conductor that wires them into a single, drivable build session.
+ *
+ * It runs in two modes:
+ *
+ *   - {@link Forge.buildInteractive} — a short scripted *interview*. It asks the
+ *     user, through the {@link ForgeView} seam, for the agent's name, purpose,
+ *     tool needs, and model preference; folds the answers into a blueprint via
+ *     {@link defineAgent}; records each interview step on a {@link ToolLedger}; and
+ *     keeps the dialogue as a transcript a {@link TranscriptModel} can project.
+ *   - {@link Forge.buildFromConfig} — the non-interactive path. It takes a
+ *     {@link SmithyConfig} (a profile plus pre-supplied `answers`) and produces the
+ *     same kind of blueprint with no I/O at all.
+ *
+ * Finally {@link Forge.instantiate} turns a finished blueprint into a runnable
+ * {@link Agent} by way of {@link toAgentConfig} and `createAgent`.
+ *
+ * The view (and its lone `ask`) is *injected*, never constructed here, so tests
+ * can script the entire interview with canned answers and assert against the
+ * recorded ledger and transcript without ever touching a terminal or the network.
+ */
+import type { Agent } from "../runtime";
+import type { SmithyConfig } from "./config";
+import type { AgentBlueprint } from "./persona";
+import { ToolLedger } from "./runtime";
+import type { ForgeView, RenderTranscript } from "./ui";
+/**
+ * The injectable collaborators a {@link Forge} runs against.
+ *
+ * Both are optional. `view` is the full {@link ForgeView} seam; `ask` is a
+ * convenience override of just its prompt function — handy in tests that only
+ * care about scripting answers and not about captured `show` output. When neither
+ * is given, the Forge falls back to a {@link ConsoleForgeView} over stdio.
+ */
+export interface ForgeOptions {
+    /** The text view the interview reads from and writes to. */
+    readonly view?: ForgeView;
+    /** A prompt function overriding {@link ForgeView.ask} (the interview seam). */
+    readonly ask?: (question: string) => Promise<string>;
+}
+/** The answer keys the interview collects and {@link buildFromConfig} consumes. */
+export type InterviewKey = "name" | "purpose" | "tools" | "model";
+/** The collected interview answers, keyed by {@link InterviewKey}. */
+export type InterviewAnswers = Partial<Record<InterviewKey, string>>;
+/**
+ * The build session.
+ *
+ * Construct one with {@link createForge} (or directly), then call
+ * {@link buildInteractive} or {@link buildFromConfig} to obtain a validated
+ * {@link AgentBlueprint}, and {@link instantiate} to turn that blueprint into a
+ * runnable {@link Agent}. The {@link ledger} and {@link transcript} accessors
+ * expose what the most recent interactive build recorded.
+ */
+export declare class Forge {
+    /** The view the interview talks through; falls back to a console view. */
+    private readonly view;
+    /** The accountant for interview steps, one row per question asked. */
+    private readonly toolLedger;
+    /** The sanitizing projector for the recorded dialogue. */
+    private readonly transcriptModel;
+    /** The raw dialogue turns recorded during {@link buildInteractive}. */
+    private dialogue;
+    constructor(options?: ForgeOptions);
+    /**
+     * Run the scripted interview and return the resulting blueprint.
+     *
+     * Walks the {@link INTERVIEW} script: for each question it `show`s the prompt,
+     * `ask`s through the view, records the answer as a dialogue turn pair, and files
+     * one {@link ToolLedger} row noting the step. Once every answer is in, the
+     * answers are mapped through {@link defineAgent} (seeded by the profile the
+     * "tools" answer implies) into a validated {@link AgentBlueprint}.
+     *
+     * The session state — {@link ledger} and {@link transcript} — is reset at the
+     * start of each call so a reused Forge does not carry a prior interview's rows.
+     *
+     * @param seedProfile Optional starter profile name to seed defaults from.
+     */
+    buildInteractive(seedProfile?: string): Promise<AgentBlueprint>;
+    /**
+     * Build a blueprint non-interactively from a resolved {@link SmithyConfig}.
+     *
+     * No view, no prompting: the answers are read straight from `cfg.answers`, the
+     * starter profile from `cfg.profile`, and an explicit `cfg.model` (if present)
+     * overrides whatever the answers or profile would choose. The same
+     * {@link assemble} mapping is used as the interactive path, so both routes
+     * produce blueprints of identical shape.
+     *
+     * @param cfg The launch configuration (typically from a {@link FlagReader}).
+     */
+    buildFromConfig(cfg: SmithyConfig): AgentBlueprint;
+    /**
+     * Turn a finished blueprint into a runnable {@link Agent}.
+     *
+     * Projects the blueprint onto a runtime `AgentConfig` via {@link toAgentConfig}
+     * (resolving the named tool collection into a real toolbox) and hands it to
+     * `createAgent`. `cwd` roots the agent's tools at a working directory.
+     *
+     * @param blueprint A blueprint already validated by {@link defineAgent}.
+     * @param cwd       Optional working directory for the agent's tools.
+     */
+    instantiate(blueprint: AgentBlueprint, cwd?: string): Agent;
+    /** The ledger of steps recorded by the most recent interactive build. */
+    get ledger(): ToolLedger;
+    /** A sanitized, render-ready projection of the recorded dialogue. */
+    get transcript(): RenderTranscript;
+    /**
+     * Map a set of interview answers (plus an optional profile) into a validated
+     * {@link AgentBlueprint}.
+     *
+     * The "tools" answer, when it names a known tool collection, sets the
+     * blueprint's `toolCollection`; otherwise the profile/baseline default stands.
+     * The "model" answer, when non-empty, overrides the profile's model. `name` and
+     * `purpose` flow straight through to `name` and `description`. The single
+     * validation gate lives inside {@link defineAgent}.
+     */
+    private assemble;
+    /** Append one speaker turn of plain text to the recorded dialogue. */
+    private recordTurn;
+}
+/**
+ * Construct a {@link Forge} build session.
+ *
+ * The thin factory mirrors the rest of the codebase's `create*` convention and
+ * keeps the injectable {@link ForgeOptions} (a scripted view or `ask`) at the call
+ * site, which is what lets tests drive the interview with no real I/O.
+ */
+export declare function createForge(options?: ForgeOptions): Forge;