agentfootprint 10.2.0 → 10.3.1

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

@@ -0,0 +1,385 @@
+/**
+ * selfExplain — the IN-CONVERSATION door over the agent's own trace.
+ *
+ * `.selfExplain()` on the builder mounts ONE skill plus ONE scoped tool
+ * provider. Day to day the tool catalog carries only the skill's
+ * activation row — the trace tools are NOT in the skill (skill `tools`
+ * land in the static registry, exposed every iteration); they ride a
+ * `skillScopedTools` provider gated on the skill's activation, composed
+ * with whatever provider the consumer already set. When the user asks a
+ * why-question the LLM activates the skill, and the NEXT iteration's
+ * catalog gains the trace tools, bound to the agent's own PREVIOUS
+ * COMPLETED run.
+ *
+ * The two pieces here:
+ *
+ * 1. `SelfExplainBinding` — the late-binding seam, a plain CombinedRecorder
+ *    attached like any consumer recorder (zero engine changes):
+ *
+ *      - capture at `onRunEnd`/`onRunFailed`: the just-finished run's
+ *        snapshot becomes the explainable evidence (a FAILED run is
+ *        still a completed trace — "why did you fail?" works);
+ *      - rotate at `onRunStart`: a FRESH ControlDepRecorder per run. The
+ *        retired instance never sees the new run's events, so its live
+ *        `asLookup()` survives Convention-4's runId reset — the captured
+ *        control edges stay valid for the whole next turn.
+ *
+ *    B13 safety lives here: `Agent.run()` reassigns its executor at run
+ *    START, so resolving artifacts mid-run through `getLastSnapshot()`
+ *    would expose the IN-FLIGHT run. Capturing only at terminal flush
+ *    means the binding can never serve anything but a completed run.
+ *
+ *    Keyed PER CONVERSATION (R2-11): one agent instance can serve
+ *    many people (`standingAgent({ agent })`), so "the previous completed
+ *    run" is asked of the ASKING run's session — the evidence of the last
+ *    run that session completed, never whichever run the instance finished
+ *    last. A run with no session reads the last run that had none. A tool's
+ *    retained inner runs are served through the same key
+ *    (`core/innerRunRecords.ts · innerRunsOfConversation`).
+ *
+ * 2. `buildSelfExplainSkill` — the skill in two modes:
+ *
+ *      - INLINE (default): the skill unlocks the trace tools — every name
+ *        in `TRACE_TOOL_NAMES` (11 today) — in the main agent's own loop
+ *        (same model). The count is deliberately not restated anywhere
+ *        that could fall behind the pack.
+ *      - DELEGATE: the skill unlocks ONE tool — `explain_run(question)` —
+ *        whose execute runs a nested `traceDebugAgent` on the consumer's
+ *        chosen (cheaper) provider/model and returns its evidence-cited
+ *        answer. The main conversation pays for one tool call; the
+ *        trace-walking loop happens at the delegate's price. Loaded via
+ *        dynamic import so the builder never statically pulls Agent
+ *        through this module (no core ↔ lib cycle).
+ */
+import { isFlowEvent } from 'footprintjs';
+import { controlDepRecorder } from 'footprintjs/trace';
+import { defineSkill } from '../injection-engine/factories/defineSkill.js';
+import { defineTool } from '../tools/tools.js';
+import { eventTail } from '../events/eventTail.js';
+import { skillScopedTools } from '../tools/skillScopedTools.js';
+import { SELF_EXPLAIN_BODY, SELF_EXPLAIN_WHEN } from './debugPrompt.js';
+import { innerRunsOfConversation } from '../core/innerRunRecords.js';
+import { NO_COMPLETED_RUN_MESSAGE } from '../lib/traceToolNames.js';
+/** Default per-turn event cap for the self-explain binding. */
+export const SELF_EXPLAIN_MAX_EVENTS = 2000;
+/**
+ * How many conversations one binding keeps evidence for — the least recently
+ * explained or completed is dropped past it. One agent instance serving many
+ * sessions holds one completed turn per session, so the bound is what keeps a
+ * long-lived shared agent from pinning every session's last snapshot. A
+ * session whose evidence was dropped is answered like one with no completed
+ * turn: nothing is served, and nothing of anybody else's is served instead.
+ */
+const MAX_CONVERSATIONS = 64;
+/**
+ * The separate bound for ONE-SHOT conversations — a hosted request with no
+ * session, which no later request can name (`SelfExplainServing.oneShot`).
+ * Kept on their own shelf so a flood of sessionless requests can never evict a
+ * session's evidence (recheck NIT 4); small, because nothing ever asks a
+ * follow-up question of one.
+ */
+const MAX_ONE_SHOT_CONVERSATIONS = 8;
+function shelf(max) {
+    return { captured: new Map(), runs: new Map(), max };
+}
+/** Drop the oldest entries of an insertion-ordered map past `max`. */
+function bound(held, max) {
+    while (held.size > max) {
+        const oldest = held.keys().next();
+        if (oldest.done === true)
+            return;
+        held.delete(oldest.value);
+    }
+}
+/** How many of one conversation's runs its inner-run view admits. */
+const MAX_RUNS_PER_CONVERSATION = 32;
+/**
+ * The late-binding seam. Create one per built Agent, attach
+ * `binding.recorder()` via `agent.attach()`, and point `bindTo()` at the
+ * agent's `getLastSnapshot`. `artifacts` then always answers with the
+ * previous COMPLETED run of the asking conversation — never the in-flight
+ * one, and never another conversation's.
+ */
+export class SelfExplainBinding {
+    include;
+    maxEvents;
+    source;
+    ctrl = controlDepRecorder();
+    tail;
+    /** Evidence and run ids per conversation (see
+     *  {@link SelfExplainSource.getServing}), on two shelves: one for
+     *  conversations a caller can come back to ({@link MAX_CONVERSATIONS}), one
+     *  for one-shot ones ({@link MAX_ONE_SHOT_CONVERSATIONS}). Insertion order is
+     *  recency order. Run ids are recorded at run START, so a run that PAUSED or
+     *  FAILED (neither reaches the terminal capture) still owns the records its
+     *  tools filed (recheck RS4). */
+    lasting = shelf(MAX_CONVERSATIONS);
+    oneShot = shelf(MAX_ONE_SHOT_CONVERSATIONS);
+    constructor(include = {}, maxEvents = SELF_EXPLAIN_MAX_EVENTS) {
+        this.include = include;
+        this.maxEvents = maxEvents;
+    }
+    get wantsNarrative() {
+        return this.include.narrative !== false;
+    }
+    get wantsEvents() {
+        return this.include.events !== false;
+    }
+    /**
+     * Point the binding at the agent it explains.
+     *
+     * Accepts the bare `getSnapshot` function it has always accepted (the
+     * evidence a completed run leaves behind on its own), or the full
+     * source, which adds the two parts a snapshot does NOT carry: the
+     * narrative, and the typed event stream.
+     */
+    bindTo(source) {
+        this.source = typeof source === 'function' ? { getSnapshot: source } : source;
+        if (this.wantsEvents && this.source.on) {
+            this.tail = eventTail(this.maxEvents);
+            this.source.on('*', (event) => this.tail?.push(event));
+        }
+    }
+    /**
+     * Evidence of the previous completed run OF THE ASKING CONVERSATION, or
+     * undefined when that conversation has completed none (or its evidence was
+     * dropped past the bound). Never another conversation's.
+     */
+    get artifacts() {
+        // No refresh on read: a read happens only inside the asking
+        // conversation's own run, whose terminal capture files it as the most
+        // recent anyway.
+        const serving = this.serving();
+        const conversation = serving?.conversation;
+        const held = this.shelfOf(serving);
+        const turn = held.captured.get(conversation);
+        if (turn === undefined)
+            return undefined;
+        const allInnerRuns = this.source?.getInnerRuns?.();
+        const innerRuns = allInnerRuns === undefined
+            ? undefined
+            : this.source?.getServing === undefined
+                ? allInnerRuns
+                : innerRunsOfConversation(allInnerRuns, ownRuns(held.runs.get(conversation) ?? [], conversation));
+        return {
+            snapshot: turn.snapshot,
+            controlDeps: turn.ctrl.asLookup(),
+            ...(turn.narrative !== undefined && { narrative: turn.narrative }),
+            ...(turn.events !== undefined && { events: turn.events }),
+            ...(innerRuns !== undefined && { innerRuns }),
+        };
+    }
+    /** The conversation (and run) in flight, or served last. */
+    serving() {
+        return this.source?.getServing?.();
+    }
+    /** Which shelf a conversation lives on. */
+    shelfOf(serving) {
+        return serving?.oneShot === true ? this.oneShot : this.lasting;
+    }
+    /** Remember that the serving run belongs to its conversation (bounded both ways). */
+    recordRun(serving) {
+        const { runs, max } = this.shelfOf(serving);
+        const held = runs.get(serving.conversation) ?? [];
+        runs.delete(serving.conversation);
+        runs.set(serving.conversation, [...held, serving.runId].slice(-MAX_RUNS_PER_CONVERSATION));
+        bound(runs, max);
+    }
+    /** File the serving conversation's evidence as its most recent, within the bound. */
+    file(serving, turn) {
+        const { captured, max } = this.shelfOf(serving);
+        captured.delete(serving?.conversation);
+        captured.set(serving?.conversation, turn);
+        bound(captured, max);
+    }
+    /** The recorder to attach — forwards flow events to the per-run ctrl. */
+    recorder() {
+        const capture = () => {
+            const snapshot = this.source?.getSnapshot();
+            if (!snapshot)
+                return;
+            // The narrative and the event tail are read at the SAME terminal
+            // flush as the snapshot, so the three describe one turn. Reading
+            // either later would mean reading it during the NEXT turn.
+            const narrative = this.wantsNarrative && this.source?.getNarrative
+                ? this.source.getNarrative().map((entry) => entry.text)
+                : undefined;
+            const events = this.tail?.snapshot().events;
+            // Filed under the FINISHED run's conversation — at the terminal flush
+            // the source still names the run that just ended.
+            this.file(this.serving(), {
+                snapshot,
+                ctrl: this.ctrl,
+                ...(narrative !== undefined && { narrative }),
+                ...(events !== undefined && { events }),
+            });
+        };
+        return {
+            id: 'self-explain-binding',
+            // Inline always: capture must complete at the terminal flush, and
+            // the ctrl forwarding is four cheap map writes per event.
+            delivery: 'inline',
+            onRunStart: () => {
+                // Rotate FIRST: the retired ctrl never sees this run's events,
+                // so the captured lookup survives Convention-4's runId reset.
+                // The event tail rotates for the same reason — turn N+1's
+                // evidence must not carry turn N's events. The retired tail is
+                // the one its conversation's `captured` entry already holds, so it
+                // is not lost.
+                this.ctrl = controlDepRecorder();
+                if (this.wantsEvents && this.source?.on)
+                    this.tail = eventTail(this.maxEvents);
+                // The run joins its conversation NOW, not at the end: a pause or a
+                // failure never reaches the terminal capture, and the records its
+                // tools filed must still be its conversation's to read.
+                const serving = this.serving();
+                if (serving !== undefined)
+                    this.recordRun(serving);
+            },
+            onRunEnd: capture,
+            onRunFailed: capture,
+            onDecision: (e) => this.ctrl.onDecision(e),
+            onSelected: (e) => this.ctrl.onSelected(e),
+            onStageExecuted: (e) => this.ctrl.onStageExecuted(e),
+            onError: (e) => {
+                // ControlDepRecorder consumes FLOW errors only (branch-slot
+                // accounting); scope errors don't carry traversal context.
+                if (isFlowEvent(e))
+                    this.ctrl.onError(e);
+            },
+        };
+    }
+}
+/**
+ * Which inner-run records a conversation may read: those its own completed
+ * runs filed. A record that names no run (a third-party producer, a tool run
+ * outside an agent) cannot be attributed, so it is admitted only on the
+ * direct no-session path (`undefined`) — never to a session or a hosted
+ * request.
+ */
+function ownRuns(runIds, conversation) {
+    const runs = new Set(runIds);
+    return (runId) => (runId === undefined ? conversation === undefined : runs.has(runId));
+}
+/** The delegate-mode tool: one call → a nested debugger at delegate price. */
+function buildExplainRunTool(binding, delegate, toolpack) {
+    return defineTool({
+        name: 'explain_run',
+        description: "Answer a question about this agent's PREVIOUS completed turn by walking its recorded " +
+            'trace (a dedicated trace debugger runs the investigation and returns an evidence-cited ' +
+            "answer). Pass the user's why-question verbatim.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                question: { type: 'string', description: 'The why-question to investigate.' },
+            },
+            required: ['question'],
+            additionalProperties: false,
+        },
+        execute: async ({ question }, ctx) => {
+            const artifacts = binding.artifacts;
+            if (!artifacts)
+                return NO_COMPLETED_RUN_MESSAGE;
+            // Dynamic import: keeps Agent out of this module's static graph
+            // (AgentBuilder imports this file; Agent imports AgentBuilder).
+            const { traceDebugAgent } = await import('./traceDebugAgent.js');
+            const debuggerAgent = traceDebugAgent({
+                artifacts,
+                provider: delegate.provider,
+                model: delegate.model,
+                maxIterations: delegate.maxIterations,
+                toolpack,
+            });
+            // The debugger's run is NESTED in the calling agent's run, so it is
+            // covered by the same policy — its own record (the question, what the
+            // trace tools served it, its answer) keeps out what the agent's does.
+            const out = await debuggerAgent.run({ message: question }, ctx.redact !== undefined ? { redact: ctx.redact } : undefined);
+            return typeof out === 'object' && out !== null && 'content' in out
+                ? String(out.content)
+                : String(out);
+        },
+    });
+}
+/** The default skill id — the activation key the LLM passes to read_skill. */
+export const SELF_EXPLAIN_SKILL_ID = 'self-explain';
+/**
+ * The skill `.selfExplain()` mounts — methodology body ONLY. The trace
+ * tools deliberately do NOT ride the skill: skill `tools` land in the
+ * static registry (exposed every iteration); catalog gating is the
+ * ToolProvider's job — see {@link buildSelfExplainToolProvider}.
+ */
+export function buildSelfExplainSkill(options) {
+    return defineSkill({
+        id: options.id ?? SELF_EXPLAIN_SKILL_ID,
+        description: SELF_EXPLAIN_WHEN,
+        body: SELF_EXPLAIN_BODY + (options.instruction ? `\n\n${options.instruction}` : ''),
+    });
+}
+/**
+ * The gated tool delivery — `skillScopedTools` (the shipped primitive)
+ * scoped to the skill's id, composed with the consumer's own provider
+ * when they set one. The iteration after activation, `ctx.activeSkillId`
+ * matches and the catalog gains the trace tools (inline) or the single
+ * `explain_run` tool (delegate).
+ *
+ * INLINE MODE LOADS THE PACK LAZILY (9.94.0). The toolpack module is the
+ * largest single module on the library's default graph, and until this
+ * release every consumer who imported `Agent` carried it — `.selfExplain()`
+ * or not — because this function reached it statically. Now the pack is
+ * `import()`ed the first time the self-explain skill is ACTIVE on an
+ * iteration, and never before: not at `build()`, not on a turn where the
+ * model never opened the skill, not at all for an agent that did not enable
+ * `.selfExplain()`. A bundler splits it into its own chunk; Node loads it
+ * through the same `require` it always did, one microtask later.
+ *
+ * What the consumer sees: `list(ctx)` still answers `[]` synchronously when
+ * the skill is not active (the sync fast path the tools slot skips the await
+ * for), and a Promise of the same eleven tools when it is — the shape
+ * `ToolProvider.list` has always allowed, and the one the composed provider
+ * below already used. The provider id is unchanged, so `.watch()` output and
+ * the `skill-scoped:` refusal in the builder read exactly as before.
+ */
+export function buildSelfExplainToolProvider(binding, options, existing) {
+    const skillId = options.id ?? SELF_EXPLAIN_SKILL_ID;
+    const scoped = options.delegate
+        ? skillScopedTools(skillId, [buildExplainRunTool(binding, options.delegate, options.toolpack)])
+        : lazilyMountedTraceTools(skillId, binding, options.toolpack);
+    if (!existing)
+        return scoped;
+    return {
+        id: `${existing.id}+${scoped.id}`,
+        list: async (ctx) => [...(await existing.list(ctx)), ...(await scoped.list(ctx))],
+    };
+}
+/**
+ * The inline-mode provider: `skillScopedTools` semantics, with the tool list
+ * behind an `import()` that runs once, on the first ACTIVE iteration.
+ *
+ * The inactive path delegates to a real `skillScopedTools(skillId, [])` so it
+ * keeps that primitive's exact behaviour — the `[]` answer AND its one-time
+ * dev-mode warning about a skill that is loaded but not by `read_skill` — and
+ * the active path resolves the pack, builds the same scoped provider over it
+ * ONCE, and asks it. A failed load rejects `list()`, which the tools slot
+ * already reports as `tools.discovery_failed` and rethrows; the memo is
+ * cleared so the next iteration retries rather than serving a dead promise.
+ */
+function lazilyMountedTraceTools(skillId, binding, toolpack) {
+    const inactive = skillScopedTools(skillId, []);
+    let mounted;
+    const mount = () => {
+        mounted ??= import('./lazyToolpack.js').then(({ lazyTraceToolpack }) => skillScopedTools(skillId, lazyTraceToolpack(() => binding.artifacts, toolpack)), (err) => {
+            mounted = undefined;
+            throw err;
+        });
+        return mounted;
+    };
+    return {
+        id: inactive.id,
+        list(ctx) {
+            if (ctx.activeSkillId !== skillId)
+                return inactive.list(ctx);
+            return mount().then((provider) => provider.list(ctx));
+        },
+    };
+}
+//# sourceMappingURL=selfExplain.js.map

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

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

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

