/**
 * 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>;
//# sourceMappingURL=traceToolpack.d.ts.map