agentfootprint 10.3.0 → 10.4.0

package/dist/esm/lib/tool-lint/types.d.ts

@@ -1,155 +0,0 @@
-/**
- * tool-lint types — the tool-catalog confusability lint contract
- * (RFC-002 tier 1, blocks C1–C3).
- *
- * Pattern: Strategy seam (the plug-and-play meta-pattern) — the frame
- *          and rule engine are the library's; the embedder, thresholds,
- *          and structural rule pack are all consumer-injected, with our
- *          defaults. Exactly like NarrativeFormatter / reliability /
- *          permission / commentary strategies.
- * Role:    `src/lib/` leaf module. ZERO stack buy-in: input is a plain
- *          `{ name, description?, inputSchema? }[]` — any OpenAI /
- *          Anthropic / LangChain / MCP tool list normalizes to it
- *          (see `coerceCatalog`). The library's own `Tool[]` adapts via
- *          `catalogFromTools`.
- *
- * ## Honest claim (RFC-002 §2)
- *
- * Confusability here is embedding geometry over what the model READS
- * (tool name + description) — a deterministic heuristic for "could the
- * model mix these up", never a measurement of any model's actual
- * selection function. Tier 3 (choice-entropy sampling) validates the
- * proxy; until then treat verdicts as review prompts, not ground truth.
- */
-import type { Embedder, SimilarityPair } from '../influence-core/index.js';
-/**
- * One tool as the lint sees it — the minimal, framework-agnostic shape.
- * `inputSchema` is a JSON Schema object (the same one the LLM sees);
- * structural rules read `properties` / `required` / `enum` from it.
- */
-export interface CatalogTool {
-    readonly name: string;
-    readonly description?: string;
-    /** JSON Schema for the tool's arguments (`type: 'object'` shape). */
-    readonly inputSchema?: Readonly<Record<string, unknown>>;
-}
-/** Verdict for one description pair from the similarity analysis. */
-export type PairVerdict = 'confusable' | 'watch';
-/** One flagged pair: two tools the model could plausibly mix up. */
-export interface ConfusablePairFinding {
-    readonly kind: PairVerdict;
-    /** Tool names (input order: `a` has the lower catalog index). */
-    readonly a: string;
-    readonly b: string;
-    /** cosine(embed(a), embed(b)) over `confusabilityText` of each tool. */
-    readonly similarity: number;
-    /**
-     * Heuristic suggestion for the DIFFERENTIATING AXIS — what to make
-     * explicit in the descriptions so the model can tell them apart
-     * (e.g. "names differ only by 'influx' — say WHEN to use each").
-     */
-    readonly hint: string;
-}
-/** Severity of a structural finding. `error` fails the gate by default. */
-export type LintSeverity = 'error' | 'warn';
-/** One structural finding from a `LintRule`. */
-export interface StructuralFinding {
-    /** Id of the rule that produced this finding. */
-    readonly rule: string;
-    /** Name of the offending tool. */
-    readonly tool: string;
-    readonly severity: LintSeverity;
-    readonly message: string;
-    /** Offending parameter name, when the finding is param-scoped. */
-    readonly param?: string;
-    /** Concrete fix suggestion (e.g. the JSON-Schema `enum` to add). */
-    readonly suggestion?: string;
-}
-/**
- * One pluggable structural rule. Rules are plain objects — add your own
- * to `rules` in `analyzeToolCatalog` options, or filter the exported
- * `defaultStructuralRules` to remove ours.
- */
-export interface LintRule {
-    /** Stable id, kebab-case (shows on findings + CLI output). */
-    readonly id: string;
-    /** Inspect ONE tool (with the whole catalog for context) and return
-     *  zero or more findings. Must not throw on weird-but-valid input. */
-    check(tool: CatalogTool, catalog: readonly CatalogTool[]): readonly StructuralFinding[];
-}
-export interface AnalyzeToolCatalogOptions {
-    /**
-     * Injected embedder for the confusability analysis. OMITTED → the
-     * similarity analysis is skipped (structural rules still run) and
-     * `report.similarity.analyzed` is false.
-     *
-     * Wrap in an `EmbeddingCache` (from `agentfootprint/observe`) so
-     * catalog descriptions embed once across lint runs — keyed by content
-     * hash, so unchanged descriptions cost nothing on re-lint.
-     */
-    readonly embedder?: Embedder;
-    /**
-     * Pairs with similarity ≥ this are `confusable`. Default 0.85 — a
-     * STARTING point calibrated for real sentence embedders (where
-     * unrelated tool descriptions typically land 0.3–0.7).
-     *
-     * ⚠ Per-embedder calibration is REQUIRED (RFC-002 §3): absolute
-     * cosine ranges differ by embedder. The test/demo `mockEmbedder`
-     * (character-frequency) compresses unrelated prose into ~0.85–0.97,
-     * so with the mock use `MOCK_EMBEDDER_CALIBRATION` and trust only
-     * RELATIVE ordering of pairs, never absolute verdicts.
-     */
-    readonly confusabilityThreshold?: number;
-    /**
-     * Pairs within this band BELOW the threshold are `watch` (advisory —
-     * never fail the gate). Default 0.05.
-     */
-    readonly watchBand?: number;
-    /**
-     * The structural rule pack. Default `defaultStructuralRules`.
-     * Add/remove freely — rules are plain `{ id, check }` objects.
-     */
-    readonly rules?: readonly LintRule[];
-    /**
-     * Which structural severity fails the gate (`report.ok`).
-     * Default 'error' — warnings are advisory. 'warn' = strict mode.
-     */
-    readonly failOn?: LintSeverity;
-    /** Abort signal threaded to the embedder (network backends). */
-    readonly signal?: AbortSignal;
-}
-/** The similarity section of a report. */
-export interface SimilarityReport {
-    /** False when no embedder was supplied — similarity was skipped. */
-    readonly analyzed: boolean;
-    readonly confusable: readonly ConfusablePairFinding[];
-    readonly watch: readonly ConfusablePairFinding[];
-    /**
-     * EVERY pair ranked by similarity, descending — the relative-ordering
-     * view that stays meaningful under ANY embedder (including the mock).
-     * Empty when `analyzed` is false.
-     */
-    readonly ranked: readonly SimilarityPair[];
-    readonly thresholds: {
-        readonly confusabilityThreshold: number;
-        readonly watchBand: number;
-    };
-}
-/** The lint report — `ok` is the CI-gateable verdict. */
-export interface ToolCatalogReport {
-    /**
-     * True when there are no confusable pairs AND no structural findings
-     * at/above `failOn` severity. The CI gate: exit non-zero on `!ok`.
-     */
-    readonly ok: boolean;
-    readonly toolCount: number;
-    readonly similarity: SimilarityReport;
-    readonly structural: readonly StructuralFinding[];
-    readonly summary: {
-        readonly confusable: number;
-        readonly watch: number;
-        readonly errors: number;
-        readonly warnings: number;
-    };
-}
-export type { Embedder, SimilarityPair };

