experimental-ash 0.10.2 → 0.10.3

package/dist/src/public/channels/slack/connections.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Slack rendering for `connection.authorization_*` events.
+ *
+ * The framework emits these when a tool call needs the user to complete
+ * an OAuth-style authorization flow (e.g. signing in to Linear). The
+ * channel's default handler posts:
+ *
+ * 1. An ephemeral "Sign in with X" link button to the triggering user
+ *    (when their id is known), surfacing the challenge URL.
+ * 2. A public "Connect with X to continue" status message visible to
+ *    everyone in the thread.
+ *
+ * When the matching `connection.authorization_completed` event arrives
+ * the public status message is edited in place to surface the outcome
+ * (`authorized` / `declined` / `failed` / `timed-out`).
+ */
+/**
+ * Outcomes carried on a `connection.authorization_completed` event.
+ * Mirrors the framework event shape so the renderer needs no extra
+ * imports.
+ */
+export type ConnectionAuthorizationOutcome = "authorized" | "declined" | "failed" | "timed-out";
+/**
+ * Title-cases a connection name (`linear` → `Linear`) for display. Empty
+ * strings pass through unchanged so the renderer never emits an empty
+ * label inside a sentence.
+ */
+export declare function formatConnectionDisplayName(connectionName: string): string;
+/**
+ * Public status text posted when an authorization challenge fires. When
+ * the channel cannot identify a triggering user (rare — schedule-initiated
+ * sessions or events that lack actor metadata) the text drops the
+ * "Connect with" call-to-action since there's no one to act on it.
+ */
+export declare function buildAuthRequiredPublicText(input: {
+    readonly displayName: string;
+    readonly hasUser: boolean;
+}): string;
+/**
+ * Final-state markdown for the previously-posted status message. Edited
+ * in place by `connection.authorization_completed` so the user sees
+ * resolution without scrolling.
+ */
+export declare function buildAuthCompletedText(input: {
+    readonly displayName: string;
+    readonly outcome: ConnectionAuthorizationOutcome;
+    readonly reason?: string;
+}): string;
+/**
+ * Block Kit blocks for the ephemeral "Sign in with X" link button.
+ * Slack ephemerals accept the same block list shape as regular messages
+ * so the helper returns blocks directly.
+ */
+export declare function buildAuthEphemeralBlocks(input: {
+    readonly displayName: string;
+    readonly url: string;
+}): unknown[];

package/dist/src/public/channels/slack/connections.js

@@ -0,0 +1,70 @@
+/**
+ * Slack rendering for `connection.authorization_*` events.
+ *
+ * The framework emits these when a tool call needs the user to complete
+ * an OAuth-style authorization flow (e.g. signing in to Linear). The
+ * channel's default handler posts:
+ *
+ * 1. An ephemeral "Sign in with X" link button to the triggering user
+ *    (when their id is known), surfacing the challenge URL.
+ * 2. A public "Connect with X to continue" status message visible to
+ *    everyone in the thread.
+ *
+ * When the matching `connection.authorization_completed` event arrives
+ * the public status message is edited in place to surface the outcome
+ * (`authorized` / `declined` / `failed` / `timed-out`).
+ */
+/**
+ * Title-cases a connection name (`linear` → `Linear`) for display. Empty
+ * strings pass through unchanged so the renderer never emits an empty
+ * label inside a sentence.
+ */
+export function formatConnectionDisplayName(connectionName) {
+    if (connectionName.length === 0)
+        return connectionName;
+    return connectionName.charAt(0).toUpperCase() + connectionName.slice(1);
+}
+/**
+ * Public status text posted when an authorization challenge fires. When
+ * the channel cannot identify a triggering user (rare — schedule-initiated
+ * sessions or events that lack actor metadata) the text drops the
+ * "Connect with" call-to-action since there's no one to act on it.
+ */
+export function buildAuthRequiredPublicText(input) {
+    if (!input.hasUser) {
+        return `Authorization required for ${input.displayName} (no triggering user)`;
+    }
+    return `Connect with ${input.displayName} to continue`;
+}
+/**
+ * Final-state markdown for the previously-posted status message. Edited
+ * in place by `connection.authorization_completed` so the user sees
+ * resolution without scrolling.
+ */
+export function buildAuthCompletedText(input) {
+    if (input.outcome === "authorized") {
+        return `:white_check_mark: ${input.displayName} connected`;
+    }
+    const tail = input.reason !== undefined ? ` (${input.reason})` : "";
+    return `:x: ${input.displayName} authorization ${input.outcome}${tail}`;
+}
+/**
+ * Block Kit blocks for the ephemeral "Sign in with X" link button.
+ * Slack ephemerals accept the same block list shape as regular messages
+ * so the helper returns blocks directly.
+ */
+export function buildAuthEphemeralBlocks(input) {
+    return [
+        {
+            type: "actions",
+            elements: [
+                {
+                    type: "button",
+                    text: { type: "plain_text", text: `Sign in with ${input.displayName}` },
+                    url: input.url,
+                    style: "primary",
+                },
+            ],
+        },
+    ];
+}

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

