agentfootprint 13.0.0 → 14.0.0

package/dist/esm/trace-toolpack/traceToolpack/findInTrace.js

@@ -0,0 +1,178 @@
+import { defineTool } from '../../tools/tools.js';
+import { FIND_HITS_DEFAULT, FIND_QUERY_MIN_CHARS, FIND_QUERY_MAX_CHARS, FIND_CONTEXT_RADIUS, FIND_SCAN_BUDGET, } from './structuralLimits.js';
+import { TOOLPACK_HARD_CAPS } from '../types.js';
+import { clampParam, displayKey, safeStringify, displayText } from '../bounded.js';
+import { redactionNote } from './valueLines.js';
+/** A bounded window of `text` around the first case-insensitive match. */
+function matchWindow(text, needleLower, radius) {
+    const at = text.toLowerCase().indexOf(needleLower);
+    if (at < 0)
+        return undefined;
+    const start = Math.max(0, at - radius);
+    const end = Math.min(text.length, at + needleLower.length + radius);
+    return ((start > 0 ? '…' : '') +
+        text.slice(start, end).replace(/\s+/g, ' ') +
+        (end < text.length ? '…' : ''));
+}
+// ── find_in_trace ──────────────────────────────────────────────────────────
+/**
+ * The missing FIRST move.
+ *
+ * Every other tool needs a name you already have: a step id, a state key,
+ * a variable. But a follow-up question arrives in the user's words — "why
+ * did you say order 7712 was out of warranty?" — and the model's only
+ * options were to guess a key or read the whole narrative. This is the
+ * bridge from free text to ids: search the record, hand back POINTERS.
+ *
+ * Three properties make it a search rather than a dump:
+ *
+ *   - it serves a bounded WINDOW around each match, never the value;
+ *   - every hit line ends with the exact next call to make, so a search
+ *     result is a menu of drills rather than an answer to be believed;
+ *   - it searches the REDACTED commit log, because that is the only copy
+ *     that exists — a redacted value reads as its placeholder here for
+ *     the same reason it does everywhere else.
+ *
+ * The zero-hit answer is the honest one: it names what never enters the
+ * record at all, so "not found" cannot be read as "did not happen".
+ */
+function buildFindInTrace(artifacts, index) {
+    return defineTool({
+        name: 'find_in_trace',
+        description: 'Search this run\'s record for free text — "7712", "out of stock", a phrase from the ' +
+            'answer — and get back the step ids and keys where it appears. Searches stage names and ' +
+            'descriptions, state keys, every committed value, and the narrative. Case-insensitive ' +
+            `substring; returns up to maxHits pointers (default ${FIND_HITS_DEFAULT}, hard cap ` +
+            `${TOOLPACK_HARD_CAPS.findMaxHits}), each with the exact follow-up call to make. Use it ` +
+            'FIRST when the question names something the run mentioned but you have no id for.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'The text to look for (case-insensitive substring), e.g. an order id, a phrase ' +
+                        'from the answer, or a tool name.',
+                },
+                maxHits: {
+                    type: 'integer',
+                    description: `Pointers to return (default ${FIND_HITS_DEFAULT}, hard cap ${TOOLPACK_HARD_CAPS.findMaxHits}).`,
+                },
+            },
+            required: ['query'],
+            additionalProperties: false,
+        },
+        execute: ({ query, maxHits }) => {
+            const trimmed = query.trim();
+            if (trimmed.length < FIND_QUERY_MIN_CHARS) {
+                return (`find_in_trace: '${trimmed}' is too short to search (minimum ${FIND_QUERY_MIN_CHARS} ` +
+                    `characters) — a one-character query matches nearly every step, which is the same as ` +
+                    `no answer. Search for an id, a value, a key, or a phrase from the answer.`);
+            }
+            const needle = trimmed.slice(0, FIND_QUERY_MAX_CHARS).toLowerCase();
+            const cap = clampParam(maxHits, FIND_HITS_DEFAULT, 1, TOOLPACK_HARD_CAPS.findMaxHits);
+            const hits = [];
+            let scans = 0;
+            let budgetHit = false;
+            /** Record a hit; true once the cap is reached and scanning should stop. */
+            const add = (line) => {
+                hits.push(line);
+                return hits.length >= cap;
+            };
+            // 1. STAGES — what the run's steps are called and what they claim to do.
+            let full = false;
+            for (const group of index.groups) {
+                const haystack = `${group.stagePart} ${group.name ?? ''} ${group.description ?? ''}`;
+                const window = matchWindow(haystack, needle, FIND_CONTEXT_RADIUS);
+                if (window === undefined)
+                    continue;
+                if (add(`- stage: ${window} → trace_node('${group.ids[0]}')`)) {
+                    full = true;
+                    break;
+                }
+            }
+            // 2. STATE KEYS — the names, not the values (those are step 3).
+            if (!full) {
+                for (const path of index.knownPaths) {
+                    const dotted = displayKey(path);
+                    if (!dotted.toLowerCase().includes(needle))
+                        continue;
+                    if (add(`- state key '${dotted}' → who_wrote('${dotted}')`)) {
+                        full = true;
+                        break;
+                    }
+                }
+            }
+            // 3. COMMITTED VALUES — what each step actually wrote. Serialized ONE
+            //    (step, key) payload at a time and discarded: a search must never
+            //    build a serialization of the whole log to look through.
+            if (!full) {
+                outer: for (const bundle of index.commitLog) {
+                    const overwrite = bundle.overwrite;
+                    const updates = bundle.updates;
+                    for (const entry of bundle.trace) {
+                        if (scans >= FIND_SCAN_BUDGET) {
+                            budgetHit = true;
+                            break outer;
+                        }
+                        scans++;
+                        const payload = overwrite?.[entry.path] ?? updates?.[entry.path];
+                        if (payload === undefined)
+                            continue;
+                        const window = matchWindow(safeStringify(payload), needle, FIND_CONTEXT_RADIUS);
+                        if (window === undefined)
+                            continue;
+                        const dotted = displayKey(entry.path);
+                        if (add(`- ${bundle.runtimeStageId} wrote '${dotted}' (${entry.verb}): ${displayText(window)}${redactionNote([bundle], entry.path)} → get_value('${bundle.runtimeStageId}', '${dotted}')`)) {
+                            full = true;
+                            break outer;
+                        }
+                    }
+                }
+            }
+            // 4. NARRATIVE — the story, when the artifacts carry one.
+            const narrative = artifacts.narrative;
+            if (!full && narrative !== undefined) {
+                for (let i = 0; i < narrative.length; i++) {
+                    const window = matchWindow(narrative[i], needle, FIND_CONTEXT_RADIUS);
+                    if (window === undefined)
+                        continue;
+                    if (add(`- narrative line ${i}: ${displayText(window)} → read_narrative({ offset: ${i} })`)) {
+                        full = true;
+                        break;
+                    }
+                }
+            }
+            const scope = `${index.groups.length} stage(s), ${index.knownPaths.size} state key(s), ` +
+                `${index.commitLog.length} committed step(s)` +
+                (narrative !== undefined ? `, ${narrative.length} narrative line(s)` : '');
+            if (hits.length === 0) {
+                return (`find_in_trace: no match for '${trimmed}' — searched ${scope}.\n` +
+                    (budgetHit
+                        ? `⚠ the value scan stopped after ${FIND_SCAN_BUDGET} writes, so this is "not found ` +
+                            `so far", not "not present" — narrow the query or drill with run_overview.\n`
+                        : '') +
+                    `⚠ some things NEVER enter the record and cannot be found here: run input (args), env, ` +
+                    `state seeded before the run, values carried in closures, and anything redaction removed ` +
+                    `(those read as their placeholder). Tool internals are not traced either — only the ` +
+                    `arguments in and the result out.\n` +
+                    `Try a shorter phrase, a key from run_overview, or read_narrative for the story.`);
+            }
+            const lines = [
+                `FOUND ${hits.length}${hits.length >= cap ? '+' : ''} match(es) for '${trimmed}' ` +
+                    `in ${scope} — each line ends with the call that opens it:`,
+                ...hits,
+            ];
+            if (hits.length >= cap) {
+                lines.push(`⚠ stopped at maxHits ${cap} — more matches may exist. Narrow the query, or raise ` +
+                    `maxHits (hard cap ${TOOLPACK_HARD_CAPS.findMaxHits}).`);
+            }
+            if (budgetHit) {
+                lines.push(`⚠ the value scan stopped after ${FIND_SCAN_BUDGET} writes — later steps were not ` +
+                    `searched. Narrow the query or drill from run_overview.`);
+            }
+            return lines.join('\n');
+        },
+    });
+}
+export { buildFindInTrace };
+//# sourceMappingURL=findInTrace.js.map

