indusagi 0.12.32 → 0.12.33

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;

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

@@ -0,0 +1,36 @@
+/**
+ * Smithy — the agent-builder meta-tool.
+ *
+ * Smithy is a leaf product surface: a tool whose job is to help a user design and
+ * generate new agents that run on the runtime. This is the package's single
+ * import site, re-exporting the layers built so far:
+ *
+ *   - `config`  — the {@link FlagReader} state machine that reads Smithy's CLI
+ *                 into a {@link SmithyConfig}.
+ *   - `persona` — the {@link AgentBlueprint} shape and validation, the starter
+ *                 {@link PROFILES} table, and the {@link defineAgent} generator
+ *                 (plus its {@link toAgentConfig} runtime bridge) that turn a
+ *                 partial spec into a validated, runnable agent description.
+ *   - `knowledge` — the externalised guide pack: a `manifest.json` plus markdown
+ *                 guides, loaded into a {@link KnowledgePack} by
+ *                 {@link loadKnowledge} for Smithy to consult while authoring.
+ *   - `runtime` — the stateful session bookkeeping, currently the
+ *                 {@link ToolLedger} that accounts for tool executions during a
+ *                 build.
+ *   - `ui`      — the render seam: the {@link TranscriptModel} visitor that
+ *                 sanitizes and projects a build transcript, and the minimal text
+ *                 {@link ForgeView} the builder loop talks to.
+ *   - `forge`   — the {@link Forge} build session that wires all of the above
+ *                 into an interactive (or config-driven) agent-builder and
+ *                 instantiates the finished blueprint into a runnable agent.
+ *
+ * The interactive view layer is kept behind {@link ForgeView}, a minimal text
+ * seam free of any terminal toolkit.
+ */
+export * from "./config";
+export * from "./persona";
+export * from "./knowledge";
+export * from "./runtime";
+export * from "./ui";
+export { Forge, createForge } from "./forge";
+export type { ForgeOptions, InterviewKey, InterviewAnswers, } from "./forge";

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

@@ -0,0 +1,10 @@
+/**
+ * Smithy knowledge layer — public surface.
+ *
+ * The externalised knowledge pack: a `manifest.json` cataloguing the guide docs
+ * and the markdown bodies under `guides/`, loaded into memory by
+ * {@link loadKnowledge}. A consumer imports the loader from here and reads guides
+ * by id without touching the filesystem layout directly.
+ */
+export { loadKnowledge, KnowledgeError, } from "./loader";
+export type { KnowledgePack, KnowledgeManifest, GuideManifestEntry, Guide, } from "./loader";

package/dist/types/smithy/knowledge/loader.d.ts

