@mapier/imsg-sdk 0.1.0

package/dist/imsg/rpc.js

@@ -0,0 +1,227 @@
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { imsgBinary } from './binary.js';
+// One long-lived `imsg rpc` child. JSON-RPC 2.0, one object per line on
+// stdin/stdout; notifications (method: "message") carry watch events.
+export class ImsgRpc {
+    onMessage;
+    child;
+    nextId = 1;
+    pending = new Map();
+    stopping = false;
+    constructor(onMessage, onExit) {
+        this.onMessage = onMessage;
+        this.child = spawn(imsgBinary(), ['rpc'], { stdio: ['pipe', 'pipe', 'inherit'] });
+        const rl = createInterface({ input: this.child.stdout });
+        rl.on('line', (line) => this.handleLine(line));
+        this.child.on('exit', (code) => {
+            for (const p of this.pending.values())
+                p.reject(new Error('imsg rpc exited'));
+            this.pending.clear();
+            if (!this.stopping)
+                onExit(code);
+        });
+    }
+    handleLine(line) {
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            console.error('[rpc] unparseable line:', line.slice(0, 200));
+            return;
+        }
+        if (msg.id !== undefined) {
+            const p = this.pending.get(Number(msg.id));
+            if (!p)
+                return;
+            this.pending.delete(Number(msg.id));
+            if (msg.error)
+                p.reject(new Error(`imsg rpc ${msg.error.code}: ${msg.error.message}`));
+            else
+                p.resolve(msg.result);
+        }
+        else if (msg.method === 'message' && msg.params) {
+            this.onMessage(msg.params.message);
+        }
+    }
+    request(method, params) {
+        const id = this.nextId++;
+        const payload = JSON.stringify({ jsonrpc: '2.0', id, method, params: params ?? {} });
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve: resolve, reject });
+            this.child.stdin.write(`${payload}\n`);
+        });
+    }
+    // since_rowid is an exclusive cursor — pass the last rowid already handled.
+    async subscribe(sinceRowid) {
+        const res = await this.request('watch.subscribe', {
+            ...(sinceRowid ? { since_rowid: sinceRowid } : {}),
+            include_reactions: true,
+            attachments: true,
+        });
+        return res.subscription;
+    }
+    send(target, text) {
+        const params = 'chatId' in target ? { chat_id: target.chatId, text } : { to: target.to, text };
+        return this.request('send', params);
+    }
+    async history(chatId, limit = 30) {
+        const res = await this.request('messages.history', {
+            chat_id: chatId,
+            limit,
+            attachments: true,
+        });
+        // Order is not documented — normalize to oldest-first by rowid.
+        return [...res.messages].sort((a, b) => a.id - b.id);
+    }
+    async historyRange(chatId, options) {
+        const res = await this.request('messages.history', {
+            chat_id: chatId,
+            limit: options.limit ?? 500,
+            ...(options.startAt ? { start: options.startAt } : {}),
+            ...(options.endBefore ? { end: options.endBefore } : {}),
+            ...(options.includeAttachments ? { attachments: true } : {}),
+        });
+        const startMs = options.startAt ? new Date(options.startAt).getTime() : null;
+        const endMs = options.endBefore ? new Date(options.endBefore).getTime() : null;
+        return [...res.messages]
+            .filter((message) => {
+            if (!message.created_at)
+                return startMs === null && endMs === null;
+            const occurredAt = new Date(message.created_at).getTime();
+            return (startMs === null || occurredAt >= startMs) && (endMs === null || occurredAt < endMs);
+        })
+            .sort((a, b) => a.id - b.id);
+    }
+    // Verified live against imsg 0.12.0 (2026-07-02): `chats.list` accepts
+    // `{ limit }`, returns `{ chats }` ordered newest-first by last_message_at.
+    async chats(limit = 20) {
+        const res = await this.request('chats.list', { limit });
+        return res.chats;
+    }
+    // ---- Tier 2 (bridge-backed RPC methods — openclaw/imsg docs/rpc.md
+    // "Bridge Message Actions" + the `kSupportedRPCMethods` dispatch table in
+    // openclaw's RPCServer.swift). All target an existing chat_id; none has a
+    // find-or-create `to:` form the way send() does. ----
+    // `tapback`: message_guid/kind/remove params (RPCServer+BridgeMessageHandlers.swift
+    // handleTapback → normalizeBridgeReactionType). `kind` accepts our Reaction
+    // values directly — the normalizer takes "emphasis" as an alias for its
+    // canonical "emphasize" (and the other 5 names match verbatim) — and
+    // rejects anything outside the closed 6-type set. The patched fork's
+    // arbitrary-emoji parameter is exposed separately below.
+    tapback(chatId, targetGuid, reaction, remove = false) {
+        return this.request('tapback', { chat_id: chatId, message_guid: targetGuid, kind: reaction, remove });
+    }
+    // Mapier fork extension. The `emoji` parameter deliberately replaces
+    // `kind`; sending both would route through stock imsg's classic-6
+    // normalizer and reject the custom emoji.
+    emojiTapback(chatId, targetGuid, emoji, remove = false) {
+        return this.request('tapback', { chat_id: chatId, message_guid: targetGuid, emoji, remove });
+    }
+    // Verified against openclaw/imsg 0.13.x source: `send.rich` text mode takes
+    // text + optional subject/effect/reply_to (handleSendRich).
+    sendRich(chatId, text, opts = {}) {
+        return this.request('send.rich', {
+            chat_id: chatId,
+            text,
+            ...(opts.subject !== undefined ? { subject: opts.subject } : {}),
+            ...(opts.effect ? { effect: opts.effect } : {}),
+            ...(opts.replyToGuid ? { reply_to: opts.replyToGuid } : {}),
+        });
+    }
+    // Verified against openclaw/imsg 0.13.x source: `send.attachment`
+    // (handleSendAttachment) takes file, optional audio:true, and reply_to.
+    sendAttachment(chatId, filePath, opts = {}) {
+        return this.request('send.attachment', {
+            chat_id: chatId,
+            file: filePath,
+            ...(opts.audio ? { audio: true } : {}),
+            ...(opts.replyToGuid ? { reply_to: opts.replyToGuid } : {}),
+        });
+    }
+    // Wire shape transcribed from the Mapier fork's docs/rpc.md
+    // `message.send_status` response (mapier/macos26-tier2).
+    messageSendStatus(guid) {
+        return this.request('message.send_status', { guid });
+    }
+    // Wire shape transcribed from the Mapier fork's docs/rpc.md
+    // `handles.check` response (mapier/macos26-tier2).
+    checkHandle(address, opts = {}) {
+        return this.request('handles.check', {
+            address,
+            ...(opts.aliasType ? { alias_type: opts.aliasType } : {}),
+        });
+    }
+    // Wire shape transcribed from the Mapier fork's docs/rpc.md
+    // `send.sticker` response (mapier/macos26-tier2). part_index is invalid
+    // without attach_to, so it is omitted unless both are supplied.
+    sendSticker(chatId, filePath, opts = {}) {
+        return this.request('send.sticker', {
+            chat_id: chatId,
+            file: filePath,
+            ...(opts.attachToGuid ? { attach_to: opts.attachToGuid } : {}),
+            ...(opts.attachToGuid && opts.partIndex !== undefined ? { part_index: opts.partIndex } : {}),
+        });
+    }
+    // Verified against openclaw/imsg 0.13.x source: `poll.send`
+    // (handlePollSend) takes a question and at least two options.
+    sendPoll(chatId, question, options) {
+        return this.request('poll.send', { chat_id: chatId, question, options });
+    }
+    // Verified against openclaw/imsg 0.13.x source: `send.rich` URL mode
+    // (handleSendRichLink) accepts only the URL alongside the chat id.
+    sendRichLink(chatId, url) {
+        return this.request('send.rich', { chat_id: chatId, url });
+    }
+    // `message.edit`: text is required; backwards-compatibility text defaults
+    // to the same value when omitted (handleMessageEdit).
+    editMessage(chatId, targetGuid, text) {
+        return this.request('message.edit', { chat_id: chatId, message_guid: targetGuid, text });
+    }
+    unsendMessage(chatId, targetGuid) {
+        return this.request('message.unsend', { chat_id: chatId, message_guid: targetGuid });
+    }
+    deleteMessage(chatId, targetGuid) {
+        return this.request('message.delete', { chat_id: chatId, message_guid: targetGuid });
+    }
+    // `typing`/`read` (RPCServer+Handlers.swift handleTyping/handleRead) — no
+    // observable verification surface through the Gateway (contract §2).
+    setTyping(chatId, on) {
+        return this.request('typing', { chat_id: chatId, typing: on });
+    }
+    markRead(chatId) {
+        return this.request('read', { chat_id: chatId });
+    }
+    // `group.*` (RPCServer+ChatHandlers.swift) — all resolve chat_id/chat_guid/
+    // chat_identifier the same way as the other bridge methods.
+    renameGroup(chatId, name) {
+        return this.request('group.rename', { chat_id: chatId, name });
+    }
+    // Omitting `file` clears the photo (mirrors CLI `imsg chat-photo` with no
+    // `--file`).
+    setGroupPhoto(chatId, filePath) {
+        return this.request('group.setIcon', { chat_id: chatId, ...(filePath ? { file: filePath } : {}) });
+    }
+    addParticipant(chatId, handle) {
+        return this.request('group.addParticipant', { chat_id: chatId, address: handle });
+    }
+    removeParticipant(chatId, handle) {
+        return this.request('group.removeParticipant', { chat_id: chatId, address: handle });
+    }
+    leaveGroup(chatId) {
+        return this.request('group.leave', { chat_id: chatId });
+    }
+    namePhotoStatus(chatId) {
+        return this.request('contacts.shouldShareContact', { chat_id: chatId });
+    }
+    shareNamePhoto(chatId) {
+        return this.request('contacts.shareContactCard', { chat_id: chatId });
+    }
+    stop() {
+        this.stopping = true;
+        this.child.stdin.end();
+        this.child.kill();
+    }
+}
+//# sourceMappingURL=rpc.js.map

