agentfootprint 10.2.0 → 10.3.1

package/dist/esm/tools/tools.js

@@ -0,0 +1,306 @@
+/**
+ * Tool types — Agent's tool-call contract.
+ *
+ * Pattern: Strategy (GoF) — each Tool is a strategy for "how to execute
+ *          this named operation given these args".
+ * Role:    Consumer-facing shape. Agent.tool(...) accepts these.
+ * Emits:   N/A (types only).
+ */
+import { assertToolWants } from '../artifacts/wants.js';
+import { RESULT_CLASSES } from '../semantics/types.js';
+import { assertResultColumns, COLUMN_TYPES, } from '../integrity/column-types/types.js';
+import { assertAskComponent } from './askComponent.js';
+import { warnIfInvalidToolName } from '../lib/toolName.js';
+import { assertAskOrAssume } from './declare.js';
+/**
+ * Refuse a `resultCeiling` this library cannot honor, at definition time —
+ * naming the tool and the fix, never failing at the first oversized result of
+ * the first run. Exported beside `lib/toolName.ts` · `assertValidToolName` for consumers
+ * assembling `Tool` objects by hand.
+ */
+export function assertResultCeiling(toolName, ceiling) {
+    if (ceiling === undefined)
+        return;
+    // Destructured through a fallback because this rule is also asked about
+    // values NO COMPILER vetted — a `_meta` bag from a foreign MCP server
+    // (`readToolExtras`). A `null` or a number must reach the teaching refusal
+    // below, not blow up on the destructuring on the way to it.
+    const { maxChars, narrowBy } = (ceiling ?? {});
+    if (!Number.isFinite(maxChars) || !Number.isInteger(maxChars) || maxChars <= 0) {
+        throw new Error(`defineTool: tool '${toolName}' declares resultCeiling.maxChars = ${String(maxChars)}, ` +
+            `which is not a positive whole number of characters. The ceiling is the size over ` +
+            `which the model reads a refusal instead of the result — to have no ceiling, omit ` +
+            `\`resultCeiling\` (absent means results are never measured, exactly as before).`);
+    }
+    if (narrowBy !== undefined) {
+        const usable = Array.isArray(narrowBy) &&
+            narrowBy.length > 0 &&
+            narrowBy.every((n) => typeof n === 'string' && n.trim().length > 0);
+        if (!usable) {
+            throw new Error(`defineTool: tool '${toolName}' declares resultCeiling.narrowBy = ` +
+                `${JSON.stringify(narrowBy)}, which names nothing the refusal could suggest. ` +
+                `List at least one parameter name (non-empty strings, e.g. ['limit', 'fields']), ` +
+                `or drop the field — omitting it is how "no suggestions" is said.`);
+        }
+    }
+}
+/**
+ * Refuse a `resultClass` outside the closed set, at definition time — naming
+ * the tool, the value and the whole vocabulary (the `assertResultCeiling`
+ * law: a declaration this library cannot honor fails HERE, never at the
+ * first gate run of the first CI pipeline). Exported beside it for consumers
+ * assembling `Tool` objects by hand.
+ */
+export function assertResultClass(toolName, resultClass) {
+    if (resultClass === undefined)
+        return;
+    if (!RESULT_CLASSES.includes(resultClass)) {
+        throw new Error(`defineTool: tool '${toolName}' declares resultClass '${String(resultClass)}', which is ` +
+            `not a class this library has. The classes are: ${RESULT_CLASSES.join(', ')} — each ` +
+            `carries a rule \`check:semantics\` can prove ('triage'/'inventory' results must ` +
+            `declare coverage). To declare no class, omit the field (the semantic-envelope rules ` +
+            `still apply to any result carrying the af_semantics marker).`);
+    }
+}
+/**
+ * The COLUMN-TYPE CONTRACT's rule and vocabulary, re-exported HERE.
+ *
+ * They are DEFINED in `src/integrity/column-types/types.ts`, because
+ * `src/integrity/` is a strict leaf that imports nothing outside itself and
+ * the check has to be able to read the words. They are re-exported here
+ * because `defineTool` and the MCP ingest both reach for their rules through
+ * `tools/tools.ts` — one door for every declaration's rule, and no second copy
+ * of any of them anywhere.
+ */
+export { assertResultColumns, COLUMN_TYPES, };
+/**
+ * Refuse a `resultKind` that could never be redeemed, at definition time —
+ * naming the tool and the fix (the `assertResultCeiling` / `assertResultClass`
+ * law: a declaration this library cannot honor fails HERE, never at the first
+ * oversized result of the first run). Exported beside them for consumers
+ * assembling `Tool` objects by hand.
+ *
+ * The one rule is non-blankness, and it is not a formality: the kind is what a
+ * `wants` argument is matched against by exact string equality, so a blank or
+ * whitespace-only kind mints a ticket no declaration can ever name — the same
+ * refusal `assertToolWants` raises on the consuming end, raised on the
+ * producing end too. There is deliberately NO charset or shape rule: the kind
+ * is the consumer's vocabulary, and the library does not own it.
+ */
+export function assertResultKind(toolName, resultKind) {
+    if (resultKind === undefined)
+        return;
+    if (typeof resultKind !== 'string' || resultKind.trim().length === 0) {
+        throw new Error(`defineTool: tool '${toolName}' declares resultKind ${JSON.stringify(resultKind)}, which ` +
+            `is not a kind anything could want. It is the artifact kind a PLACED result is minted ` +
+            `under, matched by exact string equality against a consuming tool's ` +
+            `\`wants\` (e.g. 'dataset/rows'), so a blank kind is a ticket no argument can redeem. ` +
+            `Name the kind your consumers declare, or omit the field — omitting it mints ` +
+            `\`tool-result/${toolName}\`, exactly as before.`);
+    }
+}
+/**
+ * Refuse an `owner` stamp with a blank half, at definition time — naming the
+ * tool and what a blank half would do.
+ *
+ * An identity edge with a blank half is worse than none: the Context Integrity
+ * checks JOIN on it, so a blank `kind` or `id` joins the wrong subjects rather
+ * than no subjects. Extracted from `defineTool` (9.71.0) so the MCP ingest
+ * boundary can hold the SAME line on a declaration that arrived over the wire —
+ * one rule, one message, two doors.
+ *
+ * Deliberately NOT a closed-set check on `kind`: the union is enforced by the
+ * compiler for anyone calling `defineTool`, and the value is only ever read
+ * into a prose reason (`owned by <kind> '<id>'`), never switched on.
+ */
+export function assertToolOwner(toolName, owner) {
+    if (owner === undefined)
+        return;
+    // Same reason as `assertResultCeiling`: this is also asked about untyped
+    // values from a foreign MCP server, so a scalar or a `null` must land on the
+    // message rather than on a TypeError from the destructuring.
+    const { kind, id } = (owner ?? {});
+    if (typeof owner !== 'object' ||
+        typeof kind !== 'string' ||
+        kind.length === 0 ||
+        typeof id !== 'string' ||
+        id.length === 0) {
+        throw new Error(`defineTool('${toolName}'): \`owner\` must carry a non-empty kind and id — it is ` +
+            `the identity edge integrity checks join on, and a blank half joins the wrong ` +
+            `subjects. Got ${JSON.stringify(owner)}.`);
+    }
+}
+/**
+ * Refuse an `argumentsFrom` edge that could never join, at definition time.
+ *
+ * The dangling-reference and unsupported-argument checks join on these names,
+ * so a blank one — or a tool grounded by itself — would join the wrong subjects
+ * or none at all. Extracted from `defineTool` (9.71.0) for the same reason as
+ * {@link assertToolOwner}: the MCP ingest boundary enforces the identical rule
+ * on a declaration a remote server sent.
+ */
+export function assertArgumentsFrom(toolName, argumentsFrom) {
+    if (argumentsFrom === undefined)
+        return;
+    // The array check is part of the rule, not a formality: a foreign server can
+    // put a bare string here, and `for…of` over one would walk its CHARACTERS
+    // and refuse them one letter at a time.
+    if (!Array.isArray(argumentsFrom) || argumentsFrom.length === 0) {
+        throw new Error(`defineTool('${toolName}'): \`argumentsFrom\` must name at least one tool — ` +
+            `omitting the field is how "no grounds" is said.`);
+    }
+    for (const ground of argumentsFrom) {
+        if (typeof ground !== 'string' || ground.length === 0) {
+            throw new Error(`defineTool('${toolName}'): \`argumentsFrom\` entries must be non-empty tool ` +
+                `names. Got ${JSON.stringify(ground)}.`);
+        }
+        if (ground === toolName) {
+            throw new Error(`defineTool('${toolName}'): \`argumentsFrom\` names the tool itself — a tool ` +
+                `cannot be its own argument ground.`);
+        }
+    }
+}
+/**
+ * Refuse a `composedOf` list that could never be drift-checked, at definition
+ * time — the {@link assertArgumentsFrom} law applied to composition: the
+ * agent-build gate joins on these names, and a blank one — or a tool composed
+ * of itself — would join the wrong subjects or none. The REGISTRATION check
+ * (is every named ingredient actually registered?) deliberately does NOT
+ * happen here: the ingredients need not exist before this tool is defined,
+ * and only the agent build sees the complete catalog.
+ */
+export function assertComposedOf(toolName, composedOf) {
+    if (composedOf === undefined)
+        return;
+    // Same reason as `assertArgumentsFrom`: this rule is also asked about
+    // untyped values from a foreign MCP server, and `for…of` over a bare string
+    // would walk its CHARACTERS.
+    if (!Array.isArray(composedOf) || composedOf.length === 0) {
+        throw new Error(`defineTool('${toolName}'): \`composedOf\` must name at least one ingredient tool — ` +
+            `omitting the field is how "not composed" is said.`);
+    }
+    for (const ingredient of composedOf) {
+        if (typeof ingredient !== 'string' || ingredient.length === 0) {
+            throw new Error(`defineTool('${toolName}'): \`composedOf\` entries must be non-empty tool names. ` +
+                `Got ${JSON.stringify(ingredient)}.`);
+        }
+        if (ingredient === toolName) {
+            throw new Error(`defineTool('${toolName}'): \`composedOf\` names the tool itself — a tool cannot ` +
+                `be its own ingredient.`);
+        }
+    }
+}
+/**
+ * Refuse a `gates` declaration that is not a boolean, at definition time.
+ * Trivial for anyone the compiler vets; load-bearing at the MCP ingest
+ * boundary, where a foreign server can put anything under the key and a
+ * truthy string would silently declare a gate nobody wrote.
+ */
+export function assertGates(toolName, gates) {
+    if (gates === undefined)
+        return;
+    if (typeof gates !== 'boolean') {
+        throw new Error(`defineTool('${toolName}'): \`gates\` must be a boolean — \`true\` (this tool's ` +
+            `procedure can raise an approval gate), \`false\` (declared gate-free), or omitted ` +
+            `(nothing declared). Got ${JSON.stringify(gates)}.`);
+    }
+}
+/**
+ * Ergonomic builder for `Tool`. Equivalent to constructing an object
+ * literal with `schema` + `execute`, but flatter and safer — the name
+ * + description live alongside the executor so they can't drift.
+ *
+ * @example
+ *   const weather = defineTool<{ city: string }, string>({
+ *     name: 'weather',
+ *     description: 'Get current weather for a city',
+ *     inputSchema: {
+ *       type: 'object',
+ *       properties: { city: { type: 'string' } },
+ *       required: ['city'],
+ *     },
+ *     execute: async ({ city }) => `${city}: 72°F sunny`,
+ *   });
+ *
+ *   const agent = Agent.create({ provider }).tool(weather).build();
+ */
+export function defineTool(options) {
+    warnIfInvalidToolName(options.name);
+    // A ceiling that cannot cap fails HERE, naming the tool — not at the first
+    // oversized result of the first run.
+    assertResultCeiling(options.name, options.resultCeiling);
+    // A class outside the closed set fails HERE too — not at the first
+    // `check:semantics` run of the first CI pipeline.
+    assertResultClass(options.name, options.resultClass);
+    // A placed-result kind nothing could want fails HERE too — not at the first
+    // oversized result of the first run with placement configured.
+    assertResultKind(options.name, options.resultKind);
+    // A column type this library has no rule for fails HERE too — not at the
+    // first rowset of the first armed run, where the symptom would be a check
+    // that quietly judges nothing.
+    assertResultColumns(options.name, options.resultColumns);
+    // A decision component for a gate that never fires is configuration that
+    // lies — configured-and-inert looks exactly like configured-and-working
+    // (the `.checkIn({ scorer })`-with-minimal-evidence precedent). And a
+    // malformed one fails HERE, naming the tool, not at the first tripped gate
+    // of the first consequential call.
+    if (options.checkInComponent !== undefined) {
+        if (options.checkIn === undefined) {
+            throw new Error(`defineTool('${options.name}'): \`checkInComponent\` has no effect without \`checkIn\`. ` +
+                `The component rides the check-in ask — which screen collects the decision — and ` +
+                `this tool declares no check-in, so it would never be shown to anyone. Declare ` +
+                `\`checkIn: 'always'\` (or a predicate), or drop the component.`);
+        }
+        assertAskComponent(options.checkInComponent, `defineTool('${options.name}') checkInComponent`);
+    }
+    // A wants-arg the schema never offers (or offers as a non-string) fails
+    // HERE too, naming the argument — not as a ref that never arrives. Judged
+    // against the RESOLVED schema: an omitted inputSchema defaults to empty
+    // properties, which offers no argument for any ref to arrive through.
+    assertToolWants(options.name, options.wants, options.inputSchema ?? { type: 'object', properties: {} });
+    // An identity edge with a blank half is worse than none: a checker would
+    // join on it and compare the wrong subjects. Refused HERE, naming the tool.
+    assertToolOwner(options.name, options.owner);
+    // The grounds edge is judged at the same door and for the same reason: the
+    // dangling-reference check joins on these names, and a blank one — or a
+    // tool grounded by itself — would join the wrong subjects or none.
+    assertArgumentsFrom(options.name, options.argumentsFrom);
+    // Composition edges get the same shape discipline; the REGISTRATION check
+    // (does every ingredient exist?) waits for the agent build, where the
+    // catalog is complete.
+    assertComposedOf(options.name, options.composedOf);
+    assertGates(options.name, options.gates);
+    // The inputs layer's rules (honesty layer 2) — judged against the RESOLVED
+    // schema, each property by its OWN schema (never the root `required`), and
+    // refused here naming the tool and the argument, not at the first call.
+    assertAskOrAssume(options.name, options.askOrAssume, options.period, options.inputSchema ?? { type: 'object', properties: {} }, options.wants);
+    return {
+        schema: {
+            name: options.name,
+            description: options.description,
+            inputSchema: options.inputSchema ?? { type: 'object', properties: {} },
+        },
+        ...(options.needs && { needs: options.needs }),
+        ...(options.wants !== undefined && { wants: options.wants }),
+        // The call-site predicate is typed to TArgs; the stored Tool keeps the
+        // non-generic shape so it widens into `Tool[]` registries.
+        ...(options.checkIn !== undefined && { checkIn: options.checkIn }),
+        ...(options.checkInComponent !== undefined && { checkInComponent: options.checkInComponent }),
+        // Copied verbatim, never inferred — an empty array is a tool that declared
+        // it touches nothing, which is a different statement from saying nothing.
+        ...(options.capabilities !== undefined && { capabilities: options.capabilities }),
+        ...(options.resultCeiling !== undefined && { resultCeiling: options.resultCeiling }),
+        ...(options.resultClass !== undefined && { resultClass: options.resultClass }),
+        ...(options.resultKind !== undefined && { resultKind: options.resultKind }),
+        ...(options.resultColumns !== undefined && { resultColumns: options.resultColumns }),
+        ...(options.owner !== undefined && { owner: options.owner }),
+        ...(options.argumentsFrom !== undefined && { argumentsFrom: options.argumentsFrom }),
+        ...(options.composedOf !== undefined && { composedOf: options.composedOf }),
+        ...(options.gates !== undefined && { gates: options.gates }),
+        ...(options.repeatedWhen !== undefined && { repeatedWhen: options.repeatedWhen }),
+        ...(options.askOrAssume !== undefined && { askOrAssume: options.askOrAssume }),
+        ...(options.period !== undefined && { period: options.period }),
+        execute: options.execute,
+    };
+}
+//# sourceMappingURL=tools.js.map

