feat(hooks): add Hermes telemetry handler

2026-05-20 17:35:56 -07:00
parent 78376bdd83
commit 27d40ce28f
9 changed files with 2452 additions and 0 deletions
@@ -0,0 +1,489 @@
+#!/usr/bin/env node
+
+// handler.ts
+import { randomUUID as randomUUID2 } from "node:crypto";
+import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir, hostname } from "node:os";
+import { join } from "node:path";
+
+// ../shared/lib.ts
+import { randomUUID } from "node:crypto";
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function pickString(...values) {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim() !== "") {
+      return value;
+    }
+  }
+  return void 0;
+}
+function pickNumber(...values) {
+  for (const value of values) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value;
+    }
+  }
+  return void 0;
+}
+function truncate(value, limit) {
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  const text = typeof value === "string" ? value : safeJSONStringify(value);
+  if (!text) {
+    return void 0;
+  }
+  if (text.length <= limit) {
+    return text;
+  }
+  return text.slice(0, limit) + "...";
+}
+function safeJSONStringify(value) {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+function buildEnvelope(framework, host, type, sessionKey, opts = {}) {
+  const correlation = {};
+  if (sessionKey) {
+    correlation.session_id = sessionKey;
+  }
+  if (opts.runId) {
+    correlation.run_id = opts.runId;
+  }
+  if (opts.spanId) {
+    correlation.span_id = opts.spanId;
+  }
+  if (opts.parentSpanId) {
+    correlation.parent_span_id = opts.parentSpanId;
+  }
+  const envelope = {
+    schema: { name: "agentmon.event", version: 1 },
+    event: {
+      id: randomUUID(),
+      type,
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      source: {
+        framework,
+        client_id: host,
+        host
+      }
+    }
+  };
+  if (Object.keys(correlation).length > 0) {
+    envelope.correlation = correlation;
+  }
+  if (opts.attributes && Object.keys(opts.attributes).length > 0) {
+    envelope.attributes = opts.attributes;
+  }
+  if (opts.payload && Object.keys(opts.payload).length > 0) {
+    envelope.payload = opts.payload;
+  }
+  return envelope;
+}
+function createTransport(ingestUrl, opts) {
+  const batchSize = opts?.batchSize ?? 10;
+  const flushMs = opts?.flushMs ?? 2e3;
+  const fetchTimeoutMs = opts?.fetchTimeoutMs ?? 500;
+  let buffer = [];
+  let flushTimer = null;
+  let isFlushing = false;
+  async function postBatch(batch) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), fetchTimeoutMs);
+    try {
+      await fetch(`${ingestUrl}/v1/events`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(batch),
+        signal: controller.signal
+      });
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  function scheduleFlush() {
+    if (!flushTimer) {
+      flushTimer = setTimeout(() => {
+        void flush2();
+      }, flushMs);
+    }
+  }
+  async function flush2() {
+    if (flushTimer) {
+      clearTimeout(flushTimer);
+      flushTimer = null;
+    }
+    if (isFlushing || buffer.length === 0) {
+      return;
+    }
+    isFlushing = true;
+    const batch = buffer.splice(0, batchSize);
+    try {
+      await postBatch(batch);
+    } catch {
+      console.debug(`[agentmon] failed to flush ${batch.length} events`);
+    } finally {
+      isFlushing = false;
+      if (buffer.length > 0) {
+        if (buffer.length >= batchSize) {
+          void flush2();
+        } else {
+          scheduleFlush();
+        }
+      }
+    }
+  }
+  function enqueue2(event) {
+    buffer.push(event);
+    if (buffer.length >= batchSize) {
+      void flush2();
+    } else {
+      scheduleFlush();
+    }
+  }
+  return { enqueue: enqueue2, flush: flush2 };
+}
+async function readStdin() {
+  return new Promise((resolve) => {
+    let data = "";
+    let done = false;
+    const timer = setTimeout(() => finish(data), 100);
+    const finish = (value) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      resolve(value);
+    };
+    process.stdin.on("data", (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on("end", () => finish(data));
+    process.stdin.on("error", () => finish(""));
+  });
+}
+
+// handler.ts
+var INGEST_URL = process.env.AGENTMON_INGEST_URL || "http://localhost:8080";
+var FRAMEWORK = process.env.AGENTMON_FRAMEWORK || "hermes";
+var HOST = process.env.AGENTMON_HOST || hostname();
+var { enqueue, flush } = createTransport(INGEST_URL);
+var STATE_DIR = join(homedir(), ".agentmon-state", "hermes");
+function ensureStateDir() {
+  try {
+    mkdirSync(STATE_DIR, { recursive: true });
+  } catch {
+  }
+}
+function loadState(sessionKey) {
+  try {
+    const raw = readFileSync(join(STATE_DIR, sessionKey + ".json"), "utf8");
+    const state = JSON.parse(raw);
+    return { spans: {}, ...state };
+  } catch {
+    return { spans: {} };
+  }
+}
+function saveState(sessionKey, state) {
+  if (!sessionKey) {
+    return;
+  }
+  ensureStateDir();
+  try {
+    writeFileSync(join(STATE_DIR, sessionKey + ".json"), JSON.stringify(state), "utf8");
+  } catch {
+  }
+}
+function clearState(sessionKey) {
+  if (!sessionKey) {
+    return;
+  }
+  try {
+    unlinkSync(join(STATE_DIR, sessionKey + ".json"));
+  } catch {
+  }
+}
+function getExtra(input) {
+  return isRecord(input.extra) ? input.extra : {};
+}
+function getSessionKey(input) {
+  const extra = getExtra(input);
+  return pickString(
+    input.session_id,
+    input.sessionId,
+    input.sessionID,
+    input.session,
+    extra.session_id,
+    extra.sessionId,
+    extra.sessionID,
+    extra.parent_session_id,
+    extra.task_id
+  );
+}
+function getToolCallId(input) {
+  const extra = getExtra(input);
+  return pickString(input.tool_call_id, extra.tool_call_id, extra.call_id, extra.id);
+}
+function getToolName(input) {
+  const extra = getExtra(input);
+  return pickString(input.tool_name, input.tool, input.name, extra.tool_name, extra.tool, extra.name) || "unknown";
+}
+function getUsage(input) {
+  const extra = getExtra(input);
+  const usage = isRecord(input.usage) ? input.usage : isRecord(extra.usage) ? extra.usage : void 0;
+  if (!usage) return void 0;
+  const result = {};
+  if (usage.input_tokens !== void 0) result.input_tokens = usage.input_tokens;
+  if (usage.prompt_tokens !== void 0) result.input_tokens = usage.prompt_tokens;
+  if (usage.output_tokens !== void 0) result.output_tokens = usage.output_tokens;
+  if (usage.completion_tokens !== void 0) result.output_tokens = usage.completion_tokens;
+  if (usage.cache_read_tokens !== void 0) result.cache_read_tokens = usage.cache_read_tokens;
+  if (usage.cache_write_tokens !== void 0) result.cache_write_tokens = usage.cache_write_tokens;
+  if (usage.cache_creation_tokens !== void 0) result.cache_write_tokens = usage.cache_creation_tokens;
+  if (usage.reasoning_tokens !== void 0) result.reasoning_tokens = usage.reasoning_tokens;
+  if (usage.total_tokens !== void 0) result.total_tokens = usage.total_tokens;
+  if (usage.total_cost !== void 0) result.total_cost = usage.total_cost;
+  if (usage.cost !== void 0) result.total_cost = usage.cost;
+  return Object.keys(result).length > 0 ? result : void 0;
+}
+function getModel(input) {
+  const extra = getExtra(input);
+  return pickString(input.model, extra.model, extra.response_model);
+}
+function getPlatform(input) {
+  const extra = getExtra(input);
+  return pickString(input.platform, extra.platform);
+}
+function getDuration(input) {
+  const extra = getExtra(input);
+  return pickNumber(input.duration_ms, input.elapsed_ms, extra.duration_ms, extra.api_duration, extra.elapsed_ms);
+}
+function ensureSessionStarted(sessionKey, input, state) {
+  if (!sessionKey || state.sessionStarted) {
+    return;
+  }
+  enqueue(buildEnvelope(FRAMEWORK, HOST, "session.start", sessionKey, {
+    attributes: {
+      synthetic: true,
+      recovered_from: "hermes-hook",
+      cwd: pickString(input.cwd),
+      platform: getPlatform(input),
+      model: getModel(input)
+    }
+  }));
+  state.sessionStarted = true;
+  saveState(sessionKey, state);
+}
+async function handleSessionStart(input) {
+  const sessionKey = getSessionKey(input) || randomUUID2();
+  const state = loadState(sessionKey);
+  if (!state.sessionStarted) {
+    enqueue(buildEnvelope(FRAMEWORK, HOST, "session.start", sessionKey, {
+      attributes: {
+        cwd: pickString(input.cwd),
+        platform: getPlatform(input),
+        model: getModel(input)
+      }
+    }));
+    state.sessionStarted = true;
+    saveState(sessionKey, state);
+  }
+  await flush();
+}
+async function handleRunStart(input) {
+  const sessionKey = getSessionKey(input) || randomUUID2();
+  const state = loadState(sessionKey);
+  ensureSessionStarted(sessionKey, input, state);
+  if (state.runId) {
+    enqueue(buildEnvelope(FRAMEWORK, HOST, "run.end", sessionKey, {
+      runId: state.runId,
+      payload: { status: "success" }
+    }));
+  }
+  const runId = randomUUID2();
+  state.runId = runId;
+  saveState(sessionKey, state);
+  const extra = getExtra(input);
+  enqueue(buildEnvelope(FRAMEWORK, HOST, "run.start", sessionKey, {
+    runId,
+    attributes: {
+      is_first_turn: extra.is_first_turn,
+      platform: getPlatform(input),
+      model: getModel(input)
+    },
+    payload: {
+      prompt_preview: truncate(extra.user_message ?? input.user_message, 200)
+    }
+  }));
+  await flush();
+}
+async function handleRunEnd(input) {
+  const sessionKey = getSessionKey(input);
+  if (!sessionKey) {
+    await flush();
+    return;
+  }
+  const state = loadState(sessionKey);
+  ensureSessionStarted(sessionKey, input, state);
+  if (state.runId) {
+    enqueue(buildEnvelope(FRAMEWORK, HOST, "run.end", sessionKey, {
+      runId: state.runId,
+      payload: {
+        status: "success",
+        duration_ms: getDuration(input),
+        model: getModel(input),
+        response_preview: truncate(getExtra(input).assistant_response, 500)
+      }
+    }));
+    state.runId = void 0;
+    saveState(sessionKey, state);
+  }
+  await flush();
+}
+async function handleToolStart(input) {
+  const sessionKey = getSessionKey(input);
+  const state = sessionKey ? loadState(sessionKey) : { spans: {} };
+  ensureSessionStarted(sessionKey, input, state);
+  const toolName = getToolName(input);
+  const toolCallId = getToolCallId(input);
+  const spanKey = toolCallId || toolName;
+  const spanId = randomUUID2();
+  state.spans[spanKey] = spanId;
+  saveState(sessionKey, state);
+  enqueue(buildEnvelope(FRAMEWORK, HOST, "span.start", sessionKey, {
+    runId: state.runId,
+    spanId,
+    attributes: {
+      span_kind: "tool",
+      name: toolName,
+      tool_call_id: toolCallId
+    },
+    payload: {
+      input: truncate(input.tool_input ?? getExtra(input).args, 500)
+    }
+  }));
+  await flush();
+}
+async function handleToolEnd(input) {
+  const sessionKey = getSessionKey(input);
+  const state = sessionKey ? loadState(sessionKey) : { spans: {} };
+  const toolName = getToolName(input);
+  const toolCallId = getToolCallId(input);
+  const spanKey = toolCallId || toolName;
+  const spanId = state.spans[spanKey];
+  const extra = getExtra(input);
+  const result = extra.result ?? input.result;
+  const resultRecord = isRecord(result) ? result : {};
+  const success = extra.error === void 0 && resultRecord.error === void 0;
+  enqueue(buildEnvelope(FRAMEWORK, HOST, "span.end", sessionKey, {
+    runId: state.runId,
+    spanId,
+    attributes: {
+      span_kind: "tool",
+      name: toolName,
+      tool_call_id: toolCallId
+    },
+    payload: {
+      status: success ? "success" : "error",
+      result_preview: truncate(resultRecord.output ?? resultRecord.error ?? extra.error ?? result, 500),
+      duration_ms: getDuration(input)
+    }
+  }));
+  delete state.spans[spanKey];
+  saveState(sessionKey, state);
+  await flush();
+}
+async function handleAPIResult(input) {
+  const sessionKey = getSessionKey(input);
+  const state = sessionKey ? loadState(sessionKey) : { spans: {} };
+  const usage = getUsage(input);
+  if (!usage) {
+    await flush();
+    return;
+  }
+  enqueue(buildEnvelope(FRAMEWORK, HOST, "metric.snapshot", sessionKey, {
+    runId: state.runId,
+    payload: {
+      metrics: {
+        usage,
+        model: getModel(input),
+        provider: pickString(getExtra(input).provider),
+        duration_ms: getDuration(input)
+      }
+    }
+  }));
+  await flush();
+}
+async function handleSessionEnd(input) {
+  const sessionKey = getSessionKey(input);
+  const state = sessionKey ? loadState(sessionKey) : { spans: {} };
+  if (state.runId) {
+    enqueue(buildEnvelope(FRAMEWORK, HOST, "run.end", sessionKey, {
+      runId: state.runId,
+      payload: {
+        status: input.interrupted || getExtra(input).interrupted ? "interrupted" : "success",
+        model: getModel(input)
+      }
+    }));
+  }
+  enqueue(buildEnvelope(FRAMEWORK, HOST, "session.end", sessionKey, {
+    payload: {
+      model: getModel(input),
+      completed: getExtra(input).completed,
+      interrupted: getExtra(input).interrupted
+    }
+  }));
+  clearState(sessionKey);
+  await flush();
+}
+var handler = async () => {
+  const hookType = process.argv[2] || "unknown";
+  let input = {};
+  try {
+    const stdin = await readStdin();
+    if (stdin) {
+      input = JSON.parse(stdin);
+    }
+  } catch {
+    input = {};
+  }
+  try {
+    switch (hookType) {
+      case "session-start":
+      case "start":
+        await handleSessionStart(input);
+        break;
+      case "run-start":
+      case "pre-llm":
+        await handleRunStart(input);
+        break;
+      case "run-end":
+      case "post-llm":
+        await handleRunEnd(input);
+        break;
+      case "tool-start":
+        await handleToolStart(input);
+        break;
+      case "tool-end":
+        await handleToolEnd(input);
+        break;
+      case "api-result":
+      case "post-api":
+        await handleAPIResult(input);
+        break;
+      case "session-end":
+      case "stop":
+        await handleSessionEnd(input);
+        break;
+      default:
+        console.debug(`[agentmon] unknown hermes hook type: ${hookType}`);
+    }
+  } catch (err) {
+    console.debug("[agentmon] hermes handler error:", err);
+  }
+};
+handler();