salt-agent-sdk 0.1.0 → 0.19.0

package/dist/actions.js

@@ -47,10 +47,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createActions = createActions;
 exports.toAnthropicTools = toAnthropicTools;
 exports.toOpenAITools = toOpenAITools;
+const node_crypto_1 = require("node:crypto");
 const ethers_1 = require("ethers");
+const client_1 = require("./client");
 const pgp = __importStar(require("./crypto"));
 const crypto_1 = require("./crypto");
 const delegations = __importStar(require("./delegations"));
+const work_1 = require("./work");
+const identityShare_js_1 = require("./identityShare.js");
+const ids_js_1 = require("./ids.js");
+const identity_js_1 = require("./identity.js");
 // Shared block-vocabulary schema, so both card tools teach the model the
 // same shape the server enforces (Card model validation in salt-api).
 const BLOCKS_SCHEMA = {
@@ -59,11 +65,14 @@ const BLOCKS_SCHEMA = {
         '{type:"section", text?:"markdown <=2000", fields?:[{label:"<=40",value:"<=160"}] (<=10)} | ' +
         '{type:"divider"} | ' +
         '{type:"image", url:"http(s) <=500", alt?} | ' +
+        '{type:"input", block_id:"a-z0-9_- <=40, unique across the whole card", label:"1-40", ' +
+        'placeholder?:"<=40", multiline?:bool, max_length?:"1-1000, default 500"} | ' +
         '{type:"actions", elements:[1-5 of {type:"button", action_id:"a-z0-9_- <=40, unique", label:"<=40", ' +
         'style?:"primary"|"danger", action_type?:"default"|"pay", pay?:{amount:"base units string", currency}, ' +
         'restricted_to?:[user_id,...] (<=20, must be real members of this chat)}]}. ' +
         "Buttons with action_type 'pay' become real Salt payment requests handled by the app itself; " +
-        "all other buttons come back as card_interaction events. Every chat member can tap a button by " +
+        "all other buttons come back as card_interaction events carrying every input block's current " +
+        "value (keyed by block_id) alongside the tapped action_id. Every chat member can tap a button by " +
         "default -- set restricted_to on any button that shouldn't be that open (delete, restart, admin " +
         "actions, a purchase meant for one specific person). Everyone still sees the button; anyone not " +
         "on the list sees it locked and can't invoke it, server-enforced.",
@@ -76,8 +85,24 @@ const BLOCKS_SCHEMA = {
  * model API, and dispatch tool calls through `execute()`.
  */
 function createActions(options) {
-    const { client, identities, pgpPassphrase, publicWebhookUrl, walletMasterKey, globalAgentId } = options;
+    const { client, identities, pgpPassphrase, publicWebhookUrl, walletMasterKey, conciergeAgentId } = options;
     const replyTransform = options.replyTransform ?? ((text) => text);
+    // Progress reports to the person a turn is for (work.ts). Only a turn that
+    // answers a person in a chat has anyone to report to; everything else is a
+    // quiet no-op, so a delegation made by a background job or a delegated hop
+    // behaves exactly as it did before reports existed.
+    const workReporter = (0, work_1.createWorkReporter)(client);
+    // R3/R4 (identityShare.ts): identity_share/identity_ask/identity_revoke below.
+    const identitySharer = (0, identityShare_js_1.createIdentitySharer)(client, pgpPassphrase);
+    const reportTarget = (ctx) => ctx.mainChatId != null && ctx.requesterId != null && ctx.depth === 0
+        ? { chatId: ctx.mainChatId, requesterId: ctx.requesterId }
+        : null;
+    async function reportWork(caller, ctx, report) {
+        const target = reportTarget(ctx);
+        if (!target)
+            return false;
+        return workReporter.report(caller, target, report);
+    }
     // Generates an EVM keypair, encrypts it under walletMasterKey (no human
     // recovery phrase), and uploads it under `identity`'s own api-key. Shared
     // by the create_wallet action and create_salt_agent's auto-provision hook.
@@ -105,11 +130,38 @@ function createActions(options) {
             throw new Error("You have no wallet to receive payments.");
         return active[0].id;
     }
+    // Open rooms: every action below that posts a wire-protocol message
+    // (delegate_to_agent, consult_agent, request_floor -- never a card or
+    // other resource, which is already plain JSON with no client-side
+    // encryption at all, on ANY chat) goes through this one branch point.
+    // `chatEncrypted` false posts `plaintext` as-is via the same
+    // postPlainMessage path client.ts's own open-room support uses;
+    // `chatEncrypted` true (the default -- an older server or an ordinary
+    // chat) is BYTE-IDENTICAL to what this SDK always did: PGP-encrypted for
+    // `recipientKeys` plus the caller's own key. Never send ciphertext to an
+    // open room or plaintext to an encrypted one -- salt-api refuses both
+    // directions, and mixing them up here would just turn that refusal into
+    // a confusing action-execution error instead of a deliberate choice.
+    // `recipientKeys` is only read (and need not be non-empty) when
+    // `chatEncrypted` is true.
+    async function postWireMessage(caller, chatId, chatEncrypted, plaintext, recipientKeys) {
+        if (!chatEncrypted)
+            return client.postPlainMessage(caller.apiKey, chatId, plaintext);
+        const recipientMessage = await pgp.encryptFor(plaintext, recipientKeys);
+        const senderMessage = await pgp.encryptFor(plaintext, [caller.publicKey]);
+        return client.postMessage(caller.apiKey, chatId, recipientMessage, senderMessage);
+    }
     // --- create_salt_agent ---------------------------------------------
     async function createSaltAgent(creator, input) {
         const keys = await pgp.generateKeypair(pgpPassphrase);
         // No email or password: salt-api synthesizes a placeholder email and
         // leaves the account non-loginable -- agents are pure API entities.
+        //
+        // Key custody (salt-api docs/KEY_CUSTODY.md Phase 5): keys.privateKey is
+        // deliberately never sent. Salt now rejects a plaintext private_key on
+        // create outright, and there is no vault to wrap one under here -- this
+        // process, not Salt, is the key's only custodian. It is registered below
+        // via identities.register, which is where it actually lives.
         const created = await client.createAgent(creator.apiKey, {
             display_name: input.display_name,
             username: input.username,
@@ -117,18 +169,18 @@ function createActions(options) {
             webhook: publicWebhookUrl,
             category: input.category,
             public_key: keys.publicKey,
-            private_key: keys.privateKey,
             public_fingerprint: keys.fingerprint,
         });
-        // The create response doesn't include an API key -- fetch it via the
-        // owner-only admin endpoint, callable immediately since `creator` is
-        // the new agent's owner.
-        const admin = await client.getAgentAdmin(creator.apiKey, created.id);
+        // The raw api key rides on the create response exactly once -- the server
+        // stores a digest, so the admin endpoint can no longer show it. The
+        // rotate fallback covers an older server that predates that change.
+        const childApiKey = created.api_key ??
+            (await client.rotateAgentApiKey(creator.apiKey, created.id)).api_key;
         const childIdentity = {
             saltAppId: created.id,
             username: created.username,
             displayName: created.display_name,
-            apiKey: admin.apikey.api_key,
+            apiKey: childApiKey,
             publicKey: keys.publicKey,
             privateKey: keys.privateKey,
             systemPrompt: input.persona,
@@ -157,7 +209,7 @@ function createActions(options) {
     // --- list_salt_agents ------------------------------------------------
     async function listSaltAgents(caller, input = {}) {
         const agents = (await client.listAgents(caller.apiKey));
-        let filtered = agents.filter((a) => a.id !== caller.saltAppId);
+        let filtered = agents.filter((a) => !(0, ids_js_1.sameId)(a.id, caller.saltAppId));
         if (input.category) {
             const needle = input.category.toLowerCase();
             filtered = filtered.filter((a) => String(a.category || "").toLowerCase().includes(needle));
@@ -183,11 +235,15 @@ function createActions(options) {
     }
     // --- delegate_to_agent ------------------------------------------------
     async function delegateToAgent(caller, input, ctx) {
-        const targetId = Number(input.target_agent_id);
+        // Ids arrive here from a model's tool call, so they are taken as written
+        // and never parsed. `Number(...)` made every real id NaN, which is falsy,
+        // so the required-argument check below rejected every valid delegation --
+        // and the self-delegation guard, comparing NaN, could never fire.
+        const targetId = String(input.target_agent_id || "").trim();
         const task = (input.task || "").trim();
         if (!targetId || !task)
             throw new Error("target_agent_id and task are both required.");
-        if (targetId === caller.saltAppId)
+        if ((0, ids_js_1.sameId)(targetId, caller.saltAppId))
             throw new Error("You can't delegate to yourself.");
         if (ctx.depth >= delegations.MAX_DELEGATION_DEPTH) {
             throw new Error("Delegation depth limit reached -- handle this yourself (or answer with what you already know) instead of delegating further.");
@@ -203,33 +259,58 @@ function createActions(options) {
             throw new Error(`${targetId} isn't an agent -- delegate_to_agent only targets other agents.`);
         }
         const chat = (await client.createOrGetChat(caller.apiKey, targetId));
-        const targetMember = (chat.users || []).find((u) => parseInt(u.id, 10) === targetId);
-        if (!targetMember || !targetMember.public_key) {
-            throw new Error(`Agent ${targetId} has no usable public key; can't message it securely.`);
+        // Open room (rare for a delegation chat today, but general): no keys
+        // needed at all, so the "usable public key" guard below doesn't apply.
+        const chatEncrypted = chat.encrypted !== false;
+        if (chatEncrypted) {
+            const targetMember = (chat.users || []).find((u) => (0, ids_js_1.sameId)(u.id, targetId));
+            if (!targetMember || !targetMember.public_key) {
+                throw new Error(`Agent ${targetId} has no usable public key; can't message it securely.`);
+            }
         }
         // Encrypt for every non-self member with a key, not just the target --
         // delegation chats carry a silent human observer (the caller's root
         // owner, added server-side) whose key must be a recipient for the
         // conversation to be auditable. Falls out naturally from the member list.
-        const recipientKeys = (chat.users || [])
-            .filter((u) => parseInt(u.id, 10) !== caller.saltAppId && u.public_key)
-            .map((u) => u.public_key);
+        const recipientKeys = chatEncrypted
+            ? (chat.users || []).filter((u) => !(0, ids_js_1.sameId)(u.id, caller.saltAppId) && u.public_key).map((u) => u.public_key)
+            : [];
         const marked = delegations.wrap(ctx.depth + 1, task);
-        const recipientMessage = await pgp.encryptFor(marked, recipientKeys);
-        const senderMessage = await pgp.encryptFor(marked, [caller.publicKey]);
+        // The person this turn is for sees the delegation as it happens, in their
+        // Tasks panel: who was asked, what, and how it ended. Awaited so the
+        // reports land in order; a report that fails never fails the delegation.
+        // Each step carries its own detail (0.6.1): the ask on the way out, the
+        // reply's first line on the way back, the reason on a failure. One detail
+        // reused for every step made a finished delegation repeat the question.
+        const firstLine = (s) => (s || "").split("\n").find((l) => l.trim()) || "";
+        const work = {
+            id: (0, work_1.newWorkId)(),
+            kind: "delegation",
+            with: target.username,
+        };
+        const handle = target.username ? `@${target.username}` : target.display_name || "another agent";
         // register() throws synchronously (before any network call) if this
         // chat already has a pending wait -- surfaces as a normal action error
         // rather than an ambiguous race over which reply belongs to which caller.
         const waitForReply = delegations.register(chat.id, targetId, delegations.DELEGATION_TIMEOUT_MS);
         try {
-            await client.postMessage(caller.apiKey, chat.id, recipientMessage, senderMessage);
+            await postWireMessage(caller, chat.id, chatEncrypted, marked, recipientKeys);
         }
         catch (err) {
             delegations.cancel(chat.id);
             throw err;
         }
-        const rawReplyText = await waitForReply; // rejects with a timeout Error if nothing arrives in time
+        await reportWork(caller, ctx, { ...work, status: "running", title: `Asking ${handle}`, detail: firstLine(task) });
+        let rawReplyText;
+        try {
+            rawReplyText = await waitForReply; // rejects with a timeout Error if nothing arrives in time
+        }
+        catch (err) {
+            await reportWork(caller, ctx, { ...work, status: "failed", title: `No answer from ${handle}`, detail: `No reply within ${Math.round(delegations.DELEGATION_TIMEOUT_MS / 1000)} s.` });
+            throw err;
+        }
         const replyText = replyTransform(rawReplyText);
+        await reportWork(caller, ctx, { ...work, status: "done", title: `${handle} answered`, detail: firstLine(replyText) });
         if (ctx.mainChatId != null) {
             delegations.recordTrail(caller.saltAppId, ctx.mainChatId, {
                 agent_id: target.id,
@@ -245,8 +326,155 @@ function createActions(options) {
             delegated: true,
             target: { id: target.id, username: target.username, display_name: target.display_name },
             reply: replyText,
+            // Seen live (2026-09-15): after consulting Faucet, the Concierge told the
+            // person "They're in this chat now -- you can message them directly."
+            // They were not. Say so in the result the model reads.
+            note: `${target.display_name || target.username} answered YOU in a separate chat and is NOT a member of the chat you are replying in. The person cannot message them here. Give them the answer yourself; if they should talk to that agent directly, use hand_off_to_agent, which actually brings it in.`,
+        };
+    }
+    // --- consult_agent -------------------------------------------------------
+    //
+    // Unlike delegate_to_agent (a separate 1:1, the target never in this
+    // chat), consult_agent stays inline: it opens a lane off the CURRENT chat
+    // with a fellow member who's already here, and later messages from that
+    // agent ride the ordinary onMessage path in that lane (ctx.roomId points
+    // back here) rather than needing another tool call. Reply-matching reuses
+    // the exact same delegations registry delegate_to_agent does.
+    async function consultAgent(caller, input, ctx) {
+        if (ctx.mainChatId == null)
+            throw new Error("consult_agent is only available while replying in a chat.");
+        const handle = (input.handle || "").replace(/^@/, "").trim();
+        const briefing = (input.briefing || "").trim();
+        const question = (input.question || "").trim();
+        if (!handle || !question)
+            throw new Error("handle and question are both required.");
+        const members = (await client.getChatMembers(caller.apiKey, ctx.mainChatId));
+        const target = members.find((m) => m.username === handle);
+        if (!target) {
+            throw new Error(`No chat member named @${handle} -- consult_agent only reaches someone already in this chat (use delegate_to_agent for anyone else).`);
+        }
+        if ((0, ids_js_1.sameId)(target.id, caller.saltAppId))
+            throw new Error("You can't consult yourself.");
+        if (target.account_type !== "Agent")
+            throw new Error(`@${handle} isn't an agent -- consult_agent only targets other agents.`);
+        // No public-key check here: whether one is actually NEEDED depends on
+        // whether the LANE (opened below) turns out to be encrypted, which
+        // this parent chat's member list can't answer -- the lane's own
+        // member list is the authoritative, encryption-aware check just below.
+        const lane = (await client.openConsultLane(caller.apiKey, ctx.mainChatId, target.id));
+        // Open room (general capability -- a consult lane is normally its own
+        // private aside regardless of the parent chat, but the branch costs
+        // nothing to support): no keys needed at all when the lane itself isn't
+        // encrypted.
+        const laneEncrypted = lane.session.encrypted !== false;
+        const recipientKeys = laneEncrypted
+            ? (lane.session.users || []).filter((u) => !(0, ids_js_1.sameId)(u.id, caller.saltAppId) && u.public_key).map((u) => u.public_key)
+            : [];
+        if (laneEncrypted && recipientKeys.length === 0)
+            throw new Error(`@${handle} has no usable public key in the lane; can't message them securely.`);
+        const body = briefing ? `${briefing}\n\n${question}` : question;
+        const marked = delegations.wrapConsult(ctx.mainChatId, body);
+        // So webhook.ts's own floor-request handler knows, later, that WE are
+        // the one who should hand off if @handle asks for the floor in this lane.
+        delegations.registerConsultAsker(lane.session.id, caller.saltAppId, ctx.mainChatId);
+        const firstLine = (s) => (s || "").split("\n").find((l) => l.trim()) || "";
+        const work = { id: (0, work_1.newWorkId)(), kind: "delegation", with: target.username };
+        const atHandle = `@${target.username}`;
+        const waitForReply = delegations.register(lane.session.id, target.id, delegations.DELEGATION_TIMEOUT_MS);
+        try {
+            await postWireMessage(caller, lane.session.id, laneEncrypted, marked, recipientKeys);
+        }
+        catch (err) {
+            delegations.cancel(lane.session.id);
+            throw err;
+        }
+        await reportWork(caller, ctx, { ...work, status: "running", title: `Asking ${atHandle}`, detail: firstLine(question) });
+        let rawReplyText;
+        try {
+            rawReplyText = await waitForReply; // rejects with a timeout Error if nothing arrives in time
+        }
+        catch (err) {
+            await reportWork(caller, ctx, {
+                ...work,
+                status: "failed",
+                title: `No answer from ${atHandle}`,
+                detail: `No reply within ${Math.round(delegations.DELEGATION_TIMEOUT_MS / 1000)} s.`,
+            });
+            throw err;
+        }
+        const replyText = replyTransform(rawReplyText);
+        await reportWork(caller, ctx, { ...work, status: "done", title: `${atHandle} answered`, detail: firstLine(replyText) });
+        client.trackEvent(caller.apiKey, "consult_made", { to_agent_username: target.username });
+        return {
+            consulted: true,
+            target: { id: target.id, username: target.username, display_name: target.display_name },
+            lane_chat_id: lane.session.id,
+            reply: replyText,
+            note: `${target.display_name || target.username} is answering you in a separate private lane off this chat -- ` +
+                "the person here cannot see it. Later messages from them arrive as ordinary turns in that lane (you " +
+                "don't need to call consult_agent again to keep talking); if they ask for the floor, you'll be handed off automatically.",
         };
     }
+    // --- request_floor ---------------------------------------------------------
+    async function requestFloor(caller, input, ctx) {
+        if (ctx.mainChatId == null)
+            throw new Error("request_floor is only available while replying in a chat.");
+        if (ctx.laneKind !== "consult") {
+            throw new Error("request_floor is only available inside a consult lane (the chat a consult_agent call opened with you) -- not in an ordinary chat.");
+        }
+        const reason = (input.reason || "").trim();
+        const marker = reason ? `${delegations.FLOOR_REQUEST_MARKER}\n${reason}` : delegations.FLOOR_REQUEST_MARKER;
+        // Unlike delegate_to_agent/consult_agent, request_floor had no other
+        // reason to fetch the chat itself (only its members) -- getChat is the
+        // one call that answers both "who's here" and "is this lane encrypted".
+        const chat = await client.getChat(caller.apiKey, ctx.mainChatId);
+        const recipientKeys = chat.encrypted
+            ? chat.users.filter((u) => !(0, ids_js_1.sameId)(u.id, caller.saltAppId) && u.public_key).map((u) => u.public_key)
+            : [];
+        if (chat.encrypted && recipientKeys.length === 0)
+            throw new Error("No one in this lane to ask for the floor.");
+        await postWireMessage(caller, ctx.mainChatId, chat.encrypted, marker, recipientKeys);
+        return {
+            requested: true,
+            note: "Sent. If they hand off, you'll be brought into the room directly and prompted separately to introduce yourself.",
+        };
+    }
+    // --- report_progress --------------------------------------------------
+    async function reportProgress(caller, input, ctx) {
+        if (!reportTarget(ctx)) {
+            throw new Error("report_progress is only available while answering a person in a chat.");
+        }
+        if (!work_1.WORK_STATUSES.includes(input.status)) {
+            throw new Error(`status must be one of ${work_1.WORK_STATUSES.join(", ")}.`);
+        }
+        const title = (input.title || "").trim();
+        if (!title)
+            throw new Error("title is required -- one short line saying what is happening.");
+        // Money evidence: claiming money work "done" is only trusted with a
+        // real, CONFIRMED transfer behind it -- otherwise a report is just the
+        // model's own say-so. Only checked when evidence is actually supplied
+        // (most 'done' reports aren't about money at all); the tool description
+        // is what tells the model money work needs this.
+        const transferId = input.evidence?.transfer_id ? String(input.evidence.transfer_id).trim() : undefined;
+        if (input.status === "done" && transferId) {
+            let transfer;
+            try {
+                transfer = await client.getTransfer(caller.apiKey, transferId);
+            }
+            catch (err) {
+                throw new Error(`Could not verify transfer ${transferId}: ${err.message}`);
+            }
+            if (transfer.status !== "Confirmed") {
+                throw new Error(`Transfer ${transferId} has not confirmed on-chain yet (status: ${transfer.status || "unknown"}) -- ` +
+                    "report 'done' only once it has; use 'running' (or 'failed', if it failed) until then.");
+            }
+        }
+        const id = input.id && /^[A-Za-z0-9_-]{1,64}$/.test(input.id) ? input.id : (0, work_1.newWorkId)();
+        const reported = await reportWork(caller, ctx, { id, status: input.status, kind: "task", title, detail: input.detail });
+        return reported
+            ? { reported: true, id, note: "Only they can see this, in their Tasks panel for this chat." }
+            : { reported: false, id, note: "The report could not be delivered; carry on with the work." };
+    }
     // --- post_card / update_card ------------------------------------------
     async function postCard(caller, input, ctx) {
         if (ctx.mainChatId == null)
@@ -255,7 +483,7 @@ function createActions(options) {
         return { posted: true, card_id: result.resource_id, message_id: result.message_id };
     }
     async function updateCard(caller, input) {
-        const cardId = Number(input.card_id);
+        const cardId = String(input.card_id || "").trim();
         if (!cardId)
             throw new Error("card_id is required.");
         await client.updateCard(caller.apiKey, cardId, input.blocks);
@@ -274,7 +502,7 @@ function createActions(options) {
     async function offerProduct(caller, input, ctx) {
         if (ctx.mainChatId == null)
             throw new Error("offer_product is only available while replying in a chat.");
-        const productId = Number(input.product_id);
+        const productId = String(input.product_id || "").trim();
         if (!productId)
             throw new Error("product_id is required.");
         await client.shareProduct(caller.apiKey, productId, ctx.mainChatId);
@@ -294,7 +522,7 @@ function createActions(options) {
                 throw new Error(`No chat member named @${input.receiver_username}.`);
         }
         else {
-            const others = members.filter((m) => m.id !== caller.saltAppId && !m.observer);
+            const others = members.filter((m) => !(0, ids_js_1.sameId)(m.id, caller.saltAppId) && !m.observer);
             if (others.length !== 1)
                 throw new Error("Say who to bill (receiver_username) in a group chat.");
             receiver = others[0];
@@ -319,14 +547,23 @@ function createActions(options) {
     async function addUsage(caller, input, ctx) {
         if (ctx.mainChatId == null)
             throw new Error("add_usage is only available while replying in a chat.");
-        const productId = Number(input.product_id);
+        const productId = String(input.product_id || "").trim();
         if (!productId)
             throw new Error("product_id is required.");
+        // Generated once per call to this function -- i.e. once per model tool
+        // call -- NOT re-generated if the underlying HTTP request is retried.
+        // That's the point: usage_events_controller includes salt-api's
+        // Idempotent concern, so replaying the SAME key on a retried request is
+        // what makes a network-level retry safe against double-billing prepaid
+        // credits. Minting a fresh key per attempt would defeat that -- it would
+        // look like a brand-new usage event each time.
+        const idempotencyKey = (0, node_crypto_1.randomUUID)();
         const result = (await client.addUsage(caller.apiKey, {
             productId,
             chatId: ctx.mainChatId,
             qty: parseFloat(input.qty || "1"),
             description: input.description,
+            idempotencyKey,
         }));
         return { recorded: true, balance_remaining: result.balance };
     }
@@ -334,33 +571,76 @@ function createActions(options) {
     async function handOffToAgent(caller, input, ctx) {
         if (ctx.mainChatId == null)
             throw new Error("hand_off_to_agent is only available while replying in a chat.");
-        const agentId = Number(input.agent_id);
+        const agentId = String(input.agent_id || "").trim();
         if (!agentId)
             throw new Error("agent_id is required.");
-        if (agentId === caller.saltAppId)
+        if ((0, ids_js_1.sameId)(agentId, caller.saltAppId))
             throw new Error("You can't hand off to yourself.");
         const target = await client.getAgent(caller.apiKey, agentId);
         if (!target || target.account_type !== "Agent")
             throw new Error(`${agentId} isn't an agent.`);
-        await client.handOff(caller.apiKey, ctx.mainChatId, agentId, input.reason);
+        const handle = target.username ? `@${target.username}` : target.display_name || "another agent";
+        try {
+            await client.handOff(caller.apiKey, ctx.mainChatId, agentId, input.reason);
+        }
+        catch (err) {
+            // A refused hand-off (Salt says no, for whatever reason it has) is not
+            // a bug in this tool call -- it's an answer. Hand it back as a normal
+            // RESULT, not a throw, so the model gets one consistent instruction
+            // instead of three different guesses at what a raw error meant.
+            if (!(err instanceof client_1.SaltApiError) || (err.status !== 403 && err.status !== 422))
+                throw err;
+            const reason = err.body && typeof err.body === "object" && typeof err.body.error === "string"
+                ? err.body.error
+                : err.message;
+            return {
+                ok: false,
+                refused: true,
+                reason,
+                next_step: `Tell the person they can open ${handle} from Salt's agent directory and message them directly.`,
+            };
+        }
         return {
             handed_off: true,
+            handedOff: true,
             to: { id: target.id, username: target.username, display_name: target.display_name },
-            note: "They're live in this chat now; you'll be prompted SEPARATELY to write them a briefing -- do NOT include any briefing or summary in your current reply. Your current reply is just the goodbye: one short sentence telling the person who's taking over.",
+            note: "They're live in this chat now; you'll be prompted SEPARATELY to write them a briefing -- do NOT include any briefing or summary in your current reply. Write nothing else this turn: the hand-off itself and the briefing you're about to write are the whole goodbye, and anything else you write now is sent to nobody.",
         };
     }
     async function handBackToConcierge(caller, input, ctx) {
         if (ctx.mainChatId == null)
             throw new Error("hand_back_to_concierge is only available while replying in a chat.");
-        if (!globalAgentId)
-            throw new Error("No Global agent is configured on this server.");
-        if (globalAgentId === caller.saltAppId)
+        // A real one step back: whoever handed THIS chat to you, which on a
+        // Concierge -> A -> B chain is A, not the fixed concierge id -- a fixed
+        // destination would skip A entirely. Only when there is no previous hop
+        // (this identity is the FIRST agent in the chat, or the trail runs out)
+        // does salt-api answer 422, and only then do we fall back to a fixed
+        // destination at all.
+        try {
+            await client.handBack(caller.apiKey, ctx.mainChatId);
+            return {
+                handed_off: true,
+                handedOff: true,
+                to: "previous",
+                note: "They're live in this chat now; you'll be prompted SEPARATELY to write them a briefing -- do NOT include any briefing or summary in your current reply. Write nothing else this turn: the hand-off itself and the briefing you're about to write are the whole goodbye, and anything else you write now is sent to nobody.",
+            };
+        }
+        catch (err) {
+            if (!(err instanceof client_1.SaltApiError) || err.status !== 422)
+                throw err;
+            // "Already at the start of this conversation." -- nowhere further
+            // back to go, so fall through to the configured front door below.
+        }
+        if (!conciergeAgentId)
+            throw new Error("No concierge is configured on this server.");
+        if ((0, ids_js_1.sameId)(conciergeAgentId, caller.saltAppId))
             throw new Error("You already are the concierge.");
-        await client.handOff(caller.apiKey, ctx.mainChatId, globalAgentId, input.reason);
+        await client.handOff(caller.apiKey, ctx.mainChatId, conciergeAgentId, input.reason);
         return {
             handed_off: true,
+            handedOff: true,
             to: "concierge",
-            note: "The concierge is live in this chat now; you'll be prompted SEPARATELY to write them a briefing -- do NOT include any briefing or summary in your current reply. Your current reply is just the goodbye: one short sentence letting the person know you're wrapping up and handing back.",
+            note: "The concierge is live in this chat now; you'll be prompted SEPARATELY to write them a briefing -- do NOT include any briefing or summary in your current reply. Write nothing else this turn: the hand-off itself and the briefing you're about to write are the whole goodbye, and anything else you write now is sent to nobody.",
         };
     }
     async function offerHandoffChoices(caller, input, ctx) {
@@ -373,13 +653,16 @@ function createActions(options) {
             client.listAgents(caller.apiKey),
             client.getChatMembers(caller.apiKey, ctx.mainChatId),
         ]);
-        const humanIds = members.filter((m) => m.account_type !== "Agent" && !m.observer).map((m) => parseInt(m.id, 10));
+        // These become the button's `restricted_to` allowlist. parseInt turned
+        // every one into NaN, which serialises to null and matches nobody -- so
+        // "only these humans may press this" silently meant "nobody may".
+        const humanIds = members.filter((m) => m.account_type !== "Agent" && !m.observer).map((m) => String(m.id));
         if (humanIds.length === 0)
             throw new Error("No human member to offer choices to.");
         const blocks = [{ type: "section", text: "Who should take this over? Pick one:" }];
         for (const c of candidates) {
-            const agent = directory.find((a) => a.id === Number(c.agent_id));
-            if (!agent || agent.id === caller.saltAppId)
+            const agent = directory.find((a) => (0, ids_js_1.sameId)(a.id, c.agent_id));
+            if (!agent || (0, ids_js_1.sameId)(agent.id, caller.saltAppId))
                 continue;
             const fields = [];
             if (agent.category)
@@ -429,6 +712,137 @@ function createActions(options) {
             note: "No recovery phrase exists for this wallet -- it's only as safe as this server's wallet master key.",
         };
     }
+    // --- identity_set / identity_get --------------------------------------
+    async function identitySet(caller, input) {
+        const claims = {};
+        for (const key of identity_js_1.AGENT_CLAIM_SECTION_KEYS) {
+            const raw = input[key];
+            if (raw === undefined || raw === null)
+                continue;
+            claims[key] = String(raw);
+        }
+        if (input.capabilities !== undefined && input.capabilities !== null) {
+            if (!Array.isArray(input.capabilities))
+                throw new Error("capabilities must be a list of {title, detail}.");
+            if (input.capabilities.length > identity_js_1.MAX_CAPABILITIES)
+                throw new Error(`List at most ${identity_js_1.MAX_CAPABILITIES} capabilities.`);
+            claims.capabilities = input.capabilities.map((c) => {
+                const item = (c ?? {});
+                const title = String(item.title ?? "").trim();
+                if (!title)
+                    throw new Error("Every capability needs a title.");
+                const detail = item.detail === undefined || item.detail === null ? "" : String(item.detail).trim();
+                return detail ? { title, detail } : { title };
+            });
+        }
+        if (Object.keys(claims).length === 0) {
+            throw new Error(`Provide at least one section to set: ${[...identity_js_1.AGENT_CLAIM_SECTION_KEYS, "capabilities"].join(", ")}.`);
+        }
+        const result = await client.setIdentity(caller.apiKey, claims);
+        return {
+            updated: true,
+            sections: Object.keys(claims),
+            card_url: result.card_url,
+            note: "These are CLAIMS you made about yourself -- signed as coming from you, not verified as true by " +
+                "anyone. A PROOF section (like your PGP fingerprint, Salt DID, or trust score) is different: Salt " +
+                "itself checks and signs those. Never present a claim as if it were checked, and never claim a " +
+                "proof section's value yourself -- this action can't set one anyway.",
+        };
+    }
+    async function identityGet(caller, input) {
+        const handle = String(input.handle || "").trim();
+        if (!handle)
+            throw new Error("handle is required.");
+        let result;
+        try {
+            result = await client.card(handle, input.kind ? { kind: input.kind } : undefined);
+        }
+        catch (err) {
+            if (err instanceof identity_js_1.IdentityCardInvalidError) {
+                return { found: false, reason: `Found a card for ${handle}, but could not trust it: ${err.message}` };
+            }
+            if (err instanceof client_1.SaltApiError && err.status === 404) {
+                return { found: false, reason: `No card is served for ${handle} -- the handle may not exist, or that account's card isn't discoverable.` };
+            }
+            throw err;
+        }
+        // `proof` is deliberately opaque (identity.ts never assumes its shape --
+        // see CardSection's comment): today it's just null-or-not, so
+        // checked_by comes back null and the note tells the model to say "a
+        // proof" rather than inventing a checker. Once the API sends
+        // `{by: "Salt" | "Grains" | "contacts"}` on a proof section, that name
+        // rides straight through with no change here.
+        const sections = (result.card.sections ?? []).map((s) => {
+            const isProof = s.proof != null;
+            const by = isProof && typeof s.proof === "object" && s.proof !== null ? s.proof.by : undefined;
+            return {
+                key: s.key,
+                value: s.value,
+                is_proof: isProof,
+                checked_by: typeof by === "string" ? by : null,
+            };
+        });
+        return {
+            found: true,
+            verified: true,
+            name: result.card.name,
+            description: result.card.description,
+            sections,
+            note: "verified: true means Salt's signature on this card checked out -- it really is what that account " +
+                "published. Sections with is_proof=true are PROOFS, checked by someone other than the subject " +
+                "itself -- checked_by names who, when known; if checked_by is null, call it 'a proof' and don't " +
+                "guess who checked it. Every other section is only that account's own claim about itself, " +
+                "unverified by anyone. Never repeat a claim section as if it had been checked.",
+        };
+    }
+    // --- identity_share / identity_ask / identity_revoke (R3/R4) -----------
+    async function identityShareAction(caller, input, ctx) {
+        const chatId = input.chat_id || ctx.mainChatId;
+        if (chatId == null) {
+            throw new Error("identity_share needs a chat_id, or must be called while replying in a chat.");
+        }
+        const keys = Array.isArray(input.keys) ? input.keys.map(String) : [];
+        if (keys.length === 0)
+            throw new Error("Provide at least one section key to share, e.g. [\"bio\", \"link\"].");
+        const result = await identitySharer.share(caller, chatId, keys);
+        return {
+            shared: true,
+            id: result.id,
+            message_id: result.messageId,
+            recipients: result.recipients,
+            note: "Sent as one signed message, readable only by the chat's members -- Salt's server only ever learned " +
+                "which section keys you shared and with whom, never the values themselves.",
+        };
+    }
+    async function identityAskAction(caller, input, ctx) {
+        if (ctx.mainChatId == null) {
+            throw new Error("identity_ask is only available while replying in a chat.");
+        }
+        const keys = Array.isArray(input.keys) ? input.keys.map(String) : [];
+        if (keys.length === 0)
+            throw new Error("Provide at least one section key to ask for, e.g. [\"legal_name\"].");
+        const text = typeof input.text === "string" && input.text.trim() ? input.text.trim() : undefined;
+        const id = await identitySharer.ask(caller, ctx.mainChatId, keys, text);
+        return {
+            asked: true,
+            id,
+            note: "Only works in a 1:1 -- there is no group equivalent yet. Their answer (a share or a decline) arrives " +
+                "as its own event, not as a return value from this call.",
+        };
+    }
+    async function identityRevokeAction(caller, input) {
+        const id = typeof input.id === "string" ? input.id.trim() : "";
+        if (!id)
+            throw new Error("id is required -- the id identity_share returned.");
+        const rows = await identitySharer.revoke(caller, id);
+        return {
+            revoked: true,
+            id,
+            chat_id: rows[0]?.chat_id ?? null,
+            recipients: rows.length,
+            note: "Stops it being served again and sends a notice into the chat -- cannot reach a copy already read on someone's device.",
+        };
+    }
     const definitions = [
         {
             name: "create_salt_agent",
@@ -480,6 +894,9 @@ function createActions(options) {
                 "exactly like a human messaging that agent. Creates (or reuses) a 1:1 chat with the target, " +
                 "sends it your request, and waits for its reply, which is returned to you to use. This is a " +
                 "real, visible conversation, not a shortcut: anyone who opens that chat can see the " +
+                "delegation happen. The target joins THAT chat, never the one you are replying in -- the person " +
+                "you are helping cannot message it there, so never tell them it is 'in this chat' (use " +
+                "hand_off_to_agent when they should talk to it directly). Anyone who opens the delegation chat can see the " +
                 "delegation happen. Use list_salt_agents first to pick a suitable, well-rated target rather " +
                 "than guessing an id. Only delegate work the other agent is plausibly better positioned for " +
                 "-- don't delegate something you can already just answer yourself. You can't delegate to " +
@@ -488,13 +905,79 @@ function createActions(options) {
             schema: {
                 type: "object",
                 properties: {
-                    target_agent_id: { type: "integer", description: "The Salt user id of the agent to delegate to (from list_salt_agents)." },
+                    target_agent_id: { type: "string", description: "The Salt user id of the agent to delegate to (from list_salt_agents)." },
                     task: { type: "string", description: "The sub-task or question to send, written as a clear, self-contained request -- the target agent has no other context about your conversation." },
                 },
                 required: ["target_agent_id", "task"],
             },
             execute: delegateToAgent,
         },
+        {
+            name: "report_progress",
+            description: "Keep the person you are answering up to date on work that takes a while, privately. Salt " +
+                "shows the report in that person's Tasks panel for this chat -- never in the conversation, " +
+                "and nobody else in the chat can see it. Use status 'running' when you start something that " +
+                "will take more than a few seconds, and again with the same id when the step changes; " +
+                "'waiting' when you cannot continue without something from them (they are notified and can " +
+                "answer you privately); 'done' or 'failed' when it ends. Keep one id for one piece of work: " +
+                "omit id to start a new one and reuse the id you get back. Delegations through " +
+                "delegate_to_agent/consult_agent are reported for you -- do not report those again. Do not " +
+                "report quick answers; just answer. MONEY WORK: report 'done' on a payment only with " +
+                "evidence: {transfer_id} -- it is verified as actually confirmed on-chain before the report " +
+                "is delivered, and refused otherwise.",
+            schema: {
+                type: "object",
+                properties: {
+                    id: { type: "string", description: "The id returned by an earlier report of the same work. Omit to start a new piece of work." },
+                    status: { type: "string", enum: ["running", "waiting", "done", "failed"], description: "Where the work stands now." },
+                    title: { type: "string", description: 'One short line, e.g. "Comparing three flights" or "I need your departure date".' },
+                    detail: { type: "string", description: "Optional: a sentence or two more, e.g. what you found so far or exactly what you need." },
+                    evidence: {
+                        type: "object",
+                        description: "Required to report 'done' on money work: {transfer_id}. Verified against the real " +
+                            "transfer (must have actually confirmed) before the report is delivered -- claiming a " +
+                            "payment is done without this, or before it confirms, is refused.",
+                        properties: { transfer_id: { type: "string", description: "The Transfer id (e.g. from send_invoice's payment, once paid)." } },
+                    },
+                },
+                required: ["status", "title"],
+            },
+            execute: reportProgress,
+        },
+        {
+            name: "consult_agent",
+            description: "Ask a fellow member of THIS chat -- someone already in the room, human-visible as a " +
+                "participant -- a question in a private lane off it, and wait for their reply, which is " +
+                "returned to you to use. Unlike delegate_to_agent (a separate 1:1 the target never joins), " +
+                "the consulted agent stays inline: their later messages arrive in your ordinary onMessage " +
+                "flow, in that lane, without you calling this again. Use this instead of delegate_to_agent " +
+                "specifically when the agent you want is already a member of the current chat. They can ask " +
+                "to be brought into the room directly instead (request_floor); you'll be handed off to them " +
+                "automatically if so.",
+            schema: {
+                type: "object",
+                properties: {
+                    handle: { type: "string", description: "Username (without @) of the agent to consult -- must already be a member of this chat." },
+                    briefing: { type: "string", description: "Optional short context the target has no other way to get (they can't see this chat)." },
+                    question: { type: "string", description: "The question to ask." },
+                },
+                required: ["handle", "question"],
+            },
+            execute: consultAgent,
+        },
+        {
+            name: "request_floor",
+            description: "From INSIDE a consult lane only (one someone opened with you via consult_agent): ask the " +
+                "asking agent to bring you into the room directly instead of continuing to relay your " +
+                "answers through this lane. If they do, you'll be handed off into the room and prompted " +
+                "separately to introduce yourself. Use this when the conversation would go faster with you " +
+                "talking to the person directly rather than through an intermediary.",
+            schema: {
+                type: "object",
+                properties: { reason: { type: "string", description: "One line on why you'd rather join directly." } },
+            },
+            execute: requestFloor,
+        },
         {
             name: "post_card",
             description: "Post an interactive card (a mini app) into the CURRENT chat: sections of markdown text " +
@@ -520,7 +1003,7 @@ function createActions(options) {
             schema: {
                 type: "object",
                 properties: {
-                    card_id: { type: "integer", description: "The card's id (from post_card's result or the card_interaction event)." },
+                    card_id: { type: "string", description: "The card's id (from post_card's result or the card_interaction event)." },
                     blocks: BLOCKS_SCHEMA,
                 },
                 required: ["card_id", "blocks"],
@@ -553,7 +1036,7 @@ function createActions(options) {
             description: "List shop products -- your own (default) or another seller's (pass seller_id). Use before offering/metering so you reference real product ids and current prices.",
             schema: {
                 type: "object",
-                properties: { seller_id: { type: "integer", description: "Omit for your own products." } },
+                properties: { seller_id: { type: "string", description: "Omit for your own products." } },
             },
             execute: listProducts,
         },
@@ -562,7 +1045,7 @@ function createActions(options) {
             description: "Share one of YOUR products into the current chat as a bubble with a real Buy button. Buying drops an invoice the buyer pays on Salt's normal rail -- you never handle the money.",
             schema: {
                 type: "object",
-                properties: { product_id: { type: "integer" } },
+                properties: { product_id: { type: "string" } },
                 required: ["product_id"],
             },
             execute: offerProduct,
@@ -598,7 +1081,7 @@ function createActions(options) {
             schema: {
                 type: "object",
                 properties: {
-                    product_id: { type: "integer" },
+                    product_id: { type: "string" },
                     qty: { type: "string", description: 'Units delivered, e.g. "1" or "3". Default "1".' },
                     description: { type: "string", description: "Short human-readable line for the ledger." },
                 },
@@ -629,12 +1112,18 @@ function createActions(options) {
                 "this same chat (no new chat is created), you stay in the room silently, and you'll be " +
                 "asked to write a briefing for them right after. Use in AUTO-mode hand-off chats when " +
                 "another agent clearly serves the person better (check list_salt_agents first for a " +
-                "well-rated match). ALWAYS tell the person you're handing off and why, in the same reply or " +
-                "just before. Never use this in MANUAL mode -- offer_handoff_choices is for that.",
+                "well-rated match). Never use this in MANUAL mode -- offer_handoff_choices is for that. On " +
+                "success, Salt itself posts a visible line naming the hand-off -- that seam plus the " +
+                "briefing you're asked for next ARE the goodbye, so write nothing else this turn: say " +
+                "whatever the person needs to know BEFORE calling this, in an earlier reply, never after -- " +
+                "any text you write in the same turn as a successful call is never sent. If Salt refuses " +
+                "the hand-off, this returns a plain result ({ok: false, refused: true, reason, next_step}) " +
+                "instead of an error -- say the reason in one sentence and follow next_step; don't call it a " +
+                "technical issue or guess at a cause.",
             schema: {
                 type: "object",
                 properties: {
-                    agent_id: { type: "integer", description: "The agent taking over (from list_salt_agents)." },
+                    agent_id: { type: "string", description: "The agent taking over (from list_salt_agents)." },
                     reason: { type: "string", description: "One line on why -- shown in the hand-off trail." },
                 },
                 required: ["agent_id", "reason"],
@@ -643,14 +1132,18 @@ function createActions(options) {
         },
         {
             name: "hand_back_to_concierge",
-            description: "Hand this conversation back to the Global concierge agent -- the router this person " +
-                "originally started with. Use this as soon as you've wrapped up what you were brought in " +
-                "for: you answered their question, finished the task, hit something outside your scope, or " +
-                "they signal they're done / want something else. Don't wait to be asked -- a person who has " +
-                "to explicitly request 'take me back to the concierge' is a failure of this tool's whole " +
-                "point. Same mechanics as hand_off_to_agent: you stay in the room silently, and you'll be " +
-                "asked to write a briefing right after. AUTO-mode hand-off chats only -- in MANUAL mode, " +
-                "tell the person they can jump back to the concierge from chat info themselves.",
+            description: "Hand this conversation back to whoever handed it over to you -- usually the Global " +
+                "concierge agent, the router this person originally started with, but exactly whoever " +
+                "handed off to you if that was someone else. Use this as soon as you've wrapped up what " +
+                "you were brought in for: you answered their question, finished the task, hit something " +
+                "outside your scope, or they signal they're done / want something else. Don't wait to be " +
+                "asked -- a person who has to explicitly request 'take me back' is a failure of this tool's " +
+                "whole point. Same mechanics as hand_off_to_agent: you stay in the room silently, you'll be " +
+                "asked to write a briefing right after, and that briefing plus Salt's own visible hand-off " +
+                "line are the whole goodbye -- write nothing else this turn; any text you write in the same " +
+                "turn as a successful call is never sent, so say anything the person needs to hear BEFORE " +
+                "calling this, in an earlier reply. AUTO-mode hand-off chats only -- in MANUAL mode, tell the " +
+                "person they can jump back to the concierge from chat info themselves.",
             schema: {
                 type: "object",
                 properties: { reason: { type: "string", description: "One line on why you're handing back -- shown in the hand-off trail." } },
@@ -672,7 +1165,7 @@ function createActions(options) {
                         description: "2-4 entries: {agent_id, why} -- `why` is your one-line pitch for this candidate.",
                         items: {
                             type: "object",
-                            properties: { agent_id: { type: "integer" }, why: { type: "string" } },
+                            properties: { agent_id: { type: "string" }, why: { type: "string" } },
                             required: ["agent_id", "why"],
                         },
                     },
@@ -681,6 +1174,132 @@ function createActions(options) {
             },
             execute: offerHandoffChoices,
         },
+        {
+            name: "identity_set",
+            description: "State one or more CLAIM sections about YOURSELF on your Salt identity card -- your public, " +
+                "signed profile (display_name, bio, link, avatar, category, message_price, funding_disclosure, and " +
+                "capabilities: your \"What I can do\" list, up to 5 lines, shown to anyone who opens your page). " +
+                "This is a CLAIM, not a proof: it's signed as coming from you, never verified as true by anyone. " +
+                "Don't set message_price to advertise a price you don't actually enforce, and don't claim a " +
+                "PROOF section (like your PGP fingerprint or trust score) here -- those are computed and signed " +
+                "by Salt itself and can't be set through this action. You cannot set who else can see a section " +
+                "(scope) -- that's controlled by your owner, not you.",
+            schema: {
+                type: "object",
+                properties: {
+                    display_name: { type: "string", description: "Shown on your card and message bubbles." },
+                    bio: { type: "string", description: "One-line description of who/what you are." },
+                    link: { type: "string", description: "A URL you want associated with you (e.g. your homepage)." },
+                    avatar: { type: "string", description: "A URL to an image to use as your avatar." },
+                    category: { type: "string", description: "Directory category, e.g. Assistant, Trading, Fun, Utilities." },
+                    message_price: { type: "string", description: 'Decimal string price to message you 1:1, e.g. "0.01". Omit for free.' },
+                    funding_disclosure: { type: "string", description: 'How you\'re funded, e.g. "self-funded" -- a real, honest answer, not left blank.' },
+                    capabilities: {
+                        type: "array",
+                        maxItems: 5,
+                        description: "What you can do, in plain words, most useful first. Replaces the whole list. Each line a short title and an optional one-line detail.",
+                        items: {
+                            type: "object",
+                            properties: {
+                                title: { type: "string", maxLength: 60, description: 'e.g. "Builds plugins for your chats"' },
+                                detail: { type: "string", maxLength: 120, description: 'e.g. "Lists, trackers and polls, right in the conversation."' },
+                            },
+                            required: ["title"],
+                        },
+                    },
+                },
+                required: [],
+            },
+            execute: identitySet,
+        },
+        {
+            name: "identity_get",
+            description: "Fetch and cryptographically verify another person's or agent's Salt identity card -- their " +
+                "public, signed profile. The whole card is signed by Salt, but that only proves it really is " +
+                "what that account published -- individual sections are marked is_proof (checked by someone " +
+                "other than the subject, named in checked_by when known) or not (that account's own unverified " +
+                "claim about itself), so you can tell the two apart before repeating anything from it. " +
+                "Verification failing at all raises an error rather than a false result.",
+            schema: {
+                type: "object",
+                properties: {
+                    handle: { type: "string", description: "Username (without @) of the person or agent whose card to fetch." },
+                    kind: { type: "string", enum: ["agent", "user"], description: "Optional: fetch only the agent card or only the person card. Omit to try both." },
+                },
+                required: ["handle"],
+            },
+            execute: identityGet,
+        },
+        {
+            name: "identity_share",
+            description: "Send one or more of YOUR OWN identity card sections into a chat as a signed, end-to-end encrypted " +
+                "message -- Salt's server only ever learns which section keys you shared and with whom, never the " +
+                "values. Defaults to the chat you're currently replying in; pass chat_id to share into a different " +
+                "one. Every non-observer member of that chat receives it. Use identity_revoke with the returned id " +
+                "to take a share back.",
+            schema: {
+                type: "object",
+                properties: {
+                    keys: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: 'Section keys to share, e.g. ["bio", "link"] -- must be sections you have actually stated (identity_set) or a proof Salt computed for you.',
+                    },
+                    chat_id: { type: "string", description: "Optional -- defaults to the current chat." },
+                },
+                required: ["keys"],
+            },
+            execute: identityShareAction,
+        },
+        {
+            name: "identity_ask",
+            description: "Ask the other person in the current 1:1 chat to share one or more sections of THEIR OWN identity " +
+                "card with you. Only works in a 1:1 -- there is no group equivalent yet. They may share what you " +
+                "asked for, share something else, decline, or ignore it; their answer arrives as its own event, not " +
+                "as a result of this call.",
+            schema: {
+                type: "object",
+                properties: {
+                    keys: { type: "array", items: { type: "string" }, description: 'Section keys you are asking for, e.g. ["legal_name"].' },
+                    text: { type: "string", description: "Optional one-line reason, shown alongside the ask." },
+                },
+                required: ["keys"],
+            },
+            execute: identityAskAction,
+        },
+        {
+            name: "react_to_message",
+            description: "React to a message with ONE emoji. Use sparingly: not all the time, just when you choose, and only if it " +
+                "relevantly complements the chat in a friendly way (thank someone back, mark a request done with a check, " +
+                "celebrate good news, show you are on it). Never react instead of answering a question, never to every " +
+                "message, never to your own, at most one per message. Calling it again with the same emoji removes yours.",
+            schema: {
+                type: "object",
+                properties: {
+                    message_id: { type: "string", description: "The id of the message to react to (the incoming message's message_id)." },
+                    emoji: { type: "string", description: "Exactly one emoji, e.g. a thumbs up or a check mark." },
+                },
+                required: ["message_id", "emoji"],
+            },
+            execute: async (caller, input) => {
+                const id = String(input?.message_id ?? "").trim();
+                if (!/^[A-Za-z0-9_-]+$/.test(id))
+                    throw new Error("message_id must be a plain Salt message id.");
+                const result = await client.react(caller.apiKey, id, String(input?.emoji ?? ""));
+                return { ok: true, ...result };
+            },
+        },
+        {
+            name: "identity_revoke",
+            description: "Revoke a section disclosure you previously sent with identity_share -- stops it being served again " +
+                "and sends a notice into the chat it was shared in. Cannot reach a copy already read on someone's device.",
+            schema: {
+                type: "object",
+                properties: { id: { type: "string", description: "The id identity_share returned." } },
+                required: ["id"],
+            },
+            execute: identityRevokeAction,
+        },
     ];
     const byName = new Map(definitions.map((d) => [d.name, d]));
     async function execute(name, input, caller, ctx) {