package/dist/esm/tools/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../../src/tools/tools.ts"],"names":[],"mappings":"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"}

package/dist/esm/trace-toolpack/bounded.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bounded.js","sourceRoot":"","sources":["../../../src/trace-toolpack/bounded.ts"],"names":[],"mappings":"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"}

package/dist/esm/trace-toolpack/debugPrompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debugPrompt.js","sourceRoot":"","sources":["../../../src/trace-toolpack/debugPrompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,0CAA0C;AAC1C,iGAAiG;AACjG,mFAAmF;AACnF,qEAAqE;AACrE,MAAM,CAAC,MAAM,uBAAuB,GAAG;;;;;;;;;;;;;+FAawD,CAAC;AAEhG,yEAAyE;AACzE,MAAM,CAAC,MAAM,iBAAiB,GAC5B,uEAAuE;IACvE,2FAA2F;IAC3F,uDAAuD,CAAC;AAE1D,kEAAkE;AAClE,MAAM,CAAC,MAAM,iBAAiB,GAC5B,GAAG,uBAAuB,MAAM;IAChC,wFAAwF;IACxF,qFAAqF;IACrF,gCAAgC,CAAC"}

package/dist/esm/trace-toolpack/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * trace-toolpack — RFC-003 Part C: the introspection toolpack.
+ *
+ * footprintjs trace evidence exposed as TOOLS an LLM calls: a debugging
+ * model navigates a COMPLETED run's evidence by runtimeStageIds instead of
+ * reading dumps. Bounded, honest (⚠ markers), redaction-respecting.
+ *
+ * Three doors over the same evidence:
+ *   - `traceToolpack`     the raw Tool[] (mount anywhere / drive scripted)
+ *   - `traceDebugAgent`   the DEDICATED conversational debugger (separate
+ *                         session, any provider — cheap models welcome)
+ *   - `.selfExplain()`    the IN-CONVERSATION door on the Agent builder
+ *                         (skill-gated, late-bound to the agent's own
+ *                         previous completed run; inline or delegate mode)
+ *
+ * …and one way IN for a run that already finished: `openRecording` turns a
+ * saved `recordRun` bundle back into artifacts, so last Tuesday's run is
+ * as navigable as this one.
+ */
+export { callTraceTool, traceToolpack, TRACE_TOOL_NAMES } from './traceToolpack.js';
+export { lazyTraceToolpack, NO_COMPLETED_RUN_MESSAGE } from './lazyToolpack.js';
+export { openRecording, type OpenableRecording } from './openRecording.js';
+export { DEFAULT_INNER_RUN_LIMIT, INNER_RUN_RECORDS, innerRunStore, innerRunsOf, mergeInnerRuns, type InnerRunLookup, type InnerRunOutcome, type InnerRunRecord, type InnerRunStore, type InnerRunSummary, type KeepsInnerRuns, } from '../core/innerRunRecords.js';
+export { traceDebugAgent, type TraceDebugAgentOptions } from './traceDebugAgent.js';
+export { buildSelfExplainSkill, buildSelfExplainToolProvider, SelfExplainBinding, SELF_EXPLAIN_MAX_EVENTS, type SelfExplainInclude, type SelfExplainOptions, type SelfExplainServing, type SelfExplainSource, } from './selfExplain.js';
+export { TOOLPACK_HARD_CAPS, type TraceToolpackArtifacts, type TraceToolpackOptions, } from './types.js';

