@atbash/sdk 0.19.2-dev.0 → 0.21.0-dev.0

package/dist/browser.d.mts

@@ -1,3 +1,4 @@
+import nodePath from 'node:path';
 import { Logger } from '@opentelemetry/api-logs';
 
 type JudgeEndpointConfig = {
@@ -37,8 +38,12 @@ interface ChainConfig {
     readonly blockchainRid: string;
     readonly nodeUrls: readonly string[];
 }
-declare const PUBLIC_CHAIN: ChainConfig;
 declare const PRIVATE_CHAIN: ChainConfig;
+/**
+ * The chain a network name selects. Only `"private"` exists; any other value,
+ * including `"public"` from an untyped caller, is refused with the same
+ * message the config switch gives, never routed to private in silence.
+ */
 declare function chainForNetwork(network: Network): ChainConfig;
 
 /**
@@ -129,13 +134,11 @@ interface MemoryScanOptions {
     toolArgsJson?: string;
 }
 /**
- * Which Atbash chain an action runs against. `public` is the shared
- * testnet (Free plan); `private` is reserved for Private / Swarm /
- * Enterprise tier subscribers. The SDK resolves which one to use from
- * the org's subscription via `orgName` — callers normally don't need
- * to pass this manually.
+ * Chain selector. Only `"private"` exists: the public testnet chains are
+ * retired. The SDK resolves an org's chain through the Dashboard via
+ * `orgName` — callers normally don't need to pass this manually.
  */
-type Network = "public" | "private";
+type Network = "private";
 /**
  * Per-call chain overrides. Pass exactly what you need to override —
  * `network` selects between the SDK's known chains, `blockchainRid` pins a
@@ -199,6 +202,8 @@ interface JudgeResult {
      * Whether the org's protection mode actually acts on a HOLD/BLOCK verdict.
      * `false` in Monitor mode (verdict is logged for observation, agent is NOT
      * jailed and the action is not held); `true` in Enforce mode.
+     * A plain boolean: an omitted field reads as `false`. `Decision.enforced`
+     * keeps "unknown" apart; gate on that, not on this.
      */
     enforced: boolean;
     /** Server-reported protection mode: `off`, `monitor`, or `enforce`. */
@@ -337,7 +342,7 @@ interface AtbashOptions {
      */
     chain?: ChainConfig;
     /**
-     * Preset chain selector — `"public"` or `"private"`. Resolves to the
+     * Preset chain selector — `"private"` is the only value. Resolves to the
      * matching `ChainConfig` via `chainForNetwork()`. Overridden by `chain`,
      * overrides env `ATBASH_DEFAULT_CHAIN_NETWORK` and the config file.
      */
@@ -372,7 +377,16 @@ interface AtbashOptions {
      * `orgEncryptionPubKey` overrides this, same as `verifyPubKey`.
      */
     orgEncryptionPubKey?: string;
-    /** When true (default), `auditToolCall` denies on any error. */
+    /**
+     * When true (default), `auditToolCall` denies on any error. When false, it
+     * allows only when Atbash could not be reached or could not answer: a
+     * transport failure, a timeout, a 5xx or a 408 (and a readable reply that
+     * neither grants nor refuses). Atbash's own refusals still deny: an
+     * unregistered agent, any other 4xx (no policy, billing suspended, quota
+     * exhausted or rate limited, unauthorized), and a 2xx reply that is not a
+     * JSON object. Direct `judgeAction` callers get a `JudgeRefusalError` for
+     * an unregistered agent or an unreadable reply.
+     */
     failClosed?: boolean;
     /**
      * When true (the default), an answer that carries no enforcement decision
@@ -399,6 +413,15 @@ interface Decision {
     verdict: DecisionVerdict;
     reason?: string;
     toolCallId?: string;
+    /**
+     * Whether the organisation acts on a HOLD/BLOCK verdict; false under Monitor mode and per-agent Shadow Mode. Absent means unknown: a
+     * transport error, or a judge that stated no mode. Test `=== false`, never
+     * `!decision.enforced`, or every outage counts as a would-block.
+     * Informational only; `allow` remains the gate.
+     */
+    enforced?: boolean;
+    /** Server-reported protection mode (`off`, `monitor`, `enforce`); absent when unknown. */
+    enforcementMode?: string;
 }
 /** Input to `auditToolCall`. */
 interface ToolCallInput {
@@ -622,6 +645,13 @@ declare class Atbash {
      * return the signed tx hex. The server broadcasts to chain.
      */
     logToolCall(action: string, context?: string, options?: LogToolCallOptions): Promise<LogToolCallResult>;
+    /**
+     * `raisePreflightErrors` (the judge path, like Python's
+     * `raise_preflight_errors`): a failed registration check throws instead of
+     * becoming `{ success: false }`, so the caller can tell Atbash's "no"
+     * (not registered, or a 4xx) from an outage.
+     */
+    private _logToolCall;
     /**
      * Sign log_tool_call + optionally judge_action, POST /api/v1/judge.
      *
@@ -630,6 +660,15 @@ declare class Atbash {
      */
     judgeAction(action: string, context?: string, options?: JudgeOptions): Promise<JudgeResult>;
     private _judgeAction;
+    /**
+     * Start a local hold on an enforced, on-chain BLOCK (the verdict that jails).
+     * Refuse any other result that lands while the agent is held, or whose
+     * request was already in flight when the block arrived: the server judged it
+     * on pre-jail state.
+     */
+    private applyJailHold;
+    /** The server's jailed refusal, produced locally while the agent is held. */
+    private localJailBlock;
     /**
      * High-level guard: redact secrets, submit for judgement, and collapse the
      * result into an allow/deny `Decision`. Fails closed by default — any error
@@ -654,6 +693,7 @@ declare class Atbash {
      * never overrides a refusal.
      */
     private decide;
+    private decideInner;
     /**
      * One exit for every judge failure.
      *
@@ -673,12 +713,12 @@ declare class Atbash {
     /**
      * Return the current status of a previously submitted judgment.
      *
-     * `chainOpts` names which chain the judgment was signed against. The
-     * server's GET /api/v1/judge routes to that chain when the SDK sends
-     * a `brid` query param; without it, the server falls back to public.
-     * Callers on the private chain must pass a `chainOpts` (or configure
-     * the client on the private chain) — otherwise polling a POSTed
-     * judgment on the private chain 404s at the server.
+     * `chainOpts` names which chain the judgment was signed against; the SDK
+     * sends it as the `brid` query param the server routes by. Without it the
+     * read uses the same chain `judgeAction` signs for (see `callBrid`): the
+     * client's org chain when it has an `orgName`, else the client default.
+     * A judgment signed with an explicit per-call `chainOpts` (or a per-call
+     * `orgName` on another chain) must be polled with that same `chainOpts`.
      */
     getJudgmentStatus(judgmentId: string, agentPubkey?: string, chainOpts?: ChainOpts): Promise<JudgmentStatus>;
     getToolCalls(maxCount: number): Promise<ToolCallRecord[]>;
@@ -710,12 +750,9 @@ declare class Atbash {
      * Resolve which chain an org's actions should run against. Cached
      * per-client by orgName. Resolution order:
      *   1. `org_networks` map (authoritative).
-     *   2. Per-chain subscription fallback — public + private records
-     *      are fetched in parallel, with `is_private_blockchain` and
-     *      `assigned_at` reconciling mixed states.
-     * A lookup that names exactly one chain wins outright. Where it names
-     * neither (a brand-new org) or cannot choose between them, the client's
-     * configured default decides.
+     *   2. Subscription fallback — the org's subscription row on the chain.
+     * A lookup that finds the org wins outright. Where it finds nothing (a
+     * brand-new org), the client's configured default decides.
      */
     resolveChainForOrg(orgName: string): Promise<ChainConfig>;
     /**
@@ -743,6 +780,13 @@ declare class Atbash {
      * chains; otherwise the client's default.
      */
     private bridFromChainOpts;
+    /**
+     * The chain one call's transactions are signed for: the per-call override
+     * when given, otherwise the client's org, otherwise the client default.
+     * log_tool_call, judge_action and the judgment-status read all use this, so
+     * a request never pairs transactions signed for two different chains.
+     */
+    private callBrid;
     /**
      * Resolve the dashboard chain used by agent metadata/policy reads.
      * Explicit per-call network overrides win; otherwise use the supplied org
@@ -813,9 +857,18 @@ declare class Atbash {
     static containsEvasionCharacters(text: string): boolean;
 }
 
+declare const DEFAULTS: {
+    ceilingMs: number;
+    pollMs: number;
+};
+/** Whether `pubkey` is currently held. */
+declare function isJailHeld(pubkey: string): boolean;
+/** Forget every hold and stop its poll; tests and hosts that reset state. */
+declare function releaseJailHolds(): void;
+/** Override the ceiling or poll interval; an empty object restores defaults. */
+declare function configureJailHold(next: Partial<typeof DEFAULTS>): void;
+
 declare const DEFAULT_ENDPOINT: string;
-declare const DEFAULT_CHROMIA_NODE_URLS: readonly string[];
-declare const DEFAULT_BLOCKCHAIN_RID: string;
 
 declare class AtbashAPIError extends Error {
     /** HTTP status code (or 0 if the request never completed). */
@@ -838,6 +891,14 @@ declare class AtbashAPIError extends Error {
 declare class SignatureVerificationError extends Error {
     constructor(message: string);
 }
+/**
+ * Atbash answered, and the answer was not a grant: the agent is not
+ * registered, or the reply could not be read. Unlike an unreachable judge this
+ * always denies, whatever `failClosed` says.
+ */
+declare class JudgeRefusalError extends Error {
+    constructor(message: string);
+}
 
 /**
  * Thin typed fetch wrapper.
@@ -1250,6 +1311,39 @@ interface GuardMemoryWriteResult {
  */
 declare function guardMemoryWrite(input: GuardMemoryWriteInput): Promise<GuardMemoryWriteResult>;
 
+/**
+ * The chain slot of a memory file, computed the same way everywhere.
+ *
+ * The Rust core finds the slot by stripping the agent's home from the file's
+ * path, as an exact string prefix. The file path arrives resolved
+ * (`path.resolve`), but the home did not: on Windows `HOME=/home/agent`
+ * resolves the file to `C:\home\agent\...` and never matches, and a host that
+ * spells the drive or the user folder differently (`c:\users\me` against
+ * `C:\Users\Me`, both the same folder) did not match either. A file with no
+ * slot is scanned but never recorded on chain, silently, so the on-chain
+ * version record and its rollback/read checks were skipped for it.
+ *
+ * Here the home (and the memory root) is resolved like the file, and on a
+ * case-insensitive file system it is passed to the core spelled the way the
+ * file path spells it. The slot itself, the part below the agent home, keeps
+ * the file's own spelling, so slots recorded before this change still match.
+ *
+ * Known limit: a folder with NTFS per-directory case sensitivity enabled
+ * (`fsutil file setCaseSensitiveInfo`, or one created from WSL) can hold both
+ * `Me` and `me`; there ASCII case does separate folders, and a sibling spelled
+ * in another case would share the home's slots. Creating one needs write
+ * access to the home's parent. A follow-up can confirm the same folder on disk
+ * when the spellings differ.
+ */
+
+/** Path semantics: `node:path` here, `path.win32` / `path.posix` in tests. */
+type PathImpl = typeof nodePath;
+/**
+ * The chain slot for `target`, or null when it gets no chain record. `p`
+ * selects path semantics (tests pass `path.win32` to check Windows anywhere).
+ */
+declare function memorySlotOf(target: string, home: string, root?: string, extraHomes?: string[], p?: PathImpl): string | null;
+
 /**
  * Aligns a local `MemoryPointer` with chain's active memory version
  * via a TTL-cached pointer check. Inside the TTL window: no-op.
@@ -1894,4 +1988,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 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 };
+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_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, JudgeRefusalError, 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, 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, configureJailHold, 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, isJailHeld, isValidPrivateKey, keyFingerprintOf, keyPathCandidates, loadAgent, loadAgentFromFile, loadUserConfig, memorySlotOf, normalizeActionForHash, normalizeActionType, normalizeForMatching, normalizeStatus, normalizeVerdict, packEnvelope, parseEnvelope, pubkeyToHex, recordCall, recordDuration, recordEvent, redactJsonStrings, redactSecrets, releaseJailHolds, resolve, resolveKeyPath, rollbackMemory, saveUserConfig, scanMemory, scanMemoryBatch, setupTelemetry, shutdownTelemetry, signEncryptedToolCall, signJudgeAction, signLogToolCall, syncLocalMemory, validateJudgeEndpoint, verifyJudgeResponseSignature, verifySignature };