experimental-ash 0.25.2 → 0.26.0

package/dist/src/public/channels/discord/discordChannel.js

@@ -0,0 +1,402 @@
+import { createLogger } from "#internal/logging.js";
+import { callDiscordApi, createDiscordFollowupMessage, discordContinuationToken, editDiscordOriginalResponse, sendDiscordChannelMessage, splitDiscordMessageContent, triggerDiscordTypingIndicator, } from "#public/channels/discord/api.js";
+import { defaultEvents, defaultOnCommand } from "#public/channels/discord/defaults.js";
+import { deriveComponentInputResponses, deriveModalInputResponses, buildFreeformModalResponse, isDiscordFreeformComponent, } from "#public/channels/discord/hitl.js";
+import { commandInteractionMessage, DISCORD_INTERACTION_RESPONSE_TYPE, DISCORD_INTERACTION_TYPE, parseDiscordInteraction, prependDiscordContext, } from "#public/channels/discord/inbound.js";
+import { discordDeferredJson, discordJson, discordJsonBody, readMessageContent, } from "#public/channels/discord/responses.js";
+import {} from "#public/channels/discord/verify.js";
+import { verifyDiscordInbound } from "#public/channels/discord/verifyInbound.js";
+import { parseJsonObject } from "#shared/json.js";
+import { defineChannel, POST, } from "#public/definitions/defineChannel.js";
+const log = createLogger("discord.channel");
+/** Discord channel factory for HTTP Interactions and proactive channel messages. */
+export function discordChannel(config = {}) {
+    const onCommand = config.onCommand ?? defaultOnCommand;
+    const mergedEvents = { ...defaultEvents, ...config.events };
+    return defineChannel({
+        kindHint: "discord",
+        state: initialDiscordState(),
+        context(state, session) {
+            return rebuildDiscordContext(state, session, config);
+        },
+        routes: [
+            POST(config.route ?? "/ash/v1/discord", async (req, { send, waitUntil }) => {
+                const body = await verifyDiscordInbound(req, config.credentials);
+                if (body === null)
+                    return new Response("unauthorized", { status: 401 });
+                let raw;
+                try {
+                    raw = parseJsonObject(JSON.parse(body));
+                }
+                catch (error) {
+                    log.warn("inbound Discord body is not valid JSON", { error });
+                    return discordJson({ content: "invalid request", ephemeral: true });
+                }
+                if (raw.type === DISCORD_INTERACTION_TYPE.PING) {
+                    return discordJson({ type: DISCORD_INTERACTION_RESPONSE_TYPE.PONG });
+                }
+                const interaction = parseDiscordInteraction(raw);
+                if (interaction === null) {
+                    return discordJson({ content: "Unsupported Discord interaction.", ephemeral: true });
+                }
+                return handleInteraction({
+                    config,
+                    interaction,
+                    onCommand,
+                    send,
+                    waitUntil,
+                });
+            }),
+        ],
+        async receive(input, { send }) {
+            const receiveArgs = input.args;
+            const channelId = readString(receiveArgs.channelId);
+            if (!channelId) {
+                throw new Error("discordChannel().receive requires args.channelId.");
+            }
+            const requestedConversationId = readString(receiveArgs.conversationId);
+            const initialMessage = receiveArgs.initialMessage;
+            if (initialMessage !== undefined && requestedConversationId !== undefined) {
+                throw new Error("discordChannel().receive: `conversationId` and `initialMessage` are mutually exclusive.");
+            }
+            let conversationId = requestedConversationId ?? "";
+            let hasMessageAnchor = requestedConversationId !== undefined;
+            if (initialMessage !== undefined) {
+                const handle = buildDiscordHandle({
+                    config,
+                    state: {
+                        ...initialDiscordState(),
+                        channelId,
+                    },
+                });
+                const posted = await handle.sendChannelMessage(initialMessage);
+                conversationId = posted.id;
+                hasMessageAnchor = posted.id.length > 0;
+            }
+            return send(input.message, {
+                auth: input.auth,
+                continuationToken: discordContinuationToken(channelId, conversationId),
+                state: {
+                    applicationId: null,
+                    channelId,
+                    conversationId: conversationId || null,
+                    guildId: null,
+                    hasMessageAnchor,
+                    initialResponseSent: true,
+                    interactionToken: null,
+                },
+            });
+        },
+        events: mergedEvents,
+    });
+}
+function rebuildDiscordContext(state, session, config) {
+    return {
+        discord: buildDiscordHandle({ config, session, state }),
+        session,
+        state,
+    };
+}
+function buildDiscordHandle(input) {
+    const api = input.config.api;
+    const state = input.state;
+    const credentials = mergeCredentials(input.config.credentials, state);
+    function anchor(posted) {
+        if (!posted.id || state.hasMessageAnchor)
+            return;
+        state.conversationId = posted.id;
+        state.hasMessageAnchor = true;
+        if (state.channelId) {
+            input.session?.setContinuationToken(discordContinuationToken(state.channelId, posted.id));
+        }
+    }
+    async function sendViaChannel(message) {
+        const channelId = state.channelId ?? "";
+        if (!channelId)
+            throw new Error("discordChannel: missing channel id for outbound message.");
+        const posted = await sendDiscordChannelMessage({
+            apiBaseUrl: api?.apiBaseUrl,
+            body: normalizePostInput(message),
+            credentials,
+            fetch: api?.fetch,
+            channelId,
+        });
+        anchor(posted);
+        return posted;
+    }
+    async function editOriginal(message) {
+        const interactionToken = state.interactionToken ?? "";
+        if (!interactionToken) {
+            throw new Error("discordChannel: missing interaction token for original response edit.");
+        }
+        const posted = await editDiscordOriginalResponse({
+            apiBaseUrl: api?.apiBaseUrl,
+            body: normalizePostInput(message),
+            credentials,
+            fetch: api?.fetch,
+            interactionToken,
+        });
+        state.initialResponseSent = true;
+        anchor(posted);
+        return posted;
+    }
+    async function followup(message) {
+        const interactionToken = state.interactionToken ?? "";
+        if (!interactionToken) {
+            throw new Error("discordChannel: missing interaction token for followup message.");
+        }
+        const posted = await createDiscordFollowupMessage({
+            apiBaseUrl: api?.apiBaseUrl,
+            body: normalizePostInput(message),
+            credentials,
+            fetch: api?.fetch,
+            interactionToken,
+        });
+        anchor(posted);
+        return posted;
+    }
+    async function startTyping() {
+        const channelId = state.channelId ?? "";
+        if (!channelId)
+            return;
+        try {
+            await triggerDiscordTypingIndicator({
+                apiBaseUrl: api?.apiBaseUrl,
+                credentials,
+                fetch: api?.fetch,
+                channelId,
+            });
+        }
+        catch (error) {
+            log.debug("Discord typing indicator failed — swallowed", { error });
+        }
+    }
+    return {
+        applicationId: state.applicationId ?? undefined,
+        channelId: state.channelId ?? "",
+        conversationId: state.conversationId ?? "",
+        guildId: state.guildId ?? undefined,
+        interactionToken: state.interactionToken ?? undefined,
+        request(path, body, options) {
+            return callDiscordApi({
+                apiBaseUrl: api?.apiBaseUrl,
+                body,
+                botToken: options?.botAuth === true ? credentials.botToken : undefined,
+                fetch: api?.fetch,
+                method: options?.method,
+                path,
+            });
+        },
+        async post(message) {
+            const bodies = expandPostBodies(normalizePostInput(message));
+            let first;
+            for (const body of bodies) {
+                const posted = await postOne({
+                    body,
+                    editOriginal,
+                    followup,
+                    sendViaChannel,
+                    state,
+                });
+                if (first === undefined)
+                    first = posted;
+            }
+            return first ?? { id: "", raw: null };
+        },
+        editOriginalResponse: editOriginal,
+        followup,
+        sendChannelMessage: sendViaChannel,
+        startTyping,
+    };
+}
+async function postOne(input) {
+    if (input.state.interactionToken && input.state.applicationId) {
+        try {
+            if (!input.state.initialResponseSent) {
+                return await input.editOriginal(input.body);
+            }
+            return await input.followup(input.body);
+        }
+        catch (error) {
+            log.warn("Discord interaction-token delivery failed, falling back to channel message", {
+                error,
+            });
+        }
+    }
+    return input.sendViaChannel(input.body);
+}
+async function handleInteraction(input) {
+    if (input.interaction.type === DISCORD_INTERACTION_TYPE.APPLICATION_COMMAND) {
+        return handleCommandInteraction({
+            config: input.config,
+            interaction: input.interaction,
+            onCommand: input.onCommand,
+            send: input.send,
+            waitUntil: input.waitUntil,
+        });
+    }
+    if (input.interaction.type === DISCORD_INTERACTION_TYPE.MESSAGE_COMPONENT) {
+        return handleComponentInteraction({
+            interaction: input.interaction,
+            send: input.send,
+            waitUntil: input.waitUntil,
+        });
+    }
+    return handleModalSubmitInteraction({
+        interaction: input.interaction,
+        send: input.send,
+        waitUntil: input.waitUntil,
+    });
+}
+async function handleCommandInteraction(input) {
+    const state = stateFromInteraction(input.interaction, {
+        conversationId: input.interaction.id,
+        hasMessageAnchor: false,
+        initialResponseSent: false,
+    });
+    const ctx = {
+        discord: buildDiscordHandle({ config: input.config, state }),
+    };
+    let result;
+    try {
+        result = await input.onCommand(ctx, input.interaction);
+    }
+    catch (error) {
+        log.error("command handler failed", { error });
+        return discordJson({ content: "The Discord command handler failed.", ephemeral: true });
+    }
+    if (result === null || result === undefined) {
+        return discordJson({ content: "Command ignored.", ephemeral: true });
+    }
+    input.waitUntil(dispatchCommand({
+        interaction: input.interaction,
+        result,
+        send: input.send,
+        state,
+    }));
+    return discordDeferredJson(result.ephemeral === true);
+}
+function handleComponentInteraction(input) {
+    if (isDiscordFreeformComponent(input.interaction.customId)) {
+        const prompt = readMessageContent(input.interaction.raw);
+        return discordJsonBody(buildFreeformModalResponse({
+            customId: input.interaction.customId,
+            prompt,
+        }));
+    }
+    const inputResponses = deriveComponentInputResponses(input.interaction);
+    if (inputResponses.length > 0) {
+        input.waitUntil(dispatchInputResponses({
+            conversationId: input.interaction.messageId,
+            inputResponses,
+            interaction: input.interaction,
+            send: input.send,
+        }));
+    }
+    return discordJsonBody({ type: DISCORD_INTERACTION_RESPONSE_TYPE.DEFERRED_UPDATE_MESSAGE });
+}
+function handleModalSubmitInteraction(input) {
+    const inputResponses = deriveModalInputResponses(input.interaction);
+    if (inputResponses.length > 0) {
+        input.waitUntil(dispatchInputResponses({
+            conversationId: input.interaction.messageId ?? input.interaction.id,
+            inputResponses,
+            interaction: input.interaction,
+            send: input.send,
+        }));
+    }
+    return discordJson({ content: "Answer received.", ephemeral: true });
+}
+async function dispatchCommand(input) {
+    const message = commandInteractionMessage(input.interaction);
+    const turnMessage = prependDiscordContext(message, {
+        channelId: input.interaction.channelId,
+        commandName: input.interaction.commandName,
+        guildId: input.interaction.guildId,
+        interactionId: input.interaction.id,
+        userId: input.interaction.user.id,
+        username: input.interaction.user.username,
+    });
+    try {
+        await input.send({
+            message: turnMessage,
+            modelContext: input.result.modelContext,
+        }, {
+            auth: input.result.auth,
+            continuationToken: discordContinuationToken(input.interaction.channelId, input.interaction.id),
+            state: input.state,
+        });
+    }
+    catch (error) {
+        log.error("command delivery failed", { error });
+    }
+}
+async function dispatchInputResponses(input) {
+    try {
+        await input.send({ inputResponses: input.inputResponses }, {
+            auth: null,
+            continuationToken: discordContinuationToken(input.interaction.channelId, input.conversationId),
+            state: stateFromInteraction(input.interaction, {
+                conversationId: input.conversationId,
+                hasMessageAnchor: true,
+                initialResponseSent: true,
+            }),
+        });
+    }
+    catch (error) {
+        log.error("interaction response delivery failed", { error });
+    }
+}
+function stateFromInteraction(interaction, options) {
+    return {
+        applicationId: interaction.applicationId,
+        channelId: interaction.channelId,
+        conversationId: options.conversationId,
+        guildId: interaction.guildId ?? null,
+        hasMessageAnchor: options.hasMessageAnchor,
+        initialResponseSent: options.initialResponseSent,
+        interactionToken: interaction.token,
+    };
+}
+function initialDiscordState() {
+    return {
+        applicationId: null,
+        channelId: null,
+        conversationId: null,
+        guildId: null,
+        hasMessageAnchor: false,
+        initialResponseSent: false,
+        interactionToken: null,
+    };
+}
+function mergeCredentials(credentials, state) {
+    const merged = {
+        applicationId: state.applicationId ?? credentials?.applicationId,
+        botToken: credentials?.botToken,
+        publicKey: credentials?.publicKey,
+        webhookVerifier: credentials?.webhookVerifier,
+    };
+    return merged;
+}
+function normalizePostInput(message) {
+    if (typeof message === "string")
+        return { content: message };
+    return message;
+}
+function expandPostBodies(body) {
+    if (typeof body.content !== "string")
+        return [body];
+    const chunks = splitDiscordMessageContent(body.content);
+    return chunks.map((content, index) => {
+        if (index === 0) {
+            return { ...body, content };
+        }
+        return {
+            allowed_mentions: body.allowed_mentions,
+            content,
+        };
+    });
+}
+function readString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}