package/dist/esm/trace-toolpack/index.js

@@ -0,0 +1,34 @@
+/**
+ * trace-toolpack — RFC-003 Part C: the introspection toolpack.
+ *
+ * footprintjs trace evidence exposed as TOOLS an LLM calls: a debugging
+ * model navigates a COMPLETED run's evidence by runtimeStageIds instead of
+ * reading dumps. Bounded, honest (⚠ markers), redaction-respecting.
+ *
+ * Three doors over the same evidence:
+ *   - `traceToolpack`     the raw Tool[] (mount anywhere / drive scripted)
+ *   - `traceDebugAgent`   the DEDICATED conversational debugger (separate
+ *                         session, any provider — cheap models welcome)
+ *   - `.selfExplain()`    the IN-CONVERSATION door on the Agent builder
+ *                         (skill-gated, late-bound to the agent's own
+ *                         previous completed run; inline or delegate mode)
+ *
+ * …and one way IN for a run that already finished: `openRecording` turns a
+ * saved `recordRun` bundle back into artifacts, so last Tuesday's run is
+ * as navigable as this one.
+ */
+export { callTraceTool, traceToolpack, TRACE_TOOL_NAMES } from './traceToolpack.js';
+// `missingArtifactMessage` is deliberately NOT re-exported: it is the lazy
+// pack's own answer for a tool whose optional evidence this run lacks, and a
+// consumer has no call to construct one.
+export { lazyTraceToolpack, NO_COMPLETED_RUN_MESSAGE } from './lazyToolpack.js';
+export { openRecording } from './openRecording.js';
+// The record a TOOL keeps of its own run — what `inspect_tool_run` opens.
+// `INNER_RUN_RECORDS` / `innerRunsOf` are the join key between a Tool and
+// its store; `innerRunStore` / `mergeInnerRuns` exist for consumers wiring
+// a chart tool into artifacts by hand (the Agent builder does it for you).
+export { DEFAULT_INNER_RUN_LIMIT, INNER_RUN_RECORDS, innerRunStore, innerRunsOf, mergeInnerRuns, } from '../core/innerRunRecords.js';
+export { traceDebugAgent } from './traceDebugAgent.js';
+export { buildSelfExplainSkill, buildSelfExplainToolProvider, SelfExplainBinding, SELF_EXPLAIN_MAX_EVENTS, } from './selfExplain.js';
+export { TOOLPACK_HARD_CAPS, } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/trace-toolpack/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/trace-toolpack/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACpF,2EAA2E;AAC3E,6EAA6E;AAC7E,yCAAyC;AACzC,OAAO,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAChF,OAAO,EAAE,aAAa,EAA0B,MAAM,oBAAoB,CAAC;AAC3E,0EAA0E;AAC1E,0EAA0E;AAC1E,2EAA2E;AAC3E,2EAA2E;AAC3E,OAAO,EACL,uBAAuB,EACvB,iBAAiB,EACjB,aAAa,EACb,WAAW,EACX,cAAc,GAOf,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,eAAe,EAA+B,MAAM,sBAAsB,CAAC;AACpF,OAAO,EACL,qBAAqB,EACrB,4BAA4B,EAC5B,kBAAkB,EAClB,uBAAuB,GAKxB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,kBAAkB,GAGnB,MAAM,YAAY,CAAC"}