@@ -19,6 +19,28 @@ import type { InputRequest } from "#runtime/input/types.js";
  * interactive widgets can avoid collisions.
  */
 export declare const HITL_ACTION_PREFIX = "ash_input:";
+/**
+ * `action_id` prefix for the "Type your answer" button that opens a
+ * freeform-answer modal. Splitting the prefix from {@link HITL_ACTION_PREFIX}
+ * lets the route handler differentiate "this click is a final answer"
+ * (resolve via `inputResponses`) from "this click needs a modal first"
+ * (call `views.open`, then resolve on `view_submission`).
+ */
+export declare const HITL_FREEFORM_ACTION_PREFIX = "ash_input_freeform:";
+/**
+ * `view.callback_id` carried on the freeform-answer modal. Used to
+ * route the inbound `view_submission` back to this channel.
+ */
+export declare const HITL_FREEFORM_MODAL_CALLBACK_ID = "ash_input_freeform_submit";
+/**
+ * `block_id` of the modal's text-input block — the route reads the
+ * submitted text out of `view.state.values[block_id][action_id]`.
+ */
+export declare const HITL_FREEFORM_MODAL_BLOCK_ID = "ash_freeform_block";
+/**
+ * `action_id` of the text input inside the freeform answer modal.
+ */
+export declare const HITL_FREEFORM_MODAL_ACTION_ID = "ash_freeform_text";
 /**
  * Subset of one Slack interactivity action the HITL decoder reads.
  * Mirrors the relevant fields of `SlackInteractionAction`.
@@ -61,7 +83,59 @@ export declare function isHitlAction(actionId: string): boolean;
  *   dropdown so the picker stays scrollable.
  * - Anything else with options → buttons. Best for visually distinct
  *   choices (approve / deny / cancel).
+ * - No options (or `allowFreeform: true`) → a single "Type your answer"
+ *   button that opens a Slack modal with a plain_text_input. The modal
+ *   submission comes back as a `view_submission` webhook the channel
+ *   resolves into an {@link InputResponse} carrying `text`.
  *
  * Always emits at least the prompt section.
  */
 export declare function renderInputRequestBlocks(request: InputRequest): unknown[];
