agentfootprint/dist/esm/debug.js

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

/**
 * debug — diagnosis tools for a BROKEN run.
 *
 * Where `agentfootprint/observe` watches a HEALTHY run (recorders), this
 * subpath is the autopsy kit for a wrong answer. Split out of `observe` in
 * the surface cleanup — same code, dedicated home, so the import path now
 * matches the Debug docs category. The honesty discipline is unchanged:
 * scores/weights are embedding-geometry PROXIES; ablation verdicts are the
 * ONLY causal claims; slice completeness is bounded by tracking — and says so.
 *
 * Four libraries:
 *   • influence-core   — embedding-based scoring (proxy, never causal)
 *   • trace-toolpack   — traceToolpack + traceDebugAgent + `.selfExplain()`
 *   • context-bisect   — localizeContextBug + ablation/restoration probes
 *   • tool-lint        — build-time tool-catalog confusability lint
 *
 * For backward compatibility these are ALSO re-exported (deprecated) from
 * `agentfootprint/observe` for one transition version.
 *
 * Not an import path of its own since 9.0.0. This is the implementation barrel
 * behind `agentfootprint/observe`, which re-exports every name here — same
 * symbols, one door. Import from the door.
 */
// influence-core — the ONE embedding-based scoring engine (RFC-002/003
// block D6). Not a recorder: pure, embedder-injected scoring functions
// + the shared bounded embedding cache. Honest claim: every score is an
// embedding-geometry PROXY — semantic alignment, never model internals,
// never causal attribution.
export { adaptWeights, averageRelevancy, compositeScore, contentHash, DEFAULT_CLEAR_WINNER_MARGIN, DEFAULT_CLEAR_WINNER_RATIO, DEFAULT_INFLUENCE_WEIGHTS, DEFAULT_MARGIN_THRESHOLD, DEFAULT_PERSISTENCE_THRESHOLD, DEFAULT_SHORTLIST_BAND, EmbeddingCache, embeddingCache, finalAnswerSimilarity, attributeChoice, explainChoice, lexicalOverlapStrategy, listInfluenceStrategies, marginStrategy, pairwiseSimilarity, persistence, rankingConfidence, ratioStrategy, scoreContrastiveInfluence, scoreInfluence, scoreLexicalInfluence, scoreMargin, semanticAlignmentStrategy, snippetUnits, structuralProximity, } from './influence-core/index.js';
// Introspection toolpack (RFC-003 Part C) — footprintjs trace evidence
// exposed as TOOLS a debugging LLM calls over a COMPLETED run's artifacts.
// Bounded, honest (⚠ markers), redaction-respecting, id-navigable.
export { callTraceTool, lazyTraceToolpack, NO_COMPLETED_RUN_MESSAGE, TOOLPACK_HARD_CAPS, TRACE_TOOL_NAMES, traceToolpack, traceCauseTools, readStoredCauseArtifacts, } from './trace-toolpack/index.js';
// `openRecording` — a saved run (`recordRun(...).toRecording()`, live or
// parsed back from JSON) reopened as toolpack artifacts. The one adapter
// between the recording shape the viewers read and the artifact bag the
// trace tools read; pure, and honest about the two things a serialized
// run cannot carry back (control edges, and a narrative nobody recorded).
export { openRecording } from './trace-toolpack/index.js';
// The record a TOOL keeps of its OWN run — `flowchartAsTool({ keepRecord:
// true })` files one per invocation under the outer `toolCallId`, and
// `inspect_tool_run` opens it. The Agent builder collects the stores at
// `.build()`, so these are for consumers assembling artifacts by hand.
export { DEFAULT_INNER_RUN_LIMIT, INNER_RUN_RECORDS, innerRunStore, innerRunsOf, mergeInnerRuns, } from './trace-toolpack/index.js';
// The two conversational doors over the toolpack: a DEDICATED debugger
// agent (separate session, any provider — cheap models welcome), and the
// in-conversation `.selfExplain()` builder option's types. Same evidence,
// same honesty discipline as the UI doors (BacktrackView / Lens).
export { buildSelfExplainSkill, buildSelfExplainToolProvider, SELF_EXPLAIN_MAX_EVENTS, SelfExplainBinding, traceDebugAgent, } from './trace-toolpack/index.js';
// Contextual-bug localizer (RFC-003 Part B, D7–D9) — "git bisect for
// context". Assembly: footprintjs causal DAG (control edges + honesty
// markers + EdgeWeigher) × influence-core scoring (D6) × consumer-run
// counterfactual ablation. §B2 claim tiers: scores/weights are
// embedding-geometry PROXIES; ablation verdicts are the ONLY causal
// claims; slice completeness is bounded by tracking — and says so.
export { ablationForSuspect, applyAblations, assembleTrajectory, assignCostVerdicts, bisectCulprits, bucketByAnchors, shortlistEarlyCulprits, walkToRoot, walkTrajectory, buildWriterFrameIndex, joinVariableSlice, traceVariable, DEFAULT_RECENCY_DECAY, classifySuspect, findLoopHeads, CONTEXT_BISECT_DEFAULTS, defaultOutcomeComparator, defaultSuspectClassifier, findDroppedContext, formatContextBugReport, llmCallIdsFromEvents, llmEdgeWeigher, localizeContextBug, probeFlipped, removableSources, rerunWithoutSources, runAblationProbe, runRestorationProbe, stepOutputText, suspectLabel, verdictFor, } from './context-bisect/index.js';
// Strategy arms — the SUBSTITUTION half of the counterfactual engine
// ("scorer A vs scorer B", "topK vs a re-ranker"). Deliberately a SIBLING of
// `AblationSpec` rather than a fifth arm on it: ablation removes, an arm
// replaces, and the union feeds a subset search substitutions do not compose
// under. Wired to 9.41.0's run manifest, so a run says which arm it belonged to
// instead of the experimenter asserting it. See context-bisect/arms/README.md.
export { applyArm, armConfigKey, armFacetsFromManifest, armLabel, checkArmApplication, checkArmApplied, collectArmRuns, compareStrategyArms, declaredFacetCount, manifestFromEvents, matchArm, nullBandFrom, RUN_CONFIGURED_EVENT, scoreArmRuns, validateStrategyArms, verdictForArm, } from './context-bisect/index.js';
// BacktrackTrace serializer — feeds agentThinkingUI's <BacktrackView>
// (the "why?" board) straight off a localizer report. Pure mapping, no
// UI dependency; the interfaces mirror agentthinkingui's contract.
export { sliceToBacktrackTrace, toBacktrackTrace, variableToBacktrackTrace, } from './context-bisect/index.js';
// Tool-catalog confusability lint (RFC-002 tier 1, C1–C3) — build-time,
// CI-gateable, framework-agnostic: plain { name, description?, inputSchema? }
// tools in (OpenAI/Anthropic/MCP lists coerce via coerceCatalog; the
// library's Tool[] via catalogFromTools), a report with a gateable `ok`
// out. Pluggable structural rule pack; thresholds + embedder consumer-
// injected with our defaults. Bin: `agentfootprint-lint-tools`.
// Front door: https://agentfootprint.dev/docs/debug/tool-catalog-lint/
export { analyzeToolCatalog, catalogFromTools, coerceCatalog, confusabilityText, DEFAULT_CONFUSABILITY_THRESHOLD, DEFAULT_OMISSION_CUES, DEFAULT_WATCH_BAND, DEFAULT_WHEN_CUES, defaultStructuralRules, descriptionRule, differentiationHint, enumInProseRule, formatToolCatalogReport, MOCK_EMBEDDER_CALIBRATION, optionalParamRule, runToolLintCli, saysWhatNotWhenRule, } from './tool-lint/index.js';
// check:semantics (9.53.0) — the tool-lint pattern applied to RESULT shapes:
// judge sample results (your mock tools' returns, dumped to JSON) against
// the semantic-envelope vocabulary and the per-class rules declared on
// defineTool({ resultClass }). A triage tool whose sample declares no
// coverage fails the build NAMING the tool and the field. The authoring
// half (describedResult(), readSemantics, the types) ships on the main barrel.
// The overclaim rules — a refusal or an absence never asserts more than was
// read — warn by default; `strict` or `rules: ['overclaim']` make them errors.
export { checkSemantics, coerceSemanticsCatalog, formatSemanticsReport, runCheckSemanticsCli, } from './semantics/index.js';
// recorded-chat — the session-scoped turn recorder. Wraps a consumer agent
// factory into a recorded conversation: send() freezes each turn's evidence,
// reason(k)/rerunTurn(k)/fork(k) are the per-turn transparency loop. Absorbs
// the three glue traps (per-turn artifact freezing, byte-exact history
// threading, same-factory runner derivation) while COMPOSING with the loop
// above (localizeContextBug + rerunWithoutSources returned UNMODIFIED), never
// duplicating it. Branch, never rewrite.
export { recordedChat, } from './recorded-chat/index.js';
//# sourceMappingURL=debug.js.map