@smthrs/observability 0.33.0

package/src/_coreTracingShape.ts

@@ -0,0 +1,17 @@
+import type { Effect } from "effect";
+import type { CorrelationPatch } from "./_coreCorrelation/CorrelationPatch.ts";
+
+export type SmithersSpanAttributesInput = Readonly<Record<string, unknown>>;
+
+export type TracingServiceShape = {
+  readonly withSpan: <A, E, R>(
+    name: string,
+    effect: Effect.Effect<A, E, R>,
+    attributes?: Record<string, unknown>,
+  ) => Effect.Effect<A, E, R>;
+  readonly annotate: (attributes: Record<string, unknown>) => Effect.Effect<void>;
+  readonly withCorrelation: <A, E, R>(
+    context: CorrelationPatch,
+    effect: Effect.Effect<A, E, R>,
+  ) => Effect.Effect<A, E, R>;
+};

package/src/_otelLogBuilders.js

@@ -0,0 +1,102 @@
+/**
+ * @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) {
+  if (event.event.kind === "capture.error") {
+    // Truncated output is a non-fatal capture issue, not an error
+    if (event.payload?.reason === "truncated-json-stream") {
+      return "WARN";
+    }
+    return "ERROR";
+  }
+  if (event.event.kind === "capture.warning" || event.event.kind === "stderr") {
+    return "WARN";
+  }
+  return "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,164 @@
+import { readFile, readdir, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, 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 [];
+  // The Codex CLI keeps all state (including sessions) under CODEX_HOME
+  // when set; ~/.codex is only its default.
+  const codexHome = process.env.CODEX_HOME?.trim();
+  return [codexHome ? join(codexHome, "sessions") : 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) => basename(file) === `${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 dayFolders = new Set();
+  for (const offset of [-1, 0, 1]) {
+    const day = new Date(startedAtMs + offset * 24 * 60 * 60 * 1000);
+    dayFolders.add(
+      join(
+        String(day.getUTCFullYear()),
+        String(day.getUTCMonth() + 1).padStart(2, "0"),
+        String(day.getUTCDate()).padStart(2, "0"),
+      ),
+    );
+    dayFolders.add(
+      join(
+        String(day.getFullYear()),
+        String(day.getMonth() + 1).padStart(2, "0"),
+        String(day.getDate()).padStart(2, "0"),
+      ),
+    );
+  }
+  const dayRoots = buildCodexSessionRoots(agent).flatMap((root) => [...dayFolders].map((folder) => join(root, folder)));
+  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;
+}

package/src/_smithersSpanAttributeAliases.js

@@ -0,0 +1,19 @@
+export const smithersSpanAttributeAliases = {
+  runId: "smithers.run_id",
+  run_id: "smithers.run_id",
+  workflowName: "smithers.workflow_name",
+  workflow_name: "smithers.workflow_name",
+  nodeId: "smithers.node_id",
+  node_id: "smithers.node_id",
+  iteration: "smithers.iteration",
+  attempt: "smithers.attempt",
+  nodeLabel: "smithers.node_label",
+  node_label: "smithers.node_label",
+  toolName: "smithers.tool_name",
+  tool_name: "smithers.tool_name",
+  agent: "smithers.agent",
+  model: "smithers.model",
+  status: "smithers.status",
+  waitReason: "smithers.wait_reason",
+  wait_reason: "smithers.wait_reason",
+};

package/src/_smithersTraceSpanStorage.js

@@ -0,0 +1,3 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+/** @type {AsyncLocalStorage<import("effect/Tracer").AnySpan>} */
+export const smithersTraceSpanStorage = new AsyncLocalStorage();