@@ -0,0 +1,64 @@
+/**
+ * `loadKnowledge` — read Smithy's knowledge pack off disk into a {@link KnowledgePack}.
+ *
+ * The knowledge pack used to live as one big inline constant baked into the
+ * source. That made it invisible to anyone editing the prose, impossible to diff
+ * sensibly, and welded the docs to the build. Here it is *externalised*: a
+ * `manifest.json` lists the guides by id, title, file, and summary, and each
+ * guide is a plain markdown file beside it under `guides/`. This loader is the
+ * single seam that turns those files back into structured, in-memory data the
+ * rest of Smithy can consult.
+ *
+ * The manifest is the source of truth for *which* guides exist and how they are
+ * described; the markdown files are the source of truth for their *bodies*. The
+ * loader reads the manifest first, then pulls each referenced file, so a guide
+ * that is listed but missing on disk surfaces as a clear error rather than a
+ * silent gap.
+ */
+/** One guide's manifest entry: how it is catalogued, plus where its body lives. */
+export interface GuideManifestEntry {
+    /** Stable, file-safe identifier used to look the guide up. */
+    readonly id: string;
+    /** Human-readable title. */
+    readonly title: string;
+    /** Path to the guide's markdown body, relative to the manifest. */
+    readonly file: string;
+    /** One-line description of what the guide covers. */
+    readonly summary: string;
+}
+/** The parsed shape of `manifest.json` before bodies are attached. */
+export interface KnowledgeManifest {
+    /** Manifest schema/content version. */
+    readonly version: string;
+    /** The guides this pack ships, in catalogue order. */
+    readonly guides: readonly GuideManifestEntry[];
+}
+/** One fully-loaded guide: its manifest metadata plus its markdown body. */
+export interface Guide extends GuideManifestEntry {
+    /** The guide's markdown body, read from {@link GuideManifestEntry.file}. */
+    readonly body: string;
+}
+/** The whole knowledge pack: the manifest version plus every loaded guide. */
+export interface KnowledgePack {
+    /** The manifest's declared version. */
+    readonly version: string;
+    /** Every guide, with its body attached, in manifest order. */
+    readonly guides: readonly Guide[];
+    /** Look a guide up by its {@link Guide.id}; `undefined` if absent. */
+    guide(id: string): Guide | undefined;
+}
+/** Raised when the knowledge pack cannot be loaded or fails its shape check. */
+export declare class KnowledgeError extends Error {
+    constructor(message: string);
+}
+/**
+ * Load the knowledge pack from `dir` (defaults to this module's own directory).
+ *
+ * Reads and validates `manifest.json`, then reads each guide's markdown body,
+ * resolving file paths relative to the manifest. The returned pack is frozen and
+ * carries a {@link KnowledgePack.guide} lookup. Any missing or malformed input
+ * surfaces as a {@link KnowledgeError}.
+ *
+ * @param dir Optional directory holding `manifest.json` and `guides/`.
+ */
+export declare function loadKnowledge(dir?: string): Promise<KnowledgePack>;

package/dist/types/smithy/persona/blueprint.d.ts

@@ -0,0 +1,75 @@
+/**
+ * `AgentBlueprint` — the validated description of one agent Smithy can mint.
+ *
+ * A blueprint is the small, declarative spec that fully determines a generated
+ * agent: its name, a one-line description, the system prompt that gives it its
+ * voice, which slice of the tool surface it is trusted with, the model that backs
+ * it, and optional free-form tags for cataloguing. It is the unit that flows
+ * through Smithy's persona layer — profiles supply partial blueprints, the
+ * {@link defineAgent} generator merges and completes them, and the runtime
+ * adapter turns a finished blueprint into a runnable `AgentConfig`.
+ *
+ * Everything here is *data plus validation*. The shape is mirrored by a zod
+ * schema so a blueprint that arrives from disk, a profile table, or a user-typed
+ * spec is checked before anything downstream trusts it. The tool-collection
+ * literal union is intentionally identical to the three named collections the
+ * capabilities layer publishes (`read-only` / `coding` / `all`); it is kept as a
+ * local union so this schema validates standalone without importing that type.
+ */
+import { z } from "zod";
+/**
+ * The tool surface a generated agent is granted, named to match the capabilities
+ * layer's collections:
+ *   - `read-only` — observe the workspace and the web; never mutate.
+ *   - `coding`    — read-only plus write/edit/bash/todo/process.
+ *   - `all`       — every registered tool.
+ */
+export type ToolCollectionName = "read-only" | "coding" | "all";
+/** The complete, validated description of an agent to be generated. */
+export interface AgentBlueprint {
+    /** A short, file-safe identifier for the agent (e.g. `code-reviewer`). */
+    readonly name: string;
+    /** A one-line summary of what the agent is for. */
+    readonly description: string;
+    /** The system prompt that establishes the agent's role and behaviour. */
+    readonly systemPrompt: string;
+    /** Which slice of the built-in tool surface the agent may call. */
+    readonly toolCollection: ToolCollectionName;
+    /** The model id the agent's runs are bound to. */
+    readonly model: string;
+    /** Optional free-form labels for grouping and search. */
+    readonly tags?: readonly string[];
+}
+/** zod schema mirroring {@link AgentBlueprint}; the validation source of truth. */
+export declare const agentBlueprintSchema: z.ZodType<AgentBlueprint>;
+/** Raised when a candidate object fails {@link agentBlueprintSchema}. */
+export declare class BlueprintError extends Error {
+    /** The individual validation issues, in `path: message` form. */
+    readonly issues: readonly string[];
+    constructor(issues: readonly string[]);
+}
+/**
+ * Validate an arbitrary value as an {@link AgentBlueprint}, throwing a
+ * {@link BlueprintError} (with every issue collected) when it does not conform.
+ *
+ * Returns a fresh, typed object on success so callers never alias the input.
+ */
+export declare function validateBlueprint(candidate: unknown): AgentBlueprint;
+/**
+ * Non-throwing variant of {@link validateBlueprint}: returns the typed blueprint
+ * or `undefined`, for callers that prefer to branch rather than catch.
+ */
+export declare function tryValidateBlueprint(candidate: unknown): AgentBlueprint | undefined;
+/**
+ * Serialize a blueprint to canonical, stable, pretty-printed JSON.
+ *
+ * Keys are emitted in a fixed order (independent of the object's own key order)
+ * so two equal blueprints always produce byte-identical text — handy for diffing,
+ * caching, and writing to a manifest.
+ */
+export declare function serializeBlueprint(blueprint: AgentBlueprint): string;
+/**
+ * Parse JSON text back into a validated {@link AgentBlueprint}. Malformed JSON
+ * and schema failures both surface as a {@link BlueprintError}.
+ */
+export declare function deserializeBlueprint(text: string): AgentBlueprint;