+/**
+ * Metadata round-tripped on the freeform-answer modal's
+ * `private_metadata` field. Threaded from the button click that opens
+ * the modal to the `view_submission` that closes it so the route can
+ * deliver the answer back to the right session.
+ */
+export interface HitlFreeformModalMetadata {
+    readonly continuationToken: string;
+    readonly channelId: string;
+    readonly threadTs: string;
+    readonly messageTs: string;
+    readonly requestId: string;
+}
+/**
+ * Builds the `views.open` payload for the freeform-answer modal. The
+ * triggering `prompt` is preserved as a header section so the user can
+ * re-read what they're answering inside the modal.
+ *
+ * Title is auto-truncated to the Slack modal-title limit.
+ */
+export declare function buildFreeformModalView(input: {
+    readonly metadata: HitlFreeformModalMetadata;
+    readonly prompt?: string;
+}): Record<string, unknown>;
+/**
+ * True when an `action_id` was minted by the framework's freeform-answer
+ * button (the click that opens a modal — not the final answer).
+ */
+export declare function isFreeformAction(actionId: string): boolean;
+/**
+ * Extracts the requestId from a freeform-answer button's `action_id`.
+ */
+export declare function freeformRequestIdFromActionId(actionId: string): string | undefined;
+/**
+ * Renders the "answered" replacement blocks for a previously-posted
+ * HITL card. Preserves the original prompt block (so context stays
+ * visible), appends a confirmation line naming the chosen answer, and
+ * attributes the click to the user when their id is known.
+ *
+ * Slack's `chat.update` replaces every block in one shot, so the caller
+ * passes the full list to `blocks` and the rendered fallback text to
+ * `text`.
+ */
+export declare function buildAnsweredBlocks(input: {
+    readonly promptBlock: unknown;
+    readonly answerLabel: string;
+    readonly userId?: string;
+}): unknown[];

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

@@ -12,12 +12,35 @@
  * picks whichever is set so the renderer can pick a widget kind on
  * UX grounds without changing the read path.
  */
+import { truncateModalTitle, truncatePlainText } from "#public/channels/slack/limits.js";
 /**
  * Wire-format prefix every framework HITL widget mints onto its
  * `action_id`. Exposed so end-user adapters that render their own
  * interactive widgets can avoid collisions.
  */
 export const HITL_ACTION_PREFIX = "ash_input:";
+/**
+ * `action_id` prefix for the "Type your answer" button that opens a
+ * freeform-answer modal. Splitting the prefix from {@link HITL_ACTION_PREFIX}
+ * lets the route handler differentiate "this click is a final answer"
+ * (resolve via `inputResponses`) from "this click needs a modal first"
+ * (call `views.open`, then resolve on `view_submission`).
+ */
+export const HITL_FREEFORM_ACTION_PREFIX = "ash_input_freeform:";
+/**
+ * `view.callback_id` carried on the freeform-answer modal. Used to
+ * route the inbound `view_submission` back to this channel.
+ */
+export const HITL_FREEFORM_MODAL_CALLBACK_ID = "ash_input_freeform_submit";
+/**
+ * `block_id` of the modal's text-input block — the route reads the
+ * submitted text out of `view.state.values[block_id][action_id]`.
+ */
+export const HITL_FREEFORM_MODAL_BLOCK_ID = "ash_freeform_block";
+/**
+ * `action_id` of the text input inside the freeform answer modal.
+ */
+export const HITL_FREEFORM_MODAL_ACTION_ID = "ash_freeform_text";
 /**
  * Maximum radio-button option count before the renderer falls back to
  * a `static_select` dropdown. Matches Slack's UX guidance (radio
@@ -54,6 +77,10 @@ export function isHitlAction(actionId) {
  *   dropdown so the picker stays scrollable.
  * - Anything else with options → buttons. Best for visually distinct
  *   choices (approve / deny / cancel).
+ * - No options (or `allowFreeform: true`) → a single "Type your answer"
+ *   button that opens a Slack modal with a plain_text_input. The modal
+ *   submission comes back as a `view_submission` webhook the channel
+ *   resolves into an {@link InputResponse} carrying `text`.
  *
  * Always emits at least the prompt section.
  */