package/dist/esm/lib/tool-lint/types.js

@@ -1,25 +0,0 @@
-/**
- * tool-lint types — the tool-catalog confusability lint contract
- * (RFC-002 tier 1, blocks C1–C3).
- *
- * Pattern: Strategy seam (the plug-and-play meta-pattern) — the frame
- *          and rule engine are the library's; the embedder, thresholds,
- *          and structural rule pack are all consumer-injected, with our
- *          defaults. Exactly like NarrativeFormatter / reliability /
- *          permission / commentary strategies.
- * Role:    `src/lib/` leaf module. ZERO stack buy-in: input is a plain
- *          `{ name, description?, inputSchema? }[]` — any OpenAI /
- *          Anthropic / LangChain / MCP tool list normalizes to it
- *          (see `coerceCatalog`). The library's own `Tool[]` adapts via
- *          `catalogFromTools`.
- *
- * ## Honest claim (RFC-002 §2)
- *
- * Confusability here is embedding geometry over what the model READS
- * (tool name + description) — a deterministic heuristic for "could the
- * model mix these up", never a measurement of any model's actual
- * selection function. Tier 3 (choice-entropy sampling) validates the
- * proxy; until then treat verdicts as review prompts, not ground truth.
- */
-export {};
-//# sourceMappingURL=types.js.map

package/dist/esm/lib/tool-lint/types.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/lib/tool-lint/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG"}

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

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

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