package/dist/esm/trace-toolpack/traceToolpack/findInTrace.js.map

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

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

@@ -0,0 +1,73 @@
+import type { ContextErrorKind, ContextError } from '../../integrity/finding/types.js';
+import type { ToolpackIndex } from './packIndex.js';
+import type { CheckReport } from '../../integrity/disposition/types.js';
+/** The kinds the tool OFFERS — the ones a shipped check can actually file. */
+declare const CONTEXT_ERROR_KINDS: ContextErrorKind[];
+/** Named in the finding type, filable by nothing here. Said out loud, never offered. */
+declare const UNFILABLE_CONTEXT_ERROR_KINDS: ContextErrorKind[];
+/**
+ * The answer for a `kind` this build cannot report on.
+ *
+ * It runs BEFORE the evidence checks on purpose: whether a class is filable
+ * is a fact about the BUILD, not about the run, and it stays true however
+ * much evidence the tail carries. Args validation is a dial
+ * (`toolArgValidation: 'off' | 'warn'`), so the enum is a menu rather than a
+ * wall — `execute` really is reachable with a kind it never offered, and the
+ * one answer it must never give there is a negative verdict.
+ */
+declare function unanswerableKind(kind: string): string | undefined;
+declare const CONTEXT_ERROR_EVENT = "agentfootprint.integrity.context_error";
+declare const DISPOSITION_EVENT = "agentfootprint.integrity.disposition";
+/**
+ * An advisory is a filed finding the seam marked as NOT a defect (9.61.0 —
+ * today, an answer that DECLINES to claim a fact the run verified). Same
+ * quarantine rule as the dev canary: it is shown, and it is never counted
+ * as a context error. A reader that did not know the field would report
+ * doubt as a contradiction.
+ */
+declare function isAdvisory(filed: FiledFinding): boolean;
+/**
+ * The standing bound of the whole Context Integrity family, repeated
+ * wherever this tool reports — because the sentence it prevents ("nothing
+ * was found, so the run is fine") is the exact misreading that let two
+ * shipped checks in this codebase decay into decoration.
+ */
+declare const INTEGRITY_BOUND: string;
+/**
+ * One filed finding, joined to the step the event was stamped with.
+ *
+ * The payload is read as PARTIAL on purpose: an event tail may have been
+ * parsed back from JSON, or written by an older version of the library that
+ * did not file every field this one knows about.
+ */
+interface FiledFinding {
+    readonly error: Partial<ContextError> & {
+        readonly iteration?: number;
+    };
+    readonly filedAt?: string;
+    readonly iteration?: number;
+}
+/** Subjects, read defensively: an event tail may have been parsed from JSON. */
+declare function subjectsOf(raw: unknown): {
+    kind: string;
+    id: string;
+}[];
+/** The witness assertions' step ids — the two-or-more facts that disagreed. */
+declare function witnessStepsOf(raw: unknown): {
+    ids: string[];
+    total: number;
+    unstamped: number;
+};
+/**
+ * The commit-log answer for ONE state key, in a sentence.
+ *
+ * It walks nothing new: `findLastWriter` + `commitValueAt` are the same
+ * pair `who_wrote` and `get_value` use, so there is no second reader of the
+ * commit log to drift — only a shorter sentence, and the exact follow-up
+ * calls that open the long one.
+ */
+declare function stateJoinFor(index: ToolpackIndex, path: string, previewChars: number): string | undefined;
+/** Render ONE disposition row: did this check run, and what did it see? */
+declare function dispositionLine(report: CheckReport): string;
+export { CONTEXT_ERROR_KINDS, UNFILABLE_CONTEXT_ERROR_KINDS, unanswerableKind, CONTEXT_ERROR_EVENT, DISPOSITION_EVENT, isAdvisory, INTEGRITY_BOUND, subjectsOf, witnessStepsOf, stateJoinFor, dispositionLine, };
+export type { FiledFinding };

