@botcord/daemon 0.2.36 → 0.2.38

package/dist/gateway/channels/state-store.d.ts

@@ -0,0 +1,60 @@
+/**
+ * On-disk cursor + provider-state for one third-party gateway. Kept separate
+ * from `secret-store` so high-frequency cursor advancements don't churn the
+ * secret file (and so cursor doesn't end up in any secret backup).
+ */
+export interface ThirdPartyGatewayState {
+    cursor?: string;
+    providerState?: Record<string, unknown>;
+    updatedAt: string;
+}
+export declare function defaultGatewayStatePath(gatewayId: string, override?: string): string;
+export interface GatewayStateStoreOptions {
+    /** Override the on-disk path; defaults to `~/.botcord/daemon/gateways/{id}.state.json`. */
+    override?: string;
+    /** Debounce window for batching writes; defaults to 1000ms. Use `0` for sync writes (tests). */
+    debounceMs?: number;
+}
+export declare class GatewayStateStore {
+    private readonly file;
+    private readonly debounceMs;
+    private state;
+    private timer;
+    private dirty;
+    private flushRetryCount;
+    /** W9: most recent write error surfaced for diagnostics. Cleared on success. */
+    lastError: Error | null;
+    constructor(gatewayId: string, opts?: GatewayStateStoreOptions);
+    /** Read the current cursor (in-memory; reflects pending writes). */
+    getCursor(): string | undefined;
+    /** Read the current provider-state bag. Mutating the returned object does not persist. */
+    getProviderState(): Record<string, unknown> | undefined;
+    getSnapshot(): ThirdPartyGatewayState;
+    /** Update cursor + optional provider state and schedule a debounced flush. */
+    update(patch: {
+        cursor?: string;
+        providerState?: Record<string, unknown>;
+    }): void;
+    /**
+     * Force a synchronous write of the pending state, if any.
+     *
+     * W9: on write failure, leave `dirty=true` and re-arm the debounce timer
+     * so a subsequent `update()` (or background timer fire) retries instead of
+     * silently dropping the pending state. The error is also re-thrown so
+     * callers that explicitly invoke `flush()` (shutdown paths, tests) see it.
+     */
+    flush(): void;
+    /** Flush and stop accepting future debounced writes. */
+    close(): void;
+    /** On-disk path; exposed for tests and diagnostics. */
+    get filePath(): string;
+    private scheduleFlush;
+    /**
+     * Re-arm the debounce timer after a write failure. Bounded delay (capped
+     * at 5s) so transient failures do not become a hot-spin retry loop.
+     * After MAX_FLUSH_RETRIES consecutive failures, log and stop retrying so
+     * a permanently broken write path cannot loop indefinitely. `lastError` is
+     * left set so callers can detect persistent failure.
+     */
+    private scheduleFlushRetry;
+}

package/dist/gateway/channels/state-store.js

