@copilotkit/channels-slack 0.1.0

package/dist/native-stream.js

@@ -0,0 +1,208 @@
+/**
+ * Default text-flush floor. `chat.appendStream` is Tier 4 (100+/min), so 600ms
+ * (~100/min) keeps comfortable headroom while streaming noticeably more
+ * smoothly than the legacy `chat.update` path (~1/sec). The `WebClient` retries
+ * 429s honoring `Retry-After`, so this is a soft floor, not a correctness gate.
+ */
+const DEFAULT_MIN_INTERVAL_MS = 600;
+/** Slack caps `markdown_text` at 12k chars per `appendStream` call. */
+const APPEND_CHAR_LIMIT = 12000;
+export class NativeMessageStream {
+    buffer = "";
+    queue = Promise.resolve();
+    lastFlushedAt = 0;
+    flushTimer;
+    finished = false;
+    /** Current streamed message ts (undefined until the first `startStream`). */
+    curTs;
+    /** Buffer chars already appended as text to the current message. */
+    curPosted = 0;
+    /** ts of the first streamed message (for the returned MessageRef). */
+    firstTsValue;
+    /** Set once `startStream` has failed and we've fallen back to the legacy transport. */
+    legacy;
+    /** Set once a chunk append has failed/been refused, so we stop trying. */
+    chunksDisabled = false;
+    transport;
+    makeFallback;
+    onStartFailure;
+    onChunkFailure;
+    minIntervalMs;
+    constructor(config) {
+        this.transport = config.transport;
+        this.makeFallback = config.fallback;
+        this.onStartFailure = config.onStartFailure;
+        this.onChunkFailure = config.onChunkFailure;
+        this.minIntervalMs = config.minIntervalMs ?? DEFAULT_MIN_INTERVAL_MS;
+    }
+    /** The first streamed message's ts (or the fallback's), available after finish(). */
+    get firstTs() {
+        return this.firstTsValue;
+    }
+    append(fullText) {
+        if (this.legacy) {
+            this.legacy.append(fullText);
+            return;
+        }
+        if (fullText === this.buffer)
+            return;
+        this.buffer = fullText;
+        this.scheduleFlush();
+    }
+    /**
+     * Append a structured chunk (`task_update` / `plan_update` / `blocks`) to the
+     * streamed message. Flushes any pending text first so the chunk lands AFTER
+     * the text emitted so far. No-op (firing `onChunkFailure` once) when the
+     * stream has fallen back to legacy or chunks were already refused.
+     */
+    appendChunk(chunk) {
+        if (this.legacy || this.chunksDisabled) {
+            if (!this.chunksDisabled) {
+                this.chunksDisabled = true;
+                this.onChunkFailure?.(new Error("native streaming unavailable"));
+            }
+            return;
+        }
+        // Drop the throttle gate so the chunk (and the text before it) flush
+        // promptly — tool-progress shouldn't wait out the text cadence.
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = undefined;
+        }
+        this.queue = this.queue.then(() => this.flushChunk(chunk));
+    }
+    async finish(finalBlocks) {
+        this.finished = true;
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = undefined;
+        }
+        this.enqueueFlush();
+        await this.queue;
+        if (this.legacy) {
+            await this.legacy.finish();
+            return;
+        }
+        // Finalize the streamed message (no-op if we never started one).
+        if (this.curTs) {
+            try {
+                await this.transport.stopStream(this.curTs, finalBlocks);
+            }
+            catch (err) {
+                console.error("[native-stream] stopStream failed:", err);
+            }
+        }
+    }
+    scheduleFlush() {
+        if (this.flushTimer)
+            return;
+        const elapsed = Date.now() - this.lastFlushedAt;
+        const delay = Math.max(0, this.minIntervalMs - elapsed);
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = undefined;
+            this.enqueueFlush();
+        }, delay);
+    }
+    enqueueFlush() {
+        this.queue = this.queue.then(() => this.flushText());
+    }
+    /** Ensure the stream is started; on failure, fall back to legacy and replay. Returns false if failed over. */
+    async ensureStarted() {
+        if (this.curTs)
+            return true;
+        try {
+            this.curTs = await this.transport.startStream();
+            this.firstTsValue = this.curTs;
+            return true;
+        }
+        catch (err) {
+            this.failOverToLegacy(err);
+            return false;
+        }
+    }
+    /** Append all un-posted buffer text to the current message, chunked under the 12k per-call cap. */
+    async flushText() {
+        if (this.legacy)
+            return; // appends are forwarded directly once failed over
+        if (this.curPosted >= this.buffer.length)
+            return; // nothing new
+        if (!(await this.ensureStarted()))
+            return;
+        try {
+            let cursor = this.curPosted;
+            while (cursor < this.buffer.length) {
+                const end = Math.min(cursor + APPEND_CHAR_LIMIT, this.buffer.length);
+                await this.transport.appendText(this.curTs, this.buffer.slice(cursor, end));
+                cursor = end;
+                this.curPosted = cursor;
+            }
+        }
+        catch (err) {
+            // A mid-stream append failure shouldn't sink the stream; the next flush
+            // retries from `curPosted` (only advanced on success).
+            console.error(`[native-stream] appendText failed (ts=${this.curTs}, posted=${this.curPosted}/${this.buffer.length}):`, err);
+        }
+        finally {
+            this.lastFlushedAt = Date.now();
+        }
+    }
+    /** Flush pending text, then append one structured chunk. */
+    async flushChunk(chunk) {
+        if (this.legacy || this.chunksDisabled)
+            return;
+        // Start the stream even if no text yet — a tool call can be the first thing
+        // the agent emits (`startStream` accepts a content-less open; the chunk is
+        // the message's first content).
+        if (!(await this.ensureStarted())) {
+            this.disableChunks(new Error("startStream failed"));
+            return;
+        }
+        await this.flushTextInline();
+        try {
+            await this.transport.appendChunks(this.curTs, [chunk]);
+        }
+        catch (err) {
+            console.error(`[native-stream] appendChunks failed (ts=${this.curTs}):`, err);
+            this.disableChunks(err);
+        }
+        finally {
+            this.lastFlushedAt = Date.now();
+        }
+    }
+    /** Append pending text to the current (already-started) message; swallow failures. */
+    async flushTextInline() {
+        if (this.curPosted >= this.buffer.length)
+            return;
+        try {
+            let cursor = this.curPosted;
+            while (cursor < this.buffer.length) {
+                const end = Math.min(cursor + APPEND_CHAR_LIMIT, this.buffer.length);
+                await this.transport.appendText(this.curTs, this.buffer.slice(cursor, end));
+                cursor = end;
+                this.curPosted = cursor;
+            }
+        }
+        catch (err) {
+            console.error(`[native-stream] appendText (pre-chunk) failed (ts=${this.curTs}):`, err);
+        }
+    }
+    disableChunks(err) {
+        if (this.chunksDisabled)
+            return;
+        this.chunksDisabled = true;
+        this.onChunkFailure?.(err);
+    }
+    /**
+     * Switch to the legacy `chat.update` transport and replay the full buffer so
+     * no text is lost ("opting in can never break a bot"). The full buffer is
+     * replayed because `append()` forwards the accumulated full text once
+     * `this.legacy` is set, so the legacy stream owns the whole response.
+     */
+    failOverToLegacy(err) {
+        console.warn("[native-stream] startStream failed; using legacy transport:", err);
+        this.onStartFailure?.(err);
+        const legacy = this.makeFallback();
+        legacy.append(this.buffer);
+        this.legacy = legacy;
+    }
+}

