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

package/dist/index.mjs

@@ -374,9 +374,19 @@ function loadAgentFromFile(keyPath) {
 }
 
 // src-ts/normalize.ts
+function wireText(raw, fallback = "") {
+  if (raw === null || raw === void 0) return fallback;
+  if (typeof raw === "object" || typeof raw === "function") return fallback;
+  return String(raw);
+}
+function wireNumber(raw, fallback = 0) {
+  if (raw === null || raw === void 0) return fallback;
+  if (typeof raw === "object" || typeof raw === "function") return fallback;
+  return Number(raw);
+}
 function normalizeVerdict(raw) {
   if (raw === null || raw === void 0) return "No verdict";
-  const v = String(raw).trim().toUpperCase();
+  const v = wireText(raw).trim().toUpperCase();
   if (v === "ALLOW" || v === "GREEN") return "ALLOW";
   if (v === "HOLD" || v === "YELLOW") return "HOLD";
   if (v === "BLOCK" || v === "RED") return "BLOCK";
@@ -386,7 +396,7 @@ function normalizeActionType(raw) {
   return typeof raw === "string" ? raw.trim().toLowerCase() : "";
 }
 function normalizeStatus(raw) {
-  const s = String(raw ?? "").toLowerCase();
+  const s = wireText(raw).toLowerCase();
   if (s === "pending" || s === "answered" || s === "error") return s;
   return "error";
 }
@@ -473,6 +483,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
 import { readFileSync as readFileSync2 } from "fs";
 import { homedir as homedir2 } from "os";
@@ -486,7 +549,11 @@ import {
   MeterProvider,
   PeriodicExportingMetricReader
 } from "@opentelemetry/sdk-metrics";
+import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
+import { BatchLogRecordProcessor, LoggerProvider } from "@opentelemetry/sdk-logs";
+import { createHash } from "crypto";
 var meterProvider = null;
+var loggerProvider = null;
 var callCounter = null;
 var durationHistogram = null;
 var defaultSource = "sdk";
@@ -513,6 +580,41 @@ function autoInit() {
   if (isTelemetryOptedOut()) return;
   setupTelemetry({ enabled: true });
 }
+function defaultAgentKeyHasher(pubkeyHex) {
+  return 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;
@@ -524,16 +626,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 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
@@ -565,6 +671,21 @@ function setupTelemetry(config) {
     description: "SDK function execution duration",
     unit: "ms"
   });
+  counterHasher = config.hashAgentKey ?? defaultAgentKeyHasher;
+  const logExporter = new 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 LoggerProvider({
+    resource: resourceFromAttributes({ "service.name": "atbash-sdk" }),
+    processors: [new BatchLogRecordProcessor({ exporter: logExporter })]
+  });
+  configureEvents(loggerProvider.getLogger("atbash-sdk"), {
+    source: config.source ?? defaultSource,
+    hashAgentKey: config.hashAgentKey ?? defaultAgentKeyHasher
+  });
 }
 function recordCall(functionName, source, agentPubkey) {
   autoInit();
@@ -572,7 +693,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) {
@@ -584,15 +708,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;
@@ -700,6 +825,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;
@@ -910,7 +1042,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;
@@ -919,7 +1051,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.`
     );
   }
@@ -1161,15 +1293,15 @@ config.json still holds an "agentKey" (${identity}), but a settings file no long
       verdict: normalizeVerdict(data.verdict),
       allow: this.executable(data),
       actionType: normalizeActionType(data.action_type),
-      reason: String(data.reason ?? ""),
-      confidence: Number(data.confidence ?? 0),
-      provider: String(data.provider ?? ""),
-      latencyMs: Number(data.latency_ms ?? 0),
-      toolCallId: String(data.tool_call_id ?? logResult.toolCallId),
+      reason: wireText(data.reason),
+      confidence: wireNumber(data.confidence),
+      provider: wireText(data.provider),
+      latencyMs: wireNumber(data.latency_ms),
+      toolCallId: wireText(data.tool_call_id, logResult.toolCallId),
       onChain: Boolean(data.on_chain),
       enforced: Boolean(data.enforced),
-      enforcementMode: String(data.enforcement_mode ?? ""),
-      status: String(data.status ?? ""),
+      enforcementMode: wireText(data.enforcement_mode),
+      status: wireText(data.status),
       score,
       refusal: explicitRefusal(data)
     };
@@ -1393,8 +1525,8 @@ config.json still holds an "agentKey" (${identity}), but a settings file no long
         status: normalizeStatus(data.status),
         verdict: normalizeVerdict(data.verdict),
         allow: this.executable(data),
-        reason: String(data.reason ?? ""),
-        judgmentId: String(data.judgmentId ?? judgmentId),
+        reason: wireText(data.reason),
+        judgmentId: wireText(data.judgmentId, judgmentId),
         onChain: optBool(data.onChain),
         cached: optBool(data.cached),
         responseTimeMs: optNumber(data.responseTimeMs)
@@ -1678,10 +1810,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;
     }
   }
@@ -1983,10 +2133,12 @@ function isRecord2(v) {
 }
 function optString(v) {
   if (v === null || v === void 0) return void 0;
+  if (typeof v === "object" || typeof v === "function") return void 0;
   return typeof v === "string" ? v : String(v);
 }
 function optNumber(v) {
   if (v === null || v === void 0) return void 0;
+  if (typeof v === "object" || typeof v === "function") return void 0;
   const n = Number(v);
   return Number.isFinite(n) ? n : void 0;
 }
@@ -2174,6 +2326,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) {
@@ -2186,24 +2379,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
@@ -2457,8 +2665,8 @@ function classifyMemoryWrite(event, ctx, opts = {}) {
 import { promises as fs } from "fs";
 import os from "os";
 import path from "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;
@@ -2468,7 +2676,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),
@@ -2496,6 +2704,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,
@@ -2509,7 +2731,7 @@ async function guardMemoryWrite(input) {
     toolNames,
     enforce = true,
     debug = false,
-    logger,
+    logger: logger2,
     agentHomeDirs,
     memoryRoot
   } = input;
@@ -2518,7 +2740,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,
@@ -2529,14 +2751,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}` },
@@ -2554,7 +2776,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
     });
@@ -2564,7 +2786,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
     });
@@ -2586,7 +2808,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 }
     );
@@ -2608,7 +2830,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
@@ -2620,7 +2842,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,
@@ -3532,6 +3754,7 @@ export {
   classifyMemoryWrite,
   columnAad,
   commitMemoryVersion,
+  configureEvents,
   containsEvasionCharacters,
   containsSecret,
   createFileLogger,
@@ -3547,6 +3770,7 @@ export {
   encryptForOrg,
   encryptMemoryContent,
   encryptedLength,
+  eventsAreOn,
   flushTelemetry,
   generateKeypair,
   getActiveAgentMemory,
@@ -3575,6 +3799,7 @@ export {
   pubkeyToHex,
   recordCall,
   recordDuration,
+  recordEvent,
   redactJsonStrings,
   redactSecrets,
   resolve,