@atbash/sdk 0.7.0 → 0.7.1

package/dist/index.mjs

@@ -3046,24 +3046,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
-import { readFileSync } from "fs";
+import { existsSync, readFileSync } from "fs";
+
+// src-ts/key-path.ts
 import { homedir } from "os";
 import { join } from "path";
-var DEFAULT_KEY_PATH_REL = ".config/atbash/guard-client-key";
-function resolveKeyPath(input) {
-  if (input) return expandHome(input);
-  const home = process.env.HOME || homedir() || "";
-  return 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 || homedir() || "";
 }
 function expandHome(p) {
   if (!p.startsWith("~/")) return p;
-  const home = process.env.HOME || homedir() || "";
-  return join(home, p.slice(2));
+  return join(home(), p.slice(2));
+}
+function keyPathCandidates() {
+  return KEY_FILENAMES.map((name2) => 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, existsSync);
 }
 function readKeyFile(keyPath) {
   const content = String(readFileSync(keyPath, "utf8") || "").trim();
@@ -3093,6 +3166,12 @@ function readKeyFile(keyPath) {
 }
 function loadAgentFromFile(keyPath) {
   const resolved = resolveKeyPath(keyPath);
+  if (!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);
 }
@@ -3138,8 +3217,8 @@ var durationHistogram = null;
 var defaultSource = "sdk";
 function isTelemetryOptedOut() {
   try {
-    const home = process.env.HOME || homedir2() || "";
-    const filePath = join2(home, ".config", "atbash", "telemetry.json");
+    const home2 = process.env.HOME || homedir2() || "";
+    const filePath = join2(home2, ".config", "atbash", "telemetry.json");
     const raw2 = readFileSync2(filePath, "utf-8").trim();
     if (!raw2) return false;
     const config2 = JSON.parse(raw2);
@@ -3217,7 +3296,7 @@ async function shutdownTelemetry() {
 // src-ts/userConfig.ts
 import {
   chmodSync,
-  existsSync,
+  existsSync as existsSync2,
   mkdirSync,
   readFileSync as readFileSync3,
   writeFileSync
@@ -3230,11 +3309,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 || homedir3() || "";
-  return join3(home, ".config", "atbash");
+  const home2 = process.env.HOME || homedir3() || "";
+  return join3(home2, ".config", "atbash");
 }
 function getConfigPath() {
   return join3(getConfigDir(), "config.json");
@@ -3242,7 +3322,7 @@ function getConfigPath() {
 function loadUserConfig() {
   try {
     const p = getConfigPath();
-    if (!existsSync(p)) return {};
+    if (!existsSync2(p)) return {};
     const raw2 = readFileSync3(p, "utf-8").trim();
     if (!raw2) return {};
     return JSON.parse(raw2);
@@ -3253,7 +3333,7 @@ function loadUserConfig() {
 }
 function saveUserConfig(config2) {
   const dir = getConfigDir();
-  if (!existsSync(dir)) {
+  if (!existsSync2(dir)) {
     mkdirSync(dir, { recursive: true, mode: 448 });
   }
   const filePath = getConfigPath();
@@ -3293,6 +3373,7 @@ var Atbash = class _Atbash {
   failClosed;
   /** Org key learned from the last agent-exists check, for this agent only. */
   _orgKeyFromChain = null;
+  debug;
   logger;
   http;
   /**
@@ -3306,6 +3387,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;
@@ -3315,8 +3398,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,
@@ -3324,6 +3409,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
@@ -3347,6 +3457,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
     });
   }
@@ -3446,11 +3559,15 @@ var Atbash = class _Atbash {
    * response bytes via the Rust core's `verifySignature`.
    */
   async judgeAction(action, context = "", options = {}) {
-    return this.track(
-      "judgeAction",
-      this.auth.pubkey,
-      () => this._judgeAction(action, context, options)
-    );
+    return this.track("judgeAction", this.auth.pubkey, async () => {
+      try {
+        return await this._judgeAction(action, context, options);
+      } catch (err) {
+        if (!isEncryptionStateMismatch(err)) throw err;
+        this._orgKeyFromChain = null;
+        return await this._judgeAction(action, context, options);
+      }
+    });
   }
   async _judgeAction(action, context, options) {
     if (!action?.trim()) {
@@ -3588,8 +3705,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
           );
         }
@@ -3641,16 +3759,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 };
   }
@@ -3991,8 +4131,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) {
@@ -4124,6 +4283,10 @@ async function safeText(resp) {
 function errorMessage(err) {
   return err instanceof Error ? err.message : String(err);
 }
+function isEncryptionStateMismatch(err) {
+  const msg = errorMessage(err);
+  return msg.includes("must be a valid encryption envelope") || msg.includes("must be plaintext");
+}
 function stringifyArgs(args) {
   if (args === null || args === void 0) return "";
   if (typeof args === "string") return args;
@@ -4134,9 +4297,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
@@ -4179,6 +4342,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);
@@ -4204,6 +4378,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,
@@ -42354,6 +42541,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));
 }
@@ -42383,7 +42574,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");
@@ -42821,7 +43016,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
+      });
     }
   }
   /**
@@ -43049,6 +43247,7 @@ function diffMemorySnapshots(before, after) {
 export {
   Atbash,
   AtbashAPIError,
+  BOOT_SYNC_HINT,
   DEFAULT_BLOCKCHAIN_RID,
   DEFAULT_CHROMIA_NODE_URLS,
   DEFAULT_ENDPOINT,
@@ -43056,11 +43255,16 @@ export {
   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,
@@ -43095,6 +43299,7 @@ export {
   isEnvelope,
   isValidPrivateKey,
   keyFingerprintOf,
+  keyPathCandidates,
   loadAgent,
   loadAgentFromFile,
   loadUserConfig,