agentfootprint 13.0.0 → 14.0.0

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

@@ -0,0 +1,13 @@
+import type { ToolpackIndex } from './packIndex.js';
+/**
+ * A write by a subflow MOUNT is its merge-back: the value was made inside. One
+ * line names the question that reaches the inner writer; '' otherwise.
+ */
+declare function mergeBackLine(index: ToolpackIndex, writerId: string, path: string): string;
+/**
+ * A key this log never wrote may still be written INSIDE a subflow mounted at
+ * this level — its own log never merged it back. One line naming the latest
+ * such mount; '' when none did (asked only on a miss).
+ */
+declare function writtenInsideLine(index: ToolpackIndex, path: string, beforeIdx?: number): string;
+export { mergeBackLine, writtenInsideLine };

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

@@ -0,0 +1,43 @@
+import { subflowWrote } from '../subflowRecords.js';
+import { mountLine } from './navigationHints.js';
+import { displayKey } from '../bounded.js';
+/**
+ * A write by a subflow MOUNT is its merge-back: the value was made inside. One
+ * line names the question that reaches the inner writer; '' otherwise.
+ */
+function mergeBackLine(index, writerId, path) {
+    if (!index.subflowDoor || index.nodes.get(writerId)?.subflowId === undefined)
+        return '';
+    // The outputMapper may rename or compute the key: claim a writer inside only
+    // when the mount's own log wrote this very path. Otherwise name the mount.
+    if (!subflowWrote(index.subflowResults?.[writerId], path)) {
+        return `\n↳ ${writerId} is a subflow mount — ${mountLine(index, writerId)}`;
+    }
+    return (`\n↳ ${writerId} is a subflow mount — this write is its merge-back. ` +
+        `inspect_subflow({ mount: '${writerId}', key: '${displayKey(path)}' }) names the writer ` +
+        `inside.`);
+}
+/**
+ * A key this log never wrote may still be written INSIDE a subflow mounted at
+ * this level — its own log never merged it back. One line naming the latest
+ * such mount; '' when none did (asked only on a miss).
+ */
+function writtenInsideLine(index, path, beforeIdx) {
+    const results = index.subflowResults;
+    if (!index.subflowDoor || results === undefined)
+        return '';
+    // Only mounts that ran BEFORE the anchor answer "who wrote it before X".
+    const mounts = [...index.orderedIds]
+        .reverse()
+        .filter((id) => index.nodes.get(id)?.subflowId !== undefined)
+        .filter((id) => beforeIdx === undefined || (index.lastIdxOf.get(id) ?? Infinity) < beforeIdx);
+    const inside = mounts.find((id) => subflowWrote(results[id], path));
+    if (inside === undefined)
+        return '';
+    // "Not merged back" is a claim about THIS log: true only if it never wrote the key.
+    const where = index.knownPaths.has(path) ? '' : ' (not merged back here)';
+    return (`\n↳ but subflow ${inside} wrote '${displayKey(path)}' in its OWN log${where}: ` +
+        `inspect_subflow({ mount: '${inside}', key: '${displayKey(path)}' }) names the writer.`);
+}
+export { mergeBackLine, writtenInsideLine };
+//# sourceMappingURL=writerHints.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"writerHints.js","sourceRoot":"","sources":["../../../../src/trace-toolpack/traceToolpack/writerHints.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C;;;GAGG;AACH,SAAS,aAAa,CAAC,KAAoB,EAAE,QAAgB,EAAE,IAAY;IACzE,IAAI,CAAC,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,SAAS,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACxF,6EAA6E;IAC7E,2EAA2E;IAC3E,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,cAAc,EAAE,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC;QAC1D,OAAO,OAAO,QAAQ,yBAAyB,SAAS,CAAC,KAAK,EAAE,QAAQ,CAAC,EAAE,CAAC;IAC9E,CAAC;IACD,OAAO,CACL,OAAO,QAAQ,sDAAsD;QACrE,6BAA6B,QAAQ,YAAY,UAAU,CAAC,IAAI,CAAC,wBAAwB;QACzF,SAAS,CACV,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,iBAAiB,CAAC,KAAoB,EAAE,IAAY,EAAE,SAAkB;IAC/E,MAAM,OAAO,GAAG,KAAK,CAAC,cAAc,CAAC;IACrC,IAAI,CAAC,KAAK,CAAC,WAAW,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IAC3D,yEAAyE;IACzE,MAAM,MAAM,GAAG,CAAC,GAAG,KAAK,CAAC,UAAU,CAAC;SACjC,OAAO,EAAE;SACT,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,SAAS,KAAK,SAAS,CAAC;SAC5D,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,SAAS,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,QAAQ,CAAC,GAAG,SAAS,CAAC,CAAC;IAChG,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;IACpE,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACpC,oFAAoF;IACpF,MAAM,KAAK,GAAG,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,yBAAyB,CAAC;IAC1E,OAAO,CACL,mBAAmB,MAAM,WAAW,UAAU,CAAC,IAAI,CAAC,mBAAmB,KAAK,IAAI;QAChF,6BAA6B,MAAM,YAAY,UAAU,CAAC,IAAI,CAAC,wBAAwB,CACxF,CAAC;AACJ,CAAC;AAED,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,CAAC"}

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

@@ -33,39 +33,20 @@
  * 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, type ToolExecutionContext } 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[];
+import 'foottrace';
+import 'foottrace';
+import '../tools/toolArgsValidation.js';
+import '../tools/tools.js';
+import '../identity/types.js';
+import '../artifacts/capability.js';
+import './bounded.js';
+import './innerDescent.js';
+import './openRecording.js';
+import './causeTools.js';
+import './storedCauseBinding.js';
+import './causeCapture.js';
+import './subflowRecords.js';
+import './types.js';
 /**
  * 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
@@ -73,10 +54,4 @@ export declare function traceToolpack(artifacts: TraceToolpackArtifacts, options
  * 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>, context?: ToolExecutionContext): Promise<string>;
+export { traceToolpack, callTraceTool } from './traceToolpack/recursiveFactory.js';