@smithers-orchestrator/observability 0.19.0 → 0.20.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithers-orchestrator/observability",
-  "version": "0.19.0",
+  "version": "0.20.1",
   "description": "Concrete Smithers metrics, logging, tracing, and observability integrations",
   "type": "module",
   "sideEffects": false,
@@ -29,12 +29,12 @@
     "@effect/platform": "^0.96.0",
     "@effect/platform-bun": "^0.89.0",
     "effect": "^3.21.1",
-    "@smithers-orchestrator/driver": "0.19.0",
-    "@smithers-orchestrator/openapi": "0.19.0",
-    "@smithers-orchestrator/agents": "0.19.0",
-    "@smithers-orchestrator/scorers": "0.19.0",
-    "@smithers-orchestrator/memory": "0.19.0",
-    "@smithers-orchestrator/time-travel": "0.19.0"
+    "@smithers-orchestrator/agents": "0.20.1",
+    "@smithers-orchestrator/driver": "0.20.1",
+    "@smithers-orchestrator/memory": "0.20.1",
+    "@smithers-orchestrator/scorers": "0.20.1",
+    "@smithers-orchestrator/openapi": "0.20.1",
+    "@smithers-orchestrator/time-travel": "0.20.1"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/SmithersEvent.ts

@@ -1,3 +1,9 @@
+import type {
+  AgentSessionTranscriptEvent,
+  AgentTraceSummary,
+  CanonicalAgentTraceEvent,
+} from "./agentTrace";
+
 type RunStatus =
   | "running"
   | "waiting-approval"
@@ -351,6 +357,7 @@ export type SmithersEvent =
       nodeId: string;
       iteration: number;
       attempt: number;
+      toolCallId: string;
       toolName: string;
       seq: number;
       timestampMs: number;
@@ -361,6 +368,7 @@ export type SmithersEvent =
       nodeId: string;
       iteration: number;
       attempt: number;
+      toolCallId: string;
       toolName: string;
       seq: number;
       status: "success" | "error";
@@ -600,4 +608,31 @@ export type SmithersEvent =
       runId: string;
       timerId: string;
       timestampMs: number;
+    }
+  | {
+      type: "AgentTraceEvent";
+      runId: string;
+      nodeId: string;
+      iteration: number;
+      attempt: number;
+      trace: CanonicalAgentTraceEvent;
+      timestampMs: number;
+    }
+  | {
+      type: "AgentTraceSummary";
+      runId: string;
+      nodeId: string;
+      iteration: number;
+      attempt: number;
+      summary: AgentTraceSummary;
+      timestampMs: number;
+    }
+  | {
+      type: "AgentSessionEvent";
+      runId: string;
+      nodeId: string;
+      iteration: number;
+      attempt: number;
+      transcript: AgentSessionTranscriptEvent;
+      timestampMs: number;
     };

package/src/_otelLogBuilders.js

@@ -0,0 +1,94 @@
+/**
+ * @typedef {"INFO" | "WARN" | "ERROR"} OtelLogSeverity
+ *
+ * @typedef {{
+ *   body: string;
+ *   attributes: Record<string, unknown>;
+ *   severity: OtelLogSeverity;
+ * }} OtelLogRecord
+ *
+ * @typedef {import('./agentTrace.ts').CanonicalAgentTraceEvent} CanonicalAgentTraceEvent
+ */
+
+/**
+ * @param {Record<string, unknown>} base
+ * @param {Record<string, string | number | boolean>} annotations
+ * @returns {Record<string, unknown>}
+ */
+export function buildOtelAttributes(base, annotations) {
+    /** @type {Record<string, unknown>} */
+    const attributes = {};
+    for (const [key, value] of Object.entries(base)) {
+        if (value !== undefined) attributes[key] = value;
+    }
+    for (const [key, value] of Object.entries(annotations)) {
+        attributes[key.startsWith("custom.") ? key : `custom.${key}`] = value;
+    }
+    return attributes;
+}
+
+/**
+ * @param {{
+ *   category: "agent-trace" | "agent-session";
+ *   payload: unknown;
+ *   raw: unknown;
+ *   redaction: { applied: boolean; ruleIds: string[] };
+ *   annotations: Record<string, string | number | boolean>;
+ * }} body
+ * @param {Record<string, unknown>} attributes
+ * @param {OtelLogSeverity} severity
+ * @returns {OtelLogRecord}
+ */
+export function buildOtelLogRecord(body, attributes, severity) {
+    return {
+        body: JSON.stringify({
+            category: body.category,
+            payload: body.payload,
+            raw: body.raw,
+            redaction: body.redaction,
+            annotations: body.annotations,
+        }),
+        attributes,
+        severity,
+    };
+}
+
+/**
+ * @param {CanonicalAgentTraceEvent} event
+ * @returns {OtelLogSeverity}
+ */
+export function inferCanonicalSeverity(event) {
+    return event.event.kind === "capture.error"
+        ? "ERROR"
+        : event.event.kind === "capture.warning" || event.event.kind === "stderr"
+            ? "WARN"
+            : "INFO";
+}
+
+/**
+ * @param {unknown} raw
+ * @returns {OtelLogSeverity}
+ */
+export function inferSessionSeverity(raw) {
+    const row = /** @type {any} */ (raw);
+    const rowType = String(row?.type ?? "").toLowerCase();
+    if (row?.is_error === true ||
+        row?.isError === true ||
+        row?.error ||
+        row?.errorMessage ||
+        row?.message?.stopReason === "error" ||
+        row?.message?.errorMessage ||
+        rowType.includes("error")) {
+        return "ERROR";
+    }
+    if (rowType.includes("warning")) return "WARN";
+    return "INFO";
+}
+
+/**
+ * @param {CanonicalAgentTraceEvent} event
+ * @returns {boolean}
+ */
+export function shouldExportTraceEventToOtel(event) {
+    return event.event.kind !== "artifact.created";
+}