@@ -0,0 +1,173 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+const DEFAULT_GATEWAYS_DIR = path.join(homedir(), ".botcord", "daemon", "gateways");
+const DEFAULT_DEBOUNCE_MS = 1000;
+export function defaultGatewayStatePath(gatewayId, override) {
+    if (override && override.length > 0)
+        return override;
+    return path.join(DEFAULT_GATEWAYS_DIR, `${gatewayId}.state.json`);
+}
+function readState(file) {
+    if (!existsSync(file))
+        return { updatedAt: new Date(0).toISOString() };
+    try {
+        return JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return { updatedAt: new Date(0).toISOString() };
+    }
+}
+function writeStateSync(file, state) {
+    const dir = path.dirname(file);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const tmp = `${file}.tmp`;
+    writeFileSync(tmp, JSON.stringify(state, null, 2), { mode: 0o600 });
+    renameSync(tmp, file);
+}
+/**
+ * Per-gateway state store with debounced writes. Reads are always synchronous
+ * against the in-memory snapshot, so the polling loop sees its own writes
+ * even before they are flushed to disk. `flush()` is exposed for shutdown
+ * paths and tests; `close()` flushes and clears the timer.
+ */
+const MAX_FLUSH_RETRIES = 10;
+export class GatewayStateStore {
+    file;
+    debounceMs;
+    state;
+    timer = null;
+    dirty = false;
+    flushRetryCount = 0;
+    /** W9: most recent write error surfaced for diagnostics. Cleared on success. */
+    lastError = null;
+    constructor(gatewayId, opts = {}) {
+        this.file = defaultGatewayStatePath(gatewayId, opts.override);
+        this.debounceMs = opts.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+        this.state = readState(this.file);
+    }
+    /** Read the current cursor (in-memory; reflects pending writes). */
+    getCursor() {
+        return this.state.cursor;
+    }
+    /** Read the current provider-state bag. Mutating the returned object does not persist. */
+    getProviderState() {
+        return this.state.providerState;
+    }
+    getSnapshot() {
+        return { ...this.state };
+    }
+    /** Update cursor + optional provider state and schedule a debounced flush. */
+    update(patch) {
+        if (patch.cursor !== undefined)
+            this.state.cursor = patch.cursor;
+        if (patch.providerState !== undefined) {
+            this.state.providerState = patch.providerState;
+        }
+        this.state.updatedAt = new Date().toISOString();
+        this.scheduleFlush();
+    }
+    /**
+     * Force a synchronous write of the pending state, if any.
+     *
+     * W9: on write failure, leave `dirty=true` and re-arm the debounce timer
+     * so a subsequent `update()` (or background timer fire) retries instead of
+     * silently dropping the pending state. The error is also re-thrown so
+     * callers that explicitly invoke `flush()` (shutdown paths, tests) see it.
+     */
+    flush() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        if (!this.dirty)
+            return;
+        try {
+            writeStateSync(this.file, this.state);
+            this.dirty = false;
+            this.lastError = null;
+            this.flushRetryCount = 0;
+        }
+        catch (err) {
+            this.lastError = err instanceof Error ? err : new Error(String(err));
+            // Keep dirty=true so the next update() re-arms a flush. We also
+            // schedule a retry now in case the caller has nothing else queued.
+            this.scheduleFlushRetry();
+            throw this.lastError;
+        }
+    }
+    /** Flush and stop accepting future debounced writes. */
+    close() {
+        this.flush();
+    }
+    /** On-disk path; exposed for tests and diagnostics. */
+    get filePath() {
+        return this.file;
+    }
+    scheduleFlush() {
+        this.dirty = true;
+        if (this.debounceMs <= 0) {
+            // W9: synchronous mode — re-throw on failure so the caller sees the
+            // problem instead of having the data silently disappear.
+            this.flush();
+            return;
+        }
+        if (this.timer)
+            return;
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            if (!this.dirty)
+                return;
+            try {
+                writeStateSync(this.file, this.state);
+                this.dirty = false;
+                this.lastError = null;
+                this.flushRetryCount = 0;
+            }
+            catch (err) {
+                // W9: keep dirty=true and re-arm so the failed write retries.
+                this.lastError = err instanceof Error ? err : new Error(String(err));
+                this.scheduleFlushRetry();
+            }
+        }, this.debounceMs);
+        if (typeof this.timer.unref === "function")
+            this.timer.unref();
+    }
+    /**
+     * Re-arm the debounce timer after a write failure. Bounded delay (capped
+     * at 5s) so transient failures do not become a hot-spin retry loop.
+     * After MAX_FLUSH_RETRIES consecutive failures, log and stop retrying so
+     * a permanently broken write path cannot loop indefinitely. `lastError` is
+     * left set so callers can detect persistent failure.
+     */
+    scheduleFlushRetry() {
+        if (this.debounceMs <= 0)
+            return; // sync mode: caller decides
+        if (this.timer)
+            return;
+        this.flushRetryCount += 1;
+        if (this.flushRetryCount > MAX_FLUSH_RETRIES) {
+            // Persistent failure — give up. lastError remains set for diagnostics.
+            console.error(`[state-store] flush failed ${MAX_FLUSH_RETRIES} times; giving up on ${this.file}`, this.lastError);
+            return;
+        }
+        const retryMs = Math.min(Math.max(this.debounceMs, 250), 5000);
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            if (!this.dirty)
+                return;
+            try {
+                writeStateSync(this.file, this.state);
+                this.dirty = false;
+                this.lastError = null;
+                this.flushRetryCount = 0;
+            }
+            catch (err) {
+                this.lastError = err instanceof Error ? err : new Error(String(err));
+                this.scheduleFlushRetry();
+            }
+        }, retryMs);
+        if (typeof this.timer.unref === "function")
+            this.timer.unref();
+    }
+}