package/dist/imsg/rpc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc.js","sourceRoot":"","sources":["../../src/imsg/rpc.ts"],"names":[],"mappings":"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"}

package/dist/imsg/status.d.ts

@@ -0,0 +1,9 @@
+import type { GatewayCapabilities } from '../gateway/types.js';
+interface ImsgStatusPayload {
+    selectors?: Record<string, boolean>;
+    rpc_features?: string[];
+}
+export declare const NO_PATCHED_GATEWAY_CAPABILITIES: GatewayCapabilities;
+export declare function patchedCapabilitiesFromStatus(status: ImsgStatusPayload): GatewayCapabilities;
+export declare function readPatchedGatewayCapabilities(): GatewayCapabilities;
+export {};

package/dist/imsg/status.js

@@ -0,0 +1,37 @@
+import { execFileSync } from 'node:child_process';
+import { reportRuntimeIssue } from '../runtime-report.js';
+import { imsgBinary } from './binary.js';
+export const NO_PATCHED_GATEWAY_CAPABILITIES = {
+    emojiTapback: false,
+    stickerSend: false,
+    groupPhoto: false,
+    groupParticipants: false,
+    namePhotoSharing: false,
+};
+export function patchedCapabilitiesFromStatus(status) {
+    const selectors = status.selectors ?? {};
+    return {
+        emojiTapback: selectors.emojiTapbackSend === true && status.rpc_features?.includes('tapback.emoji') === true,
+        stickerSend: selectors.stickerSend === true,
+        groupPhoto: selectors.groupPhotoUpdate === true,
+        groupParticipants: selectors.groupAddParticipant === true && selectors.groupRemoveParticipant === true,
+        namePhotoSharing: selectors.namePhotoShouldOffer === true && selectors.namePhotoShare === true,
+    };
+}
+export function readPatchedGatewayCapabilities() {
+    try {
+        const stdout = execFileSync(imsgBinary(), ['status', '--json'], {
+            encoding: 'utf8',
+            timeout: 10_000,
+        });
+        return patchedCapabilitiesFromStatus(JSON.parse(stdout));
+    }
+    catch {
+        // Fail closed, but never silently: a probe failure downgrades the pod to
+        // stock-imsg capability, and an operator has to be able to see why every
+        // patched verb vanished. Closed code only — no ambient console here.
+        reportRuntimeIssue('imsg_capability_probe_failed');
+        return { ...NO_PATCHED_GATEWAY_CAPABILITIES };
+    }
+}
+//# sourceMappingURL=status.js.map

