@sigrun/ext-gateway 0.0.0-stage → 0.1.2

package/dist/inbound/pipeline.js

@@ -0,0 +1,600 @@
+/**
+ * The inbound pipeline (spec §8.4): one `receive` runs the ordered
+ * steps. Task 3 landed steps 2 (dedupe), 3 (self/bot drops), 6 (album
+ * merge) and 10 (submit) plus the M12 submit-error outcomes; Task 4
+ * fills step 1 (the claimed gate), step 4 (self-link) and step 5 (the
+ * DM access policies) INLINE over the shared {@link AccessState} — the
+ * access stores are engine-wide (one pairing queue, one link-code
+ * table, one token table, one loop guard), so the engine builds the
+ * state and hands it to every channel's pipeline. Steps 7 (commands),
+ * 8 (interaction answers) and 9 (attachments) remain INJECTABLE STAGES
+ * (`PipelineDeps.stages`) filled by their own tasks — the design keeps
+ * the step ORDER in one place while each task lands its logic.
+ *
+ * The channel's config is read LIVE per event by the CALLER (the
+ * engine's `receive` wrapper reads `readConfig(host)` and passes the
+ * channel's block in) — every field except `enabled` is per-event.
+ *
+ * On admission the pipeline records `submissionId → { bindingKey,
+ * channel }` in `deps.origins` (the in-memory map the outbound tasks
+ * consume — which chat a run came from, so settled answers route).
+ *
+ * The notice/error replies go through `deps.channel.send` — the
+ * adapter-bound transport, host-independent (the loopback fixture's
+ * `sent` array records them, which is how the sigrun e2e asserts reply
+ * text). A failed notice send is logged, never thrown: the submit
+ * error already resolved the event's fate.
+ */
+import { join } from "node:path";
+import { buildEnvelope } from "./envelope.js";
+import { AlbumCollector, ALBUM_WINDOW_MS } from "./albums.js";
+import { bindingKey, BindingStore } from "../state/bindings.js";
+import { SeenSet } from "../state/seen.js";
+import { IdentityStore } from "../state/identities.js";
+import { PairingStore } from "../access/pairing.js";
+import { LinkCodes } from "../access/link-codes.js";
+import { LoopGuard } from "../access/loop-guard.js";
+import { ButtonTokens } from "./tokens.js";
+import { normalizeCode } from "../access/codes.js";
+import { redeemLink } from "../commands/link.js";
+import { approvePairing, denyPairing } from "../commands/pair.js";
+import { handleChatCommand } from "../commands/chat.js";
+import { admitGroupEvent, ensureGroupShare } from "./groups.js";
+/** The pinned UnservedModelError notice (spec §8.4 M12, exact copy). */
+const UNSERVED_MODEL_NOTICE = "The model <ref> is not available. Use /model to pick another.";
+/** The pinned group refusal for `/link` (spec §8.2, exact copy). */
+const LINK_GROUP_REFUSAL = "send this in a direct message";
+/** Build a private access state over `stateDir` (the no-`access` shape). */
+function privateAccess(host, stateDir, now, log) {
+    return {
+        identities: new IdentityStore(host, join(stateDir, "identities.json"), { log }),
+        pairing: new PairingStore(join(stateDir, "pairing.json"), { now }),
+        linkCodes: new LinkCodes(),
+        tokens: new ButtonTokens(),
+        loopGuard: new LoopGuard(),
+    };
+}
+export function createPipeline(deps) {
+    const now = deps.now ?? Date.now;
+    // The engine hands ONE store in (every pipeline, the settled fan-out
+    // and the delivery workers share it — cross-instance writes would
+    // interleave separate JsonFile queues and lose updates); the
+    // stand-alone shape constructs its own.
+    const bindings = deps.bindings ??
+        new BindingStore(join(deps.stateDir, "bindings.json"), { now });
+    const seen = new SeenSet(join(deps.stateDir, "seen.json"));
+    const access = deps.access ??
+        privateAccess(deps.host, deps.stateDir, () => now(), deps.log);
+    const albums = new AlbumCollector(now, ALBUM_WINDOW_MS);
+    // Per-group close timers (the album window's flush).
+    const albumTimers = new Map();
+    // The open groups' submission metadata, keyed by the same timer key:
+    // a flush (stopIntake) needs everything a receive would have carried.
+    const openAlbums = new Map();
+    const receivePipeline = async (channelId, event, config) => {
+        const key = bindingKey(channelId, event.chat);
+        const seenId = `${key}:${event.messageId}`;
+        // Step 1 — the claimed gate (§8.2): an unclaimed deployment has
+        // no users to act for; every event drops with ONE log line per
+        // channel (the state can flip mid-process — the check is per
+        // event, not cached at start).
+        if ((await deps.host.users.list()).length === 0) {
+            deps.log.once(`unclaimed:${channelId}`, "warn", `setup unclaimed — dropping inbound (channel "${channelId}")`);
+            return dropped();
+        }
+        // Step 2 — dedupe (in-flight-aware: a racing redelivery claims
+        // false and drops; an engine failure releases for the retry).
+        if (!seen.claim(seenId, now())) {
+            return dropped();
+        }
+        try {
+            return await admit(channelId, event, key, config);
+        }
+        catch (error) {
+            // An unexpected throw is an ENGINE failure: release the seen id
+            // (the platform redelivers) and reject — the adapter does not
+            // ack, so the message is retried rather than lost.
+            seen.release(seenId);
+            throw error;
+        }
+    };
+    /** The pipeline past the dedupe claim. */
+    async function admit(channelId, event, key, config) {
+        // Step 3 — self and bot drops. An ADMITTED bot rides the loop
+        // guard (§8.2: 10 per chat per 60000 ms, then a 300000 ms
+        // cooldown) — a chatty integration must never monopolize the run
+        // queue or echo itself into a loop.
+        if (event.fromSelf === true)
+            return dropped();
+        if (event.sender.isBot === true) {
+            if (!config.allowBots)
+                return dropped();
+            if (!access.loopGuard.admit(key, now())) {
+                deps.log.once(`loop-guard:${key}`, "warn", "bot loop guard tripped — bot messages on this chat drop for 5 minutes");
+                return dropped();
+            }
+        }
+        // Step 4 — self-link (`/link <code>`, §8.2): handled BEFORE
+        // access — the code IS the authorization, so the sender may be
+        // unknown here. Only when the channel's `selfLink` is on; a
+        // selfLink-off channel leaves `/link` to the access policy (an
+        // allowlist channel's operator chose a closed list).
+        if (config.selfLink && isLinkCommand(event.text)) {
+            if (event.chat.chatType !== "dm") {
+                // The code was exposed to other members (M9): void it, then
+                // refuse. The refusal is exact (the plan pins the string).
+                access.linkCodes.invalidate(normalizeCode(event.text.replace(/^\/link\s*/, "")));
+                await sendNotice(event.chat, LINK_GROUP_REFUSAL, undefined);
+                return { outcome: "command" };
+            }
+            const reply = await redeemLink({
+                identities: access.identities,
+                linkCodes: access.linkCodes,
+                log: deps.log,
+                now,
+            }, channelId, event);
+            await sendNotice(event.chat, reply, undefined);
+            return { outcome: "command" };
+        }
+        // Step 5 — access (§8.2). Groups read their row from the live
+        // config per event; removing a row stops admission without
+        // deleting the chat's durable binding (Review Focus 3).
+        let user;
+        let commandUser;
+        let owner;
+        let group;
+        let senderLabel = event.sender.name ?? event.sender.id;
+        if (event.chat.chatType !== "dm") {
+            const admission = await admitGroupEvent(config, channelId, event, access.identities);
+            if (!admission.admit) {
+                if (admission.reason === "unlisted" || admission.reason === "failed") {
+                    deps.log.once(`group-${admission.reason}:${channelId}:${event.chat.chatId}`, "warn", `group message dropped (${admission.reason}, channel "${channelId}")`);
+                }
+                else if (admission.reason === "unlinked") {
+                    const day = Math.floor(now() / 86_400_000);
+                    deps.log.once(`group-unlinked:${channelId}:${event.sender.id}:${day}`, "warn", `group message from unlinked sender dropped (channel "${channelId}")`);
+                }
+                return dropped();
+            }
+            user = admission.user;
+            // Unlinked anyone senders submit under the owner but never
+            // control the conversation or invoke commands (§8.2).
+            commandUser = admission.linked ? admission.user : undefined;
+            owner = admission.group.owner;
+            group = admission.group;
+            if (admission.linked) {
+                const directoryUser = await deps.host.users.get(admission.user);
+                senderLabel = directoryUser?.name ?? admission.user;
+            }
+            else {
+                senderLabel = admission.senderLabel;
+            }
+        }
+        else {
+            const resolved = await access.identities.userFor(config, channelId, event.sender.id);
+            if (resolved === undefined) {
+                return await unknownDm(channelId, event, config);
+            }
+            user = resolved.user;
+            commandUser = user;
+            owner = user;
+            // An allowlisted identity has no link row to seed the home DM.
+            // Record this DM as the channel home when none exists so tools
+            // and notices have the same target as linked identities.
+            if (access.identities.homesOf(user).every((home) => home.channel !== channelId)) {
+                // Keep admission ordered, especially for album siblings: only
+                // the first writer installs the home; no async write here.
+                // Album siblings can race this first-home write; keep the
+                // synchronous check/update ordering and await durability.
+                void access.identities.ensureHome(user, channelId, event.chat)
+                    .catch((error) => {
+                    deps.log.error("home chat persistence failed", error);
+                });
+            }
+        }
+        // The bound conversation, or a fresh one for an unbound chat.
+        const binding = bindings.get(key);
+        if (binding?.dead) {
+            await bindings.clearDead(key);
+        }
+        let conversationId;
+        if (binding === undefined) {
+            conversationId = (await deps.host.conversations.create({
+                owner,
+                source: "gateway",
+                name: event.chat.title ??
+                    `${deps.channel.label} ${group === undefined ? "DM" : "group"}`,
+                ...(group?.members !== "anyone"
+                    ? {}
+                    : {
+                        agent: {
+                            tools: group.tools,
+                            ...(group.extensions === undefined
+                                ? {}
+                                : { extensions: group.extensions }),
+                        },
+                    }),
+            }));
+            await bindings.bind(key, conversationId, event.chat);
+        }
+        else {
+            conversationId = binding.conversationId;
+            // An archived conversation unarchives before submit (spec
+            // §8.3's my-call: archiving never silently breaks a chat).
+            const meta = await deps.host.conversations.meta(conversationId);
+            if (meta.archived) {
+                await deps.host.conversations.patchMeta(conversationId, {
+                    archived: false,
+                });
+            }
+        }
+        if (group !== undefined && commandUser !== undefined) {
+            await ensureGroupShare(deps.host, conversationId, commandUser);
+        }
+        // Step 7 — commands run INLINE (§8.5), before album merging and
+        // the busy submission queue. A first-message command acts on the
+        // binding admission just created, not on the earlier snapshot.
+        // created, not on the pre-creation `undefined` snapshot.
+        const currentBinding = bindings.get(key) ?? binding;
+        const command = await handleChatCommand({
+            host: deps.host,
+            channel: deps.channel,
+            bindings,
+            identities: access.identities,
+            pairing: access.pairing,
+            linkCodes: access.linkCodes,
+            streams: deps.streams,
+            channelOf: (id) => deps.channelOf?.(id) ?? (id === channelId ? deps.channel : undefined),
+            log: deps.log,
+            now,
+        }, {
+            channel: channelId,
+            event,
+            bindingKey: key,
+            user: commandUser,
+            binding: currentBinding,
+            selfLink: config.selfLink,
+            ...(group === undefined ? {} : { group }),
+        });
+        if (command === "command") {
+            await seen.commit(`${key}:${event.messageId}`, now());
+            return { outcome: "command" };
+        }
+        // Step 8 — interaction text answers (injected; Task 9 fills).
+        const interaction = await deps.stages?.interactionAnswer?.(channelId, event);
+        if (interaction !== undefined) {
+            await seen.commit(`${key}:${event.messageId}`, now());
+            return interaction;
+        }
+        // Step 6 — the album merge: a group's events become ONE
+        // submission when the window closes; a plain event is its own.
+        const envelopeText = buildEnvelope(event, {
+            group: group !== undefined,
+            senderLabel,
+        });
+        const batch = albums.add(key, event, envelopeText);
+        if (batch === undefined) {
+            // Collecting: commit seen NOW (the events ARE admitted — a
+            // platform redelivery of a held sibling is a no-op). A SIGKILL
+            // before the window closes loses this submission by design;
+            // graceful stopIntake flushes it, and redelivery dedupes safely.
+            // Arm the close timer that submits the merged batch.
+            await seen.commit(`${key}:${event.messageId}`, now());
+            scheduleAlbumClose(channelId, key, event, user, conversationId, config);
+            return { outcome: "admitted" };
+        }
+        // Step 10 — submit.
+        return await submit(channelId, event, key, conversationId, user, batch, config);
+    }
+    /** Step 5's unknown-DM branch: the channel's `dm` policy (§8.2). */
+    async function unknownDm(channelId, event, config) {
+        if (config.dm === "disabled") {
+            // Silent: no reply, no log (the operator turned DMs off —
+            // a log line per stranger would be noise, not signal).
+            return dropped();
+        }
+        if (config.dm === "allowlist") {
+            // Drop, logged once per sender per day (the day bucket in the
+            // key; a restart re-logs once — the honest per-process bound).
+            const day = Math.floor(now() / 86_400_000);
+            deps.log.once(`dm-drop:${channelId}:${event.sender.id}:${day}`, "warn", `dm from unknown sender dropped (channel "${channelId}")`);
+            return dropped();
+        }
+        // `pairing`: one request, one reply carrying the code, admin
+        // notices — and the message itself is NEVER submitted, then or
+        // after approval (§8.2).
+        const result = access.pairing.request(channelId, { id: event.sender.id, name: event.sender.name }, event.chat, now());
+        if ("limited" in result) {
+            // No reply on a limit (§8.2): a reply would be an oracle for a
+            // probing sender. The drop is logged once per sender.
+            deps.log.once(`pairing-limited:${channelId}:${event.sender.id}`, "info", `pairing request over limit (${result.limited}, channel "${channelId}")`);
+            return dropped();
+        }
+        await sendNotice(event.chat, `Your pairing code is ${result.code}. An admin will approve it — ` +
+            "until then your messages are not processed.", undefined);
+        await notifyAdmins(channelId, event, result.code, config);
+        return dropped();
+    }
+    /** The pairing notice to every effective admin's home DM (§8.2). */
+    async function notifyAdmins(channelId, event, code, config) {
+        void config;
+        const users = await deps.host.users.list();
+        const admins = users.filter((row) => row.admin === true || row.groupAdmin === true);
+        if (admins.length === 0)
+            return;
+        const who = event.sender.name ?? event.sender.id;
+        const text = `Pairing request from ${who} on ${deps.channel.label}.\n` +
+            `/pair approve ${code} <user>\n` +
+            `/pair deny ${code}`;
+        // Buttons when they fit: one "Approve as <user>" per DIRECTORY
+        // user plus Deny, within `buttons.max` (the max-1 bound leaves
+        // room for the Deny row entry). Too many users → text only.
+        const caps = deps.channel.capabilities.buttons;
+        const rows = caps === undefined || users.length > caps.max - 1
+            ? undefined
+            : [
+                [
+                    ...users.map((row) => ({
+                        label: `Approve as ${row.user}`,
+                        data: access.tokens.issue({
+                            kind: "pair",
+                            code,
+                            decision: "approve",
+                            user: row.user,
+                        }),
+                        style: "primary",
+                    })),
+                    {
+                        label: "Deny",
+                        data: access.tokens.issue({
+                            kind: "pair",
+                            code,
+                            decision: "deny",
+                        }),
+                        style: "danger",
+                    },
+                ],
+            ];
+        for (const admin of admins) {
+            // §8.8: an admin's home chats are always DMs; the notice rides
+            // THIS channel's adapter, so only this channel's homes get it.
+            for (const home of access.identities.homesOf(admin.user)) {
+                if (home.channel !== channelId)
+                    continue;
+                await sendNotice(home.chat, text, rows);
+            }
+        }
+    }
+    /** Step 10: the submit + the M12 error outcomes. */
+    async function submit(channelId, event, key, conversationId, user, batch, config) {
+        const text = batch.texts.join("\n");
+        const media = deps.stages?.attachments === undefined
+            ? { parts: [], notes: [] }
+            : await deps.stages.attachments({ ...event, attachments: batch.attachments });
+        // A media-only event submits its notes, not an empty text block.
+        const textParts = [
+            ...(text === "" ? [] : [{ type: "text", text }]),
+            ...media.notes.map((note) => ({ type: "text", text: note })),
+        ];
+        const parts = [...media.parts, ...textParts];
+        // Host submission rejects an empty input array; preserve an empty
+        // attachment-less event as an empty text part.
+        if (parts.length === 0)
+            parts.push({ type: "text", text });
+        const opts = {
+            user,
+            requestId: `${key}:${event.messageId}`,
+            whenBusy: config.busy,
+        };
+        const origin = {
+            bindingKey: key,
+            channel: channelId,
+            chat: event.chat,
+        };
+        let ownsStream = false;
+        if (deps.streams !== undefined) {
+            try {
+                // Open BEFORE submit: a fast provider may publish its first (or
+                // only) live frame before submit's promise resolves.
+                ownsStream = await deps.streams.open(conversationId, origin);
+            }
+            catch (error) {
+                // Admission must still proceed when only the preview cannot open.
+                deps.log.error("stream open failed", error);
+            }
+        }
+        try {
+            const record = await deps.host.conversations.submit(conversationId, parts, opts);
+            await seen.commit(`${key}:${event.messageId}`, now());
+            deps.origins.set(record.id, origin);
+            return { outcome: "admitted" };
+        }
+        catch (error) {
+            if (ownsStream)
+                deps.streams?.abandon(conversationId);
+            if (error instanceof Error &&
+                error.name === "UnservedModelError") {
+                // The pinned notice with the ref interpolated (M12). Named
+                // by `name`, never `instanceof` across the types-only
+                // contract (the error class ships in sigrun's runtime, not
+                // the extension types).
+                const ref = unservedModelRef(error);
+                // Commit seen BEFORE the notice: the idempotency record
+                // must be durable before the fallible network write — a
+                // commit failure after a sent notice would make the
+                // platform redeliver into a duplicate submit + duplicate
+                // notice.
+                await seen.commit(`${key}:${event.messageId}`, now());
+                await sendNotice(event.chat, UNSERVED_MODEL_NOTICE.replace("<ref>", ref), undefined);
+                return dropped();
+            }
+            if (error instanceof Error &&
+                error.name === "ConversationOpError") {
+                // A short notice + the error code logged (M12).
+                const code = conversationOpCode(error);
+                deps.log.error(`submit failed (conversation ${String(conversationId)}, code "${code}")`, error);
+                // Commit seen BEFORE the notice (the same ordering as the
+                // UnservedModelError branch: idempotency first, network second).
+                await seen.commit(`${key}:${event.messageId}`, now());
+                await sendNotice(event.chat, "Could not deliver that message. Try again in a moment.", undefined);
+                return dropped();
+            }
+            throw error;
+        }
+    }
+    /** Send one notice reply through the adapter (errors logged, never thrown). */
+    async function sendNotice(chat, text, buttons) {
+        const message = {
+            chat,
+            text,
+            ...(buttons === undefined ? {} : { buttons }),
+        };
+        try {
+            await deps.channel.send(message);
+        }
+        catch (error) {
+            deps.log.error("notice send failed", error);
+        }
+    }
+    /** Arm the album-close timer for a collecting group (one per group). */
+    function scheduleAlbumClose(channelId, key, event, user, conversationId, config) {
+        if (event.groupId === undefined)
+            return;
+        const timerKey = `${key}:${event.groupId}`;
+        if (albumTimers.has(timerKey))
+            return;
+        openAlbums.set(timerKey, {
+            channelId,
+            key,
+            groupId: event.groupId,
+            event,
+            user,
+            conversationId,
+            config,
+        });
+        const timer = setTimeout(() => {
+            albumTimers.delete(timerKey);
+            openAlbums.delete(timerKey);
+            const batch = albums.close(key, event.groupId ?? "");
+            if (batch.texts.length === 0)
+                return;
+            void submit(channelId, event, key, conversationId, user, batch, config)
+                .catch((error) => {
+                // The timer path has no receive to reject: an unexpected
+                // throw logs loud (the album's events are committed seen;
+                // the M12 classes already resolved their own outcome).
+                deps.log.error("album submit failed", error);
+            });
+        }, ALBUM_WINDOW_MS);
+        albumTimers.set(timerKey, timer);
+    }
+    /**
+     * Flush every open album window NOW and submit its merged batch —
+     * the engine's `stopIntake` calls this so a shutdown inside the
+     * 1500 ms window never loses a collected album (its events are
+     * already committed seen; without this flush the platform's
+     * redelivery would be a dedupe no-op, permanently dropping them).
+     *
+     * Every submission settles before this resolves; an unexpected
+     * throw on one album is logged (the flush still drains the rest —
+     * one failed album must not strand the others at shutdown).
+     */
+    async function flushAlbums() {
+        for (const timer of albumTimers.values())
+            clearTimeout(timer);
+        albumTimers.clear();
+        const pending = [...openAlbums.values()];
+        openAlbums.clear();
+        await Promise.all(pending.map(async (album) => {
+            const batch = albums.close(album.key, album.groupId);
+            if (batch.texts.length === 0)
+                return;
+            try {
+                await submit(album.channelId, album.event, album.key, album.conversationId, album.user, batch, album.config);
+            }
+            catch (error) {
+                deps.log.error("album flush submit failed", error);
+            }
+        }));
+    }
+    // The tap handler (§8.7 button tokens): a pair decision needs an
+    // EFFECTIVE admin tapper (C8) — the tapper's platform identity maps
+    // through the same allowlist/links, then the directory record's
+    // admin flag or group grant decides. Everything else resolves
+    // quietly: a replayed/foreign token, an unknown sender, a plain
+    // user. The requester's "linked" notice rides `approvePairing`.
+    async function pipelineAction(channelId, event, config) {
+        const action = access.tokens.resolve(event.data);
+        if (action === undefined)
+            return;
+        const tapper = await access.identities.userFor(config, channelId, event.sender.id);
+        if (action.kind === "interaction") {
+            if (deps.interactionAnswer === undefined)
+                return;
+            if (action.field === undefined) {
+                deps.log.error("interaction token has no field; refusing to invent one");
+                return;
+            }
+            const reply = await deps.interactionAnswer({
+                conversationId: action.conversationId,
+                callId: action.callId,
+                values: { [action.field]: action.optionId },
+                user: tapper?.user,
+            });
+            await sendNotice(event.chat, reply, undefined);
+            return;
+        }
+        if (tapper === undefined) {
+            deps.log.once(`tap-unknown:${channelId}:${event.sender.id}`, "warn", "pairing button tap from an unknown sender ignored");
+            return;
+        }
+        const record = await deps.host.users.get(tapper.user);
+        if (record === undefined || (record.admin !== true && record.groupAdmin !== true)) {
+            deps.log.once(`tap-not-admin:${channelId}:${tapper.user}`, "warn", `pairing button tap by non-admin "${tapper.user}" ignored`);
+            return;
+        }
+        const pairDeps = {
+            host: deps.host,
+            identities: access.identities,
+            pairing: access.pairing,
+            channelOf: (id) => id === channelId ? deps.channel : undefined,
+            log: deps.log,
+            now,
+        };
+        if (action.decision === "deny") {
+            await denyPairing(pairDeps, action.code);
+            return;
+        }
+        if (action.user === undefined)
+            return;
+        await approvePairing(pairDeps, action.code, action.user);
+    }
+    // The flush + tap handles ride the returned receive function
+    // (properties, not a separate return shape — the engine holds the
+    // same callable it wires into every adapter's context).
+    receivePipeline.flushAlbums = flushAlbums;
+    receivePipeline.action = pipelineAction;
+    return receivePipeline;
+}
+/** Is `text` a `/link` invocation (with or without an argument)? */
+function isLinkCommand(text) {
+    return text === "/link" || text.startsWith("/link ");
+}
+/** Extract the `provider/modelId` ref from an UnservedModelError-like. */
+function unservedModelRef(error) {
+    const ref = error.ref;
+    if (ref?.provider !== undefined && ref.modelId !== undefined) {
+        return `${ref.provider}/${ref.modelId}`;
+    }
+    return "the configured model";
+}
+/** Extract the error code from a ConversationOpError-like. */
+function conversationOpCode(error) {
+    const body = error
+        .body;
+    return body?.error ?? error.message;
+}
+/** The dropped outcome. */
+function dropped() {
+    return { outcome: "dropped" };
+}