package/dist/render/block-kit.d.ts

@@ -0,0 +1,35 @@
+import type { BotNode } from "@copilotkit/channels-ui";
+import type { KnownBlock } from "@slack/types";
+/**
+ * Stable `action_id` of the native AI feedback row's `feedback_buttons`
+ * element. The adapter intercepts clicks on this id (routing them to the
+ * app's feedback callback) before they reach the engine's interaction
+ * dispatch — see `adapter.ts`.
+ */
+export declare const FEEDBACK_ACTION_ID = "ck-fb";
+/**
+ * Build the native AI-feedback row (`context_actions` + `feedback_buttons`)
+ * attached to a finalized streamed reply via `chat.stopStream`'s `blocks`.
+ * The clicked button's `value` ("positive" / "negative") carries the sentiment.
+ */
+export declare function buildFeedbackBlocks(opts?: {
+    positiveLabel?: string;
+    negativeLabel?: string;
+}): KnownBlock[];
+/**
+ * Render a cross-platform component IR tree (already expanded by `renderToIR`
+ * and pre-bound by the action registry, so event props are `{ id }`) into a
+ * Slack Block Kit `KnownBlock[]`.
+ *
+ * The renderer is total: unknown intrinsic types are skipped rather than
+ * throwing. Per-element Slack limits are applied via {@link truncateText} and
+ * {@link clampArray}; nothing is silently dropped — overflowing collections
+ * clamp and, at the top level, append an explicit overflow signal block.
+ */
+export declare function renderBlockKit(ir: BotNode[]): KnownBlock[];
+/** Render IR to Slack blocks, extracting a top-level <Message accent="#hex"> color for an attachment wrapper. */
+export declare function renderSlackMessage(ir: BotNode[]): {
+    blocks: KnownBlock[];
+    accent?: string;
+};
+//# sourceMappingURL=block-kit.d.ts.map