@@ -0,0 +1,28 @@
+/**
+ * selfExplainHost — the trace toolpack's binding of the agent builder's
+ * `.selfExplain()` port, and the module the root door takes `Agent` and
+ * `AgentBuilder` from.
+ *
+ * Pattern: Plugin registration (the `devWarnHost.ts` precedent).
+ * Role:    trace-toolpack (layer L10, above the agent). The agent builder
+ *          names only `core/agent/selfExplainPort.ts`; this file hands it the
+ *          three pieces `selfExplain.ts` builds — the binding, the skill and
+ *          the provider — at load, before any builder can reach `build()`.
+ * Emits:   nothing.
+ *
+ * WHY THE CLASSES ARE RE-EXPORTED HERE. The root barrel and every other door
+ * are flagged side-effect-free (package.json `sideEffects`), and a bundler is
+ * then free to skip a barrel and link `import { Agent }` straight to the module
+ * that declares it. A registration placed in the barrel would be skipped with
+ * it: webpack and rolldown both drop it (measured on a minimal package, both
+ * bundlers, while this file was written). So the root door re-exports `Agent` and
+ * `AgentBuilder` FROM this module, which IS flagged as having side effects —
+ * whoever imports the agent through a door runs this file first, and a bundle
+ * that never names the agent does not carry it. `traceDebugAgent.ts` builds
+ * its agent from the same import, so `agentfootprint/observe`, the other door
+ * whose graph reaches the builder, registers too.
+ */
+import { type SelfExplainExtension } from '../core/agent/selfExplainPort.js';
+/** The toolpack's half of the port, exactly what the builder called before the port existed. */
+export declare const selfExplainExtension: SelfExplainExtension;
+export { Agent, AgentBuilder } from '../core/Agent.js';

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