package/dist/inbound/tokens.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Button tokens (spec §8.7 §12 "opaque transport-private button
+ * tokens"): the opaque `data` strings the engine puts on chat buttons
+ * and resolves when a tap arrives. Opaque BY DESIGN — a token carries
+ * no readable decision, so a screenshot or log line leaks nothing an
+ * attacker could replay through a different chat.
+ *
+ * Single-use on resolve: a tap consumes its token, so a replayed tap
+ * (a double delivery, a copied message) is a no-op. In memory — a
+ * restart voids outstanding tokens, which only ever adorn live chat
+ * messages.
+ *
+ * Task 9 (chat interactions) mints the `kind: "interaction"` tokens
+ * through this same class: ONE table per engine, every button routes
+ * through it.
+ */
+/** What a button does when tapped. */
+export type TokenAction = {
+    readonly kind: "pair";
+    readonly code: string;
+    readonly decision: "approve" | "deny";
+    readonly user?: string;
+} | {
+    readonly kind: "interaction";
+    readonly conversationId: number;
+    readonly callId: string;
+    /** The root-form choice field (U6 records are not decision-specific). */
+    readonly field?: string;
+    readonly optionId: string;
+};
+/** The button-token table, one instance per engine. */
+export declare class ButtonTokens {
+    private readonly live;
+    /** Mint a token for `action` (the `data` a button carries). */
+    issue(action: TokenAction): string;
+    /** Resolve a tap: the action, consumed (undefined on replay). */
+    resolve(token: string): TokenAction | undefined;
+}

package/dist/inbound/tokens.js

@@ -0,0 +1,42 @@
+/**
+ * Button tokens (spec §8.7 §12 "opaque transport-private button
+ * tokens"): the opaque `data` strings the engine puts on chat buttons
+ * and resolves when a tap arrives. Opaque BY DESIGN — a token carries
+ * no readable decision, so a screenshot or log line leaks nothing an
+ * attacker could replay through a different chat.
+ *
+ * Single-use on resolve: a tap consumes its token, so a replayed tap
+ * (a double delivery, a copied message) is a no-op. In memory — a
+ * restart voids outstanding tokens, which only ever adorn live chat
+ * messages.
+ *
+ * Task 9 (chat interactions) mints the `kind: "interaction"` tokens
+ * through this same class: ONE table per engine, every button routes
+ * through it.
+ */
+import { randomInt } from "node:crypto";
+/** The token alphabet (RFC 4648 base32 — the Crockford-adjacent set). */
+const TOKEN_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+/** The pinned token body length (16 chars, `t:`-prefixed). */
+const TOKEN_LENGTH = 16;
+/** The button-token table, one instance per engine. */
+export class ButtonTokens {
+    live = new Map();
+    /** Mint a token for `action` (the `data` a button carries). */
+    issue(action) {
+        let body = "";
+        for (let i = 0; i < TOKEN_LENGTH; i++) {
+            body += TOKEN_ALPHABET[randomInt(TOKEN_ALPHABET.length)];
+        }
+        const token = `t:${body}`;
+        this.live.set(token, action);
+        return token;
+    }
+    /** Resolve a tap: the action, consumed (undefined on replay). */
+    resolve(token) {
+        const action = this.live.get(token);
+        if (action !== undefined)
+            this.live.delete(token);
+        return action;
+    }
+}