@timqi/pier 0.0.1

package/dist/channels/slack-outbound.js

@@ -0,0 +1,121 @@
+// How a turn becomes messages in a Slack thread.
+//
+// Split out of the adapter because it is a separate decision from routing
+// inbound traffic: which renderer to use, how to chunk against that renderer's
+// limit, and what an empty turn still has to say. The adapter keeps the 👀
+// receipts, because those are about the turn ending, not about what was said.
+import { formatTurnMeta, originLabel } from "../core/reply.js";
+import { isBlockRejection } from "./slack-api.js";
+import { actions, chunk, context, escapeMrkdwn, markdown, MARKDOWN_MAX, MRKDWN_MAX, sections, toMrkdwn, } from "./slack-render.js";
+/**
+ * The web shows a turn's cost on hover. Slack has a `context` block — genuinely
+ * small, muted text — so unlike Telegram the footer needs no italic hack to
+ * read as a footnote.
+ */
+const footerText = (meta) => escapeMrkdwn(formatTurnMeta(meta));
+export class SlackOutbound {
+    api;
+    log;
+    /**
+     * Latched off for the process on the first refusal, so the failed round trip
+     * is paid once rather than once per message.
+     */
+    markdownBlocks = true;
+    constructor(api, log) {
+        this.api = api;
+        this.log = log;
+    }
+    /**
+     * Post one turn, empty text included: the turn settled with nothing to say,
+     * and that is still something to show.
+     */
+    async reply(channel, threadTs, reply) {
+        const text = reply.text.trim();
+        const footer = reply.meta ? footerText(reply.meta) : "";
+        const row = actions(reply.suggestions);
+        // A turn that produced no text still posts its footer, and says which kind
+        // of nothing it was. Silence must be *observable*: total silence is
+        // indistinguishable from a crash, a dropped connection or a bug, and the
+        // person waiting has no way to tell. A muted one-liner is the cheapest
+        // honest answer.
+        // Options count as a reply: the buttons are the answer, so a turn that is
+        // only its options is not "nothing".
+        const quiet = text || row
+            ? ""
+            : reply.silence
+                ? `_stayed silent — ${escapeMrkdwn(reply.silence)}_`
+                : "_no reply_";
+        if (!(text || row || footer || quiet))
+            return;
+        const parts = text ? chunk(text, this.budget()) : [""];
+        for (const [i, part] of parts.entries()) {
+            const last = i === parts.length - 1;
+            // The footer and the buttons ride the last chunk only. The quiet marker
+            // shares the footer's block, so an empty turn is one muted line rather
+            // than two.
+            const note = last ? [quiet, footer].filter(Boolean).join(" · ") : "";
+            await this.post(channel, threadTs, part, [
+                ...(note ? [context(note)] : []),
+                ...(last && row ? [row] : []),
+            ]);
+        }
+    }
+    /**
+     * A system note: quoted, labelled with where it came from, and deliberately
+     * plain — no buttons and no turn footer, because the turn this input
+     * triggers has not ended yet.
+     */
+    async note(channel, threadTs, note) {
+        // Markdown's own blockquote, so the note reads as quoted on either path.
+        const body = note.text.split("\n").map((line) => `> ${line}`).join("\n");
+        for (const part of chunk(`_${originLabel(note.origin)}_\n${body}`, this.budget())) {
+            await this.post(channel, threadTs, part, []);
+        }
+    }
+    /** Which budget `chunk()` should respect, given the path we are on. */
+    budget() {
+        return this.markdownBlocks ? MARKDOWN_MAX : MRKDWN_MAX;
+    }
+    /**
+     * Post one message's body, preferring Slack's own markdown renderer.
+     *
+     * The `markdown` block takes the agent's markdown unmodified — tables,
+     * headers and nested lists all survive, none of which the mrkdwn subset can
+     * express — and the client never folds it behind "Show more". It is recent
+     * enough to be refused by an older workspace, so a rejection degrades to the
+     * translated mrkdwn path instead of losing the turn.
+     */
+    async post(channel, threadTs, body, trailing) {
+        // `text` is the notification and accessibility fallback, never shown
+        // beside the blocks.
+        const notice = body || trailing.length ? body || "…" : "";
+        if (this.markdownBlocks) {
+            const blocks = [...(body ? [markdown(body)] : []), ...trailing];
+            if (!blocks.length)
+                return;
+            try {
+                await this.api.postMessage({ channel, thread_ts: threadTs, text: notice, blocks });
+                return;
+            }
+            catch (err) {
+                if (!isBlockRejection(err))
+                    throw err;
+                this.markdownBlocks = false;
+                this.log(`markdown block refused, falling back to mrkdwn: ${String(err)}`);
+            }
+        }
+        // Legacy path: translate to mrkdwn and split into section blocks. The body
+        // was chunked against the larger budget, so it may need splitting again.
+        for (const part of body ? chunk(toMrkdwn(body), MRKDWN_MAX) : [""]) {
+            const blocks = [...sections(part), ...trailing];
+            if (!blocks.length)
+                continue;
+            await this.api.postMessage({
+                channel,
+                thread_ts: threadTs,
+                text: part || notice || "…",
+                blocks,
+            });
+        }
+    }
+}