package/dist/esm/trace-toolpack/innerDescent.d.ts

@@ -0,0 +1,58 @@
+/**
+ * innerDescent — the ONE way the toolpack opens a record that sits BELOW the
+ * run it serves.
+ *
+ * Pattern: one-slot memo + param-shaped dispatch + a frame said out loud.
+ * Role:    shared by the two entry points that descend —
+ *          `inspect_tool_run` (the record a chart-as-tool kept of its own run)
+ *          and `inspect_subflow` (a subflow mount's own commit log). Each entry
+ *          point decides only WHAT it opens and how to name it; opening,
+ *          asking and framing happen here, once, so the two descents cannot
+ *          drift into two vocabularies.
+ *
+ * WHY THE INNER VIEW IS THE PACK ITSELF. An inner record is a run like any
+ * other: a commit log, an execution tree, a fold base. So the inner views are
+ * the pack's own tools, built over the inner artifact bag — there is no second
+ * implementation of "what did this step write", and the reason codes come out
+ * of the same basis twins, folded from the INNER record's own `initialState`.
+ *
+ * WHY ONE SLOT. Three questions into one inner record build one index; the
+ * memo pins at most one inner pack beyond what the snapshot already holds.
+ */
+import type { Tool } from '../tools/tools.js';
+import type { TraceToolpackArtifacts } from './types.js';
+/** What the model asked of an inner record — the narrowest param wins. */
+export interface InnerQuestion {
+    readonly runtimeStageId?: string;
+    readonly key?: string;
+    readonly variable?: string;
+    readonly find?: string;
+}
+/** How an entry point names what it opened — three lines, said every time. */
+export interface InnerFrame {
+    /** What was opened, and how big it is. */
+    readonly header: string;
+    /** The moves that stay inside it. */
+    readonly next: string;
+    /** Whose ids these are — and that the outer tools do not take them. */
+    readonly namespace: string;
+}
+/** `callTraceTool`, injected so this module does not import the pack. */
+export type CallTraceTool = (tools: readonly Tool[], name: string, args: Record<string, unknown>) => Promise<string>;
+/** Open (or reuse) the inner pack for `id`; a string is an honest refusal. */
+export type InnerPackSlot = (id: string, open: () => TraceToolpackArtifacts | string) => Tool[] | string;
+/**
+ * One inner pack at a time, memoised by the id it was opened under. `open`
+ * runs only on a miss, and a refusal (a string) is never memoised — the next
+ * ask tries again rather than repeating a stale "could not open".
+ */
+export declare function innerPackSlot(build: (artifacts: TraceToolpackArtifacts) => Tool[]): InnerPackSlot;
+/**
+ * Ask an opened inner pack one question. Param-shaped dispatch (the
+ * `backtrack({ element })` precedent): the narrowest question asked wins, and
+ * no params at all is the entry point — the inner `run_overview`. A `key`
+ * without a step is "who wrote it last in there" (`who_wrote`).
+ */
+export declare function askInner(tools: readonly Tool[], question: InnerQuestion, call: CallTraceTool): Promise<string>;
+/** The answer, inside its frame. */
+export declare function framed(frame: InnerFrame, body: string): string;

