@ai-agent-forge/plugin-observability 0.85.0

package/dist/observability.js

@@ -0,0 +1,1442 @@
+/**
+ * First-party observability plugin: a per-session bounded event journal over
+ * the draft lifecycle catalog plus a deterministic problem-report exporter.
+ *
+ * Extracted from the host's `src/plugins/observability.ts` (D-075 S4, second
+ * B-class batch). The plugin is an ordinary capability-plugin citizen: it
+ * subscribes through `api.lifecycle.registerObserve`, persists reports through
+ * `api.output` when the host declares the `output-artifacts` feature, and
+ * never touches host internals. Every payload that leaves the journal through
+ * a problem report is pushed through the host output serializer redaction
+ * channel, so internal field keys are replaced at any depth before anything
+ * is exported.
+ *
+ * Event definitions are host-owned: the host's bootstrap lifecycle plugin
+ * defines every catalog event before capability plugins load, and this plugin
+ * registers observers by `{ id, version }` reference only (see
+ * `./event-ids.ts`). A host that has not defined a subscribed event gets a
+ * structured registration failure instead of a silent empty subscription.
+ */
+import { appendFileSync } from "node:fs";
+import { AGENT_SETTLED_EVENT_ID, AGENT_TASK_SETTLED_EVENT_ID, CATALOG_EVENT_VERSION, INPUT_RECEIVED_EVENT_ID, MODEL_SELECT_EVENT_ID, MODEL_STREAM_EVENT_ID, OPERATION_END_EVENT_ID, PLUGIN_DISPOSE_EVENT_ID, PLUGIN_READY_EVENT_ID, SESSION_AUTO_RETRY_EVENT_ID, SESSION_COMPACTION_COMMIT_EVENT_ID, SESSION_COMPACTION_DECISION_EVENT_ID, SESSION_COMPACTION_FAILED_EVENT_ID, SESSION_CONTEXT_REPLACED_EVENT_ID, SESSION_END_EVENT_ID, SESSION_RELOAD_EVENT_ID, SESSION_START_EVENT_ID, TOOL_CALL_EVENT_ID, TOOL_COMMIT_EVENT_ID, TOOL_EXECUTE_EVENT_ID, TOOL_EXECUTION_START_EVENT_ID, TOOL_GATE_BLOCKED_EVENT_ID, TOOL_RESULT_EVENT_ID, TOOL_RESULT_RAW_EVENT_ID, TURN_END_EVENT_ID, TURN_START_EVENT_ID, UI_PROMPT_END_EVENT_ID, UI_PROMPT_START_EVENT_ID, } from "./event-ids.js";
+import { createOtlpTraceExportSink } from "./otlp-exporter.js";
+import { createHostOutputSerializer, } from "./output-serializer.js";
+export const OBSERVABILITY_PLUGIN_ID = "agent-forge.observability";
+export const DEFAULT_JOURNAL_MAX_ENTRIES = 2000;
+export const DEFAULT_PROBLEM_REPORT_TAIL_SIZE = 50;
+export const PROBLEM_REPORT_OPERATION_ID = "agent-forge.observability/problem-report";
+const REDACTION_POLICY_VERSION = "agent-forge.observability@1";
+/** The builtin memory capability's recall tool; its executions feed the hit rate. */
+export const MEMORY_RECALL_TOOL_NAME = "memory_recall";
+/** Default `maxStringChars` for trace payload snapshots (design §4.3). */
+export const DEFAULT_TRACE_MAX_STRING_CHARS = 16_000;
+/** Default snapshot budget: 384 KiB, strictly below the 512 KiB record budget (design §4.3). */
+export const DEFAULT_TRACE_MAX_SNAPSHOT_BYTES = 393_216;
+/** Hard per-record budget; the write-path guard of last resort (design §4.2/§4.3). */
+export const TRACE_RECORD_MAX_BYTES = 524_288;
+/** Args/result summaries inside `tool.span` data are bounded to ~2 KiB each. */
+export const TRACE_TOOL_SUMMARY_MAX_CHARS = 2_048;
+/**
+ * Upper bound per in-flight span-state table (`pendingTurns`, `toolSpans`,
+ * `streams`, result-diff pairs). Bounded by design: entries are keyed by
+ * in-flight ids and deleted on pairing, but a crash or a lost terminal event
+ * would otherwise leak them — past the bound the oldest unpaired entry is
+ * evicted FIFO (first key in Map insertion order).
+ */
+export const TRACE_SPAN_STATE_MAX_ENTRIES = 256;
+/** Serialized leaves below this size never pay for their own redaction placeholder. */
+const TRACE_SNAPSHOT_MIN_REDACTABLE_BYTES = 64;
+const TRACE_SCHEMA_V1 = "agent-forge/trace.v1";
+const TRACE_SINK_FAILURE_STAGE = "observability.trace.sink-failure";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function assertPositiveSafeInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value < 1)
+        throw new Error(`${label} must be a positive safe integer`);
+}
+function assertNonEmptyString(value, label) {
+    if (typeof value !== "string" || value.trim() === "")
+        throw new Error(`${label} must be a non-empty string`);
+}
+function firstTextContent(data) {
+    const content = data.content;
+    if (!Array.isArray(content))
+        return undefined;
+    for (const item of content) {
+        if (isRecord(item) && item.type === "text" && typeof item.text === "string")
+            return item.text;
+    }
+    return undefined;
+}
+function extractSessionId(data) {
+    if (!isRecord(data) || typeof data.sessionId !== "string" || data.sessionId === "")
+        return null;
+    return data.sessionId;
+}
+function deriveLevel(stage, data) {
+    if (!isRecord(data))
+        return "info";
+    if (stage === MODEL_STREAM_EVENT_ID)
+        return isRecord(data.error) ? "error" : "info";
+    if (stage === OPERATION_END_EVENT_ID) {
+        if (data.status === "failed")
+            return "error";
+        return data.status === "cancelled" ? "warn" : "info";
+    }
+    if (stage === PLUGIN_DISPOSE_EVENT_ID)
+        return data.status === "failed" ? "error" : "info";
+    if (data.isError === true)
+        return "error";
+    return "info";
+}
+function buildSummary(stage, data) {
+    if (!isRecord(data))
+        return stage;
+    const isError = data.isError === true;
+    switch (stage) {
+        case MODEL_STREAM_EVENT_ID:
+            return `${String(data.phase)} ${String(data.event)}`;
+        case TOOL_CALL_EVENT_ID:
+            return `call ${String(data.toolName)}`;
+        case TOOL_EXECUTE_EVENT_ID:
+            return `execute ${String(data.toolName)}${isError ? " (error)" : ""}`;
+        case TOOL_RESULT_RAW_EVENT_ID:
+        case TOOL_RESULT_EVENT_ID:
+            return `result ${String(data.toolName)}${isError ? " (error)" : ""}`;
+        case TOOL_COMMIT_EVENT_ID:
+            return `commit ${String(data.toolName)}${isError ? " (error)" : ""}`;
+        case OPERATION_END_EVENT_ID:
+            return `${String(data.operationKind)} ${String(data.status)}`;
+        case PLUGIN_READY_EVENT_ID:
+            return `ready ${String(data.pluginId)}`;
+        case PLUGIN_DISPOSE_EVENT_ID:
+            return `disposed ${String(data.pluginId)} (${String(data.status)})`;
+        case SESSION_RELOAD_EVENT_ID:
+            return `generation ${String(data.generation)}`;
+        case SESSION_CONTEXT_REPLACED_EVENT_ID:
+            return `context replaced (${String(data.reason)})`;
+        default:
+            return stage;
+    }
+}
+function extractErrorInfo(entry) {
+    const data = entry.data;
+    // v8 ignore next -- error 级条目的 data 恒为对象（deriveLevel 已保证）
+    if (!isRecord(data))
+        return null;
+    const phase = typeof data.phase === "string" && data.phase !== "" ? data.phase : undefined;
+    if (isRecord(data.error) && typeof data.error.code === "string" && typeof data.error.message === "string") {
+        return { code: data.error.code, message: data.error.message, ...(phase === undefined ? {} : { phase }) };
+    }
+    if (data.status === "failed") {
+        const message = typeof data.errorMessage === "string" ? data.errorMessage : entry.summary;
+        return { code: "operation.failed", message, ...(phase === undefined ? {} : { phase }) };
+    }
+    if (data.isError === true) {
+        const message = firstTextContent(data) ?? entry.summary;
+        return { code: "tool.failed", message, ...(phase === undefined ? {} : { phase }) };
+    }
+    return null;
+}
+/** Deterministic JSON: sorted object keys, no whitespace, stable scalars. */
+function canonicalJson(value) {
+    if (value === null)
+        return "null";
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "number")
+        return Number.isFinite(value) ? String(value) : "null";
+    if (typeof value === "boolean")
+        return String(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    // v8 ignore next -- 报告体仅由 JSON-safe 字段构成，不可序列化分支不可达
+    if (isRecord(value)) {
+        const keys = Object.keys(value)
+            .filter((key) => value[key] !== undefined)
+            .sort();
+        return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`;
+    }
+    throw new Error(`Value is not JSON-serializable: ${typeof value}`);
+}
+/** FNV-1a 32-bit over the UTF-8 bytes of the input, rendered as 8 hex chars. */
+export function fnv1a32Hex(input) {
+    let hash = 0x811c9dc5;
+    for (const byte of new TextEncoder().encode(input)) {
+        hash ^= byte;
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, "0");
+}
+/**
+ * Bounded ring journal with drop-oldest eviction and a replay guard: a
+ * lifecycle event id already seen is ignored, so redelivery stays idempotent.
+ * The replay window matches the ring bound — evicted events may be re-recorded.
+ */
+export function createObservabilityJournal(options = {}) {
+    const maxEntries = options.maxEntries ?? DEFAULT_JOURNAL_MAX_ENTRIES;
+    assertPositiveSafeInteger(maxEntries, "Journal maxEntries");
+    const now = options.now ?? (() => Date.now());
+    const entries = [];
+    const seenEventIds = new Set();
+    const seenOrder = [];
+    let sequence = 0;
+    let dropped = 0;
+    const filterEntries = (filter) => {
+        if (filter === undefined)
+            return entries;
+        if (filter.limit !== undefined)
+            assertPositiveSafeInteger(filter.limit, "Query limit");
+        const filtered = entries.filter((entry) => (filter.sessionId === undefined || entry.sessionId === filter.sessionId) &&
+            (filter.stage === undefined || entry.stage === filter.stage) &&
+            (filter.level === undefined || entry.level === filter.level) &&
+            (filter.traceId === undefined || entry.traceId === filter.traceId));
+        return filter.limit === undefined ? filtered : filtered.slice(-filter.limit);
+    };
+    return {
+        appendEvent(event) {
+            assertNonEmptyString(event.id, "Lifecycle event id");
+            if (seenEventIds.has(event.id))
+                return null;
+            seenEventIds.add(event.id);
+            seenOrder.push(event.id);
+            const entry = Object.freeze({
+                sequence: ++sequence,
+                at: now(),
+                sessionId: extractSessionId(event.data),
+                stage: event.type,
+                level: deriveLevel(event.type, event.data),
+                ...(event.correlationId === undefined ? {} : { traceId: event.correlationId }),
+                summary: buildSummary(event.type, event.data),
+                ...(event.data === undefined ? {} : { data: event.data }),
+            });
+            entries.push(entry);
+            while (entries.length > maxEntries) {
+                entries.shift();
+                const evicted = seenOrder.shift();
+                // v8 ignore next -- seenOrder 与 entries 同步增删，evicted 不会有 undefined
+                if (evicted !== undefined)
+                    seenEventIds.delete(evicted);
+                dropped += 1;
+            }
+            return entry;
+        },
+        query: (filter) => [...filterEntries(filter)],
+        explainTrace(traceId) {
+            assertNonEmptyString(traceId, "Trace id");
+            let previous = null;
+            const steps = entries
+                .filter((entry) => entry.traceId === traceId)
+                .map((entry) => {
+                const durationMs = previous === null ? null : entry.at - previous;
+                previous = entry.at;
+                return Object.freeze({ entry, durationMs });
+            });
+            return { traceId, steps: Object.freeze(steps) };
+        },
+        getMetrics: (options) => buildMetricsSnapshot(entries, options),
+        stats: () => ({ size: entries.length, dropped }),
+    };
+}
+/**
+ * Linear-interpolated percentile (R-7): position `(n - 1) * ratio` between the
+ * sorted order statistics. Returns `null` for an empty sample.
+ */
+export function percentile(values, ratio) {
+    if (!Number.isFinite(ratio) || ratio < 0 || ratio > 1) {
+        throw new Error("Percentile ratio must be a number between 0 and 1");
+    }
+    if (values.length === 0)
+        return null;
+    const sorted = [...values].sort((a, b) => a - b);
+    const position = (sorted.length - 1) * ratio;
+    const lower = Math.floor(position);
+    const upper = Math.ceil(position);
+    if (lower === upper)
+        return sorted[lower];
+    return sorted[lower] + (sorted[upper] - sorted[lower]) * (position - lower);
+}
+const notSampled = (reason) => ({ status: "not_sampled", reason });
+/** The journal carries no standalone cancel event: `operation.end(cancelled)` is itself the turn's terminal fact. */
+const CANCEL_LATENCY_NOT_SAMPLED = notSampled("journal records no standalone cancel signal event; operation.end(cancelled) is itself the terminal event");
+/** The lifecycle catalog defines no usage/token-bearing event for the journal to subscribe to. */
+const TOKENS_NOT_SAMPLED = notSampled("lifecycle catalog defines no usage/token cost event for the journal to record");
+const isCancelledOperationEnd = (entry) => entry.stage === OPERATION_END_EVENT_ID && isRecord(entry.data) && entry.data.status === "cancelled";
+/**
+ * Groups journal entries by their correlationId into turn groups ordered by
+ * their last entry's sequence, then keeps only the trailing `windowTurns`
+ * groups (all groups when the bound is undefined).
+ */
+function selectTurnWindow(entries, windowTurns) {
+    const groups = new Map();
+    for (const entry of entries) {
+        if (entry.traceId === undefined)
+            continue;
+        const group = groups.get(entry.traceId);
+        if (group === undefined)
+            groups.set(entry.traceId, [entry]);
+        else
+            group.push(entry);
+    }
+    const ordered = [...groups].map(([traceId, group]) => ({
+        traceId,
+        entries: group,
+        lastSequence: group[group.length - 1].sequence,
+    }));
+    ordered.sort((a, b) => a.lastSequence - b.lastSequence);
+    return windowTurns === undefined ? ordered : ordered.slice(-windowTurns);
+}
+/**
+ * Aggregates a deterministic product-metrics snapshot from journal entries.
+ * Read-only: the entries are consumed as-is, so journal recording behavior is
+ * untouched and export-side redaction cannot affect any count.
+ *
+ * Metric rulings over the lifecycle catalog (v1):
+ * - A turn is a correlationId group. It succeeds when it contains a
+ *   `model.stream` entry (assistant output) and no error-level entry and no
+ *   `operation.end(cancelled)` terminal; duration is last.at - first.at.
+ * - Tool execution is counted once per `tool.execute` entry (the settled
+ *   invocation; execute/result.raw/result/commit would multiply-count one call).
+ * - Cancel latency is not sampled: the catalog has no standalone cancel event
+ *   among the journal's subscriptions, and `operation.end(cancelled)` is itself
+ *   the terminal event, so the cancel-to-terminal delay is always zero-by-construction.
+ * - Tokens are not sampled: no usage/token event exists in the catalog.
+ * - Memory recall hit: a `memory_recall` `tool.execute` whose `isError` is false
+ *   with non-empty `content`.
+ */
+export function buildMetricsSnapshot(entries, options = {}) {
+    const windowTurns = options.windowTurns;
+    if (windowTurns !== undefined) {
+        assertPositiveSafeInteger(windowTurns, "Window turns");
+    }
+    const groups = selectTurnWindow(entries, windowTurns);
+    const windowEntries = groups.flatMap((group) => group.entries);
+    const firstAt = windowEntries[0]?.at ?? null;
+    const lastAt = windowEntries.at(-1)?.at ?? null;
+    const turnDurations = [];
+    let successCount = 0;
+    for (const group of groups) {
+        const first = group.entries[0];
+        const last = group.entries[group.entries.length - 1];
+        turnDurations.push(last.at - first.at);
+        const hasAssistantOutput = group.entries.some((entry) => entry.stage === MODEL_STREAM_EVENT_ID);
+        const hasErrorLevel = group.entries.some((entry) => entry.level === "error");
+        const hasCancelledTerminal = group.entries.some(isCancelledOperationEnd);
+        if (hasAssistantOutput && !hasErrorLevel && !hasCancelledTerminal)
+            successCount += 1;
+    }
+    let toolCalls = 0;
+    let toolErrors = 0;
+    const errorsByTool = new Map();
+    for (const entry of windowEntries) {
+        if (entry.stage !== TOOL_EXECUTE_EVENT_ID)
+            continue;
+        toolCalls += 1;
+        if (!isRecord(entry.data) || entry.data.isError !== true)
+            continue;
+        toolErrors += 1;
+        const toolName = typeof entry.data.toolName === "string" ? entry.data.toolName : "unknown";
+        errorsByTool.set(toolName, (errorsByTool.get(toolName) ?? 0) + 1);
+    }
+    const topErrors = [...errorsByTool]
+        .map(([toolName, errors]) => ({ toolName, errors }))
+        .sort((a, b) => b.errors - a.errors || (a.toolName < b.toolName ? -1 : 1));
+    let recallCalls = 0;
+    let recallHits = 0;
+    for (const entry of windowEntries) {
+        if (entry.stage !== TOOL_EXECUTE_EVENT_ID)
+            continue;
+        if (!isRecord(entry.data) || entry.data.toolName !== MEMORY_RECALL_TOOL_NAME)
+            continue;
+        recallCalls += 1;
+        if (entry.data.isError !== true && Array.isArray(entry.data.content) && entry.data.content.length > 0) {
+            recallHits += 1;
+        }
+    }
+    const memoryRecall = recallCalls === 0
+        ? notSampled("no memory_recall tool executions in the window")
+        : { status: "sampled", calls: recallCalls, hits: recallHits, hitRate: recallHits / recallCalls };
+    const cancelLatencyMs = CANCEL_LATENCY_NOT_SAMPLED;
+    const tokens = TOKENS_NOT_SAMPLED;
+    return Object.freeze({
+        version: 1,
+        window: Object.freeze({
+            windowTurns: windowTurns ?? null,
+            sampledTurns: groups.length,
+            firstAt,
+            lastAt,
+        }),
+        turns: Object.freeze({
+            count: groups.length,
+            successCount,
+            successRate: groups.length === 0 ? null : successCount / groups.length,
+            p50DurationMs: percentile(turnDurations, 0.5),
+            p95DurationMs: percentile(turnDurations, 0.95),
+        }),
+        tools: Object.freeze({
+            calls: toolCalls,
+            errors: toolErrors,
+            errorRate: toolCalls === 0 ? null : toolErrors / toolCalls,
+            topErrors: Object.freeze(topErrors),
+        }),
+        cancelLatencyMs,
+        tokens,
+        memoryRecall,
+    });
+}
+/**
+ * Bounded, redacted snapshot of an arbitrary JSON tree (design §4.3):
+ * image-like content collapses to `{ redacted: "image", approxBytes }`
+ * placeholders, strings over `maxStringChars` truncate with a
+ * `…[truncated N chars]` suffix, and — when the serialized snapshot exceeds
+ * `maxSnapshotBytes` — string leaves degrade largest-first to
+ * `{ redacted: "truncated", approxBytes }` placeholders until it fits.
+ * Structure, ordering, roles, and scalars are preserved; the function is pure
+ * and total (cycles and non-serializable values become explicit placeholders).
+ */
+export function redactProviderPayloadSnapshot(payload, limits) {
+    const redacted = redactTree(payload, limits, new Set());
+    return enforceSnapshotBudget(redacted, limits.maxSnapshotBytes);
+}
+const truncationSuffix = (originalLength, keptLength) => `…[truncated ${originalLength - keptLength} chars]`;
+/** Best-effort serialized byte size; non-serializable values fall back to their string form. */
+function approxBytesOf(value) {
+    try {
+        const serialized = JSON.stringify(value);
+        if (serialized !== undefined)
+            return Buffer.byteLength(serialized, "utf8");
+    }
+    catch {
+        // fall through to the string form below
+    }
+    return Buffer.byteLength(String(value), "utf8");
+}
+function isImageLikeContent(value) {
+    if (value.type === "image" || value.type === "image_url")
+        return true;
+    const image = value.image;
+    if (typeof image === "string" || isRecord(image))
+        return true;
+    if (typeof value.base64 === "string")
+        return true;
+    const imageUrl = value.image_url;
+    if (typeof imageUrl === "string" || isRecord(imageUrl))
+        return true;
+    // Google-family adapters inline images as {inlineData:{mimeType,data}} /
+    // {inline_data:{mime_type,data}}; both carry raw base64 and must collapse.
+    if (isRecord(value.inlineData) || isRecord(value.inline_data))
+        return true;
+    return false;
+}
+function redactTree(value, limits, seen) {
+    if (typeof value === "string") {
+        if (value.length > limits.maxStringChars) {
+            return `${value.slice(0, limits.maxStringChars)}${truncationSuffix(value.length, limits.maxStringChars)}`;
+        }
+        return value;
+    }
+    if (Array.isArray(value)) {
+        if (seen.has(value))
+            return { redacted: "circular" };
+        seen.add(value);
+        try {
+            return value.map((item) => redactTree(item, limits, seen));
+        }
+        finally {
+            seen.delete(value);
+        }
+    }
+    if (!isRecord(value))
+        return value;
+    if (seen.has(value))
+        return { redacted: "circular" };
+    seen.add(value);
+    try {
+        if (isImageLikeContent(value)) {
+            return { redacted: "image", approxBytes: approxBytesOf(value) };
+        }
+        const out = {};
+        for (const [key, entry] of Object.entries(value)) {
+            if (entry === undefined)
+                continue;
+            out[key] = redactTree(entry, limits, seen);
+        }
+        return out;
+    }
+    finally {
+        seen.delete(value);
+    }
+}
+/** Collects string leaves at any depth, keeping parent references for replacement. */
+function collectStringLeaves(value, seen, out) {
+    if (typeof value === "string" || !isRecordLikeContainer(value))
+        return;
+    if (seen.has(value))
+        return;
+    seen.add(value);
+    try {
+        const parent = value;
+        for (const [key, entry] of Object.entries(parent)) {
+            if (typeof entry === "string") {
+                const size = Buffer.byteLength(entry, "utf8");
+                if (size >= TRACE_SNAPSHOT_MIN_REDACTABLE_BYTES) {
+                    out.push({ parent, key, size });
+                }
+            }
+            else {
+                collectStringLeaves(entry, seen, out);
+            }
+        }
+    }
+    finally {
+        seen.delete(value);
+    }
+}
+function isRecordLikeContainer(value) {
+    return value !== null && typeof value === "object";
+}
+/**
+ * Degrades the largest string leaves to `{ redacted: "truncated", approxBytes }`
+ * placeholders until the snapshot fits `maxSnapshotBytes`. Roots that already
+ * fit pass through untouched; residuals fall through to the record-level guard.
+ */
+function enforceSnapshotBudget(root, maxSnapshotBytes) {
+    let total = approxBytesOf(root);
+    if (total <= maxSnapshotBytes)
+        return root;
+    const leaves = [];
+    collectStringLeaves(root, new Set(), leaves);
+    // Stable sort (ES2019+): equal sizes keep deterministic walk order.
+    leaves.sort((a, b) => b.size - a.size);
+    for (const leaf of leaves) {
+        if (total <= maxSnapshotBytes)
+            break;
+        const placeholder = { redacted: "truncated", approxBytes: leaf.size };
+        leaf.parent[leaf.key] = placeholder;
+        total -= leaf.size - approxBytesOf(placeholder);
+    }
+    return root;
+}
+/**
+ * Last-resort write guard (design §4.3): when a serialized record exceeds the
+ * 512 KiB hard budget, its `data` collapses to a record-level truncation
+ * marker. Normal traffic never reaches this — the snapshot budget (384 KiB) is
+ * strictly below it.
+ */
+function enforceRecordBudget(record) {
+    const serialized = JSON.stringify(record);
+    if (serialized !== undefined && Buffer.byteLength(serialized, "utf8") <= TRACE_RECORD_MAX_BYTES)
+        return record;
+    return { ...record, data: { truncated: true, approxBytes: approxBytesOf(record.data) } };
+}
+/**
+ * Bounded args/result summary for `tool.span` data (≤ ~2 KiB each): values
+ * that serialize within the bound stay structured, larger ones keep only a
+ * truncated serialization.
+ */
+function boundedJsonSummary(value, maxChars) {
+    try {
+        const serialized = JSON.stringify(value);
+        if (serialized === undefined)
+            return String(value);
+        if (Buffer.byteLength(serialized, "utf8") <= maxChars)
+            return value;
+        return `${serialized.slice(0, maxChars)}${truncationSuffix(serialized.length, maxChars)}`;
+    }
+    catch (error) {
+        return `[unserializable: ${error instanceof Error ? error.message : String(error)}]`;
+    }
+}
+/**
+ * Upper bound on retained stack lines for a mirrored Error value; the same
+ * bound the host logger applies to a logged cause (core/logger.ts).
+ */
+const MIRROR_ERROR_STACK_MAX_LINES = 10;
+/**
+ * Error-aware bounded serialization for the `plugin.log` mirror, with the same
+ * cause-bounding semantics as the host logger: an `Error` value becomes
+ * `{ name, message, stack: first 10 lines }` — plain JSON serialization would
+ * collapse it to `{}` because Errors own no enumerable properties — while every
+ * other value keeps the existing bounded JSON behavior. Errors nested inside
+ * objects/arrays are replaced at any depth, cycle-safe.
+ */
+function errorAwareBoundedJsonSummary(value, maxChars) {
+    const replaceErrors = (input, seen) => {
+        if (input instanceof Error) {
+            const stackLines = input.stack?.split("\n");
+            const stack = stackLines === undefined ? undefined : stackLines.slice(0, MIRROR_ERROR_STACK_MAX_LINES).join("\n");
+            return { name: input.name, message: input.message, ...(stack === undefined ? {} : { stack }) };
+        }
+        if (Array.isArray(input) || isRecord(input)) {
+            if (seen.has(input))
+                return { redacted: "circular" };
+            seen.add(input);
+            try {
+                return Array.isArray(input)
+                    ? input.map((item) => replaceErrors(item, seen))
+                    : Object.fromEntries(Object.entries(input).map(([key, entry]) => [key, replaceErrors(entry, seen)]));
+            }
+            finally {
+                seen.delete(input);
+            }
+        }
+        return input;
+    };
+    return boundedJsonSummary(replaceErrors(value, new Set()), maxChars);
+}
+/**
+ * First-party delegation tool names whose `tool.span` record gains a
+ * structured child-session reference (design §4.6 父子关联行): `subagent_run`'s
+ * foreground projection parses `tasks[].sessionId`, `subagent_result`'s a
+ * top-level `sessionId`. Third-party delegation tools are deliberately not
+ * auto-covered — they can build their own collector over the same public
+ * lifecycle subscription face.
+ */
+const DELEGATION_TOOL_NAMES = new Set(["subagent_run", "subagent_result"]);
+function firstTextOfContent(content) {
+    if (!Array.isArray(content))
+        return undefined;
+    for (const item of content) {
+        if (isRecord(item) && item.type === "text" && typeof item.text === "string")
+            return item.text;
+    }
+    return undefined;
+}
+/**
+ * Extracts the structured child-session reference from an untruncated
+ * delegation tool result: the projection JSON inside the raw `tool.execute`
+ * content is parsed — never the 2 KiB bounded display summary. Shape stays
+ * stable across task counts: `childSessionId` is always the first extracted
+ * session id and `childSessionCount` the number of session ids extracted
+ * (1 for `subagent_result`). Unparsable results, unknown tool names, or
+ * projections without a session id yield undefined — the keys stay absent,
+ * never fabricated.
+ */
+function extractChildSessionReference(toolName, result) {
+    if (!DELEGATION_TOOL_NAMES.has(toolName))
+        return undefined;
+    const text = firstTextOfContent(result);
+    if (text === undefined)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isRecord(parsed))
+        return undefined;
+    if (toolName === "subagent_result") {
+        if (typeof parsed.sessionId !== "string" || parsed.sessionId === "")
+            return undefined;
+        return { childSessionId: parsed.sessionId, childSessionCount: 1 };
+    }
+    const tasks = parsed.tasks;
+    if (!Array.isArray(tasks))
+        return undefined;
+    const sessionIds = [];
+    for (const task of tasks) {
+        if (isRecord(task) && typeof task.sessionId === "string" && task.sessionId !== "") {
+            sessionIds.push(task.sessionId);
+        }
+    }
+    if (sessionIds.length === 0)
+        return undefined;
+    return { childSessionId: sessionIds[0], childSessionCount: sessionIds.length };
+}
+/**
+ * Trace-file sink over `agent-forge/trace.v1` (design §4). Records are
+ * appended one JSON line at a time, flushed per write; `seq` restarts at 1
+ * whenever the host resolves a different path. Write failures never throw:
+ * the first failure of a streak reports through `adapter.onSinkFailure` plus a
+ * journal error entry, later consecutive failures only count.
+ */
+function createTraceSink(adapter, options, now, reportSinkError, exportSinks) {
+    const maxStringChars = options.maxStringChars ?? DEFAULT_TRACE_MAX_STRING_CHARS;
+    const maxSnapshotBytes = options.maxSnapshotBytes ?? DEFAULT_TRACE_MAX_SNAPSHOT_BYTES;
+    assertPositiveSafeInteger(maxStringChars, "Trace maxStringChars");
+    assertPositiveSafeInteger(maxSnapshotBytes, "Trace maxSnapshotBytes");
+    const limits = { maxStringChars, maxSnapshotBytes };
+    // Telemetry export seam (design §8): host-injected sinks plus the OTLP
+    // exporter when configured. Sink failures are isolated per sink and never
+    // reach event delivery or the file sink.
+    const sinks = [
+        ...exportSinks,
+        ...(options.otlp === undefined
+            ? []
+            : [
+                createOtlpTraceExportSink({
+                    ...options.otlp,
+                    onFailure: (error) => {
+                        reportSinkError(error);
+                    },
+                }),
+            ]),
+    ];
+    const feedExportSinks = (record) => {
+        for (const sink of sinks) {
+            try {
+                sink.onTraceRecord(record);
+            }
+            catch {
+                // isolated: a broken export sink must not break the file sink
+            }
+        }
+    };
+    const flushExportSinks = (reason) => {
+        for (const sink of sinks) {
+            try {
+                void sink.flush(reason).catch(() => { });
+            }
+            catch {
+                // isolated
+            }
+        }
+    };
+    let seq = 0;
+    let currentPath = null;
+    let failing = false;
+    const emitRecord = (draft) => {
+        const path = adapter.getTraceFilePath();
+        if (path === null)
+            return;
+        try {
+            if (path !== currentPath) {
+                currentPath = path;
+                seq = 0;
+            }
+            const record = enforceRecordBudget({
+                v: 1,
+                schema: TRACE_SCHEMA_V1,
+                seq: seq + 1,
+                t: now(),
+                ...draft,
+            });
+            feedExportSinks(record);
+            appendFileSync(path, `${JSON.stringify(record)}\n`, "utf8");
+            seq += 1;
+            failing = false;
+        }
+        catch (error) {
+            // Rate-limited failure handling (design §4.4): report the first
+            // failure of a streak, stay silent on consecutive ones, never throw.
+            if (!failing) {
+                failing = true;
+                try {
+                    adapter.onSinkFailure(error);
+                }
+                catch {
+                    // sink-failure reporting must never break event delivery
+                }
+                reportSinkError(error);
+            }
+        }
+    };
+    const boundedData = (data) => redactProviderPayloadSnapshot(data, limits);
+    const emitFromEvent = (event, draft) => {
+        emitRecord({
+            ...(event.correlationId === undefined ? {} : { traceId: event.correlationId }),
+            ...draft,
+        });
+    };
+    const pendingTurns = new Map();
+    const toolSpans = new Map();
+    const streams = new Map();
+    /** One captured side per toolCallId for the result-diff self-check. */
+    const resultDiffPairs = new Map();
+    /** toolCallIds whose pairing already emitted a diff record; guards idempotence. */
+    const resultDiffSeen = new Map();
+    /**
+     * Bounded-by-design insertion: past `TRACE_SPAN_STATE_MAX_ENTRIES` the
+     * oldest unpaired entry (first key in Map insertion order) is evicted FIFO.
+     */
+    const setTracked = (map, key, value) => {
+        map.set(key, value);
+        while (map.size > TRACE_SPAN_STATE_MAX_ENTRIES) {
+            const oldest = map.keys().next();
+            // v8 ignore next -- 循环条件保证 map 非空，第一个 key 必存在
+            if (oldest.done !== true)
+                map.delete(oldest.value);
+        }
+    };
+    const turnKey = (event) => {
+        if (event.correlationId !== undefined)
+            return `c:${event.correlationId}`;
+        const data = isRecord(event.data) ? event.data : {};
+        const sessionId = typeof data.sessionId === "string" ? data.sessionId : "";
+        const turnIndex = typeof data.turnIndex === "number" ? data.turnIndex : "";
+        return `t:${sessionId}:${turnIndex}`;
+    };
+    const usageToGenAi = (usage) => {
+        if (!isRecord(usage))
+            return undefined;
+        const mapped = {};
+        const fields = [
+            ["input", "gen_ai.usage.input_tokens"],
+            ["output", "gen_ai.usage.output_tokens"],
+            ["cacheRead", "gen_ai.usage.cache_read_tokens"],
+            ["cacheWrite", "gen_ai.usage.cache_write_tokens"],
+            ["totalTokens", "gen_ai.usage.total_tokens"],
+        ];
+        for (const [source, target] of fields) {
+            const value = usage[source];
+            if (typeof value === "number" && Number.isFinite(value))
+                mapped[target] = value;
+        }
+        const cost = usage.cost;
+        if (isRecord(cost) && typeof cost.total === "number" && Number.isFinite(cost.total)) {
+            mapped["gen_ai.usage.cost"] = cost.total;
+        }
+        return Object.keys(mapped).length > 0 ? mapped : undefined;
+    };
+    const emitGenericLifecycle = (event) => {
+        emitFromEvent(event, {
+            kind: "lifecycle",
+            level: deriveLevel(event.type, event.data),
+            data: boundedData({ event: event.type, data: event.data }),
+        });
+    };
+    /**
+     * Result-diff self-check (design §4.2 `decision` row): captures one side of
+     * the `tool.result.raw@1` → `tool.result@1` pairing for a toolCallId. Once
+     * both sides arrived, their bounded serializations are compared and a
+     * mismatch emits one `decision` record with `{toolCallId, rawBytes,
+     * finalBytes}`.
+     *
+     * Record semantics: "the final output differs from the tool's raw output".
+     * Legacy result hooks and image normalization also contribute to a
+     * difference, so this is deliberately not a transform attribution. The
+     * comparison reuses the 2 KiB bounded summary; both byte sizes refer to
+     * those bounded serializations.
+     *
+     * Idempotence: a toolCallId whose pairing already emitted a `decision`
+     * record is remembered (bounded, FIFO-evicted like the other span-state
+     * tables); later raw/final deliveries for the same toolCallId are skipped
+     * outright, so duplicate events can never trigger a second comparison or a
+     * second record.
+     */
+    const recordResultDiffSide = (side, event) => {
+        const data = isRecord(event.data) ? event.data : {};
+        const toolCallId = data.toolCallId;
+        if (typeof toolCallId !== "string")
+            return;
+        if (resultDiffSeen.has(toolCallId))
+            return;
+        const content = side === "raw" ? data.content : isRecord(data.message) ? data.message.content : undefined;
+        if (!Array.isArray(content))
+            return; // a side that cannot be serialized is never fabricated
+        const serialized = JSON.stringify(boundedJsonSummary(content, TRACE_TOOL_SUMMARY_MAX_CHARS));
+        if (serialized === undefined)
+            return;
+        const pair = resultDiffPairs.get(toolCallId) ?? {};
+        pair[side] = serialized;
+        setTracked(resultDiffPairs, toolCallId, pair);
+        if (pair.raw === undefined || pair.final === undefined)
+            return;
+        resultDiffPairs.delete(toolCallId);
+        if (pair.raw === pair.final)
+            return;
+        setTracked(resultDiffSeen, toolCallId, true);
+        emitFromEvent(event, {
+            kind: "decision",
+            level: "info",
+            data: {
+                toolCallId,
+                rawBytes: Buffer.byteLength(pair.raw, "utf8"),
+                finalBytes: Buffer.byteLength(pair.final, "utf8"),
+            },
+        });
+    };
+    const handleEvent = (event) => {
+        const data = isRecord(event.data) ? event.data : {};
+        switch (event.type) {
+            case SESSION_START_EVENT_ID: {
+                // Session-level parent linkage (design §4.2 session.start row):
+                // the session-header facts arrive through the host adapter; an
+                // adapter without a getter — or an unset header field — keeps
+                // the previous record shape (no parentSessionId/parentTraceId
+                // key, never null).
+                const parentSessionId = adapter.getParentAgentSessionId?.();
+                const parentTraceId = adapter.getParentTraceId?.();
+                emitFromEvent(event, {
+                    kind: "session.start",
+                    level: "info",
+                    data: boundedData({
+                        ...data,
+                        ...(parentSessionId === undefined ? {} : { parentSessionId }),
+                        ...(parentTraceId === undefined ? {} : { parentTraceId }),
+                    }),
+                });
+                return;
+            }
+            case SESSION_END_EVENT_ID:
+                // The session.end fact stays in the trace file (lifecycle record);
+                // the export sinks get their final flush beside it (design §8).
+                emitGenericLifecycle(event);
+                flushExportSinks("session.end");
+                return;
+            case TURN_START_EVENT_ID:
+                setTracked(pendingTurns, turnKey(event), { startedAt: now() });
+                return;
+            case TURN_END_EVENT_ID: {
+                const key = turnKey(event);
+                const pending = pendingTurns.get(key);
+                if (pending === undefined)
+                    return; // unpaired span: no record (crash leaves gaps by design)
+                pendingTurns.delete(key);
+                const endedAt = now();
+                emitFromEvent(event, {
+                    kind: "turn.span",
+                    level: "info",
+                    dur: Math.max(0, endedAt - pending.startedAt),
+                    data: boundedData({
+                        ...(typeof data.sessionId === "string" ? { sessionId: data.sessionId } : {}),
+                        ...(typeof data.turnIndex === "number" ? { turnIndex: data.turnIndex } : {}),
+                        ...(typeof data.messageCount === "number" ? { messageCount: data.messageCount } : {}),
+                        // 回合级偏离结果（第 4 期）：completed 回合省键，从不虚构。
+                        ...(typeof data.outcome === "string" ? { outcome: data.outcome } : {}),
+                    }),
+                });
+                return;
+            }
+            case TOOL_EXECUTION_START_EVENT_ID: {
+                if (typeof data.toolCallId !== "string")
+                    return;
+                const span = toolSpans.get(data.toolCallId) ?? { toolName: "unknown" };
+                setTracked(toolSpans, data.toolCallId, {
+                    ...span,
+                    toolName: typeof data.toolName === "string" ? data.toolName : span.toolName,
+                    startedAt: now(),
+                });
+                return;
+            }
+            case TOOL_CALL_EVENT_ID:
+            case TOOL_EXECUTE_EVENT_ID: {
+                // Args/result capture only; the span record is emitted on commit.
+                if (typeof data.toolCallId !== "string")
+                    return;
+                const span = toolSpans.get(data.toolCallId) ?? {
+                    toolName: typeof data.toolName === "string" ? data.toolName : "unknown",
+                };
+                setTracked(toolSpans, data.toolCallId, {
+                    ...span,
+                    ...(data.input !== undefined ? { args: data.input } : {}),
+                    ...(event.type === TOOL_EXECUTE_EVENT_ID && data.content !== undefined ? { result: data.content } : {}),
+                });
+                return;
+            }
+            case TOOL_GATE_BLOCKED_EVENT_ID: {
+                // 拦截归因（第 4 期）：仅当该 callId 的 span state 已存在时写入
+                // blocked 标记；state 缺席即忽略，不照 TOOL_CALL/TOOL_EXECUTION_START
+                // 的缺席建 state 先例（防伪造 callId 占用 256 FIFO 淘汰窗口）。
+                if (typeof data.toolCallId !== "string")
+                    return;
+                const span = toolSpans.get(data.toolCallId);
+                if (span !== undefined) {
+                    span.blocked = true;
+                    if (typeof data.reason === "string" && data.reason !== "")
+                        span.blockReason = data.reason;
+                }
+                emitGenericLifecycle(event);
+                return;
+            }
+            case TOOL_COMMIT_EVENT_ID: {
+                if (typeof data.toolCallId !== "string")
+                    return;
+                const span = toolSpans.get(data.toolCallId);
+                if (span === undefined || span.startedAt === undefined)
+                    return; // unpaired span: no record
+                toolSpans.delete(data.toolCallId);
+                const isError = data.isError === true;
+                const endedAt = now();
+                const toolName = typeof data.toolName === "string" ? data.toolName : span.toolName;
+                // 父侧结构化子会话引用（第 4 期，design §4.6）：仅识别第一方委派工具，
+                // 从未截断的 tool.execute content 解析（非 2KiB 展示文本）；提取失败省键。
+                const childSession = extractChildSessionReference(toolName, span.result);
+                emitFromEvent(event, {
+                    kind: "tool.span",
+                    level: isError ? "error" : "info",
+                    dur: Math.max(0, endedAt - span.startedAt),
+                    data: boundedData({
+                        callId: data.toolCallId,
+                        toolName,
+                        isError,
+                        // 拦截归因（第 4 期）：span state 标记过 blocked 才投影；reason
+                        // 未标记则省 blockReason 键，正常调用两键都不出现。
+                        ...(span.blocked === true ? { blocked: true } : {}),
+                        ...(span.blocked === true && span.blockReason !== undefined ? { blockReason: span.blockReason } : {}),
+                        ...(childSession === undefined ? {} : { childSessionId: childSession.childSessionId }),
+                        ...(childSession === undefined ? {} : { childSessionCount: childSession.childSessionCount }),
+                        ...(span.args !== undefined
+                            ? { args: boundedJsonSummary(span.args, TRACE_TOOL_SUMMARY_MAX_CHARS) }
+                            : {}),
+                        ...(span.result !== undefined
+                            ? { result: boundedJsonSummary(span.result, TRACE_TOOL_SUMMARY_MAX_CHARS) }
+                            : {}),
+                    }),
+                });
+                return;
+            }
+            case MODEL_STREAM_EVENT_ID: {
+                const streamId = typeof data.streamId === "string" ? data.streamId : null;
+                if (streamId === null)
+                    return;
+                const eventName = data.event;
+                if (eventName === "start") {
+                    setTracked(streams, streamId, { startedAt: now() });
+                    return;
+                }
+                if (data.terminal !== true) {
+                    if (typeof eventName === "string" && eventName.endsWith("_delta")) {
+                        const timing = streams.get(streamId);
+                        if (timing !== undefined && timing.firstDeltaAt === undefined)
+                            timing.firstDeltaAt = now();
+                    }
+                    return;
+                }
+                const timing = streams.get(streamId);
+                streams.delete(streamId);
+                const streamEndedAt = now();
+                const partial = isRecord(data.partial) ? data.partial : undefined;
+                const usage = usageToGenAi(partial?.usage);
+                const isErrorEvent = eventName === "error";
+                emitFromEvent(event, {
+                    kind: "llm.response",
+                    level: isErrorEvent ? "error" : "info",
+                    ...(timing?.startedAt !== undefined ? { dur: Math.max(0, streamEndedAt - timing.startedAt) } : {}),
+                    data: boundedData({
+                        streamId,
+                        ...(typeof partial?.stopReason === "string" ? { stopReason: partial.stopReason } : {}),
+                        ...(usage !== undefined ? usage : {}),
+                        ...(timing?.startedAt !== undefined && timing.firstDeltaAt !== undefined
+                            ? { ttftMs: Math.max(0, timing.firstDeltaAt - timing.startedAt) }
+                            : {}),
+                        ...(isErrorEvent ? { error: boundedData(data.error) } : {}),
+                    }),
+                });
+                return;
+            }
+            case SESSION_AUTO_RETRY_EVENT_ID:
+            case SESSION_COMPACTION_DECISION_EVENT_ID:
+                // Retry/compaction decisions: validated event data passes through
+                // the bounded redaction channel verbatim; absent optional fields
+                // (threshold triplet) stay absent — never fabricated.
+                emitFromEvent(event, { kind: "decision", level: "info", data: boundedData(event.data) });
+                return;
+            case SESSION_COMPACTION_FAILED_EVENT_ID:
+                // A genuinely failed compaction is a real failure terminal, not a
+                // decision: records as `error` with the reason/errorMessage facts.
+                emitFromEvent(event, {
+                    kind: "error",
+                    level: "error",
+                    data: boundedData({
+                        ...(typeof data.reason === "string" ? { reason: data.reason } : {}),
+                        ...(typeof data.errorMessage === "string" ? { errorMessage: data.errorMessage } : {}),
+                    }),
+                });
+                return;
+            case SESSION_COMPACTION_COMMIT_EVENT_ID: {
+                // Whitelist projection: summary and other long-text fields stay out
+                // of the trace record on purpose (design §4.2 decision row).
+                emitFromEvent(event, {
+                    kind: "decision",
+                    level: "info",
+                    data: boundedData({
+                        ...(typeof data.entryId === "string" ? { entryId: data.entryId } : {}),
+                        ...(typeof data.reason === "string" ? { reason: data.reason } : {}),
+                        ...(typeof data.tokensBefore === "number" ? { tokensBefore: data.tokensBefore } : {}),
+                        ...(data.usage === undefined ? {} : { usage: data.usage }),
+                    }),
+                });
+                return;
+            }
+            case TOOL_RESULT_RAW_EVENT_ID:
+                emitGenericLifecycle(event);
+                recordResultDiffSide("raw", event);
+                return;
+            case TOOL_RESULT_EVENT_ID:
+                emitGenericLifecycle(event);
+                recordResultDiffSide("final", event);
+                return;
+            case OPERATION_END_EVENT_ID:
+            case PLUGIN_DISPOSE_EVENT_ID: {
+                if (data.status === "failed") {
+                    // Captured error terminal: the `error` kind records the failure fact.
+                    emitFromEvent(event, {
+                        kind: "error",
+                        level: "error",
+                        data: boundedData({ source: event.type, ...data }),
+                    });
+                    return;
+                }
+                emitGenericLifecycle(event);
+                return;
+            }
+            default:
+                emitGenericLifecycle(event);
+        }
+    };
+    return {
+        flush: () => flushExportSinks("dispose"),
+        onEvent(event) {
+            try {
+                handleEvent(event);
+            }
+            catch {
+                // Trace collection must never break event delivery (design §4.4).
+            }
+        },
+        captureProviderPayload(payload, model) {
+            const source = isRecord(payload) ? payload : {};
+            const tools = source.tools;
+            const messages = source.messages;
+            // Both wire shapes are accepted: Anthropic lists tools flat
+            // (`tools[].name`), openai-completions nests them under
+            // `tools[].function.name`; only string names are collected.
+            const toolNames = Array.isArray(tools)
+                ? tools
+                    .map((tool) => {
+                    if (!isRecord(tool))
+                        return null;
+                    if (typeof tool.name === "string")
+                        return tool.name;
+                    const fn = tool.function;
+                    return isRecord(fn) && typeof fn.name === "string" ? fn.name : null;
+                })
+                    .filter((name) => name !== null)
+                : undefined;
+            const system = source.system;
+            let systemPromptChars;
+            if (typeof system === "string") {
+                systemPromptChars = system.length;
+            }
+            else if (Array.isArray(system)) {
+                let total = 0;
+                let found = false;
+                for (const block of system) {
+                    if (isRecord(block) && typeof block.text === "string") {
+                        total += block.text.length;
+                        found = true;
+                    }
+                }
+                if (found)
+                    systemPromptChars = total;
+            }
+            if (systemPromptChars === undefined && Array.isArray(messages)) {
+                // openai-completions wire shape: the system prompt rides as
+                // system-role messages instead of a top-level `system` field.
+                let total = 0;
+                let found = false;
+                for (const message of messages) {
+                    if (!isRecord(message) || message.role !== "system")
+                        continue;
+                    const content = message.content;
+                    if (typeof content === "string") {
+                        total += content.length;
+                        found = true;
+                    }
+                    else if (Array.isArray(content)) {
+                        for (const part of content) {
+                            if (isRecord(part) && typeof part.text === "string") {
+                                total += part.text.length;
+                                found = true;
+                            }
+                        }
+                    }
+                }
+                if (found)
+                    systemPromptChars = total;
+            }
+            const data = {
+                ...(typeof model === "string" ? { "gen_ai.request.model": model } : {}),
+                ...(systemPromptChars === undefined ? {} : { systemPromptChars }),
+                ...(Array.isArray(messages) ? { messageCount: messages.length } : {}),
+                ...(toolNames === undefined ? {} : { toolNames }),
+                payload: redactProviderPayloadSnapshot(payload, limits),
+            };
+            // Emitted immediately: the payload is final before the request is
+            // sent, so "written" means "was about to be sent" even under a crash
+            // (design §4.2 llm.request row). traceId comes from the turn in
+            // flight; an adapter without the getter keeps the phase-1 shape
+            // (no traceId field).
+            const traceId = adapter.getTurnCorrelationId?.();
+            emitRecord({
+                ...(traceId === undefined ? {} : { traceId }),
+                kind: "llm.request",
+                level: "info",
+                data,
+            });
+        },
+        mirrorPluginLog(record) {
+            // Self-recursion guard (design §4.4): never call api.logger on this
+            // path — the host forwards logger output into here, so a logger call
+            // would loop. Trace-append only; emitRecord never throws.
+            const traceId = adapter.getTurnCorrelationId?.();
+            emitRecord({
+                ...(traceId === undefined ? {} : { traceId }),
+                kind: "plugin.log",
+                // debug maps to the envelope's info floor; data.level keeps the
+                // record's own level verbatim.
+                level: record.level === "warn" ? "warn" : record.level === "error" ? "error" : "info",
+                data: {
+                    pluginId: record.pluginId,
+                    level: record.level,
+                    message: record.message,
+                    ...(record.fields === undefined
+                        ? {}
+                        : { fields: errorAwareBoundedJsonSummary(record.fields, TRACE_TOOL_SUMMARY_MAX_CHARS) }),
+                    ...(record.cause === undefined
+                        ? {}
+                        : { cause: errorAwareBoundedJsonSummary(record.cause, TRACE_TOOL_SUMMARY_MAX_CHARS) }),
+                },
+            });
+        },
+    };
+}
+/**
+ * Events the journal records; the ids come from the shared lifecycle catalog
+ * (see `./event-ids.ts`). The trace sink consumes the same deliveries but
+ * never changes this set. The host defines these events before capability
+ * plugins load; the plugin only holds the `{ id, version }` reference.
+ */
+const observedEventIds = [
+    { id: MODEL_STREAM_EVENT_ID, version: CATALOG_EVENT_VERSION },
+    { id: TOOL_CALL_EVENT_ID, version: CATALOG_EVENT_VERSION },
+    { id: TOOL_EXECUTE_EVENT_ID, version: CATALOG_EVENT_VERSION },
+    { id: TOOL_RESULT_RAW_EVENT_ID, version: CATALOG_EVENT_VERSION },
+    { id: TOOL_RESULT_EVENT_ID, version: CATALOG_EVENT_VERSION },
+    { id: TOOL_COMMIT_EVENT_ID, version: CATALOG_EVENT_VERSION },
+    { id: OPERATION_END_EVENT_ID, version: CATALOG_EVENT_VERSION },
+    { id: PLUGIN_READY_EVENT_ID, version: CATALOG_EVENT_VERSION },
+    { id: PLUGIN_DISPOSE_EVENT_ID, version: CATALOG_EVENT_VERSION },
+    { id: SESSION_RELOAD_EVENT_ID, version: CATALOG_EVENT_VERSION },
+    { id: SESSION_CONTEXT_REPLACED_EVENT_ID, version: CATALOG_EVENT_VERSION },
+];
+/**
+ * Trace-only subscriptions (design §4.4): span-pairing, session/agent facts,
+ * and the decision/compaction attribution events the trace sink needs but the
+ * journal must not record, so journal and problem-report behavior stays
+ * byte-identical with or without tracing. Each event id keeps exactly one
+ * registration; these are additional ids, not a parallel subscription
+ * mechanism. Registered only when a trace adapter is injected. The phase-4
+ * additions close the coverage-matrix gaps (design §4.6): session.end@1,
+ * agent.task.settled@1, and the prompt/input boundary events.
+ */
+const traceOnlyObservedEventIds = [
+    { id: SESSION_START_EVENT_ID, version: CATALOG_EVENT_VERSION },
+    { id: TURN_START_EVENT_ID, version: CATALOG_EVENT_VERSION },
+    { id: TURN_END_EVENT_ID, version: CATALOG_EVENT_VERSION },
+    { id: TOOL_EXECUTION_START_EVENT_ID, version: CATALOG_EVENT_VERSION },
+    { id: MODEL_SELECT_EVENT_ID, version: CATALOG_EVENT_VERSION },
+    { id: AGENT_SETTLED_EVENT_ID, version: CATALOG_EVENT_VERSION },
+    { id: SESSION_AUTO_RETRY_EVENT_ID, version: CATALOG_EVENT_VERSION },
+    { id: SESSION_COMPACTION_DECISION_EVENT_ID, version: CATALOG_EVENT_VERSION },
+    { id: SESSION_COMPACTION_FAILED_EVENT_ID, version: CATALOG_EVENT_VERSION },
+    { id: SESSION_COMPACTION_COMMIT_EVENT_ID, version: CATALOG_EVENT_VERSION },
+    { id: SESSION_END_EVENT_ID, version: CATALOG_EVENT_VERSION },
+    { id: AGENT_TASK_SETTLED_EVENT_ID, version: CATALOG_EVENT_VERSION },
+    // 拦截归因（第 4 期）：block 短路观察事实；handleEvent 专门 case 标记
+    // span state 后走 emitGenericLifecycle。
+    { id: TOOL_GATE_BLOCKED_EVENT_ID, version: CATALOG_EVENT_VERSION },
+    // 纯订阅缺口闭合（第 4 期，design §4.6）：用户提示边界与输入到达；均经
+    // handleEvent 的 default 分支走 emitGenericLifecycle（kind="lifecycle"）。
+    { id: UI_PROMPT_START_EVENT_ID, version: CATALOG_EVENT_VERSION },
+    { id: UI_PROMPT_END_EVENT_ID, version: CATALOG_EVENT_VERSION },
+    { id: INPUT_RECEIVED_EVENT_ID, version: CATALOG_EVENT_VERSION },
+];
+function createRedactionContext() {
+    return { surface: "cli-text", policyVersion: REDACTION_POLICY_VERSION, inspectorAuthorized: false };
+}
+function sortedCounts(entries, pick) {
+    const counts = {};
+    for (const entry of entries) {
+        const key = pick(entry);
+        counts[key] = (counts[key] ?? 0) + 1;
+    }
+    const sorted = {};
+    for (const key of Object.keys(counts).sort())
+        sorted[key] = counts[key];
+    return sorted;
+}
+/**
+ * Builds a deterministic problem report from the journal. Every payload is
+ * rendered through the host output serializer redaction channel, and the whole
+ * report body goes through a second whole-document pass, so internal field
+ * keys cannot survive at any depth.
+ */
+export function buildProblemReport(input) {
+    assertNonEmptyString(input.sessionId, "Report sessionId");
+    assertNonEmptyString(input.reason, "Report reason");
+    if (!Number.isSafeInteger(input.tailSize) || input.tailSize < 0) {
+        throw new Error("Report tailSize must be a non-negative safe integer");
+    }
+    const redactionContext = createRedactionContext();
+    const sessionEntries = input.journal.query({ sessionId: input.sessionId });
+    let redactionApplied = false;
+    const projectPayload = (payload) => {
+        const projection = input.serializer.project({ data: payload }, redactionContext);
+        if (projection.redactions !== undefined)
+            redactionApplied = true;
+        return projection.text;
+    };
+    const lastErrorEntry = [...sessionEntries].reverse().find((entry) => entry.level === "error") ?? null;
+    const lastErrorDetail = lastErrorEntry === null ? null : extractErrorInfo(lastErrorEntry);
+    const lastError = lastErrorEntry === null || lastErrorDetail === null
+        ? null
+        : Object.freeze({
+            sequence: lastErrorEntry.sequence,
+            at: lastErrorEntry.at,
+            stage: lastErrorEntry.stage,
+            ...(lastErrorDetail.phase === undefined ? {} : { phase: lastErrorDetail.phase }),
+            traceId: lastErrorEntry.traceId ?? null,
+            code: lastErrorDetail.code,
+            message: lastErrorDetail.message,
+        });
+    const tail = sessionEntries.slice(-input.tailSize).map((entry) => Object.freeze({
+        sequence: entry.sequence,
+        at: entry.at,
+        stage: entry.stage,
+        level: entry.level,
+        traceId: entry.traceId ?? null,
+        summary: entry.summary,
+        ...(entry.data === undefined ? {} : { data: projectPayload(entry.data) }),
+    }));
+    const draft = {
+        version: 1,
+        createdAt: input.now(),
+        reason: input.reason,
+        session: Object.freeze({
+            sessionId: input.sessionId,
+            entryCount: sessionEntries.length,
+            firstSequence: sessionEntries[0]?.sequence ?? null,
+            lastSequence: sessionEntries[sessionEntries.length - 1]?.sequence ?? null,
+        }),
+        lastError,
+        journalTail: tail,
+        counts: Object.freeze({
+            byStage: sortedCounts(sessionEntries, (entry) => entry.stage),
+            byLevel: sortedCounts(sessionEntries, (entry) => entry.level),
+        }),
+        dropped: input.journal.stats().dropped,
+    };
+    // Whole-report redaction pass: the exporter output may only ever carry
+    // allowlisted field names, at any depth, even if a future report field
+    // starts colliding with an internal key.
+    const wholeReportProjection = input.serializer.project(draft, redactionContext);
+    // v8 ignore next -- 报告体字段名不含内部键；二遍脱敏是防未来字段冲突的前瞻防御
+    if (wholeReportProjection.redactions !== undefined)
+        redactionApplied = true;
+    const body = {
+        ...draft,
+        redactionApplied,
+        projection: Object.freeze({ surface: redactionContext.surface, text: wholeReportProjection.text }),
+    };
+    const reportId = fnv1a32Hex(canonicalJson(body));
+    return Object.freeze({ ...body, reportId });
+}
+/**
+ * Creates the observability plugin on top of a public capability API.
+ * Returns the journal facade, the deterministic problem-report exporter, and
+ * — when a trace adapter is injected — the trace sink (design §4).
+ */
+export function createObservabilityPlugin(api, options = {}) {
+    const maxEntries = options.maxEntries ?? DEFAULT_JOURNAL_MAX_ENTRIES;
+    const tailSize = options.tailSize ?? DEFAULT_PROBLEM_REPORT_TAIL_SIZE;
+    assertPositiveSafeInteger(tailSize, "Report tailSize");
+    const now = options.now ?? (() => Date.now());
+    const journal = createObservabilityJournal({ maxEntries, now });
+    const serializer = createHostOutputSerializer();
+    let sinkFailureSequence = 0;
+    const reportSinkError = (error) => {
+        sinkFailureSequence += 1;
+        // Synthetic journal entry (not a catalog event): keeps the failure
+        // visible to problem reports without touching the lifecycle directory.
+        journal.appendEvent({
+            id: `${OBSERVABILITY_PLUGIN_ID}/trace-sink-failure/${sinkFailureSequence}`,
+            deliveryId: `trace-sink-failure-${sinkFailureSequence}`,
+            type: TRACE_SINK_FAILURE_STAGE,
+            version: 1,
+            phase: "committed",
+            source: OBSERVABILITY_PLUGIN_ID,
+            timestamp: now(),
+            // `isError` drives the journal's generic error-level derivation; the
+            // `error` envelope feeds the problem report's last-error extraction.
+            data: {
+                isError: true,
+                error: { code: "trace.sink.failed", message: error instanceof Error ? error.message : String(error) },
+            },
+        });
+    };
+    const traceConfig = options.trace;
+    const trace = traceConfig === undefined
+        ? undefined
+        : createTraceSink(traceConfig.adapter, traceConfig.options ?? {}, now, reportSinkError, traceConfig.exportSinks ?? []);
+    const record = (event) => {
+        journal.appendEvent(event);
+        trace?.onEvent(event);
+    };
+    const registrations = [];
+    for (const binding of observedEventIds) {
+        registrations.push(api.lifecycle.registerObserve(binding.id, record, binding.version));
+    }
+    if (trace !== undefined) {
+        for (const binding of traceOnlyObservedEventIds) {
+            registrations.push(api.lifecycle.registerObserve(binding.id, (event) => trace.onEvent(event), binding.version));
+        }
+    }
+    const exportProblemReport = async (input) => {
+        const report = buildProblemReport({
+            journal,
+            now,
+            tailSize,
+            serializer,
+            sessionId: input.sessionId,
+            reason: input.reason,
+        });
+        // Artifact persistence uses only the public OutputArtifactAPI. When the
+        // host did not declare the `output-artifacts` feature, api.output is
+        // undefined and the report object alone is returned; reaching the host
+        // artifact store through any other path is not allowed here.
+        if (api.output === undefined)
+            return report;
+        const ref = await api.output.put({
+            sessionId: input.sessionId,
+            operationId: PROBLEM_REPORT_OPERATION_ID,
+            kind: "problem-report",
+            mediaType: "application/json",
+            truncated: false,
+            data: new TextEncoder().encode(canonicalJson(report)),
+        });
+        return Object.freeze({ ...report, artifact: Object.freeze({ ...ref }) });
+    };
+    return {
+        id: OBSERVABILITY_PLUGIN_ID,
+        query: (filter) => journal.query(filter),
+        explainTrace: (traceId) => journal.explainTrace(traceId),
+        getMetrics: (options) => journal.getMetrics(options),
+        stats: () => journal.stats(),
+        exportProblemReport,
+        captureProviderPayload: (payload, model) => trace?.captureProviderPayload(payload, model),
+        mirrorPluginLog: (record) => trace?.mirrorPluginLog(record),
+        dispose: () => {
+            trace?.flush();
+            const failures = [];
+            for (const registration of registrations) {
+                try {
+                    registration.dispose();
+                }
+                catch (error) {
+                    failures.push(error);
+                }
+            }
+            registrations.length = 0;
+            if (failures.length === 1)
+                throw failures[0];
+            if (failures.length > 1)
+                throw new AggregateError(failures, "Observability plugin disposal failed");
+        },
+    };
+}
+//# sourceMappingURL=observability.js.map