salt-agent-sdk 0.1.0 → 0.19.0

package/dist/client.js

@@ -5,33 +5,107 @@
 // each identity's own api-key per call (a process can act as more than one
 // Salt agent: the primary identity, plus any it spawns via createAgent).
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SaltApiError = void 0;
+exports.RecipientContactsOnlyError = exports.RECIPIENT_CONTACTS_ONLY = exports.SaltApiError = exports.AppStateConflictError = void 0;
+exports.sanitizeAttachmentFilename = sanitizeAttachmentFilename;
+exports.isAsked = isAsked;
 exports.createSaltClient = createSaltClient;
+const node_crypto_1 = require("node:crypto");
+const identity_js_1 = require("./identity.js");
+const recovery_js_1 = require("./recovery.js");
+const crypto_js_1 = require("./crypto.js");
+/**
+ * Basename only, control characters and path separators stripped, capped at
+ * 200 characters, falling back to "attachment" when nothing usable is left.
+ * A filename lives only inside an attachment's PGP-encrypted metadata blob
+ * (see Attachment's header comment in salt-api) -- Salt itself never sees
+ * or sanitizes it -- so anything that later treats a DECRYPTED filename as
+ * a filesystem path (an agent's own read/save-to-disk tool) must sanitize
+ * on the way OUT, since it is exactly as attacker-controlled as any other
+ * chat member's input. Exported so both sendAttachment (outgoing) and a
+ * consumer's incoming-attachment handler can share one rule.
+ */
+function sanitizeAttachmentFilename(name) {
+    const base = String(name ?? "")
+        .split(/[\\/]/)
+        .pop() ?? "";
+    // eslint-disable-next-line no-control-regex
+    const cleaned = base.replace(/[\u0000-\u001f\u007f]/g, "").trim();
+    const safe = cleaned.replace(/^\.+/, "").slice(0, 200);
+    return safe || "attachment";
+}
+/**
+ * Thrown by `setState` on a 409 -- the installation's shared state moved
+ * under the caller since `ifVersion`. Carries the CURRENT `{doc, version}`
+ * straight off the response body (salt-api's own 409 payload), so a caller
+ * can merge its change onto the fresh doc and retry with the new version
+ * rather than spending a second round trip just to re-fetch first.
+ */
+class AppStateConflictError extends Error {
+    doc;
+    version;
+    constructor(doc, version) {
+        super("App state changed under you -- merge onto the current doc and retry with its version.");
+        this.name = "AppStateConflictError";
+        this.doc = doc;
+        this.version = version;
+    }
+}
+exports.AppStateConflictError = AppStateConflictError;
+function isAsked(value) {
+    return !!value && typeof value === "object" && value.asked === true;
+}
+const postMediaFields = (media) => ({
+    post_media: Buffer.from(media.data).toString("base64"),
+    post_media_content_type: media.contentType,
+});
 class SaltApiError extends Error {
     status;
     body;
+    /** Salt's machine-readable refusal code (`{error, code}`), when the body carries one. */
+    code;
     constructor(method, url, status, body) {
-        super(`Salt API ${method} ${url} -> ${status}`);
+        // Salt's refusals carry one plain sentence ({error: "..."}). Put it in
+        // the message: a tool result that says only "-> 422" leaves a model
+        // guessing, while "The person has not said anything since the last
+        // hand-off. Answer them yourself..." tells it what to do instead.
+        // POST /auth (self-registration) answers {status: {message}} instead.
+        const b = body && typeof body === "object" ? body : undefined;
+        const sentence = typeof b?.error === "string" ? b.error : typeof b?.status?.message === "string" ? b.status.message : undefined;
+        const reason = sentence ? `: ${sentence}` : "";
+        super(`Salt API ${method} ${url} -> ${status}${reason}`);
         this.name = "SaltApiError";
         this.status = status;
         this.body = body;
+        if (typeof b?.code === "string")
+            this.code = b.code;
     }
 }
 exports.SaltApiError = SaltApiError;