@@ -0,0 +1,35 @@
+/**
+ * selfExplainHost — the trace toolpack's binding of the agent builder's
+ * `.selfExplain()` port, and the module the root door takes `Agent` and
+ * `AgentBuilder` from.
+ *
+ * Pattern: Plugin registration (the `devWarnHost.ts` precedent).
+ * Role:    trace-toolpack (layer L10, above the agent). The agent builder
+ *          names only `core/agent/selfExplainPort.ts`; this file hands it the
+ *          three pieces `selfExplain.ts` builds — the binding, the skill and
+ *          the provider — at load, before any builder can reach `build()`.
+ * Emits:   nothing.
+ *
+ * WHY THE CLASSES ARE RE-EXPORTED HERE. The root barrel and every other door
+ * are flagged side-effect-free (package.json `sideEffects`), and a bundler is
+ * then free to skip a barrel and link `import { Agent }` straight to the module
+ * that declares it. A registration placed in the barrel would be skipped with
+ * it: webpack and rolldown both drop it (measured on a minimal package, both
+ * bundlers, while this file was written). So the root door re-exports `Agent` and
+ * `AgentBuilder` FROM this module, which IS flagged as having side effects —
+ * whoever imports the agent through a door runs this file first, and a bundle
+ * that never names the agent does not carry it. `traceDebugAgent.ts` builds
+ * its agent from the same import, so `agentfootprint/observe`, the other door
+ * whose graph reaches the builder, registers too.
+ */
+import { registerSelfExplain } from '../core/agent/selfExplainPort.js';
+import { buildSelfExplainSkill, buildSelfExplainToolProvider, SelfExplainBinding, } from './selfExplain.js';
+/** The toolpack's half of the port, exactly what the builder called before the port existed. */
+export const selfExplainExtension = {
+    binding: (options) => new SelfExplainBinding(options.include, options.maxEvents),
+    skill: buildSelfExplainSkill,
+    toolProvider: buildSelfExplainToolProvider,
+};
+registerSelfExplain(selfExplainExtension);
+export { Agent, AgentBuilder } from '../core/Agent.js';
+//# sourceMappingURL=selfExplainHost.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"selfExplainHost.js","sourceRoot":"","sources":["../../../src/trace-toolpack/selfExplainHost.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,mBAAmB,EAA6B,MAAM,kCAAkC,CAAC;AAClG,OAAO,EACL,qBAAqB,EACrB,4BAA4B,EAC5B,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAE1B,gGAAgG;AAChG,MAAM,CAAC,MAAM,oBAAoB,GAAyB;IACxD,OAAO,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,kBAAkB,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,SAAS,CAAC;IAChF,KAAK,EAAE,qBAAqB;IAC5B,YAAY,EAAE,4BAA4B;CAC3C,CAAC;AAEF,mBAAmB,CAAC,oBAAoB,CAAC,CAAC;AAE1C,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC"}

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

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

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

