agentfootprint/dist/trace-toolpack/traceDebugAgent.js

The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.

"use strict";
/**
 * traceDebugAgent — the DEDICATED conversational door over a completed
 * run's trace. One call returns a ready Agent whose entire catalog is
 * the trace toolpack and whose system prompt is the proven debugging
 * methodology (overview → drill by id → cite evidence → respect ⚠).
 *
 * The counterpart doors over the same evidence:
 *   - the UI (BacktrackView / Lens) for humans who LOOK,
 *   - `.selfExplain()` for why-questions INSIDE the main conversation
 *     (which, in delegate mode, runs one of these under the hood).
 *
 * Why dedicated (B13 posture): trace views can replay adversarial text
 * from the original run — a SEPARATE session over a COMPLETED run keeps
 * that out of the production conversation. It is also the cheap-model
 * story made real: debug a Sonnet/Opus run with a Haiku-priced session
 * that reads only what it opens, by id (~9% of the trace in the
 * example-01 fixture; the gap widens with run size).
 */
Object.defineProperty(exports, "__esModule", { value: true });
exports.traceDebugAgent = void 0;
// The agent through the self-explain host, as the doors hand it out: the
// `/observe` door reaches the builder only through this file, so taking the
// class from the host registers the `.selfExplain()` port there too.
const selfExplainHost_js_1 = require("./selfExplainHost.js");
const debugPrompt_js_1 = require("./debugPrompt.js");
const traceToolpack_js_1 = require("./traceToolpack.js");
/**
 * Build the dedicated trace debugger. The returned Agent is a normal
 * Agent — `await debuggerAi.run({ message: 'Why was the refund approved?' })`
 * answers from the recorded evidence, citing runtimeStageIds.
 */
function traceDebugAgent(options) {
    if (options.mode !== undefined && options.mode !== 'recorded' && options.mode !== 'hypothesis') {
        throw new TypeError('traceDebugAgent: invalid explanation mode');
    }
    const system = debugPrompt_js_1.TRACE_DEBUG_METHODOLOGY +
        '\n\n' +
        debugPrompt_js_1.CAUSE_FINDING_METHODOLOGY +
        (options.mode === 'hypothesis' ? '\n\n' + debugPrompt_js_1.TRACE_HYPOTHESIS_MODE : '') +
        (options.instruction ? `\n\n${options.instruction}` : '');
    return selfExplainHost_js_1.Agent.create({
        provider: options.provider,
        model: options.model,
        name: options.name ?? 'TraceDebugAgent',
        id: 'trace-debug-agent',
        maxIterations: options.maxIterations ?? 8,
    })
        .system(system)
        .tools((0, traceToolpack_js_1.traceToolpack)(options.artifacts, options.toolpack))
        .build();
}
exports.traceDebugAgent = traceDebugAgent;
//# sourceMappingURL=traceDebugAgent.js.map