experimental-ash 0.10.4 → 0.11.0

package/dist/src/internal/application/package.js

@@ -6,7 +6,7 @@ import { ASH_PACKAGE_NAME } from "#package-name.js";
 let cachedPackageInfo;
 // The package build stamps the published version into `dist` so bundled
 // deployments can still report package metadata without resolving package.json.
-const BUNDLED_FALLBACK_PACKAGE_VERSION = "0.10.4";
+const BUNDLED_FALLBACK_PACKAGE_VERSION = "0.11.0";
 const BUNDLED_FALLBACK_PACKAGE_VERSION_PLACEHOLDER = "__ASH_PACKAGE_VERSION_PLACEHOLDER__";
 const WORKFLOW_MODULE_ALIASES = {
     "workflow/api": "src/compiled/@workflow/core/runtime.js",

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

@@ -0,0 +1,28 @@
+import type { SessionAuthContext } from "#channel/types.js";
+import type { Message } from "#compiled/chat/index.js";
+import type { SlackChannelEvents, SlackContext, SlackMentionResult } from "#public/channels/slack/slackChannel.js";
+/**
+ * Workspace-scoped projection of the Slack actor that produced
+ * `message`. Used by {@link defaultOnMention} to derive a
+ * {@link SessionAuthContext} when the customer hasn't supplied their
+ * own `onMention`.
+ */
+export declare function defaultSlackAuth(message: Message, ctx: SlackContext): SessionAuthContext | null;
+/**
+ * Default `onMention` — derives auth from the Slack actor and posts a
+ * `"Thinking…"` typing indicator before the workflow runtime starts.
+ */
+export declare function defaultOnMention(ctx: SlackContext, message: Message): Promise<SlackMentionResult>;
+/**
+ * Default `input.requested` handler — renders each pending HITL
+ * request as Slack `block_actions`. Buttons by default; radio for
+ * ≤6-option select requests; static_select for >6-option select
+ * requests. Override by declaring `events["input.requested"]`.
+ */
+export declare function defaultInputRequestedHandler(): NonNullable<SlackChannelEvents["input.requested"]>;
+/**
+ * Built-in Slack event handlers — typing indicators, error replies,
+ * and the connection-authorization status flow. Each is overridable
+ * per-event by passing the same key under `slackChannel({ events })`.
+ */
+export declare const defaultEvents: SlackChannelEvents;

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

@@ -0,0 +1,223 @@
+import { createLogger, extractErrorId, formatErrorHint } from "#internal/logging.js";
+import { decodeThreadId } from "#public/channels/slack/api.js";
+import { buildAuthCompletedText, buildAuthEphemeralBlocks, buildAuthRequiredPublicText, formatConnectionDisplayName, } from "#public/channels/slack/connections.js";
+import { renderInputRequestBlocks } from "#public/channels/slack/hitl.js";
+import { truncateTypingStatus } from "#public/channels/slack/limits.js";
+const log = createLogger("slack.defaults");
+function readTeamId(message) {
+    const raw = message.raw;
+    const teamId = raw?.team_id ?? raw?.team;
+    return typeof teamId === "string" && teamId.length > 0 ? teamId : undefined;
+}
+/**
+ * Workspace-scoped projection of the Slack actor that produced
+ * `message`. Used by {@link defaultOnMention} to derive a
+ * {@link SessionAuthContext} when the customer hasn't supplied their
+ * own `onMention`.
+ */
+export function defaultSlackAuth(message, ctx) {
+    const author = message.author;
+    if (!author)
+        return null;
+    const teamId = readTeamId(message);
+    const isBot = author.isBot === true;
+    const userId = String(author.userId);
+    const principalId = teamId
+        ? isBot
+            ? `slack:${teamId}:bot:${userId}`
+            : `slack:${teamId}:${userId}`
+        : isBot
+            ? `slack:bot:${userId}`
+            : `slack:${userId}`;
+    const attributes = {
+        author_type: isBot ? "bot" : "user",
+        channel_id: ctx.slack.channelId,
+        thread_ts: ctx.slack.threadTs,
+        user_id: userId,
+    };
+    if (typeof author.userName === "string" && author.userName.length > 0) {
+        attributes.user_name = author.userName;
+    }
+    if (typeof author.fullName === "string" && author.fullName.length > 0) {
+        attributes.full_name = author.fullName;
+    }
+    if (teamId !== undefined) {
+        attributes.team_id = teamId;
+    }
+    return {
+        attributes,
+        authenticator: "slack-webhook",
+        issuer: teamId !== undefined ? `slack:${teamId}` : "slack",
+        principalId,
+        principalType: isBot ? "service" : "user",
+    };
+}
+/**
+ * Default `onMention` — derives auth from the Slack actor and posts a
+ * `"Thinking…"` typing indicator before the workflow runtime starts.
+ */
+export async function defaultOnMention(ctx, message) {
+    await ctx.thread.startTyping("Thinking...");
+    return { auth: defaultSlackAuth(message, ctx) };
+}
+/**
+ * Reads the first non-empty line of a model-emitted message. The
+ * default `actions.requested` handler uses this to surface the
+ * model's own pre-tool-call narration as the typing indicator.
+ */
+function firstNonEmptyLine(text) {
+    for (const line of text.split(/\r?\n/u)) {
+        const trimmed = line.trim();
+        if (trimmed.length > 0)
+            return trimmed;
+    }
+    return undefined;
+}
+/**
+ * Default `input.requested` handler — renders each pending HITL
+ * request as Slack `block_actions`. Buttons by default; radio for
+ * ≤6-option select requests; static_select for >6-option select
+ * requests. Override by declaring `events["input.requested"]`.
+ */
+export function defaultInputRequestedHandler() {
+    return async (data, ctx) => {
+        if (data.requests.length === 0)
+            return;
+        const decoded = decodeThreadId(ctx.thread.id ?? "");
+        await ctx.slack.request("chat.postMessage", {
+            channel: decoded.channelId,
+            thread_ts: decoded.threadTs,
+            blocks: data.requests.flatMap(renderInputRequestBlocks),
+            text: data.requests.map((r) => r.prompt).join("\n"),
+        });
+    };
+}
+/**
+ * Built-in Slack event handlers — typing indicators, error replies,
+ * and the connection-authorization status flow. Each is overridable
+ * per-event by passing the same key under `slackChannel({ events })`.
+ */
+export const defaultEvents = {
+    async "turn.started"(_event, ctx) {
+        ctx.state.pendingToolCallMessage = null;
+        await ctx.thread.startTyping("Working...");
+    },
+    async "actions.requested"(event, ctx) {
+        const buffered = ctx.state.pendingToolCallMessage;
+        ctx.state.pendingToolCallMessage = null;
+        if (buffered) {
+            await ctx.thread.startTyping(truncateTypingStatus(buffered));
+            return;
+        }
+        const labels = event.actions.map((a) => (a.kind === "tool-call" ? a.toolName : a.kind));
+        await ctx.thread.startTyping(truncateTypingStatus(`Running ${labels.join(", ")}...`));
+    },
+    async "message.completed"(event, ctx) {
+        if (event.finishReason === "tool-calls") {
+            // Buffer the model's prose so `actions.requested` can surface
+            // it as the typing indicator. Don't post — there's no
+            // user-visible answer yet, just narration before a tool call.
+            ctx.state.pendingToolCallMessage = event.message
+                ? (firstNonEmptyLine(event.message) ?? null)
+                : null;
+            return;
+        }
+        ctx.state.pendingToolCallMessage = null;
+        if (event.message)
+            await ctx.thread.post({ markdown: event.message });
+    },
+    async "turn.failed"(event, ctx) {
+        const hint = formatErrorHint(event);
+        const errorId = extractErrorId(event.details);
+        await ctx.thread.post({
+            markdown: [
+                `I hit an error while handling your request${hint}.`,
+                "",
+                "Please try again, rephrase, or reach out if it keeps failing.",
+                ...(errorId ? ["", `_Error id: \`${errorId}\`_`] : []),
+            ].join("\n"),
+        });
+    },
+    async "session.failed"(event, ctx) {
+        const hint = formatErrorHint(event);
+        const errorId = extractErrorId(event.details);
+        await ctx.thread.post({
+            markdown: [
+                `This session couldn't recover from an error${hint}.`,
+                "",
+                "Start a new thread to continue — I can't pick this one back up.",
+                ...(errorId ? ["", `_Error id: \`${errorId}\`_`] : []),
+            ].join("\n"),
+        });
+    },
+    async "connection.authorization_required"(event, ctx) {
+        const displayName = formatConnectionDisplayName(event.connectionName);
+        const triggeringUserId = ctx.state.triggeringUserId ?? null;
+        const challengeUrl = event.authorization?.url;
+        if (triggeringUserId && challengeUrl) {
+            try {
+                await ctx.slack.request("chat.postEphemeral", {
+                    channel: ctx.slack.channelId,
+                    user: triggeringUserId,
+                    thread_ts: ctx.slack.threadTs,
+                    blocks: buildAuthEphemeralBlocks({ displayName, url: challengeUrl }),
+                    text: `Sign in with ${displayName}: ${challengeUrl}`,
+                });
+            }
+            catch (error) {
+                log.error("Slack auth ephemeral delivery failed", {
+                    connectionName: event.connectionName,
+                    error,
+                });
+            }
+        }
+        const publicText = buildAuthRequiredPublicText({
+            displayName,
+            hasUser: triggeringUserId !== null,
+        });
+        try {
+            const sent = await ctx.thread.post({ markdown: publicText });
+            const sentId = sent && typeof sent === "object" && "id" in sent ? sent.id : undefined;
+            if (typeof sentId === "string") {
+                ctx.state.pendingAuthMessageTs = {
+                    ...ctx.state.pendingAuthMessageTs,
+                    [event.connectionName]: sentId,
+                };
+            }
+        }
+        catch (error) {
+            log.error("Slack auth public message delivery failed", {
+                connectionName: event.connectionName,
+                error,
+            });
+        }
+    },
+    async "connection.authorization_completed"(event, ctx) {
+        const pending = ctx.state.pendingAuthMessageTs ?? {};
+        const ts = pending[event.connectionName];
+        if (ts === undefined)
+            return;
+        const displayName = formatConnectionDisplayName(event.connectionName);
+        const text = buildAuthCompletedText({
+            displayName,
+            outcome: event.outcome,
+            reason: event.reason,
+        });
+        try {
+            await ctx.slack.request("chat.update", {
+                channel: ctx.slack.channelId,
+                ts,
+                text,
+            });
+        }
+        catch (error) {
+            log.error("Slack auth status edit failed", {
+                connectionName: event.connectionName,
+                error,
+            });
+        }
+        const next = { ...pending };
+        delete next[event.connectionName];
+        ctx.state.pendingAuthMessageTs = next;
+    },
+};

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

@@ -1,4 +1,3 @@
-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 SlackEventContext, 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 SlackMentionResult, type SlackMentionResultOrPromise, 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/index.js

@@ -1,3 +1,2 @@
-export { slack } from "#public/channels/slack/slack.js";
 export { slackChannel, } 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";

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

@@ -1,3 +1,4 @@
+import type { SessionAuthContext } from "#channel/types.js";
 import { type SlackBotToken } from "#compiled/@chat-adapter/slack/index.js";
 import { type Message, type SerializedThread, type StateAdapter, type Thread } from "#compiled/chat/index.js";
 import type { HandleMessageStreamEvent } from "#protocol/message.js";
@@ -9,7 +10,7 @@ type EventData<T extends HandleMessageStreamEvent["type"]> = Extract<HandleMessa
     data: infer D;
 } ? D : undefined;
 /**
- * Pre-dispatch Slack context — handed to `run`, `onMention`, and
+ * Pre-dispatch Slack context — handed to `onMention` and
  * `onInteraction`. These hooks run on the inbound webhook side, before
  * the runtime hydrates any session state, so `state` is intentionally
  * absent here.
@@ -124,10 +125,15 @@ export interface SlackInteractionAction {
      */
     readonly label?: string;
 }
