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

package/dist/browser.d.mts

@@ -430,6 +430,16 @@ declare class Atbash {
      * calls don't re-hit the dashboard. Cleared by `clearChainCache()`.
      */
     private readonly _chainCache;
+    /**
+     * Short-TTL cache for `/api/ai/exists`. The `registered` field is
+     * monotonic (once true, stays true), so most calls in a burst re-fetch
+     * data that hasn't changed. The `org_encryption_pubkey` field CAN change
+     * — an org toggling encryption mid-session — so the TTL is deliberately
+     * short (see `AGENT_EXISTS_TTL_MS`). Keyed by (pubkey, network) so
+     * cross-agent / cross-network calls don't collide.
+     */
+    private _agentExistsCache;
+    private static readonly AGENT_EXISTS_TTL_MS;
     /**
      * Cached bearer token for risk-engine / insurance read calls. Built
      * lazily as a signed `log_tool_call` tx and refreshed every 4 min so
@@ -547,6 +557,8 @@ declare class Atbash {
     private resolveChainFromMap;
     /** Drop any cached chain resolutions. Useful in tests. */
     clearChainCache(): void;
+    /** Drop the short-TTL `/api/ai/exists` cache. Useful in tests. */
+    clearAgentExistsCache(): void;
     /**
      * Wrap an SDK method body in telemetry — records the call at start
      * and a success/error duration at end. Re-throws on failure so the
@@ -576,7 +588,13 @@ declare class Atbash {
     private raiseIfError;
     /** Wrap a failed HTTP *response* (non-2xx / non-200) as an AtbashAPIError. */
     private httpError;
-    /** Wrap a *transport* failure (fetch threw, no response) as an AtbashAPIError. */
+    /**
+     * Wrap a transport failure (fetch threw, no response) as an AtbashAPIError.
+     *
+     * `HttpTransportError.kind` names the cause; the message is already
+     * human-readable. `debug` echoes the original exception so operators can
+     * cross-reference with node / undici logs when a class doesn't match.
+     */
     private transportError;
     private json;
     static generateKeypair(): KeyPair;
@@ -602,6 +620,43 @@ declare class SignatureVerificationError extends Error {
     constructor(message: string);
 }
 
+/**
+ * Thin typed fetch wrapper.
+ *
+ * openapi-typescript emits types only (no runtime client), so this is the
+ * single hand-written transport — generic `get`/`post` over global `fetch`
+ * with a per-request timeout. The endpoint-specific request/response *shapes*
+ * are pulled from the generated `schema.ts` at the call sites in client.ts, so
+ * the wire contract still lives in spec/openapi.yaml. Methods return the raw
+ * `Response` so the caller can read the exact bytes the server signed before
+ * any decode (judge signature verification) — mirroring the Python surface's
+ * use of raw httpx (DECISIONS 2026-05-22).
+ */
+type QueryValue = string | number | boolean | undefined | null;
+declare class HttpClient {
+    readonly baseUrl: string;
+    readonly timeoutMs: number;
+    constructor(baseUrl: string, timeoutMs: number);
+    buildUrl(path: string, query?: Record<string, QueryValue>): string;
+    get(path: string, query?: Record<string, QueryValue>, headers?: Record<string, string>): Promise<Response>;
+    post(path: string, body: unknown, headers?: Record<string, string>): Promise<Response>;
+    private fetch;
+}
+/**
+ * A transport failure the SDK can act on. Every real cause the platform surfaces
+ * lands as one of these — the message names the cause in plain language so a
+ * plugin can show it to a user without decoding httpx / fetch internals.
+ *
+ * `cause` preserves the original error for debug logging; consumers that want
+ * the raw exception (e.g. tests) read it there.
+ */
+declare class HttpTransportError extends Error {
+    readonly kind: "timeout" | "aborted" | "dns" | "connect_refused" | "connection_reset" | "unknown";
+    constructor(kind: HttpTransportError["kind"], message: string, options?: {
+        cause?: unknown;
+    });
+}
+
 /** Normalize wire shapes (verdict casing, status, pubkey) to canonical forms. */
 
 declare function normalizeVerdict(raw: unknown): Verdict;
@@ -850,19 +905,6 @@ interface ClassifyMemoryWriteOptions {
  */
 declare function classifyMemoryWrite(event: unknown, ctx: unknown, opts?: ClassifyMemoryWriteOptions): MemoryEntry | null;
 
-/**
- * Plugin-agnostic memory-write guard.
- *
- * A single call that replaces the plugin's usual memory-write branch:
- *   classify → scan (Layer 1 regex + Layer 2 LLM) → gate on verdict →
- *   persist to chain (fire-and-forget when allowed) → return decision.
- *
- * Plugins call this from their `before_tool_call` hook. When it returns
- * `{ handled: false }` the call wasn't a memory write and the plugin
- * should fall through to its regular tool-call audit. When
- * `{ handled: true }` the plugin returns `decision` directly.
- */
-
 /**
  * Minimal logger accepted by `guardMemoryWrite`. Plugins pass their
  * host runtime's logger (openclaw's `api.logger`, MCP's console, etc.).
@@ -893,6 +935,8 @@ interface GuardMemoryWriteInput extends ClassifyMemoryWriteOptions {
     debug?: boolean;
     /** Optional logger for debug probe + persist-failure warnings. */
     logger?: GuardLogger;
+    /** Absolute path of the agent's managed memory file. Required for chain commits — omitted skips them. */
+    memoryFilePath?: string;
 }
 /** Plugin-facing decision. Shape mirrors what plugins return from `before_tool_call`. */
 interface GuardMemoryDecision {
@@ -957,12 +1001,19 @@ interface SyncMemoryOptions {
  * `drifted: false` — pointer is still valid; caller can keep serving the local copy.
  * `drifted: true`  — active id changed on chain; `current` is the fresh decrypted row
  *                    (or `null` if active memory was removed entirely).
+ *
+ * `checked` — whether this call actually queried chain. `false` means the TTL
+ * window was still open and the pointer was trusted without contacting chain, so
+ * `drifted: false` carries no evidence about the current state. Callers that
+ * vouch for content to a third party must not treat an unchecked result as proof.
  */
 type SyncMemoryResult = {
     drifted: false;
+    checked: boolean;
     pointer: MemoryPointer;
 } | {
     drifted: true;
+    checked: true;
     current: AgentMemoryEntry | null;
     pointer: MemoryPointer;
 };
@@ -1024,12 +1075,42 @@ interface ClassifyMemoryReadOptions {
  */
 declare function classifyMemoryRead(event: unknown, ctx: unknown, opts?: ClassifyMemoryReadOptions): boolean;
 
-/** Decision the manager returns to the plugin's `before_tool_call` handler. */
+/**
+ * Decision the manager returns to the plugin's `before_tool_call` handler.
+ *
+ * `allow: true` alone is NOT evidence that anything was checked. Read `audited`
+ * to tell the two apart, and route un-audited calls to your own judge — see the
+ * field docs below.
+ */
 interface HookDecision {
     allow?: boolean;
     block?: boolean;
     blockReason?: string;
     reason?: string;
+    /**
+     * Whether the guard reached an enforcement decision about *this* call.
+     *
+     * Note this describes whether the guard **decided**, not whether it allowed.
+     * Every `block` is `audited: true` — a blocked call is the most thoroughly
+     * checked outcome the guard produces (a red scan, a ciphertext integrity
+     * failure, a rolled-back version), and a host must never re-judge its way past
+     * one.
+     *
+     * Absent or false means the guard reached no decision — it was inside its cache
+     * window, chain was unreachable, the scan never ran, the file it can vouch for
+     * is not the file being read, or it is in observe mode. Those calls are
+     * unaudited: fall through to your own judge exactly as for a `null` return.
+     *
+     * So the host rule is:
+     *   `if (d.block) deny;  else if (d.audited) allow;  else judge it yourself;`
+     *
+     * Treating a bare `allow: true` as a completed audit is what this field exists
+     * to prevent. A host that ignores it and returns the decision verbatim will
+     * execute unaudited tool calls.
+     */
+    audited?: boolean;
+    /** Scan verdict when one was produced (`green` | `yellow` | `red`). Absent when no scan ran. */
+    verdict?: string;
 }
 interface MemoryGuardManagerOptions {
     auth: AgentAuth;
@@ -1052,6 +1133,13 @@ interface MemoryGuardManagerOptions {
     rollbackMinScore?: number;
     /** True → return `{block:true}` on defense triggers. False → log and return `null` (audit-only). Default true. */
     enforce?: boolean;
+    /**
+     * Chain targeting for the pointer sync (network, blockchainRid, nodeUrls).
+     * Defaults to the SDK's configured chain. Without this the manager could only
+     * ever talk to the default chain, which left the whole memory-read path
+     * untestable — `syncLocalMemory` already accepted these options.
+     */
+    chainOpts?: ChainOpts;
     /** Host-specific tuning of what counts as a memory read. */
     memoryReadClassifier?: ClassifyMemoryReadOptions;
     /** Passed through to `guardMemoryWrite`. Host memory-write tool names override. */
@@ -1088,12 +1176,33 @@ declare class MemoryGuardManager {
      */
     runBootProbe(): Promise<void>;
     /**
-     * Returns a `HookDecision` when the event is a memory read or write
-     * (host returns it verbatim to its runtime). Returns `null` when the
-     * event isn't memory-related — host falls through to its own audit.
+     * Returns a `HookDecision` when the guard reached a decision about this event.
+     * Returns `null` when it did not — either the event isn't memory-related, or it
+     * is but the guard could not check it. In both cases the host falls through to
+     * its own audit.
+     *
+     * A returned decision carries `audited` (see `HookDecision`). Only
+     * `{ allow: true, audited: true }` means "checked and cleared"; anything else
+     * that allows is a call the host still needs to judge.
      */
     handleBeforeToolCall(event: unknown, ctx: unknown): Promise<HookDecision | null>;
     private mapGuardResult;
+    /**
+     * Whether the pointer state this manager tracks actually describes the file
+     * this call is about to read.
+     *
+     * The classifier fires on nine patterns — including the bare tokens
+     * `"memory/"`, `"CLAUDE.md"` and `"AGENTS.md"` — but the sync path only ever
+     * reads, refreshes, or vouches for `this.memoryFilePath`. Without this check a
+     * read of `/repo/CLAUDE.md` (or any path merely containing `memory/`) would
+     * receive an `audited: true` for a file the guard never opened.
+     *
+     * Conservative on purpose: every path-shaped value found must resolve to the
+     * managed file. If none is found, or any one differs, the answer is no. That
+     * also covers events carrying two different path keys, where the classifier
+     * and the host could otherwise disagree about which one is authoritative.
+     */
+    private vouchesForTarget;
     private handleMemoryRead;
     private writeMemoryAtomic;
 }
@@ -1237,4 +1346,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, 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 };
+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, 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, 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 };