@@ -0,0 +1,42 @@
+/**
+ * traceDebugAgent — the DEDICATED conversational door over a completed
+ * run's trace. One call returns a ready Agent whose entire catalog is
+ * the trace toolpack and whose system prompt is the proven debugging
+ * methodology (overview → drill by id → cite evidence → respect ⚠).
+ *
+ * The counterpart doors over the same evidence:
+ *   - the UI (BacktrackView / Lens) for humans who LOOK,
+ *   - `.selfExplain()` for why-questions INSIDE the main conversation
+ *     (which, in delegate mode, runs one of these under the hood).
+ *
+ * Why dedicated (B13 posture): trace views can replay adversarial text
+ * from the original run — a SEPARATE session over a COMPLETED run keeps
+ * that out of the production conversation. It is also the cheap-model
+ * story made real: debug a Sonnet/Opus run with a Haiku-priced session
+ * that reads only what it opens, by id (~9% of the trace in the
+ * example-01 fixture; the gap widens with run size).
+ */
+import { Agent } from './selfExplainHost.js';
+import type { AgentOptions } from '../core/agent/types.js';
+import type { TraceToolpackArtifacts, TraceToolpackOptions } from './types.js';
+export interface TraceDebugAgentOptions {
+    /** The completed run's evidence — `{ snapshot, controlDeps?, narrative? }`. */
+    readonly artifacts: TraceToolpackArtifacts;
+    /** Any provider — `mock()` in tests, a cheap model in production. */
+    readonly provider: AgentOptions['provider'];
+    readonly model: string;
+    /** ReAct budget for one debugging question. Default 8. */
+    readonly maxIterations?: number;
+    /** Appended to the methodology system prompt (domain hints, tone). */
+    readonly instruction?: string;
+    /** Bounding dials forwarded to the toolpack. */
+    readonly toolpack?: TraceToolpackOptions;
+    /** Display name in events/metrics. Default 'TraceDebugAgent'. */
+    readonly name?: string;
+}
+/**
+ * Build the dedicated trace debugger. The returned Agent is a normal
+ * Agent — `await debuggerAi.run({ message: 'Why was the refund approved?' })`
+ * answers from the recorded evidence, citing runtimeStageIds.
+ */
+export declare function traceDebugAgent(options: TraceDebugAgentOptions): Agent;

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

