@atbash/sdk 0.9.2 → 0.10.0

package/dist/browser.mjs

@@ -40585,7 +40585,7 @@ function requireFailoverStrategies() {
     exports.createTimeoutPromise = createTimeoutPromise;
     const utils_12 = requireUtils$1();
     const httpUtil_1 = httpUtil;
-    const logger2 = __importStar2(logger$3);
+    const logger3 = __importStar2(logger$3);
     const http_utils_1 = httpUtils;
     function getUnreachableDuration(statusCode, error4) {
       if ((0, http_utils_1.isNetworkError)(error4)) {
@@ -40686,7 +40686,7 @@ function requireFailoverStrategies() {
         while (true) {
           if (groupedSuccessfulResponses.maxNumberOfEqualResponses() >= bftMajorityThreshold) {
             if (groupedSuccessfulResponses.numberOfDistinctResponses() > 1) {
-              logger2.warning(`Got disagreeing responses, but could still reach BFT majority`);
+              logger3.warning(`Got disagreeing responses, but could still reach BFT majority`);
             }
             return groupedSuccessfulResponses.majorityResponse();
           }
@@ -40724,7 +40724,7 @@ function requireFailoverStrategies() {
           if (!isError4 && !error4) {
             return { error: error4, statusCode, rspBody, transactionTimestamp };
           }
-          logger2.info(`${method} request failed on ${endpoint.url}. Attempt: ${attempt + 1} / ${config2.attemptsPerEndpoint}`);
+          logger3.info(`${method} request failed on ${endpoint.url}. Attempt: ${attempt + 1} / ${config2.attemptsPerEndpoint}`);
           yield (0, utils_12.sleep)(config2.attemptInterval);
         }
         return { error: error4, statusCode, rspBody, transactionTimestamp };
@@ -40760,7 +40760,7 @@ function requireFailoverStrategies() {
             if (isServerError) {
               const duration = getUnreachableDuration(statusCode !== null && statusCode !== void 0 ? statusCode : void 0, response.error);
               nodeManager2.makeNodeUnavailable(node2.url, duration);
-              logger2.info(`request failed with server error on ${node2.url} trying next node`);
+              logger3.info(`request failed with server error on ${node2.url} trying next node`);
               break;
             }
             if (isClientError) {
@@ -40768,11 +40768,11 @@ function requireFailoverStrategies() {
                 return { error: error4, statusCode, rspBody, transactionTimestamp };
               }
               if (!nodeManager2.useStickyNode) {
-                logger2.info(`request failed client error on ${node2.url} trying next node`);
+                logger3.info(`request failed client error on ${node2.url} trying next node`);
                 break;
               }
             }
-            logger2.info(`${method} request failed on ${node2.url}. Attempt: ${attempt + 1} / ${config2.attemptsPerEndpoint}`);
+            logger3.info(`${method} request failed on ${node2.url}. Attempt: ${attempt + 1} / ${config2.attemptsPerEndpoint}`);
             if (config2.attemptInterval > 0) {
               yield (0, utils_12.sleep)(config2.attemptInterval);
             }
@@ -41001,7 +41001,7 @@ function requireUtils$1() {
     exports.getBlockchainRidFromIid = getBlockchainRidFromIid;
     exports.convertToPrintable = convertToPrintable;
     const buffer_12 = buffer$3;
-    const logger2 = __importStar2(logger$3);
+    const logger3 = __importStar2(logger$3);
     const errors_12 = errors;
     const gtxTool = __importStar2(gtx$1);
     const errors_2 = errors;
@@ -41084,7 +41084,7 @@ function requireUtils$1() {
     function validTxRid(txRID) {
       if (txRID.length != 32) {
         const error4 = new errors_12.InvalidTxRidException(txRID);
-        logger2.error(error4.toString());
+        logger3.error(error4.toString());
         return false;
       }
       return true;
@@ -41487,7 +41487,7 @@ function requireUtils$1() {
     function handleGetResponse(error4, statusCode, responseObject, callback) {
       try {
         const responseObjectPrintable = convertToPrintable(responseObject);
-        logger2.debug(`error: ${error4}, status code: ${statusCode}, response body: ${responseObjectPrintable}`);
+        logger3.debug(`error: ${error4}, status code: ${statusCode}, response body: ${responseObjectPrintable}`);
         if (error4) {
           return callback(error4, null);
         }
@@ -41497,16 +41497,16 @@ function requireUtils$1() {
         return callback(null, responseObject);
       } catch (error5) {
         callback(error5, null);
-        logger2.error(`client.handleGetResponse(): Failed to call the callback function. ${error5}`);
+        logger3.error(`client.handleGetResponse(): Failed to call the callback function. ${error5}`);
       }
     }
     function handlePostResponse(error4, statusCode, responseObject, callback) {
       var _a2;
       const responseObjectPrintable = convertToPrintable(responseObject);
-      logger2.debug(`error: ${error4}, status code: ${statusCode}, response body: ${responseObjectPrintable}`);
+      logger3.debug(`error: ${error4}, status code: ${statusCode}, response body: ${responseObjectPrintable}`);
       try {
         if (error4) {
-          logger2.error(`In client post(). ${error4}`);
+          logger3.error(`In client post(). ${error4}`);
           callback(error4, null);
         } else if (!statusCode || !(0, http_utils_1.isSuccessfulStatusCode)(statusCode)) {
           let errorMessage2 = `Unexpected status code from server. Code: ${statusCode}.`;
@@ -41514,14 +41514,14 @@ function requireUtils$1() {
           if (responseObjectPrintable) {
             errorMessage2 += ` Message: ${responseObjectPrintable}.`;
           }
-          logger2.error(errorMessage2);
+          logger3.error(errorMessage2);
           callback(new errors_12.UnexpectedStatusError(statusCode !== null && statusCode !== void 0 ? statusCode : 400, errorMessageInResponseBody || responseObjectPrintable), responseObject);
         } else {
-          logger2.info(`Calling responseCallback with responseObject: ${responseObjectPrintable}`);
+          logger3.info(`Calling responseCallback with responseObject: ${responseObjectPrintable}`);
           callback(null, responseObject);
         }
       } catch (error5) {
-        logger2.error(`client.handlePostResponse(): Failed to call callback function ${error5}`);
+        logger3.error(`client.handlePostResponse(): Failed to call callback function ${error5}`);
       }
     }
     function getBlockchainRidFromIid(_a2) {
@@ -42259,7 +42259,7 @@ function requireBlockchainClient() {
   const crypto_12 = requireCryptoBrowserify();
   const cloneDeep_1$1 = __importDefault2(cloneDeep_1);
   const IccfProofTxMaterialBuilder_1 = requireIccfProofTxMaterialBuilder();
-  const logger2 = __importStar2(logger$3);
+  const logger3 = __importStar2(logger$3);
   const formatter_12 = formatter;
   const serialization_12 = serialization$2;
   const gtxTool = __importStar2(gtx$1);
@@ -42301,7 +42301,7 @@ function requireBlockchainClient() {
         },
         signTransaction(transaction, signMethod2, callback) {
           return __awaiter2(this, void 0, void 0, function* () {
-            logger2.debug(`Signing transaction with ${!(0, utils_12.isKeyPair)(signMethod2) ? "signature provider containing " : ""}pubKey: ${(0, formatter_12.toString)(signMethod2.pubKey)}`);
+            logger3.debug(`Signing transaction with ${!(0, utils_12.isKeyPair)(signMethod2) ? "signature provider containing " : ""}pubKey: ${(0, formatter_12.toString)(signMethod2.pubKey)}`);
             const gtx2 = (0, utils_12.getGTXFromBufferOrTransactionOrOperation)(transaction, config2.blockchainRid);
             try {
               const signedTx = yield (0, utils_12.isKeyPair)(signMethod2) ? gtxTool.sign(gtx2, signMethod2.privKey, config2.merkleHashVersion, signMethod2.pubKey) : gtxTool.sign(gtx2, signMethod2, config2.merkleHashVersion);
@@ -42326,7 +42326,7 @@ function requireBlockchainClient() {
           const promiEvent = new promiEvents_12.Web3PromiEvent((resolve2, reject) => __awaiter2(this, void 0, void 0, function* () {
             let error4 = null;
             for (let i = 0; i < config2.retryTransactionPolling.count; i++) {
-              logger2.info(`sendTransactionWithRetries attempt ${i + 1} of ${config2.retryTransactionPolling.count}`);
+              logger3.info(`sendTransactionWithRetries attempt ${i + 1} of ${config2.retryTransactionPolling.count}`);
               const tmpPromiEvent = sendOnce().on(enums_12.TransactionEvent.ClusterAnchoringConfirmation, (receipt) => {
                 promiEvent.emit(enums_12.TransactionEvent.ClusterAnchoringConfirmation, receipt);
               }).on(enums_12.TransactionEvent.SystemAnchoringConfirmation, (receipt) => {
@@ -42338,7 +42338,7 @@ function requireBlockchainClient() {
               }).on(enums_12.TransactionEvent.DappConfirmed, (receipt) => {
                 promiEvent.emit(enums_12.TransactionEvent.DappConfirmed, receipt);
               }).catch((tmpError) => {
-                logger2.warning(`sendTransactionWithRetries error on attempt ${i + 1} of ${config2.retryTransactionPolling.count}: ${tmpError}`);
+                logger3.warning(`sendTransactionWithRetries error on attempt ${i + 1} of ${config2.retryTransactionPolling.count}: ${tmpError}`);
                 promiEvent.emit(enums_12.TransactionEvent.Rejected, tmpError);
                 error4 = tmpError;
               });
@@ -43073,11 +43073,11 @@ function requireDecodeTransactionToGtx() {
   Object.defineProperty(decodeTransactionToGtx, "__esModule", { value: true });
   decodeTransactionToGtx.decodeTransactionToGtx = decodeTransactionToGtx$1;
   const gtxTool = __importStar2(gtx$1);
-  const logger2 = __importStar2(logger$3);
+  const logger3 = __importStar2(logger$3);
   const dump_1 = requireDump();
   function decodeTransactionToGtx$1(encodedTransaction) {
     const gtx2 = gtxTool.deserialize(encodedTransaction);
-    logger2.debug(`Output from deserializing a raw transaction: ${(0, dump_1.dumpGtv)(gtx2)}`);
+    logger3.debug(`Output from deserializing a raw transaction: ${(0, dump_1.dumpGtv)(gtx2)}`);
     return gtx2;
   }
   return decodeTransactionToGtx;
@@ -43455,6 +43455,17 @@ var native = {
   defaultChromiaNodeUrls: () => [...DEFAULT_CHROMIA_NODE_URLS_ARR],
   defaultPrivateNodeUrls: () => [...DEFAULT_PRIVATE_NODE_URLS_ARR],
   // Server-only surfaces — throw at runtime, keep types satisfied.
+  // The memory signers are here and not with the other signing shims because
+  // their args are encrypted by `encryptMemoryContent`, which this build does
+  // not have: a browser could sign the transaction but never produce one worth
+  // sending.
+  signAddAgentMemory: stub("signAddAgentMemory"),
+  signRollbackAgentMemory: stub("signRollbackAgentMemory"),
+  extractMemoryEdits: stub("extractMemoryEdits"),
+  applyMemoryEdits: stub("applyMemoryEdits"),
+  memorySlotForPath: stub("memorySlotForPath"),
+  isSafeMemorySlot: stub("isSafeMemorySlot"),
+  defaultAgentHomeDirs: stub("defaultAgentHomeDirs"),
   classifyMemoryWrite: stub("classifyMemoryWrite"),
   classifyMemoryRead: stub("classifyMemoryRead"),
   defaultMemoryWriteToolNames: stub("defaultMemoryWriteToolNames"),
@@ -43531,6 +43542,32 @@ function randomHex(size) {
   return hex;
 }
 
+// src-ts/auth-bearer.ts
+init_define_ATBASH_CHROMIA_NODE_URLS();
+init_define_ATBASH_PRIVATE_NODE_URLS();
+var BEARER_TTL_MS = 4 * 60 * 1e3;
+var bearers = /* @__PURE__ */ new Map();
+function agentAuthBearer(auth, blockchainRid) {
+  const key3 = `${auth.pubkey}:${blockchainRid}`;
+  const now = Date.now();
+  const cached = bearers.get(key3);
+  if (cached && now - cached.issuedAt < BEARER_TTL_MS) return cached.hex;
+  const hex = native.signLogToolCall(
+    `auth-${now.toString(36)}-${randomHex(4)}`,
+    `auth:${now}`,
+    "",
+    "auth-bearer",
+    "",
+    auth.privkey,
+    blockchainRid
+  );
+  bearers.set(key3, { hex, issuedAt: now });
+  return hex;
+}
+function agentAuthHeaders(auth, blockchainRid) {
+  return { Authorization: `Bearer ${agentAuthBearer(auth, blockchainRid)}` };
+}
+
 // src-ts/chain-config.ts
 init_define_ATBASH_CHROMIA_NODE_URLS();
 init_define_ATBASH_PRIVATE_NODE_URLS();
@@ -44588,9 +44625,19 @@ init_define_ATBASH_PRIVATE_NODE_URLS();
 // src-ts/normalize.ts
 init_define_ATBASH_CHROMIA_NODE_URLS();
 init_define_ATBASH_PRIVATE_NODE_URLS();
+function wireText(raw2, fallback = "") {
+  if (raw2 === null || raw2 === void 0) return fallback;
+  if (typeof raw2 === "object" || typeof raw2 === "function") return fallback;
+  return String(raw2);
+}
+function wireNumber(raw2, fallback = 0) {
+  if (raw2 === null || raw2 === void 0) return fallback;
+  if (typeof raw2 === "object" || typeof raw2 === "function") return fallback;
+  return Number(raw2);
+}
 function normalizeVerdict(raw2) {
   if (raw2 === null || raw2 === void 0) return "No verdict";
-  const v = String(raw2).toUpperCase();
+  const v = wireText(raw2).trim().toUpperCase();
   if (v === "ALLOW" || v === "GREEN") return "ALLOW";
   if (v === "HOLD" || v === "YELLOW") return "HOLD";
   if (v === "BLOCK" || v === "RED") return "BLOCK";
@@ -44600,7 +44647,7 @@ function normalizeActionType(raw2) {
   return typeof raw2 === "string" ? raw2.trim().toLowerCase() : "";
 }
 function normalizeStatus(raw2) {
-  const s2 = String(raw2 ?? "").toLowerCase();
+  const s2 = wireText(raw2).toLowerCase();
   if (s2 === "pending" || s2 === "answered" || s2 === "error") return s2;
   return "error";
 }
@@ -44627,17 +44674,58 @@ function allowSignalsPermit(data) {
   }
   return signals.length === 0 || signals.every((value) => value === true);
 }
+function explicitRefusal(data) {
+  let hold = false;
+  for (const source of decisionSources(data)) {
+    const verdict = verdictOf(source);
+    if (verdict === "BLOCK" || verdict === "RED") return "BLOCK";
+    if (verdict === "HOLD" || verdict === "YELLOW") hold = true;
+    const actionType = actionTypeOf(source);
+    if (actionType === "block") return "BLOCK";
+    if (actionType === "hold_for_user_confirm") hold = true;
+  }
+  if (!allowSignalsPermit(data)) return "BLOCK";
+  return hold ? "HOLD" : "";
+}
+function decisionSources(data) {
+  return [data, isRecord(data.decision) ? data.decision : {}];
+}
+function verdictOf(source) {
+  return typeof source.verdict === "string" ? source.verdict.trim().toUpperCase() : "";
+}
+function actionTypeRank(actionType) {
+  if (actionType === "block") return 4;
+  if (actionType === "hold_for_user_confirm") return 3;
+  if (actionType === "") return 1;
+  if (actionType === "allow") return 0;
+  return 2;
+}
+function actionTypeOf(source) {
+  let winner = "";
+  for (const key3 of ["action_type", "actionType"]) {
+    const raw2 = source[key3];
+    if (raw2 === void 0 || raw2 === null) continue;
+    const actionType = normalizeActionType(raw2);
+    if (actionTypeRank(actionType) > actionTypeRank(winner)) winner = actionType;
+  }
+  return winner;
+}
 function wireActionType(data) {
-  if (data.action_type !== void 0)
-    return normalizeActionType(data.action_type);
-  return normalizeActionType(data.actionType);
+  for (const source of decisionSources(data)) {
+    const actionType = actionTypeOf(source);
+    if (actionType !== "") return actionType;
+  }
+  return "";
 }
 function isAuditTier(data) {
   const absentVerdict = data.verdict === null || data.verdict === void 0;
   return absentVerdict && data.status === "logged";
 }
+function isAuditTierBody(data) {
+  return isAuditTier(data);
+}
 function canonicalAllow(data) {
-  if (!allowSignalsPermit(data)) return false;
+  if (explicitRefusal(data) !== "") return false;
   const actionType = wireActionType(data);
   if (actionType && actionType !== "allow") return false;
   if (isAuditTier(data)) return true;
@@ -44646,6 +44734,62 @@ function canonicalAllow(data) {
   return verdict === "ALLOW" || verdict === "GREEN";
 }
 
+// src-ts/opentel/events.ts
+init_define_ATBASH_CHROMIA_NODE_URLS();
+init_define_ATBASH_PRIVATE_NODE_URLS();
+var SLOW_MS = 1500;
+var SUCCESS_SAMPLE_RATE = 10;
+var logger2 = 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));
+}
+var SOURCE_SHAPE = /^(?:sdk|cli|plugin:[a-z0-9][a-z0-9._-]{0,31})$/;
+function configureEvents(next, opts = {}) {
+  logger2 = next;
+  eventsEnabled = next !== null && !eventsOptedOut();
+  if (opts.version) sdkVersion = opts.version;
+  if (opts.source && SOURCE_SHAPE.test(opts.source)) eventSource = opts.source;
+  hashAgentKey = opts.hashAgentKey ?? null;
+}
+function eventsAreOn() {
+  return eventsEnabled && logger2 !== 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;
+    logger2.emit({ body: e.functionName, attributes });
+  } catch {
+  }
+}
+
 // src-ts/browser/opentel/telemetry.ts
 init_define_ATBASH_CHROMIA_NODE_URLS();
 init_define_ATBASH_PRIVATE_NODE_URLS();
@@ -44682,6 +44826,12 @@ function resolve(_key, flagValue) {
 function forcedChainNetwork(flagValue) {
   return flagValue === "public" || flagValue === "private" ? flagValue : void 0;
 }
+function agentKeyFromEnv() {
+  return "";
+}
+function strandedAgentKey() {
+  return "";
+}
 
 // src-ts/client.ts
 function generateToolCallId() {
@@ -44707,6 +44857,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;
@@ -44720,6 +44877,10 @@ var Atbash = class _Atbash {
   orgEncryptionPubKey;
   /** When true (default), `auditToolCall` denies on any error. */
   failClosed;
+  /** When true (default), an unenforced (audit-tier) answer is refused. */
+  requireEnforcement;
+  /** Overall deadline for one auditToolCall decision, in ms. */
+  decisionTimeoutMs;
   /** Org key learned from the last agent-exists check, for this agent only. */
   _orgKeyFromChain = null;
   debug;
@@ -44761,16 +44922,6 @@ var Atbash = class _Atbash {
    */
   _agentExistsCache = null;
   static AGENT_EXISTS_TTL_MS = 5e3;
-  /**
-   * Cached bearer token for risk-engine / insurance read calls. Built
-   * lazily as a signed `log_tool_call` tx and refreshed every 4 min so
-   * server-side replay protection windows never expire it mid-session.
-   */
-  // Keyed by blockchainRid so bearers for the public and private chains can
-  // coexist. The dashboard derives `authNetwork` from the BRID inside the
-  // signed envelope, so a bearer signed for chain A cannot authenticate a
-  // request routed to chain B — every chain the client talks to needs its own.
-  _authBearers = /* @__PURE__ */ new Map();
   /** Guards `logEnvironmentOnce` — hosts construct several clients. */
   static environmentLogged = false;
   constructor(privkey, options = {}) {
@@ -44793,6 +44944,8 @@ var Atbash = class _Atbash {
     this.verifyPubKey = validated.verifyPubKey ?? void 0;
     this.orgEncryptionPubKey = options.orgEncryptionPubKey;
     this.failClosed = options.failClosed !== false;
+    this.requireEnforcement = options.requireEnforcement !== false;
+    this.decisionTimeoutMs = options.decisionTimeoutMs ?? DEFAULT_DECISION_TIMEOUT_MS;
     this.debug = options.debug === true;
     this.logger = options.logger ?? {};
     this.http = new HttpClient(this.endpoint, options.timeoutMs ?? 12e4);
@@ -44856,6 +45009,84 @@ var Atbash = class _Atbash {
    * validated against the trusted allowlist / self-hosted policy; a
    * self-hosted endpoint's `verifyPubKey` becomes the client default.
    */
+  /**
+   * Decide which key this client signs as.
+   *
+   * Most specific wins: a key passed in code, then a key file the host named,
+   * then the environment, then the default key file. `config.json` is absent
+   * from that list on purpose — it is a settings file, writable by anything
+   * that can write the user's home and read by every Atbash integration on the
+   * machine, so letting it name the key meant one stray value silently
+   * re-pointed who each of them signed as.
+   *
+   * A named `keyPath` that does not exist throws rather than falling through.
+   * The caller said which file holds its identity; quietly signing as a
+   * different one is the outcome worth refusing.
+   *
+   * @param options - The `fromConfig` options, read for `agentKey` and `keyPath`.
+   * @returns The resolved agent identity.
+   * @throws When a named key file is missing, or no identity can be found.
+   */
+  static resolveIdentity(options) {
+    if (options.agentKey) return native.loadAgent(options.agentKey);
+    if (options.keyPath) return loadAgentFromFile(options.keyPath);
+    const fromEnv = agentKeyFromEnv();
+    if (fromEnv) return native.loadAgent(fromEnv);
+    try {
+      return loadAgentFromFile();
+    } catch (err) {
+      throw _Atbash.explainStrandedKey(err);
+    }
+  }
+  /**
+   * Add the one thing a machine with no key file needs to hear.
+   *
+   * This is the only path where the operator cannot see what happened: no key
+   * file, and the key they are looking for sits in `config.json`, which no
+   * longer selects the identity. A bare "key file not found" sends them hunting
+   * for a key they already have. Only this branch gets the hint — a caller who
+   * named a `keyPath` is told about that path, where a stranded key is noise.
+   *
+   * @param err - The "key file not found" error from the default lookup.
+   * @returns The same error, or one that also names the key in config.json.
+   */
+  static explainStrandedKey(err) {
+    const stranded = strandedAgentKey();
+    if (!stranded) return err;
+    let identity;
+    try {
+      identity = native.derivePublicKey(stranded);
+    } catch {
+      identity = "(unreadable)";
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return new Error(
+      `${message}
+config.json still holds an "agentKey" (${identity}), but a settings file no longer chooses the signing key. Move it into one of the key files above, or set ATBASH_AGENT_KEY.`
+    );
+  }
+  /**
+   * Say so when `config.json` still holds an agent key.
+   *
+   * Nothing signs with it any more, and silence would leave an operator
+   * believing one identity is in force while another is. The pubkey is named,
+   * not the key, so the line is safe in a log.
+   *
+   * @param logger - The host logger, when one was supplied.
+   */
+  static warnOnStrandedKey(logger3) {
+    const stranded = strandedAgentKey();
+    if (!stranded) return;
+    let identity;
+    try {
+      identity = native.derivePublicKey(stranded);
+    } catch {
+      identity = "(unreadable)";
+    }
+    logger3?.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.`
+    );
+  }
   static fromConfig(options = {}) {
     const configuredEndpoint = resolve("judgeEndpoint") || void 0;
     const configuredVerifyPubKey = resolve("judgeVerifyPubKey") || void 0;
@@ -44871,8 +45102,8 @@ var Atbash = class _Atbash {
         verifyPubKey: configuredVerifyPubKey
       } : { endpoint: configuredEndpoint })
     );
-    const agentKey = resolve("agentKey", options.agentKey);
-    const auth = agentKey ? native.loadAgent(agentKey) : loadAgentFromFile(options.keyPath);
+    const auth = _Atbash.resolveIdentity(options);
+    _Atbash.warnOnStrandedKey(options.logger);
     return new _Atbash(auth.privkey, {
       endpoint: validated.url,
       chain: options.chain,
@@ -44883,6 +45114,8 @@ var Atbash = class _Atbash {
       orgName: options.orgName,
       verifyPubKey: validated.verifyPubKey ?? void 0,
       failClosed: options.failClosed,
+      requireEnforcement: options.requireEnforcement,
+      decisionTimeoutMs: options.decisionTimeoutMs,
       // 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")),
@@ -45081,45 +45314,28 @@ var Atbash = class _Atbash {
     }
     if (!resp.ok) throw await this.httpError(resp);
     const bodyBytes = Buffer.from(await resp.arrayBuffer());
-    const verifyPubKey = options.verifyPubKey ?? this.verifyPubKey;
+    const verifyPubKey = this.effectiveVerifyKey(options.verifyPubKey);
     if (verifyPubKey !== void 0) {
-      const sig = resp.headers.get("X-Atbash-Signature");
-      if (!sig) {
-        throw new SignatureVerificationError(
-          "missing X-Atbash-Signature header"
-        );
-      }
-      let ok;
-      try {
-        ok = native.verifySignature(bodyBytes, sig, verifyPubKey);
-      } catch (err) {
-        throw new SignatureVerificationError(
-          `signature verification threw: ${errorMessage(err)}`
-        );
-      }
-      if (!ok) {
-        throw new SignatureVerificationError(
-          "signature does not verify against configured verifyPubKey"
-        );
-      }
+      verifyResponseSignature(bodyBytes, resp, verifyPubKey);
     }
     const data = parseJson(bodyBytes);
     const rawScore = data.score;
     const score = typeof rawScore === "number" && Number.isInteger(rawScore) && rawScore >= 1 && rawScore <= 10 ? rawScore : void 0;
     return {
       verdict: normalizeVerdict(data.verdict),
-      allow: canonicalAllow(data),
+      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 ?? ""),
-      score
+      enforcementMode: wireText(data.enforcement_mode),
+      status: wireText(data.status),
+      score,
+      refusal: explicitRefusal(data)
     };
   }
   /* ── audit_tool_call (redact → judge → decision) ───────────────────────── */
@@ -45152,77 +45368,125 @@ var Atbash = class _Atbash {
     }
     try {
       this.logger.info?.("[atbash] judge API called", { tool: toolName });
-      const result = await this.judgeAction(actionText, contextText, {
-        toolName,
-        toolArgsJson: argsJson,
-        orgName: this.orgName,
-        // Passed through unredacted — caller vouches for the contents.
-        resolved: input.resolved
-      });
-      if (result.verdict === "No verdict") {
-        if (result.status !== "logged") {
-          return this.failJudge(
-            `judge returned no verdict without an audit-tier marker (status: ${result.status || "absent"})`,
-            void 0,
-            result.toolCallId
-          );
-        }
-        return {
-          allow: true,
-          verdict: "ALLOW",
-          reason: result.reason || "audit tier \u2014 request logged on-chain, no AI enforcement",
-          toolCallId: result.toolCallId
-        };
-      }
-      const action = result.actionType;
-      if (action === "block") {
+      const result = await withDeadline(
+        this.judgeAction(actionText, contextText, {
+          toolName,
+          toolArgsJson: argsJson,
+          orgName: this.orgName,
+          // Passed through unredacted — caller vouches for the contents.
+          resolved: input.resolved
+        }),
+        this.decisionTimeoutMs
+      );
+      return this.decide(result);
+    } catch (err) {
+      if (err instanceof SignatureVerificationError) {
+        this.failJudge(errorMessage(err), err);
         return {
           allow: false,
-          verdict: "BLOCK",
-          reason: result.reason,
-          toolCallId: result.toolCallId
+          verdict: "ERROR",
+          reason: `The judge's reply failed its signature check (${errorMessage(err)}), so it was not trusted.`
         };
       }
-      if (action === "hold_for_user_confirm") {
-        return {
-          allow: false,
-          verdict: "HOLD",
-          reason: result.reason || "held for human confirmation",
-          toolCallId: result.toolCallId
-        };
+      return this.failJudge(errorMessage(err), err);
+    }
+  }
+  /**
+   * The verify key for one call (R4, governor tier-2 review). A per-call key
+   * may only narrow what the client accepts: on a client pinned to a judge
+   * key it must be that same key, never a replacement; on an unpinned client
+   * it adds the check.
+   */
+  effectiveVerifyKey(perCall) {
+    if (perCall === void 0) return this.verifyPubKey;
+    const key3 = perCall.trim().toLowerCase();
+    if (this.verifyPubKey !== void 0 && key3 !== this.verifyPubKey) {
+      throw new SignatureVerificationError(
+        "a per-call verifyPubKey cannot replace the judge key this client is pinned to"
+      );
+    }
+    return key3;
+  }
+  /**
+   * Collapse a judge result into a {@link Decision}. The most restrictive
+   * signal wins (security review 2026-09-30, H1): `action_type`, `verdict`
+   * and the canonical `allow` are each able to deny, and only a result where
+   * all three agree may execute. A present `allow` / `decision.allow` that is
+   * not exactly `true` is the judge declining to grant permission, so it
+   * denies even under `failClosed: false` — that option relaxes *errors*, it
+   * never overrides a refusal.
+   */
+  decide(result) {
+    const toolCallId = result.toolCallId;
+    const deny = (verdict, reason) => ({
+      allow: false,
+      verdict,
+      reason,
+      toolCallId
+    });
+    const notGranted = "the judge response did not grant permission";
+    const held = deny("HOLD", result.reason || "held for human confirmation");
+    const blocked = deny("BLOCK", result.reason || notGranted);
+    if (result.refusal === "BLOCK") return blocked;
+    if (result.verdict === "No verdict") {
+      if (result.actionType === "block") {
+        return blocked;
+      }
+      if (result.actionType === "hold_for_user_confirm") {
+        return held;
+      }
+      if (result.refusal === "HOLD") return held;
+      if (result.status !== "logged") {
+        return this.failJudge(
+          `judge returned no verdict without an audit-tier marker (status: ${result.status || "absent"})`,
+          void 0,
+          toolCallId
+        );
       }
-      if (action === "allow") {
-        if (result.verdict === "HOLD") {
-          return {
-            allow: false,
-            verdict: "HOLD",
-            reason: result.reason,
-            toolCallId: result.toolCallId
-          };
-        }
-        if (result.verdict === "BLOCK") {
-          return {
-            allow: false,
-            verdict: "BLOCK",
-            reason: result.reason,
-            toolCallId: result.toolCallId
-          };
-        }
+      if (this.requireEnforcement) {
+        this.logger.warn?.(
+          "[atbash] judge did not enforce this action (audit tier) and requireEnforcement is on: denied",
+          { toolCallId }
+        );
         return {
-          allow: true,
-          verdict: "ALLOW",
-          reason: result.reason,
-          toolCallId: result.toolCallId
+          allow: false,
+          verdict: "ERROR",
+          reason: "Atbash logged this action but did not check it (audit-tier plan), and this client requires a checked decision. Upgrade the plan, or set requireEnforcement: false for log-only mode.",
+          toolCallId
         };
       }
-      return this.failJudge(
-        "unrecognized action_type from judge",
-        void 0,
-        result.toolCallId
-      );
-    } catch (err) {
-      return this.failJudge(errorMessage(err), err);
+      if (result.allow !== true) return deny("BLOCK", notGranted);
+      return {
+        allow: true,
+        verdict: "ALLOW",
+        reason: result.reason || "audit tier \u2014 request logged on-chain, no AI enforcement",
+        toolCallId
+      };
+    }
+    const action = result.actionType;
+    if (action === "block") {
+      return deny("BLOCK", result.reason || "Blocked by your organisation's Atbash policy.");
+    }
+    if (action === "hold_for_user_confirm") {
+      return held;
     }
+    if (result.refusal === "HOLD") return held;
+    if (action === "allow") {
+      if (result.verdict === "HOLD") return held;
+      if (result.verdict === "BLOCK") return blocked;
+      if (result.allow !== true) return deny("BLOCK", notGranted);
+      return {
+        allow: true,
+        verdict: "ALLOW",
+        reason: result.reason,
+        toolCallId
+      };
+    }
+    return this.failJudge(
+      "unrecognized action_type from judge",
+      void 0,
+      toolCallId
+    );
   }
   /**
    * One exit for every judge failure.
@@ -45234,18 +45498,30 @@ var Atbash = class _Atbash {
    */
   failJudge(reason, cause, toolCallId) {
     const api2 = cause instanceof AtbashAPIError ? cause : null;
+    const userReason = userFacingReason(reason, api2);
     const status = api2 ? ` status=${api2.status || "no-response"}` : "";
+    const detail = this.debug ? ` detail=${truncate(reason, 500)}` : "";
     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}`,
+      `[atbash] judge API failed \u2014${status} reason=${truncate(userReason, 300)}${detail}${body}`,
       {
-        reason,
-        ...api2 ? { status: api2.status, body: api2.body } : {},
+        reason: userReason,
+        ...api2 ? { status: api2.status } : {},
+        ...this.debug && api2 ? { body: api2.body, detail: reason } : {},
         endpoint: this.endpoint,
         ...toolCallId ? { toolCallId } : {}
       }
     );
-    return this.fail(reason, toolCallId);
+    return this.fail(userReason, toolCallId);
+  }
+  /**
+   * The canonical permission for a response body under this client's
+   * settings: {@link canonicalAllow}, minus the audit tier when
+   * `requireEnforcement` is on. Never more permissive than `auditToolCall`.
+   */
+  executable(data) {
+    if (!canonicalAllow(data)) return false;
+    return !(this.requireEnforcement && isAuditTierBody(data));
   }
   fail(reason, toolCallId) {
     return { allow: !this.failClosed, verdict: "ERROR", reason, toolCallId };
@@ -45271,13 +45547,18 @@ var Atbash = class _Atbash {
         this.authHeaders(brid)
       );
       await this.raiseIfError(resp);
-      const data = await this.json(resp) ?? {};
+      const bytes = Buffer.from(await resp.arrayBuffer());
+      if (this.verifyPubKey !== void 0) {
+        verifyResponseSignature(bytes, resp, this.verifyPubKey);
+      }
+      const parsed = tryParseJson(bytes.toString("utf-8"));
+      const data = isRecord2(parsed) ? parsed : {};
       return {
         status: normalizeStatus(data.status),
         verdict: normalizeVerdict(data.verdict),
-        allow: canonicalAllow(data),
-        reason: String(data.reason ?? ""),
-        judgmentId: String(data.judgmentId ?? judgmentId),
+        allow: this.executable(data),
+        reason: wireText(data.reason),
+        judgmentId: wireText(data.judgmentId, judgmentId),
         onChain: optBool(data.onChain),
         cached: optBool(data.cached),
         responseTimeMs: optNumber(data.responseTimeMs)
@@ -45561,10 +45842,28 @@ var Atbash = class _Atbash {
     recordCall(name2, void 0, agentPubkey);
     try {
       const result = await fn();
-      recordDuration(name2, performance.now() - start, "success");
+      const durationMs = performance.now() - start;
+      recordDuration(name2, durationMs, "success");
+      recordEvent({
+        functionName: name2,
+        durationMs,
+        status: "success",
+        agentPubkey,
+        chain: this.blockchainRid
+      });
       return result;
     } catch (err) {
-      recordDuration(name2, performance.now() - start, "error");
+      const durationMs = performance.now() - start;
+      recordDuration(name2, durationMs, "error");
+      recordEvent({
+        functionName: name2,
+        durationMs,
+        status: "error",
+        agentPubkey,
+        chain: this.blockchainRid,
+        errorClass: err instanceof Error ? err.constructor.name : typeof err,
+        ...errorDetail(err)
+      });
       throw err;
     }
   }
@@ -45602,25 +45901,10 @@ var Atbash = class _Atbash {
    * trips the server's replay window.
    */
   getAuthBearer(brid) {
-    const chainBrid = brid ?? this.blockchainRid;
-    const now = Date.now();
-    const cached = this._authBearers.get(chainBrid);
-    if (cached && now - cached.issuedAt < 4 * 60 * 1e3) return cached.hex;
-    const nonce = `auth-${now.toString(36)}-${randomHex(4)}`;
-    const hex = native.signLogToolCall(
-      nonce,
-      `auth:${now}`,
-      "",
-      "auth-bearer",
-      "",
-      this.auth.privkey,
-      chainBrid
-    );
-    this._authBearers.set(chainBrid, { hex, issuedAt: now });
-    return hex;
+    return agentAuthBearer(this.auth, brid ?? this.blockchainRid);
   }
   authHeaders(brid) {
-    return { Authorization: `Bearer ${this.getAuthBearer(brid)}` };
+    return agentAuthHeaders(this.auth, brid ?? this.blockchainRid);
   }
   async riskEngineGet(action, params, brid) {
     let resp;
@@ -45750,6 +46034,66 @@ var Atbash = class _Atbash {
     return native.containsEvasionCharacters(text);
   }
 };
+function userFacingReason(reason, api2) {
+  if (api2 && api2.status > 0) {
+    const where = ` (HTTP ${api2.status}${api2.path ? ` from ${api2.path}` : ""})`;
+    const b = api2.body.toLowerCase();
+    if (b.includes("agent not registered")) {
+      return `Agent not registered with Atbash: onboard it in the Atbash dashboard${where}.`;
+    }
+    if (b.includes("jailed")) {
+      return `This agent is jailed; unjail it in the Atbash dashboard${where}.`;
+    }
+    if (b.includes("agent has no policy") || b.includes("no policy configured")) {
+      return `This agent has no policy; attach one in the Atbash dashboard${where}.`;
+    }
+    if (b.includes("audit tier") || b.includes("verdict disabled") || b.includes("verdict not supported")) {
+      return `The organisation's plan does not include checked decisions${where}.`;
+    }
+    return `The Atbash judge answered with an error${where}, so the action was not approved.`;
+  }
+  const text = api2 ? api2.body || reason : reason;
+  return truncate(text.replace(/https?:\/\/[^\s)]+/g, "the judge"), 300);
+}
+var DEFAULT_DECISION_TIMEOUT_MS = 6e4;
+async function withDeadline(p, ms) {
+  let timer;
+  const deadline = new Promise((_, reject) => {
+    timer = setTimeout(
+      () => reject(
+        new Error(
+          `The judge did not give a decision within ${Math.round(ms / 1e3)} s, so the action was not approved. Check the network, or raise decisionTimeoutMs.`
+        )
+      ),
+      ms
+    );
+  });
+  p.catch(() => void 0);
+  try {
+    return await Promise.race([p, deadline]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function verifyResponseSignature(bodyBytes, resp, verifyPubKey) {
+  const sig = resp.headers.get("X-Atbash-Signature");
+  if (!sig) {
+    throw new SignatureVerificationError("missing X-Atbash-Signature header");
+  }
+  let ok;
+  try {
+    ok = native.verifySignature(bodyBytes, sig, verifyPubKey);
+  } catch (err) {
+    throw new SignatureVerificationError(
+      `signature verification threw: ${errorMessage(err)}`
+    );
+  }
+  if (!ok) {
+    throw new SignatureVerificationError(
+      "signature does not verify against configured verifyPubKey"
+    );
+  }
+}
 function baseToolCall(raw2) {
   return {
     toolCallId: String(raw2.tool_call_id ?? ""),
@@ -45821,10 +46165,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;
 }
@@ -45951,22 +46297,6 @@ function bootSyncFailureLine(cause) {
   );
 }
 
-// src-ts/memory/_gtv_bytes.ts
-init_define_ATBASH_CHROMIA_NODE_URLS();
-init_define_ATBASH_PRIVATE_NODE_URLS();
-function gtvToFfiSafe(value) {
-  if (value instanceof Uint8Array) return Buffer.from(value).toString("hex");
-  if (Array.isArray(value)) return value.map(gtvToFfiSafe);
-  if (value !== null && typeof value === "object") {
-    const out = {};
-    for (const [key3, val] of Object.entries(value)) {
-      out[key3] = gtvToFfiSafe(val);
-    }
-    return out;
-  }
-  return value;
-}
-
 // src-ts/memory/index.ts
 init_define_ATBASH_CHROMIA_NODE_URLS();
 init_define_ATBASH_PRIVATE_NODE_URLS();
@@ -46309,6 +46639,7 @@ export {
   classifyMemoryWrite,
   columnAad,
   commitMemoryVersion,
+  configureEvents,
   containsEvasionCharacters2 as containsEvasionCharacters,
   containsSecret2 as containsSecret,
   createFileLogger,
@@ -46324,6 +46655,7 @@ export {
   encryptForOrg,
   encryptMemoryContent2 as encryptMemoryContent,
   encryptedLength,
+  eventsAreOn,
   flushTelemetry,
   generateKeypair2 as generateKeypair,
   getActiveAgentMemory,
@@ -46334,7 +46666,6 @@ export {
   getMemoryHistory,
   getRecentAgentMemory,
   getRollbackHistory,
-  gtvToFfiSafe,
   guardMemoryWrite,
   isEnvelope,
   isValidPrivateKey2 as isValidPrivateKey,
@@ -46353,6 +46684,7 @@ export {
   pubkeyToHex,
   recordCall,
   recordDuration,
+  recordEvent,
   redactJsonStrings,
   redactSecrets2 as redactSecrets,
   resolve,