package/dist/esm/trace-toolpack/innerDescent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"innerDescent.js","sourceRoot":"","sources":["../../../src/trace-toolpack/innerDescent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAoCH;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,KAAoD;IAChF,IAAI,MAA0B,CAAC;IAC/B,IAAI,SAA6B,CAAC;IAClC,OAAO,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE;QAClB,IAAI,SAAS,KAAK,SAAS,IAAI,MAAM,KAAK,EAAE;YAAE,OAAO,SAAS,CAAC;QAC/D,MAAM,SAAS,GAAG,IAAI,EAAE,CAAC;QACzB,IAAI,OAAO,SAAS,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QACpD,MAAM,GAAG,EAAE,CAAC;QACZ,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC;QAC7B,OAAO,SAAS,CAAC;IACnB,CAAC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,KAAsB,EACtB,QAAuB,EACvB,IAAmB;IAEnB,MAAM,EAAE,cAAc,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAC;IACzD,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC,KAAK,EAAE,eAAe,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7E,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC1E,IAAI,cAAc,KAAK,SAAS,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtD,OAAO,IAAI,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,cAAc,EAAE,GAAG,EAAE,CAAC,CAAC;IAC3D,CAAC;IACD,IAAI,cAAc,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC,KAAK,EAAE,YAAY,EAAE,EAAE,cAAc,EAAE,CAAC,CAAC;IACvF,8EAA8E;IAC9E,+CAA+C;IAC/C,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;IAChE,OAAO,IAAI,CAAC,KAAK,EAAE,cAAc,EAAE,EAAE,CAAC,CAAC;AACzC,CAAC;AAED,oCAAoC;AACpC,MAAM,UAAU,MAAM,CAAC,KAAiB,EAAE,IAAY;IACpD,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACtE,CAAC"}