@@ -61,10 +88,8 @@ export function renderInputRequestBlocks(request) {
     const prompt = { text: { text: request.prompt, type: "mrkdwn" }, type: "section" };
     const actionId = `${HITL_ACTION_PREFIX}${request.requestId}`;
     const options = request.options;
-    if (!options || options.length === 0) {
-        return [prompt];
-    }
-    if (request.display === "select") {
+    const acceptsFreeform = request.allowFreeform === true || !options || options.length === 0;
+    if (options && options.length > 0 && request.display === "select") {
         const widget = options.length <= RADIO_SELECT_OPTION_LIMIT
             ? { type: "radio_buttons", action_id: actionId, options: options.map(buildOption) }
             : {
@@ -75,12 +100,86 @@ export function renderInputRequestBlocks(request) {
             };
         return [prompt, { type: "actions", elements: [widget] }];
     }
-    return [prompt, { type: "actions", elements: options.map((opt) => buildButton(opt, actionId)) }];
+    if (options && options.length > 0) {
+        return [
+            prompt,
+            { type: "actions", elements: options.map((opt) => buildButton(opt, actionId)) },
+        ];
+    }
+    if (acceptsFreeform) {
+        return [
+            prompt,
+            {
+                type: "actions",
+                elements: [
+                    {
+                        type: "button",
+                        action_id: `${HITL_FREEFORM_ACTION_PREFIX}${request.requestId}`,
+                        text: { type: "plain_text", text: "Type your answer" },
+                        style: "primary",
+                        value: request.requestId,
+                    },
+                ],
+            },
+        ];
+    }
+    return [prompt];
+}
+/**
+ * Builds the `views.open` payload for the freeform-answer modal. The
+ * triggering `prompt` is preserved as a header section so the user can
+ * re-read what they're answering inside the modal.
+ *
+ * Title is auto-truncated to the Slack modal-title limit.
+ */
+export function buildFreeformModalView(input) {
+    const title = input.prompt ? truncateModalTitle(input.prompt) : "Your answer";
+    const promptBlocks = input.prompt
+        ? [{ type: "section", text: { type: "mrkdwn", text: input.prompt } }]
+        : [];
+    return {
+        type: "modal",
+        callback_id: HITL_FREEFORM_MODAL_CALLBACK_ID,
+        private_metadata: JSON.stringify(input.metadata),
+        title: { type: "plain_text", text: title },
+        submit: { type: "plain_text", text: "Submit" },
+        close: { type: "plain_text", text: "Cancel" },
+        blocks: [
+            ...promptBlocks,
+            {
+                type: "input",
+                block_id: HITL_FREEFORM_MODAL_BLOCK_ID,
+                element: {
+                    type: "plain_text_input",
+                    action_id: HITL_FREEFORM_MODAL_ACTION_ID,
+                    multiline: true,
+                    placeholder: { type: "plain_text", text: "Type your answer here..." },
+                },
+                label: { type: "plain_text", text: "Answer" },
+            },
+        ],
+    };
+}
+/**
+ * True when an `action_id` was minted by the framework's freeform-answer
+ * button (the click that opens a modal — not the final answer).
+ */
+export function isFreeformAction(actionId) {
+    return actionId.startsWith(HITL_FREEFORM_ACTION_PREFIX);
+}
+/**
+ * Extracts the requestId from a freeform-answer button's `action_id`.
+ */
+export function freeformRequestIdFromActionId(actionId) {
+    if (!isFreeformAction(actionId))
+        return undefined;
+    const slice = actionId.slice(HITL_FREEFORM_ACTION_PREFIX.length);
+    return slice.length > 0 ? slice : undefined;
 }
 function buildButton(opt, actionId) {
     const button = {
         action_id: actionId,
-        text: { text: opt.label, type: "plain_text" },
+        text: { text: truncatePlainText(opt.label), type: "plain_text" },
         type: "button",
         value: opt.id,
     };
@@ -91,11 +190,39 @@ function buildButton(opt, actionId) {
 }
 function buildOption(opt) {
     const option = {
-        text: { text: opt.label, type: "plain_text" },
+        text: { text: truncatePlainText(opt.label), type: "plain_text" },
         value: opt.id,
     };
-    if (opt.description && opt.description.length > 0) {
-        option.description = { text: opt.description, type: "plain_text" };
+    const description = truncatePlainText(opt.description);
+    if (description && description.length > 0) {
+        option.description = { text: description, type: "plain_text" };
     }
     return option;
 }
+/**
+ * Renders the "answered" replacement blocks for a previously-posted
+ * HITL card. Preserves the original prompt block (so context stays
+ * visible), appends a confirmation line naming the chosen answer, and
+ * attributes the click to the user when their id is known.
+ *
+ * Slack's `chat.update` replaces every block in one shot, so the caller
+ * passes the full list to `blocks` and the rendered fallback text to
+ * `text`.
+ */
+export function buildAnsweredBlocks(input) {
+    const blocks = [];
+    if (input.promptBlock !== undefined && input.promptBlock !== null) {
+        blocks.push(input.promptBlock);
+    }
+    blocks.push({
+        type: "section",
+        text: { type: "mrkdwn", text: `:white_check_mark: *${input.answerLabel}*` },
+    });
+    if (input.userId && input.userId.length > 0) {
+        blocks.push({
+            type: "context",
+            elements: [{ type: "mrkdwn", text: `Answered by <@${input.userId}>` }],
+        });
+    }
+    return blocks;
+}

package/dist/src/public/channels/slack/inbound.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Inbound mention-text shaping.
+ *
+ * The channel calls these helpers on every inbound `app_mention` before
+ * handing the text to {@link buildSlackTurnMessage}:
+ *
+ * 1. {@link renderInboundText} converts the chat SDK's formatted AST
+ *    back to GFM so the agent sees `[label](url)` / `**bold**` /
+ *    bullets / mentions instead of the raw `<@U…>` / `<https://…|…>`
+ *    fragments that `message.text` strips formatting down to.
+ * 2. {@link prependSlackContext} attaches a `<slack_context>` block
+ *    naming the actor, channel, and thread so the agent's prompt always
+ *    knows who and where it is talking.
+ */
+import { type Message } from "#compiled/chat/index.js";
+import type { UserContent } from "ai";
+/**
+ * Verified inbound identity used to render a `<slack_context>` block.
+ *
+ * Channel-owned shape so the helper does not depend on the chat SDK
+ * `Message` type (and is therefore trivially testable in isolation).
+ */
+export interface SlackInboundContext {
+    readonly userId: string;
+    readonly userName?: string;
+    readonly fullName?: string;
+    readonly channelId: string;
+    readonly threadTs: string;
+    readonly teamId?: string;
+}
+/**
+ * Re-renders a chat SDK message back to GFM markdown.
+ *
+ * The chat SDK parses Slack's inbound mrkdwn into a structured AST on
+ * `message.formatted`. Stringifying that AST preserves hyperlinks,
+ * mentions, and inline emphasis that `message.text` strips. Falls back
+ * to `message.text` when the AST is missing or fails to stringify so a
+ * misbehaving formatter never blocks an inbound turn.
+ */
+export declare function renderInboundText(message: Message): string;
+/**
+ * Renders one {@link SlackInboundContext} as a `<slack_context>` block.
+ * Lines are deterministic and tag-delimited so the agent can pattern-match
+ * the block out of its prompt if it wants to.
+ */
+export declare function formatSlackContextBlock(context: SlackInboundContext): string;
+/**
+ * Prepends a `<slack_context>` block to the inbound turn message.
+ *
+ * Accepts either a raw string (no attachments) or a {@link UserContent}
+ * array (text + file parts). In the array case the context block lands
+ * as the first {@link TextPart} — followed by the original parts — so
+ * attachments stay intact.
+ */
+export declare function prependSlackContext(message: string | UserContent, context: SlackInboundContext): string | UserContent;

package/dist/src/public/channels/slack/inbound.js

@@ -0,0 +1,75 @@
+/**
+ * Inbound mention-text shaping.
+ *
+ * The channel calls these helpers on every inbound `app_mention` before
+ * handing the text to {@link buildSlackTurnMessage}:
+ *
+ * 1. {@link renderInboundText} converts the chat SDK's formatted AST
+ *    back to GFM so the agent sees `[label](url)` / `**bold**` /
+ *    bullets / mentions instead of the raw `<@U…>` / `<https://…|…>`
+ *    fragments that `message.text` strips formatting down to.
+ * 2. {@link prependSlackContext} attaches a `<slack_context>` block
+ *    naming the actor, channel, and thread so the agent's prompt always
+ *    knows who and where it is talking.
+ */
+import { stringifyMarkdown } from "#compiled/chat/index.js";
+import { createLogger } from "#internal/logging.js";
+const log = createLogger("slack.inbound");
+/**
+ * Re-renders a chat SDK message back to GFM markdown.
+ *
+ * The chat SDK parses Slack's inbound mrkdwn into a structured AST on
+ * `message.formatted`. Stringifying that AST preserves hyperlinks,
+ * mentions, and inline emphasis that `message.text` strips. Falls back
+ * to `message.text` when the AST is missing or fails to stringify so a
+ * misbehaving formatter never blocks an inbound turn.
+ */
+export function renderInboundText(message) {
+    const fallback = typeof message.text === "string" ? message.text : "";
+    const formatted = message.formatted;
+    if (formatted === null || formatted === undefined) {
+        return fallback;
+    }
+    try {
+        const rendered = stringifyMarkdown(formatted).trim();
+        return rendered.length > 0 ? rendered : fallback;
+    }
+    catch (error) {
+        log.warn("stringifyMarkdown failed — falling back to plain text", { error });
+        return fallback;
+    }
+}
+/**
+ * Renders one {@link SlackInboundContext} as a `<slack_context>` block.
+ * Lines are deterministic and tag-delimited so the agent can pattern-match
+ * the block out of its prompt if it wants to.
+ */
+export function formatSlackContextBlock(context) {
+    const lines = [
+        "<slack_context>",
+        `user_id: ${context.userId}`,
+        ...(context.userName ? [`user_name: ${context.userName}`] : []),
+        ...(context.fullName ? [`full_name: ${context.fullName}`] : []),
+        `channel_id: ${context.channelId}`,
+        `thread_ts: ${context.threadTs}`,
+        ...(context.teamId ? [`team_id: ${context.teamId}`] : []),
+        "</slack_context>",
+    ];
+    return lines.join("\n");
+}
+/**
+ * Prepends a `<slack_context>` block to the inbound turn message.
+ *
+ * Accepts either a raw string (no attachments) or a {@link UserContent}
+ * array (text + file parts). In the array case the context block lands
+ * as the first {@link TextPart} — followed by the original parts — so
+ * attachments stay intact.
+ */
+export function prependSlackContext(message, context) {
+    const block = formatSlackContextBlock(context);
+    if (typeof message === "string") {
+        return message.length > 0 ? `${block}\n\n${message}` : block;
+    }
+    const contextPart = { type: "text", text: block };
+    return [contextPart, ...message];
+}

package/dist/src/public/channels/slack/index.d.ts

@@ -1,4 +1,4 @@
 export { slack, type SlackOptions } from "#public/channels/slack/slack.js";
-export { slackChannel, type SlackApiHandle, type SlackApiResponse, type SlackChannel, type SlackChannelConfig, type SlackChannelEvents, type SlackChannelCredentials, type SlackChannelState, type SlackContext, type SlackInteractionAction, type SlackReceiveArgs, type SlackStateAdapter, type SlackWebhookVerifier, } from "#public/channels/slack/slackChannel.js";
+export { slackChannel, type SlackApiHandle, type SlackApiResponse, type SlackChannel, type SlackChannelConfig, type SlackChannelEvents, type SlackChannelCredentials, type SlackChannelState, type SlackContext, type SlackEventContext, type SlackInteractionAction, type SlackReceiveArgs, type SlackStateAdapter, type SlackWebhookVerifier, } from "#public/channels/slack/slackChannel.js";
 export { Actions, Button, Card, CardText, Divider, Fields, Image, LinkButton, Modal, RadioSelect, Section, Select, SelectOption, Table, TextInput, } from "#compiled/chat/index.js";
 export type { AdapterPostableMessage, Attachment, Author, CardElement, FileUpload, Message, PostableMessage, SentMessage, Thread, } from "#compiled/chat/index.js";

package/dist/src/public/channels/slack/interactions.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Slack `block_actions` + `view_submission` wire handling.
+ *
+ * The route handler reads the form-encoded body, hands it here, and we:
+ *
+ * 1. Decode `block_actions` payloads into a typed shape the channel can
+ *    work with — actions, channel/thread metadata, the clicker, and the
+ *    full original block list for answered-card updates.
+ * 2. Open the freeform-answer modal inline when the click was a "Type
+ *    your answer" button (Slack's `trigger_id` is only valid for ~3s,
+ *    so this can't run under `waitUntil`).
+ * 3. Resolve `view_submission` payloads (freeform modal submissions)
+ *    back into parked HITL requests via `send`.
+ *
+ * Anything we don't consume flows through to the user-supplied
+ * `onInteraction` callback. Always returns `Response("ok")` — followup
+ * work runs under `waitUntil` so the webhook ACK is immediate.
+ */
+import type { Message } from "#compiled/chat/index.js";
+import type { SlackChannelConfig, SlackChannelState, SlackInteractionAction } from "#public/channels/slack/slackChannel.js";
+import type { SendFn } from "#public/definitions/defineChannel.js";
+/**
+ * Decoded view of a Slack `block_actions` payload. Returned by
+ * {@link parseBlockActionsPayload} and read by the handler.
+ */
+interface ParsedBlockActionsPayload {
+    readonly actions: SlackInteractionAction[];
+    readonly channelId: string;
+    readonly threadTs: string;
+    readonly teamId: string | undefined;
+    /**
+     * Slack actor that authored the click. Used to attribute the answered
+     * card via `Answered by <@userId>` after a HITL response is delivered.
+     */
+    readonly userId: string | undefined;
+    /**
+     * The full block list off the clicked message. Preserved on the
+     * answered-card update so the original prompt stays visible after the
+     * interactive controls are stripped.
+     */
+    readonly messageBlocks: readonly unknown[];
+}
+/**
+ * Decodes a Slack `block_actions` payload into a {@link ParsedBlockActionsPayload}.
+ * Returns `null` for payloads that don't carry the channel/thread
+ * metadata the handler needs.
+ */
+export declare function parseBlockActionsPayload(body: Record<string, unknown>): ParsedBlockActionsPayload | null;
+/**
+ * Channel-supplied dependencies for {@link handleInteractionPost}.
+ *
+ * Carries the bits the handler needs that come from channel
+ * construction: credentials for outbound API calls, the user's
+ * `onInteraction` callback for non-HITL clicks, and a chat-SDK module
+ * supplier so the handler can build a thread for the user callback
+ * without statically depending on `#compiled/chat/index.js`.
+ */
+export interface InteractionHandlerDeps {
+    readonly config: SlackChannelConfig;
+    readonly loadChatModule: () => Promise<typeof import("#compiled/chat/index.js")>;
+}
+/**
+ * Entry point for Slack's form-encoded interactivity endpoint. Routes
+ * `view_submission` payloads to the freeform-answer flow, intercepts
+ * "Type your answer" button clicks to open a modal, resolves
+ * framework HITL clicks against the parked session, and forwards
+ * anything else to `config.onInteraction`.
+ */
+export declare function handleInteractionPost(rawBody: string, ctx: {
+    send: SendFn<SlackChannelState>;
+    waitUntil: (task: Promise<unknown>) => void;
+}, deps: InteractionHandlerDeps): Promise<Response>;
+export type { ParsedBlockActionsPayload };
+export type { Message };