package/dist/types/smithy/persona/define-agent.d.ts

@@ -0,0 +1,51 @@
+/**
+ * `defineAgent` — the single blueprint generator, and `toAgentConfig` — the
+ * bridge from a finished blueprint into the runtime's `AgentConfig`.
+ *
+ * Where a naive design ships a family of `createReviewAgent` / `createCoderAgent`
+ * / `createResearchAgent` factories that differ only by a tool factory and a few
+ * prompt lines, Smithy ships *one* generator over a data table. {@link defineAgent}
+ * takes a caller's spec (which must at least name the agent), optionally seeds it
+ * from a starter {@link PROFILES | profile}, merges the two with the spec winning
+ * on every field, fills any remaining gap from a baseline default, and validates
+ * the completed object as an {@link AgentBlueprint}. The result is a fully-formed,
+ * checked blueprint — or a {@link BlueprintError} if the merge could not satisfy
+ * the schema.
+ *
+ * {@link toAgentConfig} is the second half: it turns that validated blueprint into
+ * the immutable `AgentConfig` the agent runtime consumes, resolving the named tool
+ * collection into a runnable `ToolBox` via the capabilities layer.
+ */
+import type { AgentConfig } from "../../runtime";
+import { type AgentBlueprint } from "./blueprint";
+/** The minimum a caller must supply: at least the agent's name. */
+export type AgentSpec = Partial<AgentBlueprint> & {
+    name: string;
+};
+/**
+ * Build a complete, validated {@link AgentBlueprint} from a partial spec and an
+ * optional starter profile.
+ *
+ * Precedence, highest first: the caller's `spec`, then the named `profile`'s
+ * defaults, then the module {@link BASELINE}. `tags` from the spec replace (do not
+ * merge with) the profile's tags, so a caller stays in full control of labelling.
+ *
+ * @param spec    The caller's blueprint fragment; must include `name`.
+ * @param profile Optional starter profile name (e.g. `coder`); ignored if absent.
+ * @throws BlueprintError when the merged result fails schema validation, or when
+ *         a non-empty `profile` does not name a known profile.
+ */
+export declare function defineAgent(spec: AgentSpec, profile?: string): AgentBlueprint;
+/**
+ * Project a validated {@link AgentBlueprint} onto the runtime's immutable
+ * {@link AgentConfig}.
+ *
+ * The blueprint's `systemPrompt` becomes the config's `system` preamble, the
+ * `model` is passed through, and the named `toolCollection` is resolved into a
+ * runnable `ToolBox` by the capabilities layer. `cwd` roots the resulting tools
+ * at a working directory (defaults to the process cwd inside `toolBox`).
+ *
+ * @param blueprint A blueprint that has already passed {@link defineAgent}.
+ * @param cwd       Optional working directory the tools operate within.
+ */
+export declare function toAgentConfig(blueprint: AgentBlueprint, cwd?: string): AgentConfig;

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

