charness 0.0.0-stage → 3.0.0

package/dist/utils/markdownTableRender.js

@@ -0,0 +1,298 @@
+"use strict";
+/**
+ * @description Pure pre-processing pass that turns raw GitHub-flavored
+ * markdown tables (`| a | b |` …) into a readable Telegram form.
+ *
+ * Why this exists: OpenCode replies often contain GFM tables as plain pipe
+ * text, which is unreadable on a phone. This module detects those blocks and
+ * rewrites each one to a HYBRID rendering chosen by width:
+ *  - narrow table (aligned form fits {@link tableMaxMonospaceWidth}) → a
+ *    column-aligned box-drawing frame WRAPPED in a ``` fence, so the shared
+ *    `renderAgentHtml` fence machinery turns it into a `<pre>` (monospace).
+ *  - wide table → per-row "field: value" blocks as plain markdown lines, which
+ *    flow through the normal bold/inline passes.
+ *
+ * It is wired as step 0.5 of `renderAgentHtml` (after the control-char strip,
+ * before the fence regex) and therefore runs on EVERY agent output for BOTH
+ * backends. Two safety invariants follow from that:
+ *  1. it is FENCE-AWARE — lines inside an existing ```-delimited region are
+ *     never scanned for tables (a code block full of pipes must survive);
+ *  2. it leaves all non-table text byte-for-byte identical.
+ *
+ * The detector is narrow on purpose (header pipe row + GFM separator row +
+ * ≥1 body rows), so ordinary prose containing a stray `|` never matches.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tableMaxMonospaceWidth = void 0;
+exports.detectTables = detectTables;
+exports.parseTable = parseTable;
+exports.renderAligned = renderAligned;
+exports.renderFieldValue = renderFieldValue;
+exports.renderTable = renderTable;
+exports.renderMarkdownTables = renderMarkdownTables;
+/**
+ * Width budget (in monospace code points) for the aligned form. If the widest
+ * line of the box-drawing render exceeds this, the renderer falls back to the
+ * "field: value" form instead. Chosen so an aligned table still fits a typical
+ * phone without horizontal scroll. Tunable — the main agent confirms/adjusts
+ * the exact value via live verification.
+ */
+exports.tableMaxMonospaceWidth = 42;
+// Box-drawing glyphs for the aligned frame.
+const boxTopLeft = '┌';
+const boxTopMid = '┬';
+const boxTopRight = '┐';
+const boxMidLeft = '├';
+const boxMidMid = '┼';
+const boxMidRight = '┤';
+const boxBottomLeft = '└';
+const boxBottomMid = '┴';
+const boxBottomRight = '┘';
+const boxVertical = '│';
+const boxHorizontal = '─';
+/** Field-value form: the marker that precedes each row's key cell. */
+const fieldValueRowMarker = '▸';
+/**
+ * A GFM separator row: each column is dashes with optional leading/trailing
+ * colons for alignment, cells split by `|`, outer pipes optional. At least one
+ * dash per column. Examples: `|---|---|`, `:--:|:-:`, `| --- | :---: |`.
+ */
+const separatorRowRegex = /^\s*\|?\s*:?-+:?\s*(\|\s*:?-+:?\s*)*\|?\s*$/;
+/** A line that looks like a table row: contains at least one `|`. The narrow
+ *  detector below additionally requires a valid separator row to follow the
+ *  header, so this loose check alone never triggers on prose. */
+function checkIsPipeRow(line) {
+    return line.includes('|');
+}
+/**
+ * Split one table row on UNESCAPED `|`, trim each cell, and drop the empty
+ * edge cells produced by outer pipes (`| a | b |` → `['a', 'b']`). Escaped
+ * `\|` is preserved as a literal pipe inside a cell.
+ */
+function parseRowCells(line) {
+    const cells = [];
+    let current = '';
+    let index = 0;
+    while (index < line.length) {
+        const char = line[index];
+        if (char === '\\' && line[index + 1] === '|') {
+            current += '|';
+            index += 2;
+            continue;
+        }
+        if (char === '|') {
+            cells.push(current);
+            current = '';
+            index += 1;
+            continue;
+        }
+        current += char;
+        index += 1;
+    }
+    cells.push(current);
+    const trimmed = cells.map((cell) => cell.trim());
+    // Drop a single empty cell at each edge — the artifact of outer pipes. Only
+    // ONE per side: an intentionally-empty interior cell stays.
+    if (trimmed.length > 0 && trimmed[0] === '')
+        trimmed.shift();
+    if (trimmed.length > 0 && trimmed[trimmed.length - 1] === '')
+        trimmed.pop();
+    return trimmed;
+}
+/**
+ * Find every GFM table block in `text`, returning their line ranges. A block
+ * is a header pipe row, a separator row directly below it, then ≥1 consecutive
+ * pipe body rows. Lines inside an existing ```-fenced region are skipped, so a
+ * code block containing pipes never matches.
+ */
+function detectTables(text) {
+    const lines = text.split('\n');
+    const ranges = [];
+    let isInsideFence = false;
+    let lineIndex = 0;
+    while (lineIndex < lines.length) {
+        const line = lines[lineIndex];
+        // Track ``` fence open/close state line by line — never scan inside one.
+        if (/^\s*```/.test(line)) {
+            isInsideFence = !isInsideFence;
+            lineIndex += 1;
+            continue;
+        }
+        if (isInsideFence) {
+            lineIndex += 1;
+            continue;
+        }
+        const separatorIndex = lineIndex + 1;
+        const headerCells = parseRowCells(line);
+        const isTableStart = checkIsPipeRow(line) &&
+            separatorIndex < lines.length &&
+            separatorRowRegex.test(lines[separatorIndex]) &&
+            // A bare separator with no header text isn't a table.
+            headerCells.length > 0 &&
+            // GFM requires the delimiter row to match the header's column count. This
+            // also rejects a `---` thematic break sitting under a pipe-bearing prose
+            // line (which `separatorRowRegex` alone would accept) — a false positive
+            // that matters because this runs on EVERY agent output.
+            parseRowCells(lines[separatorIndex]).length === headerCells.length;
+        if (!isTableStart) {
+            lineIndex += 1;
+            continue;
+        }
+        // Consume consecutive body rows after the separator.
+        let bodyIndex = separatorIndex + 1;
+        while (bodyIndex < lines.length && !/^\s*```/.test(lines[bodyIndex]) && checkIsPipeRow(lines[bodyIndex])) {
+            bodyIndex += 1;
+        }
+        // Require ≥1 body row — a header+separator with no rows isn't worth a frame.
+        if (bodyIndex > separatorIndex + 1) {
+            ranges.push({ startLine: lineIndex, endLineExclusive: bodyIndex });
+            lineIndex = bodyIndex;
+            continue;
+        }
+        lineIndex += 1;
+    }
+    return ranges;
+}
+/**
+ * Parse a table block (the raw lines of one detected range, joined by `\n`)
+ * into headers + rows. Ragged rows shorter than the header are padded with
+ * `''`; rows longer than the header keep their extra cells (so nothing is
+ * silently lost — the aligned form widens to fit).
+ */
+function parseTable(block) {
+    const lines = block.split('\n').filter((line) => line.trim().length > 0);
+    const headers = parseRowCells(lines[0]);
+    // lines[1] is the separator row — skip it.
+    const bodyLines = lines.slice(2);
+    const rows = bodyLines.map((line) => {
+        const cells = parseRowCells(line);
+        while (cells.length < headers.length)
+            cells.push('');
+        return cells;
+    });
+    return { headers, rows };
+}
+/**
+ * Strip the inline-markdown markers (`**`, `*`, `` ` ``) that are invisible in
+ * the final render, so column width is measured on the VISIBLE text. Used for
+ * width math only — the rendered cell keeps its markers.
+ */
+function getVisibleCellText(cell) {
+    return cell.replace(/\*\*/g, '').replace(/\*/g, '').replace(/`/g, '');
+}
+/** Display width of a cell in CODE POINTS (not UTF-16 units), counted on the
+ *  visible text so Cyrillic / emoji columns align. */
+function getCellDisplayWidth(cell) {
+    return [...getVisibleCellText(cell)].length;
+}
+/** Right-pad `cell` with spaces to `width` code points (visible width). */
+function padCellToWidth(cell, width) {
+    const padding = width - getCellDisplayWidth(cell);
+    return padding > 0 ? cell + ' '.repeat(padding) : cell;
+}
+/** Per-column max display width across header + all rows. */
+function getColumnWidths(table) {
+    const columnCount = table.rows.reduce((max, row) => Math.max(max, row.length), table.headers.length);
+    const widths = [];
+    for (let column = 0; column < columnCount; column += 1) {
+        const headerWidth = column < table.headers.length ? getCellDisplayWidth(table.headers[column]) : 0;
+        const bodyWidth = table.rows.reduce((max, row) => Math.max(max, column < row.length ? getCellDisplayWidth(row[column]) : 0), 0);
+        widths.push(Math.max(headerWidth, bodyWidth));
+    }
+    return widths;
+}
+/** Build one bordered content line: `│ cell │ cell │` padded to column widths. */
+function buildAlignedRow(cells, widths) {
+    const padded = widths.map((width, column) => padCellToWidth(cells[column] ?? '', width));
+    return `${boxVertical} ${padded.join(` ${boxVertical} `)} ${boxVertical}`;
+}
+/** Build one frame line (top / middle / bottom) from the three corner glyphs. */
+function buildFrameLine(left, mid, right, widths) {
+    const segments = widths.map((width) => boxHorizontal.repeat(width + 2));
+    return `${left}${segments.join(mid)}${right}`;
+}
+/**
+ * Render the table as a monospace, column-aligned box-drawing frame. The
+ * caller wraps the result in a ``` fence so the HTML layer makes it a `<pre>`.
+ */
+function renderAligned(table) {
+    const widths = getColumnWidths(table);
+    const out = [];
+    out.push(buildFrameLine(boxTopLeft, boxTopMid, boxTopRight, widths));
+    out.push(buildAlignedRow(table.headers, widths));
+    out.push(buildFrameLine(boxMidLeft, boxMidMid, boxMidRight, widths));
+    for (const row of table.rows)
+        out.push(buildAlignedRow(row, widths));
+    out.push(buildFrameLine(boxBottomLeft, boxBottomMid, boxBottomRight, widths));
+    return out.join('\n');
+}
+/**
+ * Render the table as per-row "field: value" blocks for the wide case. The
+ * first column is the key cell (after `▸`); remaining columns become
+ * `  <header>: <cell>` lines. Inline markdown in cell text is kept — the HTML
+ * layer renders it. When there is only one column (no obvious key/value split)
+ * the rows are numbered instead.
+ */
+function renderFieldValue(table) {
+    const hasKeyColumn = table.headers.length >= 2;
+    const blocks = table.rows.map((row, rowIndex) => {
+        const lines = [];
+        if (hasKeyColumn) {
+            lines.push(`${fieldValueRowMarker} ${row[0] ?? ''}`);
+            for (let column = 1; column < table.headers.length; column += 1) {
+                lines.push(`  ${table.headers[column]}: ${row[column] ?? ''}`);
+            }
+        }
+        else {
+            // No key column to anchor on — number the rows so they stay distinct.
+            lines.push(`${fieldValueRowMarker} ${rowIndex + 1}. ${row[0] ?? ''}`);
+        }
+        return lines.join('\n');
+    });
+    return blocks.join('\n');
+}
+/** Widest line (in code points) of an aligned render — the width-budget input. */
+function getAlignedWidestLineWidth(aligned) {
+    return aligned.split('\n').reduce((max, line) => Math.max(max, [...line].length), 0);
+}
+/**
+ * Pick the rendering for one table: aligned (fenced) if its widest line fits
+ * {@link tableMaxMonospaceWidth}, else the field-value form. Returns the text
+ * already wrapped for the HTML layer (``` fence for aligned, plain lines for
+ * field-value).
+ */
+function renderTable(table) {
+    const aligned = renderAligned(table);
+    if (getAlignedWidestLineWidth(aligned) <= exports.tableMaxMonospaceWidth) {
+        return `\`\`\`\n${aligned}\n\`\`\``;
+    }
+    return renderFieldValue(table);
+}
+/**
+ * Replace every detected GFM table block in `text` with its chosen rendering,
+ * in place. Non-table text and fenced regions are returned byte-for-byte
+ * unchanged. This is the single entry point wired into `renderAgentHtml`.
+ */
+function renderMarkdownTables(text) {
+    const ranges = detectTables(text);
+    if (ranges.length === 0)
+        return text;
+    const lines = text.split('\n');
+    const out = [];
+    let lineIndex = 0;
+    let rangeIndex = 0;
+    while (lineIndex < lines.length) {
+        const range = ranges[rangeIndex];
+        if (range && lineIndex === range.startLine) {
+            const block = lines.slice(range.startLine, range.endLineExclusive).join('\n');
+            out.push(renderTable(parseTable(block)));
+            lineIndex = range.endLineExclusive;
+            rangeIndex += 1;
+            continue;
+        }
+        out.push(lines[lineIndex]);
+        lineIndex += 1;
+    }
+    return out.join('\n');
+}
+//# sourceMappingURL=markdownTableRender.js.map

package/dist/utils/markdownTableRender.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdownTableRender.js","sourceRoot":"","sources":["../../src/utils/markdownTableRender.ts"],"names":[],"mappings":"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"}

package/dist/utils/mediaGroupCollector.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @description Debounced batching of Telegram media-album items.
+ *
+ * A media album (multiple photos/files sent as one visual message) arrives over
+ * the Bot API as N SEPARATE messages that share a `media_group_id`, delivered in
+ * a quick burst. Forwarding each as its own agent prompt makes them abort one
+ * another's generation, and any per-item gating hint ("no agent running") fires
+ * N times. This collector coalesces a group: each {@link MediaGroupCollector.collect}
+ * call appends the item and resets a per-group debounce timer; once the burst
+ * settles (no new item for `debounceMs`) the `onFlush` callback fires ONCE with
+ * the group's items in arrival order.
+ *
+ * It also owns the per-group HINT DEDUPE ({@link MediaGroupCollector.checkShouldAnnounceOnce}):
+ * a small set keyed by the same group key so a gating reply (no agent / unbound)
+ * or a download-error reply is emitted only once per album. Entries are dropped
+ * when the group flushes or times out, so the structure can't leak; an explicit
+ * cap bounds it even against a pathological flood of distinct group keys.
+ *
+ * Side-effect-free apart from timers — `debounceMs` is a constructor param so
+ * tests drive it with real short timers (e.g. 50ms) instead of mocking the clock.
+ */
+export interface MediaGroupCollector<TItem> {
+    /**
+     * Append an item to its group and (re)arm the group's debounce timer. The
+     * group flushes `debounceMs` after the LAST collected item.
+     */
+    collect(groupKey: string, item: TItem): void;
+    /**
+     * One-shot guard for per-group side effects (gating hints, dedup'd error
+     * replies). Returns `true` the FIRST time it is called for a still-open group
+     * key and `false` for every subsequent call until that group flushes. A group
+     * key with no live entry is created on demand so a hint can be claimed before
+     * (or without) any item is collected.
+     */
+    checkShouldAnnounceOnce(groupKey: string): boolean;
+    /** Number of groups currently buffered — for tests / diagnostics. */
+    readonly size: number;
+}
+export interface MediaGroupCollectorOptions<TItem> {
+    /** Quiet period after the last item before a group flushes. */
+    debounceMs: number;
+    /** Invoked once per settled group with its items in arrival order. */
+    onFlush: (groupKey: string, items: TItem[]) => void;
+}
+/**
+ * @description Create a {@link MediaGroupCollector}. The returned object holds
+ * per-group timers internally; there is no global timer, so an idle collector
+ * costs nothing.
+ */
+export declare function createMediaGroupCollector<TItem>(options: MediaGroupCollectorOptions<TItem>): MediaGroupCollector<TItem>;
+//# sourceMappingURL=mediaGroupCollector.d.ts.map

package/dist/utils/mediaGroupCollector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mediaGroupCollector.d.ts","sourceRoot":"","sources":["../../src/utils/mediaGroupCollector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAiBH,MAAM,WAAW,mBAAmB,CAAC,KAAK;IACxC;;;OAGG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI,CAAC;IAC7C;;;;;;OAMG;IACH,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACnD,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,0BAA0B,CAAC,KAAK;IAC/C,+DAA+D;IAC/D,UAAU,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,IAAI,CAAC;CACrD;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAC7C,OAAO,EAAE,0BAA0B,CAAC,KAAK,CAAC,GACzC,mBAAmB,CAAC,KAAK,CAAC,CAmD5B"}

package/dist/utils/mediaGroupCollector.js

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * @description Debounced batching of Telegram media-album items.
+ *
+ * A media album (multiple photos/files sent as one visual message) arrives over
+ * the Bot API as N SEPARATE messages that share a `media_group_id`, delivered in
+ * a quick burst. Forwarding each as its own agent prompt makes them abort one
+ * another's generation, and any per-item gating hint ("no agent running") fires
+ * N times. This collector coalesces a group: each {@link MediaGroupCollector.collect}
+ * call appends the item and resets a per-group debounce timer; once the burst
+ * settles (no new item for `debounceMs`) the `onFlush` callback fires ONCE with
+ * the group's items in arrival order.
+ *
+ * It also owns the per-group HINT DEDUPE ({@link MediaGroupCollector.checkShouldAnnounceOnce}):
+ * a small set keyed by the same group key so a gating reply (no agent / unbound)
+ * or a download-error reply is emitted only once per album. Entries are dropped
+ * when the group flushes or times out, so the structure can't leak; an explicit
+ * cap bounds it even against a pathological flood of distinct group keys.
+ *
+ * Side-effect-free apart from timers — `debounceMs` is a constructor param so
+ * tests drive it with real short timers (e.g. 50ms) instead of mocking the clock.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMediaGroupCollector = createMediaGroupCollector;
+/**
+ * Hard ceiling on concurrently-tracked groups. Telegram albums settle within a
+ * couple of seconds, so live groups are normally 0–1; this only guards against a
+ * degenerate flood of distinct keys never flushing. When exceeded, the oldest
+ * group is force-flushed to reclaim its slot rather than dropped silently.
+ */
+const maxConcurrentGroups = 256;
+/**
+ * @description Create a {@link MediaGroupCollector}. The returned object holds
+ * per-group timers internally; there is no global timer, so an idle collector
+ * costs nothing.
+ */
+function createMediaGroupCollector(options) {
+    const { debounceMs, onFlush } = options;
+    const groups = new Map();
+    function flush(groupKey) {
+        const group = groups.get(groupKey);
+        if (!group)
+            return;
+        clearTimeout(group.timer);
+        groups.delete(groupKey);
+        // Flush even an item-less group (it may exist only to hold a claimed hint);
+        // an empty array is a harmless no-op for the typical onFlush.
+        onFlush(groupKey, group.items);
+    }
+    function armTimer(groupKey) {
+        const timer = setTimeout(() => flush(groupKey), debounceMs);
+        // Don't let a pending album timer keep the process alive on shutdown.
+        if (typeof timer.unref === 'function')
+            timer.unref();
+        return timer;
+    }
+    function ensureGroup(groupKey) {
+        const existing = groups.get(groupKey);
+        if (existing)
+            return existing;
+        if (groups.size >= maxConcurrentGroups) {
+            // Reclaim a slot by flushing the oldest (insertion-ordered) group.
+            const oldestKey = groups.keys().next().value;
+            if (oldestKey !== undefined)
+                flush(oldestKey);
+        }
+        const created = { items: [], timer: armTimer(groupKey), isAnnounced: false };
+        groups.set(groupKey, created);
+        return created;
+    }
+    return {
+        collect(groupKey, item) {
+            const group = ensureGroup(groupKey);
+            group.items.push(item);
+            clearTimeout(group.timer);
+            group.timer = armTimer(groupKey);
+        },
+        checkShouldAnnounceOnce(groupKey) {
+            const group = ensureGroup(groupKey);
+            if (group.isAnnounced)
+                return false;
+            group.isAnnounced = true;
+            return true;
+        },
+        get size() {
+            return groups.size;
+        },
+    };
+}
+//# sourceMappingURL=mediaGroupCollector.js.map

package/dist/utils/mediaGroupCollector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mediaGroupCollector.js","sourceRoot":"","sources":["../../src/utils/mediaGroupCollector.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;AA+CH,8DAqDC;AAlGD;;;;;GAKG;AACH,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAkChC;;;;GAIG;AACH,SAAgB,yBAAyB,CACvC,OAA0C;IAE1C,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IACxC,MAAM,MAAM,GAAG,IAAI,GAAG,EAA6B,CAAC;IAEpD,SAAS,KAAK,CAAC,QAAgB;QAC7B,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACnC,IAAI,CAAC,KAAK;YAAE,OAAO;QACnB,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC1B,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACxB,4EAA4E;QAC5E,8DAA8D;QAC9D,OAAO,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;IAED,SAAS,QAAQ,CAAC,QAAgB;QAChC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,UAAU,CAAC,CAAC;QAC5D,sEAAsE;QACtE,IAAI,OAAO,KAAK,CAAC,KAAK,KAAK,UAAU;YAAE,KAAK,CAAC,KAAK,EAAE,CAAC;QACrD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,SAAS,WAAW,CAAC,QAAgB;QACnC,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACtC,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAC9B,IAAI,MAAM,CAAC,IAAI,IAAI,mBAAmB,EAAE,CAAC;YACvC,mEAAmE;YACnE,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;YAC7C,IAAI,SAAS,KAAK,SAAS;gBAAE,KAAK,CAAC,SAAS,CAAC,CAAC;QAChD,CAAC;QACD,MAAM,OAAO,GAAsB,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;QAChG,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC9B,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,OAAO;QACL,OAAO,CAAC,QAAQ,EAAE,IAAI;YACpB,MAAM,KAAK,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;YACpC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACvB,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC1B,KAAK,CAAC,KAAK,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACnC,CAAC;QACD,uBAAuB,CAAC,QAAQ;YAC9B,MAAM,KAAK,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;YACpC,IAAI,KAAK,CAAC,WAAW;gBAAE,OAAO,KAAK,CAAC;YACpC,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC;YACzB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,IAAI;YACN,OAAO,MAAM,CAAC,IAAI,CAAC;QACrB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/utils/messageSendService.d.ts

@@ -0,0 +1,136 @@
+import type { SendFilesToThread } from './fileSendService';
+/**
+ * @description Deliver a batch of DISCRETE messages into a topic. Unlike the
+ * normal agent-output path (which coalesces / glues a burst into the fewest
+ * messages), this sends each input item as its OWN Telegram message — the
+ * primitive behind the `send_messages_to_user` MCP tool, used when an agent
+ * wants several separate messages (e.g. a per-item news digest: one message per
+ * headline). A single input string that renders past Telegram's cap is split
+ * defensively, but two distinct inputs are NEVER merged.
+ *
+ * Each item may ALSO carry ONE attachment: an item with a `path` is delivered
+ * through the SAME secure file-send pipeline as `send_file_to_user` (its `text`
+ * becomes the media caption, trimmed to Telegram's 1024-char cap), reusing all
+ * of that pipeline's path-safety, media classification, and dispatch. An item
+ * without a `path` is a plain text message exactly as before.
+ *
+ * Kept dependency-free of `bot.ts` (which builds a Telegraf instance at module
+ * load): the caller injects the target resolver, the per-chunk sender, and the
+ * reusable file-send closure, so this service composes with the same paced send
+ * path the rest of the bot uses and stays unit-testable in isolation (mirrors
+ * `createSendFilesToThread`).
+ */
+/**
+ * @name DiscreteMessageItem
+ * @description One item of a `send_messages_to_user` batch. A plain string is a
+ * text-only message (backward-compatible). An object may carry a text body, an
+ * attachment `path` (relative to the bound folder), or both; `asFile` forces the
+ * document override on the attachment. At least one of `text`/`path` must be
+ * non-empty on an object item.
+ */
+export type DiscreteMessageItem = string | {
+    text?: string;
+    path?: string;
+    asFile?: boolean;
+};
+/**
+ * @name SendMessagesToThreadResult
+ * @description `undeliveredCount` on success counts the messages that were
+ * attempted but did not land (a partial delivery stays `ok`), so a caller can
+ * tell a partial delivery from a full one without parsing `summary`.
+ * `sentMessageIds` are the TEXT messages that landed, in order — what a caller
+ * pins or edits afterwards (an answer's pin, S8); attachments are not listed.
+ */
+export type SendMessagesToThreadResult = {
+    ok: true;
+    summary: string;
+    undeliveredCount: number;
+    sentMessageIds: number[];
+} | {
+    ok: false;
+    error: string;
+} | {
+    ok: false;
+    kind: 'deliveryUnknown';
+    error: string;
+};
+export type SendMessagesToThread = (threadKey: string, args: SendMessagesToThreadOptions) => Promise<SendMessagesToThreadResult>;
+export interface SendMessagesToThreadOptions {
+    /** The items to deliver, in order; each becomes its own Telegram message. */
+    messages: DiscreteMessageItem[];
+    /**
+     * Canonical directory granted by a directory-scoped MCP token. Threaded into
+     * every attachment send so the file pipeline re-checks the binding, exactly
+     * like `send_file_to_user`.
+     */
+    authorizedWorkDir?: string;
+    /**
+     * Optional cancellation — checked between items (best-effort, coarse) AND
+     * caught when an in-flight attachment send rejects with it, so either way the
+     * caller gets the structured "cancelled after delivering N" result.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Upper bound on how many discrete messages one call may deliver. A per-item
+ * news digest is ~30–40 messages; 50 leaves headroom while bounding a runaway
+ * call (each message is separately rate-paced, so a large batch also floods the
+ * topic with notifications).
+ */
+export declare const maxDiscreteMessages = 50;
+export interface SendMessagesToThreadDeps<TTarget> {
+    /** Map the scope-resolved thread key string to the concrete send target. */
+    resolveTarget(threadKey: string): {
+        ok: true;
+        target: TTarget;
+    } | {
+        ok: false;
+        error: string;
+    };
+    /**
+     * Send ONE already-split chunk as its own permanent message; resolves the sent
+     * message id, `null` when it did not land. The caller wires this to the bot's
+     * paced HTML-with-plain-fallback send so ordering / rate-limiting / `/clear`
+     * tracking are reused.
+     */
+    sendChunk(target: TTarget, chunk: string, signal?: AbortSignal): Promise<number | null>;
+    /**
+     * Deliver ONE attachment via the SAME reusable file-send pipeline behind
+     * `send_file_to_user` (path-safety, media classification, album/size rules,
+     * 1024-char caption trim all reused). The caller injects the exact
+     * `sendFilesToThread` closure it already built for the file tool.
+     */
+    sendFiles: SendFilesToThread;
+    /**
+     * The connector's own splitter — injected rather than imported so this
+     * service stays platform-neutral (the cap and the split rule are the
+     * surface's, not this service's).
+     */
+    splitMessage(text: string, maxLength: number, measureRendered: (chunk: string) => number): string[];
+    /** Max SOURCE length per message handed to {@link SendMessagesToThreadDeps.splitMessage} (defensive split). */
+    maxMessageLength: number;
+    /** Rendered-length measure so an over-cap RENDERED message is split like normal output. */
+    measureRendered(chunk: string): number;
+}
+/**
+ * @description Build the discrete-message sender. Each item is delivered as its
+ * OWN message, preserving order: a text item is split (defensively) into
+ * Telegram-sized chunks and each chunk sent separately; an attachment item goes
+ * through the injected file-send pipeline as a single path (text → caption).
+ * Cancellation is checked between items (coarse — a chunk already dispatched to
+ * the pacer still lands) and is ALSO caught when it is raised from inside an
+ * in-flight attachment send: `sendFiles` rejects on abort rather than returning,
+ * and letting that escape hid how many messages had already landed (the agent's
+ * natural retry then posted them twice).
+ *
+ * Items are validated up front (an all-empty object → error, nothing sent) so
+ * the service mirrors the MCP schema's all-or-nothing rejection. Failure is NOT
+ * swallowed: if every send failed the result is an ERROR (with any attachment
+ * errors named), so the agent knows nothing reached the topic instead of reading
+ * a false "Delivered 0" success; a partial failure stays `ok` but says how many
+ * landed. An attachment whose delivery outcome is unknown terminates the batch
+ * with a `deliveryUnknown` result so the agent does not blindly retry (mirrors
+ * `send_file_to_user`).
+ */
+export declare function createSendMessagesToThread<TTarget>(deps: SendMessagesToThreadDeps<TTarget>): SendMessagesToThread;
+//# sourceMappingURL=messageSendService.d.ts.map

package/dist/utils/messageSendService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messageSendService.d.ts","sourceRoot":"","sources":["../../src/utils/messageSendService.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAA2B,MAAM,mBAAmB,CAAC;AAEpF;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAC3B,MAAM,GACN;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,MAAM,0BAA0B,GAClC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,EAAE,CAAA;CAAE,GACjF;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC5B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,iBAAiB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D,MAAM,MAAM,oBAAoB,GAAG,CACjC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,2BAA2B,KAC9B,OAAO,CAAC,0BAA0B,CAAC,CAAC;AAEzC,MAAM,WAAW,2BAA2B;IAC1C,6EAA6E;IAC7E,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,MAAM,WAAW,wBAAwB,CAAC,OAAO;IAC/C,4EAA4E;IAC5E,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/F;;;;;OAKG;IACH,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACxF;;;;;OAKG;IACH,SAAS,EAAE,iBAAiB,CAAC;IAC7B;;;;OAIG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,MAAM,EAAE,CAAC;IACpG,+GAA+G;IAC/G,gBAAgB,EAAE,MAAM,CAAC;IACzB,2FAA2F;IAC3F,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;CACxC;AA8DD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAChD,IAAI,EAAE,wBAAwB,CAAC,OAAO,CAAC,GACtC,oBAAoB,CAwFtB"}