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

package/README.md

@@ -29,18 +29,15 @@ const result = await atbash.judgeAction(
   "Outbound AML check — new recipient, over threshold",
 );
 
-// 3. Enforce the verdict
-switch (result.verdict) {
-  case "ALLOW":
-    // Proceed with the action
-    break;
-  case "HOLD":
-    // Held — operator must approve in the dashboard
-    console.log("Held for review:", result.toolCallId);
-    break;
-  case "BLOCK":
-    // Refused — agent is jailed in Enforcement tier
-    throw new Error(`Blocked: ${result.reason}`);
+// 3. Act on the decision. `allow` is the gate; `verdict` says why.
+if (result.allow) {
+  // Proceed with the action
+} else if (result.verdict === "HOLD") {
+  // Held — operator must approve in the dashboard
+  console.log("Held for review:", result.toolCallId);
+} else {
+  // Refused — agent is jailed in Enforcement tier
+  throw new Error(`Blocked: ${result.reason}`);
 }
 ```
 
@@ -85,6 +82,8 @@ Every `judgeAction` call returns one of three verdicts:
 | `HOLD`  | Requires operator review | Pause — poll `getJudgmentStatus` until resolved |
 | `BLOCK` | Violates a red line | Abort — agent is jailed in Enforcement tier |
 
+> **Gate on `allow`, not on `verdict`.** `allow` is the canonical permission the SDK computes from every signal in the response; `verdict` is one of those signals, and reads as the reason. The two differ when an organisation does not enforce an agent's verdicts — Shadow Mode on an agent, or org-wide Monitor mode — where the action is judged and recorded on chain but deliberately not applied. Branching on `verdict` re-derives a denial the organisation chose not to make.
+
 > **NB:** If your org has no active subscription, the judge returns `"No verdict"` — actions are logged on-chain for the audit trail but not evaluated by an AI provider. Assign a plan at [atbash.ai/risk-engine/settings](https://atbash.ai/risk-engine/settings) for active verdicts.
 
 ## API
@@ -195,3 +194,67 @@ Policy authoring, operator reviews, and agent management happen at [atbash.ai](h
 ## License
 
 Licensed under the [Apache License, Version 2.0](LICENSE). See [NOTICE](NOTICE) for attribution. Versions published before this change remain available under the license they shipped with.
+
+## Telemetry — what the SDK sends
+
+The SDK reports how its own functions perform. It runs inside your agents and
+the data leaves your network, so the payload is **metadata only** and the list
+below is the whole of it.
+
+**Sent**
+
+| Field | Example |
+| --- | --- |
+| `function.name` | `judgeAction`, `memory.memory-add` |
+| `status` / `outcome` | `success`, `error` |
+| `duration_ms` | `142` |
+| `error.class` | `AtbashAPIError` |
+| `error.status` / `error.path` | `404`, `/api/v1/judge` — the route, never its query string |
+| `sdk.version` | `0.18.0` |
+| `chain` | the blockchain RID — public infrastructure, and it names no customer |
+| `agent.hash` | SHA-256 of the agent's **public** key, never the key itself |
+| `source` | `sdk`, `cli`, `plugin:openclaw` |
+
+**Never sent.** Action text, tool arguments, policy text, organisation names,
+memory file paths, memory contents, response bodies, and keys of any kind.
+`error.path` is the route alone — the query string is stripped where the error
+is built, because it carries org names, tool call ids and the agent pubkey. These are not fields
+that get emptied before sending — there is no field for them to go in.
+
+`agent.hash` is de-identification, not anonymisation: agent public keys are
+readable from the chain, so anyone holding that list can match a hash back to
+an agent. Supply your own salted hasher to `setupTelemetry({ hashAgentKey })`
+if you need it to be uncorrelatable.
+
+### Turning it off
+
+```bash
+export ATBASH_TELEMETRY_DISABLED=1
+```
+
+or create `~/.config/atbash/telemetry.json` containing `{ "enabled": false }`.
+
+**On a Private deployment, telemetry may already be off for everyone.** The operator disables collection by leaving `HONEYCOMB_API_KEY` unset on their Atbash service; the telemetry route then accepts the request and discards the payload, so nothing is forwarded and agents never see an error or retry. That is an operator setting on the deployment, not one you control from the agent — the switches above are yours.
+
+To keep the operational counters but drop the richer per-operation events:
+
+```bash
+export ATBASH_TELEMETRY_EVENTS_DISABLED=1
+```
+
+### Sending it to your own collector
+
+Point the SDK at any OTLP endpoint you control. Atbash is then bypassed
+entirely and **no Atbash credential is created or transmitted** — your headers
+are the only ones sent.
+
+```bash
+export ATBASH_TELEMETRY_COLLECTOR_URL=https://otel.yourcompany.example
+export ATBASH_TELEMETRY_COLLECTOR_HEADERS='{"x-api-key":"your-key"}'
+```
+
+Metrics go to `/v1/metrics` and events to `/v1/logs` beneath that URL. `https`
+is required; a collector on `localhost` additionally needs
+`ATBASH_TELEMETRY_ALLOW_LOOPBACK=1`, so a mistyped URL cannot silently turn
+exporting off. A URL that is refused raises at setup rather than quietly
+falling back to Atbash.

package/dist/browser.d.mts

@@ -1,3 +1,5 @@
+import { Logger } from '@opentelemetry/api-logs';
+
 type JudgeEndpointConfig = {
     policy?: "default";
     endpoint?: string;
@@ -1233,6 +1235,19 @@ interface GuardMemoryWriteResult {
     /** Present when handled. True only after the chain transaction confirms. */
     committed?: boolean;
 }
+/**
+ * Guard a memory write, and record what was decided.
+ *
+ * Wraps the decision rather than threading telemetry through its eight exits,
+ * so a later return added inside cannot quietly stop being counted.
+ *
+ * Only a call this guard actually handled is recorded. A tool call that was
+ * never a memory write is not a memory operation, and counting it would put
+ * every unrelated edit into the number a memory migration reads.
+ *
+ * @param input - The tool call and the agent to judge it for.
+ * @returns What the guard decided; unchanged by the recording.
+ */
 declare function guardMemoryWrite(input: GuardMemoryWriteInput): Promise<GuardMemoryWriteResult>;
 
 /**
@@ -1641,6 +1656,20 @@ interface TelemetryConfig {
      * `{ Authorization: "Bearer <hex>" }`). Required to actually export.
      */
     getAuthHeaders?: () => Record<string, string>;
+    /**
+     * Hashes the agent key before it is emitted on a wide event.
+     *
+     * Defaults to an unsalted SHA-256, which is de-identification rather than
+     * anonymisation: agent pubkeys are public on chain and can be enumerated, so
+     * the mapping is recoverable by anyone holding that list. Supply a salted
+     * hasher to make it uncorrelatable, at the cost of joining across
+     * deployments.
+     *
+     * Injected rather than imported so the telemetry modules need nothing from
+     * the native addon. Left unset, the agent field is dropped from events
+     * rather than falling back to the raw key.
+     */
+    hashAgentKey?: (pubkeyHex: string) => string;
 }
 declare function setupTelemetry(config: TelemetryConfig): void;
 /**
@@ -1663,6 +1692,121 @@ declare function flushTelemetry(): Promise<void>;
  */
 declare function shutdownTelemetry(): Promise<void>;
 
+/**
+ * Wide events: one row per SDK operation, alongside the counters.
+ *
+ * The counters in `telemetry.ts` are aggregated inside this process before
+ * export, so Honeycomb never receives a per-operation row. That is fine for
+ * "is it up" and useless for everything else: a question nobody attached an
+ * attribute for in advance cannot be answered later, because the data to
+ * answer it never existed. "Which org sees the most failures", "what preceded
+ * a fail-closed", "is the new release slower" are all that shape.
+ *
+ * So each operation also emits one event carrying its whole context. The
+ * counters stay — they are the right tool for health boards and alerts, and
+ * they are not sampled.
+ *
+ * TWO RULES SHAPE THIS MODULE.
+ *
+ * The payload is METADATA ONLY, and the allowlist below is the whole of it:
+ * function name, outcome, latency, error class, error status and path, SDK
+ * version, chain, and a hash of the agent key. Action text, tool arguments, policy text, organisation
+ * names and keys never appear — not as a field that is emptied, but as a field
+ * that does not exist, so there is nothing to forget to strip.
+ *
+ * The agent key is hashed, never sent raw, and the hasher is INJECTED rather
+ * than imported: this module needs nothing from the native addon. With no
+ * hasher supplied the field is DROPPED rather than falling back to the raw
+ * key, so the guarantee does not depend on wiring somebody could forget.
+ *
+ * NOTE on what hashing does and does not buy. Agent pubkeys are public on
+ * chain and can be enumerated, so an UNSALTED hash is reversible by anyone who
+ * can read the chain: it is de-identification, not anonymisation. A salted
+ * hasher makes it uncorrelatable and costs cross-deployment joins. Which one
+ * is wanted is the caller's decision; this module only guarantees the raw key
+ * never leaves.
+ *
+ * And the richer payload has its own switch. Counters carry a function name
+ * and a source. These events carry agent and org identity off a customer's
+ * machine, which is a different proposition for a security product, so
+ * `ATBASH_TELEMETRY_EVENTS_DISABLED=1` turns them off while leaving the health
+ * counters on. Both remain subject to the existing global opt-out.
+ */
+
+/** Attributes an event may carry. Anything not listed here cannot be emitted. */
+interface OperationEvent {
+    /** SDK function, matching the counter's `function.name` so the two join. */
+    functionName: string;
+    durationMs: number;
+    status: "success" | "error";
+    /**
+     * Hex pubkey of the agent the call was made as. Hashed before it is emitted,
+     * and omitted entirely when no hasher is configured.
+     */
+    agentPubkey?: string;
+    /**
+     * Blockchain RID of the chain this call concerned.
+     *
+     * The RID rather than a network label: it is public infrastructure, it is
+     * unambiguous, and it identifies the deployment without naming a customer.
+     */
+    chain?: string;
+    /** Constructor name of the thrown error, e.g. `AtbashAPIError`. */
+    errorClass?: string;
+    /** HTTP status, or 0 when the request never completed. */
+    errorStatus?: number;
+    /**
+     * Request path the status came from, e.g. `/api/v1/judge`.
+     *
+     * The class alone does not say what failed: several routes answer one call
+     * and more than one can 404, so `AtbashAPIError` cannot distinguish "this
+     * agent is not registered" from "the chain-routing lookup did not resolve".
+     * The path settles it.
+     *
+     * Carries no query string — `requestPath` strips it at the point the error
+     * is built, because a query string carries org names, tool call ids and the
+     * agent pubkey. Structured and already sanitised, so this stays inside the
+     * metadata rule where an error message would not.
+     */
+    errorPath?: string;
+    /**
+     * Short categorical result, when "success" is too coarse — e.g. a memory
+     * write that scanned clean but never reached the chain.
+     *
+     * Categorical by contract: a value a caller chooses from a fixed vocabulary,
+     * never free text and never anything derived from user content.
+     */
+    outcome?: string;
+}
+/** Hashes an agent key for emission. Supplied by `setupTelemetry`. */
+type AgentKeyHasher = (pubkeyHex: string) => string;
+/**
+ * Point this module at a logger, or at nothing.
+ *
+ * Called by `setupTelemetry` once the shared exporter exists, so events and
+ * counters travel the same authenticated route and share one opt-out decision.
+ *
+ * @param next - Logger to emit through, or null to disable.
+ * @param opts - Version and source stamped on every event, and the hasher
+ *   applied to the agent key. Without a hasher, the agent field is dropped.
+ */
+declare function configureEvents(next: Logger | null, opts?: {
+    version?: string;
+    source?: string;
+    hashAgentKey?: AgentKeyHasher;
+}): void;
+/** True when an event would actually be emitted. Exported for tests and callers that build context lazily. */
+declare function eventsAreOn(): boolean;
+/**
+ * Emit one wide event for a completed operation.
+ *
+ * Never throws and never blocks: telemetry failing must not change what the
+ * caller observes. Does nothing when events are off.
+ *
+ * @param e - The completed operation.
+ */
+declare function recordEvent(e: OperationEvent): void;
+
 /**
  * Rust core does the work; `browser/encrypted-toolcall.ts` mirrors it for the
  * browser and must produce the same columns.
@@ -1760,4 +1904,4 @@ declare function containsSecret(text: string): boolean;
 declare function createMemorySnapshot(entries: MemoryEntry[], takenAt: number): MemorySnapshot;
 declare function diffMemorySnapshots(before: MemorySnapshot, after: MemorySnapshot): MemoryDiffResult;
 
-export { type ActionType, type AgentAuth, type AgentLookupOptions, type AgentMemoryEntry, type AgentPolicy, type AnomalySeverity, type AnomalyType, Atbash, AtbashAPIError, type AtbashLogger, type AtbashOptions, type AtbashUserConfig, BOOT_SYNC_HINT, type ChainConfig, type ChainOpts, type ClassifierToolContext, type ClassifierToolEvent, type ClassifyMemoryReadOptions, type ClassifyMemoryWriteOptions, type ClientSource, type CommitMemoryOptions, DEFAULT_BLOCKCHAIN_RID, DEFAULT_CHROMIA_NODE_URLS, DEFAULT_ENDPOINT, DEFAULT_MEMORY_PATH_PATTERNS, DEFAULT_MEMORY_READ_TOOL_NAMES, DEFAULT_MEMORY_WRITE_TOOL_NAMES, type Decision, type DecisionVerdict, EciesDomain, type EncryptedMemory, type Envelope, type FromConfigOptions, type GuardLogger, type GuardMemoryDecision, type GuardMemoryWriteInput, type GuardMemoryWriteResult, type HeldAction, type HeldActionReview, type HookDecision, HttpClient, HttpTransportError, type JudgeEndpointConfig, type JudgeOptions, type JudgeResult, type JudgmentState, type JudgmentStatus, KEY_FILENAMES, type KeyPair, type LogToolCallOptions, type LogToolCallResult, type MemoryAnomaly, type MemoryDiffResult, type MemoryEntry, MemoryGuardManager, type MemoryGuardManagerOptions, MemoryIntegrityError, type MemoryPointer, type MemoryRollbackEvent, type MemoryScanOptions, type MemoryScanResult, type MemoryScanVerdict, type MemorySnapshot, type ModifiedEntry, type Network, type OrgSubscription, PRIVATE_CHAIN, PUBLIC_CHAIN, PointerStore, type Provider, type PubkeyValue, type RedactResult, type RollbackMemoryOptions, type SecretKind, type SecretMatch, SignatureVerificationError, type Subscription, type SyncMemoryOptions, type SyncMemoryResult, type TelemetryConfig, type TierInfo, type ToolCallFull, type ToolCallInput, type ToolCallRecord, type ValidatedEndpoint, type Verdict, type WrappedLogger, bootSyncFailureLine, buildAllowedJudgeHosts, canonicalAllow, chainForNetwork, chooseKeyPath, claimHashHex, classifyMemoryRead, classifyMemoryWrite, columnAad, commitMemoryVersion, containsEvasionCharacters, containsSecret, createFileLogger, createMemoryGuardManager, createMemorySnapshot, decryptForOrg, decryptMemoryContent, defaultPluginLogPath, defaultPointerPath, deriveMemoryKey, derivePublicKey, diffMemorySnapshots, encryptForOrg, encryptMemoryContent, encryptedLength, flushTelemetry, generateKeypair, getActiveAgentMemory, getActiveMemoryId, getConfigDir, getConfigPath, getMemoryById, getMemoryHistory, getRecentAgentMemory, getRollbackHistory, guardMemoryWrite, isEnvelope, isValidPrivateKey, keyFingerprintOf, keyPathCandidates, loadAgent, loadAgentFromFile, loadUserConfig, normalizeActionForHash, normalizeActionType, normalizeForMatching, normalizeStatus, normalizeVerdict, packEnvelope, parseEnvelope, pubkeyToHex, recordCall, recordDuration, redactJsonStrings, redactSecrets, resolve, resolveKeyPath, rollbackMemory, saveUserConfig, scanMemory, scanMemoryBatch, setupTelemetry, shutdownTelemetry, signEncryptedToolCall, signJudgeAction, signLogToolCall, syncLocalMemory, validateJudgeEndpoint, verifyJudgeResponseSignature, verifySignature };
+export { type ActionType, type AgentAuth, type AgentLookupOptions, type AgentMemoryEntry, type AgentPolicy, type AnomalySeverity, type AnomalyType, Atbash, AtbashAPIError, type AtbashLogger, type AtbashOptions, type AtbashUserConfig, BOOT_SYNC_HINT, type ChainConfig, type ChainOpts, type ClassifierToolContext, type ClassifierToolEvent, type ClassifyMemoryReadOptions, type ClassifyMemoryWriteOptions, type ClientSource, type CommitMemoryOptions, DEFAULT_BLOCKCHAIN_RID, DEFAULT_CHROMIA_NODE_URLS, DEFAULT_ENDPOINT, DEFAULT_MEMORY_PATH_PATTERNS, DEFAULT_MEMORY_READ_TOOL_NAMES, DEFAULT_MEMORY_WRITE_TOOL_NAMES, type Decision, type DecisionVerdict, EciesDomain, type EncryptedMemory, type Envelope, type FromConfigOptions, type GuardLogger, type GuardMemoryDecision, type GuardMemoryWriteInput, type GuardMemoryWriteResult, type HeldAction, type HeldActionReview, type HookDecision, HttpClient, HttpTransportError, type JudgeEndpointConfig, type JudgeOptions, type JudgeResult, type JudgmentState, type JudgmentStatus, KEY_FILENAMES, type KeyPair, type LogToolCallOptions, type LogToolCallResult, type MemoryAnomaly, type MemoryDiffResult, type MemoryEntry, MemoryGuardManager, type MemoryGuardManagerOptions, MemoryIntegrityError, type MemoryPointer, type MemoryRollbackEvent, type MemoryScanOptions, type MemoryScanResult, type MemoryScanVerdict, type MemorySnapshot, type ModifiedEntry, type Network, type OperationEvent, type OrgSubscription, PRIVATE_CHAIN, PUBLIC_CHAIN, PointerStore, type Provider, type PubkeyValue, type RedactResult, type RollbackMemoryOptions, type SecretKind, type SecretMatch, SignatureVerificationError, type Subscription, type SyncMemoryOptions, type SyncMemoryResult, type TelemetryConfig, type TierInfo, type ToolCallFull, type ToolCallInput, type ToolCallRecord, type ValidatedEndpoint, type Verdict, type WrappedLogger, bootSyncFailureLine, buildAllowedJudgeHosts, canonicalAllow, chainForNetwork, chooseKeyPath, claimHashHex, classifyMemoryRead, classifyMemoryWrite, columnAad, commitMemoryVersion, configureEvents, containsEvasionCharacters, containsSecret, createFileLogger, createMemoryGuardManager, createMemorySnapshot, decryptForOrg, decryptMemoryContent, defaultPluginLogPath, defaultPointerPath, deriveMemoryKey, derivePublicKey, diffMemorySnapshots, encryptForOrg, encryptMemoryContent, encryptedLength, eventsAreOn, flushTelemetry, generateKeypair, getActiveAgentMemory, getActiveMemoryId, getConfigDir, getConfigPath, getMemoryById, getMemoryHistory, getRecentAgentMemory, getRollbackHistory, guardMemoryWrite, isEnvelope, isValidPrivateKey, keyFingerprintOf, keyPathCandidates, loadAgent, loadAgentFromFile, loadUserConfig, normalizeActionForHash, normalizeActionType, normalizeForMatching, normalizeStatus, normalizeVerdict, packEnvelope, parseEnvelope, pubkeyToHex, recordCall, recordDuration, recordEvent, redactJsonStrings, redactSecrets, resolve, resolveKeyPath, rollbackMemory, saveUserConfig, scanMemory, scanMemoryBatch, setupTelemetry, shutdownTelemetry, signEncryptedToolCall, signJudgeAction, signLogToolCall, syncLocalMemory, validateJudgeEndpoint, verifyJudgeResponseSignature, verifySignature };

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;
@@ -44625,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).trim().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";
@@ -44637,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";
 }
@@ -44724,6 +44734,61 @@ 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));
+}
+function configureEvents(next, opts = {}) {
+  logger2 = 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 && 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();
@@ -44791,6 +44856,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;
@@ -45001,7 +45073,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(logger2) {
+  static warnOnStrandedKey(logger3) {
     const stranded = strandedAgentKey();
     if (!stranded) return;
     let identity;
@@ -45010,7 +45082,7 @@ config.json still holds an "agentKey" (${identity}), but a settings file no long
     } catch {
       identity = "(unreadable)";
     }
-    logger2?.warn?.(
+    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.`
     );
   }
@@ -45252,15 +45324,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)
     };
@@ -45484,8 +45556,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)
@@ -45769,10 +45841,28 @@ config.json still holds an "agentKey" (${identity}), but a settings file no long
     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;
     }
   }
@@ -46074,10 +46164,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;
 }
@@ -46546,6 +46638,7 @@ export {
   classifyMemoryWrite,
   columnAad,
   commitMemoryVersion,
+  configureEvents,
   containsEvasionCharacters2 as containsEvasionCharacters,
   containsSecret2 as containsSecret,
   createFileLogger,
@@ -46561,6 +46654,7 @@ export {
   encryptForOrg,
   encryptMemoryContent2 as encryptMemoryContent,
   encryptedLength,
+  eventsAreOn,
   flushTelemetry,
   generateKeypair2 as generateKeypair,
   getActiveAgentMemory,
@@ -46589,6 +46683,7 @@ export {
   pubkeyToHex,
   recordCall,
   recordDuration,
+  recordEvent,
   redactJsonStrings,
   redactSecrets2 as redactSecrets,
   resolve,