package/dist/esm/trace-toolpack/lazyToolpack.d.ts

@@ -0,0 +1,54 @@
+/**
+ * lazyTraceToolpack — the toolpack with LATE-BOUND artifacts.
+ *
+ * `traceToolpack(artifacts)` is a factory over FROZEN artifacts: it
+ * precomputes an index and even bakes step-id enums into tool schemas.
+ * That is right for the dedicated debugger (the run is already complete
+ * when you build it) — and wrong for `.selfExplain()`, where the tools
+ * are defined at Agent BUILD time but must read the agent's own *previous
+ * completed run*, which changes every turn.
+ *
+ * This wrapper splits the two lifetimes:
+ *
+ *   - SCHEMAS are built once from an empty template (artifact-independent —
+ *     no id enums, generic descriptions; the same shape `traceToolpack`
+ *     itself produces past the enum cap), so the tools can be mounted on
+ *     a skill before any run exists.
+ *   - EXECUTION resolves `resolve()` per call, builds the REAL toolpack
+ *     over the resolved artifacts (memoized by snapshot identity — one
+ *     index per completed run, not per call), and delegates through
+ *     `callTraceTool` so arg validation matches the eager path.
+ *
+ * When `resolve()` returns undefined (no completed run yet), every tool
+ * answers with an honest, model-visible message instead of throwing —
+ * the same #9 philosophy as the toolpack's unknown-id corrections.
+ */
+import type { Tool } from '../tools/tools.js';
+import { NO_COMPLETED_RUN_MESSAGE } from '../lib/traceToolNames.js';
+import type { TraceToolpackArtifacts, TraceToolpackOptions } from './types.js';
+export { NO_COMPLETED_RUN_MESSAGE };
+/**
+ * Model-visible answer when a tool MOUNTED on the catalog has no evidence
+ * to serve for this particular run.
+ *
+ * The lazy pack's shape is fixed at Agent BUILD time — the tool catalog and
+ * the builder's name reservation both need to know the list before any run
+ * exists — while an artifact bag's OPTIONAL parts (the narrative, the event
+ * tail) are decided per run. So a tool can be on the catalog with nothing
+ * behind it, and the honest move is to say which switch turns it back on
+ * rather than to answer emptily.
+ */
+export declare function missingArtifactMessage(toolName: string): string;
+/**
+ * Build the toolpack with late-bound artifacts.
+ *
+ * The template is built over an artifact bag that declares EVERY optional
+ * part (an empty narrative, an empty event tail), so the lazy pack mounts
+ * the same tool list every time. That fixed list is what the Agent
+ * builder's name reservation and the tool catalog are both keyed on — a
+ * pack whose shape depended on a run that has not happened yet could not
+ * be reserved at build time. When a resolved run turns out not to carry
+ * one of those parts, the tool answers with
+ * {@link missingArtifactMessage} instead of quietly disappearing.
+ */
+export declare function lazyTraceToolpack(resolve: () => TraceToolpackArtifacts | undefined, options?: TraceToolpackOptions): Tool[];

