@atbash/sdk 0.10.9-dev.0 → 0.10.11-dev.0

package/README.md

@@ -111,8 +111,8 @@ Read-only methods that read from the Chromia blockchain and dashboard.
 | `getToolCallCount()` | Total number of tool calls on-chain |
 | `getToolCallFull(toolCallId)` | Full details of a single tool call |
 | `getOrgTierInfo(orgName)` | Check an org's tier and whether verdicts are enabled |
-| `getAgentDetail(pubkey)` | Get agent metadata (org, status, creation date) |
-| `getAgentPolicy(pubkey)` | Check the agent's policy pack and jail status |
+| `getAgentDetail(pubkey, options?)` | Get agent metadata (org, status, creation date) |
+| `getAgentPolicy(pubkey, options?)` | Check the agent's policy pack and jail status |
 | `getPendingHeldActions(orgName, maxCount)` | List actions waiting for operator approval |
 | `getHeldActionReviews(orgName, maxCount)` | List completed operator reviews |
 | `getSafetyStats()` | Chain-wide safety statistics |
@@ -148,6 +148,16 @@ const atbash = Atbash.fromConfig();   // reads env + config file
 
 Persistent config helpers: `saveUserConfig(config)`, `loadUserConfig()`, `resolve(key, flagValue?)`, `getConfigPath()`.
 
+Agent policy and detail reads can resolve the organization's active network, or
+accept an explicit network override:
+
+```ts
+await atbash.getAgentPolicy(atbash.pubkey, { orgName: "acme" });
+await atbash.getAgentDetail(atbash.pubkey, {
+  chainOpts: { network: "private" },
+});
+```
+
 ## Error handling
 
 The SDK throws standard `Error` objects. Known failure modes are enriched with a pointer to the dashboard page that fixes them:

package/dist/browser.d.mts

@@ -274,6 +274,13 @@ interface AgentPolicy {
     isCustom: boolean;
     defaultPolicy: string;
 }
+/** Options for agent metadata and policy lookups. */
+interface AgentLookupOptions {
+    /** Resolve the agent's network from this organization's active network. */
+    orgName?: string;
+    /** Explicit per-call chain override. `network` selects the dashboard chain. */
+    chainOpts?: ChainOpts;
+}
 /** Optional structured logger. */
 interface AtbashLogger {
     info?(...args: unknown[]): void;
@@ -430,6 +437,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
@@ -511,8 +528,8 @@ declare class Atbash {
     getOrgTierInfo(orgName: string): Promise<TierInfo | null>;
     getPendingHeldActions(orgName: string, maxCount: number): Promise<HeldAction[]>;
     getHeldActionReviews(orgName: string, maxCount: number): Promise<HeldActionReview[]>;
-    getAgentDetail(agentPubkey: string): Promise<Record<string, unknown>>;
-    getAgentPolicy(agentPubkey: string): Promise<AgentPolicy>;
+    getAgentDetail(agentPubkey: string, options?: AgentLookupOptions): Promise<Record<string, unknown>>;
+    getAgentPolicy(agentPubkey: string, options?: AgentLookupOptions): Promise<AgentPolicy>;
     getSafetyStats(): Promise<Record<string, unknown>>;
     /**
      * Org's subscription on a specific chain. The `network` arg selects
@@ -547,6 +564,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
@@ -561,6 +580,14 @@ declare class Atbash {
      * chains; otherwise the client's default.
      */
     private bridFromChainOpts;
+    /**
+     * Resolve the dashboard chain used by agent metadata/policy reads.
+     * Explicit per-call network overrides win; otherwise use the supplied org
+     * or the client's configured default org. A custom BRID is intentionally
+     * left untouched because it cannot be represented by the dashboard's
+     * public/private query selector.
+     */
+    private resolveAgentLookupNetwork;
     /**
      * Get-or-create a Bearer token for dashboard reads. The token is a
      * signed `log_tool_call` op (locally signed, never submitted) — the
@@ -893,19 +920,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.).
@@ -936,6 +950,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 {
@@ -1000,12 +1016,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;
 };
@@ -1067,12 +1090,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;
@@ -1095,6 +1148,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. */
@@ -1131,12 +1191,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;
 }
@@ -1145,13 +1226,17 @@ declare function createMemoryGuardManager(opts: MemoryGuardManagerOptions): Memo
 /**
  * Atbash SDK Telemetry — OpenTelemetry metrics for usage tracking.
  *
- * Tracks: function call counts, latency, source (CLI/plugin/SDK),
- * and agent identity. ON by default.
+ * Metrics are POSTed to the Atbash-owned `/api/telemetry` proxy, which
+ * verifies the bearer, injects the Honeycomb ingest key server-side, and
+ * forwards to Honeycomb. The ingest credential never enters the SDK.
+ *
+ * Environment opt-out (recommended for air-gapped deployments):
+ * ATBASH_TELEMETRY_DISABLED=1
  *
  * Opt-out: create ~/.config/atbash/telemetry.json with { "enabled": false }
  * The file must be readable by the SDK process. If missing, corrupted, or
- * unreadable → telemetry stays ON. Environment variables cannot disable
- * telemetry (prevents agent bypass via env-var injection).
+ * unreadable, telemetry remains eligible to start unless the environment
+ * opt-out is set.
  */
 type ClientSource = "cli" | "sdk" | "plugin:openclaw" | "plugin:langchain" | "plugin:langgraph" | "plugin:hermes" | "plugin:eliza" | "plugin:crewai" | "plugin:mcp" | "plugin:autogen" | "plugin:jeenai" | (string & {});
 interface TelemetryConfig {
@@ -1161,6 +1246,13 @@ interface TelemetryConfig {
     source?: ClientSource;
     /** Flush interval in ms. Default: 60000 */
     exportIntervalMs?: number;
+    /** Atbash endpoint that hosts /api/telemetry. Required to actually export. */
+    endpoint?: string;
+    /**
+     * Called on every export to obtain fresh auth headers (typically
+     * `{ Authorization: "Bearer <hex>" }`). Required to actually export.
+     */
+    getAuthHeaders?: () => Record<string, string>;
 }
 declare function setupTelemetry(config: TelemetryConfig): void;
 /**
@@ -1280,4 +1372,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, 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 };
+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 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 };