@smithers-orchestrator/observability 0.20.0 → 0.20.1

package/src/_traceEventNormalizers.js

@@ -0,0 +1,397 @@
+import { extractTextFromJsonValue } from "@smithers-orchestrator/agents/BaseCliAgent";
+import { normalizeTokenUsage } from "@smithers-orchestrator/agents/BaseCliAgent";
+
+/**
+ * @typedef {import('./agentTrace.ts').AgentFamily} AgentFamily
+ * @typedef {import('./agentTrace.ts').CanonicalAgentTraceEventKind} CanonicalAgentTraceEventKind
+ *
+ * @typedef {"message" | "tool" | "pi" | "none"} PayloadKind
+ *
+ * @typedef {{
+ *   kind: CanonicalAgentTraceEventKind;
+ *   payloadKind: PayloadKind;
+ *   expect?: CanonicalAgentTraceEventKind;
+ * }} MappedStructuredEvent
+ *
+ * @typedef {{
+ *   kind: CanonicalAgentTraceEventKind;
+ *   payload: Record<string, unknown> | null;
+ *   raw: unknown;
+ *   rawType?: string;
+ *   observed?: boolean;
+ * }} NormalizedTraceEvent
+ *
+ * @typedef {{
+ *   events: NormalizedTraceEvent[];
+ *   expectedKinds?: CanonicalAgentTraceEventKind[];
+ * }} NormalizedTraceBatch
+ */
+
+/** @type {Record<string, MappedStructuredEvent>} */
+const piSimpleEventMap = {
+    session: { kind: "session.start", payloadKind: "pi" },
+    agent_start: { kind: "session.start", payloadKind: "pi" },
+    agent_end: { kind: "session.end", payloadKind: "pi" },
+    turn_start: { kind: "turn.start", payloadKind: "pi", expect: "turn.end" },
+    message_start: { kind: "message.start", payloadKind: "pi" },
+    tool_execution_start: { kind: "tool.execution.start", payloadKind: "tool", expect: "tool.execution.end" },
+    tool_execution_update: { kind: "tool.execution.update", payloadKind: "tool", expect: "tool.execution.end" },
+    tool_execution_end: { kind: "tool.execution.end", payloadKind: "tool" },
+    auto_compaction_start: { kind: "compaction.start", payloadKind: "pi" },
+    auto_compaction_end: { kind: "compaction.end", payloadKind: "pi" },
+    auto_retry_start: { kind: "retry.start", payloadKind: "pi" },
+    auto_retry_end: { kind: "retry.end", payloadKind: "pi" },
+};
+
+/** @type {Record<string, MappedStructuredEvent>} */
+const genericStructuredEventMap = {
+    message_start: { kind: "message.start", payloadKind: "message" },
+    assistant_message_start: { kind: "message.start", payloadKind: "message" },
+    "response.started": { kind: "message.start", payloadKind: "message" },
+    tool_call_start: { kind: "tool.execution.start", payloadKind: "tool", expect: "tool.execution.end" },
+    tool_execution_start: { kind: "tool.execution.start", payloadKind: "tool", expect: "tool.execution.end" },
+    "tool_call.started": { kind: "tool.execution.start", payloadKind: "tool", expect: "tool.execution.end" },
+    tool_call_delta: { kind: "tool.execution.update", payloadKind: "tool", expect: "tool.execution.end" },
+    tool_call_update: { kind: "tool.execution.update", payloadKind: "tool", expect: "tool.execution.end" },
+    tool_execution_update: { kind: "tool.execution.update", payloadKind: "tool", expect: "tool.execution.end" },
+    "tool_call.delta": { kind: "tool.execution.update", payloadKind: "tool", expect: "tool.execution.end" },
+    tool_call_end: { kind: "tool.execution.end", payloadKind: "tool" },
+    tool_execution_end: { kind: "tool.execution.end", payloadKind: "tool" },
+    "tool_call.completed": { kind: "tool.execution.end", payloadKind: "tool" },
+    tool_result: { kind: "tool.result", payloadKind: "tool" },
+    "tool_result.completed": { kind: "tool.result", payloadKind: "tool" },
+};
+
+/**
+ * @param {any} parsed
+ * @returns {string | undefined}
+ */
+function extractGenericDeltaText(parsed) {
+    const candidates = [
+        parsed?.delta?.text,
+        parsed?.delta,
+        parsed?.text,
+        parsed?.content_block?.text,
+        parsed?.contentBlock?.text,
+        parsed?.message?.text,
+        parsed?.message?.content,
+        parsed?.output_text,
+    ];
+    for (const candidate of candidates) {
+        if (typeof candidate === "string" && candidate) return candidate;
+    }
+    return undefined;
+}
+
+/**
+ * @param {any} parsed
+ * @returns {string | undefined}
+ */
+function extractGenericMessageText(parsed) {
+    return extractTextFromJsonValue(parsed?.message ?? parsed?.response ?? parsed?.item ?? parsed);
+}
+
+/**
+ * @param {any} parsed
+ * @returns {Record<string, unknown>}
+ */
+function extractGenericMessagePayload(parsed) {
+    /** @type {Record<string, unknown>} */
+    const payload = {};
+    const role = parsed?.message?.role ?? parsed?.role ?? parsed?.response?.role;
+    if (typeof role === "string") payload.role = role;
+    const text = extractGenericMessageText(parsed);
+    if (text) payload.text = text;
+    if (parsed?.id) payload.id = parsed.id;
+    return payload;
+}
+
+/**
+ * @param {any} parsed
+ * @returns {Record<string, unknown>}
+ */
+function extractGenericToolPayload(parsed) {
+    const tool = parsed?.tool ?? parsed?.toolCall ?? parsed?.tool_call ?? parsed?.toolExecution ?? parsed;
+    return {
+        toolCallId: tool?.id ?? tool?.toolCallId ?? parsed?.id,
+        toolName: tool?.name ?? tool?.toolName ?? parsed?.toolName,
+        argsPreview: tool?.args ?? tool?.arguments ?? parsed?.args,
+        resultPreview: tool?.result ?? parsed?.result,
+        isError: Boolean(tool?.isError ?? parsed?.isError ?? parsed?.error),
+    };
+}
+
+/**
+ * @param {any} parsed
+ * @returns {Record<string, unknown>}
+ */
+function extractPiPayload(parsed) {
+    /** @type {Record<string, unknown>} */
+    const payload = {};
+    if (parsed?.message?.role) payload.role = parsed.message.role;
+    const text = extractGenericMessageText(parsed?.message);
+    if (text) payload.text = text;
+    if (parsed?.id) payload.id = parsed.id;
+    return payload;
+}
+
+/**
+ * @param {any} parsed
+ * @param {PayloadKind} payloadKind
+ * @returns {Record<string, unknown> | null}
+ */
+function extractMappedPayload(parsed, payloadKind) {
+    if (payloadKind === "message") return extractGenericMessagePayload(parsed);
+    if (payloadKind === "tool") return extractGenericToolPayload(parsed);
+    if (payloadKind === "pi") return extractPiPayload(parsed);
+    return {};
+}
+
+/**
+ * @param {CanonicalAgentTraceEventKind} kind
+ * @param {Record<string, unknown> | null} payload
+ * @param {unknown} raw
+ * @param {string | undefined} rawType
+ * @param {boolean} [observed]
+ * @returns {NormalizedTraceEvent}
+ */
+function buildNormalizedEvent(kind, payload, raw, rawType, observed = false) {
+    return { kind, payload, raw, rawType, observed };
+}
+
+/**
+ * @param {any} parsed
+ * @param {string} rawType
+ * @param {MappedStructuredEvent} mapped
+ * @returns {NormalizedTraceBatch}
+ */
+function normalizeMappedEvent(parsed, rawType, mapped) {
+    return {
+        events: [buildNormalizedEvent(mapped.kind, extractMappedPayload(parsed, mapped.payloadKind), parsed, rawType)],
+        expectedKinds: mapped.expect ? [mapped.expect] : undefined,
+    };
+}
+
+/**
+ * @param {any} parsed
+ * @param {string} rawType
+ * @returns {NormalizedTraceBatch | null}
+ */
+function normalizeClaudeStructuredEvent(parsed, rawType) {
+    if (rawType === "assistant") {
+        const text = extractGenericMessageText(parsed?.message ?? parsed);
+        const events = text
+            ? [buildNormalizedEvent("message.update", extractGenericMessagePayload(parsed?.message ?? parsed), parsed, rawType)]
+            : [buildNormalizedEvent("stdout", { eventType: rawType }, parsed, rawType, true)];
+        const usage = normalizeTokenUsage(parsed?.message?.usage);
+        if (usage) events.push(buildNormalizedEvent("usage", usage, parsed, rawType));
+        return { events };
+    }
+    if (rawType === "result") {
+        /** @type {NormalizedTraceEvent[]} */
+        const events = [];
+        const usage = normalizeTokenUsage(parsed?.usage);
+        if (usage) events.push(buildNormalizedEvent("usage", usage, parsed, rawType));
+        const text = extractGenericMessageText(parsed);
+        if (text) {
+            events.push(buildNormalizedEvent("assistant.message.final", { text }, parsed, rawType));
+        }
+        return events.length > 0 ? { events } : null;
+    }
+    return null;
+}
+
+/**
+ * @param {any} parsed
+ * @param {string} rawType
+ * @returns {NormalizedTraceBatch | null}
+ */
+function normalizeGeminiStructuredEvent(parsed, rawType) {
+    if (rawType === "message") {
+        const text = extractGenericMessageText(parsed);
+        if (parsed?.role === "assistant" && typeof text === "string" && text) {
+            return {
+                events: [
+                    buildNormalizedEvent(parsed?.delta ? "assistant.text.delta" : "assistant.message.final", { text }, parsed, rawType),
+                ],
+            };
+        }
+    }
+    if (rawType === "result" && parsed?.stats) {
+        const usage = normalizeTokenUsage(parsed.stats);
+        return usage ? { events: [buildNormalizedEvent("usage", usage, parsed, rawType)] } : null;
+    }
+    return null;
+}
+
+/**
+ * @param {any} parsed
+ * @param {string} rawType
+ * @returns {NormalizedTraceBatch | null}
+ */
+function normalizeCodexStructuredEvent(parsed, rawType) {
+    if (rawType === "thread.started") {
+        return { events: [buildNormalizedEvent("stdout", { eventType: rawType }, parsed, rawType, true)] };
+    }
+    if (rawType === "turn.started") {
+        return { events: [buildNormalizedEvent("turn.start", {}, parsed, rawType)], expectedKinds: ["turn.end"] };
+    }
+    if (rawType === "item.completed" && parsed?.item?.type === "agent_message") {
+        const text = extractGenericMessageText(parsed.item);
+        if (typeof text === "string" && text) {
+            return { events: [buildNormalizedEvent("assistant.message.final", { text }, parsed, rawType)] };
+        }
+    }
+    if (rawType === "turn.completed") {
+        /** @type {NormalizedTraceEvent[]} */
+        const events = [];
+        const usage = normalizeTokenUsage(parsed?.usage);
+        if (usage) events.push(buildNormalizedEvent("usage", usage, parsed, rawType));
+        events.push(buildNormalizedEvent("turn.end", {}, parsed, rawType));
+        const text = extractGenericMessageText(parsed);
+        if (text) {
+            events.push(buildNormalizedEvent("assistant.message.final", { text }, parsed, rawType));
+        }
+        return { events };
+    }
+    return null;
+}
+
+/**
+ * @param {any} parsed
+ * @param {string} rawType
+ * @returns {NormalizedTraceBatch | null}
+ */
+function normalizePiStructuredEvent(parsed, rawType) {
+    const simple = piSimpleEventMap[rawType];
+    if (simple) return normalizeMappedEvent(parsed, rawType, simple);
+    if (rawType === "turn_end") {
+        /** @type {NormalizedTraceEvent[]} */
+        const events = [buildNormalizedEvent("turn.end", extractPiPayload(parsed), parsed, rawType)];
+        const text = extractGenericMessageText(parsed?.message);
+        if (text) {
+            events.push(buildNormalizedEvent("assistant.message.final", { text }, parsed?.message, rawType));
+        }
+        const usage = normalizeTokenUsage(parsed?.message?.usage);
+        if (usage) events.push(buildNormalizedEvent("usage", usage, parsed.message.usage, "usage"));
+        return { events };
+    }
+    if (rawType === "message_end") {
+        /** @type {NormalizedTraceEvent[]} */
+        const events = [buildNormalizedEvent("message.end", extractPiPayload(parsed), parsed, rawType)];
+        const text = extractGenericMessageText(parsed?.message);
+        if (parsed?.message?.role === "assistant" && text) {
+            events.push(buildNormalizedEvent("assistant.message.final", { text }, parsed?.message, rawType));
+        }
+        return { events };
+    }
+    if (rawType === "message_update") {
+        const evt = parsed?.assistantMessageEvent;
+        if (evt?.type === "text_delta" && typeof evt.delta === "string") {
+            return { events: [buildNormalizedEvent("assistant.text.delta", { text: evt.delta }, parsed, evt.type)] };
+        }
+        if ((evt?.type === "thinking_delta" || evt?.type === "reasoning_delta") && typeof evt.delta === "string") {
+            return { events: [buildNormalizedEvent("assistant.thinking.delta", { text: evt.delta }, parsed, evt.type)] };
+        }
+        return { events: [buildNormalizedEvent("message.update", extractPiPayload(parsed), parsed, rawType)] };
+    }
+    return { events: [buildNormalizedEvent("stdout", { eventType: rawType }, parsed, rawType, true)] };
+}
+
+/**
+ * @param {any} parsed
+ * @param {string} rawType
+ * @returns {NormalizedTraceBatch | null}
+ */
+function normalizeSharedStructuredEvent(parsed, rawType) {
+    const mapped = genericStructuredEventMap[rawType];
+    if (mapped) return normalizeMappedEvent(parsed, rawType, mapped);
+    if ([
+        "message_delta",
+        "assistant_message.delta",
+        "assistant_message_delta",
+        "response.output_text.delta",
+        "content_block_delta",
+    ].includes(rawType)) {
+        const text = extractGenericDeltaText(parsed);
+        if (typeof text === "string" && text) {
+            return { events: [buildNormalizedEvent("assistant.text.delta", { text }, parsed, rawType)] };
+        }
+    }
+    if ([
+        "thinking_delta",
+        "reasoning_delta",
+        "response.reasoning.delta",
+    ].includes(rawType)) {
+        const text = extractGenericDeltaText(parsed);
+        if (typeof text === "string" && text) {
+            return { events: [buildNormalizedEvent("assistant.thinking.delta", { text }, parsed, rawType)] };
+        }
+    }
+    if ([
+        "message_end",
+        "assistant_message_end",
+        "response.completed",
+        "message_stop",
+    ].includes(rawType)) {
+        /** @type {NormalizedTraceEvent[]} */
+        const events = [buildNormalizedEvent("message.end", extractGenericMessagePayload(parsed), parsed, rawType)];
+        const text = extractGenericMessageText(parsed);
+        if (text) {
+            events.push(buildNormalizedEvent("assistant.message.final", { text }, parsed, rawType));
+        }
+        const usage = normalizeTokenUsage(parsed?.usage);
+        if (usage) events.push(buildNormalizedEvent("usage", usage, parsed, rawType));
+        return { events };
+    }
+    return null;
+}
+
+/**
+ * @param {AgentFamily} agentFamily
+ * @param {any} parsed
+ * @param {string} rawType
+ * @returns {NormalizedTraceBatch}
+ */
+export function normalizeStructuredEventForFamily(agentFamily, parsed, rawType) {
+    if (agentFamily === "pi") {
+        return normalizePiStructuredEvent(parsed, rawType) ?? {
+            events: [buildNormalizedEvent("stdout", { eventType: rawType }, parsed, rawType, true)],
+        };
+    }
+    if (agentFamily === "claude-code") {
+        const normalized = normalizeClaudeStructuredEvent(parsed, rawType);
+        if (normalized) return normalized;
+    }
+    if (agentFamily === "gemini") {
+        const normalized = normalizeGeminiStructuredEvent(parsed, rawType);
+        if (normalized) return normalized;
+    }
+    if (agentFamily === "codex") {
+        const normalized = normalizeCodexStructuredEvent(parsed, rawType);
+        if (normalized) return normalized;
+    }
+    const shared = normalizeSharedStructuredEvent(parsed, rawType);
+    if (shared) return shared;
+    return { events: [buildNormalizedEvent("stdout", { eventType: rawType }, parsed, rawType, true)] };
+}
+
+/**
+ * @param {AgentFamily} agentFamily
+ * @param {any} parsed
+ * @returns {{ sessionId?: string; threadId?: string }}
+ */
+export function extractProviderSessionCorrelation(agentFamily, parsed) {
+    if (agentFamily === "codex") {
+        const threadId = typeof parsed?.thread_id === "string" ? parsed.thread_id : undefined;
+        return { threadId };
+    }
+    const sessionId = typeof parsed?.session_id === "string"
+        ? parsed.session_id
+        : typeof parsed?.sessionId === "string"
+            ? parsed.sessionId
+            : agentFamily === "pi" && typeof parsed?.id === "string"
+                ? parsed.id
+                : undefined;
+    return { sessionId };
+}

