agentfootprint/dist/observe.js

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

"use strict";
/**
 * agentfootprint/observe — observability recorders.
 *
 * Pattern: Observer (GoF) — pluggable, fire-and-forget event listeners
 *          for the agent's typed event stream.
 * Role:    Outer ring (Hexagonal). Attach via `runner.attachScopeRecorder()`;
 *          the runner emits events, recorders accumulate state.
 *
 * Three tiers (progressive disclosure):
 *
 *   Tier 1 — context + stream                                (the core)
 *     • ContextRecorder      — every slot composition
 *     • StreamRecorder       — token-level LLM streaming
 *
 *   Tier 2 — composition + agent                       (structural nav)
 *     • CompositionRecorder  — Sequence/Parallel/Conditional/Loop entries
 *     • AgentRecorder        — agent-loop iterations, tool calls
 *     • BoundaryRecorder     — domain-tagged subflow entry/exit
 *     • FlowchartRecorder    — StepGraph projection (Lens-friendly)
 *
 *   Tier 3 — domain dashboards                              (attach on demand)
 *     • CostRecorder         — token/USD spend
 *     • EvalRecorder         — eval scores from `runner.emit('eval.*', ...)`
 *     • MemoryRecorder       — memory injections + writes
 *     • EmbeddingRecorder    — embedding cost, index-time vs query-time
 *     • PermissionRecorder   — permission decisions + denials
 *     • SkillRecorder        — skill activations
 *     • LoggingRecorder      — structured log lines per event
 *     • StatusRecorder     — chat-bubble first-person status
 *
 * Domain-flavored consumers (Lens, Grafana, Datadog) compose Tier 1+2
 * directly; Tier 3 dashboards are opt-in.
 */
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
    if (k2 === undefined) k2 = k;
    var desc = Object.getOwnPropertyDescriptor(m, k);
    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
      desc = { enumerable: true, get: function() { return m[k]; } };
    }
    Object.defineProperty(o, k2, desc);
}) : (function(o, m, k, k2) {
    if (k2 === undefined) k2 = k;
    o[k2] = m[k];
}));
var __exportStar = (this && this.__exportStar) || function(m, exports) {
    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
};
Object.defineProperty(exports, "__esModule", { value: true });
exports.memoryRecorder = exports.evalRecorder = exports.contextEvaluatedRecorder = exports.toolsRecorder = exports.costRecorder = exports.LiveAgentTurnTracker = exports.LiveToolTracker = exports.LiveLLMTracker = exports.LiveStateRecorder = exports.liveStateRecorder = exports.attachLocalObservability = exports.traceToStepGraph = exports.redactContent = exports.serializeTrace = exports.summarizeVector = exports.summarizeEmbeddings = exports.exportBugReport = exports.describeBugReport = exports.UnsafeRecordingIdError = exports.recordingFileName = exports.fileRecordingSink = exports.UnsupportedPrivacyModeError = exports.IndeterminateRunFactError = exports.RECORDING_ENVELOPE_FORMAT = exports.FULL_PRIVACY_POLICY_ID = exports.persistRecording = exports.buildRecordingEnvelope = exports.assessAnswer = exports.answerAccountPointerKey = exports.accountForAnswer = exports.trustBoundaryRecorder = exports.PackedRecordingTooLargeError = exports.PackedRecordingError = exports.DEFAULT_UNPACK_MAX_BYTES = exports.PACKED_RECORDING_FORMAT = exports.isPackedRecording = exports.unpackRecording = exports.packRecording = exports.recordRun = exports.buildStepGraphFromEvents = exports.buildStepGraph = exports.attachFlowchart = exports.runStepRecorder = exports.RunStepRecorder = exports.BoundaryRecorder = exports.boundaryRecorder = exports.agentRecorder = exports.compositionRecorder = exports.streamRecorder = exports.ContextRecorder = void 0;
exports.ledgerGated = exports.ledgerEntryScorer = exports.ledgerToolGate = exports.contextLedger = exports.formatRouteHop = exports.routeRecorder = exports.toolChoiceRecorder = exports.buildChoiceContext = exports.typedEmit = exports.agentThinkingTrace = exports.toolLineageRecorder = exports.attachStatus = exports.LoggingDomains = exports.attachLogging = exports.resilienceRecorder = exports.skillRecorder = exports.permissionRecorder = exports.embeddingRecorder = void 0;
// Tier 1 — context + stream
var ContextRecorder_js_1 = require("./recorders/core/ContextRecorder.js");
Object.defineProperty(exports, "ContextRecorder", { enumerable: true, get: function () { return ContextRecorder_js_1.ContextRecorder; } });
var StreamRecorder_js_1 = require("./recorders/core/StreamRecorder.js");
Object.defineProperty(exports, "streamRecorder", { enumerable: true, get: function () { return StreamRecorder_js_1.streamRecorder; } });
// Tier 2 — composition + agent
var CompositionRecorder_js_1 = require("./recorders/core/CompositionRecorder.js");
Object.defineProperty(exports, "compositionRecorder", { enumerable: true, get: function () { return CompositionRecorder_js_1.compositionRecorder; } });
var AgentRecorder_js_1 = require("./recorders/core/AgentRecorder.js");
Object.defineProperty(exports, "agentRecorder", { enumerable: true, get: function () { return AgentRecorder_js_1.agentRecorder; } });
var BoundaryRecorder_js_1 = require("./recorders/observability/BoundaryRecorder.js");
Object.defineProperty(exports, "boundaryRecorder", { enumerable: true, get: function () { return BoundaryRecorder_js_1.boundaryRecorder; } });
Object.defineProperty(exports, "BoundaryRecorder", { enumerable: true, get: function () { return BoundaryRecorder_js_1.BoundaryRecorder; } });
var RunStepRecorder_js_1 = require("./recorders/observability/RunStepRecorder.js");
Object.defineProperty(exports, "RunStepRecorder", { enumerable: true, get: function () { return RunStepRecorder_js_1.RunStepRecorder; } });
Object.defineProperty(exports, "runStepRecorder", { enumerable: true, get: function () { return RunStepRecorder_js_1.runStepRecorder; } });
var FlowchartRecorder_js_1 = require("./recorders/observability/FlowchartRecorder.js");
Object.defineProperty(exports, "attachFlowchart", { enumerable: true, get: function () { return FlowchartRecorder_js_1.attachFlowchart; } });
Object.defineProperty(exports, "buildStepGraph", { enumerable: true, get: function () { return FlowchartRecorder_js_1.buildStepGraph; } });
Object.defineProperty(exports, "buildStepGraphFromEvents", { enumerable: true, get: function () { return FlowchartRecorder_js_1.buildStepGraphFromEvents; } });
// recordRun — save a run so a viewer can show it later. THE producer for
// `{ snapshot, events, structure }`: the timeline, the state, and the chart,
// which is the shape the UIs consume (lens's `observeRecording`) and the one
// every integration used to assemble by hand, each missing a different piece.
var recordRun_js_1 = require("./recorders/observability/recordRun.js");
Object.defineProperty(exports, "recordRun", { enumerable: true, get: function () { return recordRun_js_1.recordRun; } });
// A recording with every repeated value written ONCE — what to store or send
// when the run is long: plain JSON repeats the history once per place that
// saw it (K²·R), packed it grows with K·R. `unpackRecording` reads both
// shapes, so a reader that calls it reads every recording ever minted — and
// expands a packed one only when the plain recording it stands for is within
// `maxBytes` (default `DEFAULT_UNPACK_MAX_BYTES`).
var recordingPack_js_1 = require("./recorders/observability/recordingPack.js");
Object.defineProperty(exports, "packRecording", { enumerable: true, get: function () { return recordingPack_js_1.packRecording; } });
Object.defineProperty(exports, "unpackRecording", { enumerable: true, get: function () { return recordingPack_js_1.unpackRecording; } });
Object.defineProperty(exports, "isPackedRecording", { enumerable: true, get: function () { return recordingPack_js_1.isPackedRecording; } });
Object.defineProperty(exports, "PACKED_RECORDING_FORMAT", { enumerable: true, get: function () { return recordingPack_js_1.PACKED_RECORDING_FORMAT; } });
Object.defineProperty(exports, "DEFAULT_UNPACK_MAX_BYTES", { enumerable: true, get: function () { return recordingPack_js_1.DEFAULT_UNPACK_MAX_BYTES; } });
Object.defineProperty(exports, "PackedRecordingError", { enumerable: true, get: function () { return recordingPack_js_1.PackedRecordingError; } });
Object.defineProperty(exports, "PackedRecordingTooLargeError", { enumerable: true, get: function () { return recordingPack_js_1.PackedRecordingTooLargeError; } });
// Runtime selected-policy evidence: typed subscription only, with one bounded
// capture owner. recordRun can own its lifecycle and snapshot bundle.
var index_js_1 = require("./trust-boundaries/index.js");
Object.defineProperty(exports, "trustBoundaryRecorder", { enumerable: true, get: function () { return index_js_1.trustBoundaryRecorder; } });
// accountForAnswer — "Explain this answer": one answer's recording (plus what
// the app declared) in, a typed account out — facts, each with who vouches for
// it and where it lives in the record, and fixed sentences from a closed,
// versioned template table. Pure and read-time: no clock, network or model.
// See src/answer-account/README.md.
// `answerAccountPointerKey(pointer)` is the key of the `shown` map the hosting
// op `{ op: 'answer-account', ref }` returns beside the account.
var index_js_2 = require("./answer-account/index.js");
Object.defineProperty(exports, "accountForAnswer", { enumerable: true, get: function () { return index_js_2.accountForAnswer; } });
Object.defineProperty(exports, "answerAccountPointerKey", { enumerable: true, get: function () { return index_js_2.answerAccountPointerKey; } });
// assessAnswer — the answer's STANDING, folded from the run's committed record:
// known · consistent with the record · not sure (with the reasons) · ask · not
// assessed. Never read from how sure the model sounds, never "known" from
// silence, never from events. The account's "How sure" row renders the same
// fold. ONE public type; its family (a reason, a witness, a check that ran) by
// indexed access. See src/core/agent/assessment/README.md.
var assess_js_1 = require("./core/agent/assessment/assess.js");
Object.defineProperty(exports, "assessAnswer", { enumerable: true, get: function () { return assess_js_1.assessAnswer; } });
// The recording ENVELOPE — the versioned contract that makes a recording
// archivable. `recordRun` freezes a run; this states which run it is, how much
// of it this is, who produced it and under what privacy policy, so a saved run
// can be filed, attached to a bug report, or read by an analysis tool without
// every consumer inventing its own wrapper. Every field is derived from the
// run's own events or stated by the caller — never guessed.
var recordingEnvelope_js_1 = require("./recorders/observability/recordingEnvelope.js");
Object.defineProperty(exports, "buildRecordingEnvelope", { enumerable: true, get: function () { return recordingEnvelope_js_1.buildRecordingEnvelope; } });
Object.defineProperty(exports, "persistRecording", { enumerable: true, get: function () { return recordingEnvelope_js_1.persistRecording; } });
Object.defineProperty(exports, "FULL_PRIVACY_POLICY_ID", { enumerable: true, get: function () { return recordingEnvelope_js_1.FULL_PRIVACY_POLICY_ID; } });
Object.defineProperty(exports, "RECORDING_ENVELOPE_FORMAT", { enumerable: true, get: function () { return recordingEnvelope_js_1.RECORDING_ENVELOPE_FORMAT; } });
Object.defineProperty(exports, "IndeterminateRunFactError", { enumerable: true, get: function () { return recordingEnvelope_js_1.IndeterminateRunFactError; } });
Object.defineProperty(exports, "UnsupportedPrivacyModeError", { enumerable: true, get: function () { return recordingEnvelope_js_1.UnsupportedPrivacyModeError; } });
// The reference sink: one archived run per JSON file, written atomically
// (tmp + rename) so a crash never leaves a half-parsed archive. The file name
// derives from the run id, which makes it a key — hence the asserted safe
// charset and `UnsafeRecordingIdError` rather than a hopeful `${runId}.json`.
var fileRecordingSink_js_1 = require("./recorders/observability/fileRecordingSink.js");
Object.defineProperty(exports, "fileRecordingSink", { enumerable: true, get: function () { return fileRecordingSink_js_1.fileRecordingSink; } });
Object.defineProperty(exports, "recordingFileName", { enumerable: true, get: function () { return fileRecordingSink_js_1.recordingFileName; } });
Object.defineProperty(exports, "UnsafeRecordingIdError", { enumerable: true, get: function () { return fileRecordingSink_js_1.UnsafeRecordingIdError; } });
// exportBugReport — a bug report IS the evidence. `describeBugReport` measures
// the run first (selectable units, sizes, the redacted keys by NAME) so a human
// can consent to exactly what leaves; `exportBugReport` bundles the units they
// kept as named files plus a real (stored) zip. `githubBugReporter` — in this
// same door, from the providers barrel — files that bundle.
//
// The evidence in that zip is a RecordingEnvelope (bundle layout 2), built by
// the same `buildRecordingEnvelope` above rather than a second wrapper — so the
// producer facts are stamped once. `BugReportRunFacts` is the pair the envelope
// cannot derive; without it the bundle still ships, as the bare recording, with
// the manifest naming the fact that was missing.
var index_js_3 = require("./bug-report/index.js");
Object.defineProperty(exports, "describeBugReport", { enumerable: true, get: function () { return index_js_3.describeBugReport; } });
Object.defineProperty(exports, "exportBugReport", { enumerable: true, get: function () { return index_js_3.exportBugReport; } });
// What a recording keeps of a vector: `{ dims, norm }`, not the bytes (8.20.0).
// Applied by BoundaryRecorder and recordRun unless `recordEmbeddings: true`;
// exported so consumers that render or post-process recordings can apply or
// recognise the same projection.
var embeddingSummary_js_1 = require("./recorders/observability/embeddingSummary.js");
Object.defineProperty(exports, "summarizeEmbeddings", { enumerable: true, get: function () { return embeddingSummary_js_1.summarizeEmbeddings; } });
Object.defineProperty(exports, "summarizeVector", { enumerable: true, get: function () { return embeddingSummary_js_1.summarizeVector; } });
// Offline replay: freeze a live run model into a UI-free, JSON-lossless Trace
// (redaction applied at the serialize boundary). agentfootprint-lens's <Replay>
// rehydrates it. See docs/design/local-observability-and-pii.md.
var trace_js_1 = require("./recorders/observability/trace.js");
Object.defineProperty(exports, "serializeTrace", { enumerable: true, get: function () { return trace_js_1.serializeTrace; } });
Object.defineProperty(exports, "redactContent", { enumerable: true, get: function () { return trace_js_1.redactContent; } });
Object.defineProperty(exports, "traceToStepGraph", { enumerable: true, get: function () { return trace_js_1.traceToStepGraph; } });
// localObservability — Tier-3 retain: live onLive(graph) + offline
// getTrace()/onRecorded. NOT a Lens recorder — to render a run in Lens, use
// `recordRun` above and lens's `observeRecording`.
var localObservability_js_1 = require("./recorders/observability/localObservability.js");
Object.defineProperty(exports, "attachLocalObservability", { enumerable: true, get: function () { return localObservability_js_1.attachLocalObservability; } });
var LiveStateRecorder_js_1 = require("./recorders/observability/LiveStateRecorder.js");
Object.defineProperty(exports, "liveStateRecorder", { enumerable: true, get: function () { return LiveStateRecorder_js_1.liveStateRecorder; } });
Object.defineProperty(exports, "LiveStateRecorder", { enumerable: true, get: function () { return LiveStateRecorder_js_1.LiveStateRecorder; } });
Object.defineProperty(exports, "LiveLLMTracker", { enumerable: true, get: function () { return LiveStateRecorder_js_1.LiveLLMTracker; } });
Object.defineProperty(exports, "LiveToolTracker", { enumerable: true, get: function () { return LiveStateRecorder_js_1.LiveToolTracker; } });
Object.defineProperty(exports, "LiveAgentTurnTracker", { enumerable: true, get: function () { return LiveStateRecorder_js_1.LiveAgentTurnTracker; } });
// Tier 3 — domain dashboards
var CostRecorder_js_1 = require("./recorders/core/CostRecorder.js");
Object.defineProperty(exports, "costRecorder", { enumerable: true, get: function () { return CostRecorder_js_1.costRecorder; } });
var ToolsRecorder_js_1 = require("./recorders/core/ToolsRecorder.js");
Object.defineProperty(exports, "toolsRecorder", { enumerable: true, get: function () { return ToolsRecorder_js_1.toolsRecorder; } });
var ContextEvaluatedRecorder_js_1 = require("./recorders/core/ContextEvaluatedRecorder.js");
Object.defineProperty(exports, "contextEvaluatedRecorder", { enumerable: true, get: function () { return ContextEvaluatedRecorder_js_1.contextEvaluatedRecorder; } });
var EvalRecorder_js_1 = require("./recorders/core/EvalRecorder.js");
Object.defineProperty(exports, "evalRecorder", { enumerable: true, get: function () { return EvalRecorder_js_1.evalRecorder; } });
var MemoryRecorder_js_1 = require("./recorders/core/MemoryRecorder.js");
Object.defineProperty(exports, "memoryRecorder", { enumerable: true, get: function () { return MemoryRecorder_js_1.memoryRecorder; } });
var EmbeddingRecorder_js_1 = require("./recorders/core/EmbeddingRecorder.js");
Object.defineProperty(exports, "embeddingRecorder", { enumerable: true, get: function () { return EmbeddingRecorder_js_1.embeddingRecorder; } });
var PermissionRecorder_js_1 = require("./recorders/core/PermissionRecorder.js");
Object.defineProperty(exports, "permissionRecorder", { enumerable: true, get: function () { return PermissionRecorder_js_1.permissionRecorder; } });
var SkillRecorder_js_1 = require("./recorders/core/SkillRecorder.js");
Object.defineProperty(exports, "skillRecorder", { enumerable: true, get: function () { return SkillRecorder_js_1.skillRecorder; } });
// Provider-decorator telemetry (fallback.triggered / error.retried /
// error.recovered / error.circuit_changed). Attached automatically by
// Agent / LLMCall / Parallel;
// exported so consumers running the public message-api charts on a bare
// FlowChartExecutor can wire the bridge themselves.
var ResilienceRecorder_js_1 = require("./recorders/core/ResilienceRecorder.js");
Object.defineProperty(exports, "resilienceRecorder", { enumerable: true, get: function () { return ResilienceRecorder_js_1.resilienceRecorder; } });
var LoggingRecorder_js_1 = require("./recorders/observability/LoggingRecorder.js");
Object.defineProperty(exports, "attachLogging", { enumerable: true, get: function () { return LoggingRecorder_js_1.attachLogging; } });
Object.defineProperty(exports, "LoggingDomains", { enumerable: true, get: function () { return LoggingRecorder_js_1.LoggingDomains; } });
var StatusRecorder_js_1 = require("./recorders/observability/StatusRecorder.js");
Object.defineProperty(exports, "attachStatus", { enumerable: true, get: function () { return StatusRecorder_js_1.attachStatus; } });
// Tool→tool DATA-FLOW graph, derived by value provenance from the tool emit
// stream (see finding 2: causalChain can't see LLM-mediated tool dependencies).
var ToolLineageRecorder_js_1 = require("./recorders/observability/ToolLineageRecorder.js");
Object.defineProperty(exports, "toolLineageRecorder", { enumerable: true, get: function () { return ToolLineageRecorder_js_1.toolLineageRecorder; } });
// AgentThinkingUI Trace (run → the "watch it think" beat list, collected during
// traversal). Lets any agentfootprint run drive AgentThinkingUI / domain views.
var AgentThinkingTraceRecorder_js_1 = require("./recorders/observability/AgentThinkingTraceRecorder.js");
Object.defineProperty(exports, "agentThinkingTrace", { enumerable: true, get: function () { return AgentThinkingTraceRecorder_js_1.agentThinkingTrace; } });
// Emit primitive — used by every Tier-3 source-domain.
var typedEmit_js_1 = require("./recorders/core/typedEmit.js");
Object.defineProperty(exports, "typedEmit", { enumerable: true, get: function () { return typedEmit_js_1.typedEmit; } });
// ── Diagnosis tools ────────────────────────────────────────────
// influence-core, trace-toolpack, context-bisect and tool-lint live in
// `src/debug.ts`. 8.0.0 folded their import path INTO this one, and 9.0.0
// removed the separate `agentfootprint/debug` subpath, so this re-export is
// how they reach the door. Watching a healthy run and performing the autopsy
// on a broken one come through the same door on purpose.
__exportStar(require("./debug.js"), exports);
// Tool-choice margin recorder (RFC-002 tier 2, C4–C6) — per LLM call,
// ranks the OFFERED catalog against the choice context (user message +
// latest assistant reasoning) via influence-core scoreMargin; embeds
// LAZILY on first read; flags narrow margins + proxy disagreements.
var ToolChoiceRecorder_js_1 = require("./recorders/observability/ToolChoiceRecorder.js");
Object.defineProperty(exports, "buildChoiceContext", { enumerable: true, get: function () { return ToolChoiceRecorder_js_1.buildChoiceContext; } });
Object.defineProperty(exports, "toolChoiceRecorder", { enumerable: true, get: function () { return ToolChoiceRecorder_js_1.toolChoiceRecorder; } });
var RouteRecorder_js_1 = require("./recorders/observability/RouteRecorder.js");
Object.defineProperty(exports, "routeRecorder", { enumerable: true, get: function () { return RouteRecorder_js_1.routeRecorder; } });
Object.defineProperty(exports, "formatRouteHop", { enumerable: true, get: function () { return RouteRecorder_js_1.formatRouteHop; } });
// context-ledger — which context pieces EARNED their tokens? Post-run
// bookkeeping (offers/uses/outcomes from the commit log) feeding the gating
// seams. See src/context-ledger/README.md.
var index_js_4 = require("./context-ledger/index.js");
Object.defineProperty(exports, "contextLedger", { enumerable: true, get: function () { return index_js_4.contextLedger; } });
Object.defineProperty(exports, "ledgerToolGate", { enumerable: true, get: function () { return index_js_4.ledgerToolGate; } });
Object.defineProperty(exports, "ledgerEntryScorer", { enumerable: true, get: function () { return index_js_4.ledgerEntryScorer; } });
Object.defineProperty(exports, "ledgerGated", { enumerable: true, get: function () { return index_js_4.ledgerGated; } });
//# sourceMappingURL=observe.js.map