@timqi/pier 0.1.0 → 0.1.1

package/dist/channels/dedup.js

@@ -1,11 +1,8 @@
-// At-least-once delivery, deduplicated: both push transports (Slack Socket
-// Mode, Lark's long connection) redeliver an event the platform did not see
-// acknowledged, so the same id can arrive twice. One implementation, because
-// the second copy had already appeared and the map has an invariant that is
-// easy to lose on a rewrite: it is fed by every message in every chat the bot
-// is in, so it must be bounded and time-limited, never grow-only.
-/** Fraction of `max` a full map is cut back to, so the eviction walk is paid
- *  once per that many messages instead of once per message. */
+// At-least-once delivery, deduplicated: Slack and Lark redeliver an event they
+// did not see acknowledged. The map is fed by every message in every chat, so
+// it must be bounded and time-limited, never grow-only.
+/** A full map is cut back to this fraction of `max`, so the eviction walk is
+ *  amortized instead of paid on every message at the bound. */
 const KEEP = 0.9;
 export class Dedup {
     log;
@@ -26,15 +23,9 @@ export class Dedup {
                 if (now - at > this.ttlMs)
                     this.seen.delete(id);
             }
-            // Pruning expired entries is not enough under a burst of live ones —
-            // `max` must be a real bound, so the oldest entries go next. The cost
-            // is a forgotten id under extreme load (a redelivery slips through,
-            // which downstream handling tolerates); unbounded memory is worse.
-            // Map iterates in insertion order, so the front is the oldest.
-            //
-            // Evicting down to `KEEP` rather than to exactly `max` is what makes
-            // the walk amortized: at the bound, freeing one slot per message meant
-            // re-walking the whole map on every message from then on.
+            // `max` must be a real bound, so under a burst of live entries the
+            // oldest go too (Map iterates in insertion order); a redelivery slipping
+            // through under extreme load is tolerated, unbounded memory is not.
             const keep = Math.floor(this.max * KEEP);
             for (const [id] of this.seen) {
                 if (this.seen.size <= keep)

package/dist/channels/gatekeeper.js

@@ -1,20 +1,13 @@
-// The two inbound decisions every adapter makes identically: may this message
-// through, and may this stranger be told how to bind.
-//
-// Both were written twice before landing here, and both have a rule that is
-// easy to get subtly wrong on the second copy — a drop must always name its
-// verdict, and the throttle map must prune rather than grow. Keeping them in
-// one place is what makes "log every drop" and "bound every map fed by
-// strangers" true of every platform instead of one.
+// The inbound decisions every adapter makes identically: may this message
+// through, may this chat be remembered, and may this stranger be told how to
+// bind.
 import { gate } from "./config.js";
-/** How often one unbound DM sender may be told how to bind. */
 const BIND_HINT_EVERY_MS = 10 * 60_000;
 export class Gatekeeper {
     store;
     platform;
     log;
     noun;
-    /** Last time each unbound DM sender was told how to bind. */
     hints = new Map();
     constructor(store, platform, log, 
     /** What the platform calls a conversation, for the drop log. */
@@ -24,11 +17,8 @@ export class Gatekeeper {
         this.log = log;
         this.noun = noun;
     }
-    /**
-     * The whole inbound permission decision, plus the log line every drop owes.
-     * A silently skipped branch is indistinguishable from a bug, so the verdict
-     * is always named.
-     */
+    /** Every drop names its verdict: a silently skipped branch is
+     *  indistinguishable from a bug. */
     admit(what, chatId, req) {
         const verdict = gate({
             policy: this.store.policy(this.platform, chatId),
@@ -42,14 +32,14 @@ export class Gatekeeper {
         this.log(`dropped ${what} in ${this.noun} ${chatId}: ${verdict}`);
         return false;
     }
-    /**
-     * May this sender be told how to bind? Groups stay silent by contract, but a
-     * DM that swallows every message looks broken rather than locked — and a bot
-     * that answers every one is an echo amplifier.
-     *
-     * Anyone can DM a bot, so this map is fed by strangers: expired entries are
-     * dropped on the way past instead of keeping one per sender forever.
-     */
+    /** A group the bot was added to is something an operator must see, but a DM
+     *  from a stranger may not write a row (or make the bot look its sender up):
+     *  anyone can start one. */
+    mayDiscover(req) {
+        return !req.isDm || this.store.isBound(this.platform, req.userId);
+    }
+    /** A bot that answers every stranger is an echo amplifier. The map is fed by
+     *  strangers, so expired entries are pruned on the way past. */
     mayHint(userId, now = Date.now()) {
         if (now - (this.hints.get(userId) ?? 0) < BIND_HINT_EVERY_MS)
             return false;

package/dist/channels/lark-api.js

@@ -1,23 +1,10 @@
-// Thin Lark (Feishu) client: API shapes and the WebSocket transport, no policy.
-// The one file in channels/ that talks to open.feishu.cn, so the adapter stays
-// testable against `LarkClient`.
-//
-// Unlike Slack's Socket Mode — JSON frames a while loop can own — Lark's long
-// connection is a protobuf-framed proprietary protocol with server-pushed
-// reconnect/ping config, so the official SDK carries the transport (and its
-// tenant-token refresh). It is confined to this file; nothing SDK-shaped leaks
-// past `LarkClient`. Domain is fixed to Feishu (open.feishu.cn) on purpose:
-// this instance's operator uses Feishu, and a Lark-international switch is a
-// config field we would carry for nobody.
-//
-// Two credentials, like Slack but for a different reason: every call and the
-// socket itself authenticate as `app_id` + `app_secret`, so ChannelConfig's
-// `token` carries the App ID and `appToken` the App Secret.
-//
-// One transport fact that shaped the adapter: the SDK sends the WS response
-// frame only *after* the registered handler resolves, and Lark redelivers what
-// it never saw answered — so handlers here must return once the event is
-// queued, never once it is handled ("ack is not handling", paid for on Slack).
+// Thin Lark (Feishu) client: API shapes and the WebSocket transport, no policy;
+// the one file that talks to open.feishu.cn. The long connection is a
+// protobuf-framed proprietary protocol, so the official SDK carries the
+// transport, confined to this file. Domain is fixed to Feishu. ChannelConfig's
+// `token` is the App ID and `appToken` the App Secret. The SDK acks a frame only
+// after the handler resolves and Lark redelivers what it never saw answered, so
+// handlers return once the event is queued.
 import * as Lark from "@larksuiteoapi/node-sdk";
 /** Lark answers HTTP 200 with a business code; non-zero is the real error. */
 function ok(what, res) {
@@ -28,8 +15,7 @@ function ok(what, res) {
 export class LarkApi {
     log;
     client;
-    /** Our own open_id, remembered from botOpenId() — reaction removal must
-     *  only ever touch a reaction *this* app made. */
+    /** Reaction removal must only touch a reaction this app made. */
     me = "";
     constructor(appId, appSecret, log = () => { }) {
         this.log = log;
@@ -53,13 +39,8 @@ export class LarkApi {
         return this.me;
     }
     // --- long connection ---------------------------------------------------------
-    /**
-     * The SDK owns the loop: endpoint discovery, protobuf frames, ping/pong and
-     * the reconnect pacing the server itself pushes down. `card.action.trigger`
-     * is registered through `register`'s generic because IHandles types events
-     * only, not callbacks; its payload shape is pinned by the adapter's golden
-     * tests instead.
-     */
+    /** `card.action.trigger` goes through `register`'s generic because IHandles
+     *  types events only, not callbacks. */
     connect(handlers) {
         const dispatcher = new Lark.EventDispatcher({
             loggerLevel: Lark.LoggerLevel.error,
@@ -79,8 +60,7 @@ export class LarkApi {
                         mentions: data.message.mentions,
                     },
                 });
-                // Resolve now: the SDK answers the frame only after this returns, and
-                // a turn outlives Lark's redelivery deadline.
+                // The SDK acks only after this returns; a turn outlives the redelivery deadline.
                 return Promise.resolve();
             },
             "card.action.trigger": (data) => {
@@ -102,12 +82,9 @@ export class LarkApi {
             domain: Lark.Domain.Feishu,
             loggerLevel: Lark.LoggerLevel.error,
         });
-        // Fire and forget, deliberately: start() settles on the SDK's schedule —
-        // it retries a busy endpoint and can sit in that loop for a long time —
-        // and ChannelRuntime serializes reloads, so awaiting here would let one
-        // unreachable network block every later Console save. Credentials were
-        // already proven by botOpenId() before connect() is called; a transport
-        // failure after that is the reconnect loop's job, and is logged.
+        // Not awaited: start() can sit in the SDK's retry loop for a long time,
+        // and ChannelRuntime serializes reloads, so one unreachable network would
+        // block every later Console save. botOpenId() already proved the credentials.
         void ws.start({ eventDispatcher: dispatcher })
             .catch((err) => this.log(`lark long connection failed: ${String(err)}`));
         return Promise.resolve({
@@ -129,23 +106,15 @@ export class LarkApi {
             data: {
                 msg_type: "interactive",
                 content: JSON.stringify(card),
-                // What makes the reply land in the message's own topic instead of the
-                // chat's main flow — Lark's equivalent of posting to a thread_ts.
+                // Lark's equivalent of posting to a thread_ts.
                 reply_in_thread: true,
             },
         });
         return { messageId: ok("message.reply", res).data?.message_id ?? "" };
     }
-    /**
-     * Two calls: the bytes go to the platform first and come back as a key,
-     * then the key is posted as a message. Images take the image endpoint so
-     * they render inline; everything else is a `stream` file, which is Lark's
-     * name for "a file whose type I am not claiming to know".
-     *
-     * The SDK unwraps an upload response to its `data`, so a business failure
-     * arrives as a missing key rather than as a code — hence the explicit throw
-     * instead of `ok()`.
-     */
+    /** Images take the image endpoint so they render inline; `stream` is Lark's
+     *  "type unknown". The SDK unwraps an upload response to its `data`, so a
+     *  failure arrives as a missing key, not a code. */
     async uploadFile(rootId, file) {
         const bytes = Buffer.from(file.bytes);
         let content;
@@ -190,12 +159,8 @@ export class LarkApi {
             data: { reaction_type: { emoji_type: emojiType } },
         }));
     }
-    /**
-     * Lark deletes reactions by `reaction_id`, and several parties may have
-     * used the same emoji — so list, keep only the entry *this app* owns
-     * (`operator_type` alone is not ownership: another bot's 👀 is an app
-     * reaction too, and deleting it would strand our own), delete that.
-     */
+    /** `operator_type` alone is not ownership: another bot's 👀 is an app
+     *  reaction too, and deleting it would strand our own. */
     async removeReaction(messageId, emojiType) {
         let pageToken;
         do {
@@ -208,7 +173,7 @@ export class LarkApi {
                 if (op?.operator_type !== "app")
                     continue;
                 // The list reports an app operator by open_id or app_id depending on
-                // surface; accept either of ours, never a blank (avibe's rule).
+                // surface; accept either of ours, never a blank.
                 const id = (op.operator_id ?? "").trim();
                 if (!id || (id !== this.me && id !== this.appId))
                     continue;
@@ -242,13 +207,8 @@ export class LarkApi {
         }
     }
     // --- files ----------------------------------------------------------------------
-    /**
-     * `maxBytes` is enforced *while streaming*: the receive event often omits
-     * `file_size`, so the metadata check upstream cannot be the only cap, and
-     * buffering an unbounded stream whole into memory is the exact failure the
-     * cap exists for. The error message carries "too large" — the adapter's
-     * lost-marker wording keys on it.
-     */
+    /** Enforced while streaming: the receive event often omits `file_size`. The
+     *  error carries "too large", which the lost-marker wording keys on. */
     async download(messageId, fileKey, type, maxBytes) {
         const res = await this.client.im.v1.messageResource.get({
             path: { message_id: messageId, file_key: fileKey },

package/dist/channels/lark-outbound.js

@@ -1,45 +1,25 @@
-// How a turn becomes cards in a Lark thread.
-//
-// Split from the adapter the way slack-outbound.ts is: what a turn renders as
-// — one card per chunk, footer and buttons on the last, and what an empty turn
-// still has to say — is a different decision from routing inbound traffic. The
-// adapter keeps the 👀 receipts, because those are about the turn ending, not
-// about what was said.
+// How a turn becomes cards in a Lark thread: one card per chunk, footer and
+// buttons on the last, 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 { button, buttonRow, card, chunk, footer, LARK_MAX, markdown, OFFER_PREFIX, withFooter, withoutButtons, } from "./lark-render.js";
-/** How many sent cards the retire cache remembers (avibe keeps 200). */
 const SENT_CACHE = 200;
 export class LarkOutbound {
     api;
     log;
-    /**
-     * The cards this process sent with buttons on them, for retiring the row
-     * once an option is taken — a 2.0 card cannot be read back from the
-     * platform (see LarkActionValue), so what we sent is the only copy.
-     * In-memory and bounded, copied from avibe: purely cosmetic state. A click
-     * after a restart still *works* (the label rides in the value); the buttons
-     * merely stay up, and the skip is logged.
-     */
+    /** A 2.0 card cannot be read back (LarkActionValue), so what we sent is the
+     *  only copy to retire buttons from. Cosmetic: a click after a restart still
+     *  works, the buttons merely stay up. */
     sent = new Map();
     constructor(api, log) {
         this.api = api;
         this.log = log;
     }
-    /**
-     * Post one turn as replies into the conversation's thread, empty text
-     * included: a turn that produced nothing still posts its footer and says
-     * which kind of nothing it was — total silence is indistinguishable from a
-     * crash, and the person watching the 👀 come off has no way to tell.
-     *
-     * The footer folds into the last body chunk's own markdown element (a
-     * second element renders a blank gap); only a bodiless turn gets it as the
-     * standalone muted element. Buttons ride the last chunk, like every other
-     * platform — the card is remembered so retire() can rebuild it without them.
-     */
+    /** An empty turn still posts its footer and says which kind of nothing (§5).
+     *  The footer folds into the last chunk's element (a second element renders
+     *  a blank gap); only a bodiless turn gets the standalone one. */
     async reply(root, reply) {
-        // A file the agent linked lives on Pier's machine, so the link is dead in
-        // Lark: the bytes are uploaded instead and the label stays in the text.
+        // A local file link is dead in Lark: the bytes are uploaded instead.
         const { text: spoken, paths } = splitAttachments(reply.text);
         const text = spoken.trim();
         const meta = reply.meta ? formatTurnMeta(reply.meta) : "";
@@ -66,17 +46,11 @@ export class LarkOutbound {
             if (last && row && messageId)
                 this.remember(messageId, card(elements));
         }
-        // Attachments follow the words, so the card 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(root, file), this.log);
         if (lost)
             await this.api.replyCard(root, card([markdown(lost)]));
     }
-    /**
-     * Take the buttons off a card one option was just taken from — the rest
-     * answer a question the conversation has moved past. Best-effort by design:
-     * an unremembered card (sent before a restart) keeps its row, logged.
-     */
+    /** Best-effort: a card sent before a restart keeps its row, logged. */
     async retire(messageId) {
         const known = this.sent.get(messageId);
         if (!known) {
@@ -96,14 +70,8 @@ export class LarkOutbound {
             this.sent.delete(oldest);
         }
     }
-    /**
-     * 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 id of the last card it posted — where the caller puts the
-     * 👀 for that turn, at the foot of the topic the reply will land in.
-     */
+    /** No footer: the turn this input triggers has not ended. Answers with the
+     *  id of the last card posted, where the caller puts the 👀. */
     async note(root, note) {
         const body = note.text.split("\n").map((line) => `> ${line}`).join("\n");
         let messageId;

package/dist/channels/lark-panel.js

@@ -1,17 +1,10 @@
-// Lark's half of the settings panel: card markup, flow button rows, and a form
-// card for the one typed answer. The panel itself lives in `panel.ts`.
-//
-// Lark has no modal a WebSocket app can open — a "modal" here is the panel
-// message patched into a form card (an input plus a submit button), which is
-// avibe's verified pattern. The submit button's `name` carries the thread root
-// the same way every other panel button's callback value does, so a submission
-// needs no adapter-side state to find its conversation — the map below only
-// remembers where the panel message itself lives.
+// Lark's half of the settings panel (panel.ts has the rest). Lark has no modal
+// a WebSocket app can open, so the typed answer is the panel patched into a
+// form card; the submit button's `name` carries the thread root.
 import { button as cardButton, buttonRow, card, footer, formInput, markdown, } from "./lark-render.js";
 import { ChatPanel, CWD_PLACEHOLDER, CWD_TAIL, PANEL_PREFIX, } from "./panel.js";
 /** A form-submit button name: `cwdgo:<thread root>`. */
 export const CWD_SUBMIT_PREFIX = "cwdgo:";
-/** The form input's field name, the key `form_value` answers under. */
 const CWD_FIELD = "cwd";
 export class LarkPanel extends ChatPanel {
     deps;
@@ -21,8 +14,7 @@ export class LarkPanel extends ChatPanel {
         super(deps);
         this.deps = deps;
     }
-    /** Lark's markdown treats what it cannot parse as literal text; there is no
-     *  escape syntax to apply (see lark-render.ts). */
+    /** Lark's markdown has no escape syntax (lark-render.ts). */
     esc(text) {
         return text;
     }
@@ -33,7 +25,6 @@ export class LarkPanel extends ChatPanel {
     render(view, root, note) {
         const elements = [
             ...view.groups.map((g) => markdown([`**${g.title}**${g.suffix ?? ""}`, ...g.lines].join("\n"))),
-            // A flow row wraps, so a page of models lays out like Slack's one row.
             ...(view.picks?.length ? [buttonRow(view.picks.map((p) => this.btn(p, root)))] : []),
             ...view.rows.filter((r) => r.length).map((row) => buttonRow(row.map((b) => this.btn(b, root)))),
         ];
@@ -41,7 +32,6 @@ export class LarkPanel extends ChatPanel {
             elements.push(footer(note));
         return card(elements);
     }
-    /** Open a fresh panel, replacing whichever one this conversation had. */
     async open(key, chatId, root) {
         const sent = await this.deps.api.replyCard(root, this.render(await this.view(key, chatId), root));
         this.remember(key, { chatId, root, messageId: sent.messageId, models: [] });
@@ -55,10 +45,7 @@ export class LarkPanel 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(action, key, payload, root) {
         return this.dispatch(key, payload, action, () => this.open(key, action.chatId, root));
     }
@@ -81,11 +68,8 @@ export class LarkPanel extends ChatPanel {
         };
         await this.deps.api.patchCard(state.messageId, card([form, buttonRow([this.btn({ label: "Cancel", action: "panel" }, state.root)])])).catch((err) => this.deps.log(`cwd form failed: ${String(err)}`));
     }
-    /**
-     * Consume a form submission. The adapter routes any `cwdgo:` submit here;
-     * a panel that outlived its process is re-remembered from the event itself,
-     * so the outcome still lands on the card the user is looking at.
-     */
+    /** A panel that outlived its process is re-remembered from the event, so
+     *  the outcome lands on the card the user is looking at. */
     async onCwdSubmit(key, action, root) {
         if (!this.state(key)) {
             this.remember(key, { chatId: action.chatId, root, messageId: action.messageId, models: [] });

package/dist/channels/lark-render.js

@@ -1,62 +1,29 @@
 // How a reply looks on Lark: an interactive card whose body is a markdown
-// element, buttons as flow columns, and the turn footer as notation-sized grey
-// text.
-//
-// Everything is a card, never a plain `text` message, because three checklist
-// features live or die on it: buttons (next-step suggestions, the settings
-// panel), edit-in-place (the panel's one-message contract, via message.patch),
-// and the muted footer. The costs are known and accepted: the chat list
-// previews a card as「卡片」rather than its first line, and card interactions
-// expire after 30 days — fine for buttons that answer the turn they rode on.
-//
-// The markdown element takes the agent's markdown near-unmodified — Lark's
-// dialect covers emphasis, fences, lists, links and quotes — so unlike
-// Telegram (HTML) and Slack's mrkdwn fallback there is no translation layer,
-// and no escaping either: Lark treats what it cannot parse as literal text
-// rather than rejecting the message (avibe ships the same identity escape).
+// element. Always a card, never plain `text`: buttons, edit-in-place and the
+// muted footer all need one. Costs accepted: the chat list previews a card as
+// 「卡片」, and card interactions expire after 30 days. Lark's markdown dialect
+// takes the agent's markdown near-unmodified and treats what it cannot parse as
+// literal text, so there is no translation and no escaping.
 import { balanceFences, chunkText } from "./chunk.js";
-/**
- * Chunk budget in characters. The binding limit is the card's 30KB request
- * cap in *bytes*; a CJK character spends three, plus JSON string overhead, so
- * 7000 chars keeps the worst all-CJK turn near 21KB with room for the card
- * scaffolding around it.
- */
+/** The binding limit is the card's 30KB request cap in bytes; a CJK character
+ *  spends three, so 7000 chars keeps an all-CJK turn near 21KB plus scaffolding. */
 export const LARK_MAX = 7000;
 // Lark truncates a button label around this, mid-word.
 const BUTTON_MAX = 60;
-/**
- * Cut at the last break that fits, then re-balance code fences across the cut:
- * Lark, like Slack, lets an unterminated ``` swallow the rest of the message.
- */
+/** Fences re-balanced across the cut: an unterminated ``` swallows the rest. */
 export const chunk = (text, max) => balanceFences(chunkText(text, max));
-/** The body of a turn, rendered by Lark's own markdown dialect. */
 export const markdown = (content) => ({ tag: "markdown", content });
-/**
- * Small muted text. Card schema 2.0 removed the `note` component; its
- * replacement is a notation-sized markdown element, and the grey must come
- * from the inline font tag because 2.0's markdown element rejects a
- * `text_color` property. Both verified against the live API (by avibe).
- *
- * Standalone cards only (a quiet turn, an options row): beside a body it
- * would render a blank gap — elements space themselves apart and no spacing
- * knob is documented — so there the footer folds into the body's own element
- * (`withFooter`), where a newline is just a newline.
- */
+/** Schema 2.0 has no `note`, and its markdown element rejects `text_color`, so
+ *  the grey is an inline font tag. Standalone cards only: beside a body it
+ *  renders a blank gap, so there the footer folds into the body (`withFooter`). */
 export const footer = (content) => ({
     tag: "markdown",
     content: `<font color='grey'>${content}</font>`,
     text_size: "notation",
 });
-/**
- * Markdown constructs a following line *continues* instead of leaving: a list
- * item, a blockquote, a table row. After one of these a single newline is
- * lazy continuation — the footer rendered glued onto "5. 麻辣烫：…" in the
- * field — so the footer needs the blank line that ends the construct. After a
- * plain paragraph the single newline stays, because that is the tight spacing
- * this helper exists for.
- */
+/** After a list item, a quote or a table row a single newline is lazy
+ *  continuation and the footer glues onto the line; those need a blank line. */
 const LAZY_LINE = /^\s*(?:[-*+]\s|\d+[.)]\s|>|\|)/;
-/** A body and its footer in one markdown element — grey, gapless. */
 export const withFooter = (body, note) => {
     const last = body.trimEnd().split("\n").at(-1) ?? "";
     const brk = LAZY_LINE.test(last) ? "\n\n" : "\n";
@@ -69,11 +36,7 @@ export const button = (label, value) => ({
     type: "default",
     behaviors: [{ type: "callback", value }],
 });
-/**
- * One row of buttons as a `flow` column set: each column sizes to its button
- * and the row wraps on narrow screens, so a long label beside a short one
- * costs nothing (the same property Slack's actions row has natively).
- */
+/** A `flow` column set sizes each column to its button and wraps on narrow screens. */
 export const buttonRow = (buttons) => ({
     tag: "column_set",
     flex_mode: "flow",
@@ -84,7 +47,7 @@ export const card = (elements) => ({
     schema: "2.0",
     body: { direction: "vertical", elements },
 });
-/** A typed answer inside a card — Lark's stand-in for a modal. */
+/** Lark's stand-in for a modal. */
 export const formInput = (name, label, placeholder) => ({
     tag: "input",
     name,
@@ -93,15 +56,8 @@ export const formInput = (name, label, placeholder) => ({
     placeholder: { tag: "plain_text", content: placeholder },
 });
 // --- next-step buttons -----------------------------------------------------------
-/**
- * The callback value carries the key (`sg:0`) *and* the label. On Slack the
- * label is read back off the message the platform echoes with the click; Lark
- * echoes only the value, and `message.get` cannot return a 2.0 card at all
- * (see LarkActionValue), so the value is this platform's "read it back off
- * the message" — still platform state, never adapter memory, so a button
- * survives a restart and the Console's reload the same way (avibe ships the
- * label in the value too: `quick_reply:<label>`).
- */
+/** The value carries the key and the label: Lark echoes only the value, and
+ *  `message.get` cannot return a 2.0 card (LarkActionValue), so this is the one
+ *  place a button's meaning survives a restart. */
 export const OFFER_PREFIX = "sg:";
-/** The card minus its button rows — how taken options are retired. */
 export const withoutButtons = (cardIn) => card(cardIn.body.elements.filter((el) => el.tag !== "column_set" && el.tag !== "button"));