package/src/_sessionFileResolvers.js

@@ -0,0 +1,146 @@
+import { readFile, readdir, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * @param {string} dir
+ * @returns {Promise<string[]>}
+ */
+async function listJsonlFiles(dir) {
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        const nested = await Promise.all(entries.map(async (entry) => {
+            const path = join(dir, entry.name);
+            if (entry.isDirectory()) return listJsonlFiles(path);
+            return entry.isFile() && path.endsWith(".jsonl") ? [path] : [];
+        }));
+        return nested.flat();
+    } catch {
+        return [];
+    }
+}
+
+/**
+ * @param {any} agent
+ * @returns {string[]}
+ */
+function buildCodexSessionRoots(agent) {
+    const custom = agent?.opts?.sessionDir ?? agent?.opts?.codexSessionDir;
+    if (typeof custom === "string" && custom) return [custom];
+    if (String(agent?.constructor?.name ?? "") !== "CodexAgent") return [];
+    return [join(homedir(), ".codex", "sessions")];
+}
+
+/**
+ * @param {any} agent
+ * @returns {string[]}
+ */
+function buildClaudeSessionRoots(agent) {
+    const custom = agent?.opts?.sessionDir ??
+        agent?.opts?.claudeProjectsDir ??
+        agent?.opts?.projectsDir;
+    if (typeof custom === "string" && custom) return [custom];
+    if (String(agent?.constructor?.name ?? "") !== "ClaudeCodeAgent") return [];
+    return [join(homedir(), ".claude", "projects")];
+}
+
+/**
+ * @param {any} agent
+ * @returns {string[]}
+ */
+function buildPiSessionRoots(agent) {
+    if (typeof agent?.opts?.session === "string" && agent.opts.session) {
+        return [agent.opts.session];
+    }
+    const custom = agent?.opts?.sessionDir;
+    if (typeof custom === "string" && custom) return [custom];
+    if (String(agent?.constructor?.name ?? "") !== "PiAgent") return [];
+    return [join(homedir(), ".pi", "agent", "sessions")];
+}
+
+/**
+ * @param {string} cwd
+ * @returns {string}
+ */
+function sanitizeClaudeProjectPath(cwd) {
+    return cwd.replace(/[\\/]/g, "-");
+}
+
+/**
+ * @param {unknown} sessionCwd
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+function isCorrelatedSessionCwd(sessionCwd, cwd) {
+    if (typeof sessionCwd !== "string" || !sessionCwd) return false;
+    return (sessionCwd === cwd ||
+        sessionCwd.startsWith(`${cwd}/`) ||
+        cwd.startsWith(`${sessionCwd}/`));
+}
+
+/**
+ * @param {any} agent
+ * @param {string} [sessionId]
+ * @returns {Promise<string | null>}
+ */
+export async function resolvePiSessionFile(agent, sessionId) {
+    if (typeof agent?.opts?.session === "string" && agent.opts.session) {
+        return agent.opts.session;
+    }
+    if (!sessionId) return null;
+    for (const root of buildPiSessionRoots(agent)) {
+        const files = await listJsonlFiles(root);
+        const match = files.find((file) => file.includes(sessionId));
+        if (match) return match;
+    }
+    return null;
+}
+
+/**
+ * @param {any} agent
+ * @param {string} cwd
+ * @param {string} [sessionId]
+ * @returns {Promise<string | null>}
+ */
+export async function resolveClaudeSessionFile(agent, cwd, sessionId) {
+    if (!sessionId) return null;
+    for (const root of buildClaudeSessionRoots(agent)) {
+        const direct = join(root, sanitizeClaudeProjectPath(cwd), `${sessionId}.jsonl`);
+        try {
+            const info = await stat(direct);
+            if (info.isFile()) return direct;
+        } catch {}
+        const files = await listJsonlFiles(root);
+        const match = files.find((file) => file.endsWith(`/${sessionId}.jsonl`));
+        if (match) return match;
+    }
+    return null;
+}
+
+/**
+ * @param {any} agent
+ * @param {string} cwd
+ * @param {number} startedAtMs
+ * @returns {Promise<string | null>}
+ */
+export async function resolveCodexSessionFile(agent, cwd, startedAtMs) {
+    const day = new Date(startedAtMs);
+    const dayRoots = buildCodexSessionRoots(agent).map((root) => join(root, String(day.getUTCFullYear()), String(day.getUTCMonth() + 1).padStart(2, "0"), String(day.getUTCDate()).padStart(2, "0")));
+    const candidates = (await Promise.all(dayRoots.map((root) => listJsonlFiles(root)))).flat();
+    /** @type {{ file: string; delta: number } | null} */
+    let best = null;
+    for (const file of candidates) {
+        try {
+            const firstLine = (await readFile(file, "utf8")).split(/\r?\n/, 1)[0];
+            if (!firstLine) continue;
+            const parsed = JSON.parse(firstLine);
+            if (parsed?.type !== "session_meta") continue;
+            const sessionCwd = parsed?.payload?.cwd;
+            const sessionTs = Date.parse(String(parsed?.payload?.timestamp ?? parsed?.timestamp ?? ""));
+            if (!isCorrelatedSessionCwd(sessionCwd, cwd) || !Number.isFinite(sessionTs)) continue;
+            const delta = Math.abs(sessionTs - startedAtMs);
+            if (!best || delta < best.delta) best = { file, delta };
+        } catch {}
+    }
+    return best?.file ?? null;
+}