package/dist/imsg/status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../../src/imsg/status.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAOzC,MAAM,CAAC,MAAM,+BAA+B,GAAwB;IAClE,YAAY,EAAE,KAAK;IACnB,WAAW,EAAE,KAAK;IAClB,UAAU,EAAE,KAAK;IACjB,iBAAiB,EAAE,KAAK;IACxB,gBAAgB,EAAE,KAAK;CACxB,CAAC;AAEF,MAAM,UAAU,6BAA6B,CAAC,MAAyB;IACrE,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC;IACzC,OAAO;QACL,YAAY,EAAE,SAAS,CAAC,gBAAgB,KAAK,IAAI,IAAI,MAAM,CAAC,YAAY,EAAE,QAAQ,CAAC,eAAe,CAAC,KAAK,IAAI;QAC5G,WAAW,EAAE,SAAS,CAAC,WAAW,KAAK,IAAI;QAC3C,UAAU,EAAE,SAAS,CAAC,gBAAgB,KAAK,IAAI;QAC/C,iBAAiB,EAAE,SAAS,CAAC,mBAAmB,KAAK,IAAI,IAAI,SAAS,CAAC,sBAAsB,KAAK,IAAI;QACtG,gBAAgB,EAAE,SAAS,CAAC,oBAAoB,KAAK,IAAI,IAAI,SAAS,CAAC,cAAc,KAAK,IAAI;KAC/F,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,8BAA8B;IAC5C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,YAAY,CAAC,UAAU,EAAE,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE;YAC9D,QAAQ,EAAE,MAAM;YAChB,OAAO,EAAE,MAAM;SAChB,CAAC,CAAC;QACH,OAAO,6BAA6B,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAsB,CAAC,CAAC;IAChF,CAAC;IAAC,MAAM,CAAC;QACP,yEAAyE;QACzE,yEAAyE;QACzE,qEAAqE;QACrE,kBAAkB,CAAC,8BAA8B,CAAC,CAAC;QACnD,OAAO,EAAE,GAAG,+BAA+B,EAAE,CAAC;IAChD,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { FakeGateway } from './gateway/fake.js';
+export { ImsgGateway } from './gateway/imsg.js';
+export * from './gateway/types.js';
+export * from './gateway/portable-chat.js';
+export * from './gateway/external-ids.js';
+export * from './polls.js';
+export { reportRuntimeIssue, setRuntimeIssueReporter, type RuntimeIssueReporter } from './runtime-report.js';
+export type { MessageAttachment, MessagePoll, MessageReaction, PollOption, PollVote } from './types.js';
+export * from './interactions/index.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+export { FakeGateway } from './gateway/fake.js';
+export { ImsgGateway } from './gateway/imsg.js';
+export * from './gateway/types.js';
+export * from './gateway/portable-chat.js';
+export * from './gateway/external-ids.js';
+export * from './polls.js';
+export { reportRuntimeIssue, setRuntimeIssueReporter } from './runtime-report.js';
+export * from './interactions/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,cAAc,oBAAoB,CAAC;AACnC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,uBAAuB,EAA6B,MAAM,qBAAqB,CAAC;AAE7G,cAAc,yBAAyB,CAAC"}

