@relaymessenger/chat-sdk-adapter 0.2.0

package/dist/src/adapter.js

@@ -0,0 +1,724 @@
+import { Message, NotImplementedError, cardChildToFallbackText, emphasis, inlineCode, isCardElement, paragraph, root, strikethrough, strong, text as textNode, } from "chat";
+import { MAX_PARTS_PER_MESSAGE, MAX_TEXT_PART_BYTES, chunkRenderedText, } from "./chunk.js";
+import { RelayApiError, RelayClient } from "./client.js";
+import { renderAst, renderMarkdown, renderRawText, } from "./format.js";
+import { DedupeWindow, deriveIdempotencyKey, unkeyedIdempotencyKey, } from "./idempotency.js";
+import { toRelayReaction } from "./reactions.js";
+import { decodeWebhookSecret, verifyWebhookSignature, WebhookVerificationError, } from "./signature.js";
+import { decodeRelayThreadId, encodeRelayThreadId, relayChannelIdFromThreadId, } from "./threadId.js";
+import { activeTurn, runInTurn } from "./turn.js";
+export const RELAY_ADAPTER_NAME = "relay";
+const DEFAULT_DEDUPE_WINDOW = 4096;
+const DEFAULT_HISTORY_LIMIT = 50;
+/** `GET /v1/conversations/{id}/messages` clamps `limit` to this server side. */
+const MAX_HISTORY_LIMIT = 100;
+/**
+ * A group turn tried to commit a second message. Relay's invocation is single
+ * use, so there is nothing valid for the second message to cite and the server
+ * would answer 403.
+ */
+export class RelayInvocationSpentError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RelayInvocationSpentError";
+    }
+}
+function json(status, body) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "Content-Type": "application/json" },
+    });
+}
+async function toBytes(data) {
+    if (data instanceof Uint8Array)
+        return new Uint8Array(data);
+    if (data instanceof ArrayBuffer)
+        return new Uint8Array(data);
+    return new Uint8Array(await data.arrayBuffer());
+}
+function mediaKindToAttachmentType(part) {
+    if (part.type === "voice_memo")
+        return "audio";
+    switch (part.media_kind) {
+        case "image":
+        case "video":
+        case "audio":
+            return part.media_kind;
+        default:
+            return "file";
+    }
+}
+/** Text parts joined into one string, with every style range rebased onto it. */
+const TEXT_PART_SEPARATOR = "\n\n";
+/**
+ * Flatten a message's text parts into the single string the Chat SDK reads,
+ * carrying each part's style ranges across at their new offsets.
+ *
+ * A message routinely holds several text parts: this adapter itself produces
+ * them whenever a reply is longer than Relay's 8 KB per-part ceiling. Reading
+ * only the first part's ranges would land a chunked reply back as one flat
+ * paragraph, and applying them to the joined string unshifted would put the
+ * emphasis on the wrong words.
+ */
+function joinTextParts(parts) {
+    const pieces = [];
+    const styles = [];
+    let offset = 0;
+    for (const part of parts) {
+        const text = part.text ?? "";
+        // An empty part contributes no text, so it must not contribute a separator
+        // either: that would shift every later range by two.
+        if (!text)
+            continue;
+        if (pieces.length > 0)
+            offset += TEXT_PART_SEPARATOR.length;
+        for (const run of part.styles ?? []) {
+            styles.push({
+                start: run.start + offset,
+                length: run.length,
+                styles: run.styles,
+            });
+        }
+        pieces.push(text);
+        offset += text.length;
+    }
+    return { text: pieces.join(TEXT_PART_SEPARATOR), styles };
+}
+/**
+ * Rebuild an inline mdast run sequence from Relay's text plus style ranges, so
+ * `message.formatted` carries the emphasis the sender actually applied instead
+ * of a flat string. `underline` and `spoiler` have no mdast node, so those runs
+ * keep their words and lose only the decoration.
+ */
+function formattedFromParts(value, styles) {
+    if (!value)
+        return root([]);
+    const ranges = (styles ?? []).filter((run) => run.length > 0);
+    if (ranges.length === 0)
+        return root([paragraph([textNode(value)])]);
+    const children = [];
+    let cursor = 0;
+    for (const range of ranges) {
+        if (range.start > cursor) {
+            children.push(textNode(value.slice(cursor, range.start)));
+        }
+        const slice = value.slice(range.start, range.start + range.length);
+        let node = range.styles.includes("monospace")
+            ? inlineCode(slice)
+            : textNode(slice);
+        if (range.styles.includes("strikethrough"))
+            node = strikethrough([node]);
+        if (range.styles.includes("italic"))
+            node = emphasis([node]);
+        if (range.styles.includes("bold"))
+            node = strong([node]);
+        children.push(node);
+        cursor = range.start + range.length;
+    }
+    if (cursor < value.length)
+        children.push(textNode(value.slice(cursor)));
+    return root([paragraph(children)]);
+}
+/**
+ * Relay adapter for the Vercel Chat SDK.
+ *
+ * Relay is a consumer messenger where people talk to agents as contacts, so
+ * this adapter maps the Chat SDK's thread model onto Relay conversations one
+ * to one: a Relay conversation has no enclosing channel, and a thread id is
+ * `relay:{conversation_id}`.
+ *
+ * Two Relay rules shape the surface. A streamed turn commits exactly one
+ * canonical message, so `stream` buffers and posts once rather than editing a
+ * draft bubble into place. And a group reply is scoped to the single-use
+ * invocation that produced the inbound event, so the first send of a turn
+ * carries it and a second cannot.
+ */
+export class RelayAdapter {
+    name = RELAY_ADAPTER_NAME;
+    userName;
+    botUserId;
+    lockScope = "thread";
+    /** Relay serves history from `GET /v1/conversations/{id}/messages`. */
+    persistThreadHistory = false;
+    client;
+    webhookSecret;
+    toleranceSeconds;
+    dedupe;
+    chat;
+    constructor(options = {}) {
+        const token = options.token ?? process.env.RELAY_AGENT_TOKEN;
+        this.client =
+            options.client ??
+                new RelayClient({
+                    token: token ?? "",
+                    baseUrl: options.baseUrl,
+                    fetch: options.fetch,
+                });
+        this.webhookSecret =
+            options.webhookSecret ?? process.env.RELAY_WEBHOOK_SECRET;
+        // Decode once, here. An unusable secret raised from inside verification is
+        // a 500 on every delivery, and Relay reads a 500 as transient and
+        // redelivers ten times; raised here it is a startup failure naming the
+        // option that is wrong.
+        if (this.webhookSecret)
+            decodeWebhookSecret(this.webhookSecret);
+        this.userName = options.userName ?? "Relay Agent";
+        this.botUserId = options.agentId;
+        this.toleranceSeconds = options.toleranceSeconds;
+        this.dedupe = new DedupeWindow(options.dedupeWindow ?? DEFAULT_DEDUPE_WINDOW);
+    }
+    async initialize(chat) {
+        this.chat = chat;
+    }
+    encodeThreadId(platformData) {
+        return encodeRelayThreadId(platformData);
+    }
+    decodeThreadId(threadId) {
+        return decodeRelayThreadId(threadId);
+    }
+    channelIdFromThreadId(threadId) {
+        return relayChannelIdFromThreadId(threadId);
+    }
+    renderFormatted(content) {
+        return renderAst(content).text;
+    }
+    parseMessage(raw) {
+        const message = raw.message;
+        const threadId = this.encodeThreadId({ conversationId: message.conversation_id });
+        const parts = message.parts ?? [];
+        const textParts = parts.filter((part) => part.type === "text");
+        const joined = joinTextParts(textParts);
+        const value = joined.text || message.fallback_text || "";
+        // Ranges index into the joined part text. When the parts carried no text
+        // and the fallback stands in, they would index into a different string.
+        const styles = joined.text ? joined.styles : undefined;
+        const attachments = parts
+            .filter((part) => part.type === "media" || part.type === "voice_memo")
+            .map((part) => ({
+            type: mediaKindToAttachmentType(part),
+            url: part.url,
+            name: part.filename,
+            mimeType: part.content_type,
+            size: part.size_bytes,
+            width: part.width,
+            height: part.height,
+            ...(part.attachment_id
+                ? { fetchMetadata: { attachmentId: part.attachment_id } }
+                : {}),
+        }));
+        const links = parts
+            .filter((part) => part.type === "link_preview" && part.url)
+            .map((part) => ({
+            url: part.url,
+            title: part.title,
+            description: part.description,
+        }));
+        return new Message({
+            id: message.id,
+            threadId,
+            text: value,
+            formatted: formattedFromParts(value, styles),
+            raw,
+            author: {
+                userId: message.sender.id,
+                // Relay's event carries the sender's id and kind but no display name.
+                // Resolve one with `getUser(message.author.userId)` when you need it.
+                userName: message.sender.id,
+                fullName: message.sender.id,
+                isBot: message.sender.kind === "agent",
+                isMe: message.is_from_me ?? false,
+                ...(message.sender.kind === "system" ? { isSystem: true } : {}),
+            },
+            metadata: {
+                dateSent: new Date(message.created_at),
+                edited: Boolean(message.edited_at),
+                ...(message.edited_at ? { editedAt: new Date(message.edited_at) } : {}),
+            },
+            attachments,
+            ...(links.length > 0 ? { links } : {}),
+            // Relay delivers `message.received` to an agent only when the message is
+            // addressed to it: always in a direct conversation, and in a group only
+            // to agents with an invocation relationship to that message.
+            isMention: true,
+        });
+    }
+    async postMessage(threadId, message) {
+        const { conversationId } = this.decodeThreadId(threadId);
+        const parts = await this.buildParts(message);
+        if (parts.length === 0) {
+            throw new Error("a Relay message needs at least one part");
+        }
+        return this.sendParts(conversationId, threadId, parts);
+    }
+    async editMessage(threadId, messageId, message) {
+        this.decodeThreadId(threadId);
+        const parts = await this.buildParts(message);
+        // Relay rejects attachment-bearing edits outright, so name that here
+        // rather than letting the server answer 422 with no context.
+        if (parts.some((part) => part.type === "media" || part.type === "voice_memo")) {
+            throw new NotImplementedError("Relay edits must stay text-bearing: media and voice memo parts are rejected", "editMessage");
+        }
+        // Relay accepts exactly one text part per edit: an edit replaces one
+        // message's text, and one text part carries at most 8 KB. Text long
+        // enough to chunk cannot be an edit of one message, so refuse it here
+        // rather than sending a multi-part PATCH the server answers 422 to, or
+        // silently truncating the caller's content.
+        if (parts.length !== 1) {
+            throw new NotImplementedError("a Relay edit replaces one message with one text part of at most 8 KB; shorten the edit or post a new message", "editMessage");
+        }
+        const result = await this.client.edit(messageId, parts);
+        return {
+            id: result.message.id,
+            threadId,
+            raw: { message: result.message },
+        };
+    }
+    async deleteMessage(threadId, messageId) {
+        this.decodeThreadId(threadId);
+        await this.client.unsend(messageId);
+    }
+    async addReaction(threadId, messageId, emoji) {
+        this.decodeThreadId(threadId);
+        const reaction = toRelayReaction(emoji);
+        await this.client.react({ messageId, operation: "add", ...reaction });
+    }
+    async removeReaction(threadId, messageId, emoji) {
+        this.decodeThreadId(threadId);
+        const reaction = toRelayReaction(emoji);
+        await this.client.react({ messageId, operation: "remove", ...reaction });
+    }
+    /**
+     * Relay's typing indicator is ephemeral and carries an optional label of up
+     * to 80 characters. The invocation is peeked rather than consumed: typing is
+     * not the group reply the invocation is spent on.
+     *
+     * Failures are swallowed. Group typing without a live pending invocation is a
+     * 403 (`Relay-Server/server/src/domain/typing.ts:70-73`), which is exactly
+     * what typing after the first send of a group turn looks like. The Chat SDK
+     * treats this call as best effort and has no `stopTyping` to strand, so a
+     * hint that cannot be shown must never take the reply down with it.
+     */
+    async startTyping(threadId, status) {
+        const { conversationId } = this.decodeThreadId(threadId);
+        const turn = activeTurn(conversationId);
+        try {
+            await this.client.typing({
+                conversationId,
+                started: true,
+                ...(status ? { label: status.slice(0, 80) } : {}),
+                ...(turn?.invocationId && !turn.invocationUsed
+                    ? { invocationId: turn.invocationId }
+                    : {}),
+            });
+        }
+        catch {
+            // The indicator is decoration. The turn continues.
+        }
+    }
+    async markAsRead(threadId, messageId) {
+        const { conversationId } = this.decodeThreadId(threadId);
+        await this.client.markRead(conversationId, messageId);
+    }
+    async getUser(userId) {
+        try {
+            const { user } = await this.client.user(userId);
+            return {
+                userId: user.id,
+                userName: user.name,
+                fullName: user.name,
+                isBot: false,
+                ...(user.avatar_url ? { avatarUrl: user.avatar_url } : {}),
+            };
+        }
+        catch (error) {
+            if (typeof error === "object" &&
+                error !== null &&
+                error.status === 404) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Relay pages history backwards with `before_sequence` and returns newest
+     * first; the Chat SDK wants each page in chronological order. There is no
+     * forward cursor on the route, so `direction: "forward"` has nothing to call.
+     */
+    async fetchMessages(threadId, options) {
+        if (options?.direction === "forward") {
+            throw new NotImplementedError("Relay history pages backwards only: GET /v1/conversations/{id}/messages takes before_sequence and has no forward cursor", "fetchMessages");
+        }
+        const { conversationId } = this.decodeThreadId(threadId);
+        // The route clamps `limit` to 1..100 server side
+        // (`Relay-Server/server/src/routes/messages.ts:418`). Asking for 200 and
+        // then testing the 100 rows that come back against 200 would read as "the
+        // conversation ended here" and silently truncate the history.
+        const limit = Math.min(Math.max(Math.trunc(options?.limit ?? DEFAULT_HISTORY_LIMIT), 1), MAX_HISTORY_LIMIT);
+        const beforeSequence = options?.cursor ? Number(options.cursor) : undefined;
+        if (beforeSequence !== undefined && !Number.isFinite(beforeSequence)) {
+            throw new Error(`not a Relay history cursor: ${options?.cursor}`);
+        }
+        const { messages } = await this.client.history({
+            conversationId,
+            limit,
+            ...(beforeSequence !== undefined ? { beforeSequence } : {}),
+        });
+        const chronological = [...messages].sort((a, b) => a.sequence - b.sequence);
+        const parsed = chronological.map((message) => this.parseMessage({ message }));
+        const oldest = chronological[0];
+        return {
+            messages: parsed,
+            ...(messages.length >= limit && oldest
+                ? { nextCursor: String(oldest.sequence) }
+                : {}),
+        };
+    }
+    async fetchThread(threadId) {
+        const { conversationId } = this.decodeThreadId(threadId);
+        const { conversation } = await this.client.conversation(conversationId);
+        return {
+            id: threadId,
+            channelId: this.channelIdFromThreadId(threadId),
+            isDM: conversation.kind === "direct",
+            // Relay conversations are private to their participants; there is no
+            // workspace or externally shared scope above them.
+            channelVisibility: "private",
+            ...(conversation.title ??
+                conversation.counterpart_user?.display_name
+                ? {
+                    channelName: conversation.title ??
+                        conversation.counterpart_user?.display_name,
+                }
+                : {}),
+            metadata: {
+                kind: conversation.kind,
+                participantCount: conversation.participant_count,
+                lastSequence: conversation.last_sequence,
+                counterpartUserId: conversation.counterpart_user?.id,
+            },
+        };
+    }
+    /**
+     * Relay commits one canonical message per turn and has no draft bubble to
+     * edit, so the stream is buffered and posted once. Nothing partial ever
+     * reaches a recipient, and no cleanup is needed if the stream fails midway.
+     */
+    async stream(threadId, textStream) {
+        const pieces = [];
+        for await (const chunk of textStream) {
+            if (typeof chunk === "string") {
+                pieces.push(chunk);
+                continue;
+            }
+            if (chunk.type === "markdown_text")
+                pieces.push(chunk.text);
+            // Task and plan chunks describe in-flight progress. Relay shows progress
+            // through the typing label instead, so they do not enter the message.
+        }
+        const markdown = pieces.join("");
+        if (!markdown.trim())
+            return null;
+        return this.postMessage(threadId, { markdown });
+    }
+    /**
+     * Verify the Standard Webhooks signature over the exact raw body, refuse a
+     * replay by `event_id`, and hand the event to the Chat SDK. Relay redelivers
+     * on 5xx, so a dispatch failure must not answer 2xx.
+     */
+    async handleWebhook(request, options) {
+        if (request.method !== "POST") {
+            return json(405, { error: { code: "method_not_allowed" } });
+        }
+        if (!this.webhookSecret) {
+            throw new Error("webhookSecret is required: pass it to createRelayAdapter or set RELAY_WEBHOOK_SECRET");
+        }
+        if (!this.chat) {
+            throw new Error("the Relay adapter received a webhook before initialize()");
+        }
+        const payload = await request.text();
+        try {
+            await verifyWebhookSignature({
+                secret: this.webhookSecret,
+                payload,
+                headers: {
+                    "webhook-id": request.headers.get("webhook-id"),
+                    "webhook-timestamp": request.headers.get("webhook-timestamp"),
+                    "webhook-signature": request.headers.get("webhook-signature"),
+                },
+                options: { toleranceSeconds: this.toleranceSeconds },
+            });
+        }
+        catch (error) {
+            if (error instanceof WebhookVerificationError) {
+                return json(401, {
+                    error: { code: "invalid_signature", message: error.message },
+                });
+            }
+            throw error;
+        }
+        let envelope;
+        try {
+            envelope = JSON.parse(payload);
+        }
+        catch {
+            return json(422, {
+                error: { code: "invalid_request", message: "body is not JSON" },
+            });
+        }
+        if (!envelope.event_id || !envelope.event_type) {
+            return json(422, {
+                error: { code: "invalid_request", message: "not an event envelope" },
+            });
+        }
+        // Claim before dispatching, not after. Two redeliveries of one event can
+        // be in flight at once, and a check that only records on the way out lets
+        // both of them past.
+        if (!this.dedupe.claim(envelope.event_id)) {
+            return json(200, { deduplicated: true });
+        }
+        try {
+            await this.dispatch(envelope, options);
+        }
+        catch (error) {
+            // Give the claim back. A thrown handler answers 5xx, which is Relay's
+            // signal to redeliver, and a retained claim would turn every redelivery
+            // into a 200 that did nothing: the message would be lost outright. The
+            // `Idempotency-Key` on each send is what keeps the retry from posting
+            // twice whatever the first attempt already committed.
+            this.dedupe.release(envelope.event_id);
+            throw error;
+        }
+        return json(200, { handled: true });
+    }
+    async dispatch(envelope, options) {
+        const chat = this.chat;
+        switch (envelope.event_type) {
+            case "message.received": {
+                const data = envelope.data;
+                const raw = {
+                    message: data.message,
+                    invocation_id: data.invocation_id,
+                    event_id: envelope.event_id,
+                    event_type: envelope.event_type,
+                };
+                const threadId = this.encodeThreadId({
+                    conversationId: data.message.conversation_id,
+                });
+                const turn = {
+                    conversationId: data.message.conversation_id,
+                    eventId: envelope.event_id,
+                    invocationId: data.invocation_id,
+                    invocationUsed: false,
+                    sent: 0,
+                };
+                // Bind the turn to this dispatch's async context, so a second event on
+                // the same conversation cannot take it over while this one waits.
+                await runInTurn(turn, () => chat.processMessage(this, threadId, this.parseMessage(raw), options));
+                return;
+            }
+            case "message.edited": {
+                const data = envelope.data;
+                const raw = {
+                    message: data.message,
+                    event_id: envelope.event_id,
+                    event_type: envelope.event_type,
+                };
+                await chat.processMessageUpdated({
+                    adapter: this,
+                    threadId: this.encodeThreadId({
+                        conversationId: data.message.conversation_id,
+                    }),
+                    message: this.parseMessage(raw),
+                }, options);
+                return;
+            }
+            case "message.unsent": {
+                const data = envelope.data;
+                const threadId = this.encodeThreadId({
+                    conversationId: data.conversation_id,
+                });
+                await chat.processMessageDeleted({
+                    adapter: this,
+                    threadId,
+                    channelId: this.channelIdFromThreadId(threadId),
+                    messageId: data.message_id,
+                    deletedAt: new Date(envelope.created_at),
+                    raw: envelope,
+                }, options);
+                return;
+            }
+            default:
+                // Reaction, receipt, conversation, and group invite events acknowledge
+                // without dispatch. `reaction.added` carries an undocumented `reaction`
+                // object in the OpenAPI, so there is nothing stable to map onto the
+                // Chat SDK's ReactionEvent yet.
+                return;
+        }
+    }
+    async buildParts(message) {
+        if (typeof message === "string") {
+            return this.textParts(renderRawText(message));
+        }
+        if (isCardElement(message)) {
+            return this.textParts(renderRawText(this.cardToText(message)));
+        }
+        let rendered;
+        if ("raw" in message) {
+            rendered = renderRawText(message.raw);
+        }
+        else if ("markdown" in message) {
+            rendered = renderMarkdown(message.markdown);
+        }
+        else if ("ast" in message) {
+            rendered = renderAst(message.ast);
+        }
+        else {
+            rendered = renderRawText(this.cardToText(message.card, message.fallbackText));
+        }
+        const parts = this.textParts(rendered);
+        const attachments = "attachments" in message && message.attachments ? message.attachments : [];
+        for (const attachment of attachments) {
+            parts.push(await this.attachmentPart(attachment));
+        }
+        const files = "files" in message && message.files ? message.files : [];
+        for (const file of files) {
+            parts.push(await this.filePart(file));
+        }
+        return parts;
+    }
+    textParts(rendered) {
+        return chunkRenderedText(rendered, MAX_TEXT_PART_BYTES).map((chunk) => ({
+            type: "text",
+            text: chunk.text,
+            // An empty array is meaningful to Relay: it marks structured plain text
+            // rather than a legacy Markdown body.
+            styles: chunk.styles,
+        }));
+    }
+    /**
+     * Relay has no card surface: interactive components were removed from the
+     * app, so buttons cannot render and a human cannot answer one in Relay. The
+     * card's words are still delivered, as text, rather than dropped.
+     */
+    cardToText(card, fallbackText) {
+        if (fallbackText?.trim())
+            return fallbackText;
+        const lines = [];
+        if (card.title)
+            lines.push(card.title);
+        if (card.subtitle)
+            lines.push(card.subtitle);
+        for (const child of card.children ?? []) {
+            const rendered = cardChildToFallbackText(child);
+            if (rendered)
+                lines.push(rendered);
+        }
+        const value = lines.join("\n\n").trim();
+        if (!value) {
+            throw new NotImplementedError("Relay has no card surface and this card carried no text to fall back to", "postMessage");
+        }
+        return value;
+    }
+    async attachmentPart(attachment) {
+        if (attachment.url?.startsWith("https://")) {
+            return {
+                type: "media",
+                url: attachment.url,
+                ...(attachment.mimeType ? { content_type: attachment.mimeType } : {}),
+            };
+        }
+        const data = attachment.data ?? (await attachment.fetchData?.());
+        if (!data) {
+            throw new Error(`attachment ${attachment.name ?? "(unnamed)"} has neither an https URL nor bytes, so Relay has nothing to store`);
+        }
+        const stored = await this.client.upload({
+            body: await toBytes(data),
+            ...(attachment.mimeType ? { contentType: attachment.mimeType } : {}),
+            ...(attachment.name ? { filename: attachment.name } : {}),
+        });
+        return { type: "media", attachment_id: stored.id };
+    }
+    async filePart(file) {
+        const stored = await this.client.upload({
+            body: await toBytes(file.data),
+            ...(file.mimeType ? { contentType: file.mimeType } : {}),
+            filename: file.filename,
+        });
+        return { type: "media", attachment_id: stored.id };
+    }
+    /**
+     * Send the parts in one call when they fit, and as follow-up calls when
+     * they do not. The server splits each call at ingest into one or more
+     * messages, and the one call that carries the invocation owns every message
+     * it commits. A group turn cannot overflow, and cannot POST twice: Relay's
+     * invocation is single use per call, so a second POST has nothing valid to
+     * cite and the server answers 403.
+     */
+    async sendParts(conversationId, threadId, parts) {
+        const turn = activeTurn(conversationId);
+        const batches = [];
+        for (let i = 0; i < parts.length; i += MAX_PARTS_PER_MESSAGE) {
+            batches.push(parts.slice(i, i + MAX_PARTS_PER_MESSAGE));
+        }
+        // Relay carries an invocation only on a group event, so a turn holding one
+        // is a group turn for as long as it lives. Test that rather than testing
+        // whether an invocation is still available: once it is spent, the second
+        // send would otherwise go out bare and be refused by the server.
+        const groupTurn = turn?.invocationId !== undefined ? turn : undefined;
+        if (groupTurn?.invocationUsed) {
+            throw new RelayInvocationSpentError("this group turn already replied, and one Relay invocation permits one message");
+        }
+        const invocationId = groupTurn?.invocationId;
+        if (batches.length > 1 && invocationId) {
+            throw new RelayInvocationSpentError(`this reply needs ${batches.length} Relay send calls, and one Relay invocation permits one call`);
+        }
+        // The ordinal is the send's logical position in the turn, so a retry lands
+        // on the key the first attempt used and Relay replays it instead of
+        // posting a second message. The base counts what this turn has already
+        // committed and is read once, before the loop: it advances only on a
+        // successful send, so an attempt that threw does not push the next key
+        // along and a redelivery of the whole event starts from zero again.
+        const base = turn?.sent ?? 0;
+        let first;
+        for (const [index, batch] of batches.entries()) {
+            const idempotencyKey = turn
+                ? deriveIdempotencyKey(turn.eventId, base + index)
+                : unkeyedIdempotencyKey(conversationId);
+            const result = await this.client.send({
+                conversationId,
+                parts: batch,
+                idempotencyKey,
+                ...(first === undefined && invocationId ? { invocationId } : {}),
+            });
+            if (turn) {
+                turn.sent += 1;
+                if (first === undefined && invocationId)
+                    turn.invocationUsed = true;
+            }
+            // One call commits one or more messages; the Chat SDK's post contract
+            // names a single raw message, so the first committed one stands for the
+            // whole send. A 202 that carries none is a server contract violation:
+            // surface it as a 502 so a generic status-classing retry treats it as
+            // transient, instead of handing the caller undefined as a message.
+            const [committed] = result.messages;
+            if (!committed) {
+                throw new RelayApiError(502, "empty_send", "relay: 202 carried no messages");
+            }
+            if (first === undefined) {
+                first = {
+                    id: committed.id,
+                    threadId,
+                    raw: { message: committed },
+                };
+            }
+        }
+        if (!first) {
+            throw new RelayApiError(502, "empty_send", "relay: send committed no messages");
+        }
+        return first;
+    }
+}
+/** Build a Relay adapter for the Vercel Chat SDK. */
+export function createRelayAdapter(options = {}) {
+    return new RelayAdapter(options);
+}