@@ -1 +0,0 @@
-{"version":3,"file":"debugPrompt.js","sourceRoot":"","sources":["../../../../src/lib/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/lib/trace-toolpack/index.d.ts

@@ -1,26 +0,0 @@
-/**
- * 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 './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/lib/trace-toolpack/index.js

@@ -1,34 +0,0 @@
-/**
- * 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 './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/lib/trace-toolpack/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/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,sBAAsB,CAAC;AAC9B,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/lib/trace-toolpack/innerDescent.d.ts

@@ -1,58 +0,0 @@
-/**
- * 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 '../../core/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/lib/trace-toolpack/innerDescent.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"innerDescent.js","sourceRoot":"","sources":["../../../../src/lib/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/lib/trace-toolpack/innerRunRecords.d.ts

@@ -1,205 +0,0 @@
-/**
- * innerRunRecords — the record a tool keeps of its OWN run.
- *
- * Pattern: bounded LRU store + a structural join key (a registry symbol).
- * Role:    the one place the outer trace and an inner trace are allowed to
- *          know about each other. Nothing here executes, renders, or
- *          formats — it holds records and hands them back by id.
- *
- * THE GAP
- * ───────
- * `inspect_tool_call` resolves a tool call end to end and then stops at a
- * wall: *"⚠ boundary: what happened INSIDE the tool is not traced."* That
- * marker is honest for a tool that calls someone else's system. It is
- * needlessly honest for a tool that IS a footprintjs flowchart — that tool
- * recorded every stage it ran, and then threw the recording away, because
- * nobody was holding it.
- *
- * So: hold it. `flowchartAsTool({ keepRecord: true })` keeps each
- * invocation's inner record here, keyed by the `toolCallId` the outer run
- * already uses to name that call. One id, two levels — which is what makes
- * the descent a lookup rather than a correlation puzzle.
- *
- * WHY BOUNDED, AND WHY LRU
- * ────────────────────────
- * A retained snapshot is retained memory. An agent that runs a chart tool
- * on every turn for a week would pin every one of those runs, and the
- * failure would look like a leak rather than like a feature. So the store
- * has a cap (default {@link DEFAULT_INNER_RUN_LIMIT}), drops the
- * least-recently-USED record when it overflows, and COUNTS the drops —
- * because "we kept the last 20 of 340" is an answer a debugging session can
- * act on, and a silently missing row is not.
- *
- * Reading refreshes recency on purpose: a record under active investigation
- * (three drills into one inner run) must not be the next one evicted by a
- * turn happening beside it.
- *
- * THE JOIN KEY
- * ────────────
- * The store rides the `Tool` object under a registry symbol rather than a
- * named property: a `Tool` is a consumer-authored shape, and a plain name
- * like `innerRuns` would be a name a consumer's own tool could collide
- * with. `Symbol.for` (registry, not unique-per-module) because this package
- * ships CJS *and* ESM — two module instances of this file must agree on the
- * key or a tool built in one half would be invisible to the other.
- */
-import type { ControlDepLookup } from 'foottrace';
-/**
- * How many invocations one tool keeps by default.
- *
- * Twenty is a debugging window, not an archive: enough that "the call three
- * turns ago" is still there, small enough that a long-lived server holding
- * one store per chart tool has a ceiling it can multiply out. Raise it with
- * `keepRecordLimit` when the sessions are long and the charts are small.
- */
-export declare const DEFAULT_INNER_RUN_LIMIT = 20;
-/** How the inner run finished, from the wrapping tool's point of view. */
-export type InnerRunOutcome = 'ok' | 'error' | 'paused';
-/**
- * One retained inner run — the evidence of a single tool invocation.
- *
- * `recording` is deliberately the `{ snapshot, structure }` shape
- * `recordRun(...).toRecording()` produces, so the same `openRecording`
- * adapter opens it. It is held BY REFERENCE (no clone): the inner executor
- * is discarded after the call, so nothing else can mutate it, and cloning a
- * snapshot per invocation would be the retention cost twice over.
- */
-export interface InnerRunRecord {
-    /** The outer run's id for this call — the one `inspect_tool_call` takes. */
-    readonly toolCallId: string;
-    /** The wrapping tool's name, for messages that name what was descended into. */
-    readonly toolName: string;
-    /** How the invocation ended. A failed inner run is still a complete record. */
-    readonly outcome: InnerRunOutcome;
-    /** Committed steps in the inner run — the size hint the descent line prints. */
-    readonly steps: number;
-    /**
-     * The OUTER run that made the call (`ctx.runId`) — absent when the tool ran
-     * outside an agent run, or for a record a third-party producer filed. The
-     * store keys a record by run AND call id, so two runs that reuse a call id
-     * (another session's model, a replayed script) never displace each other;
-     * and a self-explaining agent serves only the records of the asking
-     * conversation's own runs ({@link innerRunsOfConversation}).
-     */
-    readonly runId?: string;
-    /**
-     * `{ snapshot, structure }` — absent only when capture itself failed, in
-     * which case {@link problem} says why.
-     */
-    readonly recording?: {
-        readonly snapshot: unknown;
-        readonly structure?: unknown;
-    };
-    /**
-     * The inner run's control-dependence lookup.
-     *
-     * A serialized recording can never carry one (a function does not
-     * serialize — see `openRecording`). This record is LIVE in process, so it
-     * can: the wrapping tool attaches a fresh `controlDepRecorder()` per
-     * invocation, and inner slices therefore show the `[control: rule]` edges
-     * that a reopened JSON recording has to say ⚠ about.
-     */
-    readonly controlDeps?: ControlDepLookup;
-    /** The inner run's narrative lines, when the chart had a narrative attached. */
-    readonly narrative?: readonly string[];
-    /**
-     * Why there is no `recording`.
-     *
-     * A record that could not be captured is filed anyway, carrying the
-     * reason. The alternative — no row at all — is indistinguishable from a
-     * call that was never made, which is the one thing a trace must never be
-     * ambiguous about.
-     */
-    readonly problem?: string;
-}
-/** A retained record, named without opening it. */
-export interface InnerRunSummary {
-    readonly toolCallId: string;
-    readonly toolName: string;
-    readonly outcome: InnerRunOutcome;
-    readonly steps: number;
-    /** See {@link InnerRunRecord.runId}. */
-    readonly runId?: string;
-}
-/** Read side — what the trace tools are given. */
-export interface InnerRunLookup {
-    /** The record for one tool call, or undefined (never kept, or evicted). */
-    get(toolCallId: string): InnerRunRecord | undefined;
-    /**
-     * Every record still held, least-recently-used first. Used for the
-     * unknown-id correction, so the model is told which calls it CAN descend
-     * into rather than only which one it cannot.
-     */
-    list(): readonly InnerRunSummary[];
-    /** Records dropped to stay under the cap. Non-zero means "ask sooner". */
-    readonly dropped: number;
-    /** The cap in force (the smallest, when several stores are merged). */
-    readonly limit: number;
-    /**
-     * The most recent record for `toolCallId` that `accept` admits — optional,
-     * so a lookup built before it existed still type-checks; a view falls back
-     * to {@link get} and checks the one record it returns.
-     */
-    getWhere?(toolCallId: string, accept: (record: InnerRunRecord) => boolean): InnerRunRecord | undefined;
-    /** Drops of records whose `runId` `accept` admits (optional; see {@link getWhere}). */
-    droppedWhere?(accept: (runId: string | undefined) => boolean): number;
-}
-/** Write side — what the wrapping tool holds. */
-export interface InnerRunStore extends InnerRunLookup {
-    /** File one invocation's record, evicting the least-recently-used if full. */
-    keep(record: InnerRunRecord): void;
-}
-/**
- * The key an inner-record store rides on a `Tool`.
- *
- * Registry symbol, not a unique one: this package ships CJS and ESM, and a
- * tool built through one entry point must be readable through the other.
- */
-export declare const INNER_RUN_RECORDS: unique symbol;
-/** A `Tool` (or anything) that carries retained inner runs. */
-export interface KeepsInnerRuns {
-    readonly [INNER_RUN_RECORDS]: InnerRunLookup;
-}
-/**
- * Read the inner-run store off a candidate, or undefined when it carries
- * none. Structural and total — a plain tool, a string, `null` all answer
- * "no records" rather than throwing.
- */
-export declare function innerRunsOf(candidate: unknown): InnerRunLookup | undefined;
-/**
- * A bounded LRU store of inner runs.
- *
- * @param limit maximum retained records (clamped to at least 1 — a store
- *              that keeps nothing is `keepRecord: false`, and saying so with
- *              a zero would be config that lies).
- */
-export declare function innerRunStore(limit?: number): InnerRunStore;
-/**
- * One lookup over several stores — an agent may mount more than one chart
- * tool, and the model asking "descend into call c3" should not have to know
- * which tool produced c3.
- *
- * Returns undefined for an empty list so callers can spread the field
- * conditionally rather than passing an empty lookup that answers "nothing
- * was kept" when the truth is "nothing keeps anything".
- */
-export declare function mergeInnerRuns(lookups: readonly InnerRunLookup[]): InnerRunLookup | undefined;
-/**
- * The records ONE conversation's runs filed — the view a self-explaining agent
- * serves (`selfExplain.ts · SelfExplainBinding`), so a why-question asked in
- * one conversation can neither descend into, list, nor count a call another
- * conversation's run made.
- *
- * `belongs(runId)` answers for a record's outer run (`InnerRunRecord.runId`);
- * a record that names no run is asked with `undefined`. A record the view does
- * not admit answers exactly like a record never kept — the same not-found, so
- * the view says nothing about whether anyone else called the tool — and its
- * drops are not in `dropped`. `limit` is the store's.
- *
- * @example
- * ```ts
- * const mine = innerRunsOfConversation(lookup, (runId) => myRuns.has(runId ?? ''));
- * mine.get('call-from-another-run'); // undefined — not found, not forbidden
- * ```
- */
-export declare function innerRunsOfConversation(lookup: InnerRunLookup, belongs: (runId: string | undefined) => boolean): InnerRunLookup;