-export type SlackRunResult = {
-    auth: import("#channel/types.js").SessionAuthContext | null;
+/**
+ * Result of an `onMention` callback. Return `{ auth }` (auth may be
+ * `null`) to dispatch a turn with that session auth context, or `null`
+ * to silently drop the mention.
+ */
+export type SlackMentionResult = {
+    auth: SessionAuthContext | null;
 } | null;
-export type SlackRunResultOrPromise = SlackRunResult | Promise<SlackRunResult>;
+export type SlackMentionResultOrPromise = SlackMentionResult | Promise<SlackMentionResult>;
 export interface SlackChannelEvents {
     readonly "turn.started"?: SlackEventHandler<"turn.started">;
     readonly "actions.requested"?: SlackEventHandler<"actions.requested">;
@@ -170,25 +176,25 @@ export interface SlackChannelConfig {
      */
     readonly uploadPolicy?: Partial<UploadPolicy>;
     /**
-     * Synchronous-or-async filter and auth resolver invoked the moment a
-     * Slack `app_mention` arrives, before the framework dispatches a
-     * turn. Return `{ auth }` to dispatch with that session auth context,
-     * or `null` to silently drop the mention. Runs on the inbound webhook
-     * side, so cold-start latency does not affect it.
-     */
-    run?(ctx: SlackContext, message: Message): SlackRunResultOrPromise;
-    /**
-     * Free-form pre-dispatch hook invoked after `run()` accepts but
-     * before the framework enqueues the turn. Use it for side effects
-     * that should fire on the inbound webhook side — for example,
-     * starting a typing indicator so the user sees feedback before the
-     * workflow runtime cold-starts.
+     * Invoked the moment a Slack `app_mention` arrives, before the
+     * framework dispatches a turn. Decides whether to dispatch and
+     * with what auth, and may perform pre-dispatch side effects (e.g.
+     * `ctx.thread.startTyping("Thinking…")`) on the inbound webhook
+     * side before the workflow runtime cold-starts.
      *
-     * The framework awaits this handler and catches thrown errors (the
-     * turn still dispatches if `onMention` throws). It does not alter
-     * dispatch — to skip a turn, return `null` from `run()`.
+     * Return `{ auth }` to dispatch with that session auth context, or
+     * `null` to silently drop the mention. May be sync or async; the
+     * framework awaits the result before dispatching.
+     *
+     * Thrown errors are caught and logged, and the mention is dropped
+     * (no dispatch). Wrap best-effort side effects in `try/catch` if
+     * you want them to be non-fatal.
+     *
+     * Defaults to a workspace-scoped auth derivation that posts a
+     * `"Thinking…"` typing indicator. Replacing this option fully
+     * replaces both behaviors.
      */
-    onMention?(ctx: SlackContext, message: Message): void | Promise<void>;
+    onMention?(ctx: SlackContext, message: Message): SlackMentionResultOrPromise;
     /**
      * Handler for Slack `block_actions` interactive callbacks (button
      * clicks, select changes, etc.) that are **not** consumed by the
@@ -222,5 +228,15 @@ export interface SlackChannelConfig {
  */
 export interface SlackChannel extends Channel<SlackChannelState> {
 }
+/**
+ * Slack channel factory. Wires up the Slack webhook route, mention
+ * dispatch, interaction handling, and a baseline set of typing /
+ * error / connection-auth event handlers.
+ *
+ * Defaults apply per field — pass `onMention` to fully replace the
+ * default mention pipeline (auth derivation + `"Thinking…"` typing),
+ * or pass an `events[type]` handler to replace only that one event.
+ * Fields you don't supply keep their defaults.
+ */
 export declare function slackChannel(config?: SlackChannelConfig): SlackChannel;
 export {};

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

@@ -4,7 +4,7 @@ import { ThreadImpl, } from "#compiled/chat/index.js";
 import { createLogger } from "#internal/logging.js";
 import { buildSlackApiHandle, decodeThreadId } from "#public/channels/slack/api.js";
 import { buildSlackTurnMessage, collectInboundFileParts, createSlackFetchFile, } from "#public/channels/slack/attachments.js";
-import { renderInputRequestBlocks } from "#public/channels/slack/hitl.js";
+import { defaultEvents, defaultInputRequestedHandler, defaultOnMention, } from "#public/channels/slack/defaults.js";
 import { prependSlackContext, renderInboundText, } from "#public/channels/slack/inbound.js";
 import { handleInteractionPost } from "#public/channels/slack/interactions.js";
 import { mergeUploadPolicy } from "#public/channels/upload-policy.js";
@@ -51,25 +51,6 @@ function rebuildSlackContext(state, credentials, stateAdapter) {
         state,
     };
 }
-/**
- * Default `input.requested` handler — renders each pending HITL
- * request as Slack `block_actions`. Buttons by default; radio for
- * ≤6-option select requests; static_select for >6-option select
- * requests. Override by declaring `events["input.requested"]`.
- */
-function defaultInputRequestedHandler() {
-    return async (data, ctx) => {
-        if (data.requests.length === 0)
-            return;
-        const decoded = decodeThreadId(ctx.thread.id ?? "");
-        await ctx.slack.request("chat.postMessage", {
-            channel: decoded.channelId,
-            thread_ts: decoded.threadTs,
-            blocks: data.requests.flatMap(renderInputRequestBlocks),
-            text: data.requests.map((r) => r.prompt).join("\n"),
-        });
-    };
-}
 /**
  * Build the once-registered `onNewMention` listener for a `Chat`
  * instance. The chat SDK defers handler invocation through the
@@ -84,6 +65,7 @@ function defaultInputRequestedHandler() {
  * lambda may terminate.
  */
 function buildMentionListener(config, uploadPolicy, getSend) {
+    const onMention = config.onMention ?? defaultOnMention;
     return async (thread, message) => {
         const raw = message.raw;
         // Slack delivers `app_mention` and `message.channels` for the same
@@ -100,17 +82,16 @@ function buildMentionListener(config, uploadPolicy, getSend) {
             thread,
             slack: buildSlackApiHandle(thread, config.credentials?.botToken, teamId),
         };
-        const runOpts = config.run ? await config.run(slackCtx, message) : { auth: null };
-        if (runOpts === null)
+        let mentionResult;
+        try {
+            mentionResult = await onMention(slackCtx, message);
+        }
+        catch (error) {
+            log.error("onMention handler failed", { error });
             return;
-        if (config.onMention) {
-            try {
-                await config.onMention(slackCtx, message);
-            }
-            catch (error) {
-                log.error("onMention handler failed", { error });
-            }
         }
+        if (mentionResult === null)
+            return;
         const decoded = decodeThreadId(thread.id ?? "");
         const continuationToken = `slack:${decoded.channelId}:${decoded.threadTs}`;
         const renderedText = renderInboundText(message);
@@ -133,7 +114,7 @@ function buildMentionListener(config, uploadPolicy, getSend) {
             : baseMessage;
         try {
             await send(turnMessage, {
-                auth: runOpts.auth,
+                auth: mentionResult.auth,
                 continuationToken,
                 state: {
                     serializedThread: thread.toJSON(),
@@ -147,11 +128,25 @@ function buildMentionListener(config, uploadPolicy, getSend) {
         }
     };
 }
+/**
+ * Slack channel factory. Wires up the Slack webhook route, mention
+ * dispatch, interaction handling, and a baseline set of typing /
+ * error / connection-auth event handlers.
+ *
+ * Defaults apply per field — pass `onMention` to fully replace the
+ * default mention pipeline (auth derivation + `"Thinking…"` typing),
+ * or pass an `events[type]` handler to replace only that one event.
+ * Fields you don't supply keep their defaults.
+ */
 export function slackChannel(config = {}) {
     const uploadPolicy = mergeUploadPolicy(config.uploadPolicy);
     const slackFetchFile = createSlackFetchFile({ botToken: config.credentials?.botToken });
     const stateAdapter = config.stateAdapter ?? createMemoryState();
-    const inputHandler = config.events?.["input.requested"] ?? defaultInputRequestedHandler();
+    const mergedEvents = {
+        ...defaultEvents,
+        ...config.events,
+        "input.requested": config.events?.["input.requested"] ?? defaultInputRequestedHandler(),
+    };
     // The chat SDK defers mention handler invocation past the route
     // handler returning, so the listener can't read `send` off the
     // current request. Capture it on the first request and reuse it —
@@ -166,7 +161,7 @@ export function slackChannel(config = {}) {
         chatPromise = (async () => {
             const { botToken, signingSecret, webhookVerifier } = resolveSlackAdapterCredentials(config.credentials);
             if (!botToken) {
-                throw new Error("slackChannel requires a bot token. Pass credentials.botToken or set SLACK_BOT_TOKEN.");
+                throw new Error("slackChannel() requires a bot token. Pass credentials.botToken or set SLACK_BOT_TOKEN.");
             }
             const [slackModule, chatModule] = await Promise.all([
                 import("#compiled/@chat-adapter/slack/index.js"),
@@ -226,7 +221,7 @@ export function slackChannel(config = {}) {
             await getChat();
             const channelId = input.args.channelId;
             if (!channelId) {
-                throw new Error("slackChannel.receive requires args.channelId.");
+                throw new Error("slackChannel().receive requires args.channelId.");
             }
             const chatModule = await import("#compiled/chat/index.js");
             const thread = new chatModule.ThreadImpl({
@@ -245,9 +240,6 @@ export function slackChannel(config = {}) {
                 },
             });
         },
-        events: {
-            ...config.events,
-            "input.requested": inputHandler,
-        },
+        events: mergedEvents,
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-ash",
-  "version": "0.10.4",
+  "version": "0.11.0",
   "bin": {
     "ash": "./bin/ash.js",
     "experimental-ash": "./bin/ash.js"

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

@@ -1,20 +0,0 @@
-import type { SessionAuthContext } from "#channel/types.js";
-import type { Channel } from "#public/definitions/defineChannel.js";
-import { type SlackChannelCredentials, type SlackChannelState, type SlackContext, type SlackEventContext, type SlackStateAdapter } from "#public/channels/slack/slackChannel.js";
-export interface SlackOptions {
-    /**
-     * Maps a verified inbound Slack mention to a {@link SessionAuthContext}.
-     * Receives the chat SDK `Message` plus a {@link SlackContext} carrying
-     * the live `thread` and `slack` API handle so policies can read
-     * channel/thread metadata without re-parsing `message.raw`.
-     *
-     * Defaults to a workspace-scoped projection of the Slack actor; return
-     * `null` to silently drop the mention.
-     */
-    readonly auth?: (message: import("#compiled/chat/index.js").Message, ctx: SlackContext) => SessionAuthContext | null;
-    readonly credentials?: SlackChannelCredentials;
-    readonly botName?: string;
-    readonly stateAdapter?: SlackStateAdapter;
-}
-export declare function slack(options?: SlackOptions): Channel<SlackChannelState>;
-export type { SlackEventContext };