package/dist/channels/slack-panel.js

@@ -0,0 +1,122 @@
+// Slack's half of the settings panel: mrkdwn markup, Block Kit, and a modal
+// for the one typed answer. The panel itself lives in `panel.ts`.
+//
+// The modal is what makes this half smaller than Telegram's: `private_metadata`
+// carries the conversation with the dialog, so a submitted path needs no
+// adapter-side state to be understood, and survives a reload.
+import { ChatPanel, PANEL_PREFIX, } from "./panel.js";
+import { context, escapeMrkdwn as esc, section } from "./slack-render.js";
+/** The modal's ids. `private_metadata` carries which conversation it is for. */
+const CWD_VIEW = "cfg_cwd";
+const CWD_BLOCK = "cwd_block";
+const CWD_INPUT = "cwd_input";
+const button = (b) => ({
+    type: "button",
+    action_id: `${PANEL_PREFIX}${b.action}`,
+    text: { type: "plain_text", text: b.label, emoji: true },
+});
+const row = (buttons) => ({
+    type: "actions",
+    elements: buttons.map(button),
+});
+export class SlackPanel extends ChatPanel {
+    deps;
+    platform = "slack";
+    fence = ["`", "`"];
+    constructor(deps) {
+        super(deps);
+        this.deps = deps;
+    }
+    esc(text) {
+        return esc(text);
+    }
+    // --- rendering -------------------------------------------------------------
+    blocks(view, note) {
+        return [
+            ...view.groups.map((g) => section([`*${g.title}*${g.suffix ?? ""}`, ...g.lines].join("\n"))),
+            // Slack fits a page of choices on one row; Telegram would not.
+            ...(view.picks?.length ? [row(view.picks)] : []),
+            ...view.rows.filter((r) => r.length).map(row),
+            ...(note ? [context(esc(note))] : []),
+        ];
+    }
+    /** Open a fresh panel, replacing whichever one this conversation had. */
+    async open(key, channel, threadTs) {
+        const sent = await this.deps.api.postMessage({
+            channel,
+            thread_ts: threadTs,
+            text: "Settings",
+            blocks: this.blocks(await this.view(key, channel)),
+        });
+        this.remember(key, { chatId: channel, threadTs, ts: sent.ts, models: [] });
+    }
+    async draw(state, view, note) {
+        await this.deps.api.updateMessage({
+            channel: state.chatId,
+            ts: state.ts,
+            text: "Settings",
+            blocks: this.blocks(view, note),
+        }).catch((err) => this.deps.log(`panel edit failed: ${String(err)}`));
+    }
+    async erase(state) {
+        await this.deps.api.deleteMessage(state.chatId, state.ts)
+            .catch((err) => this.deps.log(`panel close failed: ${String(err)}`));
+    }
+    // --- actions ---------------------------------------------------------------
+    /**
+     * Handle a `cfg:` click. Returns false when the action is not ours, so the
+     * caller can treat it as one of the agent's next-step labels instead.
+     */
+    async onAction(interaction, key, actionId) {
+        return this.dispatch(key, actionId, interaction, async () => {
+            const channel = interaction.channel?.id;
+            const message = interaction.message;
+            if (channel && message)
+                await this.open(key, channel, message.thread_ts ?? message.ts);
+        });
+    }
+    // --- working directory (one typed answer, in a modal) ----------------------
+    async promptCwd(key, _state, interaction) {
+        const trigger = interaction.trigger_id;
+        if (!trigger) {
+            await this.refresh(key, "Could not open the dialog — try again.");
+            return;
+        }
+        await this.deps.api.openView(trigger, {
+            type: "modal",
+            callback_id: CWD_VIEW,
+            private_metadata: key.conversationId,
+            title: { type: "plain_text", text: "New session" },
+            submit: { type: "plain_text", text: "Start" },
+            close: { type: "plain_text", text: "Cancel" },
+            blocks: [
+                {
+                    type: "input",
+                    block_id: CWD_BLOCK,
+                    label: { type: "plain_text", text: "Working directory" },
+                    hint: {
+                        type: "plain_text",
+                        text: "An absolute path. A new session starts there; the current one stays in its own directory.",
+                    },
+                    element: {
+                        type: "plain_text_input",
+                        action_id: CWD_INPUT,
+                        placeholder: { type: "plain_text", text: "/path/to/project" },
+                    },
+                },
+            ],
+        }).catch((err) => this.deps.log(`cwd modal failed: ${String(err)}`));
+    }
+    /** Consume a modal submission. Returns false when the view is not ours. */
+    async onViewSubmission(interaction) {
+        const view = interaction.view;
+        if (view?.callback_id !== CWD_VIEW)
+            return false;
+        const key = {
+            channelId: "slack",
+            conversationId: view.private_metadata ?? "",
+        };
+        await this.startSessionIn(key, (view.state?.values?.[CWD_BLOCK]?.[CWD_INPUT]?.value ?? "").trim());
+        return true;
+    }
+}