@@ -0,0 +1,43 @@
+/**
+ * traceDebugAgent — the DEDICATED conversational door over a completed
+ * run's trace. One call returns a ready Agent whose entire catalog is
+ * the trace toolpack and whose system prompt is the proven debugging
+ * methodology (overview → drill by id → cite evidence → respect ⚠).
+ *
+ * The counterpart doors over the same evidence:
+ *   - the UI (BacktrackView / Lens) for humans who LOOK,
+ *   - `.selfExplain()` for why-questions INSIDE the main conversation
+ *     (which, in delegate mode, runs one of these under the hood).
+ *
+ * Why dedicated (B13 posture): trace views can replay adversarial text
+ * from the original run — a SEPARATE session over a COMPLETED run keeps
+ * that out of the production conversation. It is also the cheap-model
+ * story made real: debug a Sonnet/Opus run with a Haiku-priced session
+ * that reads only what it opens, by id (~9% of the trace in the
+ * example-01 fixture; the gap widens with run size).
+ */
+// The agent through the self-explain host, as the doors hand it out: the
+// `/observe` door reaches the builder only through this file, so taking the
+// class from the host registers the `.selfExplain()` port there too.
+import { Agent } from './selfExplainHost.js';
+import { TRACE_DEBUG_METHODOLOGY } from './debugPrompt.js';
+import { traceToolpack } from './traceToolpack.js';
+/**
+ * Build the dedicated trace debugger. The returned Agent is a normal
+ * Agent — `await debuggerAi.run({ message: 'Why was the refund approved?' })`
+ * answers from the recorded evidence, citing runtimeStageIds.
+ */
+export function traceDebugAgent(options) {
+    const system = TRACE_DEBUG_METHODOLOGY + (options.instruction ? `\n\n${options.instruction}` : '');
+    return Agent.create({
+        provider: options.provider,
+        model: options.model,
+        name: options.name ?? 'TraceDebugAgent',
+        id: 'trace-debug-agent',
+        maxIterations: options.maxIterations ?? 8,
+    })
+        .system(system)
+        .tools(traceToolpack(options.artifacts, options.toolpack))
+        .build();
+}
+//# sourceMappingURL=traceDebugAgent.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"traceDebugAgent.js","sourceRoot":"","sources":["../../../src/trace-toolpack/traceDebugAgent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,yEAAyE;AACzE,4EAA4E;AAC5E,qEAAqE;AACrE,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAE7C,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAmBnD;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,OAA+B;IAC7D,MAAM,MAAM,GACV,uBAAuB,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,OAAO,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACtF,OAAO,KAAK,CAAC,MAAM,CAAC;QAClB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,iBAAiB;QACvC,EAAE,EAAE,mBAAmB;QACvB,aAAa,EAAE,OAAO,CAAC,aAAa,IAAI,CAAC;KAC1C,CAAC;SACC,MAAM,CAAC,MAAM,CAAC;SACd,KAAK,CAAC,aAAa,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;SACzD,KAAK,EAAE,CAAC;AACb,CAAC"}

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

