agentfootprint
Version:
The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.
83 lines (82 loc) • 5.03 kB
TypeScript
/**
* 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, 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[];
/**
* 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>, context?: ToolExecutionContext): Promise<string>;