package/dist/esm/trace-toolpack/lazyToolpack.js

@@ -0,0 +1,102 @@
+/**
+ * lazyTraceToolpack — the toolpack with LATE-BOUND artifacts.
+ *
+ * `traceToolpack(artifacts)` is a factory over FROZEN artifacts: it
+ * precomputes an index and even bakes step-id enums into tool schemas.
+ * That is right for the dedicated debugger (the run is already complete
+ * when you build it) — and wrong for `.selfExplain()`, where the tools
+ * are defined at Agent BUILD time but must read the agent's own *previous
+ * completed run*, which changes every turn.
+ *
+ * This wrapper splits the two lifetimes:
+ *
+ *   - SCHEMAS are built once from an empty template (artifact-independent —
+ *     no id enums, generic descriptions; the same shape `traceToolpack`
+ *     itself produces past the enum cap), so the tools can be mounted on
+ *     a skill before any run exists.
+ *   - EXECUTION resolves `resolve()` per call, builds the REAL toolpack
+ *     over the resolved artifacts (memoized by snapshot identity — one
+ *     index per completed run, not per call), and delegates through
+ *     `callTraceTool` so arg validation matches the eager path.
+ *
+ * When `resolve()` returns undefined (no completed run yet), every tool
+ * answers with an honest, model-visible message instead of throwing —
+ * the same #9 philosophy as the toolpack's unknown-id corrections.
+ */
+import { callTraceTool, traceToolpack } from './traceToolpack.js';
+import { NO_COMPLETED_RUN_MESSAGE } from '../lib/traceToolNames.js';
+// Declared in `traceToolNames.ts` (beside the reserved names) so the delegate
+// tool can answer "no run yet" without loading this module; re-exported here
+// because it is this pack's answer.
+export { NO_COMPLETED_RUN_MESSAGE };
+/**
+ * Model-visible answer when a tool MOUNTED on the catalog has no evidence
+ * to serve for this particular run.
+ *
+ * The lazy pack's shape is fixed at Agent BUILD time — the tool catalog and
+ * the builder's name reservation both need to know the list before any run
+ * exists — while an artifact bag's OPTIONAL parts (the narrative, the event
+ * tail) are decided per run. So a tool can be on the catalog with nothing
+ * behind it, and the honest move is to say which switch turns it back on
+ * rather than to answer emptily.
+ */
+export function missingArtifactMessage(toolName) {
+    const part = toolName === 'read_narrative' ? 'narrative' : 'events';
+    return (`${toolName} has nothing to read for this run — the captured evidence carries no ` +
+        `${part}. This agent was built with selfExplain({ include: { ${part}: false } }), or the ` +
+        `artifacts were assembled without it. The other trace tools are unaffected.`);
+}
+/**
+ * Minimal empty snapshot for building artifact-independent template
+ * schemas. The cast is safe because the toolpack's CONSTRUCTION reads
+ * only `commitLog` (`?? []`) and `executionTree` (visit() guards
+ * undefined) — `sharedState`/`commitValues` are read only inside
+ * execute paths, and the wrapper below shadows every template execute.
+ */
+const EMPTY_SNAPSHOT = {
+    commitLog: [],
+    executionTree: undefined,
+    sharedState: {},
+    commitValues: 'full',
+};
+/**
+ * Build the toolpack with late-bound artifacts.
+ *
+ * The template is built over an artifact bag that declares EVERY optional
+ * part (an empty narrative, an empty event tail), so the lazy pack mounts
+ * the same tool list every time. That fixed list is what the Agent
+ * builder's name reservation and the tool catalog are both keyed on — a
+ * pack whose shape depended on a run that has not happened yet could not
+ * be reserved at build time. When a resolved run turns out not to carry
+ * one of those parts, the tool answers with
+ * {@link missingArtifactMessage} instead of quietly disappearing.
+ */
+export function lazyTraceToolpack(resolve, options) {
+    const template = traceToolpack({ snapshot: EMPTY_SNAPSHOT, narrative: [], events: [] }, options);
+    // One real toolpack per completed run: memoized by snapshot identity.
+    // Retention note: the memo pins at most ONE prior snapshot (whatever a
+    // trace tool last executed against) until the next call rebinds it.
+    let memoSnapshot;
+    let memoTools;
+    const realTools = (artifacts) => {
+        if (memoTools === undefined || memoSnapshot !== artifacts.snapshot) {
+            memoSnapshot = artifacts.snapshot;
+            memoTools = traceToolpack(artifacts, options);
+        }
+        return memoTools;
+    };
+    return template.map((tool) => ({
+        ...tool,
+        execute: async (args) => {
+            const artifacts = resolve();
+            if (!artifacts)
+                return NO_COMPLETED_RUN_MESSAGE;
+            const real = realTools(artifacts);
+            if (!real.some((candidate) => candidate.schema.name === tool.schema.name)) {
+                return missingArtifactMessage(tool.schema.name);
+            }
+            return callTraceTool(real, tool.schema.name, args);
+        },
+    }));
+}
+//# sourceMappingURL=lazyToolpack.js.map