@@ -0,0 +1,82 @@
+/**
+ * traceToolpack — footprintjs trace evidence exposed as TOOLS an LLM calls
+ * (RFC-003 Part C: the introspection toolpack).
+ *
+ * "The framework's internal tool for itself": after a run completes, a
+ * debugging LLM (a cheap model in a SEPARATE session) navigates the run's
+ * evidence by ids instead of reading dumps — the same just-in-time,
+ * token-efficient loading pattern as `read_skill`. Feed the slice, not the
+ * trace; the LLM ranks by navigating, so no embedder is needed.
+ *
+ * Pattern: Factory over frozen artifacts. `traceToolpack(artifacts)` returns
+ *          plain `Tool[]` — mount them on any Agent, or drive them scripted
+ *          via `callTraceTool` (the offline auditor pattern, like
+ *          examples/features/20). Nothing re-runs; every tool is a bounded
+ *          read-only VIEW over a COMPLETED run's snapshot + commit log.
+ *
+ * The toolpack's three contracts (B13 posture):
+ *
+ *   1. BOUNDED BY DEFAULT — every output is capped (previews, slice
+ *      depth/nodes, value chars, narrative lines). Per-call params raise
+ *      the budget only up to hard caps the LLM cannot exceed.
+ *   2. HONEST — truncation and incompleteness are ALWAYS marked (⚠), never
+ *      silent: truncated slices, untracked sources (args/env/silent reads),
+ *      missing read tracking, missing control-dependence lookup, values the
+ *      commit log cannot see (pre-run state, closures).
+ *   3. REDACTION-RESPECTING — the commit log already carries redacted
+ *      payloads (footprintjs scrubs at commit time); the toolpack passes
+ *      placeholders through verbatim and flags redacted keys. It never
+ *      reconstructs around a redaction.
+ *
+ * Why ids: every view names steps by `runtimeStageId`
+ * (`stageId#executionIndex`) — the universal key linking the commit log,
+ * the execution tree, and recorder events. The LLM drills like a debugger:
+ * overview → slice → node → value, paying only for what it opens.
+ */
+import { type Tool } from '../tools/tools.js';
+import { type TraceToolpackArtifacts, type TraceToolpackOptions } from './types.js';
+/**
+ * Build the introspection toolpack over a COMPLETED run's artifacts.
+ *
+ * Returns plain `Tool[]`:
+ *
+ * | Tool                | Question it answers                                    |
+ * |---------------------|--------------------------------------------------------|
+ * | `run_overview`      | What happened, broadly? (the entry point)              |
+ * | `find_context_errors` | What did this run contradict itself about, and why?  |
+ * | `find_in_trace`     | WHERE in this run does "…" appear? (free text → ids)   |
+ * | `trace_node`        | What did step X read/write, and where did its inputs come from? |
+ * | `trace_slice`       | Which chain of steps produced the data at X? (causal slice) |
+ * | `backtrack`         | Why is VARIABLE K what it is? (+ `element`: who made K[i]?) — variable-first |
+ * | `who_wrote`         | Which step last wrote key K?                           |
+ * | `get_value`         | The full value of K as of step X (capped, truncation-marked) |
+ * | `inspect_tool_call` | One tool call end to end: proposed args → ran-with args → result → outcome |
+ * | `inspect_tool_run`  | INSIDE one tool call — the chart it ran, when that tool kept its record |
+ * | `inspect_subflow`   | INSIDE one subflow mount — the subflow's own log, one level at a time |
+ * | `read_narrative`    | The human-readable story, paginated (only when narrative provided) |
+ *
+ * Mount on an Agent (`Agent.create({...}).tool(...tools)`) or drive scripted
+ * via {@link callTraceTool}. The tools NEVER throw on bad ids/keys — they
+ * return corrective, model-visible messages (the #9 philosophy), and their
+ * strict input schemas give Agent-dispatched calls free arg validation.
+ *
+ * Security note (B13 posture): trace content can carry adversarial text from
+ * the original run (tool results, user input). Serve these tools to a
+ * SEPARATE debugging session over completed runs — not to the production
+ * agent mid-run — and treat tool outputs as data, not instructions.
+ */
+export declare function traceToolpack(artifacts: TraceToolpackArtifacts, options?: TraceToolpackOptions): Tool[];
+/**
+ * The tool names this pack can mount — declared in `traceToolNames.ts` so the
+ * Agent builder can reserve them WITHOUT loading this module (the pack is
+ * mounted lazily since 9.94.0); re-exported here so the list still reads as
+ * the pack's own.
+ */
+export { TRACE_TOOL_NAMES } from '../lib/traceToolNames.js';
+/**
+ * Invoke a toolpack tool OUTSIDE an Agent (scripted debug sessions, tests,
+ * offline auditors). Mirrors the Agent's #9 boundary: args are validated
+ * against the tool's inputSchema first, and an invalid call returns the same
+ * model-visible correction string instead of executing.
+ */
+export declare function callTraceTool(tools: readonly Tool[], name: string, args?: Record<string, unknown>): Promise<string>;