agentfootprint 13.0.0 → 14.0.0

package/dist/trace-toolpack/traceToolpack/recursiveFactory.js

@@ -0,0 +1,397 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.callTraceTool = exports.traceToolpack = void 0;
+const storedCauseBinding_js_1 = require("../storedCauseBinding.js");
+const causeCapture_js_1 = require("../causeCapture.js");
+const types_js_1 = require("../types.js");
+const packIndex_js_1 = require("./packIndex.js");
+const toolCallJournal_js_1 = require("./toolCallJournal.js");
+const runOverview_js_1 = require("./runOverview.js");
+const contextErrors_js_1 = require("./contextErrors.js");
+const findInTrace_js_1 = require("./findInTrace.js");
+const nodeView_js_1 = require("./nodeView.js");
+const sliceView_js_1 = require("./sliceView.js");
+const backtrackView_js_1 = require("./backtrackView.js");
+const valueQueries_js_1 = require("./valueQueries.js");
+const causeTools_js_1 = require("../causeTools.js");
+const narrativeView_js_1 = require("./narrativeView.js");
+const innerDescent_js_1 = require("../innerDescent.js");
+const openRecording_js_1 = require("../openRecording.js");
+const artifactFacts_js_1 = require("./artifactFacts.js");
+const tools_js_1 = require("../../tools/tools.js");
+const innerRecords_js_1 = require("./innerRecords.js");
+const structuralLimits_js_1 = require("./structuralLimits.js");
+const subflowRecords_js_1 = require("../subflowRecords.js");
+const types_js_2 = require("../../identity/types.js");
+const capability_js_1 = require("../../artifacts/capability.js");
+const toolArgsValidation_js_1 = require("../../tools/toolArgsValidation.js");
+// ── The factory ────────────────────────────────────────────────────────────
+// LENS · tool-result · persistent-history
+// reads: the completed run ← footprintjs's own owners (causalChain, commitValueAt, findLastWriter, sliceForKey,
+//        arrayProvenance, elementProvenance) — re-derived nowhere; the disposition line ← the recorded event
+//        the bounds ← bounded.ts, through which every value this toolpack serves passes
+//        a never-dispatched call ← the bracket's typed `notDispatched`, else the history message's (`notDispatchedOf`); never `error`/`durationMs`
+// law: may omit, never deny; every clause anchored to the call it was composed on.
+/**
+ * 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.
+ */
+function traceToolpack(artifacts, options) {
+    // Saved-only evidence has its own graph-only door. Inspect the claim as data
+    // before a snapshot getter, indexing or any graph code can run.
+    let savedClaim = true;
+    try {
+        const cause = Object.getOwnPropertyDescriptor(artifacts, 'cause');
+        savedClaim =
+            (0, storedCauseBinding_js_1.storedCauseAssessment)(artifacts).kind !== 'none' ||
+                (cause === undefined
+                    ? 'cause' in artifacts
+                    : (0, storedCauseBinding_js_1.storedCauseAssessment)((0, causeCapture_js_1.captureOwn)(artifacts, 'cause')).kind !== 'none');
+    }
+    catch {
+        // An accessor or hostile object cannot supply evidence for a mixed bag.
+    }
+    if (savedClaim)
+        throw new TypeError('Stored capture evidence requires traceCauseTools.');
+    const opts = (0, types_js_1.resolveToolpackOptions)(options);
+    const index = (0, packIndex_js_1.buildIndex)(artifacts);
+    // ONE reader over the scattered tool-call evidence, shared by the two
+    // tools that need it: the join at the boundary (`inspect_tool_call`) and
+    // the descent through it (`inspect_tool_run`). Its lookups are lazy and
+    // memoized, so a pack that opens neither pays nothing and a pack that
+    // opens both pays once.
+    const calls = (0, toolCallJournal_js_1.buildToolCallReader)(artifacts, index);
+    const tools = [
+        (0, runOverview_js_1.buildRunOverview)(artifacts, index),
+        (0, contextErrors_js_1.buildFindContextErrors)(artifacts, index, calls, opts),
+        (0, findInTrace_js_1.buildFindInTrace)(artifacts, index),
+        (0, nodeView_js_1.buildTraceNode)(artifacts, index, opts),
+        (0, sliceView_js_1.buildTraceSlice)(artifacts, index, opts),
+        (0, backtrackView_js_1.buildBacktrack)(artifacts, index, opts),
+        (0, valueQueries_js_1.buildWhoWrote)(index, opts),
+        (0, valueQueries_js_1.buildGetValue)(index, opts),
+        (0, toolCallJournal_js_1.buildInspectToolCall)(artifacts, calls),
+        buildInspectToolRun(artifacts, calls, options),
+        buildInspectSubflow(artifacts, index, options),
+        ...(0, causeTools_js_1.buildCauseTools)(artifacts, index.nodes, options?.cause),
+    ];
+    if (artifacts.narrative !== undefined) {
+        tools.push((0, narrativeView_js_1.buildReadNarrative)(artifacts.narrative));
+    }
+    return tools;
+}
+exports.traceToolpack = traceToolpack;
+// ── inspect_tool_run ───────────────────────────────────────────────────────
+/**
+ * THROUGH the boundary — the tool call's own run, opened.
+ *
+ * `inspect_tool_call` answers everything about a call except the question
+ * that usually follows it: *and then what did it DO?* For a tool that
+ * reaches into a payments API, "not traced" is the true answer. For a tool
+ * that is itself a footprintjs chart, the true answer was thrown away —
+ * the chart recorded every stage and nobody held the record.
+ *
+ * `flowchartAsTool({ keepRecord: true })` holds it. This tool opens it, and
+ * three properties keep the descent from becoming a second, worse trace API:
+ *
+ *   - ONE VOCABULARY. The inner views are the pack's own tools, run over
+ *     the inner artifact bag through `openRecording` — the same adapter a
+ *     saved recording uses. There is no second implementation of "what did
+ *     this step write", so there is no second implementation to drift.
+ *   - TWO ID NAMESPACES, SAID OUT LOUD. Inner `runtimeStageId`s belong to
+ *     the tool's chart, not the outer run. Every output says so, because a
+ *     model that pastes an inner id into `trace_node` gets a correction
+ *     that reads like a bug rather than like a boundary.
+ *   - HONEST ABSENCE THAT NAMES THE SWITCH. `keepRecord` is off by default
+ *     (retaining a snapshot per invocation is memory the caller has to
+ *     agree to), so "nothing to open" is the COMMON case — and an answer
+ *     that just says "nothing" teaches the model the tool is broken.
+ */
+function buildInspectToolRun(artifacts, reader, options) {
+    // One inner pack at a time, memoized by call id (`innerDescent`): three
+    // drills into one inner run build one index.
+    const slot = (0, innerDescent_js_1.innerPackSlot)((inner) => traceToolpack(inner, options));
+    const openRecord = (record) => {
+        if (record.recording === undefined) {
+            return (`tool call '${record.toolCallId}' ran '${record.toolName}', which keeps records — but ` +
+                `THIS one could not be captured: ${record.problem ?? 'reason not recorded'}. The call ` +
+                `itself was unaffected; inspect_tool_call('${record.toolCallId}') still has the ` +
+                `envelope (arguments in, result out).`);
+        }
+        try {
+            const inner = {
+                // `openRecording` is the adapter, not a copy of it: same lift, same
+                // two teaching refusals if the bag is malformed. The two fields it
+                // cannot lift from JSON — control edges, and a narrative nobody
+                // attached — are added here because this record is LIVE in process.
+                ...(0, openRecording_js_1.openRecording)(record.recording),
+                ...(record.controlDeps !== undefined && { controlDeps: record.controlDeps }),
+                ...(record.narrative !== undefined && { narrative: record.narrative }),
+            };
+            artifactFacts_js_1.WITHOUT_SUBFLOW_DOOR.add(inner);
+            return inner;
+        }
+        catch (e) {
+            return (`the retained record for '${record.toolCallId}' could not be opened: ` +
+                `${e instanceof Error ? e.message : String(e)}`);
+        }
+    };
+    return (0, tools_js_1.defineTool)({
+        name: 'inspect_tool_run',
+        description: 'Go INSIDE one tool call. Some tools are themselves recorded flowcharts and keep the ' +
+            'record of what they ran; this opens it. Called with just a toolCallId it returns a ' +
+            'bounded overview of the inner run (its stages, its errors, its state keys). Add ' +
+            "'find' to search that inner run in free text, 'variable' to ask why an inner value is " +
+            "what it is, 'key' alone for who last wrote an inner key, 'runtimeStageId' to open one " +
+            "inner step, or both 'runtimeStageId' and 'key' for an inner value in full. The ids it returns are the INNER chart's — the " +
+            'outer trace tools do not accept them. Reach for it when inspect_tool_call says a ' +
+            'record was kept and the question is about what the tool DID, not what it returned.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                toolCallId: {
+                    type: 'string',
+                    description: "The tool call to descend into — the same id inspect_tool_call takes, e.g. 'c1'.",
+                },
+                runtimeStageId: {
+                    type: 'string',
+                    description: "Optional: open ONE step of the inner run (an inner id, from this tool's own " +
+                        'overview — not an outer step id).',
+                },
+                key: {
+                    type: 'string',
+                    description: "Optional: an inner state key, e.g. 'forecast' — alone, who last wrote it inside; " +
+                        'with runtimeStageId, its value in full as of that step.',
+                },
+                variable: {
+                    type: 'string',
+                    description: 'Optional: an inner state key to explain — anchors at its last writer inside the ' +
+                        'chart and walks back.',
+                },
+                find: {
+                    type: 'string',
+                    description: 'Optional: free text to locate inside the inner run (returns inner ids).',
+                },
+                cause: {
+                    type: 'string',
+                    enum: ['attention_list', 'root_cause', 'impact'],
+                    description: 'Optional: ask a bounded cause tool inside this retained run.',
+                },
+                nodeId: {
+                    type: 'string',
+                    description: 'An opaque node id returned by attention_list inside this retained run.',
+                },
+            },
+            required: ['toolCallId'],
+            additionalProperties: false,
+        },
+        execute: async ({ toolCallId, runtimeStageId, key, variable, find, cause, nodeId }, ctx) => {
+            const lookup = artifacts.innerRuns;
+            if (lookup === undefined)
+                return (0, innerRecords_js_1.noInnerRecordsMessage)(toolCallId);
+            const record = lookup.get(toolCallId);
+            if (record === undefined)
+                return (0, innerRecords_js_1.unknownInnerRunMessage)(toolCallId, lookup, reader);
+            const inner = slot(record.toolCallId, () => openRecord(record));
+            if (typeof inner === 'string')
+                return inner;
+            const body = await (0, innerDescent_js_1.askInner)(inner, { runtimeStageId, key, variable, find, cause, nodeId }, callTraceTool, ctx);
+            return (0, innerDescent_js_1.framed)({
+                header: `INSIDE TOOL CALL ${toolCallId} — '${record.toolName}' ran a recorded flowchart ` +
+                    `(${record.steps} committed step(s), ${record.outcome}).`,
+                next: `next inside call '${toolCallId}': inspect_tool_run({ toolCallId: '${toolCallId}', ` +
+                    `runtimeStageId: '<inner id>' }) opens a step · add 'key' for a value in full · ` +
+                    `'variable' asks why an inner value is what it is · 'find' searches this inner run.`,
+                namespace: `⚠ the ids above are INNER ids — they name steps of ${record.toolName}'s own chart, ` +
+                    `not of the run that called it. trace_node / get_value / trace_slice do not accept ` +
+                    `them; come back through inspect_tool_run.`,
+            }, body);
+        },
+    });
+}
+/**
+ * INSIDE a subflow mount — the subflow's OWN log, opened.
+ *
+ * A subflow runs in an isolated runtime and commits to its own log, so this
+ * run's log holds only the mount boundary: what went in, what came back. The
+ * evidence of who wrote a value IN there was always recorded (footprintjs keeps
+ * it in `subflowResults`) — no tool served it. This one does, through the same
+ * descent `inspect_tool_run` uses (`innerDescent`): the inner views are the
+ * pack's own tools over the mount's own record, so the inner answers carry the
+ * same reason codes, folded from the SUBFLOW's own `initialState`.
+ *
+ *   - BY REFERENCE. Nothing from inside a subflow is printed until the model
+ *     asks; the outer views carry one line naming the door.
+ *   - ONE LEVEL AT A TIME. A mount nested inside a subflow is opened through
+ *     its parent's pack — this tool walks the chain (`mountChain`), each level
+ *     answering only for its own log.
+ *   - ITS OWN NAMESPACE. Inner ids are said to be inner on every answer, and
+ *     an outer tool handed one corrects toward here (`innerIdMessage`).
+ */
+function buildInspectSubflow(artifacts, index, options) {
+    const slot = (0, innerDescent_js_1.innerPackSlot)((inner) => traceToolpack(inner, options));
+    const isStep = (id) => index.nodes.has(id) || index.firstIdxOf.has(id);
+    const mountIds = () => index.orderedIds.filter((id) => index.nodes.get(id)?.subflowId);
+    const notAMount = (mount) => {
+        if (isStep(mount)) {
+            return `'${mount}' is an outer step, not a subflow mount — trace_node('${mount}') opens it.`;
+        }
+        const mounts = mountIds();
+        const sameStage = mounts.filter((id) => (0, packIndex_js_1.stagePartOf)(id) === mount);
+        if (sameStage.length > 0) {
+            return (`'${mount}' ran ${sameStage.length} time(s); a mount is ONE execution: ` +
+                `${sameStage.slice(0, structuralLimits_js_1.MOUNT_SUGGESTION_CAP).join(', ')}` +
+                `${sameStage.length > structuralLimits_js_1.MOUNT_SUGGESTION_CAP ? ', …' : ''}. Retry with one of those ids.`);
+        }
+        if (mounts.length === 0)
+            return `the traced run mounted no subflows — there is no inner log to open.`;
+        return (`unknown mount '${mount}'. Subflow mounts in the traced run: ` +
+            `${mounts.slice(0, structuralLimits_js_1.MOUNT_SUGGESTION_CAP).join(', ')}` +
+            `${mounts.length > structuralLimits_js_1.MOUNT_SUGGESTION_CAP ? ', …' : ''}.`);
+    };
+    return (0, tools_js_1.defineTool)({
+        name: 'inspect_subflow',
+        description: "Open a [subflow] step's OWN log (the run's log holds only its boundary). Mount id alone: " +
+            "inner overview. 'key': its last writer inside. 'variable': why it is what it is. " +
+            "'find': search. 'runtimeStageId' (+'key'): one inner step (value). Inner ids go back here.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                mount: { type: 'string', description: "The mount step, e.g. 'sf-tools#11'." },
+                runtimeStageId: { type: 'string', description: 'Optional: an inner step id.' },
+                key: { type: 'string', description: 'Optional: an inner state key.' },
+                variable: { type: 'string', description: 'Optional: an inner state key to explain.' },
+                find: { type: 'string', description: 'Optional: free text to locate inside.' },
+                cause: {
+                    type: 'string',
+                    enum: ['attention_list', 'root_cause', 'impact'],
+                    description: 'Optional: ask a bounded cause tool inside this subflow.',
+                },
+                nodeId: {
+                    type: 'string',
+                    description: 'An opaque node id returned by attention_list inside this subflow.',
+                },
+            },
+            required: ['mount'],
+            additionalProperties: false,
+        },
+        execute: async ({ mount, runtimeStageId, key, variable, find, cause, nodeId }, ctx) => {
+            const question = { runtimeStageId, key, variable, find, cause, nodeId };
+            const results = index.subflowResults;
+            const isMount = index.nodes.get(mount)?.subflowId !== undefined;
+            // A mount nested below this level: open its parent here, ask there.
+            if (!isMount && !isStep(mount) && results !== undefined) {
+                const chain = (0, subflowRecords_js_1.mountChain)(results, mount, isStep);
+                if (chain !== undefined && chain.length > 1) {
+                    const parent = chain[0];
+                    const pack = slot(parent, () => (0, innerRecords_js_1.openSubflowArtifacts)(artifacts, parent));
+                    if (typeof pack === 'string')
+                        return pack;
+                    return callTraceTool(pack, 'inspect_subflow', { mount, ...(0, innerRecords_js_1.definedOf)(question) }, ctx);
+                }
+            }
+            if (!isMount)
+                return notAMount(mount);
+            if (runtimeStageId !== undefined &&
+                runtimeStageId !== mount &&
+                isStep(runtimeStageId) &&
+                index.homeMountOf(runtimeStageId) !== mount) {
+                return (`'${runtimeStageId}' is a step of the run ABOVE subflow ${mount}, not of its own log — ` +
+                    `trace_node('${runtimeStageId}') opens it there.`);
+            }
+            const inner = slot(mount, () => (0, innerRecords_js_1.openSubflowArtifacts)(artifacts, mount));
+            if (typeof inner === 'string')
+                return inner;
+            const body = await (0, innerDescent_js_1.askInner)(inner, question, callTraceTool, ctx);
+            const name = index.nodes.get(mount)?.name;
+            const parent = index.homeMountOf(mount);
+            const commits = (0, subflowRecords_js_1.innerCommitCount)(index.subflowResults, mount);
+            return (0, innerDescent_js_1.framed)({
+                header: `INSIDE SUBFLOW ${mount}${name !== undefined ? ` — "${name}"` : ''}` +
+                    `${parent !== undefined ? ` (nested in ${parent})` : ''}: its own log, ` +
+                    `${commits} commit(s)${(0, subflowRecords_js_1.opensWithSeed)(index.subflowResults, mount) ? ", the mount's seed first" : ''}.`,
+                next: `next inside '${mount}': inspect_subflow({ mount: '${mount}', runtimeStageId: ` +
+                    `'<inner id>' }) opens a step · 'key' alone names its last writer inside · 'variable' ` +
+                    `asks why an inner value is what it is · 'find' searches this inner log.`,
+                namespace: `⚠ the ids above are INNER ids — steps of subflow ${mount}'s own log, not of the run ` +
+                    `that mounted it. trace_node / get_value / trace_slice correct them back here.`,
+            }, body);
+        },
+    });
+}
+// ── Scripted/offline invocation (the auditor pattern) ─────────────────────
+/**
+ * Minimal offline ToolExecutionContext — trace tools never use credentials.
+ *
+ * `teardownScopes: []` is a STATEMENT, not an omission (9.7.0): nothing fires
+ * here, ever. There is no run, no session and no dispatch loop to settle a call
+ * against — this context exists so a toolpack tool can be invoked from a script.
+ * A tool that reads the empty list knows not to open anything it would need
+ * closed; a tool that calls `onTeardown` anyway is refused by name rather than
+ * having its cleanup silently filed where nothing will run it.
+ */
+const OFFLINE_CONTEXT = {
+    toolCallId: 'trace-toolpack-offline',
+    iteration: 0,
+    credentials: (0, types_js_2.unconfiguredCredentialProvider)(),
+    hasCredentials: false,
+    // Offline has no run to scope refs to; the capability teaches, never lies.
+    artifacts: (0, capability_js_1.unconfiguredArtifacts)(),
+    hasArtifacts: false,
+    // Offline has no stage to emit from and no dispatcher to reach (9.52.0);
+    // a progress report is dropped rather than refused, because losing telemetry
+    // is not a reason to fail a call that is doing its work.
+    progress: () => {
+        /* nowhere to file it offline — see the note above */
+    },
+    teardownScopes: [],
+    onTeardown: () => {
+        throw new Error('callTraceTool: onTeardown is not honoured offline — `ctx.teardownScopes` is empty, ' +
+            'so no scope would ever fire. Run this tool inside an Agent if it holds a session.');
+    },
+};
+/**
+ * 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.
+ */
+async function callTraceTool(tools, name, args = {}, context = OFFLINE_CONTEXT) {
+    const tool = tools.find((candidate) => candidate.schema.name === name);
+    if (!tool) {
+        const available = tools.map((candidate) => candidate.schema.name).join(', ');
+        throw new Error(`callTraceTool: no tool named '${name}'. Available: ${available}`);
+    }
+    const verdict = (0, toolArgsValidation_js_1.validateToolArgs)(args, tool.schema.inputSchema);
+    if (!verdict.ok)
+        return (0, toolArgsValidation_js_1.formatToolArgIssues)(name, verdict.issues);
+    return String(await tool.execute(args, context));
+}
+exports.callTraceTool = callTraceTool;
+//# sourceMappingURL=recursiveFactory.js.map