package/dist/src/public/channels/discord/hitl.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Discord HITL component rendering + decode helpers.
+ *
+ * Discord components carry a `custom_id` with a 100-character cap. Ash
+ * encodes only the request id and, for buttons, the selected option id.
+ */
+import { type DiscordComponentInteraction, type DiscordModalSubmitInteraction } from "#public/channels/discord/inbound.js";
+import type { InputRequest, InputResponse } from "#runtime/input/types.js";
+/** Discord component type values used by the native channel. */
+export declare const DISCORD_COMPONENT_TYPE: {
+    readonly ACTION_ROW: 1;
+    readonly BUTTON: 2;
+    readonly STRING_SELECT: 3;
+    readonly TEXT_INPUT: 4;
+};
+/** Custom id prefix for selectable HITL controls. */
+export declare const DISCORD_HITL_CUSTOM_ID_PREFIX = "ash_input:";
+/** Custom id prefix for the button/modal freeform flow. */
+export declare const DISCORD_HITL_FREEFORM_CUSTOM_ID_PREFIX = "ash_input_freeform:";
+/** Text-input id inside the freeform modal. */
+export declare const DISCORD_HITL_FREEFORM_TEXT_INPUT_ID = "ash_freeform_text";
+/** Renders one input request as Discord message components. */
+export declare function renderInputRequestComponents(request: InputRequest): readonly Readonly<Record<string, unknown>>[];
+/** Builds a Discord modal response for one freeform HITL request. */
+export declare function buildFreeformModalResponse(input: {
+    readonly customId: string;
+    readonly prompt: string | undefined;
+}): Record<string, unknown>;
+/** Returns true when a component custom id starts the freeform modal flow. */
+export declare function isDiscordFreeformComponent(customId: string): boolean;
+/** Decodes one component interaction into HITL input responses. */
+export declare function deriveComponentInputResponses(interaction: DiscordComponentInteraction): readonly InputResponse[];
+/** Decodes one modal submission into HITL input responses. */
+export declare function deriveModalInputResponses(interaction: DiscordModalSubmitInteraction): readonly InputResponse[];