package/dist/esm/trace-toolpack/lazyToolpack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazyToolpack.js","sourceRoot":"","sources":["../../../src/trace-toolpack/lazyToolpack.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAKH,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAGpE,8EAA8E;AAC9E,6EAA6E;AAC7E,oCAAoC;AACpC,OAAO,EAAE,wBAAwB,EAAE,CAAC;AAEpC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,sBAAsB,CAAC,QAAgB;IACrD,MAAM,IAAI,GAAG,QAAQ,KAAK,gBAAgB,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC;IACpE,OAAO,CACL,GAAG,QAAQ,uEAAuE;QAClF,GAAG,IAAI,wDAAwD,IAAI,uBAAuB;QAC1F,4EAA4E,CAC7E,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,cAAc,GAAG;IACrB,SAAS,EAAE,EAAE;IACb,aAAa,EAAE,SAAS;IACxB,WAAW,EAAE,EAAE;IACf,YAAY,EAAE,MAAM;CACS,CAAC;AAEhC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAiD,EACjD,OAA8B;IAE9B,MAAM,QAAQ,GAAG,aAAa,CAAC,EAAE,QAAQ,EAAE,cAAc,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC;IAEjG,sEAAsE;IACtE,uEAAuE;IACvE,oEAAoE;IACpE,IAAI,YAAyC,CAAC;IAC9C,IAAI,SAA6B,CAAC;IAClC,MAAM,SAAS,GAAG,CAAC,SAAiC,EAAU,EAAE;QAC9D,IAAI,SAAS,KAAK,SAAS,IAAI,YAAY,KAAK,SAAS,CAAC,QAAQ,EAAE,CAAC;YACnE,YAAY,GAAG,SAAS,CAAC,QAAQ,CAAC;YAClC,SAAS,GAAG,aAAa,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QAChD,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC,CAAC;IAEF,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC7B,GAAG,IAAI;QACP,OAAO,EAAE,KAAK,EAAE,IAA6B,EAAE,EAAE;YAC/C,MAAM,SAAS,GAAG,OAAO,EAAE,CAAC;YAC5B,IAAI,CAAC,SAAS;gBAAE,OAAO,wBAAwB,CAAC;YAChD,MAAM,IAAI,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC;YAClC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,KAAK,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC1E,OAAO,sBAAsB,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAClD,CAAC;YACD,OAAO,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACrD,CAAC;KACF,CAAC,CAAC,CAAC;AACN,CAAC"}