package/dist/esm/trace-toolpack/traceToolpack/findingEvidence.js

@@ -0,0 +1,176 @@
+import { safeStringify, boundedPreview, displayKey, displayText, renderPreview, } from '../bounded.js';
+import { findLastWriter, commitValueAt } from 'foottrace';
+import { redactionNote } from './valueLines.js';
+// ── find_context_errors ────────────────────────────────────────────────────
+/**
+ * The six ContextErrorKinds — each mapped to the check that can FILE it in
+ * this build, or `false` when no check ships for that class.
+ *
+ * Two jobs in one table:
+ *
+ *   - the compile-time pin. The record's KEY type is `ContextErrorKind`, so
+ *     a kind added to the finding type without joining this list fails to
+ *     compile HERE, rather than becoming a value the tool's enum silently
+ *     rejects at run time.
+ *   - the honesty gate. `ContextErrorKind` names nine defect classes;
+ *     `src/integrity/` ships eight checks. Offering the sixth in the
+ *     schema enum invites a query whose only possible answer is a negative
+ *     verdict about a class nothing in the library could have filed — the
+ *     tool telling a model "no duplicate-execution errors" when nothing on
+ *     earth was looking for one. Only filable kinds reach the enum; the
+ *     description and the refusal are generated from this same table, so a
+ *     check that lands is advertised everywhere by flipping one entry.
+ */
+const CONTEXT_ERROR_KIND_CHECKS = {
+    'invariant-violation': 'src/integrity/invariant-violation (write + wire)',
+    'unsupported-argument': 'src/integrity/unsupported-argument (choice)',
+    'dangling-reference': 'src/integrity/dangling-reference (compose)',
+    'duplicate-execution': false,
+    'unsupported-claim': 'src/integrity/unsupported-claim (claim)',
+    'empty-lookup': 'src/integrity/empty-lookup (write)',
+    'column-type-mismatch': 'src/integrity/column-types (write)',
+    'missing-column': 'src/integrity/column-types (write)',
+    'prior-turn-evidence': 'src/integrity/prior-turn-evidence (claim)',
+};
+const ALL_CONTEXT_ERROR_KINDS = Object.keys(CONTEXT_ERROR_KIND_CHECKS);
+/** The kinds the tool OFFERS — the ones a shipped check can actually file. */
+const CONTEXT_ERROR_KINDS = ALL_CONTEXT_ERROR_KINDS.filter((kind) => CONTEXT_ERROR_KIND_CHECKS[kind] !== false);
+/** Named in the finding type, filable by nothing here. Said out loud, never offered. */
+const UNFILABLE_CONTEXT_ERROR_KINDS = ALL_CONTEXT_ERROR_KINDS.filter((kind) => CONTEXT_ERROR_KIND_CHECKS[kind] === false);
+/**
+ * The answer for a `kind` this build cannot report on.
+ *
+ * It runs BEFORE the evidence checks on purpose: whether a class is filable
+ * is a fact about the BUILD, not about the run, and it stays true however
+ * much evidence the tail carries. Args validation is a dial
+ * (`toolArgValidation: 'off' | 'warn'`), so the enum is a menu rather than a
+ * wall — `execute` really is reachable with a kind it never offered, and the
+ * one answer it must never give there is a negative verdict.
+ */
+function unanswerableKind(kind) {
+    const offered = CONTEXT_ERROR_KINDS.join(', ');
+    if (!Object.prototype.hasOwnProperty.call(CONTEXT_ERROR_KIND_CHECKS, kind)) {
+        return (`find_context_errors: ⚠ '${kind}' is not a defect class this library knows — it is not a ` +
+            `Context Integrity kind at all, so nothing was ever filed under that word and this answer ` +
+            `says nothing about the run. Classes this build can file: ${offered}.`);
+    }
+    if (CONTEXT_ERROR_KIND_CHECKS[kind] !== false)
+        return undefined;
+    return (`find_context_errors: ⚠ UNANSWERABLE — '${kind}' is a defect class the finding type names, ` +
+        `and no check in this build can file it. Nothing ever looked for one, so silence about it is ` +
+        `not evidence of its absence. Classes this build can file: ${offered} — call again with one ` +
+        `of those, or with no 'kind' at all.`);
+}
+const CONTEXT_ERROR_EVENT = 'agentfootprint.integrity.context_error';
+const DISPOSITION_EVENT = 'agentfootprint.integrity.disposition';
+/**
+ * An advisory is a filed finding the seam marked as NOT a defect (9.61.0 —
+ * today, an answer that DECLINES to claim a fact the run verified). Same
+ * quarantine rule as the dev canary: it is shown, and it is never counted
+ * as a context error. A reader that did not know the field would report
+ * doubt as a contradiction.
+ */
+function isAdvisory(filed) {
+    return filed.error.advisory === true;
+}
+/**
+ * The standing bound of the whole Context Integrity family, repeated
+ * wherever this tool reports — because the sentence it prevents ("nothing
+ * was found, so the run is fine") is the exact misreading that let two
+ * shipped checks in this codebase decay into decoration.
+ */
+const INTEGRITY_BOUND = '⚠ Green means no REGISTERED check was violated — it does not mean no context error exists. ' +
+    'A seam with no checker files nothing, and an encounter with no stamped identity is silent.';
+/** Subjects, read defensively: an event tail may have been parsed from JSON. */
+function subjectsOf(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const item of raw) {
+        if (item === null || typeof item !== 'object')
+            continue;
+        const subject = item;
+        out.push({
+            kind: typeof subject.kind === 'string' ? subject.kind : '?',
+            id: typeof subject.id === 'string' ? subject.id : safeStringify(subject.id),
+        });
+    }
+    return out;
+}
+/** The witness assertions' step ids — the two-or-more facts that disagreed. */
+function witnessStepsOf(raw) {
+    if (!Array.isArray(raw))
+        return { ids: [], total: 0, unstamped: 0 };
+    const ids = [];
+    let unstamped = 0;
+    for (const item of raw) {
+        const stamp = item !== null && typeof item === 'object'
+            ? item.runtimeStageId
+            : undefined;
+        if (typeof stamp === 'string' && stamp !== '') {
+            if (!ids.includes(stamp))
+                ids.push(stamp);
+        }
+        else
+            unstamped++;
+    }
+    return { ids, total: raw.length, unstamped };
+}
+/**
+ * The commit-log answer for ONE state key, in a sentence.
+ *
+ * It walks nothing new: `findLastWriter` + `commitValueAt` are the same
+ * pair `who_wrote` and `get_value` use, so there is no second reader of the
+ * commit log to drift — only a shorter sentence, and the exact follow-up
+ * calls that open the long one.
+ */
+function stateJoinFor(index, path, previewChars) {
+    const writer = findLastWriter(index.commitLog, path);
+    if (!writer)
+        return undefined;
+    const preview = boundedPreview(commitValueAt(index.commitLog, index.commitLog.indexOf(writer), path), previewChars);
+    const dotted = displayKey(path);
+    return (`'${dotted}' = ${displayText(renderPreview(preview))}${redactionNote([writer], path)} — last ` +
+        `written by ${writer.runtimeStageId} ("${writer.stage}") → who_wrote('${dotted}') · ` +
+        `backtrack({ variable: '${dotted}' })`);
+}
+/** Render ONE disposition row: did this check run, and what did it see? */
+function dispositionLine(report) {
+    const check = typeof report.check === 'string' ? report.check : '?';
+    const head = `- ${check} @${report.seam ?? '?'}`;
+    const checked = typeof report.checked === 'number' ? report.checked : 0;
+    const notApplicable = typeof report.notApplicable === 'number' ? report.notApplicable : 0;
+    const unreachable = typeof report.unreachable === 'number' ? report.unreachable : 0;
+    const findings = typeof report.findings === 'number' ? report.findings : 0;
+    const synthetic = typeof report.synthetic === 'number' ? report.synthetic : 0;
+    if (checked + notApplicable + unreachable === 0) {
+        return (`${head}: ⚠ REGISTERED BUT NEVER RAN — zero encounters while this run did work. The check ` +
+            `is wired and nothing fed it (wiring rot); its silence is not health.`);
+    }
+    // `ran 0×` with encounters on the other counters is NOT "found nothing":
+    // every encounter was out of scope or unreachable, so this seam went
+    // unchecked. Saying it found nothing would read the count backwards.
+    const parts = [
+        checked > 0 ? `ran ${checked}×` : `⚠ ran 0× — nothing at this seam was actually checked`,
+        ...(findings > 0
+            ? [`${findings} finding(s)`]
+            : checked > 0
+                ? ['0 findings — the checker ran and found nothing at this seam']
+                : []),
+    ];
+    if (notApplicable > 0) {
+        parts.push(`not-applicable ${notApplicable} (out of scope by rule)`);
+    }
+    if (unreachable > 0) {
+        parts.push(`unreachable ${unreachable} ⚠ — no stamped identity edge, so those encounters were SILENT, ` +
+            `not clean`);
+    }
+    if (synthetic > 0)
+        parts.push(`synthetic canary ${synthetic} (quarantined from the real counts)`);
+    if (typeof report.lastFiredAt === 'number') {
+        parts.push(`last fired ${new Date(report.lastFiredAt).toISOString()}`);
+    }
+    return `${head}: ${parts.join(' · ')}`;
+}
+export { CONTEXT_ERROR_KINDS, UNFILABLE_CONTEXT_ERROR_KINDS, unanswerableKind, CONTEXT_ERROR_EVENT, DISPOSITION_EVENT, isAdvisory, INTEGRITY_BOUND, subjectsOf, witnessStepsOf, stateJoinFor, dispositionLine, };
+//# sourceMappingURL=findingEvidence.js.map

