@smithers-orchestrator/observability 0.20.0 → 0.20.1

package/src/agentTraceCapabilities.js

@@ -0,0 +1,138 @@
+/**
+ * @typedef {import('./agentTrace.ts').AgentFamily} AgentFamily
+ * @typedef {import('./agentTrace.ts').AgentTraceCapabilityProfile} AgentTraceCapabilityProfile
+ */
+
+/** @type {Record<AgentFamily, AgentTraceCapabilityProfile>} */
+export const agentTraceCapabilities = {
+    pi: {
+        sessionMetadata: true,
+        assistantTextDeltas: true,
+        visibleThinkingDeltas: true,
+        finalAssistantMessage: true,
+        toolExecutionStart: true,
+        toolExecutionUpdate: true,
+        toolExecutionEnd: true,
+        retryEvents: true,
+        compactionEvents: true,
+        rawStderrDiagnostics: true,
+        persistedSessionArtifact: true,
+    },
+    codex: {
+        sessionMetadata: false,
+        assistantTextDeltas: false,
+        visibleThinkingDeltas: false,
+        finalAssistantMessage: true,
+        toolExecutionStart: false,
+        toolExecutionUpdate: false,
+        toolExecutionEnd: false,
+        retryEvents: false,
+        compactionEvents: false,
+        rawStderrDiagnostics: true,
+        persistedSessionArtifact: false,
+    },
+    "claude-code": {
+        sessionMetadata: false,
+        assistantTextDeltas: true,
+        visibleThinkingDeltas: false,
+        finalAssistantMessage: true,
+        toolExecutionStart: false,
+        toolExecutionUpdate: false,
+        toolExecutionEnd: false,
+        retryEvents: false,
+        compactionEvents: false,
+        rawStderrDiagnostics: true,
+        persistedSessionArtifact: false,
+    },
+    gemini: {
+        sessionMetadata: false,
+        assistantTextDeltas: false,
+        visibleThinkingDeltas: false,
+        finalAssistantMessage: true,
+        toolExecutionStart: false,
+        toolExecutionUpdate: false,
+        toolExecutionEnd: false,
+        retryEvents: false,
+        compactionEvents: false,
+        rawStderrDiagnostics: true,
+        persistedSessionArtifact: false,
+    },
+    kimi: {
+        sessionMetadata: false,
+        assistantTextDeltas: false,
+        visibleThinkingDeltas: false,
+        finalAssistantMessage: true,
+        toolExecutionStart: false,
+        toolExecutionUpdate: false,
+        toolExecutionEnd: false,
+        retryEvents: false,
+        compactionEvents: false,
+        rawStderrDiagnostics: true,
+        persistedSessionArtifact: false,
+    },
+    openai: {
+        sessionMetadata: false,
+        assistantTextDeltas: false,
+        visibleThinkingDeltas: false,
+        finalAssistantMessage: true,
+        toolExecutionStart: true,
+        toolExecutionUpdate: false,
+        toolExecutionEnd: true,
+        retryEvents: false,
+        compactionEvents: false,
+        rawStderrDiagnostics: false,
+        persistedSessionArtifact: false,
+    },
+    anthropic: {
+        sessionMetadata: false,
+        assistantTextDeltas: false,
+        visibleThinkingDeltas: false,
+        finalAssistantMessage: true,
+        toolExecutionStart: true,
+        toolExecutionUpdate: false,
+        toolExecutionEnd: true,
+        retryEvents: false,
+        compactionEvents: false,
+        rawStderrDiagnostics: false,
+        persistedSessionArtifact: false,
+    },
+    amp: {
+        sessionMetadata: false,
+        assistantTextDeltas: false,
+        visibleThinkingDeltas: false,
+        finalAssistantMessage: true,
+        toolExecutionStart: true,
+        toolExecutionUpdate: false,
+        toolExecutionEnd: true,
+        retryEvents: false,
+        compactionEvents: false,
+        rawStderrDiagnostics: true,
+        persistedSessionArtifact: false,
+    },
+    forge: {
+        sessionMetadata: false,
+        assistantTextDeltas: false,
+        visibleThinkingDeltas: false,
+        finalAssistantMessage: true,
+        toolExecutionStart: true,
+        toolExecutionUpdate: false,
+        toolExecutionEnd: true,
+        retryEvents: false,
+        compactionEvents: false,
+        rawStderrDiagnostics: true,
+        persistedSessionArtifact: false,
+    },
+    unknown: {
+        sessionMetadata: false,
+        assistantTextDeltas: false,
+        visibleThinkingDeltas: false,
+        finalAssistantMessage: true,
+        toolExecutionStart: true,
+        toolExecutionUpdate: false,
+        toolExecutionEnd: true,
+        retryEvents: false,
+        compactionEvents: false,
+        rawStderrDiagnostics: true,
+        persistedSessionArtifact: false,
+    },
+};

