@cohortapp/agent-sdk 2.3.0

package/lib/diagnostics/events.test.mjs

@@ -0,0 +1,290 @@
+/**
+ * events.test.mjs — node:test coverage for the diagnostic-event spine.
+ *
+ * Hermetic: each test writes into an isolated tmpdir and injects a fixed clock,
+ * so date-stamped filenames and timestamps are deterministic. We assert the
+ * on-disk JSONL is valid, carries trace_id, and that emitEvent NEVER throws —
+ * including on an unwritable directory.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { promises as fsp } from "node:fs";
+import { readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  emitEvent,
+  isValidEventType,
+  EVENT_TYPES,
+} from "./events.mjs";
+import { mintTraceId, withTrace } from "./trace.mjs";
+
+async function makeDir() {
+  const path = join(
+    tmpdir(),
+    `events-test-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+  );
+  await fsp.mkdir(path, { recursive: true });
+  return path;
+}
+async function rm(path) {
+  try { await fsp.rm(path, { recursive: true, force: true }); } catch { /* */ }
+}
+
+const FIXED_MS = Date.UTC(2026, 5, 11, 12, 30, 0); // 2026-06-11T12:30:00Z
+const fixedNow = () => FIXED_MS;
+
+function readRows(logDir) {
+  const file = join(logDir, "2026-06-11.jsonl");
+  const body = readFileSync(file, "utf-8");
+  return body
+    .trim()
+    .split("\n")
+    .filter(Boolean)
+    .map((l) => JSON.parse(l)); // throws if any line is not valid JSON
+}
+
+// ---------------------------------------------------------------------------
+// EVENT_TYPES contract
+// ---------------------------------------------------------------------------
+
+test("EVENT_TYPES is the closed 8-type set and is frozen", () => {
+  const values = Object.values(EVENT_TYPES).sort();
+  assert.deepEqual(values, [
+    "classified",
+    "dispatched",
+    "error",
+    "guard_fail",
+    "item_received",
+    "sent",
+    "session_closed",
+    "session_opened",
+  ]);
+  assert.ok(Object.isFrozen(EVENT_TYPES));
+});
+
+test("isValidEventType only accepts the contract types", () => {
+  assert.equal(isValidEventType("item_received"), true);
+  assert.equal(isValidEventType("sent"), true);
+  assert.equal(isValidEventType("nope"), false);
+  assert.equal(isValidEventType(""), false);
+  assert.equal(isValidEventType(null), false);
+  assert.equal(isValidEventType(42), false);
+});
+
+// ---------------------------------------------------------------------------
+// emitEvent — happy path writes valid JSONL with trace_id
+// ---------------------------------------------------------------------------
+
+test("emitEvent writes a valid JSONL row with the full contract shape", async () => {
+  const logDir = await makeDir();
+  try {
+    const traceId = mintTraceId();
+    const ok = emitEvent(
+      {
+        type: EVENT_TYPES.ITEM_RECEIVED,
+        trace_id: traceId,
+        span: "root",
+        attrs: { source: "slack", item_id: "C123.456" },
+      },
+      { now: fixedNow, logDir }
+    );
+    assert.equal(ok, true);
+
+    const rows = readRows(logDir);
+    assert.equal(rows.length, 1);
+    const row = rows[0];
+    assert.equal(row.type, "item_received");
+    assert.equal(row.trace_id, traceId);
+    assert.equal(row.span, "root");
+    assert.equal(row.ts, "2026-06-11T12:30:00.000Z");
+    assert.deepEqual(row.attrs, { source: "slack", item_id: "C123.456" });
+  } finally {
+    await rm(logDir);
+  }
+});
+
+test("emitEvent appends successive rows to the same date stream", async () => {
+  const logDir = await makeDir();
+  try {
+    const t = mintTraceId();
+    emitEvent({ type: "item_received", trace_id: t }, { now: fixedNow, logDir });
+    emitEvent({ type: "classified", trace_id: t }, { now: fixedNow, logDir });
+    emitEvent({ type: "sent", trace_id: t }, { now: fixedNow, logDir });
+    const rows = readRows(logDir);
+    assert.equal(rows.length, 3);
+    assert.deepEqual(rows.map((r) => r.type), ["item_received", "classified", "sent"]);
+    // All correlate to one interaction.
+    assert.ok(rows.every((r) => r.trace_id === t));
+  } finally {
+    await rm(logDir);
+  }
+});
+
+test("emitEvent names the file by UTC date of the event", async () => {
+  const logDir = await makeDir();
+  try {
+    emitEvent({ type: "sent" }, { now: fixedNow, logDir });
+    assert.ok(existsSync(join(logDir, "2026-06-11.jsonl")));
+  } finally {
+    await rm(logDir);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// emitEvent — ambient trace context fills trace_id/span
+// ---------------------------------------------------------------------------
+
+test("emitEvent inherits trace_id/span from the ambient withTrace context", async () => {
+  const logDir = await makeDir();
+  try {
+    const traceId = mintTraceId();
+    withTrace({ trace_id: traceId, span: "root.classify" }, () => {
+      emitEvent({ type: "classified", attrs: { category: "action_required" } }, {
+        now: fixedNow,
+        logDir,
+      });
+    });
+    const [row] = readRows(logDir);
+    assert.equal(row.trace_id, traceId);
+    assert.equal(row.span, "root.classify");
+  } finally {
+    await rm(logDir);
+  }
+});
+
+test("emitEvent trace_id is null when no id supplied and no ambient context", async () => {
+  const logDir = await makeDir();
+  try {
+    emitEvent({ type: "error", attrs: { msg: "boom" } }, { now: fixedNow, logDir });
+    const [row] = readRows(logDir);
+    assert.equal(row.trace_id, null);
+    assert.equal(row.span, "root");
+  } finally {
+    await rm(logDir);
+  }
+});
+
+test("an explicit trace_id overrides the ambient context", async () => {
+  const logDir = await makeDir();
+  try {
+    const ambient = mintTraceId();
+    const explicit = mintTraceId();
+    withTrace(ambient, () => {
+      emitEvent({ type: "sent", trace_id: explicit }, { now: fixedNow, logDir });
+    });
+    const [row] = readRows(logDir);
+    assert.equal(row.trace_id, explicit);
+  } finally {
+    await rm(logDir);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// emitEvent — closed type set: unknown type is coerced to error
+// ---------------------------------------------------------------------------
+
+test("an unknown event type is coerced to error and preserves the original", async () => {
+  const logDir = await makeDir();
+  try {
+    emitEvent({ type: "totally_made_up", attrs: { a: 1 } }, { now: fixedNow, logDir });
+    const [row] = readRows(logDir);
+    assert.equal(row.type, "error");
+    assert.equal(row.attrs._invalid_type, "totally_made_up");
+    assert.equal(row.attrs.a, 1);
+  } finally {
+    await rm(logDir);
+  }
+});
+
+test("a missing type is coerced to error with _invalid_type null", async () => {
+  const logDir = await makeDir();
+  try {
+    emitEvent({ attrs: {} }, { now: fixedNow, logDir });
+    const [row] = readRows(logDir);
+    assert.equal(row.type, "error");
+    assert.equal(row.attrs._invalid_type, null);
+  } finally {
+    await rm(logDir);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// emitEvent — never throws; degrades to false
+// ---------------------------------------------------------------------------
+
+test("emitEvent never throws on a bad/unwritable dir (returns false)", async () => {
+  const logDir = await makeDir();
+  try {
+    // Make the diagnostics dir a FILE so mkdir/append fails.
+    const blocker = join(logDir, "blocked");
+    await fsp.writeFile(blocker, "x");
+    // Point logDir at a path under the file → cannot create a directory there.
+    const badDir = join(blocker, "diagnostics");
+    let ok;
+    assert.doesNotThrow(() => {
+      ok = emitEvent({ type: "sent", trace_id: "T" }, { now: fixedNow, logDir: badDir });
+    });
+    assert.equal(ok, false);
+  } finally {
+    await rm(logDir);
+  }
+});
+
+test("emitEvent never throws on a null/garbage event argument", () => {
+  let ok;
+  assert.doesNotThrow(() => {
+    ok = emitEvent(null, { append: () => true });
+  });
+  assert.equal(ok, true); // coerced to {} → error row, write succeeds
+});
+
+test("emitEvent returns false when the injected appender fails", () => {
+  const ok = emitEvent(
+    { type: "sent", trace_id: "T" },
+    { append: () => false }
+  );
+  assert.equal(ok, false);
+});
+
+test("emitEvent never throws when the appender itself throws", () => {
+  let ok;
+  assert.doesNotThrow(() => {
+    ok = emitEvent({ type: "sent" }, {
+      append: () => { throw new Error("disk gone"); },
+    });
+  });
+  assert.equal(ok, false);
+});
+
+test("emitEvent tolerates non-object attrs by wrapping them", async () => {
+  const logDir = await makeDir();
+  try {
+    emitEvent({ type: "sent", trace_id: "T", attrs: "just a string" }, {
+      now: fixedNow,
+      logDir,
+    });
+    const [row] = readRows(logDir);
+    assert.deepEqual(row.attrs, { value: "just a string" });
+  } finally {
+    await rm(logDir);
+  }
+});
+
+test("emitEvent uses the injected appender with the date-stamped path", () => {
+  const calls = [];
+  const ok = emitEvent(
+    { type: "dispatched", trace_id: "T" },
+    {
+      now: fixedNow,
+      logDir: "/somewhere/logs/diagnostics",
+      append: (path, record) => { calls.push({ path, record }); return true; },
+    }
+  );
+  assert.equal(ok, true);
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0].path, "/somewhere/logs/diagnostics/2026-06-11.jsonl");
+  assert.equal(calls[0].record.type, "dispatched");
+});

package/lib/diagnostics/otel.mjs

@@ -0,0 +1,237 @@
+/**
+ * lib/diagnostics/otel.mjs — Claude Code native OTLP enablement (env builder).
+ *
+ * For a Claude-Code fleet, ~70% of observability is "turn on the env vars":
+ * Claude Code natively emits OpenTelemetry metrics/logs/traces — cost-per-session
+ * in USD, `api_error`/`api_refusal`/`tool_decision` events, `TRACEPARENT`
+ * inheritance — once `CLAUDE_CODE_ENABLE_TELEMETRY=1` and the `OTEL_*` exporter
+ * vars are set (gaps-enterprise-ops G7/G14). This module is the single, pure
+ * BUILDER for that env block, plus the `OTEL_RESOURCE_ATTRIBUTES` string that
+ * stamps `service.name` and the agent id onto every signal so a fleet collector
+ * can attribute traces/metrics to the right Mac mini.
+ *
+ * It is a pure function over inputs (an env source + agent identity) returning a
+ * plain `{KEY: value}` map. It does NOT mutate `process.env`, spawn anything, or
+ * add an OpenTelemetry SDK dependency — maestro is near-zero-dep, and Claude Code
+ * already ships the SDK. The returned map is what you spread into a spawned
+ * sub-session's env, or render into managed `settings.json` `env` for fleet-wide
+ * rollout (see docs/guides/observability-otel.md).
+ *
+ * Disabled by default. The block is produced only when telemetry is explicitly
+ * enabled (`MAESTRO_OTEL=1`, or `config.enabled === true`); otherwise an EMPTY
+ * map is returned, so an un-configured agent emits nothing and spreading the
+ * result is a no-op.
+ *
+ * Constraints (CLAUDE.md): ESM, Node built-ins only, pure + injectable (env and
+ * identity are passed in, never read implicitly beyond the default `process.env`
+ * convenience). Never throws.
+ *
+ * @module lib/diagnostics/otel
+ */
+
+/** Truthy env strings, mirroring Claude Code's own "1/true/yes/on" convention. */
+const TRUTHY = new Set(["1", "true", "yes", "on"]);
+
+/**
+ * Interpret a value as a boolean flag the way the rest of maestro / Claude Code
+ * does: case-insensitive 1/true/yes/on.
+ * @param {unknown} v
+ * @returns {boolean}
+ */
+function isTruthy(v) {
+  return TRUTHY.has(String(v == null ? "" : v).trim().toLowerCase());
+}
+
+/**
+ * Decide whether telemetry is enabled. Order: explicit `config.enabled`
+ * (boolean) wins; otherwise the `MAESTRO_OTEL` env flag.
+ * @param {object} opts
+ * @param {Record<string, string|undefined>} opts.env
+ * @param {{enabled?: boolean}} opts.config
+ * @returns {boolean}
+ */
+export function otelEnabled({ env = process.env, config = {} } = {}) {
+  if (typeof config.enabled === "boolean") return config.enabled;
+  return isTruthy(env.MAESTRO_OTEL);
+}
+
+/**
+ * Sanitize one `OTEL_RESOURCE_ATTRIBUTES` value: it is a comma-separated
+ * `k=v,k=v` string, so a `,` or `=` inside a value would corrupt the list. We
+ * strip those (and surrounding whitespace) rather than percent-encode, keeping
+ * the attribute human-readable in a collector UI. Empty after stripping → "".
+ * @param {unknown} v
+ * @returns {string}
+ */
+function sanitizeAttrValue(v) {
+  return String(v == null ? "" : v)
+    .replace(/[,=]/g, " ")
+    .trim();
+}
+
+/**
+ * Derive a stable agent id for `service.instance.id` / the `agent.id` resource
+ * attribute from an agent identity record (config/agent.json shape). Prefers an
+ * explicit id, then the repo slug, then a slugified full name. Returns "" when
+ * nothing usable is present (the attribute is then omitted, not blank).
+ * @param {object} identity
+ * @returns {string}
+ */
+export function deriveAgentId(identity = {}) {
+  const raw =
+    identity.agentId ||
+    identity.id ||
+    identity.repoSlug ||
+    identity.slackMemberId ||
+    identity.fullName ||
+    identity.firstName ||
+    "";
+  return String(raw)
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/**
+ * Build the `OTEL_RESOURCE_ATTRIBUTES` value: `service.name`, `service.version`,
+ * the agent id (as both `service.instance.id` and a friendly `agent.id`), and
+ * any extra caller-supplied attributes. Skips empty values so the list never
+ * carries a dangling `k=`.
+ * @param {object} opts
+ * @param {string} opts.serviceName
+ * @param {string} [opts.serviceVersion]
+ * @param {string} [opts.agentId]
+ * @param {Record<string, string>} [opts.extra]
+ * @returns {string}
+ */
+export function buildResourceAttributes({
+  serviceName,
+  serviceVersion,
+  agentId,
+  extra = {},
+} = {}) {
+  const pairs = [];
+  const push = (k, v) => {
+    const val = sanitizeAttrValue(v);
+    if (k && val) pairs.push(`${k}=${val}`);
+  };
+  push("service.name", serviceName);
+  push("service.version", serviceVersion);
+  push("service.instance.id", agentId);
+  push("agent.id", agentId);
+  for (const [k, v] of Object.entries(extra)) push(k, v);
+  return pairs.join(",");
+}
+
+/**
+ * Build the managed-settings env block that enables Claude Code's native OTLP
+ * telemetry for THIS agent.
+ *
+ * Returns an empty object `{}` when telemetry is not enabled (see otelEnabled),
+ * so the caller can unconditionally spread it. When enabled, returns the env map:
+ *
+ *   CLAUDE_CODE_ENABLE_TELEMETRY  "1"
+ *   OTEL_METRICS_EXPORTER         metrics exporter (default "otlp")
+ *   OTEL_LOGS_EXPORTER            logs/events exporter (default "otlp")
+ *   OTEL_TRACES_EXPORTER          traces exporter (default "otlp")
+ *   OTEL_EXPORTER_OTLP_PROTOCOL   "grpc" | "http/protobuf" | "http/json"
+ *   OTEL_EXPORTER_OTLP_ENDPOINT   collector endpoint (when configured)
+ *   OTEL_EXPORTER_OTLP_HEADERS    auth headers (when configured)
+ *   OTEL_METRIC_EXPORT_INTERVAL   ms between metric exports (when configured)
+ *   OTEL_LOGS_EXPORT_INTERVAL     ms between log exports (when configured)
+ *   OTEL_RESOURCE_ATTRIBUTES      service.name + agent id (+ extras)
+ *
+ * All exporter knobs are read from `config` first, then `env` (so an operator
+ * can set them in managed `settings.json` `env` OR in the shell), then a small
+ * set of safe defaults. Endpoint/headers/intervals are emitted only when a value
+ * is present — Claude Code's own OTLP defaults apply otherwise.
+ *
+ * @param {object} [opts]
+ * @param {Record<string, string|undefined>} [opts.env] env source (default process.env)
+ * @param {object} [opts.config] telemetry config block (config/observability.yaml shape)
+ * @param {boolean} [opts.config.enabled]
+ * @param {string} [opts.config.endpoint]
+ * @param {string} [opts.config.protocol]
+ * @param {string} [opts.config.headers]
+ * @param {string} [opts.config.metricsExporter]
+ * @param {string} [opts.config.logsExporter]
+ * @param {string} [opts.config.tracesExporter]
+ * @param {number|string} [opts.config.metricExportIntervalMs]
+ * @param {number|string} [opts.config.logsExportIntervalMs]
+ * @param {Record<string, string>} [opts.config.resourceAttributes] extra attrs
+ * @param {object} [opts.identity] agent identity (config/agent.json shape)
+ * @param {string} [opts.serviceName] override service.name (default "maestro-agent")
+ * @param {string} [opts.serviceVersion] override service.version
+ * @returns {Record<string, string>} env map (empty when disabled)
+ */
+export function buildOtelEnv(opts = {}) {
+  try {
+    const env = opts.env || process.env;
+    const config = opts.config || {};
+    if (!otelEnabled({ env, config })) return {};
+
+    const identity = opts.identity || {};
+    const serviceName =
+      opts.serviceName || config.serviceName || env.OTEL_SERVICE_NAME || "maestro-agent";
+    const serviceVersion =
+      opts.serviceVersion ||
+      config.serviceVersion ||
+      identity.maestroVersion ||
+      identity.version ||
+      "";
+    const agentId = deriveAgentId(identity);
+
+    // Resolution helper: config wins, then env, then default.
+    const pick = (cfgKey, envKey, dflt) => {
+      const c = config[cfgKey];
+      if (c != null && String(c).trim() !== "") return String(c).trim();
+      const e = env[envKey];
+      if (e != null && String(e).trim() !== "") return String(e).trim();
+      return dflt;
+    };
+
+    const out = {
+      CLAUDE_CODE_ENABLE_TELEMETRY: "1",
+      OTEL_METRICS_EXPORTER: pick("metricsExporter", "OTEL_METRICS_EXPORTER", "otlp"),
+      OTEL_LOGS_EXPORTER: pick("logsExporter", "OTEL_LOGS_EXPORTER", "otlp"),
+      OTEL_TRACES_EXPORTER: pick("tracesExporter", "OTEL_TRACES_EXPORTER", "otlp"),
+      OTEL_EXPORTER_OTLP_PROTOCOL: pick(
+        "protocol",
+        "OTEL_EXPORTER_OTLP_PROTOCOL",
+        "http/protobuf"
+      ),
+    };
+
+    // Optional knobs: only emit when an actual value exists so Claude Code's own
+    // OTLP defaults apply otherwise (don't clobber with a blank).
+    const endpoint = pick("endpoint", "OTEL_EXPORTER_OTLP_ENDPOINT", "");
+    if (endpoint) out.OTEL_EXPORTER_OTLP_ENDPOINT = endpoint;
+
+    const headers = pick("headers", "OTEL_EXPORTER_OTLP_HEADERS", "");
+    if (headers) out.OTEL_EXPORTER_OTLP_HEADERS = headers;
+
+    const metricInterval = pick(
+      "metricExportIntervalMs",
+      "OTEL_METRIC_EXPORT_INTERVAL",
+      ""
+    );
+    if (metricInterval) out.OTEL_METRIC_EXPORT_INTERVAL = String(metricInterval);
+
+    const logsInterval = pick("logsExportIntervalMs", "OTEL_LOGS_EXPORT_INTERVAL", "");
+    if (logsInterval) out.OTEL_LOGS_EXPORT_INTERVAL = String(logsInterval);
+
+    const resourceAttrs = buildResourceAttributes({
+      serviceName,
+      serviceVersion,
+      agentId,
+      extra: config.resourceAttributes || {},
+    });
+    if (resourceAttrs) out.OTEL_RESOURCE_ATTRIBUTES = resourceAttrs;
+
+    return out;
+  } catch {
+    // A pure builder must never break a spawn path; degrade to "no telemetry".
+    return {};
+  }
+}