package/dist/esm/trace-toolpack/traceToolpack/findingEvidence.js.map

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

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

@@ -0,0 +1,11 @@
+import type { TraceToolpackArtifacts } from '../types.js';
+import type { ToolCallReader } from './toolCallJournal.js';
+/** The mount's record as an artifact bag, or why there is none. */
+declare function openSubflowArtifacts(artifacts: TraceToolpackArtifacts, mount: string): TraceToolpackArtifacts | string;
+/** The question's params that were actually given (strict schemas refuse `undefined`). */
+declare function definedOf(question: Record<string, string | undefined>): Record<string, string>;
+/** No tool in this run keeps a record — name the switch, not the emptiness. */
+declare function noInnerRecordsMessage(toolCallId: string): string;
+/** A record was expected and is not here: evicted, or never kept for THIS tool. */
+declare function unknownInnerRunMessage(toolCallId: string, lookup: NonNullable<TraceToolpackArtifacts['innerRuns']>, reader: ToolCallReader): string;
+export { openSubflowArtifacts, definedOf, noInnerRecordsMessage, unknownInnerRunMessage };

package/dist/esm/trace-toolpack/traceToolpack/innerRecords.js

@@ -0,0 +1,88 @@
+import { openSubflow } from '../subflowRecords.js';
+import { RAW_CONTROL_DEPS } from './artifactFacts.js';
+import { INNER_RUN_SUGGESTION_CAP } from './structuralLimits.js';
+/** The mount's record as an artifact bag, or why there is none. */
+function openSubflowArtifacts(artifacts, mount) {
+    const opened = openSubflow(artifacts.snapshot, mount);
+    if (typeof opened === 'string')
+        return `inspect_subflow: ${opened}`;
+    // Step ids are unique across a run, so the RUN's lookup answers inner ids —
+    // but a decider OUTSIDE this log is not an inner step: keep only edges from
+    // a decider in the mount's own log, so no outer id is served as an inner one.
+    // Always filter the run's RAW lookup, never this level's filtered one: a
+    // nested mount's deciders are not in its parent's log, so filtering the
+    // parent's view would drop every edge one level further down.
+    const raw = RAW_CONTROL_DEPS.get(artifacts) ?? artifacts.controlDeps;
+    const innerIds = new Set(opened.commitLog.map((bundle) => bundle.runtimeStageId));
+    const bag = {
+        snapshot: opened,
+        ...(raw !== undefined && {
+            controlDeps: (id) => {
+                const dep = raw(id);
+                return dep !== undefined && innerIds.has(dep.deciderId) ? dep : undefined;
+            },
+        }),
+    };
+    if (raw !== undefined)
+        RAW_CONTROL_DEPS.set(bag, raw);
+    return bag;
+}
+/** The question's params that were actually given (strict schemas refuse `undefined`). */
+function definedOf(question) {
+    return Object.fromEntries(Object.entries(question).filter((entry) => entry[1] !== undefined));
+}
+/** No tool in this run keeps a record — name the switch, not the emptiness. */
+function noInnerRecordsMessage(toolCallId) {
+    return (`inspect_tool_run: nothing in this run kept a record below the tool boundary, so there is ` +
+        `no inner run for '${toolCallId}' — or for any other call. A tool keeps one only when it ` +
+        `was built to: flowchartAsTool({ name, flowchart, keepRecord: true }). That switch is OFF ` +
+        `by default because retaining a run's snapshot per invocation is memory the caller has to ` +
+        `agree to. Without it the trace holds the envelope — arguments in, result out — which is ` +
+        `what inspect_tool_call('${toolCallId}') serves.`);
+}
+/** A record was expected and is not here: evicted, or never kept for THIS tool. */
+function unknownInnerRunMessage(toolCallId, lookup, reader) {
+    const kept = lookup.list();
+    const lines = [
+        `inspect_tool_run: no retained inner run for tool call '${toolCallId}'.`,
+    ];
+    // Did the OUTER run make this call at all? Three different situations
+    // wear the same "not found", and only one of them is the consumer's to fix.
+    const outer = reader.knownCalls().find((call) => call.id === toolCallId);
+    if (outer === undefined) {
+        lines.push(`⚠ the outer run does not record a call with that id either — check ` +
+            `inspect_tool_call('${toolCallId}') first; it names every id the outer run recorded.`);
+    }
+    else {
+        lines.push(`That call ran '${outer.name}', which either does not keep records (only ` +
+            `flowchartAsTool({ keepRecord: true }) does) or had this one dropped.`);
+    }
+    if (kept.length === 0) {
+        // Past tense, anchored to the lookup that was answered (9.86.0). "Right
+        // now" pointed at the moment of READING, and this string is a tool result
+        // the model re-reads on every later call of the debugging turn.
+        lines.push(`No inner run was held when inspect_tool_run('${toolCallId}') was answered. A tool that ` +
+            `keeps records had not been called in the turn this trace covers.`);
+    }
+    else {
+        const sample = kept
+            .slice(0, INNER_RUN_SUGGESTION_CAP)
+            .map((row) => `${row.toolCallId} (${row.toolName}, ${row.steps} step(s), ${row.outcome})`)
+            .join(', ');
+        lines.push(`Inner runs you CAN open (${kept.length}): ${sample}` +
+            (kept.length > INNER_RUN_SUGGESTION_CAP ? ', …' : '') +
+            '.');
+    }
+    if (lookup.dropped > 0) {
+        lines.push(
+        // Named by id, not "this call" (9.86.1): the same repair the
+        // schema-validation line above got in 9.86.0, on the arm the checker
+        // could not see because its rule only knew `on this call`.
+        `⚠ ${lookup.dropped} older record(s) were dropped to stay under the retention cap of ` +
+            `${lookup.limit} — call '${toolCallId}' may be one of them. Raise it with ` +
+            `keepRecordLimit, or ask sooner after the call.`);
+    }
+    return lines.join('\n');
+}
+export { openSubflowArtifacts, definedOf, noInnerRecordsMessage, unknownInnerRunMessage };
+//# sourceMappingURL=innerRecords.js.map