package/dist/gateway/channels/telegram.d.ts

@@ -0,0 +1,31 @@
+import type { ChannelAdapter } from "../types.js";
+/** Options accepted by {@link createTelegramChannel}. */
+export interface TelegramChannelOptions {
+    id: string;
+    accountId: string;
+    /** Bot token. When omitted, the adapter loads it from the secret-store on start. */
+    botToken?: string;
+    baseUrl?: string;
+    /** Empty / missing list = default-deny. */
+    allowedSenderIds?: string[];
+    /** Empty / missing list = default-deny. */
+    allowedChatIds?: string[];
+    splitAt?: number;
+    secretFile?: string;
+    stateFile?: string;
+    /** Test hook: override `globalThis.fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Test hook: synchronous state writes (`debounceMs: 0`). */
+    stateDebounceMs?: number;
+}
+/**
+ * Telegram channel adapter — long-polls `getUpdates`, normalizes text messages
+ * to `GatewayInboundEnvelope`, and writes replies via `sendMessage`. Cursor
+ * (`update_id + 1`) is persisted to the state-store so a daemon restart never
+ * replays the last batch.
+ *
+ * Allowlists are default-deny: an empty (or missing) `allowedChatIds` /
+ * `allowedSenderIds` rejects every inbound message. This matches the security
+ * default in the third-party-gateway design doc.
+ */
+export declare function createTelegramChannel(opts: TelegramChannelOptions): ChannelAdapter;

package/dist/gateway/channels/telegram.js