package/dist/render/block-kit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-kit.d.ts","sourceRoot":"","sources":["../../src/render/block-kit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,KAAK,EAAuB,UAAU,EAAE,MAAM,cAAc,CAAC;AAIpE;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,UAAU,CAAC;AAE1C;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,CAAC,EAAE;IACzC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GAAG,UAAU,EAAE,CA+Bf;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,OAAO,EAAE,GAAG,UAAU,EAAE,CAiB1D;AAED,iHAAiH;AACjH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,OAAO,EAAE,GAAG;IACjD,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CASA"}

package/dist/render/block-kit.js

@@ -0,0 +1,399 @@
+import { markdownToMrkdwn } from "../markdown-to-mrkdwn.js";
+import { SLACK_LIMITS, clampArray, truncateText } from "./budget.js";
+/**
+ * Stable `action_id` of the native AI feedback row's `feedback_buttons`
+ * element. The adapter intercepts clicks on this id (routing them to the
+ * app's feedback callback) before they reach the engine's interaction
+ * dispatch — see `adapter.ts`.
+ */
+export const FEEDBACK_ACTION_ID = "ck-fb";
+/**
+ * Build the native AI-feedback row (`context_actions` + `feedback_buttons`)
+ * attached to a finalized streamed reply via `chat.stopStream`'s `blocks`.
+ * The clicked button's `value` ("positive" / "negative") carries the sentiment.
+ */
+export function buildFeedbackBlocks(opts) {
+    const block = {
+        type: "context_actions",
+        elements: [
+            {
+                type: "feedback_buttons",
+                action_id: FEEDBACK_ACTION_ID,
+                positive_button: {
+                    text: {
+                        type: "plain_text",
+                        text: truncateText(opts?.positiveLabel ?? "Good response", SLACK_LIMITS.buttonText),
+                    },
+                    value: "positive",
+                },
+                negative_button: {
+                    text: {
+                        type: "plain_text",
+                        text: truncateText(opts?.negativeLabel ?? "Bad response", SLACK_LIMITS.buttonText),
+                    },
+                    value: "negative",
+                },
+            },
+        ],
+    };
+    return [block];
+}
+/**
+ * Render a cross-platform component IR tree (already expanded by `renderToIR`
+ * and pre-bound by the action registry, so event props are `{ id }`) into a
+ * Slack Block Kit `KnownBlock[]`.
+ *
+ * The renderer is total: unknown intrinsic types are skipped rather than
+ * throwing. Per-element Slack limits are applied via {@link truncateText} and
+ * {@link clampArray}; nothing is silently dropped — overflowing collections
+ * clamp and, at the top level, append an explicit overflow signal block.
+ */
+export function renderBlockKit(ir) {
+    const blocks = [];
+    for (const node of ir) {
+        renderNode(node, blocks);
+    }
+    // Top-level budget: clamp to the per-message block ceiling, leaving room for
+    // an overflow-signal context block when we had to drop anything.
+    const { items, overflow } = clampArray(blocks, SLACK_LIMITS.blocksPerMessage);
+    if (overflow <= 0)
+        return items;
+    // Drop the last kept block to make room for the signal so we land at exactly
+    // the ceiling (49 kept + 1 signal = 50) instead of exceeding it.
+    const kept = items.slice(0, SLACK_LIMITS.blocksPerMessage - 1);
+    const dropped = overflow + 1;
+    kept.push(overflowSignal(dropped));
+    return kept;
+}
+/** Render IR to Slack blocks, extracting a top-level <Message accent="#hex"> color for an attachment wrapper. */
+export function renderSlackMessage(ir) {
+    const blocks = renderBlockKit(ir);
+    // Top-level single <Message accent="..."> → use its accent as the attachment color.
+    if (ir.length === 1 && ir[0] && ir[0].type === "message") {
+        const accent = ir[0].props.accent;
+        if (typeof accent === "string" && accent.length > 0)
+            return { blocks, accent };
+    }
+    return { blocks };
+}
+function overflowSignal(count) {
+    return {
+        type: "context",
+        elements: [{ type: "mrkdwn", text: `_…+${count} more blocks truncated_` }],
+    };
+}
+/** Render a single IR node, pushing zero or more blocks onto `out`. */
+function renderNode(node, out) {
+    if (typeof node.type !== "string")
+        return; // non-intrinsic — already expanded away
+    const props = node.props ?? {};
+    switch (node.type) {
+        case "message": {
+            // The message container is not a block; flatten its children.
+            for (const child of childNodes(node))
+                renderNode(child, out);
+            return;
+        }
+        case "header": {
+            out.push({
+                type: "header",
+                text: {
+                    type: "plain_text",
+                    text: truncateText(collectText(node), SLACK_LIMITS.headerText),
+                },
+            });
+            return;
+        }
+        case "section":
+        case "markdown": {
+            out.push({
+                type: "section",
+                text: {
+                    type: "mrkdwn",
+                    text: truncateText(markdownToMrkdwn(collectText(node)), SLACK_LIMITS.sectionText),
+                },
+            });
+            return;
+        }
+        case "fields": {
+            const fieldChildren = childNodes(node).filter((c) => c.type === "field");
+            const { items } = clampArray(fieldChildren, SLACK_LIMITS.fieldsPerSection);
+            out.push({
+                type: "section",
+                fields: items.map((f) => ({
+                    type: "mrkdwn",
+                    text: truncateText(fieldMrkdwn(f), SLACK_LIMITS.fieldText),
+                })),
+            });
+            return;
+        }
+        case "field": {
+            // Standalone field (rare) → single-field section.
+            out.push({
+                type: "section",
+                fields: [
+                    {
+                        type: "mrkdwn",
+                        text: truncateText(fieldMrkdwn(node), SLACK_LIMITS.fieldText),
+                    },
+                ],
+            });
+            return;
+        }
+        case "context": {
+            const { items } = clampArray(childNodes(node), SLACK_LIMITS.contextElements);
+            out.push({
+                type: "context",
+                elements: items.map((c) => ({
+                    type: "mrkdwn",
+                    text: markdownToMrkdwn(collectText(c)),
+                })),
+            });
+            return;
+        }
+        case "actions": {
+            const { items } = clampArray(childNodes(node), SLACK_LIMITS.actionsElements);
+            // A multi-select can't live in an `actions` block (Slack allows
+            // multi_static_select only in section/input blocks), so peel each one off
+            // into its own dispatching input block; the rest stay as action elements.
+            // Flush the pending actions block BEFORE each peeled-off input so blocks
+            // stay in source order (e.g. [Button, Select multi] → actions, then input).
+            let elements = [];
+            const flush = () => {
+                if (elements.length > 0) {
+                    out.push({ type: "actions", elements });
+                    elements = [];
+                }
+            };
+            for (const child of items) {
+                if (child.type === "select" && child.props.multi) {
+                    flush();
+                    out.push(multiSelectInput(child));
+                    continue;
+                }
+                const el = renderActionElement(child);
+                if (el !== null)
+                    elements.push(el);
+            }
+            flush();
+            return;
+        }
+        case "image": {
+            const url = (props.url ?? props.image_url);
+            out.push({
+                type: "image",
+                image_url: url ?? "",
+                alt_text: (props.alt ?? props.altText ?? ""),
+            });
+            return;
+        }
+        case "divider": {
+            out.push({ type: "divider" });
+            return;
+        }
+        case "input": {
+            out.push({
+                type: "input",
+                dispatch_action: true,
+                element: {
+                    type: "plain_text_input",
+                    action_id: truncateText(idFromHandler(props.onSubmit) ?? "input", SLACK_LIMITS.actionId),
+                    multiline: !!props.multiline,
+                },
+                label: {
+                    type: "plain_text",
+                    text: truncateText(String(props.placeholder ?? " "), 150),
+                },
+            });
+            return;
+        }
+        case "text": {
+            // Bare top-level text → a mrkdwn section.
+            const value = String(props.value ?? "");
+            out.push({
+                type: "section",
+                text: {
+                    type: "mrkdwn",
+                    text: truncateText(markdownToMrkdwn(value), SLACK_LIMITS.sectionText),
+                },
+            });
+            return;
+        }
+        case "table": {
+            // Native Slack Table block: rows of `{ type: "raw_text", text }` cells.
+            // Header row from `columns`, data rows from `row`/`cell` children.
+            // Not yet in `@slack/types`, so the block is built plain and cast.
+            const cellOf = (text) => ({
+                type: "raw_text",
+                text: truncateText(text, SLACK_LIMITS.cellText),
+            });
+            const columnsProp = props.columns;
+            const columns = columnsProp
+                ? clampArray(columnsProp, SLACK_LIMITS.tableColumns).items
+                : undefined;
+            const rows = [];
+            if (columns && columns.length > 0) {
+                rows.push(columns.map((c) => cellOf(c.header)));
+            }
+            const rowNodes = childNodes(node).filter((c) => c.type === "row");
+            const { items: dataRows } = clampArray(rowNodes, SLACK_LIMITS.tableRows);
+            for (const rowNode of dataRows) {
+                const cells = childNodes(rowNode).filter((c) => c.type === "cell");
+                rows.push(cells.map((cell) => cellOf(collectText(cell))));
+            }
+            const block = { type: "table", rows };
+            if (columns) {
+                block.column_settings = columns.map((c) => ({
+                    align: c.align ?? "left",
+                }));
+            }
+            out.push(block);
+            return;
+        }
+        case "raw": {
+            const value = props.value;
+            const native = Array.isArray(value) ? value : [value];
+            for (const b of native) {
+                if (b != null)
+                    out.push(b);
+            }
+            return;
+        }
+        default:
+            // Unknown intrinsic — skip silently (total renderer).
+            return;
+    }
+}
+/**
+ * Render one interactive element inside an `actions` block. Returns `null` for
+ * children that aren't renderable as action elements (so callers can filter).
+ */
+function renderActionElement(node) {
+    if (typeof node.type !== "string")
+        return null;
+    const props = node.props ?? {};
+    switch (node.type) {
+        case "button": {
+            const action_id = truncateText(buttonActionId(props), SLACK_LIMITS.actionId);
+            const el = {
+                type: "button",
+                action_id,
+                text: {
+                    type: "plain_text",
+                    text: truncateText(collectText(node), SLACK_LIMITS.buttonText),
+                },
+            };
+            // Link button: opens the URL natively. Slack still requires an action_id
+            // (kept above); clicks on a url button are not dispatched as actions.
+            if (typeof props.url === "string" && props.url.length > 0) {
+                el.url = props.url;
+            }
+            if (props.value !== undefined) {
+                el.value = truncateText(JSON.stringify(props.value), SLACK_LIMITS.buttonValue);
+            }
+            if (props.style === "primary" || props.style === "danger") {
+                el.style = props.style;
+            }
+            return el;
+        }
+        case "select": {
+            const action_id = truncateText(idFromHandler(props.onSelect) ?? "select", SLACK_LIMITS.actionId);
+            const options = props.options ??
+                [];
+            const { items } = clampArray(options, SLACK_LIMITS.selectOptions);
+            const el = {
+                type: "static_select",
+                action_id,
+                placeholder: {
+                    type: "plain_text",
+                    text: String(props.placeholder ?? " "),
+                },
+                options: items.map((o) => ({
+                    text: { type: "plain_text", text: truncateText(o.label, 75) },
+                    value: truncateText(String(o.value), 150),
+                })),
+            };
+            return el;
+        }
+        default:
+            return null;
+    }
+}
+/**
+ * Render a `<Select multi>` as a dispatching input block holding a
+ * `multi_static_select` (which Slack forbids inside an `actions` block). The
+ * block_actions payload carries `selected_options`, decoded to a `string[]`.
+ */
+function multiSelectInput(node) {
+    const props = node.props ?? {};
+    const action_id = truncateText(idFromHandler(props.onSelect) ?? "select", SLACK_LIMITS.actionId);
+    const options = props.options ?? [];
+    const { items } = clampArray(options, SLACK_LIMITS.selectOptions);
+    return {
+        type: "input",
+        dispatch_action: true,
+        element: {
+            type: "multi_static_select",
+            action_id,
+            placeholder: {
+                type: "plain_text",
+                text: String(props.placeholder ?? " "),
+            },
+            options: items.map((o) => ({
+                text: { type: "plain_text", text: truncateText(o.label, 75) },
+                value: truncateText(String(o.value), 150),
+            })),
+        },
+        label: {
+            type: "plain_text",
+            text: truncateText(String(props.placeholder ?? " "), 150),
+        },
+    };
+}
+/** Derive a button's `action_id`: prefer the registry-stamped id, else a stable fallback. */
+function buttonActionId(props) {
+    const fromHandler = idFromHandler(props.onClick);
+    if (fromHandler)
+        return fromHandler;
+    return props.value !== undefined ? JSON.stringify(props.value) : "action";
+}
+/** Extract `{ id }` stamped onto an event prop by the action registry, if present. */
+function idFromHandler(handler) {
+    if (handler && typeof handler === "object" && "id" in handler) {
+        const id = handler.id;
+        if (typeof id === "string")
+            return id;
+    }
+    return undefined;
+}
+/** The expanded `children` of an IR node as an `BotNode[]` (empty if none). */
+function childNodes(node) {
+    const children = node.props?.children;
+    if (Array.isArray(children))
+        return children;
+    if (children &&
+        typeof children === "object" &&
+        "type" in children) {
+        return [children];
+    }
+    return [];
+}
+/** A field's mrkdwn text: a bold `label` line (when set) above the value. */
+function fieldMrkdwn(node) {
+    const value = markdownToMrkdwn(collectText(node));
+    const label = node.props.label;
+    return typeof label === "string" && label.length > 0
+        ? `*${label}*\n${value}`
+        : value;
+}
+/** Concatenate the `value` of all descendant `text` nodes (depth-first). */
+function collectText(node) {
+    if (typeof node.type === "string" && node.type === "text") {
+        return String(node.props?.value ?? "");
+    }
+    let acc = "";
+    for (const child of childNodes(node)) {
+        acc += collectText(child);
+    }
+    return acc;
+}

package/dist/render/block-kit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=block-kit.test.d.ts.map

package/dist/render/block-kit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-kit.test.d.ts","sourceRoot":"","sources":["../../src/render/block-kit.test.ts"],"names":[],"mappings":""}