package/dist/esm/trace-toolpack/traceToolpack/innerRecords.js.map

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

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

@@ -0,0 +1,3 @@
+import type { Tool } from '../../tools/tools.js';
+declare function buildReadNarrative(narrative: readonly string[]): Tool;
+export { buildReadNarrative };

package/dist/esm/trace-toolpack/traceToolpack/narrativeView.js

@@ -0,0 +1,44 @@
+import { defineTool } from '../../tools/tools.js';
+import { TOOLPACK_HARD_CAPS } from '../types.js';
+import { clampParam, displayText } from '../bounded.js';
+import { truncateText } from './valueLines.js';
+import { NARRATIVE_LINE_CHAR_CAP } from './structuralLimits.js';
+// ── read_narrative ─────────────────────────────────────────────────────────
+function buildReadNarrative(narrative) {
+    return defineTool({
+        name: 'read_narrative',
+        description: "Read the run's human-readable narrative, paginated: offset (0-based line index) + " +
+            `maxLines (default 40, hard cap ${TOOLPACK_HARD_CAPS.narrativeMaxLines}). Long lines are ` +
+            'capped. Use AFTER the structured tools when you need the story around a step.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                offset: { type: 'integer', description: '0-based first line to read (default 0).' },
+                maxLines: {
+                    type: 'integer',
+                    description: `Lines to read (default 40, hard cap ${TOOLPACK_HARD_CAPS.narrativeMaxLines}).`,
+                },
+            },
+            additionalProperties: false,
+        },
+        execute: ({ offset, maxLines }) => {
+            const total = narrative.length;
+            if (total === 0)
+                return 'NARRATIVE: empty (0 lines).';
+            const start = clampParam(offset, 0, 0, Math.max(0, total - 1));
+            const count = clampParam(maxLines, 40, 1, TOOLPACK_HARD_CAPS.narrativeMaxLines);
+            const slice = narrative.slice(start, start + count);
+            const lines = [
+                `NARRATIVE lines ${start}–${start + slice.length - 1} of ${total}:`,
+                ...slice.map((line) => truncateText(displayText(line), NARRATIVE_LINE_CHAR_CAP)),
+            ];
+            const remaining = total - (start + slice.length);
+            if (remaining > 0) {
+                lines.push(`…${remaining} more line(s) — call read_narrative({ offset: ${start + slice.length} }).`);
+            }
+            return lines.join('\n');
+        },
+    });
+}
+export { buildReadNarrative };
+//# sourceMappingURL=narrativeView.js.map

