@atbash/sdk 0.10.5-dev.0 → 0.10.7-dev.0

package/dist/browser.d.mts

@@ -310,6 +310,12 @@ interface AtbashOptions {
     orgEncryptionPubKey?: string;
     /** When true (default), `auditToolCall` denies on any error. */
     failClosed?: boolean;
+    /**
+     * Verbose diagnostics. Off by default. When on, a failed judge call also
+     * logs the response body, which is the difference between "judge API failed"
+     * and knowing why it failed. Opt-in because that body can echo the action.
+     */
+    debug?: boolean;
     logger?: AtbashLogger;
 }
 /** Canonical decision returned by `auditToolCall`. */
@@ -350,6 +356,8 @@ interface FromConfigOptions {
     /** Default org name — see {@link AtbashOptions.orgName}. */
     orgName?: string;
     failClosed?: boolean;
+    /** See {@link AtbashOptions.debug}. */
+    debug?: boolean;
     logger?: AtbashLogger;
 }
 /** Options accepted by `judgeAction`. */
@@ -414,6 +422,7 @@ declare class Atbash {
     readonly failClosed: boolean;
     /** Org key learned from the last agent-exists check, for this agent only. */
     private _orgKeyFromChain;
+    private readonly debug;
     private readonly logger;
     private readonly http;
     /**
@@ -427,7 +436,20 @@ declare class Atbash {
      * server-side replay protection windows never expire it mid-session.
      */
     private _authBearer;
+    /** Guards `logEnvironmentOnce` — hosts construct several clients. */
+    private static environmentLogged;
     constructor(privkey: string, options?: AtbashOptions);
+    /**
+     * 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.
+     */
+    private logEnvironmentOnce;
     /**
      * Construct from resolved config: explicit overrides → env vars → the
      * `~/.config/atbash/config.json` file (see userConfig.resolve). The private
@@ -470,6 +492,15 @@ declare class Atbash {
      * explicitly false.
      */
     auditToolCall(input: ToolCallInput): Promise<Decision>;
+    /**
+     * 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.
+     */
+    private failJudge;
     private fail;
     getJudgmentStatus(judgmentId: string, agentPubkey?: string): Promise<JudgmentStatus>;
     getToolCalls(maxCount: number): Promise<ToolCallRecord[]>;
@@ -585,6 +616,8 @@ interface AtbashUserConfig {
     blockchainRid?: string;
     provider?: string;
     providerModel?: string;
+    /** "1" / "true" turns on verbose diagnostics. See AtbashOptions.debug. */
+    debug?: string;
 }
 declare function getConfigDir(): string;
 declare function getConfigPath(): string;
@@ -595,6 +628,26 @@ declare function resolve(key: keyof AtbashUserConfig, flagValue?: string): strin
 declare function resolveKeyPath(input?: string): string;
 declare function loadAgentFromFile(keyPath?: string): AgentAuth;
 
+/**
+ * Accepted key filenames, in precedence order.
+ *
+ * `guard-client-key` stays first: it is the name every existing install
+ * already has, and changing which file wins would silently switch agent
+ * identity for anyone holding both. `atbash-client-key` is accepted because
+ * it is the name people actually create — the old one carries retired
+ * branding — and hitting ENOENT on a key you just wrote, from a plugin that
+ * still reports itself installed, is a miserable first run.
+ */
+declare const KEY_FILENAMES: readonly ["guard-client-key", "atbash-client-key"];
+/** Every path checked when no explicit key path is given, in order. */
+declare function keyPathCandidates(): string[];
+/**
+ * Pick the key path: an explicit input wins untouched; otherwise the first
+ * accepted filename that exists, falling back to the preferred name so the
+ * error names something recognisable when nothing is there.
+ */
+declare function chooseKeyPath(input: string | undefined, exists: (p: string) => boolean): string;
+
 /**
  * Canonical secret kinds reported by the Rust core in `SecretMatch.kind`.
  * Wire is permissive (modelled as a free string in {@link SecretMatch})
@@ -613,6 +666,26 @@ declare function verifyJudgeResponseSignature(bodyBytes: Uint8Array, signatureHe
     reason?: string;
 };
 
+/**
+ * The boot memory-sync failure line.
+ *
+ * Split out of `guard-manager.ts` so it can be asserted without constructing a
+ * guard manager, which needs the native addon. The message is the whole point
+ * of AT-304: hosts print the message and drop the structured meta, so a cause
+ * that lives only in meta never reaches the operator.
+ */
+/** Advice, not a diagnosis — appended only when the cause is unhelpful. */
+declare const BOOT_SYNC_HINT = "check the chain endpoint and orgName if the cause above does not explain it";
+/**
+ * Lead with the real cause.
+ *
+ * The previous wording named the chain endpoint and orgName as the things to
+ * check, which sent operators to verify configuration that was already correct
+ * while the actual cause (a node answering `404 Can't find blockchain with
+ * blockchainRID: …` for a chain it does not host) stayed hidden.
+ */
+declare function bootSyncFailureLine(cause: unknown): string;
+
 /** Derive the 32-byte AES key from an agent's secp256k1 privkey (hex). Deterministic — same privkey always yields the same key. */
 declare function deriveMemoryKey(privkey: string): Promise<Buffer>;
 /** Encrypt UTF-8 plaintext. `ciphertext` has the 16-byte GCM auth tag appended, matching the SDK's on-chain byte layout. */
@@ -1164,4 +1237,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 AgentMemoryEntry, type AgentPolicy, type AnomalySeverity, type AnomalyType, Atbash, AtbashAPIError, type AtbashLogger, type AtbashOptions, type AtbashUserConfig, 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, type JudgeEndpointConfig, type JudgeOptions, type JudgeResult, type JudgmentState, type JudgmentStatus, 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, 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, buildAllowedJudgeHosts, claimHashHex, classifyMemoryRead, classifyMemoryWrite, columnAad, commitMemoryVersion, containsEvasionCharacters, containsSecret, createFileLogger, createMemoryGuardManager, createMemorySnapshot, decryptForOrg, decryptMemoryContent, defaultPluginLogPath, defaultPointerPath, deriveMemoryKey, derivePublicKey, diffMemorySnapshots, encryptForOrg, encryptMemoryContent, encryptedLength, flushTelemetry, generateKeypair, getActiveMemory, getActiveMemoryId, getAllAgentMemory, getConfigDir, getConfigPath, getMemoryById, getMemoryHistory, getRollbackHistory, guardMemoryWrite, isEnvelope, isValidPrivateKey, keyFingerprintOf, loadAgent, loadAgentFromFile, loadUserConfig, normalizeActionForHash, 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 AgentMemoryEntry, type AgentPolicy, type AnomalySeverity, type AnomalyType, Atbash, AtbashAPIError, type AtbashLogger, type AtbashOptions, type AtbashUserConfig, BOOT_SYNC_HINT, 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, 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, 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, chooseKeyPath, claimHashHex, classifyMemoryRead, classifyMemoryWrite, columnAad, commitMemoryVersion, containsEvasionCharacters, containsSecret, createFileLogger, createMemoryGuardManager, createMemorySnapshot, decryptForOrg, decryptMemoryContent, defaultPluginLogPath, defaultPointerPath, deriveMemoryKey, derivePublicKey, diffMemorySnapshots, encryptForOrg, encryptMemoryContent, encryptedLength, flushTelemetry, generateKeypair, getActiveMemory, getActiveMemoryId, getAllAgentMemory, getConfigDir, getConfigPath, getMemoryById, getMemoryHistory, getRollbackHistory, guardMemoryWrite, isEnvelope, isValidPrivateKey, keyFingerprintOf, keyPathCandidates, loadAgent, loadAgentFromFile, loadUserConfig, normalizeActionForHash, 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 };