@@ -0,0 +1,14 @@
+/**
+ * Smithy persona layer — public surface.
+ *
+ * The blueprint type + its validation/serialization helpers, the starter profile
+ * table, and the single {@link defineAgent} generator with its {@link toAgentConfig}
+ * runtime bridge. Together these turn a partial spec into a validated, runnable
+ * agent description.
+ */
+export { agentBlueprintSchema, BlueprintError, validateBlueprint, tryValidateBlueprint, serializeBlueprint, deserializeBlueprint, } from "./blueprint";
+export type { AgentBlueprint, ToolCollectionName } from "./blueprint";
+export { PROFILES, PROFILE_NAMES, isProfileName, getProfile, } from "./profiles";
+export type { AgentProfile, ProfileName } from "./profiles";
+export { defineAgent, toAgentConfig } from "./define-agent";
+export type { AgentSpec } from "./define-agent";

package/dist/types/smithy/persona/profiles.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `PROFILES` — Smithy's starter agent templates.
+ *
+ * A *profile* is a named, partial {@link AgentBlueprint}: the sensible-default
+ * skeleton for a common kind of agent. It is deliberately incomplete — it never
+ * fixes a `name` (that is the one thing a caller must always supply) — but it
+ * pins the defaults that distinguish, say, a read-only researcher from a
+ * file-mutating coder: the tool collection, a baseline model, a starter system
+ * prompt, and a description.
+ *
+ * The {@link defineAgent} generator merges a chosen profile *under* a caller's
+ * spec (spec wins on every field) and validates the result. So the profile table
+ * collapses what would otherwise be a family of near-identical `create*Agent`
+ * factory functions into one data table plus one generator. Adding a new kind of
+ * starter agent is a single entry here, not a new function.
+ *
+ * All prose below — every description and system prompt — is original to this
+ * codebase.
+ */
+import type { AgentBlueprint } from "./blueprint";
+/**
+ * A profile is a partial blueprint with `name` removed: the one field a profile
+ * never decides on the caller's behalf.
+ */
+export type AgentProfile = Partial<Omit<AgentBlueprint, "name">>;
+/** The names of the starter profiles this module ships. */
+export type ProfileName = "coder" | "researcher" | "reviewer";
+/**
+ * The starter profile table.
+ *
+ * Each entry is a complete-enough skeleton that, combined with a name, validates
+ * as a blueprint on its own — so `defineAgent({ name }, "researcher")` works with
+ * no further input.
+ */
+export declare const PROFILES: Readonly<Record<ProfileName, AgentProfile>>;
+/** The profile names as an array, for menus and validation. */
+export declare const PROFILE_NAMES: readonly ProfileName[];
+/** Type guard: whether a string names a known profile. */
+export declare function isProfileName(value: string): value is ProfileName;
+/**
+ * Look up a profile by name. Returns the partial blueprint, or `undefined` when
+ * the name is not in the table.
+ */
+export declare function getProfile(name: string): AgentProfile | undefined;

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

