allaboard 0.0.0-stage → 0.4.0

package/dist/chat/slack/reply/clients.js

@@ -0,0 +1,171 @@
+/**
+ * The daemon's two Slack clients on one token, with the daemon's retry policy:
+ *
+ * - every call that Slack rate limited (HTTP 429) is sent again after the `Retry-After` Slack
+ *   gave, up to 3 times and while its pauses add up to no more than `RATE_LIMIT_WAIT_SECONDS`
+ *   (60): a pause that would pass them is not taken, and the call is thrown as rate limited.
+ *   That is safe for every method: a rate limited call never ran. Once the
+ *   daemon stops (`ClientOptions.stopped`) such a call is thrown as it is and the pause of one
+ *   that waits ends: Slack names the length of that pause, and a stop does not wait for it.
+ *   Each rate limit is logged with its method, its `Retry-After` and the send it answered.
+ * - a call that failed on the connection (a reset, a refused or unreachable host: a
+ *   `WebAPIRequestError` that is not a timeout) is sent again once, after a backoff pause.
+ *   `sharedClient` does so for every method, which is safe for a post that is an approval, a
+ *   question or a notice. `repliesClient`, the one a reply is written with, does so for every
+ *   method but the four of `CREATING_METHODS`: a start, an append, a stop and a post are not
+ *   idempotent, a connection can reset after Slack applied the call, and a second send would
+ *   duplicate a message or its text, or stop a stream twice. The sink reads the thread back
+ *   instead, and adopts what landed.
+ * - a call Slack answered with HTTP 500 or 503 (`SERVER_ERROR_STATUSES`) is sent again as one
+ *   that failed on the connection is: once, after the same pause, by the same client for the
+ *   same methods. The statuses and the one retry are those of slack-sdk's
+ *   `ServerErrorRetryHandler` (`slack_sdk/http_retry/builtin_handlers.py`, read 2026-10-11).
+ *   The sink reads an HTTP status as a call that did not run (`unknownOutcome` in `errors.ts`),
+ *   which would let the four creating calls be sent again too; they are left out, since whether
+ *   Slack can answer 500 or 503 after it applied a call was not measured.
+ * - nothing else is sent again: Slack answering with an error (`WebAPIPlatformError`), any other
+ *   HTTP status, a timeout (a timed out call may have run).
+ *
+ * `@slack/web-api` 8.2.0 retries every failure or none: `WebClient.makeRequest` ends in
+ * `pRetry(task, this.retryConfig)`, with no option per method and none per error. So both clients
+ * are built with the two documented options that switch its retries off (`SENT_ONCE`), which
+ * makes the library report each failure once, as a typed error, and `PolicyClient.apiCall` applies
+ * the policy around `WebClient.apiCall`. A retry counts toward one budget per call, as slack-sdk's
+ * `RetryState.current_attempt` did: a connection or server error retry is allowed while no retry
+ * was made, a rate limit retry while fewer than 3 were.
+ *
+ * Differences from slack-sdk: a 429 with no valid `Retry-After` is thrown as the library's plain
+ * error at once (slack-sdk waited 1 to 2 seconds and retried; Slack always sends the header); and
+ * the pause before a retry is taken from the injected `Clock`, so a test crosses it without
+ * waiting. `files.uploadV2` is passed through untouched: it is not a Slack method but the
+ * library's three step upload, whose `files.getUploadURLExternal` and
+ * `files.completeUploadExternal` come back through `apiCall` and are retried there, one by one.
+ */
+import { WebAPIHTTPError, WebAPIRateLimitedError, WebAPIRequestError, WebClient, } from "@slack/web-api";
+import { systemClock } from "../../../clock.js";
+import { getLogger } from "../../../log.js";
+import { silentLogger } from "../quiet-logger.js";
+export const logger = getLogger("allaboard.chat.slack.reply.clients");
+/**
+ * The four calls that create or grow a message: the replies client never sends one again after a
+ * failed connection or a server error.
+ */
+export const CREATING_METHODS = [
+    "chat.startStream",
+    "chat.appendStream",
+    "chat.stopStream",
+    "chat.postMessage",
+];
+// What slack-sdk's client waited for an answer by default (`AsyncWebClient(timeout=30)`). The
+// library's default is no timeout at all (`WebClientOptions.timeout`, 0), and a pass of the sink
+// waits for its call to answer.
+export const REQUEST_TIMEOUT_MS = 30_000;
+/** The two options that make the library report each failure once, whatever else it is built with. */
+export const SENT_ONCE = {
+    retryConfig: { retries: 0 },
+    rejectRateLimitedCalls: true,
+};
+// `AsyncRateLimitErrorRetryHandler(max_retry_count=3)`, and the default of slack-sdk's connection
+// handler and of its server error one: the one retry of a call covers both kinds of failure.
+export const RATE_LIMIT_RETRIES = 3;
+// The most of Slack's `Retry-After` pauses one call waits out in all, the jitter left out (issue
+// #236): the sink sends a reply's calls holding the reply's lock, which a `!stop` waits for. The
+// one value measured, on 2026-10-12 and 2026-10-13, was 10 seconds.
+export const RATE_LIMIT_WAIT_SECONDS = 60;
+export const CONNECTION_RETRIES = 1;
+/** The HTTP statuses a call is sent again after, as after a failed connection. */
+export const SERVER_ERROR_STATUSES = [500, 503];
+// `BackoffRetryIntervalCalculator(backoff_factor=0.5)`: 0.5 * 2^attempt seconds, plus a jitter.
+const BACKOFF_FACTOR = 0.5;
+/** A request that failed before an answer, and not by the client's own timeout. */
+function failedOnConnection(error) {
+    return (error instanceof WebAPIRequestError &&
+        error.original.name !== "TimeoutError" &&
+        error.original.name !== "AbortError");
+}
+/** Slack answered with a status that says its side failed, with no word on the call itself. */
+function failedOnServer(error) {
+    return error instanceof WebAPIHTTPError && SERVER_ERROR_STATUSES.includes(error.statusCode);
+}
+/** A `WebClient` that sends each call by the policy at the top of this file. */
+class PolicyClient extends WebClient {
+    #notRetried;
+    #clock;
+    #random;
+    #stopped;
+    constructor(token, notRetried, options) {
+        const { clock, random, stopped, ...rest } = options;
+        super(token, { timeout: REQUEST_TIMEOUT_MS, ...rest, ...SENT_ONCE, logger: silentLogger() });
+        this.#notRetried = new Set(notRetried);
+        this.#clock = clock ?? systemClock;
+        this.#random = random ?? Math.random;
+        this.#stopped = stopped;
+    }
+    /**
+     * Seconds to wait before sending the call again, or null when it is not sent again. `waited` is
+     * the sum of the `Retry-After` pauses the call already took.
+     */
+    #pause(method, error, retries, waited) {
+        if (error instanceof WebAPIRateLimitedError) {
+            return retries < RATE_LIMIT_RETRIES && waited + error.retryAfter <= RATE_LIMIT_WAIT_SECONDS
+                ? error.retryAfter + this.#random()
+                : null;
+        }
+        if ((failedOnConnection(error) || failedOnServer(error)) &&
+            retries < CONNECTION_RETRIES &&
+            !this.#notRetried.has(method)) {
+            return BACKOFF_FACTOR * 2 ** retries + this.#random();
+        }
+        return null;
+    }
+    async apiCall(method, options = {}) {
+        if (method === "files.uploadV2")
+            return super.apiCall(method, options);
+        let waited = 0;
+        for (let retries = 0;; retries += 1) {
+            try {
+                return await super.apiCall(method, options);
+            }
+            catch (error) {
+                if (error instanceof WebAPIRateLimitedError) {
+                    // The method and Slack's own number, never the call's arguments: which methods are
+                    // rate limited, and for how long, is what issue #236 waits for.
+                    logger.info(`Slack rate limited ${method}: Retry-After ${error.retryAfter} s, ` +
+                        `send ${retries + 1} of ${RATE_LIMIT_RETRIES + 1}`);
+                }
+                const pause = this.#pause(method, error, retries, waited);
+                if (pause === null)
+                    throw error;
+                if (error instanceof WebAPIRateLimitedError) {
+                    // The one pause whose length Slack names, and the one a stop may leave: see
+                    // `ClientOptions.stopped`.
+                    if (this.#stopped?.aborted)
+                        throw error;
+                    waited += error.retryAfter;
+                    try {
+                        await this.#clock.sleep(pause, this.#stopped);
+                    }
+                    catch (stop) {
+                        if (this.#stopped?.aborted)
+                            throw error;
+                        throw stop;
+                    }
+                }
+                else {
+                    await this.#clock.sleep(pause);
+                }
+            }
+        }
+    }
+}
+/** The shared client: connection, server error and rate limit retries for every call. */
+export function sharedClient(token, options = {}) {
+    return new PolicyClient(token, [], options);
+}
+/**
+ * The replies client: the shared client's policy, except that `CREATING_METHODS` are not resent
+ * on a connection failure or a server error.
+ */
+export function repliesClient(token, options = {}) {
+    return new PolicyClient(token, CREATING_METHODS, options);
+}

package/dist/chat/slack/reply/errors.js

@@ -0,0 +1,125 @@
+/** What a failed Slack call says, in words that are safe to log and to decide on. */
+import { WebAPIHTTPError, WebAPIPlatformError, WebAPIRateLimitedError, WebAPIRequestError, } from "@slack/web-api";
+import { getLogger } from "../../../log.js";
+import { errorName } from "../../../values.js";
+// The sink's lines all go under one logger name. `sinks.ts` imports this logger and, through
+// `export *`, its callers get the `Logger` type from here.
+export const logger = getLogger("allaboard.chat.slack.reply.sinks");
+// chat.update errors that refuse the content itself (reference, read 2026-09-25): a plain retry
+// can pass where the blocks did not. A transient error such as `ratelimited` is not one.
+export const REFUSED_CONTENT = new Set([
+    "invalid_blocks",
+    "invalid_blocks_format",
+    "msg_too_long",
+    "invalid_arguments",
+]);
+// Slack's answers about a stream's state (measured 2026-09-28): it is over, or still open.
+export const NOT_STREAMING = "message_not_in_streaming_state";
+// The one refusal of an append's content measured on `chat.appendStream` (2026-10-01, slack-sdk
+// 3.44.1), and the one a `chat.update` of the same message was seen to pass.
+export const TOO_LONG = "msg_too_long";
+export const STILL_STREAMING = "streaming_state_conflict";
+/** The system's code for a request that never got an answer (`ECONNRESET`), else the error's name. */
+function requestFailure(original) {
+    let cause = original;
+    for (let depth = 0; depth < 4 && cause instanceof Error; depth += 1) {
+        const code = cause.code;
+        if (typeof code === "string" && code)
+            return code;
+        cause = cause.cause;
+    }
+    return original.name;
+}
+/** Slack's error code, or the error's type: never the request or its content. */
+export function describe(error) {
+    if (error instanceof WebAPIPlatformError)
+        return String(error.data.error);
+    // The code Slack gives a call past its rate limit (HTTP 429).
+    if (error instanceof WebAPIRateLimitedError)
+        return "ratelimited";
+    if (error instanceof WebAPIHTTPError)
+        return `http_${error.statusCode}`;
+    if (error instanceof WebAPIRequestError)
+        return requestFailure(error.original);
+    return errorName(error);
+}
+// What Slack says of a message whose blocks, once it has translated the markdown ones, pass 50
+// (measured 2026-10-08 on `chat.update` and `chat.postMessage`, slack-sdk 3.45.0).
+export const TOO_MANY_BLOCKS = "no more than 50 items allowed";
+export const JSON_POINTER = /\[json-pointer:([^\]]*)\]/g;
+/** The sentences Slack adds to a refused write, which say what in the payload it refused. */
+export function refusalNotes(error) {
+    if (!(error instanceof WebAPIPlatformError))
+        return [];
+    const notes = error.data.response_metadata?.messages ?? [];
+    return notes.map((note) => String(note));
+}
+export function tooManyBlocks(error) {
+    return refusalNotes(error).some((note) => note.includes(TOO_MANY_BLOCKS));
+}
+/**
+ * `describe`, with where in the payload Slack pointed and whether it counted too many blocks:
+ * paths and a fixed phrase, never Slack's own sentence, which can quote a value.
+ */
+export function describeRefusal(error) {
+    let words = describe(error);
+    const where = new Set();
+    for (const note of refusalNotes(error)) {
+        for (const match of note.matchAll(JSON_POINTER))
+            where.add(match[1] ?? "");
+    }
+    if (where.size > 0)
+        words += ` at ${[...where].sort().join(", ")}`;
+    if (tooManyBlocks(error))
+        words += ", over 50 blocks once translated";
+    return words;
+}
+// What Slack answers about a channel or a message it no longer has: the only refusals taken as
+// final by the Home tab and by the crash repair. Any other failure (a rate limit, a server
+// error, the network) is no answer.
+export const GONE = new Set([
+    "channel_not_found",
+    "message_not_found",
+    "thread_not_found",
+]);
+/** Whether Slack answered that the channel or the message is not there any more. */
+export function gone(error) {
+    return error instanceof WebAPIPlatformError && GONE.has(describe(error));
+}
+/**
+ * Whether a failed call may have been applied: Slack answering with an error says it was not
+ * (an error code, a rate limit, an HTTP status), anything else (a reset, a timeout) says nothing.
+ */
+export function unknownOutcome(error) {
+    return !(error instanceof WebAPIPlatformError ||
+        error instanceof WebAPIRateLimitedError ||
+        error instanceof WebAPIHTTPError);
+}
+/**
+ * Delete a request (an approval, a question, a hold) once it is decided or stale:
+ * `message_not_found` counts as done, as everywhere else this project deletes one. Shared by the
+ * session, the handlers and the crash repair, so the one behaviour lives in one place. False
+ * when Slack did not delete it and did not say it is gone.
+ */
+export async function deleteRequest(slack, request, options = {}) {
+    const log = options.logger ?? logger;
+    const { channel, ts } = request;
+    try {
+        await slack.chat.delete({ channel, ts });
+    }
+    catch (error) {
+        if (describe(error) !== "message_not_found") {
+            log.warning(`could not remove a request in ${channel}: ${describe(error)}`);
+            return false;
+        }
+    }
+    // Issue #71: a message ts is its post time in epoch seconds, so the age of a request when it
+    // goes is read from the log with no timer kept for it. Ids and a duration only.
+    const now = (options.now ?? (() => Date.now() / 1000))();
+    const posted = Number(ts);
+    const age = ts.trim() === "" || Number.isNaN(posted)
+        ? "age unknown"
+        : `${(now - posted).toFixed(1)}s after it was posted`;
+    log.info(`removed a request in ${channel}: message ${ts}, ${age}`);
+    return true;
+}