package/src/canonicalTraceEventToOtelLogRecord.js

@@ -0,0 +1,52 @@
+import {
+    buildOtelAttributes,
+    buildOtelLogRecord,
+    inferCanonicalSeverity,
+} from "./_otelLogBuilders.js";
+/**
+ * @typedef {import('./agentTrace.ts').CanonicalAgentTraceEvent} CanonicalAgentTraceEvent
+ * @typedef {import('./_otelLogBuilders.js').OtelLogRecord} OtelLogRecord
+ */
+
+/**
+ * @param {CanonicalAgentTraceEvent} event
+ * @param {{ agentId?: string; model?: string }} [context]
+ * @returns {OtelLogRecord}
+ */
+export function canonicalTraceEventToOtelLogRecord(event, context) {
+    const attributes = buildOtelAttributes({
+        "smithers.event.category": "agent-trace",
+        "smithers.trace.version": event.traceVersion,
+        "smithers.transcript.version": undefined,
+        "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": event.traceCompleteness,
+        "event.kind": event.event.kind,
+        "event.phase": event.event.phase,
+        "event.sequence": event.event.sequence,
+        "source.raw_type": event.source.rawType,
+        "source.raw_event_id": event.source.rawEventId,
+        "source.observed": event.source.observed,
+        "session.row_type": undefined,
+        "session.row_sequence": undefined,
+        "session.ingest_source": undefined,
+        "session.observed_live": undefined,
+        "provider.session_id": undefined,
+        "provider.thread_id": undefined,
+    }, event.annotations);
+    return buildOtelLogRecord({
+        category: "agent-trace",
+        payload: event.payload,
+        raw: event.raw,
+        redaction: event.redaction,
+        annotations: event.annotations,
+    }, attributes, inferCanonicalSeverity(event));
+}

package/src/detectAgentFamily.js

@@ -0,0 +1,28 @@
+/**
+ * @typedef {import('./agentTrace.ts').AgentFamily} AgentFamily
+ */
+
+/**
+ * @param {any} agent
+ * @returns {AgentFamily}
+ */
+export function detectAgentFamily(agent) {
+    const constructorName = String(agent?.constructor?.name ?? "").toLowerCase();
+    const idName = String(agent?.id ?? "").toLowerCase();
+    const name = constructorName && constructorName !== "object"
+        ? `${constructorName} ${idName}`
+        : idName;
+    if (name.includes("codex")) return "codex";
+    if (name.includes("claude")) return "claude-code";
+    if (name.includes("gemini")) return "gemini";
+    if (name.includes("kimi")) return "kimi";
+    if (name.includes("openai")) return "openai";
+    if (name.includes("anthropic")) return "anthropic";
+    if (name.includes("amp")) return "amp";
+    if (name.includes("forge")) return "forge";
+    if (constructorName.includes("piagent") ||
+        /(?:^|[-_\s])pi(?:$|[-_\s])/.test(idName)) {
+        return "pi";
+    }
+    return "unknown";
+}

package/src/detectCaptureMode.js

@@ -0,0 +1,24 @@
+import { detectAgentFamily } from "./detectAgentFamily.js";
+/**
+ * @typedef {import('./agentTrace.ts').AgentCaptureMode} AgentCaptureMode
+ */
+
+/**
+ * @param {any} agent
+ * @returns {AgentCaptureMode}
+ */
+export function detectCaptureMode(agent) {
+    const family = detectAgentFamily(agent);
+    const mode = agent?.opts?.mode ?? agent?.mode;
+    if (family === "pi") {
+        if (mode === "rpc") return "rpc-events";
+        if (mode === "json") return "cli-json-stream";
+        return "cli-text";
+    }
+    if (family === "codex") return "cli-json-stream";
+    const outputFormat = agent?.opts?.outputFormat ?? agent?.outputFormat;
+    if (family === "openai" || family === "anthropic") return "sdk-events";
+    if (outputFormat === "stream-json") return "cli-json-stream";
+    if (outputFormat === "json" || agent?.opts?.json) return "cli-json";
+    return "cli-text";
+}

package/src/emitOtelLogRecord.js

@@ -0,0 +1,19 @@
+import { logErrorAwait, logInfoAwait, logWarningAwait } from "./logging.js";
+/**
+ * @typedef {import('./_otelLogBuilders.js').OtelLogRecord} OtelLogRecord
+ */
+
+/**
+ * @param {"agent-trace" | "agent-session"} category
+ * @param {OtelLogRecord} record
+ * @returns {Promise<void>}
+ */
+export async function emitOtelLogRecord(category, record) {
+    if (record.severity === "ERROR") {
+        await logErrorAwait(record.body, record.attributes, category);
+    } else if (record.severity === "WARN") {
+        await logWarningAwait(record.body, record.attributes, category);
+    } else {
+        await logInfoAwait(record.body, record.attributes, category);
+    }
+}