@@ -0,0 +1,371 @@
+import { sanitizeUntrustedContent } from "./sanitize.js";
+import { GatewayStateStore } from "./state-store.js";
+import { loadGatewaySecret } from "./secret-store.js";
+import { splitText } from "./text-split.js";
+const DEFAULT_BASE_URL = "https://api.telegram.org";
+const DEFAULT_SPLIT_AT = 4000; // Telegram hard limit is 4096; leave slack.
+const POLL_TIMEOUT_S = 25;
+const POLL_BACKOFF_MS = 3000;
+const TRANSIENT_BACKOFF_MS = 1000;
+const TELEGRAM_PROVIDER = "telegram";
+/**
+ * Telegram channel adapter — long-polls `getUpdates`, normalizes text messages
+ * to `GatewayInboundEnvelope`, and writes replies via `sendMessage`. Cursor
+ * (`update_id + 1`) is persisted to the state-store so a daemon restart never
+ * replays the last batch.
+ *
+ * Allowlists are default-deny: an empty (or missing) `allowedChatIds` /
+ * `allowedSenderIds` rejects every inbound message. This matches the security
+ * default in the third-party-gateway design doc.
+ */
+export function createTelegramChannel(opts) {
+    const channelType = TELEGRAM_PROVIDER;
+    const baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    const splitAt = opts.splitAt && opts.splitAt > 0 ? opts.splitAt : DEFAULT_SPLIT_AT;
+    const allowedSenderIds = new Set((opts.allowedSenderIds ?? []).map((s) => String(s)));
+    const allowedChatIds = new Set((opts.allowedChatIds ?? []).map((s) => String(s)));
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    let botToken = opts.botToken;
+    let started = false;
+    /**
+     * C3: Redact the bot token from any log/error string. Telegram's Bot API
+     * embeds the token in the URL path, so fetch errors and JSON.parse failures
+     * routinely include it. Replace before any log.* call.
+     */
+    function redactToken(input) {
+        if (!botToken || !input)
+            return input;
+        return input.split(botToken).join("***");
+    }
+    let stateStore = null;
+    let stopCallback = null;
+    // W11: captured during start() so send() can push lastSendAt to the
+    // gateway-tracked snapshot, not just the local statusSnapshot.
+    let liveSetStatus = null;
+    let statusSnapshot = {
+        channel: opts.id,
+        accountId: opts.accountId,
+        running: false,
+        connected: false,
+        reconnectAttempts: 0,
+        lastError: null,
+        provider: TELEGRAM_PROVIDER,
+        authorized: false,
+    };
+    function ensureState() {
+        if (!stateStore) {
+            stateStore = new GatewayStateStore(opts.id, {
+                ...(opts.stateFile ? { override: opts.stateFile } : {}),
+                ...(opts.stateDebounceMs !== undefined
+                    ? { debounceMs: opts.stateDebounceMs }
+                    : {}),
+            });
+        }
+        return stateStore;
+    }
+    function loadTokenFromSecretIfNeeded() {
+        if (botToken)
+            return botToken;
+        const secret = loadGatewaySecret(opts.id, opts.secretFile);
+        if (secret && typeof secret.botToken === "string" && secret.botToken.length > 0) {
+            botToken = secret.botToken;
+        }
+        return botToken;
+    }
+    async function callApi(method, params, timeoutMs) {
+        if (!botToken)
+            throw new Error("telegram bot token not loaded");
+        const url = `${baseUrl}/bot${botToken}/${method}`;
+        let resp;
+        try {
+            resp = await fetchImpl(url, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(params),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+        }
+        catch (err) {
+            // C3: fetch errors often stringify the URL (which embeds the token).
+            // Re-raise with the token replaced.
+            const e = err;
+            const redacted = redactToken(e.message ?? String(err));
+            const next = new Error(redacted);
+            next.name = e.name ?? "Error";
+            throw next;
+        }
+        const json = (await resp.json());
+        return json;
+    }
+    function chatIdFromConversation(conversationId) {
+        if (conversationId.startsWith("telegram:user:")) {
+            return conversationId.slice("telegram:user:".length);
+        }
+        if (conversationId.startsWith("telegram:group:")) {
+            return conversationId.slice("telegram:group:".length);
+        }
+        return null;
+    }
+    function normalizeUpdate(update) {
+        const msg = update.message;
+        if (!msg)
+            return null;
+        const text = typeof msg.text === "string" ? msg.text : null;
+        if (text === null)
+            return null;
+        const from = msg.from;
+        if (!from)
+            return null;
+        const chat = msg.chat;
+        if (!chat)
+            return null;
+        const fromUserId = String(from.id);
+        const chatId = String(chat.id);
+        // W5: default-deny is the INTERSECTION — both chatId AND senderId must
+        // appear in their respective allowlists. An empty list rejects everyone.
+        // TODO: surface this rule in the dashboard help text (frontend).
+        if (!allowedChatIds.has(chatId))
+            return null;
+        if (!allowedSenderIds.has(fromUserId))
+            return null;
+        const isPrivate = chat.type === "private";
+        const conversationId = isPrivate
+            ? `telegram:user:${chatId}`
+            : `telegram:group:${chatId}`;
+        const conversationKind = isPrivate ? "direct" : "group";
+        const senderName = from.username ??
+            [from.first_name].filter((s) => typeof s === "string" && s.length > 0)[0];
+        const sanitized = sanitizeUntrustedContent(text);
+        const messageId = `telegram:${chatId}:${msg.message_id}`;
+        return {
+            id: messageId,
+            channel: opts.id,
+            accountId: opts.accountId,
+            conversation: {
+                id: conversationId,
+                kind: conversationKind,
+                ...(chat.title ? { title: chat.title } : {}),
+            },
+            sender: {
+                id: `telegram:user:${fromUserId}`,
+                ...(senderName ? { name: senderName } : {}),
+                kind: "user",
+            },
+            text: sanitized,
+            raw: update,
+            replyTo: null,
+            mentioned: false,
+            receivedAt: Date.now(),
+            trace: { id: messageId, streamable: false },
+        };
+    }
+    async function pollLoop(ctx) {
+        const { abortSignal, log, emit, setStatus } = ctx;
+        liveSetStatus = setStatus;
+        const state = ensureState();
+        function markStatus(patch) {
+            statusSnapshot = { ...statusSnapshot, ...patch };
+            setStatus(patch);
+        }
+        if (!loadTokenFromSecretIfNeeded()) {
+            markStatus({
+                running: false,
+                connected: false,
+                authorized: false,
+                lastError: "missing_secret",
+            });
+            log.error("telegram missing bot token", { gatewayId: opts.id });
+            return;
+        }
+        let offset = 0;
+        const cursor = state.getCursor();
+        if (cursor) {
+            const parsed = Number(cursor);
+            if (Number.isFinite(parsed))
+                offset = parsed;
+        }
+        markStatus({
+            running: true,
+            connected: true,
+            authorized: true,
+            reconnectAttempts: 0,
+            lastError: null,
+            lastStartAt: Date.now(),
+        });
+        log.info("telegram poll loop starting", { gatewayId: opts.id, offset });
+        let stopped = false;
+        const onAbort = () => {
+            stopped = true;
+        };
+        abortSignal.addEventListener("abort", onAbort, { once: true });
+        stopCallback = () => {
+            stopped = true;
+        };
+        while (!stopped && !abortSignal.aborted) {
+            try {
+                const resp = await callApi("getUpdates", {
+                    offset,
+                    timeout: POLL_TIMEOUT_S,
+                    allowed_updates: ["message"],
+                }, (POLL_TIMEOUT_S + 15) * 1000);
+                markStatus({ lastPollAt: Date.now() });
+                if (!resp.ok) {
+                    log.warn("telegram getUpdates non-ok", {
+                        description: redactToken(resp.description ?? ""),
+                    });
+                    markStatus({ lastError: redactToken(resp.description ?? "getUpdates failed") });
+                    await sleep(POLL_BACKOFF_MS, abortSignal);
+                    continue;
+                }
+                const updates = resp.result ?? [];
+                if (updates.length === 0)
+                    continue;
+                // W1: persist cursor only AFTER all emits return cleanly. If emit
+                // throws, leave the cursor untouched so the same batch retries on
+                // the next poll instead of being silently dropped.
+                let maxId = offset - 1;
+                for (const u of updates) {
+                    if (u.update_id > maxId)
+                        maxId = u.update_id;
+                }
+                let emitFailed = false;
+                for (const update of updates) {
+                    const normalized = normalizeUpdate(update);
+                    if (!normalized)
+                        continue;
+                    markStatus({ lastInboundAt: Date.now() });
+                    const envelope = { message: normalized };
+                    try {
+                        await emit(envelope);
+                    }
+                    catch (err) {
+                        emitFailed = true;
+                        log.error("telegram emit threw — leaving cursor unchanged", {
+                            err: redactToken(String(err)),
+                        });
+                        break;
+                    }
+                }
+                if (!emitFailed) {
+                    offset = maxId + 1;
+                    state.update({ cursor: String(offset) });
+                }
+            }
+            catch (err) {
+                if (stopped || abortSignal.aborted)
+                    break;
+                const name = err?.name ?? "";
+                if (name === "AbortError" || name === "TimeoutError") {
+                    log.warn("telegram poll transient", { name });
+                    await sleep(TRANSIENT_BACKOFF_MS, abortSignal);
+                    continue;
+                }
+                log.error("telegram poll failed", { err: redactToken(String(err)) });
+                markStatus({ lastError: redactToken(String(err)) });
+                await sleep(POLL_BACKOFF_MS, abortSignal);
+            }
+        }
+        markStatus({
+            running: false,
+            connected: false,
+            lastStopAt: Date.now(),
+        });
+        try {
+            state.flush();
+        }
+        catch (e) {
+            log.warn("state-flush-on-stop failed", { error: String(e) });
+        }
+    }
+    const adapter = {
+        id: opts.id,
+        type: channelType,
+        async start(ctx) {
+            if (started)
+                throw new Error("already started");
+            started = true;
+            await pollLoop(ctx);
+        },
+        async stop(_ctx) {
+            if (stopCallback) {
+                stopCallback();
+                stopCallback = null;
+            }
+            try {
+                stateStore?.flush();
+            }
+            catch (e) {
+                // W7: log flush failures at stop — previously swallowed silently.
+                console.warn("[telegram] state-flush-on-stop failed", String(e));
+            }
+        },
+        async send(ctx) {
+            const { message, log } = ctx;
+            if (!loadTokenFromSecretIfNeeded()) {
+                throw new Error("telegram bot token not loaded");
+            }
+            const chatId = chatIdFromConversation(message.conversationId);
+            if (!chatId) {
+                throw new Error(`telegram send: unrecognized conversationId "${message.conversationId}"`);
+            }
+            const chunks = splitText(message.text, splitAt);
+            let lastMessageId = null;
+            for (const chunk of chunks) {
+                const resp = await callApi("sendMessage", {
+                    chat_id: chatId,
+                    text: chunk,
+                    disable_web_page_preview: true,
+                }, 15_000);
+                if (!resp.ok) {
+                    log.warn("telegram sendMessage non-ok", {
+                        description: redactToken(resp.description ?? ""),
+                    });
+                    throw new Error(`telegram sendMessage failed: ${redactToken(resp.description ?? "unknown")}`);
+                }
+                if (resp.result?.message_id !== undefined) {
+                    lastMessageId = `telegram:${chatId}:${resp.result.message_id}`;
+                }
+            }
+            const sendAt = Date.now();
+            statusSnapshot = { ...statusSnapshot, lastSendAt: sendAt };
+            // W11: push to the gateway snapshot too — the dashboard reads this.
+            if (liveSetStatus)
+                liveSetStatus({ lastSendAt: sendAt });
+            return { providerMessageId: lastMessageId };
+        },
+        async typing(ctx) {
+            if (!loadTokenFromSecretIfNeeded())
+                return;
+            const chatId = chatIdFromConversation(ctx.conversationId);
+            if (!chatId)
+                return;
+            try {
+                await callApi("sendChatAction", { chat_id: chatId, action: "typing" }, 10_000);
+            }
+            catch (err) {
+                ctx.log.warn("telegram typing failed", { err: redactToken(String(err)) });
+            }
+        },
+        status() {
+            return { ...statusSnapshot };
+        },
+    };
+    return adapter;
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}

package/dist/gateway/channels/text-split.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Split a long message into chunks <= `limit` characters each. Prefers to cut
+ * on newline boundaries so multi-paragraph replies don't fragment mid-line.
+ *
+ * Shared by third-party channel adapters (Telegram, WeChat) which both have a
+ * per-message size cap from upstream and no native streaming. WeChat caller
+ * passes a smaller `limit` (~1800), Telegram a larger one (~4000, since the
+ * raw Telegram limit is 4096).
+ *
+ * Empty input returns `[""]` so callers can iterate uniformly without a length
+ * check.
+ */
+export declare function splitText(text: string, limit: number): string[];

package/dist/gateway/channels/text-split.js

@@ -0,0 +1,33 @@
+/**
+ * Split a long message into chunks <= `limit` characters each. Prefers to cut
+ * on newline boundaries so multi-paragraph replies don't fragment mid-line.
+ *
+ * Shared by third-party channel adapters (Telegram, WeChat) which both have a
+ * per-message size cap from upstream and no native streaming. WeChat caller
+ * passes a smaller `limit` (~1800), Telegram a larger one (~4000, since the
+ * raw Telegram limit is 4096).
+ *
+ * Empty input returns `[""]` so callers can iterate uniformly without a length
+ * check.
+ */
+export function splitText(text, limit) {
+    if (limit <= 0)
+        return [text];
+    if (text.length === 0)
+        return [""];
+    if (text.length <= limit)
+        return [text];
+    const out = [];
+    let remaining = text;
+    while (remaining.length > limit) {
+        let cut = remaining.lastIndexOf("\n", limit);
+        if (cut <= 0)
+            cut = limit;
+        out.push(remaining.slice(0, cut));
+        // Drop the leading newline so the next chunk doesn't start with a blank line.
+        remaining = remaining.slice(cut).replace(/^\n/, "");
+    }
+    if (remaining.length > 0)
+        out.push(remaining);
+    return out;
+}