package/dist/esm/trace-toolpack/traceToolpack/narrativeView.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"narrativeView.js","sourceRoot":"","sources":["../../../../src/trace-toolpack/traceToolpack/narrativeView.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAEhE,8EAA8E;AAE9E,SAAS,kBAAkB,CAAC,SAA4B;IACtD,OAAO,UAAU,CAAiD;QAChE,IAAI,EAAE,gBAAgB;QACtB,WAAW,EACT,oFAAoF;YACpF,kCAAkC,kBAAkB,CAAC,iBAAiB,oBAAoB;YAC1F,+EAA+E;QACjF,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,yCAAyC,EAAE;gBACnF,QAAQ,EAAE;oBACR,IAAI,EAAE,SAAS;oBACf,WAAW,EAAE,uCAAuC,kBAAkB,CAAC,iBAAiB,IAAI;iBAC7F;aACF;YACD,oBAAoB,EAAE,KAAK;SAC5B;QACD,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE;YAChC,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,CAAC;YAC/B,IAAI,KAAK,KAAK,CAAC;gBAAE,OAAO,6BAA6B,CAAC;YACtD,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;YAC/D,MAAM,KAAK,GAAG,UAAU,CAAC,QAAQ,EAAE,EAAE,EAAE,CAAC,EAAE,kBAAkB,CAAC,iBAAiB,CAAC,CAAC;YAChF,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC;YACpD,MAAM,KAAK,GAAG;gBACZ,mBAAmB,KAAK,IAAI,KAAK,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,OAAO,KAAK,GAAG;gBACnE,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,uBAAuB,CAAC,CAAC;aACjF,CAAC;YACF,MAAM,SAAS,GAAG,KAAK,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;YACjD,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;gBAClB,KAAK,CAAC,IAAI,CACR,IAAI,SAAS,iDAAiD,KAAK,GAAG,KAAK,CAAC,MAAM,MAAM,CACzF,CAAC;YACJ,CAAC;YACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED,OAAO,EAAE,kBAAkB,EAAE,CAAC"}

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

@@ -0,0 +1,6 @@
+import type { ToolpackIndex } from './packIndex.js';
+declare function unknownIdMessage(id: string, index: ToolpackIndex): string;
+/** The one line a subflow mount carries: it can be opened, and how. */
+declare function mountLine(index: ToolpackIndex, id: string): string;
+declare function unknownKeySuffix(index: ToolpackIndex): string;
+export { unknownIdMessage, mountLine, unknownKeySuffix };