package/src/kindPhase.js

@@ -0,0 +1,17 @@
+/**
+ * @typedef {import('./agentTrace.ts').CanonicalAgentTraceEventKind} CanonicalAgentTraceEventKind
+ * @typedef {import('./agentTrace.ts').CanonicalAgentTraceEventPhase} CanonicalAgentTraceEventPhase
+ */
+
+/**
+ * @param {CanonicalAgentTraceEventKind} kind
+ * @returns {CanonicalAgentTraceEventPhase}
+ */
+export function kindPhase(kind) {
+    if (kind.startsWith("session.")) return "session";
+    if (kind.startsWith("turn.")) return "turn";
+    if (kind.startsWith("message.") || kind.startsWith("assistant.")) return "message";
+    if (kind.startsWith("tool.")) return "tool";
+    if (kind.startsWith("artifact.")) return "artifact";
+    return "capture";
+}

package/src/logging.js

@@ -35,10 +35,9 @@ const minLevel = resolveMinLevel();
  * @param {Effect.Effect<void, never, never>} effect
  * @param {LogAnnotations} [annotations]
  * @param {string} [span]
- * @param {number} [level]
+ * @returns {Effect.Effect<void, never, never> | null}
  */
-function emitLog(effect, annotations, span, level = LOG_LEVEL_INFO) {
-    if (level < minLevel) return;
+function buildLogProgram(effect, annotations, span) {
     const correlationAnnotations = correlationContextToLogAnnotations(getCurrentCorrelationContext());
     const traceAnnotations = getCurrentSmithersTraceAnnotations();
     const mergedAnnotations = correlationAnnotations || traceAnnotations || annotations
@@ -55,7 +54,32 @@ function emitLog(effect, annotations, span, level = LOG_LEVEL_INFO) {
     if (span) {
         program = program.pipe(Effect.withLogSpan(span));
     }
-    void Effect.runFork(withCurrentCorrelationContext(program));
+    return withCurrentCorrelationContext(program);
+}
+
+/**
+ * @param {Effect.Effect<void, never, never>} effect
+ * @param {LogAnnotations} [annotations]
+ * @param {string} [span]
+ * @param {number} [level]
+ */
+function emitLog(effect, annotations, span, level = LOG_LEVEL_INFO) {
+    if (level < minLevel) return;
+    const program = buildLogProgram(effect, annotations, span);
+    if (program) void Effect.runFork(program);
+}
+
+/**
+ * @param {Effect.Effect<void, never, never>} effect
+ * @param {LogAnnotations} [annotations]
+ * @param {string} [span]
+ * @param {number} [level]
+ * @returns {Promise<void>}
+ */
+async function emitLogAwait(effect, annotations, span, level = LOG_LEVEL_INFO) {
+    if (level < minLevel) return;
+    const program = buildLogProgram(effect, annotations, span);
+    if (program) await Effect.runPromise(program);
 }
 /**
  * @param {string} message
@@ -89,3 +113,39 @@ export function logWarning(message, annotations, span) {
 export function logError(message, annotations, span) {
     emitLog(Effect.logError(message), annotations, span, LOG_LEVEL_ERROR);
 }
+/**
+ * @param {string} message
+ * @param {LogAnnotations} [annotations]
+ * @param {string} [span]
+ * @returns {Promise<void>}
+ */
+export async function logDebugAwait(message, annotations, span) {
+    await emitLogAwait(Effect.logDebug(message), annotations, span, LOG_LEVEL_DEBUG);
+}
+/**
+ * @param {string} message
+ * @param {LogAnnotations} [annotations]
+ * @param {string} [span]
+ * @returns {Promise<void>}
+ */
+export async function logInfoAwait(message, annotations, span) {
+    await emitLogAwait(Effect.logInfo(message), annotations, span, LOG_LEVEL_INFO);
+}
+/**
+ * @param {string} message
+ * @param {LogAnnotations} [annotations]
+ * @param {string} [span]
+ * @returns {Promise<void>}
+ */
+export async function logWarningAwait(message, annotations, span) {
+    await emitLogAwait(Effect.logWarning(message), annotations, span, LOG_LEVEL_WARNING);
+}
+/**
+ * @param {string} message
+ * @param {LogAnnotations} [annotations]
+ * @param {string} [span]
+ * @returns {Promise<void>}
+ */
+export async function logErrorAwait(message, annotations, span) {
+    await emitLogAwait(Effect.logError(message), annotations, span, LOG_LEVEL_ERROR);
+}

package/src/normalizeStructuredEvent.js

@@ -0,0 +1,15 @@
+import { normalizeStructuredEventForFamily } from "./_traceEventNormalizers.js";
+/**
+ * @typedef {import('./agentTrace.ts').AgentFamily} AgentFamily
+ * @typedef {import('./_traceEventNormalizers.js').NormalizedTraceBatch} NormalizedTraceBatch
+ */
+
+/**
+ * @param {AgentFamily} agentFamily
+ * @param {any} parsed
+ * @param {string} rawType
+ * @returns {NormalizedTraceBatch}
+ */
+export function normalizeStructuredEvent(agentFamily, parsed, rawType) {
+    return normalizeStructuredEventForFamily(agentFamily, parsed, rawType);
+}

package/src/resolveAgentTraceCapabilities.js

@@ -0,0 +1,59 @@
+import { agentTraceCapabilities } from "./agentTraceCapabilities.js";
+/**
+ * @typedef {import('./agentTrace.ts').AgentFamily} AgentFamily
+ * @typedef {import('./agentTrace.ts').AgentCaptureMode} AgentCaptureMode
+ * @typedef {import('./agentTrace.ts').AgentTraceCapabilityProfile} AgentTraceCapabilityProfile
+ */
+
+/**
+ * @param {AgentFamily} agentFamily
+ * @param {AgentCaptureMode} captureMode
+ * @returns {AgentTraceCapabilityProfile}
+ */
+export function resolveAgentTraceCapabilities(agentFamily, captureMode) {
+    const base = {
+        ...agentTraceCapabilities[agentFamily],
+        // Smithers persists a canonical NDJSON trace artifact for every successful
+        // flush regardless of the upstream agent family.
+        persistedSessionArtifact: true,
+    };
+    if (captureMode === "sdk-events" || captureMode === "cli-text") {
+        return base;
+    }
+    if (agentFamily === "codex") {
+        return {
+            ...base,
+            assistantTextDeltas: captureMode === "cli-json-stream",
+            toolExecutionStart: captureMode === "cli-json-stream",
+            toolExecutionUpdate: captureMode === "cli-json-stream",
+            toolExecutionEnd: captureMode === "cli-json-stream",
+        };
+    }
+    if (agentFamily === "claude-code") {
+        return {
+            ...base,
+            toolExecutionStart: captureMode === "cli-json-stream",
+            toolExecutionUpdate: captureMode === "cli-json-stream",
+            toolExecutionEnd: captureMode === "cli-json-stream",
+        };
+    }
+    if (agentFamily === "gemini") {
+        return {
+            ...base,
+            assistantTextDeltas: captureMode === "cli-json-stream",
+            toolExecutionStart: captureMode === "cli-json-stream",
+            toolExecutionUpdate: captureMode === "cli-json-stream",
+            toolExecutionEnd: captureMode === "cli-json-stream",
+        };
+    }
+    if (agentFamily === "kimi") {
+        return {
+            ...base,
+            assistantTextDeltas: captureMode === "cli-json-stream",
+            toolExecutionStart: captureMode === "cli-json-stream",
+            toolExecutionUpdate: captureMode === "cli-json-stream",
+            toolExecutionEnd: captureMode === "cli-json-stream",
+        };
+    }
+    return base;
+}

package/src/unsupportedKindsForCapabilities.js

@@ -0,0 +1,32 @@
+/**
+ * @typedef {import('./agentTrace.ts').AgentTraceCapabilityProfile} AgentTraceCapabilityProfile
+ * @typedef {import('./agentTrace.ts').CanonicalAgentTraceEventKind} CanonicalAgentTraceEventKind
+ */
+
+/** @type {Array<[keyof AgentTraceCapabilityProfile, CanonicalAgentTraceEventKind[]]>} */
+const capabilityKindMap = [
+    ["sessionMetadata", ["session.start", "session.end"]],
+    ["assistantTextDeltas", ["assistant.text.delta"]],
+    ["visibleThinkingDeltas", ["assistant.thinking.delta"]],
+    ["finalAssistantMessage", ["assistant.message.final"]],
+    ["toolExecutionStart", ["tool.execution.start"]],
+    ["toolExecutionUpdate", ["tool.execution.update"]],
+    ["toolExecutionEnd", ["tool.execution.end", "tool.result"]],
+    ["retryEvents", ["retry.start", "retry.end"]],
+    ["compactionEvents", ["compaction.start", "compaction.end"]],
+    ["rawStderrDiagnostics", ["stderr"]],
+    ["persistedSessionArtifact", ["artifact.created"]],
+];
+
+/**
+ * @param {AgentTraceCapabilityProfile} profile
+ * @returns {CanonicalAgentTraceEventKind[]}
+ */
+export function unsupportedKindsForCapabilities(profile) {
+    /** @type {CanonicalAgentTraceEventKind[]} */
+    const kinds = [];
+    for (const [field, mappedKinds] of capabilityKindMap) {
+        if (!profile[field]) kinds.push(...mappedKinds);
+    }
+    return kinds;
+}