-/**
- * Creates a REST client bound to a Salt deployment's host. Every method
- * takes the acting identity's own api-key explicitly rather than a
- * module-level header, since one process can legitimately act as several
- * Salt agents at once.
- */
+exports.RECIPIENT_CONTACTS_ONLY = "recipient_contacts_only";
+/** 403 `recipient_contacts_only`: the recipient only takes messages from their contacts and the caller is
+ *  not one, so no chat was created. `message` ends with the server's own sentence ("<name> only takes
+ *  messages from their contacts."), also on `sentence`. Do not retry; a request for contact is the only way in. */
+class RecipientContactsOnlyError extends SaltApiError {
+    sentence;
+    constructor(method, url, status, body) {
+        super(method, url, status, body);
+        this.name = "RecipientContactsOnlyError";
+        this.code = exports.RECIPIENT_CONTACTS_ONLY;
+        const e = body?.error;
+        this.sentence = typeof e === "string" ? e : "This person only takes messages from their contacts.";
+    }
+}
+exports.RecipientContactsOnlyError = RecipientContactsOnlyError;
 function createSaltClient(options) {
     const host = options.host.replace(/\/$/, "");
     const doFetch = options.fetchImpl ?? fetch;
-    async function request(method, path, apiKey, body, extraHeaders) {
+    const request = async function request(method, path, apiKey, body, opts) {
         const url = `${host}${path}`;
-        const headers = { "api-key": apiKey, ...extraHeaders };
+        const headers = { "api-key": apiKey, ...opts?.extraHeaders };
         if (body !== undefined)
             headers["Content-Type"] = "application/json";
+        if (opts?.idempotencyKey)
+            headers["Idempotency-Key"] = opts.idempotencyKey;
         const res = await doFetch(url, {
             method,
             headers,
@@ -45,144 +119,1194 @@ function createSaltClient(options) {
             catch {
                 parsed = await res.text().catch(() => undefined);
             }
+            if (res.status === 403 && parsed?.code === exports.RECIPIENT_CONTACTS_ONLY) {
+                throw new RecipientContactsOnlyError(method, url, res.status, parsed);
+            }
             throw new SaltApiError(method, url, res.status, parsed);
         }
         if (res.status === 204)
             return undefined;
-        return (await res.json());
+        const parsed = (await res.json());
+        // A mandate-governed call in "ask" mode never 4xx/5xxs and never throws --
+        // salt-api answers 202 `{status: "asked", exercise_id, expires_at}` instead
+        // (see actFor below). Reachable only through a call that actually carried
+        // X-Salt-Act-For; an ordinary (non-acting) call never gets asked, since
+        // authorize_acting! only runs when that header is present.
+        if (res.status === 202 && parsed && typeof parsed === "object" && parsed.status === "asked") {
+            const asked = parsed;
+            const result = { asked: true, exerciseId: asked.exercise_id, expiresAt: asked.expires_at };
+            return result;
+        }
+        return parsed;
+    };
+    /** `actFor`'s per-call header injection: `X-Salt-Act-For`/`X-Salt-Mandate` on everything, plus an
+     *  `Idempotency-Key` auto-generated for POST/PATCH when the caller didn't already supply one --
+     *  ask-mode calls need one to be safely retried, and every acting call is potentially ask-mode. */
+    function actingRequest(principalId, mandateId) {
+        return function actingRequestFn(method, path, apiKey, body, opts) {
+            const extraHeaders = { "X-Salt-Act-For": String(principalId), ...opts?.extraHeaders };
+            if (mandateId != null)
+                extraHeaders["X-Salt-Mandate"] = String(mandateId);
+            const isWrite = method === "POST" || method === "PATCH";
+            const idempotencyKey = opts?.idempotencyKey ?? (isWrite ? (0, node_crypto_1.randomUUID)() : undefined);
+            return request(method, path, apiKey, body, { extraHeaders, idempotencyKey });
+        };
+    }
+    async function whoAmI(apiKey) {
+        // Cache-busted: the answer changes on rotation and on re-keying, and a
+        // stale intermediary copy would quietly defeat both.
+        return request("GET", `/api/v1/agents/webhook_secret?_=${Date.now()}`, apiKey);
+    }
+    // Salt's Web Bot Auth signing key(s), published unauthenticated at the
+    // domain root (see salt-api's WebBotAuthController) -- the SAME key
+    // AgentCardSigner signs cards with. Cached per client instance, honouring
+    // the directory's own Cache-Control: max-age (the controller sends 300s;
+    // DEFAULT_DIRECTORY_MAX_AGE_MS stands in when the header is absent or
+    // unparseable) so a long-lived process doesn't re-fetch on every card()
+    // call, but also doesn't hold a stale key set indefinitely. Beyond age-based
+    // expiry, card() below also forces a refetch the moment a card names a
+    // kid this cache doesn't have -- see its comment for why that matters
+    // more than the age check alone (a rotation can land well inside the
+    // 5-minute window). A failed fetch never poisons the cache: the in-flight
+    // promise is cleared in `finally` so the next call (forced or not) tries again.
+    const DEFAULT_DIRECTORY_MAX_AGE_MS = 300_000;
+    let signingKeysCache = null;
+    let signingKeysInFlight = null;
+    function directoryMaxAgeMs(res) {
+        const raw = res.headers?.get?.("Cache-Control") ?? res.headers?.get?.("cache-control");
+        const match = raw ? /max-age=(\d+)/i.exec(raw) : null;
+        const seconds = match ? Number(match[1]) : NaN;
+        return Number.isFinite(seconds) && seconds >= 0 ? seconds * 1000 : DEFAULT_DIRECTORY_MAX_AGE_MS;
     }
-    return {
-        /** A chat's members (with public keys), for encrypting a reply to everyone who should read it. */
-        async getChatMembers(apiKey, chatId) {
-            const chat = await request("GET", `/api/v1/chats/${chatId}?_=${Date.now()}`, apiKey);
-            return chat?.session?.users ?? [];
-        },
-        /** Recent messages in a chat this identity is a member of (even as a silent observer). */
-        async getChatMessages(apiKey, chatId) {
-            const chat = await request("GET", `/api/v1/chats/${chatId}?_=${Date.now()}`, apiKey);
-            return chat?.messages ?? [];
-        },
-        /** Download an attachment's ciphertext bytes. Decrypt separately (see crypto.ts). */
-        async getAttachment(apiKey, messageId) {
-            const url = `${host}/api/v1/messages/${messageId}/attachment`;
-            const res = await doFetch(url, { headers: { "api-key": apiKey } });
-            if (!res.ok)
-                throw new SaltApiError("GET", url, res.status, await res.text().catch(() => undefined));
-            return Buffer.from(await res.arrayBuffer());
-        },
-        /**
-         * Post a reply into a chat. `message` is the ciphertext every human
-         * recipient reads; `senderMessage` is the copy encrypted to the
-         * sender's own key. `delegations` (optional) is the provenance trail
-         * -- salt-api re-validates every entry against the sender's actual
-         * memberships before storing it.
-         */
-        async postMessage(apiKey, chatId, message, senderMessage, delegations) {
-            const body = { chat_id: chatId, message, sender_message: senderMessage };
-            if (delegations && delegations.length > 0)
-                body.delegations = delegations;
-            return request("POST", "/api/v1/messages", apiKey, body);
-        },
-        /** Register a new Salt agent, owned by whoever's api-key calls this. */
-        async createAgent(apiKey, params) {
-            return request("POST", "/api/v1/agents", apiKey, params);
-        },
-        /** Owner-only: fetch an agent's own api-key + PGP keypair right after creating it. */
-        async getAgentAdmin(apiKey, agentId) {
-            return request("GET", `/api/v1/agents/${agentId}/admin`, apiKey);
-        },
-        /** The public Agents directory. */
-        async listAgents(apiKey) {
-            return request("GET", "/api/v1/agents", apiKey);
-        },
-        /** A single agent's directory entry. */
-        async getAgent(apiKey, agentId) {
-            return request("GET", `/api/v1/agents/${agentId}`, apiKey);
-        },
-        /** Create-or-reuse a 1:1 chat with `contactId` -- idempotent on Salt's side. */
-        async createOrGetChat(apiKey, contactId) {
-            return request("POST", "/api/v1/chats", apiKey, { contact_id: contactId });
-        },
-        /** Post a declarative blocks card into a chat (see CARD_PROTOCOL_SPEC.md / cards.ts). */
-        async postCard(apiKey, chatId, blocks, text) {
-            return request("POST", "/api/v1/cards", apiKey, { chat_id: chatId, blocks, text });
-        },
-        /** Replace an owned card's blocks -- re-broadcasts into everyone's bubble live. */
-        async updateCard(apiKey, cardId, blocks) {
-            return request("PATCH", `/api/v1/cards/${cardId}`, apiKey, { blocks });
-        },
-        // --- Commerce (products, invoices, prepaid credits) ---
-        /** My own products (sellerId omitted) or a seller's active products (sellerId given). */
-        async listProducts(apiKey, sellerId) {
-            const path = sellerId ? `/api/v1/products?seller_id=${sellerId}` : "/api/v1/products";
-            return request("GET", path, apiKey);
-        },
-        /** Create a product in the caller's shop. */
-        async createProduct(apiKey, params) {
-            return request("POST", "/api/v1/products", apiKey, params);
-        },
-        /** Drop one of the caller's products into a chat as a Buy-able bubble. */
-        async shareProduct(apiKey, productId, chatId) {
-            return request("POST", `/api/v1/products/${productId}/share`, apiKey, { chat_id: chatId });
-        },
-        /** Send an itemized invoice on the TransferRequest rail. Server re-validates all the math. */
-        async createInvoice(apiKey, params) {
-            return request("POST", "/api/v1/transfer_requests", apiKey, {
-                chat_id: params.chatId,
-                receiver_id: params.receiverId,
-                wallet_id: params.walletId,
-                amount: params.amount,
-                message: params.message,
-                request_type: "invoice",
-                line_items: params.lineItems,
-                due_at: params.dueAt,
+    async function getSigningKeys(opts) {
+        if (opts?.forceRefresh)
+            signingKeysCache = null;
+        const stale = !signingKeysCache || Date.now() - signingKeysCache.fetchedAt > signingKeysCache.maxAgeMs;
+        if (!stale)
+            return signingKeysCache.keys;
+        if (!signingKeysInFlight) {
+            signingKeysInFlight = (async () => {
+                const url = `${host}/.well-known/http-message-signatures-directory`;
+                const res = await doFetch(url);
+                if (!res.ok)
+                    throw new SaltApiError("GET", url, res.status, await res.text().catch(() => undefined));
+                const body = (await res.json());
+                const keys = body.keys ?? [];
+                signingKeysCache = { keys, fetchedAt: Date.now(), maxAgeMs: directoryMaxAgeMs(res) };
+                return keys;
+            })().finally(() => {
+                signingKeysInFlight = null;
             });
-        },
-        /** Record metered usage against the payer's prepaid credits. */
-        async addUsage(apiKey, params) {
-            const body = {
-                product_id: params.productId,
-                chat_id: params.chatId,
-                qty: params.qty,
-                description: params.description,
-            };
-            if (params.payerId)
-                body.payer_id = params.payerId;
-            return request("POST", "/api/v1/usage_events", apiKey, body);
-        },
-        /** The caller's credit relationships, both directions. */
-        async getBillingAccounts(apiKey) {
-            return request("GET", `/api/v1/billing_accounts?_=${Date.now()}`, apiKey);
-        },
-        /** The caller's own wallets. */
-        async listWallets(apiKey) {
-            return request("GET", "/api/v1/wallets", apiKey);
-        },
-        /** Upload an already-encrypted wallet under the caller's own identity (see crypto.ts). */
-        async createWallet(apiKey, params) {
-            return request("POST", "/api/v1/wallets", apiKey, params);
-        },
-        /** Hand a chat off to another agent; salt-api does the whole swap atomically. */
-        async handOff(apiKey, chatId, toAgentId, reason) {
-            return request("POST", `/api/v1/chats/${chatId}/hand_off`, apiKey, { to_agent_id: toAgentId, reason });
-        },
-        /** Ephemeral "is typing" ping. Fire-and-forget by design -- a failed ping must never block a reply. */
-        async signalTyping(apiKey, chatId) {
-            try {
-                await request("POST", `/api/v1/chats/${chatId}/typing`, apiKey, {});
-            }
-            catch {
-                // non-fatal by design
-            }
-        },
-        /**
-         * Fire-and-forget product-metrics beacon. Deliberately not awaited by
-         * callers -- an analytics post must never delay or fail a reply. Only
-         * names in salt-api's Event::CLIENT_EVENT_NAMES allowlist are accepted.
-         */
-        trackEvent(apiKey, name, properties = {}) {
-            request("POST", "/api/v1/events", apiKey, { name, properties }).catch(() => { });
-        },
-    };
+        }
+        return signingKeysInFlight;
+    }
+    /** Builds the full method surface once per `request` implementation -- called once for the base
+     *  (as-yourself) client and again, with `actingRequest`'s header-injecting wrapper, from `actFor`
+     *  below. Every method here is written exactly as it always was; only the `request` it closes
+     *  over differs between the two callers. */
+    function buildMethods(request) {
+        return {
+            /** A chat's members (with public keys), for encrypting a reply to everyone who should read it. */
+            async getChatMembers(apiKey, chatId) {
+                const chat = await request("GET", `/api/v1/chats/${chatId}?_=${Date.now()}`, apiKey);
+                return chat?.session?.users ?? [];
+            },
+            /** Recent messages in a chat this identity is a member of (even as a silent observer). */
+            async getChatMessages(apiKey, chatId) {
+                const chat = await request("GET", `/api/v1/chats/${chatId}?_=${Date.now()}`, apiKey);
+                return chat?.messages ?? [];
+            },
+            /**
+             * One `GET /api/v1/chats/:id` call for a caller that needs BOTH the
+             * member list and whether the chat is end-to-end encrypted -- e.g.
+             * actions.ts's request_floor, which (unlike delegate_to_agent/
+             * consult_agent) has no other reason to fetch the chat at all.
+             * `encrypted` is already resolved to a real boolean (defaulted `true`
+             * when the field is absent, same convention as ChatOpenedContext.encrypted
+             * and MessageContext.encrypted) -- never undefined.
+             */
+            async getChat(apiKey, chatId) {
+                const chat = await request("GET", `/api/v1/chats/${chatId}?_=${Date.now()}`, apiKey);
+                return { id: chatId, encrypted: chat?.session?.encrypted !== false, users: chat?.session?.users ?? [] };
+            },
+            /**
+             * Salt's own record of a chat, exactly as `GET /api/v1/chats/:id` answers
+             * it (nothing flattened or defaulted, unlike getChat): `session.users`
+             * with each member's `observer` flag, `session.public`, `session.encrypted`.
+             * This is what `isPrivateChat(chat, speakerId, myId)` reads -- decide
+             * privacy-sensitive actions from THIS, fetched when you need it, never
+             * from a cache or a memory service.
+             */
+            async getChatRecord(apiKey, chatId) {
+                return request("GET", `/api/v1/chats/${chatId}?_=${Date.now()}`, apiKey);
+            },
+            /** Download an attachment's ciphertext bytes. Decrypt separately (see crypto.ts). */
+            async getAttachment(apiKey, messageId) {
+                const url = `${host}/api/v1/messages/${messageId}/attachment`;
+                const res = await doFetch(url, { headers: { "api-key": apiKey } });
+                if (!res.ok)
+                    throw new SaltApiError("GET", url, res.status, await res.text().catch(() => undefined));
+                return Buffer.from(await res.arrayBuffer());
+            },
+            /**
+             * Post a reply into a chat. `message` is the ciphertext every human
+             * recipient reads; `senderMessage` is the copy encrypted to the
+             * sender's own key. `delegations` (optional) is the provenance trail
+             * -- salt-api re-validates every entry against the sender's actual
+             * memberships before storing it. The result carries `delivered_as`:
+             * `"request"` means the recipient has not accepted a first message from
+             * you yet (see Message requests in AGENTS.md) -- wait, do not re-send.
+             */
+            async postMessage(apiKey, chatId, message, senderMessage, delegations, 
+            // Who this reply addresses. Salt never sees the plaintext, so an "@handle"
+            // written into the body is invisible to it -- these ids are what actually
+            // reach the person as a mention notification. Without them a reply can
+            // SAY it is addressed to someone and, as far as the server is concerned,
+            // be addressed to nobody.
+            mentions, 
+            // `quiet` (salt-api 0.55.0): no push for this message. Honoured only for
+            // an agent posting into a private lane -- a progress report (work.ts) --
+            // and silently dropped anywhere else.
+            opts) {
+                const body = { chat_id: chatId, message, sender_message: senderMessage };
+                if (delegations && delegations.length > 0)
+                    body.delegations = delegations;
+                if (mentions && mentions.length > 0)
+                    body.mentions = mentions;
+                if (opts?.quiet)
+                    body.quiet = true;
+                return request("POST", "/api/v1/messages", apiKey, body);
+            },
+            /**
+             * Sends a file into a chat, encrypted exactly the way salt-fe's
+             * chatbox.jsx sendOneAttachment encrypts one: a fresh one-time AES-256-
+             * GCM key encrypts the file bytes (crypto.ts's encryptAttachment,
+             * byte-identical wire format to the browser's Web Crypto output), and
+             * that key/iv plus the real filename/content_type/size are PGP-
+             * encrypted as one JSON blob for every current chat member's public
+             * key -- the SAME single recipient list the caption text is encrypted
+             * for, fetched fresh via GET /api/v1/chats/:id so a just-added or
+             * just-removed member is never missed or over-included. Unlike
+             * postMessage's reply() there is no separate sender_message: the web
+             * never excludes the sender from an attachment's recipient list (it
+             * has no reason to -- there's only one `attachment_encrypted_key`
+             * field, see Attachment#as_chat_resource), so a single PGP blob
+             * covering every member already covers the sender too.
+             *
+             * Throws before doing any crypto work on an oversized file (matches
+             * salt-api's own MAX_ATTACHMENT_BYTES so a doomed upload never even
+             * starts) or a content_type outside ALLOWED_SEND_CONTENT_TYPES.
+             */
+            async sendAttachment(apiKey, chatId, params) {
+                if (params.bytes.length > crypto_js_1.MAX_ATTACHMENT_BYTES) {
+                    throw new Error(`attachment too large: ${params.bytes.length} bytes (cap ${crypto_js_1.MAX_ATTACHMENT_BYTES})`);
+                }
+                if (!(0, crypto_js_1.isAllowedSendContentType)(params.contentType)) {
+                    throw new Error(`content type not allowed: ${params.contentType}`);
+                }
+                const filename = sanitizeAttachmentFilename(params.filename);
+                const chat = await request("GET", `/api/v1/chats/${chatId}?_=${Date.now()}`, apiKey);
+                const recipientKeys = (chat?.session?.users ?? [])
+                    .map((u) => u.public_key)
+                    .filter((k) => Boolean(k));
+                if (recipientKeys.length === 0) {
+                    throw new Error(`chat ${chatId}: no recipient public keys; not sending attachment.`);
+                }
+                const { ciphertext, keyB64, ivB64 } = (0, crypto_js_1.encryptAttachment)(params.bytes);
+                const metaJson = JSON.stringify({
+                    key: keyB64,
+                    iv: ivB64,
+                    filename,
+                    content_type: params.contentType,
+                    size: params.bytes.length,
+                });
+                const caption = params.caption || `📎 ${filename}`;
+                const [encryptedMeta, encryptedCaption] = await Promise.all([
+                    (0, crypto_js_1.encryptFor)(metaJson, recipientKeys),
+                    (0, crypto_js_1.encryptFor)(caption, recipientKeys),
+                ]);
+                return request("POST", "/api/v1/messages", apiKey, {
+                    chat_id: chatId,
+                    message: encryptedCaption,
+                    attachment: ciphertext.toString("base64"),
+                    attachment_encrypted_key: encryptedMeta,
+                });
+            },
+            /**
+             * Post into an OPEN ROOM -- a chat with no end-to-end encryption, so
+             * `text` rides the wire and is stored as plain text rather than a PGP
+             * blob. There is no `senderMessage`/`delegations`/`mentions` shape here
+             * the way postMessage has: salt-api refuses this call 422 against a
+             * chat that isn't plain (never silently encrypts, never silently
+             * drops the call). Webhook/socket deliveries for a plain chat carry
+             * `message.encrypted === false` -- see webhook.ts's handleMessage,
+             * which hands the body straight through as ctx.text (ctx.encrypted
+             * false) instead of attempting PGP decrypt.
+             */
+            async postPlainMessage(apiKey, chatId, text) {
+                return request("POST", "/api/v1/messages", apiKey, { chat_id: chatId, message: text });
+            },
+            /**
+             * Open rooms (0.6x): declares what this identity wants delivered from
+             * a chat it isn't necessarily addressed in every message of --
+             * `"addressed"` (only a direct reply/@mention, the closest analogue to
+             * how a normal encrypted chat already gates agent delivery),
+             * `"keywords"` (any message containing one of `keywords`), or `"all"`
+             * (every message). Always this identity's OWN subscription for
+             * `chatId` -- same "acts on the caller, never someone else" shape as
+             * setDeliveryMode/setCallback.
+             */
+            async setChatSubscription(apiKey, chatId, params) {
+                const body = { mode: params.mode };
+                if (params.keywords && params.keywords.length > 0)
+                    body.keywords = params.keywords;
+                return request("PUT", `/api/v1/chats/${chatId}/subscription`, apiKey, body);
+            },
+            /** Removes this identity's subscription record for `chatId` -- salt-api's
+             *  default (unsubscribed) behavior applies again, same as never having
+             *  called setChatSubscription. */
+            async clearChatSubscription(apiKey, chatId) {
+                return request("DELETE", `/api/v1/chats/${chatId}/subscription`, apiKey);
+            },
+            /**
+             * Get-or-create the private lane (a sidechain) between this identity and
+             * `withId`, both members of `chatId`. Once per pair on Salt's side. Answers
+             * 422 when `chatId` is itself a lane. The lane's members come back with
+             * their public keys.
+             */
+            async openSidechain(apiKey, chatId, withId) {
+                return request("POST", `/api/v1/chats/${chatId}/sidechain?_=${Date.now()}`, apiKey, { with_id: withId });
+            },
+            /**
+             * Opens (or reuses) a CONSULT lane between the caller and `withId`, both
+             * already members of `roomId` -- mechanically identical to
+             * openSidechain (same endpoint, same get-or-create-per-pair semantics),
+             * named separately because actions.ts's consult_agent reads more
+             * clearly calling "open the lane I'm about to consult in" than a
+             * generic sidechain call. salt-api tags the resulting chat
+             * `lane_kind: "consult"`, which webhook.ts reads back off the webhook
+             * body to raise the agent-to-agent reply cap for that lane and to gate
+             * request_floor.
+             */
+            async openConsultLane(apiKey, roomId, withId) {
+                return request("POST", `/api/v1/chats/${roomId}/sidechain?_=${Date.now()}`, apiKey, { with_id: withId });
+            },
+            /** Register a new Salt agent, owned by whoever's api-key calls this. */
+            /**
+             * The create response carries the new agent's raw api key EXACTLY ONCE --
+             * salt-api stores only a digest, so no later endpoint can show it again.
+             * Capture `api_key` here; a lost key means rotateAgentApiKey, not re-reading.
+             *
+             * Key custody: `CreateAgentParams` deliberately has no `private_key` --
+             * salt-api rejects one with a 422 unconditionally (salt-api docs/
+             * KEY_CUSTODY.md Phase 5). The key stays with whoever generates it
+             * (pgp.generateKeypair, above the call site) and is registered with
+             * identities.register/a session store; salt-api never receives a copy in
+             * any form it can decrypt, so there is nothing to fetch back later --
+             * getAgentAdmin's `userkeys` never carries a usable key either.
+             */
+            async createAgent(apiKey, params) {
+                return request("POST", "/api/v1/agents", apiKey, params);
+            },
+            /**
+             * Draft an agent from one line (`POST /api/v1/agents/draft`): a person (token) or an agent by its own api-key.
+             * Returns the WHOLE draft; each `step` rewrites only its own fields and keeps the rest exactly as sent, so
+             * pass the person's edited draft back in. The AI proposes, the caller confirms: nothing is created. A model
+             * failure is a 502 `SaltApiError` (`code: "draft_failed"`); a spent budget is a 429 or 402 with one sentence.
+             * See AGENTS.md, "Make an agent from one line".
+             */
+            async draftAgent(apiKey, params) {
+                const res = await request("POST", "/api/v1/agents/draft", apiKey, params);
+                return res.draft;
+            },
+            /**
+             * Draft a whole team from one line (`POST /api/v1/teams/draft`): two to five agents, one lead, a role each, in
+             * one call per step (not one per member). Same contract as `draftAgent`: returns the WHOLE draft, a step
+             * rewrites only its own fields, nothing is created, and the AI proposes while the caller confirms. See AGENTS.md,
+             * "Teams: one room, the lead is the arbiter".
+             */
+            async draftTeam(apiKey, params) {
+                const res = await request("POST", "/api/v1/teams/draft", apiKey, params);
+                return res.draft;
+            },
+            /** Owner-only: make one member the team's lead (the arbiter of its room), or pass null for no lead. The lead must be a member the owner owns (422). */
+            async setTeamLead(apiKey, groupId, leadAgentId) {
+                return request("PATCH", `/api/v1/agent_groups/${groupId}`, apiKey, { lead_agent_id: leadAgentId });
+            },
+            /** Owner-only: set a member's job in the team ("Showrunner"; at most 40 characters, blank clears it). */
+            async setMemberRole(apiKey, groupId, agentId, role) {
+                return request("PATCH", `/api/v1/agent_groups/${groupId}/members/${agentId}`, apiKey, { role });
+            },
+            /** Owner-only: make (or return) the team's room, one encrypted group chat with you and every member. Idempotent. `left_out` is present only when positive: members the owner does not own are not added to the room. */
+            async openTeamRoom(apiKey, groupId) {
+                return request("POST", `/api/v1/agent_groups/${groupId}/room`, apiKey, {});
+            },
+            /** The teams the caller is a member of, with each lead, room and roster (`GET /api/v1/agent/teams`, by the agent's own api-key). This is how a team agent learns who else is in its room. */
+            async myTeams(apiKey) {
+                const res = await request("GET", "/api/v1/agent/teams", apiKey);
+                return res.teams;
+            },
+            /** Owner-only: mint a new api key for an agent. The old one stops working immediately. */
+            async rotateAgentApiKey(apiKey, agentId) {
+                return request("POST", `/api/v1/agents/${agentId}/rotate_api_key`, apiKey);
+            },
+            /**
+             * This identity's own webhook signing key, used to verify that an incoming
+             * webhook really came from salt-api.
+             *
+             * Fetched with the identity's own api key rather than configured from the
+             * environment: salt-api mints one secret per agent, so shipping them through
+             * env/Secrets Manager would mean the deploy had to know values the API
+             * generates. Fetching at boot also means rotation takes effect on restart.
+             */
+            async getWebhookSecret(apiKey) {
+                return (await whoAmI(apiKey))?.webhook_secret;
+            },
+            /**
+             * Which agent does this api key belong to, according to salt-api?
+             *
+             * The same endpoint as getWebhookSecret: alongside the secret it returns
+             * the canonical `agent_id` of the key's owner, which is the id salt-api
+             * puts in X-Salt-Agent-Id on every callback. An identity registered under
+             * any other id -- an env var, or a store entry that predates an id
+             * migration -- can never be found when a webhook arrives; that is what
+             * reconcileIdentityIds uses this to detect and repair.
+             */
+            whoAmI,
+            /**
+             * Owner-only: mint a new webhook signing secret for an agent. The old
+             * secret stops verifying immediately, so the agent must re-fetch via
+             * getWebhookSecret before it can validate any further deliveries.
+             */
+            async rotateWebhookSecret(apiKey, agentId) {
+                return request("POST", `/api/v1/agents/${agentId}/rotate_webhook_secret`, apiKey);
+            },
+            /**
+             * The caller sets its OWN webhook callback -- api-key auth, no id
+             * parameter, same "acts on the caller, never someone else" shape as
+             * setDeliveryMode/setChatSubscription. Exists so the platform hosting
+             * an agent can point its callback at itself without the owner ever
+             * opening Salt's web console -- see AgentsController#set_callback's
+             * own comment. Same URL-safety rule as the owner's web form
+             * (User#callback_must_be_safe) applies server-side; a human caller
+             * (not an agent's own api-key) gets a 403.
+             */
+            async setCallback(apiKey, webhook) {
+                return request("PATCH", "/api/v1/agents/callback", apiKey, { webhook });
+            },
+            /**
+             * K2 socket mode: the caller sets its OWN delivery mode -- "webhook"
+             * (the default, POST to its registered callback) or "socket" (drain
+             * GET /api/v1/agent/updates or AgentUpdatesChannel instead; see
+             * socket.ts's createSocketClient). No id parameter, same reason
+             * getWebhookSecret has none -- an agent can only ever change its own.
+             * A blank callback is always socket mode regardless of this setting.
+             */
+            async setDeliveryMode(apiKey, mode) {
+                return request("PATCH", "/api/v1/agents/delivery", apiKey, { mode });
+            },
+            /**
+             * Owner-only agent admin record. `apikey` is metadata (hint, last-used) --
+             * the raw key rides only on the createAgent response, and after that only
+             * rotateAgentApiKey can produce a usable value.
+             */
+            async getAgentAdmin(apiKey, agentId) {
+                return request("GET", `/api/v1/agents/${agentId}/admin`, apiKey);
+            },
+            /**
+             * Owner-only: set an agent's photo (`PUT /api/v1/agents/:id/admin_update`, `partial: true` so nothing else
+             * changes). PNG, JPEG, WebP or GIF up to 3 MB; anything else is a 422 with one sentence. A photo the owner
+             * sets becomes its face. Both the photo and the drawing are kept; see `setAgentFace`.
+             */
+            async setAgentPhoto(apiKey, agentId, photo) {
+                return request("PUT", `/api/v1/agents/${agentId}/admin_update`, apiKey, {
+                    partial: true,
+                    avatar: Buffer.from(photo.bytes).toString("base64"),
+                    avatar_content_type: photo.contentType,
+                });
+            },
+            /** Owner-only: choose which face is shown, `"photo"` or `"drawing"`. `"photo"` with no photo uploaded is a 422
+             *  ("Upload a photo first."). The owner's choice outranks the agent's own. */
+            async setAgentFace(apiKey, agentId, face) {
+                return request("PUT", `/api/v1/agents/${agentId}/admin_update`, apiKey, { partial: true, face });
+            },
+            /**
+             * Owner-only: set the agent's own model spend limit per UTC month in USD (`PATCH /api/v1/agents/:id/persona`, the
+             * route the web uses; a number from 1 to 1000, sent as a string, default 10 when never set). Past it the agent pauses until
+             * the month turns or the owner raises it. Anything else is a 422 with one sentence.
+             */
+            async setAgentBudget(apiKey, agentId, usd) {
+                return request("PATCH", `/api/v1/agents/${agentId}/persona`, apiKey, { persona: { model_budget_usd: String(usd) } });
+            },
+            /** Owner-only: remove the agent's photo; its drawing shows again. */
+            async removeAgentPhoto(apiKey, agentId) {
+                return request("PUT", `/api/v1/agents/${agentId}/admin_update`, apiKey, { partial: true, remove_avatar: true });
+            },
+            // --- Identity (identity.ts): this agent's own claim sections + anyone's signed card ---
+            /**
+             * This agent's own identity: every section (claim and proof) with
+             * `scope`/`editable_by`/`checked_by`, plus the public card URL it's
+             * served from. Cache-busted like getChatMembers -- a value just set
+             * with setIdentity should read back immediately.
+             */
+            async identity(apiKey) {
+                return request("GET", `/api/v1/identity?_=${Date.now()}`, apiKey);
+            },
+            /**
+             * Set one or more of this agent's own CLAIM sections (see
+             * AGENT_CLAIM_SECTION_KEYS). `scope` is never accepted here -- section
+             * visibility is owner-authenticated through the agent-management API
+             * only (plan section 7: "setScope is never on this surface"), so a
+             * caller that tries to slip one in is refused BEFORE any request is
+             * made, the same way a bad tool call should fail loud and immediately
+             * rather than round-tripping to find out the server also says no.
+             * A 422 from salt-api ({errors: {key: "line"}} for an invalid value, or
+             * {error: "Scope comes later."} were scope to somehow reach it anyway)
+             * surfaces as an ordinary SaltApiError.
+             */
+            async setIdentity(apiKey, claims) {
+                if (claims && Object.prototype.hasOwnProperty.call(claims, "scope")) {
+                    throw new Error('setIdentity cannot set "scope" -- section visibility is owner-controlled, not agent-controlled, and isn\'t on this SDK surface at all yet.');
+                }
+                return request("PATCH", "/api/v1/identity/sections", apiKey, claims);
+            },
+            /**
+             * Writes one disclosure ledger row -- metadata only, never a section
+             * VALUE (plan section 4). identityShare.ts's share() calls this once
+             * per recipient BEFORE sending any ciphertext, with the SAME `id` every
+             * time (the row is keyed on subject + recipient + id, so this creates
+             * one row per recipient under one shared id), and aborts the whole
+             * share on the first refusal (422, one plain sentence -- e.g. a key
+             * that isn't actually shared with that recipient) with nothing sent.
+             */
+            async postIdentityDisclosure(apiKey, params) {
+                return request("POST", "/api/v1/identity/disclosures", apiKey, params);
+            },
+            /**
+             * Records which chat message actually carried a share's slice, once
+             * it's been posted. Called ONCE per share() call (with the share's one
+             * `id`) right after the one encrypted SLICE message goes out
+             * (identityShare.ts's share()) -- since every recipient's row shares
+             * that id, one PATCH reaches all of them.
+             */
+            async setIdentityDisclosureMessage(apiKey, id, messageId) {
+                return request("PATCH", `/api/v1/identity/disclosures/${id}`, apiKey, { message_id: messageId });
+            },
+            /** This agent's own disclosure ledger, newest first. */
+            async listIdentityDisclosures(apiKey, opts) {
+                const params = new URLSearchParams();
+                if (opts?.before)
+                    params.set("before", opts.before);
+                if (opts?.limit != null)
+                    params.set("limit", String(opts.limit));
+                params.set("_", String(Date.now()));
+                return request("GET", `/api/v1/identity/disclosures?${params.toString()}`, apiKey);
+            },
+            /**
+             * Revokes EVERY ledger row under `id` (every recipient of that share)
+             * in one call -- stops them being served again and is the signal
+             * identityShare.ts's revoke() sends a `[[SALT-IDENTITY-REVOKE]]` wire
+             * marker off of. Cannot reach a message already read; the rows
+             * themselves are the only thing this call changes.
+             */
+            async revokeIdentityDisclosure(apiKey, id) {
+                return request("POST", `/api/v1/identity/disclosures/${id}/revoke`, apiKey);
+            },
+            /**
+             * Fetches a person's or an agent's PUBLICLY SERVED signed card and
+             * verifies its signature before returning it -- this is a public,
+             * unauthenticated GET (no api-key), matching agent_cards_controller's
+             * `skip_before_action :auth_user`. Tries the agent path then the user
+             * path unless `opts.kind` says which one. A card whose signature this
+             * SDK cannot confirm (missing, unparseable, unknown key, tampered)
+             * throws IdentityCardInvalidError rather than ever coming back
+             * `verified: false` -- a card either verifies or this call fails.
+             */
+            async card(handle, opts) {
+                const clean = String(handle || "")
+                    .replace(/^@/, "")
+                    .trim();
+                if (!clean)
+                    throw new Error("card: handle is required.");
+                const attempts = opts?.kind === "agent"
+                    ? [{ url: `${host}/api/v1/agents/${encodeURIComponent(clean)}/agent-card.json` }]
+                    : opts?.kind === "user"
+                        ? [{ url: `${host}/api/v1/users/${encodeURIComponent(clean)}/card.json` }]
+                        : [
+                            { url: `${host}/api/v1/agents/${encodeURIComponent(clean)}/agent-card.json` },
+                            { url: `${host}/api/v1/users/${encodeURIComponent(clean)}/card.json` },
+                        ];
+                let lastError;
+                for (const attempt of attempts) {
+                    let res;
+                    try {
+                        res = await doFetch(attempt.url);
+                    }
+                    catch (err) {
+                        lastError = err;
+                        continue;
+                    }
+                    if (res.status === 404) {
+                        lastError = new SaltApiError("GET", attempt.url, 404, await res.json().catch(() => undefined));
+                        continue;
+                    }
+                    if (!res.ok) {
+                        throw new SaltApiError("GET", attempt.url, res.status, await res.json().catch(() => undefined));
+                    }
+                    const card = (await res.json());
+                    let jwks = await getSigningKeys();
+                    // A card signed with a kid this cache doesn't have could mean Salt
+                    // rotated its key since we last fetched the directory (well inside
+                    // the max-age window, since rotation doesn't wait for a cache to
+                    // expire) rather than a bad card -- refetch once before deciding.
+                    // Never retried for any OTHER verification failure (bad signature,
+                    // unparseable header, unsupported alg): those can't be fixed by a
+                    // fresher key set, so they fail immediately.
+                    const header = (0, identity_js_1.parseCardSignatureHeader)(card);
+                    if (header?.kid && !jwks.some((k) => k.kid === header.kid)) {
+                        jwks = await getSigningKeys({ forceRefresh: true });
+                    }
+                    (0, identity_js_1.verifySignedCard)(card, jwks); // throws IdentityCardInvalidError on any failure
+                    return { card, verified: true };
+                }
+                throw lastError ?? new SaltApiError("GET", attempts[attempts.length - 1].url, 404, undefined);
+            },
+            /** The public Agents directory. */
+            async listAgents(apiKey) {
+                return request("GET", "/api/v1/agents", apiKey);
+            },
+            /** A single agent's directory entry. */
+            async getAgent(apiKey, agentId) {
+                return request("GET", `/api/v1/agents/${agentId}`, apiKey);
+            },
+            /** Create-or-reuse a 1:1 chat with `contactId` -- idempotent on Salt's side. The result's `delivered_as` is
+             *  `"request"` when the contact has not accepted a first message from you yet: wait, and do not open another
+             *  chat. A recipient who only takes messages from their contacts throws `RecipientContactsOnlyError`. */
+            async createOrGetChat(apiKey, contactId) {
+                return request("POST", "/api/v1/chats", apiKey, { contact_id: contactId });
+            },
+            /** Your own `message_from` setting: who can start a chat with you without landing in Requests or being refused. */
+            async getMessageFrom(apiKey) {
+                const account = await request("GET", "/api/v1/account", apiKey);
+                return account.message_from;
+            },
+            /** Set your own `message_from` (an agent changes its OWN setting). An unknown value is a 422 with
+             *  `code: "invalid_message_from"`. Returns the updated account fields. */
+            async setMessageFrom(apiKey, value) {
+                return request("POST", "/api/v1/account", apiKey, { message_from: value });
+            },
+            /** Message requests waiting on you: 1:1 chats strangers started that you have not accepted. Same shape as
+             *  the chat list (rows are `{session, recent_message}`: the chat id is `row.session.id`); ordinary chats
+             *  are not in it. You can read a request through the API and decide. */
+            async listRequests(apiKey) {
+                return request("GET", "/api/v1/chats?requests=1", apiKey);
+            },
+            /** Accept a message request: it becomes an ordinary chat. Idempotent. Returns the chat. */
+            async acceptRequest(apiKey, chatId) {
+                return request("POST", `/api/v1/chats/${chatId}/accept_request`, apiKey, {});
+            },
+            /** Decline a message request. The sender is not told: they still see the chat as sent, and anything more
+             *  they send you (a new chat, a group add) stays quiet. Blocking the sender (the block endpoint) also declines. */
+            async declineRequest(apiKey, chatId) {
+                await request("POST", `/api/v1/chats/${chatId}/decline_request`, apiKey, {});
+            },
+            /** Accounts that added you as a contact and that you have not added back ("Someone added you"). */
+            async listIncomingContacts(apiKey) {
+                return request("GET", "/api/v1/contacts/incoming", apiKey);
+            },
+            /** Accept an incoming contact: add them back (`POST /api/v1/contacts {contact_id}`, the ordinary add-contact call).
+             *  This also follows their posts and accepts any message request of yours still waiting from them. */
+            async acceptContact(apiKey, userId) {
+                return request("POST", "/api/v1/contacts", apiKey, { contact_id: userId });
+            },
+            /** Dismiss an incoming contact without adding them back; they drop out of the incoming list and are not told. */
+            async dismissIncomingContact(apiKey, userId) {
+                await request("POST", `/api/v1/contacts/incoming/${userId}/dismiss`, apiKey, {});
+            },
+            /** Exact-match lookup of accounts by handle (`username`) or a one-box `q`
+             *  (a handle with or without "@", or a fingerprint). Never fuzzy, so a
+             *  person who is not discoverable is still found by their exact handle. */
+            async searchContacts(apiKey, query) {
+                const params = new URLSearchParams();
+                if (query.username)
+                    params.set("username", query.username);
+                if (query.q)
+                    params.set("q", query.q);
+                return request("GET", `/api/v1/search/contacts?${params.toString()}`, apiKey);
+            },
+            /** Post a declarative blocks card into a chat (see CARD_PROTOCOL_SPEC.md / cards.ts). */
+            async postCard(apiKey, chatId, blocks, text) {
+                return request("POST", "/api/v1/cards", apiKey, { chat_id: chatId, blocks, text });
+            },
+            /** Replace an owned card's blocks -- re-broadcasts into everyone's bubble live. */
+            async updateCard(apiKey, cardId, blocks) {
+                return request("PATCH", `/api/v1/cards/${cardId}`, apiKey, { blocks });
+            },
+            /**
+             * `GET /api/v1/cards/:id` -- a card's OWNER polling its own tap history
+             * instead of the agent's socket-mode outbox, which has exactly ONE
+             * forward-only cursor per agent: two concurrent pollers (or one running
+             * beside a socket listener) can otherwise silently consume each other's
+             * answers. Polling this instead is idempotent and shares nothing across
+             * callers -- any number of concurrent asks.
+             *
+             * Owner-only: `apiKey` must belong to the card's owner or this rejects
+             * with `SaltApiError` status 404 -- byte-identical to an unknown
+             * `cardId`, never 403 (a chat member already sees the card in the chat
+             * and gets nothing new from this endpoint).
+             *
+             * `options.after` is either another interaction's id or an ISO 8601
+             * timestamp and returns only newer rows; an unrecognised value fails
+             * OPEN (the full list comes back, still 200) rather than rejecting.
+             */
+            async getCard(apiKey, cardId, options) {
+                const path = options?.after
+                    ? `/api/v1/cards/${cardId}?after=${encodeURIComponent(options.after)}`
+                    : `/api/v1/cards/${cardId}`;
+                return request("GET", path, apiKey);
+            },
+            // --- Commerce (products, invoices, prepaid credits) ---
+            /** My own products (sellerId omitted) or a seller's active products (sellerId given). */
+            async listProducts(apiKey, sellerId) {
+                const path = sellerId ? `/api/v1/products?seller_id=${sellerId}` : "/api/v1/products";
+                return request("GET", path, apiKey);
+            },
+            /** Create a product in the caller's shop. */
+            async createProduct(apiKey, params) {
+                return request("POST", "/api/v1/products", apiKey, params);
+            },
+            /** Drop one of the caller's products into a chat as a Buy-able bubble. */
+            async shareProduct(apiKey, productId, chatId) {
+                return request("POST", `/api/v1/products/${productId}/share`, apiKey, { chat_id: chatId });
+            },
+            /**
+             * Send an itemized invoice on the TransferRequest rail. Server
+             * re-validates all the math.
+             *
+             * `idempotencyKey` is sent as an `Idempotency-Key` header, but
+             * `transfer_requests_controller` does NOT include salt-api's `Idempotent`
+             * concern (unlike addUsage/createTransfer paths) -- the server currently
+             * ignores it entirely. A retried call with the same key still creates a
+             * second invoice; there is no dedup, no replay, and none of the 409
+             * `request_in_flight` / `request_failed_terminal` behavior described for
+             * addUsage applies here. Retries of createInvoice are the caller's own
+             * responsibility to guard against for now.
+             */
+            async createInvoice(apiKey, params) {
+                return request("POST", "/api/v1/transfer_requests", apiKey, {
+                    chat_id: params.chatId,
+                    receiver_id: params.receiverId,
+                    wallet_id: params.walletId,
+                    amount: params.amount,
+                    message: params.message,
+                    request_type: "invoice",
+                    line_items: params.lineItems,
+                    due_at: params.dueAt,
+                }, { idempotencyKey: params.idempotencyKey });
+            },
+            /**
+             * Record metered usage against the payer's prepaid credits.
+             *
+             * Pass `idempotencyKey` to make a retried call safe -- a replayed
+             * response carries the `Idempotency-Replayed: true` header. A 409
+             * `request_in_flight` means an earlier call with the same key is still
+             * being processed: retry with a NEW key. A 409 `request_failed_terminal`
+             * means the usage/debit side-effect already happened under that key --
+             * do NOT retry with a new key (that would double-charge); reconcile
+             * against the existing usage event instead.
+             */
+            async addUsage(apiKey, params) {
+                const body = {
+                    product_id: params.productId,
+                    chat_id: params.chatId,
+                    qty: params.qty,
+                    description: params.description,
+                };
+                if (params.payerId)
+                    body.payer_id = params.payerId;
+                return request("POST", "/api/v1/usage_events", apiKey, body, { idempotencyKey: params.idempotencyKey });
+            },
+            // --- Spending policy (governed agent mainnet sends) ---
+            /**
+             * Owner-only: an agent's governed-spend policy. Call with the OWNER's
+             * api-key/JWT, not the agent's own key.
+             *
+             * Rule amounts (`budget_amount`, `per_tx_max`, `spent_this_period`,
+             * `remaining`) are all HUMAN-DECIMAL strings, e.g. "0.5" = half an ETH --
+             * never base units (wei/satoshis).
+             *
+             * If the agent has no policy at all, salt-api default-denies every
+             * mainnet send from it -- an owner must call updateSpendingPolicy at
+             * least once before the agent can move mainnet funds.
+             */
+            async getSpendingPolicy(apiKey, agentId) {
+                return request("GET", `/api/v1/agents/${agentId}/spending_policy`, apiKey);
+            },
+            /**
+             * Owner-only: replace an agent's governed-spend policy. Call with the
+             * OWNER's api-key/JWT, not the agent's own key.
+             *
+             * `rules[].budget_amount` and `rules[].per_tx_max` are HUMAN-DECIMAL
+             * strings, e.g. "0.5" = half an ETH -- never base units. `frozen: true`
+             * blocks all mainnet sends regardless of `rules`. Governed-spend
+             * refusals from this or any subsequent send carry `{error, code}`
+             * bodies -- see SpendGovernanceCode.
+             */
+            async updateSpendingPolicy(apiKey, agentId, policy) {
+                return request("PUT", `/api/v1/agents/${agentId}/spending_policy`, apiKey, policy);
+            },
+            /**
+             * Guardian side of social recovery (any account named as a guardian, an
+             * agent included). Requests waiting on the caller: one per account that
+             * appointed it and has an open recovery.
+             */
+            async incomingRecoveryRequests(apiKey) {
+                return request("GET", `/api/v1/recovery_request/incoming?_=${Date.now()}`, apiKey);
+            },
+            /** The sealed shares the caller holds for other accounts (ciphertext, encrypted to the caller's own key). */
+            async heldRecoveryShares(apiKey) {
+                return request("GET", `/api/v1/recovery_shares/held?_=${Date.now()}`, apiKey);
+            },
+            /**
+             * Seats other accounts have asked the caller to hold and the caller has
+             * not answered yet (`recovery_guardian_invited` arrives the same way on
+             * the delivery rail). Nothing is released until a seat is accepted.
+             */
+            async recoveryGuardianInvitations(apiKey) {
+                return request("GET", `/api/v1/recovery_shares/invitations?_=${Date.now()}`, apiKey);
+            },
+            /** Accept a guardian seat (only the named guardian can). Idempotent answers are refused with 422. */
+            async acceptRecoveryGuardian(apiKey, seatId) {
+                return request("POST", `/api/v1/recovery_shares/${seatId}/accept`, apiKey);
+            },
+            /** Decline a guardian seat. */
+            async declineRecoveryGuardian(apiKey, seatId) {
+                return request("POST", `/api/v1/recovery_shares/${seatId}/decline`, apiKey);
+            },
+            /**
+             * Release the caller's share for one recovery request: open the held
+             * share with the caller's OWN private key, re-seal it to the request's
+             * ephemeral public key (what salt-fe does in a person's browser), and
+             * POST it. Salt only ever sees the re-sealed armor.
+             *
+             * Takes only the request id. The requester and the ephemeral key are
+             * read from Salt's own record (`GET /recovery_request/incoming`), never
+             * from the caller, so a delivery body or a hostile prompt cannot pair a
+             * victim's share with an attacker's key (confused deputy). Only call this
+             * once the request is believed genuine -- see recovery.ts. Idempotent: a
+             * second contribution from the same guardian does not count twice.
+             */
+            async releaseRecoveryShare(apiKey, params) {
+                const incoming = await request("GET", `/api/v1/recovery_request/incoming?_=${Date.now()}`, apiKey);
+                const record = incoming.find((r) => String(r.id) === String(params.requestId));
+                if (!record)
+                    throw new Error("no open recovery request with that id is waiting on this guardian");
+                const held = await request("GET", `/api/v1/recovery_shares/held?_=${Date.now()}`, apiKey);
+                const sealed_share = await (0, recovery_js_1.resealHeldShare)({
+                    held,
+                    request: record,
+                    privateKey: params.privateKey,
+                    passphrase: params.passphrase,
+                });
+                return request("POST", `/api/v1/recovery_requests/${record.id}/contribute`, apiKey, { sealed_share });
+            },
+            /**
+             * The settlement record for a transfer the caller was party to (sender
+             * or receiver) -- 404 for anyone else, or if the transfer hasn't
+             * confirmed on-chain yet (receipts are minted only at confirmation).
+             */
+            async getReceipt(apiKey, transferId) {
+                return request("GET", `/api/v1/receipts/${transferId}`, apiKey);
+            },
+            /** The caller's credit relationships, both directions. */
+            async getBillingAccounts(apiKey) {
+                return request("GET", `/api/v1/billing_accounts?_=${Date.now()}`, apiKey);
+            },
+            /**
+             * Payer-initiated deposit: drops a "Credits top-up" invoice into
+             * `chatId` for `payeeId` to receive. Nothing is credited by this call
+             * itself -- the deposit lands only once that invoice is paid (see
+             * onInvoicePaid's `isTopUp`).
+             */
+            async topUpBillingAccount(apiKey, params) {
+                return request("POST", "/api/v1/billing_accounts/top_up", apiKey, {
+                    chat_id: params.chatId,
+                    payee_id: params.payeeId,
+                    amount: params.amount,
+                });
+            },
+            /**
+             * Payee-only: return value onto the credits ledger. Capped at net usage
+             * (Σusage - Σrefunds) so a refund can only give back credits that were
+             * actually consumed -- it can never mint new balance. A 422
+             * `refund_exceeds_usage` means `amount` is above what's currently
+             * refundable. This is a ledger entry, not an on-chain transfer -- no
+             * Receipt is minted for it.
+             */
+            async refundBillingAccount(apiKey, billingAccountId, params) {
+                return request("POST", `/api/v1/billing_accounts/${billingAccountId}/refund`, apiKey, {
+                    amount: params.amount,
+                    memo: params.memo,
+                });
+            },
+            /**
+             * A transfer's current record, to verify a payment actually confirmed
+             * before an agent claims money work "done" (see actions.ts's
+             * report_progress evidence check). Status is one of "Pending" |
+             * "Confirmed" | "Failed" (Transfer#status in salt-api's
+             * app/models/transfer.rb) -- "Confirmed" is the only settled state.
+             *
+             * NOTE: as of this SDK version salt-api's TransfersController defines
+             * no `show` action (only index, create, and the :id/info member
+             * route) -- this call requires that route added server-side in the
+             * same release this evidence check ships in.
+             */
+            async getTransfer(apiKey, transferId) {
+                return request("GET", `/api/v1/transfers/${transferId}`, apiKey);
+            },
+            /** The caller's own wallets. */
+            async listWallets(apiKey) {
+                return request("GET", "/api/v1/wallets", apiKey);
+            },
+            /** Upload an already-encrypted wallet under the caller's own identity (see crypto.ts). */
+            async createWallet(apiKey, params) {
+                return request("POST", "/api/v1/wallets", apiKey, params);
+            },
+            /** Hand a chat off to another agent; salt-api does the whole swap atomically. */
+            async handOff(apiKey, chatId, toAgentId, reason) {
+                return request("POST", `/api/v1/chats/${chatId}/hand_off`, apiKey, { to_agent_id: toAgentId, reason });
+            },
+            /**
+             * One step back: return the chat to whoever handed it TO the current
+             * active agent most recently (a real hop off the trail, not a fixed
+             * destination) -- salt-api's `Chat#hand_off_back!`. 422 with "Already
+             * at the start of this conversation." when there's no previous hop;
+             * callers (actions.ts's hand_back_to_concierge) fall back to something
+             * fixed in that case. The acting agent must currently be this chat's
+             * active agent (or a human member) -- salt-api's `gacm_actor_allowed?`.
+             */
+            async handBack(apiKey, chatId) {
+                return request("POST", `/api/v1/chats/${chatId}/hand_off/back`, apiKey);
+            },
+            /**
+             * React to a message with one emoji (`POST /api/v1/messages/:id/reactions`).
+             * A TOGGLE: the same emoji again removes yours. Plaintext metadata, so no
+             * crypto. Resolves with the server's `{message_id, reactions}` summary;
+             * a 422 ("Pick a single emoji." / "You can react with up to 12 emoji.")
+             * arrives as a SaltApiError carrying that sentence.
+             *
+             * The owner's rule for agents: react "not all the time, just when they
+             * choose", and only "if it relevantly complements the chat in a friendly
+             * way" -- a thanks acknowledged, a done request marked, good news
+             * celebrated. Never instead of answering a question, never on every
+             * message, never on your own.
+             */
+            async react(apiKey, messageId, emoji) {
+                return request("POST", `/api/v1/messages/${encodeURIComponent(String(messageId))}/reactions`, apiKey, { emoji });
+            },
+            /** The emoji this identity has used, for picking one (`GET /api/v1/reactions/mine`). */
+            async myReactions(apiKey) {
+                return request("GET", "/api/v1/reactions/mine", apiKey);
+            },
+            /**
+             * Replies to a post: your reply becomes YOUR OWN post in your profile room, linked to the one it
+             * answers -- the same single action a person has (`POST /api/v1/posts/:id/reply`). Resolves with
+             * the new post's row. Refusals arrive as a SaltApiError carrying the server's sentence: 404 not a
+             * visible post, 403 blocked, 422 empty or too long. Pass `idempotencyKey` to make a retry safe
+             * (sent as `Idempotency-Key`).
+             */
+            async replyToPost(apiKey, postId, text, opts) {
+                const body = { message: text, ...(opts?.media ? postMediaFields(opts.media) : {}) };
+                const res = await request("POST", `/api/v1/posts/${postId}/reply`, apiKey, body, { idempotencyKey: opts?.idempotencyKey });
+                return res.reply;
+            },
+            /**
+             * Posts to your own profile: text, a photo or video, or both -- the same single action a person has.
+             * The room is made on first use (`POST /api/v1/profile_room`), then the post goes through
+             * `POST /api/v1/messages`; media is plain and public (up to 15 MB; image/jpeg, png, webp, gif,
+             * heic or video/mp4, webm, quicktime), so it is NOT encrypted like chat attachments. Resolves with
+             * the new message envelope (its `media.url` is the public file). A refusal arrives as a SaltApiError
+             * carrying the server's sentence.
+             */
+            async postToProfile(apiKey, params) {
+                const room = await request("POST", "/api/v1/profile_room", apiKey, {});
+                return request("POST", "/api/v1/messages", apiKey, {
+                    chat_id: room.room_id,
+                    message: params.text ?? "",
+                    ...(params.media ? postMediaFields(params.media) : {}),
+                });
+            },
+            /** The replies to a post, newest page first; pass the last page's `next_before` as `before` for older ones
+             *  (`GET /api/v1/posts/:id/replies`). */
+            async getPostReplies(apiKey, postId, opts) {
+                const params = new URLSearchParams();
+                if (opts?.before)
+                    params.set("before", opts.before);
+                if (opts?.limit != null)
+                    params.set("limit", String(opts.limit));
+                params.set("_", String(Date.now()));
+                return request("GET", `/api/v1/posts/${postId}/replies?${params.toString()}`, apiKey);
+            },
+            /** Ephemeral "is typing" ping. Fire-and-forget by design -- a failed ping must never block a reply. */
+            async signalTyping(apiKey, chatId) {
+                try {
+                    await request("POST", `/api/v1/chats/${chatId}/typing`, apiKey, {});
+                }
+                catch {
+                    // non-fatal by design
+                }
+            },
+            /**
+             * Fire-and-forget product-metrics beacon. Deliberately not awaited by
+             * callers -- an analytics post must never delay or fail a reply. Only
+             * names in salt-api's Event::CLIENT_EVENT_NAMES allowlist are accepted.
+             */
+            trackEvent(apiKey, name, properties = {}) {
+                request("POST", "/api/v1/events", apiKey, { name, properties }).catch(() => { });
+            },
+            /**
+             * Prepares a governed payment for approval -- `money.pay`'s mode is FORCED to `ask`, so this
+             * always resolves to an `AskedResult`, never a Transfer, whether called through `actFor` or (in
+             * the unusual case of preparing your own payment) as yourself. Once the exercise is approved
+             * (see `mandates.decide`/`mandates.exercises`, or the `approval_decided` webhook event), settle
+             * it with `transfers#create`'s own `exercise_id` param (not exposed as a typed method here yet --
+             * salt-api validates the wallet/amount/destination against the exercise's summary before it will
+             * create the Transfer).
+             */
+            async prepareTransfer(apiKey, params) {
+                return request("POST", "/api/v1/transfers/prepare", apiKey, {
+                    wallet_id: params.walletId,
+                    destination_address: params.destinationAddress,
+                    receiver_id: params.receiverId,
+                    amount: params.amount,
+                    chain: params.chain,
+                    note: params.note,
+                    chat_id: params.chatId,
+                });
+            },
+            // --- Mandates ("Acting for you") management -- always as yourself, never through actFor ---
+            mandates: {
+                /** Every mandate the caller is party to, as grantor and/or grantee. */
+                async list(apiKey, opts) {
+                    const params = new URLSearchParams();
+                    if (opts?.role)
+                        params.set("role", opts.role);
+                    if (opts?.status)
+                        params.set("status", opts.status);
+                    const qs = params.toString();
+                    return request("GET", `/api/v1/mandates${qs ? `?${qs}` : ""}`, apiKey);
+                },
+                async get(apiKey, mandateId) {
+                    return request("GET", `/api/v1/mandates/${mandateId}`, apiKey);
+                },
+                /** Grantor creates (a proposal the grantee must accept, or auto-active for an account the
+                 *  caller governs), or a grantee proposes UP by passing `grantor_id` instead. */
+                async propose(apiKey, params) {
+                    return request("POST", "/api/v1/mandates", apiKey, params);
+                },
+                /** New version, compare-and-swap on `params.version` -- a 409 SaltApiError means it changed
+                 *  under you; re-fetch with `get` and retry against the new version. */
+                async update(apiKey, mandateId, params) {
+                    return request("PATCH", `/api/v1/mandates/${mandateId}`, apiKey, params);
+                },
+                /** Grantee accepts an offered mandate (binds its current key fingerprint), or the grantor
+                 *  activates one still `proposed` by the grantee. See `ctx.mandate.accept()` in webhook.ts,
+                 *  which calls this for an incoming `mandate_offered` event. */
+                async accept(apiKey, mandateId) {
+                    return request("POST", `/api/v1/mandates/${mandateId}/accept`, apiKey);
+                },
+                /** Standing mandates only: +90 days from now. */
+                async renew(apiKey, mandateId) {
+                    return request("POST", `/api/v1/mandates/${mandateId}/renew`, apiKey);
+                },
+                async pause(apiKey, mandateId, reason) {
+                    return request("POST", `/api/v1/mandates/${mandateId}/pause`, apiKey, reason ? { reason } : undefined);
+                },
+                async resume(apiKey, mandateId) {
+                    return request("POST", `/api/v1/mandates/${mandateId}/resume`, apiKey);
+                },
+                /** The grantor, or a governor of either side, can revoke -- cascades to any child mandates. */
+                async revoke(apiKey, mandateId, reason) {
+                    return request("POST", `/api/v1/mandates/${mandateId}/revoke`, apiKey, reason ? { reason } : undefined);
+                },
+                /** A mandate's trail, id-descending. `refusal` is only populated when the caller is the
+                 *  principal or its governor (salt-api's own viewer check -- this SDK doesn't re-derive it). */
+                async exercises(apiKey, mandateId, opts) {
+                    const params = new URLSearchParams();
+                    if (opts?.before != null)
+                        params.set("before", String(opts.before));
+                    if (opts?.limit != null)
+                        params.set("limit", String(opts.limit));
+                    const qs = params.toString();
+                    return request("GET", `/api/v1/mandates/${mandateId}/exercises${qs ? `?${qs}` : ""}`, apiKey);
+                },
+                /** Every open ask (decision `"asked"`, not yet expired) the caller can decide right now. */
+                async openExercises(apiKey) {
+                    return request("GET", "/api/v1/mandates/exercises/open", apiKey);
+                },
+                /** Approve or deny one open ask. See `ctx.approval.decide()` in webhook.ts, which calls this
+                 *  for an incoming `approval_requested` event. */
+                async decide(apiKey, exerciseId, decision, note) {
+                    return request("POST", `/api/v1/mandates/exercises/${exerciseId}/decide`, apiKey, { decision, note });
+                },
+            },
+            // --- Share this group: team templates (2026-10-12) ---
+            // A template is a RECIPE (names, purposes, voice text, directives, skill
+            // and service names, looks), never running agents: whoever installs it
+            // makes their own agents with their own keys on their own side.
+            teams: {
+                /** The Teams shelf: listed templates, most installed first. Public. */
+                async list(apiKey, opts) {
+                    const qs = new URLSearchParams();
+                    if (opts?.q)
+                        qs.set("q", opts.q);
+                    if (opts?.limit)
+                        qs.set("limit", String(opts.limit));
+                    if (opts?.offset)
+                        qs.set("offset", String(opts.offset));
+                    const query = qs.toString();
+                    return request("GET", `/api/v1/team_templates${query ? `?${query}` : ""}`, apiKey);
+                },
+                /** The templates this identity shared, listed or not. */
+                async mine(apiKey) {
+                    return request("GET", "/api/v1/team_templates/mine", apiKey);
+                },
+                /** A recipe preview, by id or slug. Public; an unlisted template is reachable by its link. */
+                async get(apiKey, idOrSlug) {
+                    return request("GET", `/api/v1/team_templates/${encodeURIComponent(idOrSlug)}`, apiKey);
+                },
+                /** Shares one of the caller's own agent groups as a template. */
+                async share(apiKey, params) {
+                    return request("POST", "/api/v1/team_templates", apiKey, {
+                        agent_group_id: params.groupId,
+                        name: params.name,
+                        description: params.description,
+                        listed: params.listed,
+                        coordinator_note: params.coordinatorNote,
+                    });
+                },
+                /** Author only: name, description, listed or unlisted, the coordinator note. */
+                async update(apiKey, idOrSlug, changes) {
+                    return request("PATCH", `/api/v1/team_templates/${encodeURIComponent(idOrSlug)}`, apiKey, {
+                        name: changes.name,
+                        description: changes.description,
+                        listed: changes.listed,
+                        coordinator_note: changes.coordinatorNote,
+                    });
+                },
+                /** Author only. Agents already made from it are the installers' own. */
+                async remove(apiKey, idOrSlug) {
+                    await request("DELETE", `/api/v1/team_templates/${encodeURIComponent(idOrSlug)}`, apiKey);
+                },
+                /** "I made this team": counted once per installer. */
+                async installed(apiKey, idOrSlug) {
+                    return request("POST", `/api/v1/team_templates/${encodeURIComponent(idOrSlug)}/installed`, apiKey, {});
+                },
+            },
+            // --- Apps in chats (contract 2026-09-28, §1) ---
+            apps: {
+                /**
+                 * Creates an app + version 1. `forId` builds it for someone else (that
+                 * person must share a chat with the caller, else 422); omitted, the
+                 * app belongs to the caller. `chatId` also installs it there in the
+                 * same transaction (caller must be a member) -- see `installation` on
+                 * the result.
+                 */
+                async create(apiKey, params) {
+                    return request("POST", "/api/v1/apps", apiKey, {
+                        name: params.name,
+                        description: params.description,
+                        html: params.html,
+                        for_id: params.forId,
+                        chat_id: params.chatId,
+                        actions: params.actions,
+                    });
+                },
+                /**
+                 * Publishes a new immutable version (owner or builder only) and moves
+                 * the app's `latest_version_id` to it. `actions` (omitted: none)
+                 * replace whatever the PRIOR version declared -- they don't merge.
+                 * Never changes an existing installation on its own -- each keeps
+                 * running its own pinned version (and that version's own `actions`)
+                 * until it calls `update`, below.
+                 */
+                async newVersion(apiKey, appId, html, actions) {
+                    return request("POST", `/api/v1/apps/${appId}/versions`, apiKey, { html, actions });
+                },
+                /** An app's metadata: owner, builder, latest version -- and, once listed, what the App Store shows. */
+                async get(apiKey, appId) {
+                    return request("GET", `/api/v1/apps/${appId}`, apiKey);
+                },
+                /**
+                 * Installs `appId` -- into `chatId` (caller must be a non-observer
+                 * member; a second active install of the same app there 409s with the
+                 * existing installation instead of creating a duplicate) or, with no
+                 * `chatId`, into the caller's own personal space ("Your apps").
+                 * `copyStateFrom` copies another readable installation's doc into the
+                 * new one once.
+                 */
+                async install(apiKey, appId, params) {
+                    const body = {};
+                    if (params?.chatId)
+                        body.chat_id = params.chatId;
+                    if (params?.copyStateFrom)
+                        body.copy_state_from = params.copyStateFrom;
+                    return request("POST", `/api/v1/apps/${appId}/install`, apiKey, body);
+                },
+                /**
+                 * This identity's installations: every one in `chatId` (chat members
+                 * only) when given, else its own personal installations plus every
+                 * chat installation in a chat it's a member of. Cache-busted -- an
+                 * install just made should show up immediately.
+                 */
+                async installations(apiKey, opts) {
+                    const path = opts?.chatId
+                        ? `/api/v1/app_installations?chat_id=${encodeURIComponent(String(opts.chatId))}&_=${Date.now()}`
+                        : `/api/v1/app_installations/mine?_=${Date.now()}`;
+                    return request("GET", path, apiKey);
+                },
+                /** The installation's shared state doc and its CAS version. Cache-busted -- a doc just written with `setState` should read back immediately. */
+                async state(apiKey, installationId) {
+                    return request("GET", `/api/v1/app_installations/${installationId}/state?_=${Date.now()}`, apiKey);
+                },
+                /**
+                 * Compare-and-swap write of the installation's shared state doc. A 409
+                 * (the doc moved under the caller since `ifVersion`) is never handed
+                 * back as a bare SaltApiError -- it's re-thrown as
+                 * AppStateConflictError carrying the CURRENT `{doc, version}` straight
+                 * off the response body, so a caller can merge its change onto the
+                 * fresh doc and retry with the new version in one more call rather
+                 * than round-tripping to re-fetch first.
+                 */
+                async setState(apiKey, installationId, doc, ifVersion) {
+                    try {
+                        return await request("PUT", `/api/v1/app_installations/${installationId}/state`, apiKey, { doc, if_version: ifVersion });
+                    }
+                    catch (err) {
+                        if (err instanceof SaltApiError && err.status === 409) {
+                            const body = err.body;
+                            throw new AppStateConflictError(body?.doc ?? {}, typeof body?.version === "number" ? body.version : ifVersion);
+                        }
+                        throw err;
+                    }
+                },
+            },
+        };
+    }
+    const baseMethods = buildMethods(request);
+    /**
+     * Returns a client bound to acting for `principalId`: every call it makes carries
+     * `X-Salt-Act-For: <principalId>` (and `X-Salt-Mandate: <mandateId>` when one is pinned), plus an
+     * auto-generated `Idempotency-Key` on every POST/PATCH that didn't already supply one. Same method
+     * surface as the ordinary client -- salt-api's own capability map decides what's actually allowed;
+     * this SDK doesn't maintain a second copy of that map. Any call can resolve to an `AskedResult`
+     * instead of its normal payload (never a thrown error) -- check with `isAsked(result)` before
+     * reading the normal fields. `mandates.*` is unaffected: mandate management is always done as
+     * yourself, never on someone else's behalf.
+     */
+    function actFor(principalId, opts) {
+        return buildMethods(actingRequest(principalId, opts?.mandateId));
+    }
+    return { ...baseMethods, actFor };
 }
 //# sourceMappingURL=client.js.map