package/dist/interactions/catalog.d.ts

@@ -0,0 +1,2 @@
+import { InteractionRegistry } from './registry.js';
+export declare function defaultCatalog(): InteractionRegistry;

package/dist/interactions/catalog.js

@@ -0,0 +1,98 @@
+// Today's honest inventory of interaction kinds. Every claim about OUR
+// Gateway is checked against docs/gateway-contract.md and docs/imsg-polls.md;
+// claims about external products (Photon, Linq) are cited but not verifiable
+// from this repo. See docs/interactions.md for the full citations and the
+// corrections made against earlier catalog drafts.
+import { InteractionRegistry } from './registry.js';
+const TAPBACK = {
+    id: 'tapback',
+    tier: 'native-balloon',
+    requiresRecipientInstall: false,
+    correlation: 'message-guid',
+    completionTransport: 'gateway-events',
+    outbound: 'agent',
+    inboundReadback: true,
+    status: 'host-smoked',
+    fallback: 'plain-text',
+    notes: 'Gateway.tapback (guid-targeted, bridge); react() has no guid param. Host-verified: tier2-smoke.ts.',
+};
+const WEB_LINK = {
+    id: 'web-link',
+    tier: 'web-surface',
+    requiresRecipientInstall: false,
+    correlation: 'link-code',
+    completionTransport: 'out-of-band',
+    outbound: 'agent',
+    inboundReadback: false,
+    status: 'host-smoked',
+    fallback: 'none', // this IS the floor — nothing to fall back to
+    notes: 'Completion via product store/webhook, not this SDK; verified in imsg-agent link-surface, not here.',
+};
+const POLL = {
+    id: 'poll',
+    tier: 'native-balloon',
+    requiresRecipientInstall: false,
+    correlation: 'message-guid',
+    completionTransport: 'gateway-events',
+    outbound: 'agent',
+    inboundReadback: true,
+    status: 'host-smoked',
+    fallback: 'plain-text',
+    notes: 'sendPoll creates only, host-verified delivering; voting has no Gateway path (forbidden surface).',
+};
+const EFFECT = {
+    id: 'effect',
+    tier: 'native-balloon',
+    requiresRecipientInstall: false,
+    correlation: 'none',
+    completionTransport: 'none',
+    outbound: 'agent',
+    inboundReadback: false,
+    status: 'host-smoked',
+    fallback: 'plain-text',
+    notes: 'Gateway.sendRich opts.effect already provides all 12 (4 bubble+8 screen); host-verified live.',
+};
+const RICH_LINK_CARD = {
+    id: 'rich-link-card',
+    tier: 'native-balloon',
+    requiresRecipientInstall: false,
+    correlation: 'none',
+    completionTransport: 'none',
+    outbound: 'none',
+    inboundReadback: false,
+    status: 'host-smoked',
+    fallback: 'plain-text',
+    notes: 'sendRichLink delivers on builds carrying the fork richlink-sync-fix (host-verified 2026-07-14); outbound stays none until the pinned release ships that patch — no capability marker gates it. See docs/interactions.md.',
+};
+const APP_CLIP = {
+    id: 'app-clip',
+    tier: 'app-clip',
+    requiresRecipientInstall: false, // App Clips are ephemeral — no App Store install
+    correlation: 'link-code',
+    completionTransport: 'out-of-band',
+    outbound: 'none',
+    inboundReadback: false,
+    status: 'unbuilt',
+    fallback: 'web-url',
+    notes: 'Linq Agent Pay model: link opens a native checkout sheet, no install. Unbuilt seam.',
+};
+const HOST_EXTENSION_CARD = {
+    id: 'host-extension-card',
+    tier: 'extension',
+    requiresRecipientInstall: true,
+    correlation: 'message-guid',
+    completionTransport: 'gateway-events',
+    outbound: 'none',
+    inboundReadback: false,
+    status: 'unbuilt',
+    fallback: 'web-url',
+    notes: 'Photon Spectrum model: install the host once, mini-app URLs render live in-bubble. Unbuilt seam.',
+};
+export function defaultCatalog() {
+    const registry = new InteractionRegistry();
+    for (const descriptor of [TAPBACK, WEB_LINK, POLL, EFFECT, RICH_LINK_CARD, APP_CLIP, HOST_EXTENSION_CARD]) {
+        registry.register(descriptor);
+    }
+    return registry;
+}
+//# sourceMappingURL=catalog.js.map

