salt-agent-sdk 0.1.0 → 0.18.0

package/dist/webhook.js

@@ -50,31 +50,237 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HANDOFF_BRIEFING_MARKER = void 0;
+exports.DEVICE_LOST_CONTACT = exports.HANDOFF_BRIEFING_MARKER = void 0;
+exports.createDispatcher = createDispatcher;
 exports.createWebhookServer = createWebhookServer;
+const node_crypto_1 = require("node:crypto");
 const express_1 = __importDefault(require("express"));
+const asks = __importStar(require("./ask.js"));
 const pgp = __importStar(require("./crypto"));
 const delegations = __importStar(require("./delegations"));
+const identityShare = __importStar(require("./identityShare.js"));
+const identity_js_1 = require("./identity.js");
+const ids_js_1 = require("./ids.js");
+const reconcile_1 = require("./reconcile");
+const sessions = __importStar(require("./sessions"));
+const work_1 = require("./work");
 const PGP_MESSAGE_RE = /^-----BEGIN PGP MESSAGE/;
+const DELIVERED_BECAUSE_VALUES = new Set(["mention", "reply", "keyword", "all"]);
+/** Narrows salt-api's `message.delivered_because` (a plain string, only
+ *  ever present on an open-room delivery) to the known union -- anything
+ *  else (missing, or a value this SDK version doesn't recognise yet)
+ *  becomes undefined rather than an unchecked cast, so a future kind added
+ *  server-side degrades to "unknown reason" instead of lying about it. */
+function parseDeliveredBecause(raw) {
+    return typeof raw === "string" && DELIVERED_BECAUSE_VALUES.has(raw) ? raw : undefined;
+}
+function parseReplyParent(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const p = raw;
+    if (p.id == null)
+        return undefined;
+    return { id: String(p.id), author: p.author ?? null, excerpt: typeof p.excerpt === "string" ? p.excerpt : "" };
+}
 /** The exact marker a hand-off briefing must start with, so the incoming
  *  agent's polling loop (below) can detect it arrived. Consumers building
  *  the outgoing briefing prompt must instruct their model to emit this
  *  exact line first. */
 exports.HANDOFF_BRIEFING_MARKER = "[[SALT-HANDOFF-BRIEFING]]";
+/** Content types decrypted straight to UTF-8 text in `DecryptedAttachment.text`,
+ *  in addition to the raw bytes in `data`. Deliberately excludes PDF (see
+ *  DecryptedAttachment.text's own comment) and images/audio/video (never
+ *  meaningfully "text"). */
+function isTextLikeAttachment(contentType) {
+    if (contentType.startsWith("text/"))
+        return true;
+    return ["application/json", "application/csv", "application/markdown"].includes(contentType);
+}
+// --- Device moments --------------------------------------------------------
+//
+// Two agent-rail deliveries (kind `device_session`) tell an agent that the
+// person's computer went quiet in the middle of its work and that it came
+// back. Plaintext metadata only -- ids, the computer's name, timestamps --
+// delivered like card_interaction/invoice_paid, never a chat message. Source
+// of truth: salt-api docs/DEVICE_PROTOCOL.md.
+/** The `end_reason` of a device session. `lost_contact` is the one this SDK names: the computer stopped answering for 15 s mid-session. Any other value is passed through verbatim. */
+exports.DEVICE_LOST_CONTACT = "lost_contact";
 const consoleLogger = {
     info: (msg) => console.log(msg),
     error: (msg) => console.error(msg),
 };
 /**
- * Creates the Express app for a Salt agent's webhook endpoint. Mount it
- * yourself (e.g. `createWebhookServer(opts).listen(port)`, or grab `.app`
- * to compose it into a bigger server).
+ * Everything about the Salt protocol that is NOT "how do bytes get to this
+ * process" -- signature verification and the decrypt/route/dedup/reply
+ * logic for every webhook event kind. `createWebhookServer` below wraps
+ * this in an Express POST route (the only transport before K2); socket.ts's
+ * `createSocketClient` wraps the SAME dispatcher around a websocket push
+ * connection instead, so a consumer switches delivery mode with no change
+ * to onMessage/onCardInteraction/etc. -- see socket.ts's own doc comment.
  */