package/dist/trace-toolpack/traceToolpack/recursiveFactory.js.map

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

package/dist/trace-toolpack/traceToolpack/runOverview.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildRunOverview = void 0;
+const tools_js_1 = require("../../tools/tools.js");
+const structuralLimits_js_1 = require("./structuralLimits.js");
+const valueLines_js_1 = require("./valueLines.js");
+const bounded_js_1 = require("../bounded.js");
+const foottrace_1 = require("foottrace");
+// ── run_overview ───────────────────────────────────────────────────────────
+/**
+ * ONE line, only when the run mounted subflows: their inner steps are not in
+ * this log, and here is the door. By reference — nothing from inside a
+ * subflow is printed until the model asks for it.
+ */
+function overviewSubflowLine(index) {
+    if (!index.subflowDoor)
+        return undefined;
+    const mounts = index.groups.filter((group) => group.isSubflow).flatMap((group) => group.ids);
+    if (mounts.length === 0)
+        return undefined;
+    const results = index.subflowResults;
+    const openable = mounts.find((id) => results !== undefined && id in results);
+    return openable !== undefined
+        ? `[subflow] steps ran their own log: inspect_subflow({ mount: '${openable}' }) opens one.`
+        : `[subflow] steps kept no own log here — inspect_subflow({ mount }) says why.`;
+}
+function buildRunOverview(artifacts, index) {
+    return (0, tools_js_1.defineTool)({
+        name: 'run_overview',
+        description: 'Start here. One bounded summary of the completed run: status, step counts, every ' +
+            'stage (id + name + description), loop counts, where errors appeared, and honesty notes. ' +
+            "Step ids look like 'stageId#executionIndex' (e.g. 'normalize#0'); every other trace " +
+            'tool accepts them.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        execute: () => {
+            const lines = ['TRACE RUN OVERVIEW'];
+            lines.push(index.errorSteps.length > 0
+                ? `status: ⚠ completed with ${index.errorSteps.length} step error(s) — see ERRORS below`
+                : 'status: no step errors recorded');
+            lines.push(`execution steps: ${index.orderedIds.length} · distinct stages: ${index.groups.length} · ` +
+                `commit-log mode: ${artifacts.snapshot.commitValues}`);
+            const example = index.orderedIds[0] ?? 'stageId#0';
+            lines.push(`step ids look like stageId#executionIndex (e.g. '${example}') — pass them to ` +
+                `trace_node / trace_slice / get_value.`);
+            lines.push('', `STAGES (${index.groups.length} distinct, first-execution order):`);
+            for (const group of index.groups.slice(0, structuralLimits_js_1.OVERVIEW_STAGE_CAP)) {
+                const flags = [
+                    group.isDecider ? ' [decision]' : '',
+                    group.isSubflow ? ' [subflow]' : '',
+                ].join('');
+                const name = group.name !== undefined ? ` — "${group.name}"` : '';
+                const description = group.description !== undefined
+                    ? `: ${(0, valueLines_js_1.truncateText)(group.description, structuralLimits_js_1.OVERVIEW_DESCRIPTION_CAP)}`
+                    : '';
+                const errors = group.errorIds.length > 0
+                    ? ` ⚠ errors in ${group.errorIds.slice(0, 3).join(', ')}${group.errorIds.length > 3 ? ', …' : ''}`
+                    : '';
+                lines.push(`- ${group.stagePart} ×${group.ids.length}${flags}${name}${description}${errors}`);
+            }
+            if (index.groups.length > structuralLimits_js_1.OVERVIEW_STAGE_CAP) {
+                lines.push(`…and ${index.groups.length - structuralLimits_js_1.OVERVIEW_STAGE_CAP} more stages (output capped)`);
+            }
+            const subflowHint = overviewSubflowLine(index);
+            if (subflowHint !== undefined)
+                lines.push(subflowHint);
+            const loops = index.groups.filter((g) => g.ids.length > 1);
+            if (loops.length > 0) {
+                const top = [...loops]
+                    .sort((a, b) => b.ids.length - a.ids.length)
+                    .slice(0, 5)
+                    .map((g) => `${g.stagePart} ×${g.ids.length}`)
+                    .join(' · ');
+                lines.push('', `LOOPS: ${top}`);
+            }
+            if (index.errorSteps.length > 0) {
+                lines.push('', 'ERRORS:');
+                for (const step of index.errorSteps.slice(0, structuralLimits_js_1.OVERVIEW_ERROR_CAP)) {
+                    lines.push(`- ⚠ ${step.id}: ${step.keys.join(', ')} (drill with trace_node('${step.id}'))`);
+                }
+                if (index.errorSteps.length > structuralLimits_js_1.OVERVIEW_ERROR_CAP) {
+                    lines.push(`…and ${index.errorSteps.length - structuralLimits_js_1.OVERVIEW_ERROR_CAP} more error steps`);
+                }
+            }
+            if (index.untrackedStepCount > 0) {
+                lines.push('', `HONESTY: ⚠ ${index.untrackedStepCount} step(s) consumed untracked inputs (args/env/silent ` +
+                    `reads) — causal slices through them may be incomplete; trace_node marks each one.`);
+            }
+            const stateKeys = Object.keys(artifacts.snapshot.sharedState ?? {});
+            const shown = stateKeys.slice(0, structuralLimits_js_1.OVERVIEW_KEY_CAP).map(bounded_js_1.displayKey);
+            lines.push('', `SHARED STATE KEYS (${stateKeys.length}): ${shown.join(', ')}` +
+                (stateKeys.length > structuralLimits_js_1.OVERVIEW_KEY_CAP
+                    ? `, … +${stateKeys.length - structuralLimits_js_1.OVERVIEW_KEY_CAP} more`
+                    : '') +
+                ' — values via who_wrote / get_value.');
+            // COST — only when the run actually priced itself. `cumEstimatedUsd`
+            // is seeded to 0 on every agent run and only ever moves under a
+            // configured `pricingTable`, so a zero here means "this run was not
+            // priced", and printing "$0.00" for it would be a number that lies.
+            const spend = (0, valueLines_js_1.committedFinal)(index, 'cumEstimatedUsd');
+            if (typeof spend === 'number' && spend > 0) {
+                const tokensIn = (0, valueLines_js_1.committedFinal)(index, 'cumTokensInput');
+                const tokensOut = (0, valueLines_js_1.committedFinal)(index, 'cumTokensOutput');
+                const writer = (0, foottrace_1.findLastWriter)(index.commitLog, 'cumEstimatedUsd');
+                lines.push('', `COST: ~$${spend.toFixed(6)} (in ${typeof tokensIn === 'number' ? tokensIn : '?'} / out ${typeof tokensOut === 'number' ? tokensOut : '?'} tokens) — estimated by the ` +
+                    `run's pricing table, not a bill` +
+                    (writer ? ` — via get_value('${writer.runtimeStageId}', 'cumEstimatedUsd').` : '.'));
+            }
+            if (artifacts.narrative !== undefined) {
+                lines.push(`NARRATIVE: ${artifacts.narrative.length} line(s) available via read_narrative.`);
+            }
+            lines.push(`SEARCH: find_in_trace('<text>') locates any phrase in this record and hands back ids.`);
+            return lines.join('\n');
+        },
+    });
+}
+exports.buildRunOverview = buildRunOverview;
+//# sourceMappingURL=runOverview.js.map