package/dist/interactions/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../../src/interactions/catalog.ts"],"names":[],"mappings":"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"}

package/dist/interactions/harness.d.ts

@@ -0,0 +1,25 @@
+import type { FakeGateway } from '../gateway/fake.js';
+import type { InteractionRegistry } from './registry.js';
+import type { InteractionCompletion } from './types.js';
+export interface PollCycleParams {
+    chatId: number;
+    question: string;
+    options: string[];
+    voter: {
+        sender: string;
+        senderName?: string;
+        optionIndexes: number[];
+    };
+}
+export interface PollVoteResponse {
+    optionIds: string[];
+    optionTexts: string[];
+}
+export declare class InteractionHarness {
+    private readonly fake;
+    private readonly registry;
+    constructor(fake: FakeGateway, registry: InteractionRegistry);
+    private requireBuilt;
+    drivePollCycle(params: PollCycleParams): InteractionCompletion<PollVoteResponse>;
+    driveLinkCompletion<R>(kind: string, code: string, response: R): InteractionCompletion<R>;
+}

package/dist/interactions/harness.js

@@ -0,0 +1,69 @@
+import { pollEventKind } from '../polls.js';
+export class InteractionHarness {
+    fake;
+    registry;
+    constructor(fake, registry) {
+        this.fake = fake;
+        this.registry = registry;
+    }
+    requireBuilt(kind) {
+        const descriptor = this.registry.get(kind);
+        if (!descriptor)
+            throw new Error(`InteractionHarness: unknown interaction kind "${kind}"`);
+        if (descriptor.status === 'unbuilt') {
+            throw new Error(`InteractionHarness: "${kind}" is unbuilt — no capability exists to simulate`);
+        }
+        return descriptor;
+    }
+    // Injects a poll create (us) + a vote (the given participant) through
+    // FakeGateway's own poll fixture drivers, and folds the vote row into an
+    // InteractionCompletion keyed by the balloon guid (src/polls.ts classifies
+    // the vote row so this doesn't re-derive the wire hazards).
+    drivePollCycle(params) {
+        this.requireBuilt('poll');
+        const { balloon } = this.fake.injectPollCreate({
+            chatId: params.chatId,
+            fromMe: true,
+            question: params.question,
+            options: params.options,
+        });
+        const mintedOptions = balloon.poll?.options ?? [];
+        const optionIds = params.voter.optionIndexes.map((index) => {
+            const option = mintedOptions[index];
+            if (!option)
+                throw new Error(`InteractionHarness: no poll option at index ${index}`);
+            return option.id;
+        });
+        const voteMessage = this.fake.injectPollVote({
+            chatId: params.chatId,
+            sender: params.voter.sender,
+            senderName: params.voter.senderName,
+            pollGuid: balloon.guid,
+            optionIds,
+        });
+        if (!voteMessage.poll || pollEventKind(voteMessage.poll) !== 'vote') {
+            throw new Error('InteractionHarness: injectPollVote did not produce a vote row');
+        }
+        const votes = voteMessage.poll.votes ?? (voteMessage.poll.vote ? [voteMessage.poll.vote] : []);
+        return {
+            kind: 'poll',
+            correlationKey: balloon.guid,
+            response: {
+                optionIds: votes.map((v) => v.option_id).filter((id) => id !== undefined),
+                optionTexts: votes.map((v) => v.option_text).filter((t) => t !== undefined),
+            },
+        };
+    }
+    // Synthesizes a completion for a link-code kind. No gateway involvement —
+    // the completion transport is out-of-band (product store/webhook), so
+    // there is nothing to inject against FakeGateway; this just validates the
+    // kind and shapes the record.
+    driveLinkCompletion(kind, code, response) {
+        const descriptor = this.requireBuilt(kind);
+        if (descriptor.correlation !== 'link-code') {
+            throw new Error(`InteractionHarness: "${kind}" does not use link-code correlation`);
+        }
+        return { kind, correlationKey: code, response };
+    }
+}
+//# sourceMappingURL=harness.js.map