package/dist/src/public/channels/discord/hitl.js

@@ -0,0 +1,194 @@
+/**
+ * Discord HITL component rendering + decode helpers.
+ *
+ * Discord components carry a `custom_id` with a 100-character cap. Ash
+ * encodes only the request id and, for buttons, the selected option id.
+ */
+import { DISCORD_INTERACTION_RESPONSE_TYPE, } from "#public/channels/discord/inbound.js";
+/** Discord component type values used by the native channel. */
+export const DISCORD_COMPONENT_TYPE = {
+    ACTION_ROW: 1,
+    BUTTON: 2,
+    STRING_SELECT: 3,
+    TEXT_INPUT: 4,
+};
+/** Custom id prefix for selectable HITL controls. */
+export const DISCORD_HITL_CUSTOM_ID_PREFIX = "ash_input:";
+/** Custom id prefix for the button/modal freeform flow. */
+export const DISCORD_HITL_FREEFORM_CUSTOM_ID_PREFIX = "ash_input_freeform:";
+/** Text-input id inside the freeform modal. */
+export const DISCORD_HITL_FREEFORM_TEXT_INPUT_ID = "ash_freeform_text";
+const DISCORD_CUSTOM_ID_MAX_LENGTH = 100;
+const DISCORD_LABEL_MAX_LENGTH = 80;
+const DISCORD_SELECT_OPTION_TEXT_MAX_LENGTH = 100;
+const DISCORD_MODAL_TITLE_MAX_LENGTH = 45;
+const DISCORD_ACTION_ROW_LIMIT = 5;
+const DISCORD_SELECT_OPTION_LIMIT = 25;
+/** Renders one input request as Discord message components. */
+export function renderInputRequestComponents(request) {
+    const options = request.options;
+    const acceptsFreeform = request.allowFreeform === true || !options || options.length === 0;
+    if (options && options.length > 0 && request.display === "select") {
+        return [
+            {
+                components: [
+                    {
+                        custom_id: encodeHitlCustomId(DISCORD_HITL_CUSTOM_ID_PREFIX, {
+                            requestId: request.requestId,
+                        }),
+                        options: options.slice(0, DISCORD_SELECT_OPTION_LIMIT).map((option) => {
+                            const result = {
+                                label: truncate(option.label, DISCORD_SELECT_OPTION_TEXT_MAX_LENGTH),
+                                value: truncate(option.id, DISCORD_SELECT_OPTION_TEXT_MAX_LENGTH),
+                            };
+                            if (option.description !== undefined) {
+                                result.description = truncate(option.description, DISCORD_SELECT_OPTION_TEXT_MAX_LENGTH);
+                            }
+                            return result;
+                        }),
+                        placeholder: "Choose an option",
+                        type: DISCORD_COMPONENT_TYPE.STRING_SELECT,
+                    },
+                ],
+                type: DISCORD_COMPONENT_TYPE.ACTION_ROW,
+            },
+        ];
+    }
+    if (options && options.length > 0) {
+        return chunk(options.slice(0, DISCORD_ACTION_ROW_LIMIT * DISCORD_ACTION_ROW_LIMIT), 5).map((row) => ({
+            components: row.map((option) => ({
+                custom_id: encodeHitlCustomId(DISCORD_HITL_CUSTOM_ID_PREFIX, {
+                    optionId: option.id,
+                    requestId: request.requestId,
+                }),
+                label: truncate(option.label, DISCORD_LABEL_MAX_LENGTH),
+                style: toDiscordButtonStyle(option.style),
+                type: DISCORD_COMPONENT_TYPE.BUTTON,
+            })),
+            type: DISCORD_COMPONENT_TYPE.ACTION_ROW,
+        }));
+    }
+    if (acceptsFreeform) {
+        return [
+            {
+                components: [
+                    {
+                        custom_id: encodeHitlCustomId(DISCORD_HITL_FREEFORM_CUSTOM_ID_PREFIX, {
+                            requestId: request.requestId,
+                        }),
+                        label: "Type your answer",
+                        style: 1,
+                        type: DISCORD_COMPONENT_TYPE.BUTTON,
+                    },
+                ],
+                type: DISCORD_COMPONENT_TYPE.ACTION_ROW,
+            },
+        ];
+    }
+    return [];
+}
+/** Builds a Discord modal response for one freeform HITL request. */
+export function buildFreeformModalResponse(input) {
+    const payload = decodeHitlCustomId(input.customId, DISCORD_HITL_FREEFORM_CUSTOM_ID_PREFIX);
+    if (!payload) {
+        throw new Error("discordChannel: freeform custom_id is malformed.");
+    }
+    return {
+        data: {
+            components: [
+                {
+                    components: [
+                        {
+                            custom_id: DISCORD_HITL_FREEFORM_TEXT_INPUT_ID,
+                            label: "Answer",
+                            max_length: 4000,
+                            min_length: 1,
+                            placeholder: "Type your answer here...",
+                            required: true,
+                            style: 2,
+                            type: DISCORD_COMPONENT_TYPE.TEXT_INPUT,
+                        },
+                    ],
+                    type: DISCORD_COMPONENT_TYPE.ACTION_ROW,
+                },
+            ],
+            custom_id: encodeHitlCustomId(DISCORD_HITL_FREEFORM_CUSTOM_ID_PREFIX, {
+                requestId: payload.requestId,
+            }),
+            title: truncate(input.prompt ?? "Your answer", DISCORD_MODAL_TITLE_MAX_LENGTH),
+        },
+        type: DISCORD_INTERACTION_RESPONSE_TYPE.MODAL,
+    };
+}
+/** Returns true when a component custom id starts the freeform modal flow. */
+export function isDiscordFreeformComponent(customId) {
+    return decodeHitlCustomId(customId, DISCORD_HITL_FREEFORM_CUSTOM_ID_PREFIX) !== null;
+}
+/** Decodes one component interaction into HITL input responses. */
+export function deriveComponentInputResponses(interaction) {
+    const payload = decodeHitlCustomId(interaction.customId, DISCORD_HITL_CUSTOM_ID_PREFIX);
+    if (!payload)
+        return [];
+    if (payload.optionId !== undefined) {
+        return [{ optionId: payload.optionId, requestId: payload.requestId }];
+    }
+    const selected = interaction.values[0];
+    if (selected !== undefined) {
+        return [{ optionId: selected, requestId: payload.requestId }];
+    }
+    return [];
+}
+/** Decodes one modal submission into HITL input responses. */
+export function deriveModalInputResponses(interaction) {
+    const payload = decodeHitlCustomId(interaction.customId, DISCORD_HITL_FREEFORM_CUSTOM_ID_PREFIX);
+    const text = interaction.textInputs[DISCORD_HITL_FREEFORM_TEXT_INPUT_ID];
+    if (!payload || text === undefined)
+        return [];
+    return [{ requestId: payload.requestId, text }];
+}
+function encodeHitlCustomId(prefix, payload) {
+    const encoded = Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
+    const customId = `${prefix}${encoded}`;
+    if (customId.length > DISCORD_CUSTOM_ID_MAX_LENGTH) {
+        throw new Error("discordChannel: HITL custom_id exceeded Discord's 100-character limit.");
+    }
+    return customId;
+}
+function decodeHitlCustomId(customId, prefix) {
+    if (!customId.startsWith(prefix))
+        return null;
+    try {
+        const decoded = Buffer.from(customId.slice(prefix.length), "base64url").toString("utf8");
+        const parsed = JSON.parse(decoded);
+        if (typeof parsed.requestId !== "string" || parsed.requestId.length === 0)
+            return null;
+        const result = { requestId: parsed.requestId };
+        if (typeof parsed.optionId === "string") {
+            return { ...result, optionId: parsed.optionId };
+        }
+        return result;
+    }
+    catch {
+        return null;
+    }
+}
+function toDiscordButtonStyle(style) {
+    if (style === "primary")
+        return 1;
+    if (style === "danger")
+        return 4;
+    return 2;
+}
+function truncate(value, maxLength) {
+    if (value.length <= maxLength)
+        return value;
+    const sliceLength = Math.max(0, maxLength - 3);
+    return `${value.slice(0, sliceLength).trimEnd()}...`;
+}
+function chunk(values, size) {
+    const result = [];
+    for (let index = 0; index < values.length; index += size) {
+        result.push(values.slice(index, index + size));
+    }
+    return result;
+}