package/src/_traceRedaction.js

@@ -0,0 +1,62 @@
+/**
+ * @typedef {{ value: unknown; applied: boolean; ruleIds: string[] }} RedactionResult
+ */
+
+/** @type {Array<{ id: string; pattern: RegExp; replace: string }>} */
+const rules = [
+    {
+        id: "api-key",
+        pattern: /\b(?:sk|pk)_[A-Za-z0-9_-]{8,}\b/g,
+        replace: "[REDACTED_API_KEY]",
+    },
+    {
+        id: "bearer-token",
+        pattern: /Bearer\s+[A-Za-z0-9._-]{8,}/gi,
+        replace: "Bearer [REDACTED_TOKEN]",
+    },
+    {
+        id: "auth-header",
+        pattern: /"authorization"\s*:\s*"[^"]+"/gi,
+        replace: '"authorization":"[REDACTED]"',
+    },
+    {
+        id: "cookie-header",
+        pattern: /"cookie"\s*:\s*"[^"]+"/gi,
+        replace: '"cookie":"[REDACTED]"',
+    },
+    {
+        id: "secret-ish",
+        pattern: /\b(?:api[_-]?key|token|secret|password)=([^\s"']+)/gi,
+        replace: "",
+    },
+];
+
+/**
+ * @param {unknown} value
+ * @returns {RedactionResult}
+ */
+export function redactValue(value) {
+    const input = typeof value === "string" ? value : JSON.stringify(value ?? null);
+    let next = input;
+    /** @type {Set<string>} */
+    const applied = new Set();
+    for (const rule of rules) {
+        next = next.replace(rule.pattern, (match) => {
+            applied.add(rule.id);
+            if (rule.id === "secret-ish") {
+                const idx = match.indexOf("=");
+                return `${match.slice(0, idx + 1)}[REDACTED_SECRET]`;
+            }
+            return rule.replace;
+        });
+    }
+    if (applied.size === 0) return { value, applied: false, ruleIds: [] };
+    if (typeof value === "string") {
+        return { value: next, applied: true, ruleIds: [...applied] };
+    }
+    try {
+        return { value: JSON.parse(next), applied: true, ruleIds: [...applied] };
+    } catch {
+        return { value: next, applied: true, ruleIds: [...applied] };
+    }
+}

package/src/agentSessionEventToOtelLogRecord.js

@@ -0,0 +1,52 @@
+import {
+    buildOtelAttributes,
+    buildOtelLogRecord,
+    inferSessionSeverity,
+} from "./_otelLogBuilders.js";
+/**
+ * @typedef {import('./agentTrace.ts').AgentSessionTranscriptEvent} AgentSessionTranscriptEvent
+ * @typedef {import('./_otelLogBuilders.js').OtelLogRecord} OtelLogRecord
+ */
+
+/**
+ * @param {AgentSessionTranscriptEvent} event
+ * @param {{ agentId?: string; model?: string }} [context]
+ * @returns {OtelLogRecord}
+ */
+export function agentSessionEventToOtelLogRecord(event, context) {
+    const attributes = buildOtelAttributes({
+        "smithers.event.category": "agent-session",
+        "smithers.trace.version": undefined,
+        "smithers.transcript.version": event.transcriptVersion,
+        "run.id": event.runId,
+        "workflow.path": event.workflowPath,
+        "workflow.hash": event.workflowHash,
+        "node.id": event.nodeId,
+        "node.iteration": event.iteration,
+        "node.attempt": event.attempt,
+        "agent.family": event.source.agentFamily,
+        "agent.id": context?.agentId,
+        "agent.model": context?.model,
+        "agent.capture_mode": event.source.captureMode,
+        "trace.completeness": undefined,
+        "event.kind": undefined,
+        "event.phase": undefined,
+        "event.sequence": undefined,
+        "source.raw_type": undefined,
+        "source.raw_event_id": undefined,
+        "source.observed": undefined,
+        "provider.session_id": event.source.providerSessionId,
+        "provider.thread_id": event.source.providerThreadId,
+        "session.ingest_source": event.source.ingestSource,
+        "session.observed_live": event.source.observedLive,
+        "session.row_type": event.event.rowType,
+        "session.row_sequence": event.event.sequence,
+    }, event.annotations);
+    return buildOtelLogRecord({
+        category: "agent-session",
+        payload: undefined,
+        raw: event.raw,
+        redaction: event.redaction,
+        annotations: event.annotations,
+    }, attributes, inferSessionSeverity(event.raw));
+}

package/src/agentTrace.ts

@@ -0,0 +1,154 @@
+export type AgentFamily =
+  | "pi"
+  | "codex"
+  | "claude-code"
+  | "gemini"
+  | "kimi"
+  | "openai"
+  | "anthropic"
+  | "amp"
+  | "forge"
+  | "unknown";
+
+export type AgentCaptureMode =
+  | "sdk-events"
+  | "rpc-events"
+  | "cli-json-stream"
+  | "cli-json"
+  | "cli-text"
+  | "artifact-import";
+
+export type TraceCompleteness =
+  | "full-observed"
+  | "partial-observed"
+  | "final-only"
+  | "capture-failed";
+
+export type CanonicalAgentTraceEventKind =
+  | "session.start"
+  | "session.end"
+  | "turn.start"
+  | "turn.end"
+  | "message.start"
+  | "message.update"
+  | "message.end"
+  | "assistant.text.delta"
+  | "assistant.thinking.delta"
+  | "assistant.message.final"
+  | "tool.execution.start"
+  | "tool.execution.update"
+  | "tool.execution.end"
+  | "tool.result"
+  | "retry.start"
+  | "retry.end"
+  | "compaction.start"
+  | "compaction.end"
+  | "stderr"
+  | "stdout"
+  | "usage"
+  | "capture.warning"
+  | "capture.error"
+  | "artifact.created";
+
+export type CanonicalAgentTraceEventPhase =
+  | "agent"
+  | "turn"
+  | "message"
+  | "tool"
+  | "session"
+  | "capture"
+  | "artifact";
+
+export type CanonicalAgentTraceEvent = {
+  traceVersion: "1";
+  runId: string;
+  workflowPath?: string;
+  workflowHash?: string;
+  nodeId: string;
+  iteration: number;
+  attempt: number;
+  timestampMs: number;
+  event: {
+    sequence: number;
+    kind: CanonicalAgentTraceEventKind;
+    phase: CanonicalAgentTraceEventPhase;
+  };
+  source: {
+    agentFamily: AgentFamily;
+    captureMode: AgentCaptureMode;
+    rawType?: string;
+    rawEventId?: string;
+    observed: boolean;
+  };
+  traceCompleteness: TraceCompleteness;
+  payload: Record<string, unknown> | null;
+  raw: unknown;
+  redaction: {
+    applied: boolean;
+    ruleIds: string[];
+  };
+  annotations: Record<string, string | number | boolean>;
+};
+
+export type AgentTraceSummary = {
+  traceVersion: "1";
+  runId: string;
+  workflowPath?: string;
+  workflowHash?: string;
+  nodeId: string;
+  iteration: number;
+  attempt: number;
+  traceStartedAtMs: number;
+  traceFinishedAtMs: number;
+  agentFamily: AgentFamily;
+  agentId?: string;
+  model?: string;
+  captureMode: AgentCaptureMode;
+  traceCompleteness: TraceCompleteness;
+  unsupportedEventKinds: CanonicalAgentTraceEventKind[];
+  missingExpectedEventKinds: CanonicalAgentTraceEventKind[];
+  rawArtifactRefs: string[];
+};
+
+export type AgentSessionTranscriptEvent = {
+  transcriptVersion: "1";
+  runId: string;
+  workflowPath?: string;
+  workflowHash?: string;
+  nodeId: string;
+  iteration: number;
+  attempt: number;
+  timestampMs: number;
+  event: {
+    sequence: number;
+    rowType: string;
+  };
+  source: {
+    agentFamily: AgentFamily;
+    captureMode: AgentCaptureMode;
+    ingestSource: "live" | "artifact";
+    observedLive: boolean;
+    providerSessionId?: string;
+    providerThreadId?: string;
+  };
+  raw: unknown;
+  redaction: {
+    applied: boolean;
+    ruleIds: string[];
+  };
+  annotations: Record<string, string | number | boolean>;
+};
+
+export type AgentTraceCapabilityProfile = {
+  sessionMetadata: boolean;
+  assistantTextDeltas: boolean;
+  visibleThinkingDeltas: boolean;
+  finalAssistantMessage: boolean;
+  toolExecutionStart: boolean;
+  toolExecutionUpdate: boolean;
+  toolExecutionEnd: boolean;
+  retryEvents: boolean;
+  compactionEvents: boolean;
+  rawStderrDiagnostics: boolean;
+  persistedSessionArtifact: boolean;
+};