package/dist/chat/slack/reply/escape.js

@@ -0,0 +1,25 @@
+/**
+ * Third-party text shown as written in Slack's two markup languages. A leaf module, so the
+ * footer, the sinks, the approvals and the lists can all use it without an import cycle.
+ */
+// The characters that start inline formatting in a markdown block, each escapable with a backslash
+// (Slack's markdown block reference, read 2026-09-25). `#`, `+`, `-`, `.` and `!` act only at the
+// start of a line. `~` is not in the reference's list, but `~~` renders as strikethrough (measured
+// live 2026-09-25); `<` stays text there.
+const MARKDOWN_INLINE = /([\\`*_{}[\]()&~])/g;
+/** Slack's mrkdwn reads `&`, `<` and `>` as markup; a tool's title is shown as written. */
+export function mrkdwnEscape(text) {
+    return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+/** Text for inside a markdown block's own formatting, shown as written. */
+export function markdownEscape(text) {
+    return text.replace(MARKDOWN_INLINE, "\\$1");
+}
+/**
+ * Model-written text for mrkdwn, shown as written: `&`, `<` and `>` escaped, so no
+ * `<url|label>` can hide what it links, and a zero-width space after each backtick, so no
+ * run of three can close a code block.
+ */
+export function shownAsWritten(text) {
+    return mrkdwnEscape(text).replaceAll("`", "`​");
+}

package/dist/chat/slack/reply/limiter.js

@@ -0,0 +1,86 @@
+/** The budget of writes every reply in the process shares. */
+import { monotonicClock } from "../../../clock.js";
+import { Mutex } from "../../../core/port.js";
+import { getLogger } from "../../../log.js";
+export const logger = getLogger("allaboard.chat.slack.reply.limiter");
+// chat.update is Tier 3, "50+ per minute" per app (chat.update reference, read 2026-09-28): 40
+// per 60 s plus a burst of 5, worst case 45 in one window, a real margin under the documented
+// floor. Paced evenly (a token bucket, not a sliding window) past the burst, so a busy minute is
+// a steady trickle rather than every reply racing through the budget together and then freezing
+// until it resets.
+export const UPDATE_LIMIT = 40;
+export const UPDATE_WINDOW_SECONDS = 60.0;
+// How many writes the budget lets through at once before pacing kicks in: enough for a reply
+// that just started to show its first few lines without waiting on threads that were already busy.
+export const UPDATE_BURST = 5;
+// A write that waited this long for its turn is logged (issue #203): one token takes
+// `UPDATE_WINDOW_SECONDS / UPDATE_LIMIT` (1.5 s) to come back, so a wait this long is a line of
+// writes ahead, which is when the budget delays what the owner sees. The number is the
+// project's own.
+export const UPDATE_WAIT_LOGGED_SECONDS = 5.0;
+/**
+ * One instance shared by every `ReplySink` in the process, so their chat.update writes stay
+ * under Slack's app-wide budget: a token bucket refilling at `limit` tokens per `window` seconds
+ * (evenly, one token every `window / limit`), holding at most `burst` at once. A caller that has
+ * to wait keeps its place in line, since it holds the lock for as long as it waits, so the next
+ * caller queues up behind it. A retry the Slack client makes under the hood, inside one
+ * `chat.update` call, spends no extra token here: the limiter only gates the call itself, not
+ * what the client does while it is in flight.
+ */
+export class UpdateLimiter {
+    /** Tokens regained per second. */
+    rate;
+    burst;
+    clock;
+    log;
+    tokens;
+    checked;
+    lock = new Mutex();
+    constructor(options = {}) {
+        const limit = options.limit ?? UPDATE_LIMIT;
+        const window = options.window ?? UPDATE_WINDOW_SECONDS;
+        this.rate = limit / window;
+        this.burst = options.burst ?? UPDATE_BURST;
+        this.clock = options.clock ?? monotonicClock;
+        this.log = options.logger ?? logger;
+        this.tokens = this.burst;
+        this.checked = this.clock.time();
+    }
+    /**
+     * Waits until a token is available, then spends it. A signal that aborts gives the place up.
+     * A wait of `UPDATE_WAIT_LOGGED_SECONDS` or more, the line of callers ahead included, is logged.
+     */
+    async acquire(signal) {
+        const asked = this.clock.time();
+        const release = await this.lock.acquire(signal);
+        try {
+            for (;;) {
+                const now = this.clock.time();
+                this.tokens = Math.min(this.burst, this.tokens + (now - this.checked) * this.rate);
+                this.checked = now;
+                if (this.tokens >= 1) {
+                    this.tokens -= 1;
+                    const waited = now - asked;
+                    if (waited >= UPDATE_WAIT_LOGGED_SECONDS) {
+                        this.log.info(`a write waited ${waited.toFixed(1)} s for the shared budget of updates`);
+                    }
+                    return;
+                }
+                await this.clock.sleep((1 - this.tokens) / this.rate, signal);
+            }
+        }
+        finally {
+            release();
+        }
+    }
+    /**
+     * Give back a token `acquire` spent on a write that, once inside the caller's own lock, turned
+     * out not to be needed after all (the reply caught up to what it now shows while this one
+     * waited its turn): capped at `burst`, as a token earned by waiting would be. Never takes the
+     * lock: a concurrent `acquire` can hold it for as long as its own wait takes, and this must
+     * land at once regardless; `acquire` always rereads the tokens fresh on its own next pass.
+     */
+    async refund() {
+        this.tokens = Math.min(this.burst, this.tokens + 1);
+    }
+}

package/dist/chat/slack/reply/markdown.js

@@ -0,0 +1,210 @@
+/**
+ * Claude's markdown as Slack reads it: how many blocks it makes of a text and where to cut one,
+ * and the text with its markers gone, for a notification's banner.
+ *
+ * The patterns follow Python's regular expression rules where the two engines differ: Python's
+ * `\s` and `\w` are Unicode (`PY_SPACE`, `WORD`), its `.` stops at `\n` only, and its `^` under
+ * `re.M` starts a line after `\n` only (JavaScript's also after `\r`, U+2028 and U+2029).
+ */
+import { blank, PY_SPACE, strip } from "../../../text.js";
+import { len } from "./chars.js";
+import { mrkdwnEscape } from "./escape.js";
+const S = `[${PY_SPACE}]`;
+// Python's `\w` on text: a letter or a digit of any script, or `_`.
+const WORD = "[\\p{L}\\p{N}_]";
+// Slack stores a `markdown` block, and a stream's `markdown_text`, as several blocks: a header
+// per heading, a table per table, a divider per rule, and rich text for each run of anything
+// else between them. A write by `chat.update` or `chat.postMessage` is refused when the message
+// passes 50 of them; a stream is not, and the update that follows its stop is (measured
+// 2026-10-08, slack-sdk 3.45.0). Quotes, lists, images, bold lines and code blocks stay in the
+// rich text around them, and a `#` inside a code block is not a heading.
+// Read as CommonMark and GFM define them where Slack was not measured (a heading underlined
+// with `=`, a fence longer than three marks, a rule with spaces in it): a shape counted that
+// Slack keeps in its rich text only ends a message early.
+// Sticky, so that it reads a heading at an offset of a whole text as well as at a line's start.
+const HEADING = new RegExp(` {0,3}#{1,6}(?:${S}|$)`, "y");
+const UNDERLINE = new RegExp(`^ {0,3}=+${S}*$`);
+const RULE = new RegExp(`^ {0,3}([-*_])(?:${S}*\\1){2,}${S}*$`);
+const TABLE_CELL = /^:?-+:?$/;
+const FENCE = /^ {0,3}(`{3,}|~{3,})([^\n]*)$/;
+/** Whether a heading starts at `offset` of `text`. */
+export function headingAt(text, offset) {
+    HEADING.lastIndex = offset;
+    return HEADING.test(text);
+}
+/** Python's `line.rstrip("\r")`. */
+function rstripReturns(line) {
+    let end = line.length;
+    while (end > 0 && line.charCodeAt(end - 1) === 0x0d)
+        end -= 1;
+    return line.slice(0, end);
+}
+/**
+ * Whether `line` is a table's delimiter row: cells of dashes, each with an optional colon at
+ * either end, between pipes, the first and the last pipe optional.
+ *
+ * Read cell by cell, in time linear in the line. The agent writes the text, and one pattern for
+ * the whole row backtracks in cubic time on a long run of spaces (measured 2026-10-11, Node
+ * 26.5.1), on the event loop every thread shares.
+ */
+function tableRule(line) {
+    let row = strip(line);
+    if (row.startsWith("|"))
+        row = row.slice(1);
+    if (row.endsWith("|"))
+        row = row.slice(0, -1);
+    return row.split("|").every((cell) => TABLE_CELL.test(strip(cell)));
+}
+/** Where each block starts that Slack makes of a markdown text, as offsets into it. */
+export function markdownStarts(text) {
+    const starts = [];
+    const lines = text.split("\n");
+    let offset = 0;
+    let fence = "";
+    let running = false;
+    let table = false;
+    for (const [number, raw] of lines.entries()) {
+        const here = offset;
+        offset += raw.length + 1;
+        const line = rstripReturns(raw);
+        const mark = FENCE.exec(line);
+        const run = mark?.[1] ?? "";
+        const info = mark?.[2] ?? "";
+        if (fence) {
+            // Closed by a run of the same mark, at least as long, with nothing after it.
+            if (mark !== null && run.startsWith(fence) && blank(info))
+                fence = "";
+        }
+        else if (mark !== null && !info.includes("`")) {
+            fence = run;
+            table = false;
+        }
+        else {
+            if (blank(line)) {
+                table = false;
+                continue;
+            }
+            if (table && line.includes("|"))
+                continue;
+            table = false;
+            const following = rstripReturns(lines[number + 1] ?? "");
+            if (line.includes("|") && following.includes("|") && tableRule(following)) {
+                starts.push(here);
+                table = true;
+                running = false;
+                continue;
+            }
+            if (headingAt(line, 0) || RULE.test(line) || (running && UNDERLINE.test(line))) {
+                starts.push(here);
+                running = false;
+                continue;
+            }
+        }
+        if (!running) {
+            starts.push(here);
+            running = true;
+        }
+    }
+    return starts;
+}
+/** How many blocks a markdown text with words in it counts in a message. */
+export function markdownBlocks(text) {
+    return Math.max(1, markdownStarts(text).length);
+}
+/**
+ * Where to cut a markdown text so that it makes at most `room` blocks, at a block's start no
+ * earlier than `floor` (what a stream was already sent); null when nothing is to cut. A heading
+ * is never the last block before the cut, nor the last of a text that fills the room: it opens
+ * the next message, with the text it heads.
+ */
+export function markdownCut(text, room, floor = 0) {
+    const starts = markdownStarts(text);
+    let index = starts.length === room ? starts.length : null;
+    if (starts.length > room) {
+        index = null;
+        for (let i = room; i < starts.length; i += 1) {
+            if ((starts.at(i) ?? 0) >= floor) {
+                index = i;
+                break;
+            }
+        }
+    }
+    if (index === null)
+        return null;
+    for (;;) {
+        const before = starts[index - 1];
+        if (index <= 1 || before === undefined || before < floor || !headingAt(text, before))
+            break;
+        index -= 1;
+    }
+    return starts[index] ?? null;
+}
+// A pattern that reads ahead and then fails is tried again from every later start, which is
+// quadratic on a long run of `[`, of blank lines or of `_` inside a word. So the three that read
+// ahead also match what they read where no marker is (a `[` no link closes, space no marker
+// follows, `_` between two letters), and the replacement puts that back as it was.
+const LINK = /\[([^\]]*)(?:\](?:\([^)]*(\))?)?)?/g;
+// `(?<![^\n])` is Python's `^` under `re.M`; `\p{Nd}` its `\d`.
+const LINE_MARKER = new RegExp(`(?<![^\\n])${S}*((?:#+|>|[-+*]|\\p{Nd}+\\.)${S}+)?`, "gu");
+const PAIRED = /\*\*|__|~~|`+/g;
+const EMPHASIS = new RegExp(`(?<!${WORD})[*_]+|[*_]+(?!${WORD})|(_+)`, "gu");
+/**
+ * The markdown markers of `text` removed, nothing escaped, in a time linear in the text: a
+ * banner is cut from a paragraph as long as Claude wrote it.
+ */
+export function stripMarkdown(text) {
+    let plain = text.replace(LINK, (all, label, closed) => closed ? label : all);
+    plain = plain.replace(LINE_MARKER, (all, marker) => marker ? "" : all);
+    plain = plain.replace(PAIRED, "");
+    plain = plain.replace(EMPHASIS, (_all, kept) => kept ?? "");
+    return strip(plain);
+}
+/**
+ * A paragraph of Claude's markdown as the plain `text` of a notification: the markers gone
+ * (headings, quotes, list bullets, emphasis, code ticks, link targets) and `&`, `<`, `>`
+ * escaped, since Slack reads them as markup there too. With `limit` it is cut before it is
+ * escaped, so the result holds at most that many characters and no half an entity.
+ */
+export function bannerText(paragraph, options = {}) {
+    const plain = stripMarkdown(paragraph);
+    const limit = options.limit;
+    if (limit === undefined)
+        return mrkdwnEscape(plain);
+    const out = [];
+    let size = 0;
+    // By code point: an emoji is one character of the limit.
+    for (const char of plain) {
+        const piece = mrkdwnEscape(char);
+        const cost = len(piece);
+        if (size + cost > limit)
+            break;
+        out.push(piece);
+        size += cost;
+    }
+    return out.join("");
+}
+// A `<` with what follows it up to the next `|` or `>`, and the label when a `|...>` comes
+// next. The stretch with no label is matched too, so that the search goes on after it: no `<`
+// inside it opens a link either, since it would stop at the same `|` or `>`.
+const LABELLED = /<[^|>]*(?:\|([^>]*)>)?/g;
+const WORDS = new RegExp(`${WORD}+`, "gu");
+/**
+ * `text` with each `<target|label>` replaced by its label: what `/<[^|>]*\|([^>]*)>/g` and
+ * `"$1"` give, in a time linear in the text (issue #241: that pattern starts again at every `<`
+ * of a run, and reads to the end each time). A link ends at a `>`, so the text after the last
+ * one is left unread, and every `|` in what is read has a `>` after it.
+ */
+function labelsOnly(text) {
+    const end = text.lastIndexOf(">") + 1;
+    const read = text.slice(0, end).replace(LABELLED, (whole, label) => label ?? whole);
+    return read + text.slice(end);
+}
+/**
+ * The words of a text with the markup, the punctuation and the spacing gone: what two
+ * renderings of one text (Claude's markdown and Slack's converted read-back of it, with `*b*`
+ * for `**b**`, `<url|label>` for a link, `•` for a bullet) have in common.
+ */
+export function plainWords(text) {
+    const words = stripMarkdown(labelsOnly(text)).match(WORDS) ?? [];
+    return words.join(" ").toLowerCase();
+}