@atbash/sdk 0.18.0-dev.0 → 0.19.0-dev.0

package/dist/index.js

@@ -59,6 +59,7 @@ __export(src_ts_exports, {
   classifyMemoryWrite: () => classifyMemoryWrite,
   columnAad: () => columnAad,
   commitMemoryVersion: () => commitMemoryVersion,
+  configureEvents: () => configureEvents,
   containsEvasionCharacters: () => containsEvasionCharacters,
   containsSecret: () => containsSecret,
   createFileLogger: () => createFileLogger,
@@ -74,6 +75,7 @@ __export(src_ts_exports, {
   encryptForOrg: () => encryptForOrg,
   encryptMemoryContent: () => encryptMemoryContent,
   encryptedLength: () => encryptedLength,
+  eventsAreOn: () => eventsAreOn,
   flushTelemetry: () => flushTelemetry,
   generateKeypair: () => generateKeypair,
   getActiveAgentMemory: () => getActiveAgentMemory,
@@ -102,6 +104,7 @@ __export(src_ts_exports, {
   pubkeyToHex: () => pubkeyToHex,
   recordCall: () => recordCall,
   recordDuration: () => recordDuration,
+  recordEvent: () => recordEvent,
   redactJsonStrings: () => redactJsonStrings,
   redactSecrets: () => redactSecrets,
   resolve: () => resolve,
@@ -597,6 +600,59 @@ function canonicalAllow(data) {
   return verdict === "ALLOW" || verdict === "GREEN";
 }
 
+// src-ts/opentel/events.ts
+var SLOW_MS = 1500;
+var SUCCESS_SAMPLE_RATE = 10;
+var logger = null;
+var eventsEnabled = false;
+var sdkVersion = "";
+var eventSource = "sdk";
+var hashAgentKey = null;
+function eventsOptedOut() {
+  const flag = process.env.ATBASH_TELEMETRY_EVENTS_DISABLED?.trim().toLowerCase();
+  return Boolean(flag && ["1", "true", "yes", "on"].includes(flag));
+}
+function configureEvents(next, opts = {}) {
+  logger = next;
+  eventsEnabled = next !== null && !eventsOptedOut();
+  if (opts.version) sdkVersion = opts.version;
+  if (opts.source) eventSource = opts.source;
+  hashAgentKey = opts.hashAgentKey ?? null;
+}
+function eventsAreOn() {
+  return eventsEnabled && logger !== null;
+}
+function sampleRateFor(e) {
+  if (e.status === "error") return 1;
+  if (e.durationMs >= SLOW_MS) return 1;
+  return Math.random() < 1 / SUCCESS_SAMPLE_RATE ? SUCCESS_SAMPLE_RATE : 0;
+}
+function recordEvent(e) {
+  if (!eventsAreOn()) return;
+  const sampleRate = sampleRateFor(e);
+  if (sampleRate === 0) return;
+  try {
+    const attributes = {
+      "function.name": e.functionName,
+      "duration_ms": Math.round(e.durationMs),
+      status: e.status,
+      source: eventSource,
+      // Honeycomb reweights counts and percentiles by this. It is per-event
+      // because the sampling is biased by outcome and latency.
+      sampleRate
+    };
+    if (sdkVersion) attributes["sdk.version"] = sdkVersion;
+    if (e.agentPubkey && hashAgentKey) attributes["agent.hash"] = hashAgentKey(e.agentPubkey);
+    if (e.chain) attributes["chain"] = e.chain;
+    if (e.errorClass) attributes["error.class"] = e.errorClass;
+    if (e.errorStatus !== void 0) attributes["error.status"] = e.errorStatus;
+    if (e.errorPath) attributes["error.path"] = e.errorPath;
+    if (e.outcome) attributes["outcome"] = e.outcome;
+    logger.emit({ body: e.functionName, attributes });
+  } catch {
+  }
+}
+
 // src-ts/opentel/telemetry.ts
 var import_node_fs2 = require("fs");
 var import_node_os2 = require("os");
@@ -604,7 +660,11 @@ var import_node_path2 = require("path");
 var import_exporter_metrics_otlp_http = require("@opentelemetry/exporter-metrics-otlp-http");
 var import_resources = require("@opentelemetry/resources");
 var import_sdk_metrics = require("@opentelemetry/sdk-metrics");
+var import_exporter_logs_otlp_http = require("@opentelemetry/exporter-logs-otlp-http");
+var import_sdk_logs = require("@opentelemetry/sdk-logs");
+var import_node_crypto = require("crypto");
 var meterProvider = null;
+var loggerProvider = null;
 var callCounter = null;
 var durationHistogram = null;
 var defaultSource = "sdk";
@@ -631,6 +691,41 @@ function autoInit() {
   if (isTelemetryOptedOut()) return;
   setupTelemetry({ enabled: true });
 }
+function defaultAgentKeyHasher(pubkeyHex) {
+  return (0, import_node_crypto.createHash)("sha256").update(pubkeyHex).digest("hex");
+}
+var counterHasher = null;
+function hashAgentKeyOrDrop(pubkeyHex) {
+  return counterHasher ? counterHasher(pubkeyHex) : void 0;
+}
+function customCollector() {
+  const url = process.env.ATBASH_TELEMETRY_COLLECTOR_URL?.trim();
+  if (!url) return null;
+  const loopback = /^https?:\/\/(localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\])(:|\/|$)/i.test(url);
+  if (loopback && process.env.ATBASH_TELEMETRY_ALLOW_LOOPBACK !== "1") {
+    throw new Error(
+      "ATBASH_TELEMETRY_COLLECTOR_URL is a loopback address; set ATBASH_TELEMETRY_ALLOW_LOOPBACK=1 to allow it."
+    );
+  }
+  if (!loopback && !/^https:\/\//i.test(url)) {
+    throw new Error("ATBASH_TELEMETRY_COLLECTOR_URL must be https (loopback excepted).");
+  }
+  let headers = {};
+  const raw = process.env.ATBASH_TELEMETRY_COLLECTOR_HEADERS?.trim();
+  if (raw) {
+    try {
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        headers = Object.fromEntries(
+          Object.entries(parsed).map(([k, v]) => [k, String(v)])
+        );
+      }
+    } catch {
+      throw new Error("ATBASH_TELEMETRY_COLLECTOR_HEADERS must be a JSON object of header names to values.");
+    }
+  }
+  return { url: url.replace(/\/+$/, ""), headers: () => headers };
+}
 function setupTelemetry(config) {
   if (!config.enabled) return;
   if (isTelemetryOptedOut()) return;
@@ -642,16 +737,20 @@ function setupTelemetry(config) {
     requestedExportIntervalMs = config.exportIntervalMs;
   }
   if (meterProvider) return;
-  if (!config.endpoint || !config.getAuthHeaders) return;
-  if (/^https?:\/\/(localhost|127\.0\.0\.1|0\.0\.0\.0)(:|\/|$)/i.test(
+  const collector = customCollector();
+  if (!collector && (!config.endpoint || !config.getAuthHeaders)) return;
+  if (!collector && /^https?:\/\/(localhost|127\.0\.0\.1|0\.0\.0\.0)(:|\/|$)/i.test(
     config.endpoint
   ))
     return;
-  const proxyUrl = `${config.endpoint.replace(/\/+$/, "")}/api/telemetry`;
-  const getAuthHeaders = config.getAuthHeaders;
+  const destination = collector ?? {
+    url: `${config.endpoint.replace(/\/+$/, "")}/api/telemetry`,
+    headers: () => config.getAuthHeaders()
+  };
+  const proxyUrl = destination.url;
   const exporter = new import_exporter_metrics_otlp_http.OTLPMetricExporter({
-    url: proxyUrl,
-    headers: async () => getAuthHeaders(),
+    url: collector ? `${proxyUrl}/v1/metrics` : proxyUrl,
+    headers: async () => destination.headers(),
     // DELTA, not the OTel default of CUMULATIVE.
     //
     // A cumulative counter reports a running total, and the backend recovers
@@ -683,6 +782,21 @@ function setupTelemetry(config) {
     description: "SDK function execution duration",
     unit: "ms"
   });
+  counterHasher = config.hashAgentKey ?? defaultAgentKeyHasher;
+  const logExporter = new import_exporter_logs_otlp_http.OTLPLogExporter({
+    // A real collector takes OTLP at its own signal paths; the Atbash proxy
+    // takes a query parameter, because it is one authenticated route.
+    url: collector ? `${proxyUrl}/v1/logs` : `${proxyUrl}?signal=logs`,
+    headers: async () => destination.headers()
+  });
+  loggerProvider = new import_sdk_logs.LoggerProvider({
+    resource: (0, import_resources.resourceFromAttributes)({ "service.name": "atbash-sdk" }),
+    processors: [new import_sdk_logs.BatchLogRecordProcessor({ exporter: logExporter })]
+  });
+  configureEvents(loggerProvider.getLogger("atbash-sdk"), {
+    source: config.source ?? defaultSource,
+    hashAgentKey: config.hashAgentKey ?? defaultAgentKeyHasher
+  });
 }
 function recordCall(functionName, source, agentPubkey) {
   autoInit();
@@ -690,7 +804,10 @@ function recordCall(functionName, source, agentPubkey) {
   callCounter.add(1, {
     "function.name": functionName,
     source: source ?? defaultSource,
-    ...agentPubkey && { "agent.pubkey": agentPubkey }
+    // Hashed on this path too. The counters and the events export to the same
+    // place in the same request, so a raw key here would make hashing it on
+    // the event beside it pointless.
+    ...agentPubkey && { "agent.hash": hashAgentKeyOrDrop(agentPubkey) }
   });
 }
 function recordDuration(functionName, durationMs, status, source) {
@@ -702,15 +819,16 @@ function recordDuration(functionName, durationMs, status, source) {
   });
 }
 async function flushTelemetry() {
-  if (!meterProvider) return;
-  await meterProvider.forceFlush();
+  await Promise.all([meterProvider?.forceFlush(), loggerProvider?.forceFlush()]);
 }
 async function shutdownTelemetry() {
-  if (!meterProvider) return;
-  await meterProvider.shutdown();
+  await Promise.all([meterProvider?.shutdown(), loggerProvider?.shutdown()]);
   meterProvider = null;
+  loggerProvider = null;
   callCounter = null;
   durationHistogram = null;
+  counterHasher = null;
+  configureEvents(null);
   defaultSource = "sdk";
   sourceExplicitlySet = false;
   requestedExportIntervalMs = void 0;
@@ -812,6 +930,13 @@ function resolveConstructorChain(options) {
   }
   return chainForNetwork(options.network ?? forcedChainNetwork() ?? "private");
 }
+function errorDetail(err) {
+  if (!(err instanceof AtbashAPIError)) return {};
+  return {
+    errorStatus: err.status,
+    ...err.path ? { errorPath: err.path } : {}
+  };
+}
 var Atbash = class _Atbash {
   auth;
   endpoint;
@@ -1022,7 +1147,7 @@ config.json still holds an "agentKey" (${identity}), but a settings file no long
    *
    * @param logger - The host logger, when one was supplied.
    */
-  static warnOnStrandedKey(logger) {
+  static warnOnStrandedKey(logger2) {
     const stranded = strandedAgentKey();
     if (!stranded) return;
     let identity;
@@ -1031,7 +1156,7 @@ config.json still holds an "agentKey" (${identity}), but a settings file no long
     } catch {
       identity = "(unreadable)";
     }
-    logger?.warn?.(
+    logger2?.warn?.(
       `[atbash] "agentKey" in config.json is ignored \u2014 settings do not choose the signing key. It holds ${identity}; this client signs as the key file or ATBASH_AGENT_KEY instead. Move it into the key file, or delete the field, to silence this.`
     );
   }
@@ -1790,10 +1915,28 @@ config.json still holds an "agentKey" (${identity}), but a settings file no long
     recordCall(name, void 0, agentPubkey);
     try {
       const result = await fn();
-      recordDuration(name, performance.now() - start, "success");
+      const durationMs = performance.now() - start;
+      recordDuration(name, durationMs, "success");
+      recordEvent({
+        functionName: name,
+        durationMs,
+        status: "success",
+        agentPubkey,
+        chain: this.blockchainRid
+      });
       return result;
     } catch (err) {
-      recordDuration(name, performance.now() - start, "error");
+      const durationMs = performance.now() - start;
+      recordDuration(name, durationMs, "error");
+      recordEvent({
+        functionName: name,
+        durationMs,
+        status: "error",
+        agentPubkey,
+        chain: this.blockchainRid,
+        errorClass: err instanceof Error ? err.constructor.name : typeof err,
+        ...errorDetail(err)
+      });
       throw err;
     }
   }
@@ -2286,6 +2429,47 @@ async function scanMemoryBatch(entries, auth, opts) {
   return results;
 }
 
+// src-ts/memory/telemetry.ts
+function metricName(action) {
+  return `memory.${action}`;
+}
+function recordMemoryCall(action, startedAt, agentPubkey, status, err) {
+  const name = metricName(action);
+  const durationMs = performance.now() - startedAt;
+  recordCall(name, void 0, agentPubkey);
+  recordDuration(name, durationMs, status);
+  recordEvent({
+    functionName: name,
+    durationMs,
+    status,
+    agentPubkey,
+    ...err !== void 0 && {
+      errorClass: err instanceof Error ? err.constructor.name : typeof err,
+      // The chain transport is where the failures are, so the status and the
+      // route are the whole of what makes one diagnosable.
+      ...err instanceof AtbashAPIError && {
+        errorStatus: err.status,
+        ...err.path ? { errorPath: err.path } : {}
+      }
+    }
+  });
+}
+function recordMemoryGuard(verdict, committed, blocked, startedAt, agentPubkey) {
+  const durationMs = performance.now() - startedAt;
+  recordCall("memory.guard", void 0, agentPubkey);
+  recordDuration("memory.guard", durationMs, blocked ? "error" : "success");
+  recordEvent({
+    functionName: "memory.guard",
+    durationMs,
+    // A block is the outcome worth keeping every one of; the sampler keeps
+    // errors whole, and a refused write is an error from the agent's side.
+    status: blocked ? "error" : "success",
+    agentPubkey,
+    errorClass: blocked ? `memory-blocked:${verdict}` : void 0,
+    outcome: `${verdict}/${committed ? "committed" : "uncommitted"}`
+  });
+}
+
 // src-ts/memory/transport.ts
 var DEFAULT_TIMEOUT_MS = 12e4;
 function transport(opts) {
@@ -2298,24 +2482,39 @@ async function failure(action, resp) {
   );
 }
 async function memoryQuery(action, auth, blockchainRid, opts, filePath, extra = {}) {
+  const start = performance.now();
   const params = new URLSearchParams({ action, agent: auth.pubkey });
   if (filePath !== null) params.set("file_path", filePath);
   for (const [key, value] of Object.entries(extra)) params.set(key, String(value));
-  const resp = await transport(opts).get(
-    `/api/risk-engine?${params.toString()}`,
-    void 0,
-    agentAuthHeaders(auth, blockchainRid)
-  );
-  if (resp.status !== 200) throw await failure(action, resp);
-  return resp.json();
+  try {
+    const resp = await transport(opts).get(
+      `/api/risk-engine?${params.toString()}`,
+      void 0,
+      agentAuthHeaders(auth, blockchainRid)
+    );
+    if (resp.status !== 200) throw await failure(action, resp);
+    const body = await resp.json();
+    recordMemoryCall(action, start, auth.pubkey, "success");
+    return body;
+  } catch (err) {
+    recordMemoryCall(action, start, auth.pubkey, "error", err);
+    throw err;
+  }
 }
 async function memorySubmit(action, auth, opts, signedField, signedHex) {
-  const resp = await transport(opts).post("/api/risk-engine", {
-    action,
-    agentPubkey: auth.pubkey,
-    [signedField]: signedHex
-  });
-  if (resp.status !== 200) throw await failure(action, resp);
+  const start = performance.now();
+  try {
+    const resp = await transport(opts).post("/api/risk-engine", {
+      action,
+      agentPubkey: auth.pubkey,
+      [signedField]: signedHex
+    });
+    if (resp.status !== 200) throw await failure(action, resp);
+    recordMemoryCall(action, start, auth.pubkey, "success");
+  } catch (err) {
+    recordMemoryCall(action, start, auth.pubkey, "error", err);
+    throw err;
+  }
 }
 
 // src-ts/memory/chain.ts
@@ -2569,8 +2768,8 @@ function classifyMemoryWrite(event, ctx, opts = {}) {
 var import_node_fs4 = require("fs");
 var import_node_os4 = __toESM(require("os"));
 var import_node_path4 = __toESM(require("path"));
-function emitDebugProbe(event, ctx, memEntry, logger) {
-  if (!logger?.info) return;
+function emitDebugProbe(event, ctx, memEntry, logger2) {
+  if (!logger2?.info) return;
   const ev = event ?? {};
   const c = ctx ?? {};
   const argsCandidate = ev.params ?? c.params ?? ev.args ?? c.args ?? ev.arguments ?? c.arguments;
@@ -2580,7 +2779,7 @@ function emitDebugProbe(event, ctx, memEntry, logger) {
   const editsArr = Array.isArray(argsObj.edits) ? argsObj.edits : null;
   const firstEditKeys = editsArr && editsArr[0] && typeof editsArr[0] === "object" ? Object.keys(editsArr[0]).slice(0, 10) : null;
   const tool = ev.toolName ?? c.tool?.name ?? c.toolName ?? c.name ?? "(none)";
-  logger.info("[atbash][probe] before_tool_call", {
+  logger2.info("[atbash][probe] before_tool_call", {
     toolName: tool,
     eventKeys: Object.keys(ev).slice(0, 20),
     ctxKeys: Object.keys(c).slice(0, 20),
@@ -2608,6 +2807,20 @@ async function resultingDocument(memEntry, event, ctx) {
   return native.applyMemoryEdits(current, edits);
 }
 async function guardMemoryWrite(input) {
+  const start = performance.now();
+  const result = await guardMemoryWriteInner(input);
+  if (result.handled) {
+    recordMemoryGuard(
+      result.scanResult?.verdict ?? "unscanned",
+      result.committed === true,
+      result.decision?.block === true,
+      start,
+      input.auth.pubkey
+    );
+  }
+  return result;
+}
+async function guardMemoryWriteInner(input) {
   const {
     event,
     ctx,
@@ -2621,7 +2834,7 @@ async function guardMemoryWrite(input) {
     toolNames,
     enforce = true,
     debug = false,
-    logger,
+    logger: logger2,
     agentHomeDirs,
     memoryRoot
   } = input;
@@ -2630,7 +2843,7 @@ async function guardMemoryWrite(input) {
     memEntry = classifyMemoryWrite(event, ctx, { patterns, toolNames });
   } catch (err) {
     const why = err instanceof Error ? err.message : String(err);
-    logger?.warn?.("[atbash] memory classifier refused this tool call's input", { reason: why });
+    logger2?.warn?.("[atbash] memory classifier refused this tool call's input", { reason: why });
     if (!enforce) return { handled: false };
     return {
       handled: true,
@@ -2641,14 +2854,14 @@ async function guardMemoryWrite(input) {
       }
     };
   }
-  if (debug) emitDebugProbe(event, ctx, memEntry, logger);
+  if (debug) emitDebugProbe(event, ctx, memEntry, logger2);
   if (!memEntry) return { handled: false };
   let document;
   try {
     document = await resultingDocument(memEntry, event, ctx);
   } catch (err) {
     const reason = err instanceof Error ? err.message : String(err);
-    logger?.warn?.("[atbash] memory edit could not be applied", { path: memEntry.key, reason });
+    logger2?.warn?.("[atbash] memory edit could not be applied", { path: memEntry.key, reason });
     return {
       handled: true,
       decision: enforce ? { allow: false, block: true, reason: `Memory edit refused: ${reason}` } : { allow: true, reason: `Memory edit refused: ${reason}` },
@@ -2666,7 +2879,7 @@ async function guardMemoryWrite(input) {
     });
   } catch (err) {
     const reason = err instanceof Error ? err.message : String(err);
-    logger?.warn?.("[atbash] memory scan failed", {
+    logger2?.warn?.("[atbash] memory scan failed", {
       path: memEntry.key,
       reason
     });
@@ -2676,7 +2889,7 @@ async function guardMemoryWrite(input) {
     };
   }
   if (scanResult.verdict === "red") {
-    logger?.warn?.("[atbash] memory BLOCK", {
+    logger2?.warn?.("[atbash] memory BLOCK", {
       path: memEntry.key,
       reason: scanResult.reason
     });
@@ -2698,7 +2911,7 @@ async function guardMemoryWrite(input) {
   }
   const filePath = memorySlotFor(memEntry.key, memoryRoot, agentHomeDirs);
   if (filePath === null) {
-    logger?.info?.(
+    logger2?.info?.(
       `[atbash] memory scanned but not recorded \u2014 ${memEntry.key} is not inside an agent home (${(agentHomeDirs ?? native.defaultAgentHomeDirs()).join(", ")}) in your home directory, so it has no chain slot of its own.`,
       { path: memEntry.key, verdict: scanResult.verdict, score: scanResult.score }
     );
@@ -2720,7 +2933,7 @@ async function guardMemoryWrite(input) {
     });
   } catch (err) {
     const reason = err instanceof Error ? err.message : String(err);
-    logger?.warn?.("[atbash] memory commit to chain failed", {
+    logger2?.warn?.("[atbash] memory commit to chain failed", {
       path: memEntry.key,
       filePath,
       reason
@@ -2732,7 +2945,7 @@ async function guardMemoryWrite(input) {
       committed: false
     };
   }
-  logger?.info?.(
+  logger2?.info?.(
     scanResult.verdict === "yellow" ? "[atbash] memory ALLOW (yellow, low score)" : "[atbash] memory ALLOW",
     {
       path: memEntry.key,
@@ -3645,6 +3858,7 @@ function diffMemorySnapshots(before, after) {
   classifyMemoryWrite,
   columnAad,
   commitMemoryVersion,
+  configureEvents,
   containsEvasionCharacters,
   containsSecret,
   createFileLogger,
@@ -3660,6 +3874,7 @@ function diffMemorySnapshots(before, after) {
   encryptForOrg,
   encryptMemoryContent,
   encryptedLength,
+  eventsAreOn,
   flushTelemetry,
   generateKeypair,
   getActiveAgentMemory,
@@ -3688,6 +3903,7 @@ function diffMemorySnapshots(before, after) {
   pubkeyToHex,
   recordCall,
   recordDuration,
+  recordEvent,
   redactJsonStrings,
   redactSecrets,
   resolve,