package/dist/trace-toolpack/traceToolpack/runOverview.js.map

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

package/dist/trace-toolpack/traceToolpack/sliceView.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTraceSlice = void 0;
+const tools_js_1 = require("../../tools/tools.js");
+const types_js_1 = require("../types.js");
+const parameterSchemas_js_1 = require("./parameterSchemas.js");
+const bounded_js_1 = require("../bounded.js");
+const navigationHints_js_1 = require("./navigationHints.js");
+const foottrace_1 = require("foottrace");
+// ── trace_slice ────────────────────────────────────────────────────────────
+function buildTraceSlice(artifacts, index, opts) {
+    return (0, tools_js_1.defineTool)({
+        name: 'trace_slice',
+        description: 'The causal chain: which earlier steps produced the data at a step (backward ' +
+            'read→write slice over the commit log, plus [control: rule] edges to the decisions ' +
+            'that routed execution when available). Returns a compact indented tree of step ids — ' +
+            'drill any (id) with trace_node, fetch values with get_value. Bounded by maxDepth ' +
+            `(default ${opts.sliceMaxDepth}, max ${types_js_1.TOOLPACK_HARD_CAPS.sliceMaxDepth}) and maxNodes ` +
+            `(default ${opts.sliceMaxNodes}, max ${types_js_1.TOOLPACK_HARD_CAPS.sliceMaxNodes}); truncation and ` +
+            "incomplete-slice ⚠ markers are always shown. Pass 'key' to slice one state key only.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                runtimeStageId: (0, parameterSchemas_js_1.idProperty)(index, "The step to slice back from, e.g. 'approve#0'."),
+                key: (0, parameterSchemas_js_1.keyProperty)(index, 'Optional: restrict the slice to the chain that produced THIS state key.'),
+                maxDepth: {
+                    type: 'integer',
+                    description: `Optional slice depth (default ${opts.sliceMaxDepth}, hard cap ${types_js_1.TOOLPACK_HARD_CAPS.sliceMaxDepth}).`,
+                },
+                maxNodes: {
+                    type: 'integer',
+                    description: `Optional node budget (default ${opts.sliceMaxNodes}, hard cap ${types_js_1.TOOLPACK_HARD_CAPS.sliceMaxNodes}).`,
+                },
+            },
+            required: ['runtimeStageId'],
+            additionalProperties: false,
+        },
+        execute: ({ runtimeStageId, key, maxDepth, maxNodes }) => {
+            if (!index.firstIdxOf.has(runtimeStageId)) {
+                if (index.nodes.has(runtimeStageId)) {
+                    const reads = Object.keys(index.nodes.get(runtimeStageId)?.stageReads ?? {});
+                    return (`step '${runtimeStageId}' committed nothing — the commit-log slice cannot root there. ` +
+                        (reads.length > 0
+                            ? `It read: ${reads
+                                .map(bounded_js_1.displayKey)
+                                .join(', ')} — use who_wrote on each, or trace_slice from a downstream step.`
+                            : 'Use trace_node for its details, or trace_slice from a downstream step.'));
+                }
+                return (0, navigationHints_js_1.unknownIdMessage)(runtimeStageId, index);
+            }
+            const depth = (0, bounded_js_1.clampParam)(maxDepth, opts.sliceMaxDepth, 1, types_js_1.TOOLPACK_HARD_CAPS.sliceMaxDepth);
+            const nodeBudget = (0, bounded_js_1.clampParam)(maxNodes, opts.sliceMaxNodes, 2, types_js_1.TOOLPACK_HARD_CAPS.sliceMaxNodes);
+            const keysReadOf = (id) => {
+                const node = index.nodes.get(id);
+                return node?.stageReads ? Object.keys(node.stageReads) : [];
+            };
+            const normalizedKey = key !== undefined ? (0, bounded_js_1.normalizeKey)(key, index.knownPaths) : undefined;
+            const keysFn = normalizedKey !== undefined
+                ? (id) => (id === runtimeStageId ? [normalizedKey] : keysReadOf(id))
+                : keysReadOf;
+            const dag = (0, foottrace_1.causalChain)(index.commitLog, runtimeStageId, keysFn, {
+                maxDepth: depth,
+                maxNodes: nodeBudget,
+                ...(artifacts.controlDeps ? { controlDeps: artifacts.controlDeps } : {}),
+            });
+            if (!dag)
+                return (0, navigationHints_js_1.unknownIdMessage)(runtimeStageId, index);
+            const lines = [
+                `CAUSAL SLICE from ${runtimeStageId}` +
+                    (normalizedKey !== undefined ? ` for key '${(0, bounded_js_1.displayKey)(normalizedKey)}'` : '') +
+                    ` (maxDepth ${depth}, maxNodes ${nodeBudget})`,
+                'each line: Stage (stepId) ← via <the key it provided> [wrote: …]. Drill any (stepId) ' +
+                    'with trace_node; fetch values with get_value.',
+                '',
+                (0, bounded_js_1.displayText)((0, foottrace_1.formatCausalChain)(dag)),
+            ];
+            if (!artifacts.controlDeps) {
+                lines.push('⚠ control edges unavailable — artifacts carry no controlDeps lookup (attach ' +
+                    'controlDepRecorder() to the original run); decisions that routed execution are not shown.');
+            }
+            if (!index.hasReadTracking) {
+                lines.push('⚠ artifacts carry no per-step read tracking — read→write edges cannot be followed; ' +
+                    'the slice may show only the start step.');
+            }
+            return lines.join('\n');
+        },
+    });
+}
+exports.buildTraceSlice = buildTraceSlice;
+//# sourceMappingURL=sliceView.js.map