@atbash/sdk 0.10.6-dev.0 → 0.10.9-dev.0

package/dist/index.js

@@ -2856,6 +2856,7 @@ var src_ts_exports = {};
 __export(src_ts_exports, {
   Atbash: () => Atbash,
   AtbashAPIError: () => AtbashAPIError,
+  BOOT_SYNC_HINT: () => BOOT_SYNC_HINT,
   DEFAULT_BLOCKCHAIN_RID: () => DEFAULT_BLOCKCHAIN_RID,
   DEFAULT_CHROMIA_NODE_URLS: () => DEFAULT_CHROMIA_NODE_URLS,
   DEFAULT_ENDPOINT: () => DEFAULT_ENDPOINT,
@@ -2863,11 +2864,16 @@ __export(src_ts_exports, {
   DEFAULT_MEMORY_READ_TOOL_NAMES: () => DEFAULT_MEMORY_READ_TOOL_NAMES,
   DEFAULT_MEMORY_WRITE_TOOL_NAMES: () => DEFAULT_MEMORY_WRITE_TOOL_NAMES,
   EciesDomain: () => EciesDomain,
+  HttpClient: () => HttpClient,
+  HttpTransportError: () => HttpTransportError,
+  KEY_FILENAMES: () => KEY_FILENAMES,
   MemoryGuardManager: () => MemoryGuardManager,
   MemoryIntegrityError: () => MemoryIntegrityError,
   PointerStore: () => PointerStore,
   SignatureVerificationError: () => SignatureVerificationError,
+  bootSyncFailureLine: () => bootSyncFailureLine,
   buildAllowedJudgeHosts: () => buildAllowedJudgeHosts,
+  chooseKeyPath: () => chooseKeyPath,
   claimHashHex: () => claimHashHex,
   classifyMemoryRead: () => classifyMemoryRead,
   classifyMemoryWrite: () => classifyMemoryWrite,
@@ -2902,6 +2908,7 @@ __export(src_ts_exports, {
   isEnvelope: () => isEnvelope,
   isValidPrivateKey: () => isValidPrivateKey,
   keyFingerprintOf: () => keyFingerprintOf,
+  keyPathCandidates: () => keyPathCandidates,
   loadAgent: () => loadAgent,
   loadAgentFromFile: () => loadAgentFromFile,
   loadUserConfig: () => loadUserConfig,
@@ -3129,24 +3136,97 @@ var HttpClient = class {
     });
   }
   async fetch(url, init4) {
-    return fetch(url, { ...init4, signal: AbortSignal.timeout(this.timeoutMs) });
+    try {
+      return await fetch(url, {
+        ...init4,
+        signal: AbortSignal.timeout(this.timeoutMs)
+      });
+    } catch (err) {
+      throw classifyTransportError(err, url, init4.method ?? "GET", this.timeoutMs);
+    }
   }
 };
+var HttpTransportError = class extends Error {
+  kind;
+  constructor(kind, message, options) {
+    super(message, options);
+    this.name = "HttpTransportError";
+    this.kind = kind;
+  }
+};
+function classifyTransportError(err, url, method, timeoutMs) {
+  const name2 = err instanceof Error ? err.name : "";
+  const cause = err instanceof Error ? err.cause : void 0;
+  const code2 = cause && typeof cause === "object" && "code" in cause ? String(cause.code) : "";
+  if (name2 === "TimeoutError") {
+    return new HttpTransportError(
+      "timeout",
+      `${method} ${url} did not respond within ${timeoutMs} ms \u2014 the judge may be slow to boot or the LLM is under load; retry in a moment`,
+      { cause: err }
+    );
+  }
+  if (name2 === "AbortError") {
+    return new HttpTransportError(
+      "aborted",
+      `${method} ${url} was cancelled by the caller`,
+      { cause: err }
+    );
+  }
+  if (code2 === "ENOTFOUND" || code2 === "EAI_AGAIN") {
+    return new HttpTransportError(
+      "dns",
+      `could not resolve the judge hostname (${url}) \u2014 check the endpoint and DNS`,
+      { cause: err }
+    );
+  }
+  if (code2 === "ECONNREFUSED") {
+    return new HttpTransportError(
+      "connect_refused",
+      `judge refused the connection (${url}) \u2014 the service may be down or restarting`,
+      { cause: err }
+    );
+  }
+  if (code2 === "ECONNRESET" || code2 === "EPIPE") {
+    return new HttpTransportError(
+      "connection_reset",
+      `judge dropped the connection mid-request (${url}) \u2014 retry once`,
+      { cause: err }
+    );
+  }
+  return new HttpTransportError(
+    "unknown",
+    `${method} ${url} failed: ${err instanceof Error ? err.message : String(err)}`,
+    { cause: err }
+  );
+}
 
 // src-ts/keyLoader.ts
 var import_node_fs = require("fs");
+
+// src-ts/key-path.ts
 var import_node_os = require("os");
 var import_node_path = require("path");
-var DEFAULT_KEY_PATH_REL = ".config/atbash/guard-client-key";
-function resolveKeyPath(input) {
-  if (input) return expandHome(input);
-  const home = process.env.HOME || (0, import_node_os.homedir)() || "";
-  return (0, import_node_path.join)(home, DEFAULT_KEY_PATH_REL);
+var KEY_DIR_REL = ".config/atbash";
+var KEY_FILENAMES = ["guard-client-key", "atbash-client-key"];
+function home() {
+  return process.env.HOME || (0, import_node_os.homedir)() || "";
 }
 function expandHome(p) {
   if (!p.startsWith("~/")) return p;
-  const home = process.env.HOME || (0, import_node_os.homedir)() || "";
-  return (0, import_node_path.join)(home, p.slice(2));
+  return (0, import_node_path.join)(home(), p.slice(2));
+}
+function keyPathCandidates() {
+  return KEY_FILENAMES.map((name2) => (0, import_node_path.join)(home(), KEY_DIR_REL, name2));
+}
+function chooseKeyPath(input, exists) {
+  if (input) return expandHome(input);
+  const candidates = keyPathCandidates();
+  return candidates.find(exists) ?? candidates[0];
+}
+
+// src-ts/keyLoader.ts
+function resolveKeyPath(input) {
+  return chooseKeyPath(input, import_node_fs.existsSync);
 }
 function readKeyFile(keyPath) {
   const content = String((0, import_node_fs.readFileSync)(keyPath, "utf8") || "").trim();
@@ -3176,6 +3256,12 @@ function readKeyFile(keyPath) {
 }
 function loadAgentFromFile(keyPath) {
   const resolved = resolveKeyPath(keyPath);
+  if (!(0, import_node_fs.existsSync)(resolved)) {
+    const looked = keyPath ? [resolved] : keyPathCandidates();
+    throw new Error(
+      `atbash key file not found. Looked for: ${looked.join(", ")}`
+    );
+  }
   const { privKey } = readKeyFile(resolved);
   return native.loadAgent(privKey);
 }
@@ -3218,8 +3304,8 @@ var durationHistogram = null;
 var defaultSource = "sdk";
 function isTelemetryOptedOut() {
   try {
-    const home = process.env.HOME || (0, import_node_os2.homedir)() || "";
-    const filePath = (0, import_node_path2.join)(home, ".config", "atbash", "telemetry.json");
+    const home2 = process.env.HOME || (0, import_node_os2.homedir)() || "";
+    const filePath = (0, import_node_path2.join)(home2, ".config", "atbash", "telemetry.json");
     const raw2 = (0, import_node_fs2.readFileSync)(filePath, "utf-8").trim();
     if (!raw2) return false;
     const config2 = JSON.parse(raw2);
@@ -3304,11 +3390,12 @@ var ENV_MAP = {
   judgeEndpoint: "ATBASH_ENDPOINT",
   blockchainRid: "ATBASH_BLOCKCHAIN_RID",
   provider: "ATBASH_PROVIDER",
-  providerModel: "ATBASH_PROVIDER_MODEL"
+  providerModel: "ATBASH_PROVIDER_MODEL",
+  debug: "ATBASH_DEBUG"
 };
 function getConfigDir() {
-  const home = process.env.HOME || (0, import_node_os3.homedir)() || "";
-  return (0, import_node_path3.join)(home, ".config", "atbash");
+  const home2 = process.env.HOME || (0, import_node_os3.homedir)() || "";
+  return (0, import_node_path3.join)(home2, ".config", "atbash");
 }
 function getConfigPath() {
   return (0, import_node_path3.join)(getConfigDir(), "config.json");
@@ -3367,6 +3454,7 @@ var Atbash = class _Atbash {
   failClosed;
   /** Org key learned from the last agent-exists check, for this agent only. */
   _orgKeyFromChain = null;
+  debug;
   logger;
   http;
   /**
@@ -3380,6 +3468,8 @@ var Atbash = class _Atbash {
    * server-side replay protection windows never expire it mid-session.
    */
   _authBearer = null;
+  /** Guards `logEnvironmentOnce` — hosts construct several clients. */
+  static environmentLogged = false;
   constructor(privkey, options = {}) {
     this.auth = native.loadAgent(privkey);
     this.endpoint = (options.endpoint ?? DEFAULT_ENDPOINT).replace(/\/+$/, "") || DEFAULT_ENDPOINT;
@@ -3389,8 +3479,10 @@ var Atbash = class _Atbash {
     this.verifyPubKey = options.verifyPubKey;
     this.orgEncryptionPubKey = options.orgEncryptionPubKey;
     this.failClosed = options.failClosed !== false;
+    this.debug = options.debug === true;
     this.logger = options.logger ?? {};
-    this.http = new HttpClient(this.endpoint, options.timeoutMs ?? 3e4);
+    this.http = new HttpClient(this.endpoint, options.timeoutMs ?? 6e4);
+    this.logEnvironmentOnce();
     if (this.endpoint !== DEFAULT_ENDPOINT) {
       this.logger.warn?.("[atbash] running on non-default judge endpoint", {
         endpoint: this.endpoint,
@@ -3398,6 +3490,31 @@ var Atbash = class _Atbash {
       });
     }
   }
+  /**
+   * Say which environment this build talks to, once per process.
+   *
+   * The endpoint and both chain RIDs are compiled in, chosen by the npm tag,
+   * and no configuration repoints a released build. So installing the build
+   * for the wrong environment is invisible: the plugin loads, the hook fires,
+   * and every judge call fails because the agent does not exist on the chain
+   * this build targets. Organisation names are not unique across environments
+   * either, so an org resolving is not evidence the build is right.
+   */
+  logEnvironmentOnce() {
+    if (_Atbash.environmentLogged) return;
+    _Atbash.environmentLogged = true;
+    const brief = (rid) => rid ? `${rid.slice(0, 8)}\u2026` : "(unset)";
+    this.logger.info?.(
+      `[atbash] environment \u2014 judge=${this.endpoint} publicChain=${brief(native.DEFAULT_BLOCKCHAIN_RID)} privateChain=${brief(native.DEFAULT_PRIVATE_BLOCKCHAIN_RID)} activeChain=${brief(this.blockchainRid)} responseSignatureCheck=${this.verifyPubKey ? "on" : "off"}`,
+      {
+        judgeEndpoint: this.endpoint,
+        publicBlockchainRid: native.DEFAULT_BLOCKCHAIN_RID,
+        privateBlockchainRid: native.DEFAULT_PRIVATE_BLOCKCHAIN_RID,
+        activeBlockchainRid: this.blockchainRid,
+        responseSignatureCheck: Boolean(this.verifyPubKey)
+      }
+    );
+  }
   /**
    * Construct from resolved config: explicit overrides → env vars → the
    * `~/.config/atbash/config.json` file (see userConfig.resolve). The private
@@ -3421,6 +3538,9 @@ var Atbash = class _Atbash {
       orgName: options.orgName,
       verifyPubKey: validated.verifyPubKey ?? void 0,
       failClosed: options.failClosed,
+      // ATBASH_DEBUG lets an operator turn diagnostics on without editing a
+      // host's plugin config, which is usually the harder half.
+      debug: options.debug ?? /^(1|true|yes)$/i.test(resolve("debug")),
       logger: options.logger
     });
   }
@@ -3666,8 +3786,9 @@ var Atbash = class _Atbash {
       });
       if (result.verdict === "No verdict") {
         if (result.status !== "logged") {
-          return this.fail(
+          return this.failJudge(
             `judge returned no verdict without an audit-tier marker (status: ${result.status || "absent"})`,
+            void 0,
             result.toolCallId
           );
         }
@@ -3719,16 +3840,38 @@ var Atbash = class _Atbash {
           toolCallId: result.toolCallId
         };
       }
-      return this.fail(
+      return this.failJudge(
         "unrecognized action_type from judge",
+        void 0,
         result.toolCallId
       );
     } catch (err) {
-      const message = errorMessage(err);
-      this.logger.warn?.("[atbash] judge API failed", { reason: message });
-      return this.fail(message);
+      return this.failJudge(errorMessage(err), err);
     }
   }
+  /**
+   * One exit for every judge failure.
+   *
+   * Status and reason go in the *message*, not only in the meta object: hosts
+   * print the message and drop the meta, which is why this read as a bare
+   * "judge API failed" while the judge was answering with a precise reason.
+   * The response body follows only under `debug`, since it can echo the action.
+   */
+  failJudge(reason, cause, toolCallId) {
+    const api2 = cause instanceof AtbashAPIError ? cause : null;
+    const status = api2 ? ` status=${api2.status || "no-response"}` : "";
+    const body = this.debug && api2?.body ? ` body=${truncate(api2.body, 500)}` : "";
+    this.logger.warn?.(
+      `[atbash] judge API failed \u2014${status} reason=${truncate(reason, 300)}${body}`,
+      {
+        reason,
+        ...api2 ? { status: api2.status, body: api2.body } : {},
+        endpoint: this.endpoint,
+        ...toolCallId ? { toolCallId } : {}
+      }
+    );
+    return this.fail(reason, toolCallId);
+  }
   fail(reason, toolCallId) {
     return { allow: !this.failClosed, verdict: "ERROR", reason, toolCallId };
   }
@@ -4069,8 +4212,27 @@ var Atbash = class _Atbash {
       this.endpoint
     );
   }
-  /** Wrap a *transport* failure (fetch threw, no response) as an AtbashAPIError. */
+  /**
+   * Wrap a transport failure (fetch threw, no response) as an AtbashAPIError.
+   *
+   * `HttpTransportError.kind` names the cause; the message is already
+   * human-readable. `debug` echoes the original exception so operators can
+   * cross-reference with node / undici logs when a class doesn't match.
+   */
   transportError(err) {
+    if (err instanceof HttpTransportError) {
+      if (this.debug) {
+        this.logger.warn?.(
+          `[atbash] transport failed \u2014 kind=${err.kind}`,
+          {
+            kind: err.kind,
+            cause: err.cause instanceof Error ? err.cause.message : String(err.cause ?? ""),
+            endpoint: this.endpoint
+          }
+        );
+      }
+      return new AtbashAPIError(0, err.message, "", this.endpoint);
+    }
     return new AtbashAPIError(0, errorMessage(err), "", this.endpoint);
   }
   async json(resp) {
@@ -4216,9 +4378,9 @@ function stringifyArgs(args) {
   }
 }
 var MAX_ACTION_LEN = 4e3;
-function truncate(text) {
-  if (text.length <= MAX_ACTION_LEN) return text;
-  return text.slice(0, MAX_ACTION_LEN) + "\u2026";
+function truncate(text, limit = MAX_ACTION_LEN) {
+  if (text.length <= limit) return text;
+  return text.slice(0, limit) + "\u2026";
 }
 
 // src-ts/redact.ts
@@ -4261,6 +4423,17 @@ function verifyJudgeResponseSignature(bodyBytes, signatureHex, pubKeyHex) {
   };
 }
 
+// src-ts/memory/boot-sync-message.ts
+var BOOT_SYNC_HINT = "check the chain endpoint and orgName if the cause above does not explain it";
+function bootSyncFailureLine(cause) {
+  const reason = cause instanceof Error ? cause.message : String(cause);
+  const trimmed = reason.trim();
+  return trimmed ? `[atbash] boot memory sync failed: ${trimmed}` : (
+    // No cause to show: fall back to the advice rather than a bare colon.
+    `[atbash] boot memory sync failed \u2014 ${BOOT_SYNC_HINT}`
+  );
+}
+
 // src-ts/memory/crypto.ts
 async function deriveMemoryKey(privkey) {
   return native.deriveMemoryKey(privkey);
@@ -4286,6 +4459,19 @@ async function scanMemory(entry, auth, opts) {
     toolArgsJson: opts?.toolArgsJson ?? JSON.stringify({ key: entry.key, source: entry.source }),
     mode: "memory-scan"
   });
+  const knownAction = result.actionType === "allow" || result.actionType === "block" || result.actionType === "hold_for_user_confirm";
+  const missingVerdict = result.verdict === "No verdict" && result.status !== "logged";
+  const unknownAction = result.actionType !== "" && !knownAction;
+  if (missingVerdict || unknownAction) {
+    return {
+      safe: false,
+      verdict: "red",
+      reason: unknownAction ? `judge returned unrecognised action_type "${result.actionType}"` : "judge returned no verdict",
+      confidence: result.confidence,
+      score: native.defaultScoreForVerdict("red"),
+      toolCallId: result.toolCallId
+    };
+  }
   const verdict = native.mapVerdict(
     result.actionType,
     result.confidence,
@@ -42436,6 +42622,10 @@ var index = /* @__PURE__ */ getDefaultExportFromCjs(builtExports);
 
 // src-ts/memory/chain.ts
 var { createClient, encryption: encryption2, newSignatureProvider: newSignatureProvider2, Buffer: PolyBuffer } = index;
+var FAILOVER_CONFIG = {
+  strategy: "tryNextOnError",
+  attemptsPerEndpoint: 1
+};
 function toGtxBytes(bytes) {
   return PolyBuffer.from(new Uint8Array(bytes));
 }
@@ -42465,7 +42655,11 @@ function materializeChain(chainOpts) {
 }
 async function buildChainClient(chainOpts) {
   const { nodeUrls, blockchainRid } = materializeChain(chainOpts);
-  return createClient({ nodeUrlPool: [...nodeUrls], blockchainRid });
+  return createClient({
+    nodeUrlPool: [...nodeUrls],
+    blockchainRid,
+    failOverConfig: FAILOVER_CONFIG
+  });
 }
 function buildSigner(auth) {
   const privKeyBuf = Buffer.from(auth.privkey, "hex");
@@ -42903,7 +43097,10 @@ var MemoryGuardManager = class {
       await this.pointerStore.set(this.agentPubkeyHex, result.pointer);
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
-      this.logger.warn("[atbash] boot memory sync failed \u2014 check chain endpoint / orgName", { error: msg });
+      this.logger.warn(bootSyncFailureLine(err), {
+        error: msg,
+        hint: BOOT_SYNC_HINT
+      });
     }
   }
   /**
@@ -43132,6 +43329,7 @@ function diffMemorySnapshots(before, after) {
 0 && (module.exports = {
   Atbash,
   AtbashAPIError,
+  BOOT_SYNC_HINT,
   DEFAULT_BLOCKCHAIN_RID,
   DEFAULT_CHROMIA_NODE_URLS,
   DEFAULT_ENDPOINT,
@@ -43139,11 +43337,16 @@ function diffMemorySnapshots(before, after) {
   DEFAULT_MEMORY_READ_TOOL_NAMES,
   DEFAULT_MEMORY_WRITE_TOOL_NAMES,
   EciesDomain,
+  HttpClient,
+  HttpTransportError,
+  KEY_FILENAMES,
   MemoryGuardManager,
   MemoryIntegrityError,
   PointerStore,
   SignatureVerificationError,
+  bootSyncFailureLine,
   buildAllowedJudgeHosts,
+  chooseKeyPath,
   claimHashHex,
   classifyMemoryRead,
   classifyMemoryWrite,
@@ -43178,6 +43381,7 @@ function diffMemorySnapshots(before, after) {
   isEnvelope,
   isValidPrivateKey,
   keyFingerprintOf,
+  keyPathCandidates,
   loadAgent,
   loadAgentFromFile,
   loadUserConfig,