@@ -0,0 +1,9 @@
+/**
+ * Smithy runtime layer — public surface.
+ *
+ * The stateful session-level bookkeeping that backs a Smithy build. For now this
+ * is the {@link ToolLedger}, which keeps an append-only account of tool
+ * executions and the running per-tool aggregates derived from them.
+ */
+export { ToolLedger } from "./tool-ledger";
+export type { ToolEvent, LedgerEntry, ToolTally, LedgerSummary, } from "./tool-ledger";

package/dist/types/smithy/runtime/tool-ledger.d.ts

@@ -0,0 +1,130 @@
+/**
+ * `ToolLedger` — a stateful record of tool activity across a build session.
+ *
+ * While Smithy designs an agent it leans on the underlying runtime tools (read a
+ * file, run a command, search the tree, and so on). Something has to keep a
+ * running account of which tools fired, with what, and whether each call landed.
+ * The old shape of this was a pure reducer: a single function folded a list of
+ * executions into a fresh summary on every call, recomputing the whole picture
+ * from the start each time it was asked.
+ *
+ * This module replaces that fold with a long-lived object. A `ToolLedger` owns
+ * its history and is mutated as the session runs. It keeps two things in step:
+ *
+ *   - an *append-only log* — every {@link record} call pushes one
+ *     {@link LedgerEntry} onto the end and nothing is ever rewritten or removed;
+ *   - a set of *derived aggregates* — per-tool counts and a failure tally that are
+ *     advanced incrementally on each append, never rebuilt by re-walking the log.
+ *
+ * Because the aggregates ride along with the log, {@link summary} is a cheap read
+ * of already-settled numbers rather than a fold. {@link reset} returns the ledger
+ * to its just-constructed state so one instance can serve a fresh session.
+ *
+ * The class holds no I/O and no clock of its own beyond an optional caller-stamped
+ * time on each record; it only accounts for what it is told.
+ */
+/** A single tool invocation as the ledger was asked to remember it. */
+export interface ToolEvent {
+    /** The tool's name, e.g. `read-file` or `run-command`. */
+    readonly tool: string;
+    /** The arguments the tool was called with, as the caller saw them. */
+    readonly input?: unknown;
+    /** Whatever the tool produced (a result, an error payload, anything). */
+    readonly output?: unknown;
+    /** Whether the call is considered to have succeeded. */
+    readonly ok: boolean;
+}
+/**
+ * One settled row of the ledger: the event the caller recorded, plus the
+ * bookkeeping the ledger stamped onto it as it filed the row.
+ */
+export interface LedgerEntry extends ToolEvent {
+    /** 1-based position in the append order; also the count after this row. */
+    readonly seq: number;
+    /** When the row was filed (epoch ms), defaulting to filing time. */
+    readonly at: number;
+}
+/** The per-tool slice of a {@link LedgerSummary}. */
+export interface ToolTally {
+    /** Total calls recorded for this tool. */
+    readonly calls: number;
+    /** How many of those calls succeeded (`ok: true`). */
+    readonly ok: number;
+    /** How many failed (`ok: false`); always `calls - ok`. */
+    readonly failed: number;
+}
+/**
+ * A point-in-time digest of everything the ledger has seen.
+ *
+ * `byTool` carries one {@link ToolTally} per distinct tool name. The top-level
+ * fields are session-wide rollups so a caller never has to sum the map by hand.
+ */
+export interface LedgerSummary {
+    /** Total calls recorded across every tool. */
+    readonly total: number;
+    /** Total successful calls across every tool. */
+    readonly ok: number;
+    /** Total failed calls across every tool. */
+    readonly failed: number;
+    /** Number of distinct tool names that have fired at least once. */
+    readonly tools: number;
+    /** Per-tool breakdown, keyed by tool name. */
+    readonly byTool: Record<string, ToolTally>;
+}
+/**
+ * A stateful, append-style account of tool executions for one build session.
+ *
+ * Construct one per session, feed it each tool result through {@link record}, and
+ * read {@link entries} or {@link summary} whenever a snapshot is wanted. The
+ * derived counts are kept current as records arrive, so reads never re-fold the
+ * log.
+ */
+export declare class ToolLedger {
+    /** The append-only history; never spliced, only pushed. */
+    private readonly log;
+    /** Live per-tool counters, advanced one record at a time. */
+    private readonly counters;
+    /** Session-wide rollups, kept in step with {@link counters}. */
+    private totalCalls;
+    private totalOk;
+    private totalFailed;
+    /**
+     * File one tool execution.
+     *
+     * Appends a stamped {@link LedgerEntry} to the log and advances the per-tool and
+     * session-wide aggregates by exactly this one event. Returns the filed entry so
+     * a caller can read its assigned `seq` / `at`.
+     *
+     * @param event  The execution to remember.
+     * @param at     Optional epoch-ms timestamp; defaults to `Date.now()`.
+     */
+    record(event: ToolEvent, at?: number): LedgerEntry;
+    /**
+     * The append-only log, oldest first.
+     *
+     * Returns a shallow copy so a caller cannot mutate the ledger's history through
+     * the returned array. The {@link LedgerEntry} rows are themselves read-only.
+     */
+    entries(): readonly LedgerEntry[];
+    /**
+     * A digest built from the live aggregates — counts per tool and the failure
+     * tally — without re-walking the log.
+     *
+     * The returned object is a fresh, detached snapshot: the `byTool` map and each
+     * tally are copied out so later records don't reach back into it.
+     */
+    summary(): LedgerSummary;
+    /** True once at least one execution has been recorded. */
+    get size(): number;
+    /**
+     * Clear the log and every derived aggregate, returning the ledger to its
+     * freshly-constructed state so the same instance can serve a new session.
+     */
+    reset(): void;
+    /**
+     * Fold a single freshly-filed entry into the running aggregates. This is the
+     * only place the counters move, which is what keeps {@link summary} a read
+     * rather than a recomputation.
+     */
+    private advance;
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Smithy build-session tests.
+ *
+ * These exercise the agent-builder end to end with NO real I/O and NO network:
+ * the interview is driven by a scripted `ask` that returns canned answers, the
+ * knowledge pack is read from the on-disk manifest the loader ships beside it,
+ * and tool collections are resolved through the real capabilities layer (which
+ * only describes tools here — none are run).
+ *
+ * Coverage:
+ *   (1) FlagReader parses a flag line into a SmithyConfig; bad/missing values throw.
+ *   (2) defineAgent merges a spec over a profile, validates, and rejects a bad name.
+ *   (3) buildInteractive over a scripted ask() produces the expected blueprint and
+ *       records the steps on the ToolLedger and into the TranscriptModel.
+ *   (4) buildFromConfig (non-interactive) yields a blueprint whose toAgentConfig
+ *       resolves tools from the right collection.
+ *   (5) loadKnowledge reads the manifest plus at least three guides.
+ *   (6) TranscriptModel redacts a secret-looking token and collapses a huge blob.
+ */
+export {};

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

@@ -0,0 +1,11 @@
+/**
+ * Smithy UI layer — public surface.
+ *
+ * The render seam between the gateway's wire transcript and a person: the
+ * {@link TranscriptModel} visitor that sanitizes and projects turns into a
+ * {@link RenderTranscript}, and the minimal text {@link ForgeView} seam (with its
+ * default {@link ConsoleForgeView}) the builder loop talks to. No terminal
+ * toolkit is imported here; a richer view is added by implementing `ForgeView`.
+ */
+export { TranscriptModel, DEFAULT_VISITORS, DEFAULT_SANITIZE_OPTIONS, ConsoleForgeView, formatTranscript, } from "./transcript";
+export type { RenderBlockKind, RenderRole, RenderBlock, RenderTurn, RenderTranscript, SanitizeOptions, VisitContext, BlockVisitor, VisitorTable, ForgeView, } from "./transcript";