-function createWebhookServer(options) {
-    const { client, identities, pgpPassphrase, webhookSharedSecret, mediatorAgentId } = options;
+function createDispatcher(options) {
+    const { client, identities, pgpPassphrase, mediatorAgentId } = options;
     const logger = options.logger ?? consoleLogger;
-    const app = (0, express_1.default)();
-    app.use(express_1.default.json());
+    const verifySignatures = options.verifySignatures !== false;
+    const signatureTolerance = options.signatureToleranceSeconds ?? 300;
+    const sessionStore = options.sessionStore ?? sessions.MemorySessionStore();
+    const identitySharer = identityShare.createIdentitySharer(client, pgpPassphrase);
+    const mapKey = (id) => String(id).toLowerCase();
+    // A lookup miss on a signed request is the signature of a stale store: the
+    // id salt-api signs with is not the one the identity was registered under
+    // (see reconcile.ts). Ask the API once, then look again. Throttled so an
+    // unknown-agent POST from the open internet costs at most one round of
+    // whoAmI calls a minute, and single-flight so a burst shares one pass.
+    const RECONCILE_MIN_INTERVAL_MS = 60_000;
+    let lastReconcileAt = 0;
+    let reconcileInFlight = null;
+    function reconcileOnMiss() {
+        if (reconcileInFlight)
+            return reconcileInFlight;
+        if (Date.now() - lastReconcileAt < RECONCILE_MIN_INTERVAL_MS)
+            return Promise.resolve();
+        lastReconcileAt = Date.now();
+        reconcileInFlight = (0, reconcile_1.reconcileIdentityIds)(identities, client, logger)
+            .catch((err) => logger.error(`[webhook] identity reconcile failed: ${err.message}`))
+            .finally(() => {
+            reconcileInFlight = null;
+        });
+        return reconcileInFlight;
+    }
+    // One signing key per identity, fetched lazily with that identity's own api
+    // key and cached. A miss is not fatal on its own -- verifyRequest decides.
+    const secretCache = new Map();
+    async function secretForAgent(agentId) {
+        const cacheKey = String(agentId).toLowerCase();
+        const cached = secretCache.get(cacheKey);
+        if (cached)
+            return cached;
+        let identity = identities.get(agentId);
+        if (!identity) {
+            await reconcileOnMiss();
+            identity = identities.get(agentId);
+        }
+        if (!identity)
+            return undefined;
+        try {
+            const secret = await client.getWebhookSecret(identity.apiKey);
+            if (secret)
+                secretCache.set(cacheKey, secret);
+            return secret;
+        }
+        catch (err) {
+            logger.error(`[webhook] could not fetch signing key for agent ${agentId}: ${err.message}`);
+            return undefined;
+        }
+    }
+    // R1 (round 3, 2026-09-18): a bounded, rate-limited recheck for the ONE
+    // case that can still legitimately race a rotation now that salt-api
+    // signs socket-mode envelopes fresh at serve time (LANES.md) -- a real
+    // webhook POST, which IS signed at send time by the enqueuing job, can
+    // still land here with a signature made against a secret that rotated
+    // a moment after the job read it but before this cache picked up the
+    // change. At most one uncached fetch per agent per 60s, single-flight
+    // (a burst of bad signatures for one agent shares the one in-flight
+    // check rather than each firing its own), and it NEVER evicts/replaces
+    // the cached secret unless the freshly fetched one actually verifies
+    // the failing envelope -- a fetch that doesn't fix the problem leaves
+    // the cache exactly as it was. Round 2's per-envelope evict-and-refetch
+    // (and its one-time "transient" grace) is gone entirely: with
+    // serve-time signing the socket path never needs it, and this bounded
+    // version is what's left for the webhook path.
+    const UNCACHED_CHECK_MIN_INTERVAL_MS = 60_000;
+    const lastUncachedCheckAt = new Map();
+    const uncachedCheckInFlight = new Map();
+    function uncachedSecretCheck(agentId, cacheKey) {
+        const inFlight = uncachedCheckInFlight.get(cacheKey);
+        if (inFlight)
+            return inFlight;
+        const lastAt = lastUncachedCheckAt.get(cacheKey) ?? 0;
+        if (Date.now() - lastAt < UNCACHED_CHECK_MIN_INTERVAL_MS)
+            return Promise.resolve(undefined);
+        lastUncachedCheckAt.set(cacheKey, Date.now());
+        const promise = (async () => {
+            const identity = identities.get(agentId);
+            if (!identity)
+                return undefined;
+            try {
+                return await client.getWebhookSecret(identity.apiKey);
+            }
+            catch (err) {
+                logger.error(`[webhook] uncached signing-key recheck for agent ${agentId} failed: ${err.message}`);
+                return undefined;
+            }
+        })().finally(() => {
+            uncachedCheckInFlight.delete(cacheKey);
+        });
+        uncachedCheckInFlight.set(cacheKey, promise);
+        return promise;
+    }
+    // Verifies one envelope's signature. Takes the two headers and the raw
+    // body explicitly rather than an Express Request -- the SAME check runs
+    // for a webhook POST (createWebhookServer passes req.get(...) and the
+    // captured rawBody) and for a socket-mode envelope (socket.ts passes the
+    // AgentUpdate row's `headers`/`body` fields verbatim), so this function
+    // must not assume either transport.
+    //
+    // `toleranceSeconds` overrides the default (signatureTolerance, ~300s)
+    // for a caller with its own reason to -- round 3 removed socket.ts's
+    // widened one (serve-time signing means a socket envelope's timestamp
+    // is always fresh too), so both transports use the same standard window
+    // by default now.
+    //
+    // `transient: true` marks a failure that might resolve on retry (right
+    // now, only "no signing key" -- secretForAgent already swallows its own
+    // network errors and returns undefined either way, so this can't
+    // distinguish "genuinely no such identity" from "the fetch failed" any
+    // more finely than that) -- socket.ts must not advance its cursor past a
+    // row that failed for a transient reason, or a real update sitting
+    // behind a network blip would be skipped forever.
+    async function verifyEnvelope(agentId, signature, rawBody, opts) {
+        if (!verifySignatures)
+            return { ok: true };
+        // Taken as sent. `Number(...)` here made agentId NaN for every real
+        // request, NaN is falsy, and so EVERY signed webhook was rejected as
+        // "missing signature" -- the header was present and correctly formed.
+        if (!agentId || !signature)
+            return { ok: false, reason: "missing signature", transient: false };
+        const t = /t=(\d+)/.exec(signature)?.[1];
+        const v1 = /v1=([0-9a-f]+)/.exec(signature)?.[1];
+        if (!t || !v1)
+            return { ok: false, reason: "malformed signature", transient: false };
+        // Replay window. Also rejects a clock far in the future.
+        const tolerance = opts?.toleranceSeconds ?? signatureTolerance;
+        const age = Math.abs(Math.floor(Date.now() / 1000) - Number(t));
+        if (age > tolerance)
+            return { ok: false, reason: `stale signature (${age}s old)`, transient: false };
+        const secret = await secretForAgent(agentId);
+        if (!secret)
+            return { ok: false, reason: `no signing key for agent ${agentId}`, transient: true };
+        const cacheKey = String(agentId).toLowerCase();
+        // Constant-time: a fast string compare leaks the digest a byte at a time.
+        const verify = (withSecret) => {
+            const expected = (0, node_crypto_1.createHmac)("sha256", withSecret).update(`${t}.${rawBody}`).digest("hex");
+            const a = Buffer.from(v1, "utf8");
+            const b = Buffer.from(expected, "utf8");
+            return a.length === b.length && (0, node_crypto_1.timingSafeEqual)(a, b);
+        };
+        if (verify(secret))
+            return { ok: true };
+        // Pre-round-2 behaviour, restored: a bad signature is definitive --
+        // UNLESS the bounded recheck above finds a genuinely different
+        // secret that verifies it, in which case it self-heals silently and
+        // the cache picks up the new value. Never transient, never retried.
+        const fresh = await uncachedSecretCheck(agentId, cacheKey);
+        // The fresh secret comes from salt-api under the agent's own key, so it is
+        // authoritative: adopt it whenever it differs, even if THIS envelope doesn't
+        // verify under it, or a leaked old secret stays accepted after a rotation.
+        if (fresh && fresh !== secret) {
+            secretCache.set(cacheKey, fresh);
+            if (verify(fresh))
+                return { ok: true };
+        }
+        return { ok: false, reason: "bad signature", transient: false };
+    }
     // Salt fires one webhook per chat member with a callback URL
     // (Message#send_webhook in salt-api). When two or more identities THIS
     // process hosts share a chat -- which delegation makes possible -- that's
@@ -104,15 +310,51 @@ function createWebhookServer(options) {
     // THIS process hosts crosses this many auto-replies, the receiving
     // identity just stops answering the other one there, until a human sends
     // something new (which resets the count).
-    const MAX_AGENT_TO_AGENT_REPLIES_PER_CHAT = 2;
+    const MAX_AGENT_TO_AGENT_REPLIES_PER_CHAT = options.maxAgentToAgentReplies ?? 2;
+    if (!Number.isInteger(MAX_AGENT_TO_AGENT_REPLIES_PER_CHAT) || MAX_AGENT_TO_AGENT_REPLIES_PER_CHAT < 1) {
+        throw new Error(`maxAgentToAgentReplies must be a positive integer, got ${String(options.maxAgentToAgentReplies)}`);
+    }
+    // A consult lane (actions.ts's consult_agent, chatMeta.lane_kind ===
+    // "consult") is a real working conversation between two agents, not an
+    // accidental loop -- it needs real back-and-forth room, so it gets its
+    // own, much higher ceiling instead of the ordinary chat's cap.
+    const CONSULT_RUNAWAY_LIMIT = 20;
+    // Keyed by the lowercased chat id, like every other id-keyed map here.
     const agentToAgentReplyCounts = new Map();
-    app.get("/health", (_req, res) => {
-        res.json({
-            status: "ok",
-            identities: identities.all().map((i) => ({ salt_app_id: i.saltAppId, username: i.username })),
-            ...(options.healthExtra ? options.healthExtra() : {}),
-        });
-    });
+    // laneChatId (lowercased) -> its room's chat id (lowercased), learned the
+    // first time a message is seen in that lane. A human speaking in the ROOM
+    // should reset every consult lane rooted there too -- a lane's own count
+    // otherwise only resets from someone speaking IN the lane itself, and a
+    // busy pair of agents burning through CONSULT_RUNAWAY_LIMIT would stay
+    // capped even right after the person who asked for the consult weighs in.
+    const laneRoomOf = new Map();
+    // roomId (lowercased) -> the consult lane chat id a request_floor message
+    // just triggered an automatic hand-off from. Set by the floor-request
+    // handler right before calling client.handOff, consumed by
+    // handleHandoffConfirmed once salt-api's own handoff_confirmed webhook
+    // arrives for that room -- that's what lets it attach consultTranscript.
+    // Best-effort: a second floor request for the same room before the first
+    // hand-off confirms would overwrite this, which is an acceptable rarity.
+    const pendingConsultHandoffs = new Map();
+    // chat_opened has no message_id to dedupe on (it isn't a Message at all),
+    // and delivery can be retried -- so a retried delivery must not make this
+    // identity greet the same chat twice. Keyed by identity+chat since one
+    // process can host several identities and a chat could in principle be
+    // opened for more than one of them. Bounded the same way seenMessageIds is.
+    const MAX_SEEN_CHAT_OPENED = 2000;
+    const seenChatOpened = new Set();
+    function alreadyGreeted(identityId, chatId) {
+        const key = `${String(identityId).toLowerCase()}:${String(chatId).toLowerCase()}`;
+        if (seenChatOpened.has(key))
+            return true;
+        seenChatOpened.add(key);
+        if (seenChatOpened.size > MAX_SEEN_CHAT_OPENED) {
+            const oldest = seenChatOpened.values().next().value;
+            if (oldest !== undefined)
+                seenChatOpened.delete(oldest);
+        }
+        return false;
+    }
     // Every identity this process hosts shares this one endpoint, so the
     // first step is figuring out *which* identity a given message is
     // addressed to. Salt encrypts the message to every chat member's public
@@ -120,8 +362,30 @@ function createWebhookServer(options) {
     // private key that was actually a member of that chat, so trying each
     // known identity in turn and keeping whichever one succeeds is both
     // correct and cheap for the small number of identities a process hosts.
-    async function resolveIdentity(ciphertext) {
+    async function resolveIdentity(ciphertext, headerAgentId) {
+        // salt-api signs every callback for a specific RECIPIENT identity and
+        // names it in X-Salt-Agent-Id (see rejectionReason above) -- when that
+        // names one of ours, try it first. Skips the ambiguity trial-decryption
+        // has when this process hosts more than one identity that's a member of
+        // the same chat (a delegation or consult lane makes that possible): any
+        // member's key opens the multi-recipient blob, so without the header,
+        // which one "wins" is just whichever was registered first.
+        if (headerAgentId) {
+            const preferred = identities.get(headerAgentId);
+            if (preferred) {
+                try {
+                    const plaintext = await pgp.decrypt(ciphertext, preferred.privateKey, pgpPassphrase);
+                    return { identity: preferred, plaintext };
+                }
+                catch {
+                    // The header named a real hosted identity, but this ciphertext
+                    // isn't addressed to it -- fall through to trial decryption.
+                }
+            }
+        }
         for (const candidate of identities.all()) {
+            if (headerAgentId && (0, ids_js_1.sameId)(candidate.saltAppId, headerAgentId))
+                continue; // already tried above
             try {
                 const plaintext = await pgp.decrypt(ciphertext, candidate.privateKey, pgpPassphrase);
                 return { identity: candidate, plaintext };
@@ -149,39 +413,162 @@ function createWebhookServer(options) {
         const lines = [];
         for (const raw of messages) {
             const m = raw;
-            if (m.event_type || typeof m.message !== "string" || !PGP_MESSAGE_RE.test(m.message))
+            if (m.event_type || typeof m.message !== "string")
                 continue;
-            try {
-                const text = await pgp.decrypt(m.message, identity.privateKey, pgpPassphrase);
-                lines.push(`${m.user?.display_name || "someone"}: ${text}`);
+            let text;
+            if (m.encrypted === false) {
+                // Open room (salt-api 0.6x): already plaintext, nothing to decrypt.
+                text = m.message;
             }
-            catch {
-                // Predates this identity joining the chat -- skip silently.
+            else {
+                if (!PGP_MESSAGE_RE.test(m.message))
+                    continue;
+                try {
+                    text = await pgp.decrypt(m.message, identity.privateKey, pgpPassphrase);
+                }
+                catch {
+                    continue; // predates this identity joining the chat -- skip silently.
+                }
             }
+            lines.push(`${m.user?.display_name || "someone"}: ${text}`);
         }
         return lines.length ? lines.join("\n") : "(no messages yet)";
     }
+    // Same idea as buildSharedChatContext, but for a session's cold-start
+    // rebuild: structured turns instead of joined display lines, capped to
+    // the same MAX_TRANSCRIPT_TURNS a live session is bounded to, and this
+    // identity's own messages come back tagged "assistant" rather than folded
+    // into "someone: ...". Messages from before `identity` joined fail to
+    // decrypt and are skipped -- same degrade-gracefully convention.
+    async function rebuildTranscriptTail(identity, chatId) {
+        let messages;
+        try {
+            messages = await client.getChatMessages(identity.apiKey, chatId);
+        }
+        catch (err) {
+            logger.error(`[session] fetching chat ${chatId} for cold-start rebuild failed: ${err.message}`);
+            return [];
+        }
+        const turns = [];
+        for (const raw of messages) {
+            const m = raw;
+            if (m.event_type || typeof m.message !== "string")
+                continue;
+            let plaintext;
+            if (m.encrypted === false) {
+                // Open room (salt-api 0.6x): already plaintext, nothing to decrypt.
+                plaintext = m.message;
+            }
+            else {
+                if (!PGP_MESSAGE_RE.test(m.message))
+                    continue;
+                try {
+                    plaintext = await pgp.decrypt(m.message, identity.privateKey, pgpPassphrase);
+                }
+                catch {
+                    continue; // predates this identity joining the chat -- skip silently.
+                }
+            }
+            const { text: afterDepth } = delegations.parseIncoming(plaintext);
+            const content = delegations.stripConsultMarker(afterDepth);
+            const isSelf = (0, ids_js_1.sameId)(m.user?.id, identity.saltAppId);
+            turns.push({
+                role: isSelf ? "assistant" : "user",
+                content,
+                at: m.created_at ? Date.parse(m.created_at) : Date.now(),
+                from: isSelf ? undefined : m.user?.username || m.user?.display_name || String(m.user?.id ?? "someone"),
+                // Only meaningful for the OTHER party's turn -- this identity's own
+                // messages have no "reason it was delivered to me" to report.
+                deliveredBecause: isSelf ? undefined : parseDeliveredBecause(m.delivered_because),
+            });
+        }
+        return turns.length > sessions.MAX_TRANSCRIPT_TURNS ? turns.slice(-sessions.MAX_TRANSCRIPT_TURNS) : turns;
+    }
+    // Loads the stored session for (identity, chatId), or -- on a cold start --
+    // builds a fresh one from the chat's own history. Never throws: a session
+    // store or rebuild failure falls back to an empty session rather than
+    // blocking the message it's here to support.
+    async function loadOrRebuildSession(identity, chatId, chatMeta) {
+        const roomId = chatMeta?.coaching_for_chat_id || chatId;
+        try {
+            const existing = await sessionStore.get(identity.saltAppId, chatId);
+            if (existing)
+                return existing;
+        }
+        catch (err) {
+            logger.error(`[session] loading ${chatId} failed: ${err.message}`);
+        }
+        const role = chatMeta?.lane_kind === "consult" ? "consult" : chatMeta?.coaching_for_chat_id ? "lane" : "active";
+        const session = sessions.emptySession(chatId, roomId, role);
+        try {
+            session.transcriptTail = await rebuildTranscriptTail(identity, chatId);
+        }
+        catch (err) {
+            logger.error(`[session] rebuilding ${chatId} failed: ${err.message}`);
+        }
+        return session;
+    }
+    // Appends each of `repliesForSession` to `session` as an assistant turn,
+    // bounds the note, and persists -- shared by every context type that has
+    // a reply() worth remembering (onMessage additionally appends its own
+    // incoming "user" turn first; see handleMessage, which does that inline
+    // since it's the only one with an incoming turn to record at all). Never
+    // throws: a persistence failure here must not turn into an unhandled
+    // rejection on top of a webhook handler that already ran successfully.
+    async function persistSessionAfterReply(identityId, chatId, session, repliesForSession) {
+        try {
+            for (const replyText of repliesForSession) {
+                sessions.appendTurn(session, { role: "assistant", content: replyText, at: Date.now() });
+            }
+            session.note = sessions.boundNote(session.note);
+            session.updatedAt = Date.now();
+            await sessionStore.put(identityId, chatId, session);
+        }
+        catch (err) {
+            logger.error(`[session] persisting ${chatId} failed: ${err.message}`);
+        }
+    }
+    // The consult lane's own transcript, for a hand-off briefing that was
+    // triggered by a request_floor call rather than chosen by a model turn --
+    // see handleHandoffConfirmed. Capped to the last few exchanges; a consult
+    // lane that ran long doesn't need its entire history in a briefing.
+    const MAX_CONSULT_TRANSCRIPT_LINES = 30;
+    async function buildConsultTranscript(identity, laneId) {
+        const full = await buildSharedChatContext(identity, laneId);
+        const lines = full.split("\n");
+        return lines.length > MAX_CONSULT_TRANSCRIPT_LINES ? lines.slice(-MAX_CONSULT_TRANSCRIPT_LINES).join("\n") : full;
+    }
     // Decrypts an attachment's PGP metadata blob (key/iv/filename/content_type),
-    // downloads the ciphertext, and AES-GCM-decrypts it. Only images are
-    // returned with actual bytes -- the SDK doesn't know how any given model
-    // wants other file types represented, so those get a text note instead.
+    // downloads the ciphertext, and AES-GCM-decrypts it -- for any content
+    // type, up to pgp.MAX_ATTACHMENT_BYTES (the declared `size` is checked
+    // BEFORE downloading/decrypting, so a metadata blob that lies about its
+    // own size can't make this pull down and hold an unbounded blob). Text-
+    // shaped content (text/*, JSON, CSV, Markdown) also gets a decoded `text`
+    // field alongside the raw bytes; a PDF gets bytes only (see
+    // DecryptedAttachment.text's comment on why text extraction stops there).
     async function decryptAttachmentIfPresent(identity, message) {
         if (!message.resource?.encrypted_key)
             return undefined;
         try {
             const metaJson = await pgp.decrypt(message.resource.encrypted_key, identity.privateKey, pgpPassphrase);
             const meta = JSON.parse(metaJson);
-            if (!meta.content_type?.startsWith("image/")) {
+            const filename = meta.filename;
+            const contentType = meta.content_type || "unknown";
+            if (meta.size > pgp.MAX_ATTACHMENT_BYTES) {
                 return {
-                    filename: meta.filename,
-                    contentType: meta.content_type || "unknown",
+                    filename,
+                    contentType,
                     size: meta.size,
-                    unsupportedNote: `attached file: ${meta.filename}, ${meta.content_type || "unknown type"}, ${meta.size} bytes -- not viewable, only images are.`,
+                    unsupportedNote: `attached file: ${filename}, ${contentType}, ${meta.size} bytes -- too large to fetch (cap ${pgp.MAX_ATTACHMENT_BYTES} bytes).`,
                 };
             }
             const ciphertextBytes = await client.getAttachment(identity.apiKey, message.message_id);
             const plaintext = pgp.decryptAttachment(ciphertextBytes, meta.key, meta.iv);
-            return { filename: meta.filename, contentType: meta.content_type, size: meta.size, data: plaintext };
+            const result = { filename, contentType, size: meta.size, data: plaintext };
+            if (isTextLikeAttachment(contentType)) {
+                result.text = plaintext.toString("utf8");
+            }
+            return result;
         }
         catch (err) {
             logger.error(`[attachment] failed to decrypt: ${err.message}`);
@@ -210,14 +597,30 @@ function createWebhookServer(options) {
     // trail onto it + fire-and-forget metrics. Does NOT itself manage the
     // typing indicator -- see withTypingHeartbeat, which wraps the whole
     // callback (including whatever happens before reply() is even called).
-    function makeReply(identity, chatId) {
+    // `addressee` is whoever this reply is answering, when there is one. In a
+    // GROUP chat the reply is addressed back to them by handle -- being spoken
+    // to by name is how a person tells which of several messages in a busy room
+    // is meant for them, and an agent that answers into the middle of a group
+    // without naming anyone reads as talking to the room.
+    //
+    // Two deliberate limits. Only in a group: in a 1:1 there is exactly one
+    // person it could be for, and "@dan" on every line is noise. And only for a
+    // HUMAN: an agent addressed by handle receives a webhook, so auto-addressing
+    // another agent invites exactly the ping-pong the loop caps in this file
+    // exist to stop.
+    function makeReply(identity, chatId, addressee) {
         return async (text) => {
             const startedAt = Date.now();
             let recipientKeys;
+            let memberCount = 0;
             try {
                 const members = await client.getChatMembers(identity.apiKey, chatId);
+                memberCount = members.length;
                 recipientKeys = members
-                    .filter((u) => parseInt(String(u.id), 10) !== identity.saltAppId && u.public_key)
+                    // Everyone but ourselves. parseInt made both sides NaN, and
+                    // `NaN !== NaN` is true, so the sender's own key was left in the
+                    // recipient list rather than filtered out of it.
+                    .filter((u) => !(0, ids_js_1.sameId)(u.id, identity.saltAppId) && u.public_key)
                     .map((u) => u.public_key);
             }
             catch (err) {
@@ -228,10 +631,23 @@ function createWebhookServer(options) {
                 logger.error(`[chat ${chatId}] no recipient public keys; not sending.`);
                 return;
             }
+            // Group + human + a handle to use, and not already addressed by whoever
+            // wrote the reply (an agent that writes its own "@dan" keeps it, and
+            // does not get a second one bolted on the front).
+            const addressHandle = memberCount > 2 &&
+                addressee?.username &&
+                addressee.account_type !== "Agent" &&
+                !new RegExp(`(^|\\s)@${addressee.username}(?![\\w.-])`).test(text)
+                ? addressee.username
+                : null;
+            const outgoing = addressHandle ? `@${addressHandle} ${text}` : text;
+            // The ids, not the text: Salt only ever sees ciphertext, so an "@handle"
+            // in the body is invisible to it and notifies nobody by itself.
+            const mentions = addressHandle ? [addressee.id] : undefined;
             let encryptedMessage, senderMessage;
             try {
-                encryptedMessage = await pgp.encryptFor(text, recipientKeys);
-                senderMessage = await pgp.encryptFor(text, [identity.publicKey]);
+                encryptedMessage = await pgp.encryptFor(outgoing, recipientKeys);
+                senderMessage = await pgp.encryptFor(outgoing, [identity.publicKey]);
             }
             catch (err) {
                 logger.error(`[chat ${chatId}] encryption failed: ${err.message}`);
@@ -239,7 +655,7 @@ function createWebhookServer(options) {
             }
             const trail = delegations.drainTrail(identity.saltAppId, chatId);
             try {
-                await client.postMessage(identity.apiKey, chatId, encryptedMessage, senderMessage, trail);
+                await client.postMessage(identity.apiKey, chatId, encryptedMessage, senderMessage, trail, mentions);
             }
             catch (err) {
                 logger.error(`[chat ${chatId}] posting reply failed: ${err.message}`);
@@ -252,7 +668,159 @@ function createWebhookServer(options) {
             });
         };
     }
-    async function handleMessage(body) {
+    // ctx.ask/ctx.approve (K3, ask.ts) -- bound to one (identity, chatId) the
+    // same way makeReply above is, and handed to every context type that
+    // gets a reply(). The actual card post/update and pending-wait registry
+    // live in ask.ts; resolveCardInteraction/resolveMessage below (wired into
+    // handleCardInteraction/handleMessage) are what settle a wait this
+    // creates.
+    //
+    // `defaultAnswererId` (M2, security review) is each context's natural
+    // "whoever this turn is answering" -- see the individual ctx-construction
+    // call sites for what each context type passes (a message's senderRaw,
+    // chat_opened's openedBy, invoice_paid's buyer; the two hand-off contexts
+    // have no natural default and pass none, so their ask()/approve() calls
+    // must supply `answererId` explicitly). A caller's own `opts.answererId`
+    // always wins over this default.
+    function makeAsk(identity, chatId, defaultAnswererId) {
+        return (question, opts) => asks.ask(client, identity, chatId, question, { answererId: defaultAnswererId, ...opts });
+    }
+    function makeApprove(identity, chatId, defaultAnswererId) {
+        return (summary, opts) => asks.approve(client, identity, chatId, summary, { answererId: defaultAnswererId, ...opts });
+    }
+    // ctx.shareIdentity (identityShare.ts) -- bound to one (identity, chatId)
+    // the same way makeAsk/makeApprove above are.
+    function makeShareIdentity(identity, chatId) {
+        return (keys, opts) => identitySharer.share(identity, chatId, keys, opts);
+    }
+    // True when `chatId` has at least one human (account_type !== "Agent")
+    // member who is NOT a silent observer. A consult lane's human -- the
+    // delegation chain's auditor added per actions.ts's delegation-
+    // observability note -- is only ever an observer there, so a lane reads as
+    // agent-only even though a person can technically decrypt it. `chatMeta`'s
+    // own member list is used when a caller already supplied one (mainly
+    // tests); the real webhook payload's `chat` never carries members (see
+    // salt-api's WebhookJob#user_send allowlist), so this normally falls back
+    // to fetching the roster -- the same call makeReply above already makes to
+    // encrypt a reply.
+    async function chatHasNonObserverHuman(identity, chatId, chatMeta) {
+        const inlineMembers = Array.isArray(chatMeta?.users) ? chatMeta.users : undefined;
+        let members = inlineMembers;
+        if (!members) {
+            try {
+                members = await client.getChatMembers(identity.apiKey, chatId);
+            }
+            catch (err) {
+                logger.error(`[chat ${chatId}] fetching members for mention-gating failed: ${err.message}`);
+                return false;
+            }
+        }
+        return members.some((m) => m.account_type !== "Agent" && m.account_type !== "Device" && !m.observer);
+    }
+    // Runs `options.onIdentityAsk` for an incoming SALT-IDENTITY-ASK and
+    // answers it -- a SLICE (carrying `ask=parsed.id`) for the keys the
+    // handler chose to share, a DECLINE (same) for null/false/an empty
+    // array. Never lets a handler or send failure escape to the caller: an
+    // ask that can't be answered must not crash the webhook pass that
+    // received it, the same convention every other handler-invoking helper
+    // in this file follows.
+    async function handleIdentityAsk(identity, chatId, senderId, parsed) {
+        let decision;
+        try {
+            decision = await options.onIdentityAsk({ id: parsed.id, keys: parsed.keys, text: parsed.text, chatId, from: senderId });
+        }
+        catch (err) {
+            logger.error(`[chat ${chatId}] onIdentityAsk failed: ${err.message}`);
+            return;
+        }
+        try {
+            if (Array.isArray(decision) && decision.length > 0) {
+                await identitySharer.share(identity, chatId, decision, { ask: parsed.id });
+            }
+            else {
+                await identitySharer.decline(identity, chatId, parsed.id);
+            }
+        }
+        catch (err) {
+            logger.error(`[chat ${chatId}] answering identity ask ${parsed.id} failed: ${err.message}`);
+        }
+    }
+    // Handles an incoming SLICE, DECLINE or REVOKE from someone else. A
+    // SLICE is verified against the sender's own public key (fetched fresh
+    // from the chat's member list -- the same call makeReply already makes
+    // to encrypt a reply) and, when verified, recorded on this (identity,
+    // chat) session before `onIdentityShared` fires; a REVOKE removes any
+    // slice recorded under the same id first. Never lets a verification,
+    // session, or handler failure escape -- same convention as
+    // handleIdentityAsk above.
+    async function handleIdentitySharedMarker(identity, chatId, senderId, parsed) {
+        if (parsed.kind === "slice") {
+            let verified = false;
+            try {
+                const members = await client.getChatMembers(identity.apiKey, chatId);
+                const sender = members.find((m) => (0, ids_js_1.sameId)(m.id, senderId));
+                if (sender?.public_key) {
+                    verified = await pgp.verifyDetached((0, identity_js_1.canonicalizeJcs)(parsed.payload.sections), parsed.payload.signature, sender.public_key);
+                }
+            }
+            catch (err) {
+                logger.error(`[chat ${chatId}] verifying identity slice ${parsed.id} failed: ${err.message}`);
+            }
+            try {
+                const session = await loadOrRebuildSession(identity, chatId);
+                sessions.recordReceivedIdentitySlice(session, senderId, {
+                    id: parsed.id,
+                    sections: parsed.payload.sections,
+                    verified,
+                    receivedAt: Date.now(),
+                });
+                session.updatedAt = Date.now();
+                await sessionStore.put(identity.saltAppId, chatId, session);
+            }
+            catch (err) {
+                logger.error(`[session] recording identity slice ${parsed.id} for ${chatId} failed: ${err.message}`);
+            }
+            if (options.onIdentityShared) {
+                try {
+                    await options.onIdentityShared({
+                        kind: "slice",
+                        id: parsed.id,
+                        askId: parsed.askId,
+                        from: senderId,
+                        chatId,
+                        sections: parsed.payload.sections,
+                        verified,
+                    });
+                }
+                catch (err) {
+                    logger.error(`[chat ${chatId}] onIdentityShared (slice) failed: ${err.message}`);
+                }
+            }
+            return;
+        }
+        if (parsed.kind === "revoke") {
+            try {
+                const session = await loadOrRebuildSession(identity, chatId);
+                sessions.forgetReceivedIdentitySlice(session, senderId, parsed.id);
+                session.updatedAt = Date.now();
+                await sessionStore.put(identity.saltAppId, chatId, session);
+            }
+            catch (err) {
+                logger.error(`[session] forgetting revoked identity slice ${parsed.id} for ${chatId} failed: ${err.message}`);
+            }
+        }
+        if (options.onIdentityShared) {
+            try {
+                await options.onIdentityShared(parsed.kind === "decline"
+                    ? { kind: "decline", id: parsed.id, askId: parsed.askId, from: senderId, chatId }
+                    : { kind: "revoke", id: parsed.id, from: senderId, chatId });
+            }
+            catch (err) {
+                logger.error(`[chat ${chatId}] onIdentityShared (${parsed.kind}) failed: ${err.message}`);
+            }
+        }
+    }
+    async function handleMessage(body, headerAgentId) {
         const message = body.message;
         const chatId = message.chat_id;
         const chatMeta = body.chat;
@@ -260,15 +828,50 @@ function createWebhookServer(options) {
             return;
         if (message.event_type)
             return; // system events aren't prompts
-        const ciphertext = message.message;
-        if (typeof ciphertext !== "string" || !PGP_MESSAGE_RE.test(ciphertext))
-            return;
-        const resolved = await resolveIdentity(ciphertext);
-        if (!resolved) {
-            logger.error(`[chat ${chatId}] no known identity could decrypt this message; ignoring.`);
+        const rawMessage = message.message;
+        if (typeof rawMessage !== "string")
             return;
+        // Open rooms (salt-api 0.6x): a plain chat delivers `encrypted: false`
+        // and `message` is the text itself, not a PGP blob -- there is nothing
+        // to trial-decrypt, and no way to recover which hosted identity this
+        // delivery was addressed to except the header salt-api signs every
+        // callback with. Without it (a header-less transport, or a header
+        // naming an identity this process doesn't host) there is no safe
+        // fallback the way trial-decryption gives the ciphertext path below --
+        // guessing would risk this identity replying as if it heard a message
+        // that was actually addressed to a sibling identity sharing this
+        // process.
+        const isPlaintext = message.encrypted === false;
+        let identity;
+        let caption;
+        if (isPlaintext) {
+            const preferred = headerAgentId ? identities.get(headerAgentId) : undefined;
+            if (!preferred) {
+                logger.error(`[chat ${chatId}] no known identity for this plaintext message (X-Salt-Agent-Id ${headerAgentId ?? "missing"}); ignoring.`);
+                return;
+            }
+            identity = preferred;
+            caption = rawMessage;
+        }
+        else {
+            if (!PGP_MESSAGE_RE.test(rawMessage))
+                return;
+            const resolved = await resolveIdentity(rawMessage, headerAgentId);
+            if (!resolved) {
+                logger.error(`[chat ${chatId}] no known identity could decrypt this message; ignoring.`);
+                return;
+            }
+            identity = resolved.identity;
+            caption = resolved.plaintext;
         }
-        let { identity, plaintext: caption } = resolved;
+        // Wire protocol, never a prompt: a hand-off briefing is consumed by
+        // handleHandoffReceived's poll (above HANDOFF_BRIEFING_MARKER's
+        // definition), and a bare session-note line is consumed by whichever
+        // hand-off leg reads it back out (sessions.ts). Either one reaching
+        // onMessage reads to a viewer as this identity replying to its own
+        // colleague's internal handoff chatter.
+        if (caption.startsWith(exports.HANDOFF_BRIEFING_MARKER) || caption.startsWith(sessions.SESSION_NOTE_MARKER))
+            return;
         // GACM routing fix: salt-api sends one webhook delivery PER agent
         // member, but they all land on this shared server and message-id dedup
         // collapses them into a single pass -- whose decrypt-resolved identity
@@ -277,51 +880,180 @@ function createWebhookServer(options) {
         // THAT identity; the plaintext is identical under any key, only "who
         // replies" changes.
         if (chatMeta?.active_agent_id) {
-            const active = identities.get(parseInt(String(chatMeta.active_agent_id), 10));
+            const active = identities.get(String(chatMeta.active_agent_id));
             if (active)
                 identity = active;
         }
+        // A message with no sender is not a prompt, and everything below -- the
+        // self-reply loop break, the delegation-reply match, the agent-to-agent
+        // cap -- is a question about who sent it. This used to fall through with
+        // senderId = NaN, which compared equal to nothing and unequal to
+        // everything, so all three guards inverted rather than being skipped. The
+        // context handed to consumers already asserted a sender existed.
         const senderRaw = message.user;
-        const senderId = senderRaw ? parseInt(String(senderRaw.id), 10) : NaN;
+        if (!senderRaw)
+            return;
+        const senderId = String(senderRaw.id);
         // Reply to a pending delegation call? Hand it to that waiting promise
         // instead of starting a fresh reply cycle -- see delegations.ts.
         if (delegations.resolveIfPending(chatId, senderId, caption))
             return;
+        // The answer to a pending ctx.ask, typed rather than tapped? Settle
+        // that wait instead of starting a fresh reply cycle -- see ask.ts.
+        // Only a human's plain reply counts (an agent addressed by handle
+        // gets its own webhook/turn, same reasoning as the mention-gating
+        // below); `caption` is the raw decrypted text, same as delegations'
+        // check just above.
+        if (asks.resolveMessage(identity.saltAppId, chatId, senderId, senderRaw.account_type !== "Agent", caption))
+            return;
         // Never reply to our own messages (the reply we post is itself
         // delivered back to us as a webhook) -- this is what prevents an
         // infinite loop.
-        if (senderId === identity.saltAppId)
+        if ((0, ids_js_1.sameId)(senderId, identity.saltAppId))
+            return;
+        // A device lane is wire protocol, not conversation: hand it to the device
+        // hook before any conversational gate can drop it (see onDeviceLaneMessage).
+        if (chatMeta?.lane_kind === "device" && options.onDeviceLaneMessage) {
+            try {
+                Promise.resolve(options.onDeviceLaneMessage({ identity, chatId, senderId, sender: senderRaw, text: caption, chatMeta })).catch((err) => {
+                    logger.error(`[chat ${chatId}] onDeviceLaneMessage failed: ${err.message}`);
+                });
+            }
+            catch (err) {
+                logger.error(`[chat ${chatId}] onDeviceLaneMessage failed: ${err.message}`);
+            }
+            return;
+        }
+        // request_floor (actions.ts): the consulted agent is asking to be
+        // brought into the room directly instead of relaying further through
+        // this lane. Wire protocol, never a prompt -- and only actionable by
+        // whichever hosted identity actually opened this lane as the asker.
+        if (caption.startsWith(delegations.FLOOR_REQUEST_MARKER)) {
+            const asker = delegations.consultAskerFor(chatId);
+            if (asker && (0, ids_js_1.sameId)(asker.askerId, identity.saltAppId)) {
+                const reason = caption.slice(delegations.FLOOR_REQUEST_MARKER.length).replace(/^\n/, "").trim() || undefined;
+                pendingConsultHandoffs.set(mapKey(asker.roomId), chatId);
+                try {
+                    await client.handOff(identity.apiKey, asker.roomId, senderId, reason);
+                }
+                catch (err) {
+                    pendingConsultHandoffs.delete(mapKey(asker.roomId));
+                    logger.error(`[chat ${asker.roomId}] auto hand-off on floor request failed: ${err.message}`);
+                }
+            }
+            return;
+        }
+        // Identity (R3/R4, identityShare.ts): a SALT-IDENTITY-ASK/SLICE/
+        // DECLINE/REVOKE is wire protocol, never a prompt -- with one
+        // deliberate exception. An ASK with no onIdentityAsk handler registered
+        // is NOT intercepted at all: it falls through as an ordinary message,
+        // marker stripped, so a consumer that hasn't wired up the handler yet
+        // sees whatever text (if any) rode alongside it rather than losing the
+        // message outright. SLICE/DECLINE/REVOKE are always intercepted,
+        // whether or not onIdentityShared is set -- there is no "ordinary
+        // text" reading of a signed slice or a revoke.
+        if (caption.startsWith(identityShare.IDENTITY_MARKER_PREFIX)) {
+            const parsed = identityShare.parseIdentityMarker(caption);
+            if (parsed?.kind === "ask") {
+                if (options.onIdentityAsk) {
+                    await handleIdentityAsk(identity, chatId, senderId, parsed);
+                    return;
+                }
+                caption = parsed.text || "";
+            }
+            else if (parsed) {
+                await handleIdentitySharedMarker(identity, chatId, senderId, parsed);
+                return;
+            }
+            else {
+                // Starts with the prefix but didn't parse into anything usable --
+                // a garbled or foreign marker either way, never a prompt.
+                return;
+            }
+        }
+        // Cancel (work.ts's [[SALT-WORK-CANCEL id=...]]): the person cancelling
+        // a scheduled report of theirs, sent as a whole message into the lane
+        // that report was posted into. Wire protocol, never a prompt -- always
+        // intercepted, whether or not onWorkCancel is set, same as a SLICE/
+        // DECLINE/REVOKE above (there's no "ordinary text" reading of it).
+        const cancelWorkId = (0, work_1.parseWorkCancel)(caption);
+        if (cancelWorkId) {
+            if (options.onWorkCancel) {
+                const cancelRoomId = chatMeta?.coaching_for_chat_id || chatId;
+                try {
+                    await options.onWorkCancel({ identity, workId: cancelWorkId, chatId: cancelRoomId, laneId: chatId, sender: senderRaw });
+                }
+                catch (err) {
+                    logger.error(`[chat ${chatId}] onWorkCancel failed: ${err.message}`);
+                }
+            }
             return;
+        }
         // Mediated Chat: this identity is the configured Mediator, and this
         // message is in the SHARED chat it silently observes -- present for
         // context, but it only actually speaks in each human's own private
         // coaching chat (coaching_for_chat_id pointing back at this one).
-        const isMediator = !!mediatorAgentId && identity.saltAppId === mediatorAgentId;
+        const isMediator = !!mediatorAgentId && (0, ids_js_1.sameId)(identity.saltAppId, mediatorAgentId);
         if (isMediator && chatMeta?.mediator_agent_id && !chatMeta.coaching_for_chat_id)
             return;
         // Global Agent Chat Mode: when the chat declares an active agent and
         // it isn't this identity, stay silent. Lets retired/handed-off-from
         // agents remain in the room without ever double-replying.
-        if (chatMeta?.active_agent_id && String(chatMeta.active_agent_id) !== String(identity.saltAppId))
+        if (chatMeta?.active_agent_id && !(0, ids_js_1.sameId)(chatMeta.active_agent_id, identity.saltAppId))
             return;
         // A human sender always resets the count -- only agent-to-agent
         // volleys are capped, never a real conversation with a person.
-        const senderIsAgent = !!identities.get(senderId) || senderRaw?.account_type === "Agent";
+        const senderIsAgent = !!identities.get(senderId) || senderRaw.account_type === "Agent";
+        const replyCountKey = mapKey(chatId);
+        if (chatMeta?.coaching_for_chat_id) {
+            laneRoomOf.set(replyCountKey, mapKey(chatMeta.coaching_for_chat_id));
+        }
         if (senderIsAgent) {
-            const count = (agentToAgentReplyCounts.get(chatId) || 0) + 1;
-            agentToAgentReplyCounts.set(chatId, count);
-            if (count > MAX_AGENT_TO_AGENT_REPLIES_PER_CHAT) {
-                logger.error(`[chat ${chatId}] agent-to-agent reply cap reached; not auto-replying to ${senderId} again.`);
-                return;
+            // A real person changes the rule entirely: an agent-authored message
+            // is only ours to answer when it @mentions us -- the same gate
+            // salt-api applies to whether the webhook is even sent in a group
+            // chat, belt-and-suspenders for whatever still reaches us (a hand-off
+            // farewell, a briefing after item 1 above missed a variant, another
+            // agent's aside). Two agents alone in a lane have no one to perform
+            // for, so the runaway cap below still governs those exactly as before.
+            if (await chatHasNonObserverHuman(identity, chatId, chatMeta)) {
+                const mentions = (Array.isArray(message.mentions) ? message.mentions : []).map(String);
+                if (!mentions.some((id) => (0, ids_js_1.sameId)(id, identity.saltAppId))) {
+                    logger.error(`[chat ${chatId}] agent message not addressed to us in a chat with a person present; not auto-replying to ${senderId}.`);
+                    return;
+                }
+            }
+            else {
+                const limit = chatMeta?.lane_kind === "consult" ? CONSULT_RUNAWAY_LIMIT : MAX_AGENT_TO_AGENT_REPLIES_PER_CHAT;
+                const count = (agentToAgentReplyCounts.get(replyCountKey) || 0) + 1;
+                agentToAgentReplyCounts.set(replyCountKey, count);
+                if (count > limit) {
+                    logger.error(`[chat ${chatId}] agent-to-agent reply cap reached; not auto-replying to ${senderId} again.`);
+                    return;
+                }
             }
         }
         else {
-            agentToAgentReplyCounts.delete(chatId);
+            agentToAgentReplyCounts.delete(replyCountKey);
+            // A human speaking in a ROOM also resets every consult lane rooted
+            // there -- otherwise a lane capped mid-conversation stays capped even
+            // right after the person who asked for it weighs in.
+            for (const [laneKey, roomKey] of laneRoomOf) {
+                if (roomKey === replyCountKey)
+                    agentToAgentReplyCounts.delete(laneKey);
+            }
         }
-        const { depth, text: strippedCaption } = delegations.parseIncoming(caption);
+        const { depth, text: afterDepthMarker } = delegations.parseIncoming(caption);
+        const strippedCaption = delegations.stripConsultMarker(afterDepthMarker);
         let mediatorSharedContext;
         let attachment;
-        if (isMediator && chatMeta?.coaching_for_chat_id) {
+        // The shared conversation is fetched only for the MUTUAL Mediator lane,
+        // where this identity is an observer on that chat and both parties can see
+        // it is there. A private advisor lane is excluded: that advisor was never
+        // added to the shared chat, so every message would fail to decrypt and be
+        // skipped anyway -- but a guarantee that rests on a failed decrypt is one
+        // membership bug away from being no guarantee, so we do not ask at all.
+        if (isMediator && chatMeta?.coaching_for_chat_id && !chatMeta.private_lane) {
             mediatorSharedContext = await buildSharedChatContext(identity, chatMeta.coaching_for_chat_id);
         }
         else if (message.resource_type === "Attachment") {
@@ -329,20 +1061,63 @@ function createWebhookServer(options) {
         }
         if (!options.onMessage)
             return;
+        const roomId = chatMeta?.coaching_for_chat_id || chatId;
+        const session = await loadOrRebuildSession(identity, chatId, chatMeta);
+        // Wraps the shared reply() closure to also remember what was sent, so
+        // it can be appended to the session as an assistant turn once the
+        // handler returns successfully -- see the persistence step below.
+        // Nothing about what actually gets sent changes.
+        const repliesForSession = [];
+        const baseReply = makeReply(identity, chatId, senderRaw);
+        const trackedReply = async (text) => {
+            repliesForSession.push(text);
+            await baseReply(text);
+        };
         const ctx = {
             identity,
             chatId,
             senderId,
             sender: senderRaw,
             text: strippedCaption,
+            encrypted: !isPlaintext,
+            deliveredBecause: parseDeliveredBecause(message.delivered_because),
+            replyTo: message.reply_to_message_id != null ? String(message.reply_to_message_id) : undefined,
+            parent: parseReplyParent(message.parent),
             delegationDepth: depth,
             chatMeta,
+            roomId,
             mediatorSharedContext,
             attachment,
-            reply: makeReply(identity, chatId),
+            session,
+            reply: trackedReply,
+            messageId: message.message_id,
+            react: (emoji) => client.react(identity.apiKey, message.message_id, emoji),
+            // M2: default answerer is whoever sent THIS message -- never an
+            // agent (an agent sender has its own webhook/turn; ctx.ask is for
+            // asking a person).
+            ask: makeAsk(identity, chatId, senderRaw.account_type !== "Agent" ? senderId : undefined),
+            approve: makeApprove(identity, chatId, senderRaw.account_type !== "Agent" ? senderId : undefined),
+            shareIdentity: makeShareIdentity(identity, chatId),
         };
         try {
             await withTypingHeartbeat(identity, chatId, () => Promise.resolve(options.onMessage(ctx)));
+            try {
+                sessions.appendTurn(session, {
+                    role: "user",
+                    content: strippedCaption,
+                    at: Date.now(),
+                    from: String(senderRaw.username || senderRaw.display_name || senderId),
+                });
+                for (const replyText of repliesForSession) {
+                    sessions.appendTurn(session, { role: "assistant", content: replyText, at: Date.now() });
+                }
+                session.note = sessions.boundNote(session.note);
+                session.updatedAt = Date.now();
+                await sessionStore.put(identity.saltAppId, chatId, session);
+            }
+            catch (err) {
+                logger.error(`[session] persisting ${chatId} failed: ${err.message}`);
+            }
         }
         catch (err) {
             logger.error(`[chat ${chatId}] onMessage failed: ${err.message}`);
@@ -352,9 +1127,19 @@ function createWebhookServer(options) {
         }
     }
     async function handleCardInteraction(body) {
-        const identity = identities.get(parseInt(String(body.owner_id), 10));
+        // A tap answering a pending ctx.ask's own card is wire-level bookkeeping
+        // for ask.ts, never something the consumer's onCardInteraction should
+        // also see -- checked before identity resolution/onCardInteraction even
+        // matter, since this can settle an ask() with no consumer handler
+        // registered for cards at all.
+        if (asks.resolveCardInteraction(body.owner_id, body.chat_id, body.card_id, body.action_id, body.user))
+            return;
+        const identity = identities.get(String(body.owner_id));
         if (!identity || !options.onCardInteraction)
             return;
+        // No reply() on this context (a card update IS the response), so just
+        // load -- nothing new here to append or persist afterward.
+        const session = await loadOrRebuildSession(identity, body.chat_id);
         try {
             await options.onCardInteraction({
                 identity,
@@ -363,17 +1148,67 @@ function createWebhookServer(options) {
                 actionId: body.action_id,
                 user: body.user,
                 blocks: body.state?.blocks,
+                values: body.values || {},
+                session,
             });
         }
         catch (err) {
             logger.error(`[chat ${body.chat_id}] onCardInteraction failed: ${err.message}`);
         }
     }
+    async function handleAppAction(body, headerAgentId) {
+        // No owner_id/seller_id in this body to fall back on (unlike
+        // card_interaction/invoice_paid) -- X-Salt-Agent-Id is the only signal,
+        // same as the mandate rail events further down. verifyEnvelope already
+        // proved the signature against that exact identity's own key.
+        const identity = headerAgentId != null ? identities.get(String(headerAgentId)) : undefined;
+        if (!identity || !options.onAppAction)
+            return;
+        const chatId = body.chat_id ?? null;
+        // A personal ("Your apps") installation has no chat at all -- nothing
+        // for a reply to post into, same as salt.post's "Not in a chat."
+        // rejection on the bridge side. Fails soft (logged), the same
+        // convention every other reply() failure in this file follows.
+        const reply = chatId != null
+            ? makeReply(identity, chatId)
+            : async (_text) => {
+                logger.error(`[app ${body.installation_id}] reply() has no chat -- this is a personal installation.`);
+            };
+        const ctx = {
+            identity,
+            installationId: body.installation_id,
+            app: body.app,
+            chatId,
+            text: body.text,
+            data: body.data,
+            stateVersion: body.state_version,
+            sender: body.user,
+            reply,
+        };
+        try {
+            if (chatId != null) {
+                await withTypingHeartbeat(identity, chatId, () => Promise.resolve(options.onAppAction(ctx)));
+            }
+            else {
+                await options.onAppAction(ctx);
+            }
+        }
+        catch (err) {
+            logger.error(`[app ${body.installation_id}] onAppAction failed: ${err.message}`);
+        }
+    }
     async function handleInvoicePaid(body) {
-        const identity = identities.get(parseInt(String(body.seller_id), 10));
+        const identity = identities.get(String(body.seller_id));
         if (!identity || !body.chat_id || !options.onInvoicePaid)
             return;
         const chatId = body.chat_id;
+        const session = await loadOrRebuildSession(identity, chatId);
+        const repliesForSession = [];
+        const baseReply = makeReply(identity, chatId);
+        const trackedReply = async (text) => {
+            repliesForSession.push(text);
+            await baseReply(text);
+        };
         const ctx = {
             identity,
             chatId,
@@ -382,30 +1217,143 @@ function createWebhookServer(options) {
             amount: body.amount,
             isTopUp: !!body.billing_account_id,
             transferRequestId: body.transfer_request_id,
-            reply: makeReply(identity, chatId),
+            session,
+            reply: trackedReply,
+            // M2: default answerer is the buyer (never an agent -- an agent
+            // buyer has no need to be asked a question through its own purchase).
+            ask: makeAsk(identity, chatId, body.buyer.account_type !== "Agent" ? body.buyer.id : undefined),
+            approve: makeApprove(identity, chatId, body.buyer.account_type !== "Agent" ? body.buyer.id : undefined),
+            shareIdentity: makeShareIdentity(identity, chatId),
         };
         try {
             await withTypingHeartbeat(identity, chatId, () => Promise.resolve(options.onInvoicePaid(ctx)));
+            await persistSessionAfterReply(identity.saltAppId, chatId, session, repliesForSession);
         }
         catch (err) {
             logger.error(`[chat ${chatId}] onInvoicePaid failed: ${err.message}`);
         }
     }
+    async function handleChatOpened(body) {
+        if (!options.onChatOpened)
+            return;
+        const chat = body.chat;
+        const chatId = chat?.id;
+        if (chatId == null)
+            return;
+        // Unlike card_interaction/invoice_paid, this payload carries no explicit
+        // owner/seller id naming which hosted identity it's for -- salt-api
+        // delivers it once per member with a callback URL, same as everything
+        // else, but the only way this process (which can host several identities
+        // on one endpoint) learns WHICH of its identities the event is about is
+        // by noticing itself in the member list. Prefer the chat's declared
+        // active agent when that's one of ours (GACM), the same tie-break
+        // handleMessage uses, in case delegation ever puts two hosted identities
+        // in the same chat.
+        let identity;
+        if (chat?.active_agent_id)
+            identity = identities.get(String(chat.active_agent_id));
+        if (!identity) {
+            for (const member of body.members || []) {
+                identity = identities.get(String(member.id));
+                if (identity)
+                    break;
+            }
+        }
+        if (!identity) {
+            logger.error(`[chat ${chatId}] chat_opened: no hosted identity found among members; ignoring.`);
+            return;
+        }
+        if (alreadyGreeted(identity.saltAppId, chatId))
+            return;
+        const session = await loadOrRebuildSession(identity, chatId, chat);
+        const repliesForSession = [];
+        const baseReply = makeReply(identity, chatId);
+        const trackedReply = async (text) => {
+            repliesForSession.push(text);
+            await baseReply(text);
+        };
+        const ctx = {
+            identity,
+            chatId,
+            chat: chat,
+            encrypted: chat?.encrypted !== false,
+            openedBy: body.opened_by,
+            members: body.members || [],
+            openedAt: body.opened_at,
+            session,
+            reply: trackedReply,
+            // M2: default answerer is whoever opened the chat (never an agent).
+            ask: makeAsk(identity, chatId, body.opened_by?.account_type !== "Agent" ? body.opened_by?.id : undefined),
+            approve: makeApprove(identity, chatId, body.opened_by?.account_type !== "Agent" ? body.opened_by?.id : undefined),
+            shareIdentity: makeShareIdentity(identity, chatId),
+        };
+        try {
+            await withTypingHeartbeat(identity, chatId, () => Promise.resolve(options.onChatOpened(ctx)));
+            await persistSessionAfterReply(identity.saltAppId, chatId, session, repliesForSession);
+        }
+        catch (err) {
+            logger.error(`[chat ${chatId}] onChatOpened failed: ${err.message}`);
+        }
+    }
     async function handleHandoffConfirmed(body) {
-        const identity = identities.get(parseInt(String(body.from_agent_id), 10));
+        const identity = identities.get(String(body.from_agent_id));
         if (!identity || !options.onHandoffConfirmed)
             return;
         const chatId = body.chat_id;
-        const ctx = { identity, chatId, reason: body.reason, reply: makeReply(identity, chatId) };
+        // A request_floor call may have just auto-triggered this same hand-off
+        // (webhook.ts's floor-request handler, above) -- if so, give the
+        // briefing its consult lane's transcript.
+        const laneId = pendingConsultHandoffs.get(mapKey(chatId));
+        if (laneId)
+            pendingConsultHandoffs.delete(mapKey(chatId));
+        let consultTranscript;
+        if (laneId) {
+            try {
+                consultTranscript = await buildConsultTranscript(identity, laneId);
+            }
+            catch (err) {
+                logger.error(`[chat ${chatId}] fetching consult transcript for hand-off failed: ${err.message}`);
+            }
+        }
+        const session = await loadOrRebuildSession(identity, chatId);
+        // Appends the outgoing session's note (if any) as the briefing's final
+        // wire-protocol line -- see sessions.ts's SESSION_NOTE_MARKER and
+        // handleHandoffReceived below, which parses it back out on the other
+        // end. Transparent to the consumer: whatever text they reply() with is
+        // what a human sees; this just rides along after it. Reads `session.note`
+        // directly rather than re-fetching -- the same object ctx.session is, so
+        // a handler that wrote to it before calling reply() is picked up.
+        const repliesForSession = [];
+        const baseReply = makeReply(identity, chatId);
+        const reply = async (text) => {
+            repliesForSession.push(text);
+            const noteLine = sessions.formatSessionNoteLine(session.note);
+            await baseReply(noteLine ? `${text}\n${noteLine}` : text);
+        };
+        const ctx = {
+            identity,
+            chatId,
+            reason: body.reason,
+            consultTranscript,
+            session,
+            reply,
+            // M2: no natural default here (a hand-off has no single "whoever
+            // this answers") -- ask()/approve() from this context must be given
+            // answererId explicitly, or they throw synchronously.
+            ask: makeAsk(identity, chatId),
+            approve: makeApprove(identity, chatId),
+            shareIdentity: makeShareIdentity(identity, chatId),
+        };
         try {
             await withTypingHeartbeat(identity, chatId, () => Promise.resolve(options.onHandoffConfirmed(ctx)));
+            await persistSessionAfterReply(identity.saltAppId, chatId, session, repliesForSession);
         }
         catch (err) {
             logger.error(`[chat ${chatId}] onHandoffConfirmed failed: ${err.message}`);
         }
     }
     async function handleHandoffReceived(body) {
-        const identity = identities.get(parseInt(String(body.to_agent_id), 10));
+        const identity = identities.get(String(body.to_agent_id));
         if (!identity || !options.onHandoffReceived)
             return;
         const chatId = body.chat_id;
@@ -421,44 +1369,397 @@ function createWebhookServer(options) {
                 break;
             await new Promise((r) => setTimeout(r, 2000));
         }
-        const ctx = { identity, chatId, reason: body.reason, context, reply: makeReply(identity, chatId) };
+        // Seed this identity's own session for `chatId` from whatever's already
+        // stored (a fresh one if nothing is), fold in the outgoing agent's note
+        // if the briefing carried one, and persist that much right away --
+        // independent of whether onHandoffReceived itself succeeds below, same
+        // as before this session had a `session` field on its ctx at all.
+        // Stripped from `context` either way: wire protocol, never something
+        // the incoming agent's own prompt-building should see verbatim.
+        let session;
+        try {
+            session = (await sessionStore.get(identity.saltAppId, chatId)) ?? sessions.emptySession(chatId, chatId);
+        }
+        catch (err) {
+            logger.error(`[session] loading ${chatId} failed: ${err.message}`);
+            session = sessions.emptySession(chatId, chatId);
+        }
+        const note = sessions.extractSessionNote(context);
+        if (note) {
+            session.note = sessions.boundNote(note);
+            session.updatedAt = Date.now();
+            try {
+                await sessionStore.put(identity.saltAppId, chatId, session);
+            }
+            catch (err) {
+                logger.error(`[session] persisting handed-off note for ${chatId} failed: ${err.message}`);
+            }
+        }
+        context = sessions.stripSessionNoteLines(context);
+        // Whatever the introduction reply() sends here is appended below,
+        // exactly like onMessage does for its own reply -- so it's already in
+        // transcriptTail the next time this chat's onMessage runs.
+        const repliesForSession = [];
+        const baseReply = makeReply(identity, chatId);
+        const trackedReply = async (text) => {
+            repliesForSession.push(text);
+            await baseReply(text);
+        };
+        const ctx = {
+            identity,
+            chatId,
+            reason: body.reason,
+            context,
+            session,
+            reply: trackedReply,
+            // M2: no natural default here either -- see HandoffConfirmedContext's comment above.
+            ask: makeAsk(identity, chatId),
+            approve: makeApprove(identity, chatId),
+            shareIdentity: makeShareIdentity(identity, chatId),
+        };
         try {
             await withTypingHeartbeat(identity, chatId, () => Promise.resolve(options.onHandoffReceived(ctx)));
+            await persistSessionAfterReply(identity.saltAppId, chatId, session, repliesForSession);
         }
         catch (err) {
             logger.error(`[chat ${chatId}] onHandoffReceived failed: ${err.message}`);
         }
     }
-    async function dispatch(body) {
+    // Resolves which of this process's hosted identities a mandate/exercise event is FOR. The
+    // envelope's X-Salt-Agent-Id is authoritative (verifyEnvelope already checked the signature
+    // against that exact identity's own key, so it names a real recipient) -- the `candidateIds`
+    // fallback (party ids off the payload itself) only matters for a caller that runs the dispatcher
+    // directly with no header (e.g. a test, or a future transport that doesn't have one).
+    function resolveMandateIdentity(headerAgentId, ...candidateIds) {
+        if (headerAgentId != null) {
+            const byHeader = identities.get(String(headerAgentId));
+            if (byHeader)
+                return byHeader;
+        }
+        for (const id of candidateIds) {
+            if (id == null)
+                continue;
+            const found = identities.get(String(id));
+            if (found)
+                return found;
+        }
+        return undefined;
+    }
+    async function handleMandateOffered(body, headerAgentId) {
+        const identity = resolveMandateIdentity(headerAgentId, body.mandate?.grantee?.id);
+        if (!identity || !options.onMandateOffered)
+            return;
+        const mandate = body.mandate;
+        const ctx = {
+            identity,
+            mandate,
+            accept: () => client.mandates.accept(identity.apiKey, mandate.id),
+        };
+        try {
+            await options.onMandateOffered(ctx);
+        }
+        catch (err) {
+            logger.error(`[mandate ${mandate.id}] onMandateOffered failed: ${err.message}`);
+        }
+    }
+    async function handleMandateLifecycleEvent(kind, body, headerAgentId) {
+        const mandate = body.mandate;
+        const identity = resolveMandateIdentity(headerAgentId, mandate?.grantee?.id, mandate?.grantor?.id);
+        const handler = kind === "activated" ? options.onMandateActivated : kind === "paused" ? options.onMandatePaused : options.onMandateRevoked;
+        if (!identity || !handler)
+            return;
+        try {
+            await handler({ identity, mandate });
+        }
+        catch (err) {
+            logger.error(`[mandate ${mandate.id}] onMandate${kind[0].toUpperCase()}${kind.slice(1)} failed: ${err.message}`);
+        }
+    }
+    async function handleApprovalRequested(body, headerAgentId) {
+        const exercise = body.exercise;
+        const identity = resolveMandateIdentity(headerAgentId, exercise?.principal?.id);
+        if (!identity || !options.onApprovalRequested)
+            return;
+        const ctx = {
+            identity,
+            exercise,
+            decide: (decision, note) => client.mandates.decide(identity.apiKey, exercise.id, decision, note),
+        };
+        try {
+            await options.onApprovalRequested(ctx);
+        }
+        catch (err) {
+            logger.error(`[exercise ${exercise.id}] onApprovalRequested failed: ${err.message}`);
+        }
+    }
+    async function handleApprovalDecided(body, headerAgentId) {
+        const exercise = body.exercise;
+        const identity = resolveMandateIdentity(headerAgentId, exercise?.actor?.id);
+        if (!identity || !options.onApprovalDecided)
+            return;
+        try {
+            await options.onApprovalDecided({ identity, exercise });
+        }
+        catch (err) {
+            logger.error(`[exercise ${exercise.id}] onApprovalDecided failed: ${err.message}`);
+        }
+    }
+    async function handleDeviceSessionEnded(body, headerAgentId) {
+        if (!options.onDeviceSessionEnded)
+            return;
+        const identity = resolveMandateIdentity(headerAgentId, body.agent_id);
+        if (!identity)
+            return;
+        // The same delivery also goes to the computer itself; it is not the agent's to speak of.
+        if ((0, ids_js_1.sameId)(identity.saltAppId, body.device_id))
+            return;
+        const sessionId = body.session_id ?? body.id;
+        if (sessionId == null)
+            return;
+        const ctx = {
+            identity,
+            sessionId,
+            deviceId: body.device_id,
+            mandateId: body.mandate_id ?? null,
+            laneChatId: body.chat_id ?? body.chat?.id ?? null,
+            endReason: body.end_reason ?? null,
+            lostContact: body.end_reason === exports.DEVICE_LOST_CONTACT,
+            intent: typeof body.intent === "string" ? body.intent : null,
+            endedAt: body.ended_at ?? null,
+            body,
+        };
+        try {
+            await options.onDeviceSessionEnded(ctx);
+        }
+        catch (err) {
+            logger.error(`[device session ${sessionId}] onDeviceSessionEnded failed: ${err.message}`);
+        }
+    }
+    async function handleDeviceBack(body, headerAgentId) {
+        if (!options.onDeviceBack)
+            return;
+        const identity = resolveMandateIdentity(headerAgentId);
+        if (!identity)
+            return;
+        const chatId = body.chat_id ?? null;
+        const session = chatId != null ? await loadOrRebuildSession(identity, chatId) : null;
+        const repliesForSession = [];
+        const baseReply = chatId != null ? makeReply(identity, chatId) : null;
+        const ctx = {
+            identity,
+            deviceId: body.device_id,
+            deviceName: body.device_name,
+            previousSessionId: body.previous_session_id,
+            offlineAt: body.offline_at ?? null,
+            backAt: body.back_at,
+            chatId,
+            session,
+            body,
+            reply: async (text) => {
+                if (!baseReply)
+                    throw new Error("device_back: the person has no 1:1 with this agent (chat_id is null), so there is nowhere to reply");
+                repliesForSession.push(text);
+                await baseReply(text);
+            },
+        };
+        try {
+            await options.onDeviceBack(ctx);
+            if (chatId != null && session)
+                await persistSessionAfterReply(identity.saltAppId, chatId, session, repliesForSession);
+        }
+        catch (err) {
+            logger.error(`[device ${body.device_id}] onDeviceBack failed: ${err.message}`);
+        }
+    }
+    async function handleDescribeYourself(body, headerAgentId) {
+        const agent = (body.agent ?? {});
+        const identity = resolveMandateIdentity(headerAgentId, agent?.id);
+        if (!identity || !options.onDescribeYourself)
+            return;
+        const maxLength = typeof body.max_length === "number" ? body.max_length : 300;
+        const ctx = {
+            identity,
+            reason: String(body.reason ?? "created"),
+            agent,
+            ownerDescription: typeof body.owner_description === "string" ? body.owner_description : null,
+            currentDescription: typeof body.current_description === "string" ? body.current_description : null,
+            capabilities: Array.isArray(body.capabilities) ? body.capabilities : [],
+            guidance: String(body.guidance ?? ""),
+            maxLength,
+            write: async (text) => {
+                const bio = String(text ?? "").replace(/\s+/g, " ").trim().slice(0, maxLength);
+                if (!bio)
+                    return;
+                await client.setIdentity(identity.apiKey, { bio });
+            },
+        };
+        try {
+            await options.onDescribeYourself(ctx);
+        }
+        catch (err) {
+            logger.error(`[agent ${agent?.id}] onDescribeYourself failed: ${err.message}`);
+        }
+    }
+    // Answers to a pending ctx.ask (or a pending delegation reply), resolved
+    // WITHOUT running a handler. socket.ts feeds frames through one serial
+    // queue, and the handler that called `await ctx.ask(...)` occupies it, so
+    // the frame carrying the answer would wait behind the very handler that is
+    // waiting for it. socket.ts therefore calls this at frame arrival, ahead
+    // of the queue. Same checks, same order as handleMessage /
+    // handleCardInteraction (which still run for anything this does not
+    // consume), so nothing is answered by a sender those would not accept.
+    // Returns true when the frame was consumed and must not be dispatched.
+    async function resolveAnswer(body, headerAgentId) {
+        if (!asks.hasPendingAsks())
+            return false;
+        if (body?.type === "card_interaction") {
+            const b = body;
+            return asks.resolveCardInteraction(b.owner_id, b.chat_id, b.card_id, b.action_id, b.user);
+        }
+        if (body?.type !== undefined || !body?.message)
+            return false;
+        const message = body.message;
+        if (message.event_type)
+            return false;
+        const rawMessage = message.message;
+        if (typeof rawMessage !== "string")
+            return false;
+        const chatId = message.chat_id;
+        let identity;
+        let caption;
+        if (message.encrypted === false) {
+            identity = headerAgentId ? identities.get(headerAgentId) : undefined;
+            caption = rawMessage;
+        }
+        else {
+            if (!PGP_MESSAGE_RE.test(rawMessage))
+                return false;
+            const resolved = await resolveIdentity(rawMessage, headerAgentId);
+            identity = resolved?.identity;
+            caption = resolved?.plaintext ?? "";
+        }
+        if (!identity)
+            return false;
+        const activeId = body.chat?.active_agent_id;
+        if (activeId)
+            identity = identities.get(String(activeId)) ?? identity;
+        const senderRaw = message.user;
+        if (!senderRaw)
+            return false;
+        const senderId = String(senderRaw.id);
+        if (delegations.resolveIfPending(chatId, senderId, caption))
+            return true;
+        return asks.resolveMessage(identity.saltAppId, chatId, senderId, senderRaw.account_type !== "Agent", caption);
+    }
+    async function dispatch(body, headerAgentId) {
         if (body?.type === "card_interaction")
             return handleCardInteraction(body);
+        if (body?.type === "app_action")
+            return handleAppAction(body, headerAgentId);
         if (body?.type === "invoice_paid")
             return handleInvoicePaid(body);
+        if (body?.type === "chat_opened")
+            return handleChatOpened(body);
         if (body?.type === "handoff_confirmed")
             return handleHandoffConfirmed(body);
         if (body?.type === "handoff_received")
             return handleHandoffReceived(body);
+        if (body?.type === "mandate_offered")
+            return handleMandateOffered(body, headerAgentId);
+        if (body?.type === "mandate_activated")
+            return handleMandateLifecycleEvent("activated", body, headerAgentId);
+        if (body?.type === "mandate_paused")
+            return handleMandateLifecycleEvent("paused", body, headerAgentId);
+        if (body?.type === "mandate_revoked")
+            return handleMandateLifecycleEvent("revoked", body, headerAgentId);
+        if (body?.type === "approval_requested")
+            return handleApprovalRequested(body, headerAgentId);
+        if (body?.type === "approval_decided")
+            return handleApprovalDecided(body, headerAgentId);
+        if (body?.type === "describe_yourself")
+            return handleDescribeYourself(body, headerAgentId);
+        // device_session_ended and device_back are the AGENT's moments and must stay
+        // ahead of the device_session* catch-all below. device_session_ended also
+        // goes on to onDeviceDelivery (set only by a process that hosts a device):
+        // the session controller there needs the end too, and handleDeviceSessionEnded
+        // itself ignores the device's own copy.
+        if (body?.type === "device_session_ended") {
+            await handleDeviceSessionEnded(body, headerAgentId);
+            await options.onDeviceDelivery?.(body.type, body);
+            return;
+        }
+        if (body?.type === "device_back")
+            return handleDeviceBack(body, headerAgentId);
+        if (typeof body?.type === "string" && (body.type.startsWith("device_session") || body.type === "device_queue" || body.type === "device_grants_changed" || body.type === "device_owner_changed" || body.type === "device_ask_answered")) {
+            await options.onDeviceDelivery?.(body.type, body);
+            return;
+        }
         if (body?.message)
-            return handleMessage(body);
+            return handleMessage(body, headerAgentId);
     }
+    return { dispatch, verifyEnvelope, resolveAnswer };
+}
+/**
+ * Creates the Express app for a Salt agent's webhook endpoint. Mount it
+ * yourself (e.g. `createWebhookServer(opts).listen(port)`, or grab `.app`
+ * to compose it into a bigger server).
+ *
+ * A thin transport wrapper around createDispatcher -- everything about the
+ * Salt protocol itself lives there. Switching a consumer from this to
+ * socket.ts's createSocketClient (K2, an agent with no public URL) is the
+ * same `options` object with `.listen(port)` replaced by `.start()`;
+ * onMessage/onCardInteraction/etc. never change.
+ */
+function createWebhookServer(options) {
+    const logger = options.logger ?? consoleLogger;
+    const dispatcher = createDispatcher(options);
+    const app = (0, express_1.default)();
+    // Keep the raw bytes: the HMAC covers exactly what salt-api sent, and
+    // re-serialising the parsed object would digest different bytes (key order,
+    // whitespace, number formatting) and never match.
+    app.use(express_1.default.json({
+        verify: (req, _res, buf) => {
+            req.rawBody = buf.toString("utf8");
+        },
+    }));
+    app.get("/health", (_req, res) => {
+        res.json({
+            status: "ok",
+            identities: options.identities.all().map((i) => ({ salt_app_id: i.saltAppId, username: i.username })),
+            ...(options.healthExtra ? options.healthExtra() : {}),
+        });
+    });
     // salt-api's WebhookJob POSTs here with { chat, message } (or a typed
-    // event body for card/invoice/handoff). Ack immediately (200) and process
-    // in the background so a slow agent-loop call can't make Salt's webhook
-    // delivery time out.
+    // event body for card/invoice/chat_opened/handoff). Ack immediately (200)
+    // and process in the background so a slow agent-loop call can't make
+    // Salt's webhook delivery time out.
     //
-    // WEBHOOK_SHARED_SECRET: when this server is publicly reachable, anyone
-    // can POST here. Encrypted-message webhooks fail safe (forged ciphertext
-    // never decrypts), but card_interaction/invoice_paid payloads are
-    // PLAINTEXT and would be acted on -- so when the secret is configured
-    // (production), every POST must carry the matching header salt-api's
-    // jobs send. Unset (local dev), the check is skipped entirely.
+    // When this server is publicly reachable, anyone can POST here. Encrypted-
+    // message webhooks fail safe (forged ciphertext never decrypts), but
+    // card_interaction/invoice_paid/chat_opened payloads are PLAINTEXT and
+    // would be acted on -- so every POST must carry a valid HMAC signed with
+    // the RECIPIENT identity's own key (see Dispatcher#verifyEnvelope above).
     app.post("/", (req, res) => {
-        if (webhookSharedSecret && req.get("X-Salt-Webhook-Secret") !== webhookSharedSecret) {
-            res.status(401).json({ error: "invalid webhook secret" });
-            return;
-        }
-        res.status(200).json({ status: "accepted" });
-        dispatch(req.body).catch((err) => logger.error(`[webhook] unhandled error: ${err.message}`));
+        const rawBody = req.rawBody ?? "";
+        // Verify BEFORE acknowledging: an unsigned POST must never reach dispatch,
+        // because card_interaction/invoice_paid/chat_opened are plaintext and
+        // actionable.
+        dispatcher
+            .verifyEnvelope(req.get("X-Salt-Agent-Id") || undefined, req.get("X-Salt-Signature") || undefined, rawBody)
+            .then((result) => {
+            if (!result.ok) {
+                logger.error(`[webhook] rejected: ${result.reason}`);
+                res.status(401).json({ error: "invalid signature" });
+                return;
+            }
+            res.status(200).json({ status: "accepted" });
+            const headerAgentId = req.get("X-Salt-Agent-Id") || undefined;
+            dispatcher.dispatch(req.body, headerAgentId).catch((err) => logger.error(`[webhook] unhandled error: ${err.message}`));
+        })
+            .catch((err) => {
+            logger.error(`[webhook] verification failed: ${err.message}`);
+            res.status(401).json({ error: "invalid signature" });
+        });
     });
     return {
         app,