package/dist/channels/slack-render.js

@@ -0,0 +1,214 @@
+// How a reply looks on Slack: mrkdwn text, and buttons as a Block Kit
+// `actions` row.
+//
+// mrkdwn is not markdown. Bold is `*one*` star, italic is `_underscore_`,
+// strikethrough is `~one~` tilde, and a link is `<url|label>` — so the agent's
+// markdown has to be translated, not passed through. Only `&`, `<` and `>` are
+// escaped; unlike Telegram's HTML parser Slack degrades unknown syntax to
+// literal text instead of rejecting the message, so the risk here is an ugly
+// reply rather than a lost one.
+import { chunkText } from "./chunk.js";
+/**
+ * A `markdown` block's budget: Slack caps them at 12,000 cumulative chars per
+ * message, and one message carries one. This is the normal path.
+ */
+export const MARKDOWN_MAX = 11_000;
+/**
+ * The legacy fallback's budget: a `section` block's text caps at 3000, and the
+ * mrkdwn translation adds a little markup.
+ */
+export const MRKDWN_MAX = 2800;
+// Slack truncates a button label past this, mid-word.
+const BUTTON_MAX = 75;
+// Slack's cap on one actions block. `MAX_SUGGESTIONS` in core/reply.ts already
+// holds the agent to 5, so this only guards a caller that bypasses it.
+const MAX_BUTTONS = 25;
+/** Shared: the adapter and the panel escape plain text with this too. */
+export const escapeMrkdwn = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+/**
+ * Inline emphasis, applied after escaping so our own markup stays ours.
+ *
+ * Bold is marked with a private-use sentinel rather than written as `*` right
+ * away: mrkdwn spells bold with the single star that markdown uses for italic,
+ * so emitting it early would let the italic pass eat it again.
+ */
+const BOLD = "\uE002";
+function inline(text) {
+    return text
+        // Links first: their label may itself carry emphasis. Slack inverts the
+        // order of markdown's pair, and `>` inside is already escaped.
+        .replace(/\[([^\]\n]+)\]\((https?:\/\/[^\s)]+)\)/g, (_m, label, url) => `<${url}|${label}>`)
+        // Bold before italic: `**x**` must not be seen as two `*x*` runs.
+        .replace(/\*\*([^\n*]+)\*\*/g, `${BOLD}$1${BOLD}`)
+        .replace(/~~([^\n~]+)~~/g, "~$1~")
+        .replace(/(^|[\s(])[*_]([^\n*_]+)[*_](?=[\s).,!?:;]|$)/g, "$1_$2_")
+        // Headings have no size in Slack either; bold is the closest honest render.
+        .replace(/^#{1,6}[ \t]+(.+)$/gm, `${BOLD}$1${BOLD}`)
+        // Slack renders neither `-` nor `*` as a list marker, so bullets are drawn.
+        .replace(/^[ \t]*[-*+][ \t]+/gm, "\u2022 ")
+        .replaceAll(BOLD, "*");
+}
+/**
+ * Render one assistant turn as mrkdwn. Code spans and fences are extracted
+ * before escaping so emphasis inside them stays literal.
+ */
+export function toMrkdwn(markdown) {
+    const stash = [];
+    // Private-use sentinels: markdown cannot contain them, so a stashed block
+    // cannot be re-matched by the escaping and emphasis passes that follow.
+    const keep = (text) => `\uE000${stash.push(text) - 1}\uE001`;
+    // Slack code fences carry no language, so the hint is dropped rather than
+    // shown as the first line of the block.
+    let out = markdown.replace(/```[\w.+-]*\n?([\s\S]*?)```/g, (_m, code) => keep("```\n" + escapeMrkdwn(code.replace(/\n+$/, "")) + "\n```"));
+    out = out.replace(/`([^`\n]+)`/g, (_m, code) => keep(`\`${escapeMrkdwn(code)}\``));
+    out = inline(escapeMrkdwn(out));
+    return out.replace(/\uE000(\d+)\uE001/g, (_m, i) => stash[Number(i)] ?? "");
+}
+/**
+ * Split rendered mrkdwn into sendable chunks at the last blank line or newline
+ * that fits, then re-balance code fences across the cut.
+ *
+ * Telegram can be cut mid-`<pre>` and shrug — its parser closes the tag itself.
+ * Slack does not: an unterminated ``` swallows the rest of that message, and
+ * the next chunk starts *outside* a fence, so the tail of a long code block
+ * renders as prose. Closing and reopening around the boundary is what keeps a
+ * split code block readable.
+ */
+export const chunk = (text, max) => balanceFences(chunkText(text, max));
+/**
+ * Close a fence a chunk left open, and reopen it on the next one. Counting `\`
+ * runs is enough because `toMrkdwn` has already normalised every fence to a
+ * bare ``` on its own line.
+ */
+function balanceFences(parts) {
+    let open = false;
+    return parts.map((part) => {
+        const reopened = open ? `\`\`\`\n${part}` : part;
+        // The prepended fence counts too, so a chunk that closes the block it
+        // inherited comes out even and clears the flag.
+        open = ((reopened.match(/```/g) ?? []).length % 2) === 1;
+        return open ? `${reopened}\n\`\`\`` : reopened;
+    });
+}
+/**
+ * The body of a turn, as Slack's own markdown renderer sees it. Preferred over
+ * `section` for everything the agent wrote: it takes the markdown unmodified
+ * (so tables and headers survive) and the client never folds it behind
+ * "Show more".
+ */
+export const markdown = (text) => ({ type: "markdown", text });
+export const section = (text) => ({
+    type: "section",
+    text: { type: "mrkdwn", text },
+});
+// Slack caps a message at 50 blocks; the footer and the button row need two.
+const MAX_BLOCKS = 45;
+// A section block's hard limit. Nothing should reach it — chunk() caps a whole
+// message below this — but the overflow merge below could in principle.
+const SECTION_MAX = 2900;
+/**
+ * Split rendered mrkdwn into paragraphs without ever cutting a fenced code
+ * block — a fence split across two blocks would leave both unbalanced, the
+ * same hazard `chunk()` handles for messages.
+ */
+function paragraphs(text) {
+    const out = [];
+    let buf = [];
+    let fenced = false;
+    const flush = () => {
+        if (buf.length)
+            out.push(buf.join("\n"));
+        buf = [];
+    };
+    for (const line of text.split("\n")) {
+        const isFence = line.trimStart().startsWith("```");
+        // A blank line only ends a paragraph outside a fence; inside one it is code.
+        if (!fenced && !isFence && !line.trim()) {
+            flush();
+            continue;
+        }
+        buf.push(line);
+        if (isFence) {
+            fenced = !fenced;
+            // A closed fence stands alone, so it can never be merged apart.
+            if (!fenced)
+                flush();
+        }
+    }
+    flush();
+    return out;
+}
+/**
+ * The body of one message as one `section` block per paragraph — the fallback
+ * for a workspace whose Slack refuses the `markdown` block.
+ *
+ * A whole turn in a single section block gets collapsed behind "Show more",
+ * hiding most of the answer; several blocks render unfolded. Paragraphs are
+ * deliberately *not* packed together to fill a size budget — a paragraph is
+ * already the natural short unit, and merging a few of them back into one tall
+ * block is exactly what brings the collapse back.
+ */
+export function sections(text) {
+    const paras = paragraphs(text);
+    if (!paras.length)
+        return [];
+    // Past the block cap the tail is folded into the last block rather than
+    // dropped: a truncated reply is worse than a tall one, and silently losing
+    // the end of an answer is worst of all.
+    const kept = paras.slice(0, MAX_BLOCKS - 1);
+    const tail = paras.slice(MAX_BLOCKS - 1);
+    if (tail.length)
+        kept.push(tail.join("\n\n").slice(0, SECTION_MAX));
+    return kept.map(section);
+}
+/**
+ * Slack's small muted text. Telegram has none, which is why `formatTurnMeta`
+ * lands there as an italic footnote; here the footer gets the block the
+ * platform actually has for it.
+ */
+export const context = (text) => ({
+    type: "context",
+    elements: [{ type: "mrkdwn", text }],
+});
+// --- next-step buttons -------------------------------------------------------
+/**
+ * `action_id` carries an index, not the label. Slack would allow 2000 chars of
+ * `value`, but the index is what makes a button survive a `runtime.reload()`:
+ * the label is read back off the message Slack echoes with the click, so no
+ * adapter-instance memory is involved.
+ */
+export const OFFER_PREFIX = "sg:";
+const truncate = (label) => label.length > BUTTON_MAX ? `${label.slice(0, BUTTON_MAX - 1)}\u2026` : label;
+/**
+ * One actions row. Slack wraps buttons on its own and gives each its natural
+ * width, so unlike Telegram there is no row packing to budget — a long label
+ * beside a short one costs nothing.
+ */
+export function actions(labels) {
+    if (!labels.length)
+        return undefined;
+    const elements = labels.slice(0, MAX_BUTTONS).map((label, index) => ({
+        type: "button",
+        action_id: `${OFFER_PREFIX}${index}`,
+        text: { type: "plain_text", text: truncate(label), emoji: true },
+    }));
+    return { type: "actions", elements };
+}
+/**
+ * The label a next-step `action_id` stands for, read off the clicked message's
+ * own blocks — which Slack echoes back in the interaction payload. A button
+ * therefore keeps working across a restart or a config reload, where an
+ * in-memory offer list would not.
+ */
+export function offeredLabel(blocks, actionId) {
+    if (!actionId.startsWith(OFFER_PREFIX))
+        return undefined;
+    for (const block of blocks ?? []) {
+        if (block.type !== "actions")
+            continue;
+        const hit = block.elements.find((el) => el.action_id === actionId);
+        if (hit)
+            return hit.text.text;
+    }
+    return undefined;
+}