@timqi/pier 0.1.0 → 0.1.1

package/dist/channels/slack-outbound.js

@@ -1,47 +1,26 @@
-// 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.
+// How a turn becomes messages in a Slack thread: which renderer, how to chunk
+// against its limit, and what an empty turn still has to say.
 import { formatTurnMeta, isSilentReply, originLabel, quietLabel } from "../core/reply.js";
 import { sendAttachments, splitAttachments } from "./attach.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.
-     */
+    /** Latched off on the first refusal, so the failed round trip is paid once. */
     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) {
-        // A file the agent linked lives on Pier's machine, so the link is dead in
-        // Slack: the bytes are uploaded instead and the label stays in the text.
+        // A local file link is dead in Slack: the bytes are uploaded instead.
         const { text: spoken, paths } = splitAttachments(reply.text);
         const text = spoken.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.
+        // An empty turn still posts its footer and says which kind of nothing (§5).
         const quiet = isSilentReply(reply)
             ? `_${quietLabel(reply.silence && escapeMrkdwn(reply.silence))}_`
             : "";
@@ -50,33 +29,20 @@ export class SlackOutbound {
         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.
+            // The quiet marker shares the footer's block: one muted line, not two.
             const note = last ? [quiet, footer].filter(Boolean).join(" · ") : "";
             await this.post(channel, threadTs, part, [
                 ...(note ? [context(note)] : []),
                 ...(last && row ? [row] : []),
             ]);
         }
-        // Attachments follow the words, so the message introducing them is above
-        // them; anything that could not be sent says so in the thread.
         const lost = await sendAttachments(paths, (file) => this.api.uploadFile(channel, threadTs, file), this.log);
-        // Unescaped, like every other body: post() escapes on the path that needs it.
         if (lost)
             await this.post(channel, threadTs, lost, []);
     }
-    /**
-     * 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.
-     *
-     * Answers with the `ts` of the last message it posted — where the caller
-     * puts the 👀 for that turn, at the foot of the thread the reply will land
-     * in. Undefined when there was nothing to post.
-     */
+    /** No footer: the turn this input triggers has not ended. Answers with the
+     *  `ts` of the last message posted, where the caller puts the 👀. */
     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");
         let ts;
         for (const part of chunk(`_${originLabel(note.origin)}_\n${body}`, this.budget())) {
@@ -84,22 +50,13 @@ export class SlackOutbound {
         }
         return ts;
     }
-    /** 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.
-     */
+    /** The `markdown` block is recent enough to be refused by an older
+     *  workspace; a rejection degrades to the translated mrkdwn path. */
     async post(channel, threadTs, body, trailing) {
-        // `text` is the notification and accessibility fallback, never shown
-        // beside the blocks.
+        // `text` is the notification fallback, never shown beside the blocks.
         const notice = body || trailing.length ? body || "…" : "";
         if (this.markdownBlocks) {
             const blocks = [...(body ? [markdown(body)] : []), ...trailing];
@@ -116,8 +73,7 @@ export class SlackOutbound {
                 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.
+        // The body was chunked against the larger budget, so it may split again.
         let ts;
         for (const part of body ? chunk(toMrkdwn(body), MRKDWN_MAX) : [""]) {
             const blocks = [...sections(part), ...trailing];

package/dist/channels/slack-panel.js

@@ -1,12 +1,8 @@
-// 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.
+// Slack's half of the settings panel (panel.ts has the rest). The modal's
+// `private_metadata` carries the conversation, so a submission needs no
+// adapter-side state and survives a reload.
 import { ChatPanel, CWD_PLACEHOLDER, CWD_TAIL, 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";
@@ -34,13 +30,11 @@ export class SlackPanel extends ChatPanel {
     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,
@@ -63,10 +57,7 @@ export class SlackPanel extends ChatPanel {
             .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.
-     */
+    /** Returns false when the action is not ours. */
     async onAction(interaction, key, actionId) {
         return this.dispatch(key, actionId, interaction, async () => {
             const channel = interaction.channel?.id;

package/dist/channels/slack-render.js

@@ -1,78 +1,44 @@
 // 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.
+// `actions` row. mrkdwn is not markdown (`*bold*`, `_italic_`, `~strike~`,
+// `<url|label>`), so the agent's markdown is translated; Slack degrades unknown
+// syntax to literal text rather than rejecting the message.
 import { balanceFences, 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.
- */
+/** Slack caps `markdown` blocks at 12,000 cumulative chars per message. */
 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.
- */
+/** A `section` block's text caps at 3000, and the mrkdwn translation adds markup. */
 export const MRKDWN_MAX = 2800;
 // Slack truncates a button label past this, mid-word.
 const BUTTON_MAX = 75;
-/** 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.
- */
+/** mrkdwn spells bold with the single star markdown uses for italic, so bold
+ *  is marked with a sentinel until the italic pass has run. */
 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.
+        // Links first: their label may itself carry emphasis.
         .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.
+        // Slack renders neither `-` nor `*` as a list marker.
         .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.
- */
+/** Code is stashed before escaping so emphasis inside it 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.
+    // Slack fences carry no language; the hint would show as the first line.
     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 (see chunk.ts for why
- * an unbalanced fence is a mangled reply here and not on Telegram).
- */
 export const chunk = (text, max) => balanceFences(chunkText(text, max));
-/**
- * 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".
- */
+/** Slack's own renderer: 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",
@@ -80,14 +46,9 @@ export const section = (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.
+// A section block's hard limit; only the overflow merge in sections() can reach it.
 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.
- */
+/** Never cuts a fenced block: a fence split across two blocks leaves both unbalanced. */
 function paragraphs(text) {
     const out = [];
     let buf = [];
@@ -99,7 +60,6 @@ function paragraphs(text) {
     };
     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;
@@ -107,7 +67,6 @@ function paragraphs(text) {
         buf.push(line);
         if (isFence) {
             fenced = !fenced;
-            // A closed fence stands alone, so it can never be merged apart.
             if (!fenced)
                 flush();
         }
@@ -115,52 +74,31 @@ function paragraphs(text) {
     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.
- */
+/** The fallback for a workspace that refuses the `markdown` block. One section
+ *  per paragraph, never packed: a tall single block is collapsed behind "Show
+ *  more", several short ones render unfolded. */
 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.
+    // The tail is folded into the last block, not dropped.
     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.
- */
+/** Slack's small muted text, for the footer. */
 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.
- */
+/** `action_id` carries an index: the label is read back off the message Slack
+ *  echoes with the click, so a button survives a reload. */
 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.
- */
+/** Slack wraps buttons on its own, so there is no row packing to budget. */
 export function actions(labels) {
     if (!labels.length)
         return undefined;
@@ -171,12 +109,6 @@ export function actions(labels) {
     }));
     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;