package/dist/interactions/harness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness.js","sourceRoot":"","sources":["../../src/interactions/harness.ts"],"names":[],"mappings":"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"}

package/dist/interactions/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types.js';
+export { InteractionRegistry } from './registry.js';
+export { defaultCatalog } from './catalog.js';
+export { InteractionHarness } from './harness.js';
+export type { PollCycleParams, PollVoteResponse } from './harness.js';

package/dist/interactions/index.js

@@ -0,0 +1,5 @@
+export * from './types.js';
+export { InteractionRegistry } from './registry.js';
+export { defaultCatalog } from './catalog.js';
+export { InteractionHarness } from './harness.js';
+//# sourceMappingURL=index.js.map

package/dist/interactions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/interactions/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC"}

package/dist/interactions/registry.d.ts

@@ -0,0 +1,9 @@
+import type { InteractionDescriptor, InteractionTier } from './types.js';
+export declare class InteractionRegistry {
+    private readonly descriptors;
+    register(descriptor: InteractionDescriptor): void;
+    get(id: string): InteractionDescriptor | undefined;
+    all(): InteractionDescriptor[];
+    byTier(tier: InteractionTier): InteractionDescriptor[];
+    agentUsable(): InteractionDescriptor[];
+}

package/dist/interactions/registry.js

@@ -0,0 +1,33 @@
+export class InteractionRegistry {
+    descriptors = new Map();
+    register(descriptor) {
+        if (this.descriptors.has(descriptor.id)) {
+            throw new Error(`InteractionRegistry: duplicate id "${descriptor.id}"`);
+        }
+        if (descriptor.tier === 'extension' && !descriptor.requiresRecipientInstall) {
+            throw new Error(`InteractionRegistry: "${descriptor.id}" is tier "extension" but requiresRecipientInstall is false — ` +
+                'a real MSMessages card only renders on devices with the extension installed.');
+        }
+        if (descriptor.correlation === 'none' && descriptor.inboundReadback) {
+            throw new Error(`InteractionRegistry: "${descriptor.id}" has correlation "none" but inboundReadback is true — ` +
+                'a readback needs a key to correlate against.');
+        }
+        this.descriptors.set(descriptor.id, descriptor);
+    }
+    get(id) {
+        return this.descriptors.get(id);
+    }
+    all() {
+        return [...this.descriptors.values()];
+    }
+    byTier(tier) {
+        return this.all().filter((d) => d.tier === tier);
+    }
+    // Kinds the running agent process can trigger itself, with a real,
+    // ground-truthed capability behind them — not merely "the method is
+    // wired" (docs/interactions.md "Status is not a success flag").
+    agentUsable() {
+        return this.all().filter((d) => d.outbound === 'agent' && d.status === 'host-smoked');
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/interactions/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/interactions/registry.ts"],"names":[],"mappings":"AAKA,MAAM,OAAO,mBAAmB;IACb,WAAW,GAAG,IAAI,GAAG,EAAiC,CAAC;IAExE,QAAQ,CAAC,UAAiC;QACxC,IAAI,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,EAAE,CAAC;YACxC,MAAM,IAAI,KAAK,CAAC,sCAAsC,UAAU,CAAC,EAAE,GAAG,CAAC,CAAC;QAC1E,CAAC;QACD,IAAI,UAAU,CAAC,IAAI,KAAK,WAAW,IAAI,CAAC,UAAU,CAAC,wBAAwB,EAAE,CAAC;YAC5E,MAAM,IAAI,KAAK,CACb,yBAAyB,UAAU,CAAC,EAAE,gEAAgE;gBACpG,8EAA8E,CACjF,CAAC;QACJ,CAAC;QACD,IAAI,UAAU,CAAC,WAAW,KAAK,MAAM,IAAI,UAAU,CAAC,eAAe,EAAE,CAAC;YACpE,MAAM,IAAI,KAAK,CACb,yBAAyB,UAAU,CAAC,EAAE,yDAAyD;gBAC7F,8CAA8C,CACjD,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC;IAClD,CAAC;IAED,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAClC,CAAC;IAED,GAAG;QACD,OAAO,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC;IACxC,CAAC;IAED,MAAM,CAAC,IAAqB;QAC1B,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IACnD,CAAC;IAED,mEAAmE;IACnE,oEAAoE;IACpE,gEAAgE;IAChE,WAAW;QACT,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,CAAC,MAAM,KAAK,aAAa,CAAC,CAAC;IACxF,CAAC;CACF"}

package/dist/interactions/types.d.ts

@@ -0,0 +1,28 @@
+export type InteractionTier = 'web-surface' | 'app-clip' | 'native-balloon' | 'extension';
+export type CorrelationKind = 'link-code' | 'message-guid' | 'none';
+export type InteractionStatus = 'unbuilt' | 'fake-only' | 'host-smoked';
+export type OutboundCapability = 'agent' | 'manual-host-op' | 'none';
+export type CompletionTransport = 'gateway-events' | 'out-of-band' | 'none';
+export type InteractionFallback = 'web-url' | 'plain-text' | 'none';
+export interface InteractionDescriptor {
+    id: string;
+    tier: InteractionTier;
+    requiresRecipientInstall: boolean;
+    correlation: CorrelationKind;
+    completionTransport: CompletionTransport;
+    outbound: OutboundCapability;
+    inboundReadback: boolean;
+    status: InteractionStatus;
+    fallback: InteractionFallback;
+    notes: string;
+}
+export interface InteractionRequest<P = unknown> {
+    kind: string;
+    correlationKey: string;
+    payload: P;
+}
+export interface InteractionCompletion<R = unknown> {
+    kind: string;
+    correlationKey: string;
+    response: R;
+}

package/dist/interactions/types.js

@@ -0,0 +1,5 @@
+// The interaction catalog's wire types. See docs/interactions.md for the
+// four-mechanism model and the contract each descriptor row makes a claim
+// against (docs/gateway-contract.md, docs/imsg-polls.md).
+export {};
+//# sourceMappingURL=types.js.map

package/dist/interactions/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/interactions/types.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,0EAA0E;AAC1E,0DAA0D"}