charness 0.0.0-stage → 3.0.0

package/dist/connectors/telegram/outputFlushPlan.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * @description Pure planning logic for flushing agent `output` to Telegram —
+ * extracted from `bot.ts` so the streaming-append decision is unit-testable
+ * without booting Telegraf.
+ *
+ * Live repro 2026-06-05: OpenCode emits a long reply
+ * as incremental tails, and the bot edited the SAME message with only the
+ * newest batch each flush — every edit replaced everything before it, so the
+ * user could read only the last tail. The fix: a continuation tail is
+ * appended to the text already rendered into the last message and the FULL
+ * combined text is re-rendered (also re-pairing markdown tokens that straddle
+ * two flushes), spilling into new messages when it outgrows the Telegram cap.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getOutputFlushPlan = getOutputFlushPlan;
+exports.getGroupDeltaContinuation = getGroupDeltaContinuation;
+exports.appendPendingOutput = appendPendingOutput;
+exports.getUnsentRemainder = getUnsentRemainder;
+const messageSplit_1 = require("./messageSplit");
+const renderAgentHtml_1 = require("./renderAgentHtml");
+/** Inject the real render into the splitter so chunks are sized by their
+ *  rendered HTML length (escaping + tags inflate the source past Telegram's
+ *  cap), keeping `messageSplit.ts` dependency-free. */
+const measureRenderedLength = (chunk) => (0, renderAgentHtml_1.renderAgentHtml)(chunk).length;
+/**
+ * @description Decide how a flush lands in Telegram. Append-edit is possible
+ * only when the batch is a continuation AND the last message is still
+ * editable (id + source text known, no forced break since).
+ */
+function getOutputFlushPlan(input) {
+    const canAppend = input.isContinuation &&
+        !input.needsNewMessage &&
+        input.lastMessageId !== null &&
+        input.lastMessageText !== null;
+    if (!canAppend) {
+        return {
+            chunks: (0, messageSplit_1.splitMessage)(input.output, undefined, measureRenderedLength),
+            shouldEditFirstChunk: false,
+        };
+    }
+    return {
+        chunks: (0, messageSplit_1.splitMessage)(input.lastMessageText + input.output, undefined, measureRenderedLength),
+        shouldEditFirstChunk: true,
+    };
+}
+/**
+ * @description The effective continuation flag the GROUP output path should use
+ * for an incoming `output`, accounting for adapters that stream WITHOUT marking
+ * continuations (the Claude scrape adapter).
+ *
+ * OpenCode marks every tail except a response's first with `meta.isContinuation`,
+ * so the group edit-in-place path already knows which outputs extend the last
+ * message; for it (`outputsDeltas === false`) the meta flag passes through
+ * unchanged. The Claude scrape adapter emits each poll's prose delta with NO
+ * meta even though every delta CONTINUES the same block — treating those as
+ * non-continuations made `getOutputFlushPlan` start a new message per poll flush
+ * (the one-message-per-scrape flood, and every re-flowed table width its own
+ * message).
+ *
+ * For a delta-emitting adapter a poll delta is therefore a CONTINUATION (it
+ * edits the growing message in place) UNLESS the pane had a real block boundary
+ * before it — a blank-line paragraph break or a distinct block (a settled
+ * table), both surfaced out-of-band as `startsNewParagraph`. At such a boundary
+ * the delta starts a NEW message (the locked boundary rule: a new message begins
+ * only at a paragraph/section, a distinct block, or a fresh turn — the last via
+ * `needsNewMessage`, which `getOutputFlushPlan` already honours). Unlike the DM
+ * cursor (one accumulating draft → everything is a continuation,
+ * {@link getDmDraftContinuation}), group renders discrete messages, so a
+ * paragraph/block boundary must break the message, not glue onto it.
+ */
+function getGroupDeltaContinuation(metaIsContinuation, outputsDeltas, startsNewParagraph) {
+    if (!outputsDeltas)
+        return metaIsContinuation;
+    return !startsNewParagraph;
+}
+/**
+ * @description Coalesce a new output batch into the pending (not yet flushed)
+ * buffer. Continuation tails concatenate as-is — they may be cut mid-word, a
+ * `\n` would split the word across lines. DISTINCT standalone outputs join with
+ * a single `\n` by default, UPGRADED to a BLANK LINE (`\n\n`) only when
+ * `startsNewParagraph` is set — the Claude scrape adapter reports out-of-band
+ * (`OutboundHints.startsNewParagraph`) when the pane had a real paragraph
+ * break before the chunk, so multi-paragraph answers keep their structure while
+ * a single wrapped paragraph spanning two polls is NOT split by a blank.
+ */
+function appendPendingOutput(pending, output, isContinuation, startsNewParagraph = false) {
+    if (!pending)
+        return output;
+    if (isContinuation)
+        return pending + output;
+    return startsNewParagraph ? `${pending}\n\n${output}` : `${pending}\n${output}`;
+}
+/** Separator used to re-join un-sent chunks before re-enqueueing them (S2). The
+ *  planner re-splits the rejoined text next flush, so a blank line keeps the
+ *  chunk boundary readable without gluing two messages together. */
+const unsentRemainderSeparator = '\n\n';
+/**
+ * @description Compute the text that must be RE-ENQUEUED after a flush where one
+ * or more chunks failed to send (live incident 2026-06-11, plan
+ * `2026-06-11-claude-wide-table-content-loss` S2: `replyChunkWithFallback`
+ * returns `null` when a chunk is dropped on a 429 after the rate-limit queue
+ * gives up; the buffer was already cleared, so the chunk was permanently lost).
+ *
+ * `sentCount` is the number of chunks that landed, counting from the FRONT of
+ * `chunks` (sends are in order, so a failure stops the run and everything from
+ * the first failure onward is un-sent). Returns the rejoined un-sent remainder,
+ * or `null` when everything landed. Idempotent: re-flushing the remainder never
+ * re-sends a landed chunk because those are excluded here. Pure + exported for
+ * unit tests.
+ */
+function getUnsentRemainder(chunks, sentCount) {
+    if (sentCount >= chunks.length)
+        return null;
+    const remainder = chunks.slice(sentCount);
+    if (remainder.length === 0)
+        return null;
+    return remainder.join(unsentRemainderSeparator);
+}
+//# sourceMappingURL=outputFlushPlan.js.map

package/dist/connectors/telegram/outputFlushPlan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outputFlushPlan.js","sourceRoot":"","sources":["../../../src/connectors/telegram/outputFlushPlan.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;AAsCH,gDAgBC;AA2BD,8DAOC;AAYD,kDASC;AAqBD,gDAKC;AArID,iDAA8C;AAC9C,uDAAoD;AAEpD;;uDAEuD;AACvD,MAAM,qBAAqB,GAAG,CAAC,KAAa,EAAU,EAAE,CAAC,IAAA,iCAAe,EAAC,KAAK,CAAC,CAAC,MAAM,CAAC;AAyBvF;;;;GAIG;AACH,SAAgB,kBAAkB,CAAC,KAAuB;IACxD,MAAM,SAAS,GACb,KAAK,CAAC,cAAc;QACpB,CAAC,KAAK,CAAC,eAAe;QACtB,KAAK,CAAC,aAAa,KAAK,IAAI;QAC5B,KAAK,CAAC,eAAe,KAAK,IAAI,CAAC;IACjC,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO;YACL,MAAM,EAAE,IAAA,2BAAY,EAAC,KAAK,CAAC,MAAM,EAAE,SAAS,EAAE,qBAAqB,CAAC;YACpE,oBAAoB,EAAE,KAAK;SAC5B,CAAC;IACJ,CAAC;IACD,OAAO;QACL,MAAM,EAAE,IAAA,2BAAY,EAAC,KAAK,CAAC,eAAe,GAAG,KAAK,CAAC,MAAM,EAAE,SAAS,EAAE,qBAAqB,CAAC;QAC5F,oBAAoB,EAAE,IAAI;KAC3B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,SAAgB,yBAAyB,CACvC,kBAA2B,EAC3B,aAAsB,EACtB,kBAA2B;IAE3B,IAAI,CAAC,aAAa;QAAE,OAAO,kBAAkB,CAAC;IAC9C,OAAO,CAAC,kBAAkB,CAAC;AAC7B,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,mBAAmB,CACjC,OAAsB,EACtB,MAAc,EACd,cAAuB,EACvB,kBAAkB,GAAG,KAAK;IAE1B,IAAI,CAAC,OAAO;QAAE,OAAO,MAAM,CAAC;IAC5B,IAAI,cAAc;QAAE,OAAO,OAAO,GAAG,MAAM,CAAC;IAC5C,OAAO,kBAAkB,CAAC,CAAC,CAAC,GAAG,OAAO,OAAO,MAAM,EAAE,CAAC,CAAC,CAAC,GAAG,OAAO,KAAK,MAAM,EAAE,CAAC;AAClF,CAAC;AAED;;oEAEoE;AACpE,MAAM,wBAAwB,GAAG,MAAM,CAAC;AAExC;;;;;;;;;;;;;GAaG;AACH,SAAgB,kBAAkB,CAAC,MAAgB,EAAE,SAAiB;IACpE,IAAI,SAAS,IAAI,MAAM,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAC5C,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAC1C,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACxC,OAAO,SAAS,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC;AAClD,CAAC"}

package/dist/connectors/telegram/questionKeyboards.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The inline keyboard of a pending question's options and the `extra` object a send carries it in.
+ */
+import type { InlineKeyboardMarkup } from 'telegraf/typings/core/types/typegram';
+import type { OpenCodeQuestion } from '../../types';
+/**
+ * @description Build the tappable keyboard for an OpenCode question's options.
+ *
+ * The bot offers a question's options twice with different callback wiring —
+ * the live answer buttons (`qa_<qIdx>_<optIdx>`) and the idle-compaction re-ask
+ * buttons (`reask_<optIdx>`) — so `buildCallbackId` is the only thing that
+ * varies. Labels are passed through untouched: the button width cap and its
+ * elision are Telegram's, and belong to the connector's
+ * {@link buildOptionsKeyboard}, not here.
+ *
+ * `buildCallbackId` must produce an id the matching `bot.action` regex accepts.
+ * The index it receives is the 0-based position in `question.options`; the body
+ * shows that option as `index + 1`.
+ */
+export declare function buildQuestionOptionsKeyboard(question: OpenCodeQuestion, buildCallbackId: (optionIndex: number) => string): InlineKeyboardMarkup | undefined;
+/**
+ * @description Attach an optional inline keyboard to a {@link replyToThread}
+ * `extra`.
+ *
+ * One place owns the `reply_markup` spelling, because getting it wrong fails
+ * SILENTLY: the message still sends, just with no buttons, and Telegram reports
+ * nothing. `base` carries whatever else the send needs (a `parse_mode`).
+ */
+export declare function buildKeyboardExtra(keyboard: InlineKeyboardMarkup | undefined, base?: Record<string, unknown>): Record<string, unknown>;
+//# sourceMappingURL=questionKeyboards.d.ts.map

package/dist/connectors/telegram/questionKeyboards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"questionKeyboards.d.ts","sourceRoot":"","sources":["../../../src/connectors/telegram/questionKeyboards.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AACjF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGpD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,gBAAgB,EAC1B,eAAe,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,MAAM,GAC/C,oBAAoB,GAAG,SAAS,CAOlC;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,oBAAoB,GAAG,SAAS,EAC1C,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACjC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzB"}

package/dist/connectors/telegram/questionKeyboards.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildQuestionOptionsKeyboard = buildQuestionOptionsKeyboard;
+exports.buildKeyboardExtra = buildKeyboardExtra;
+const outbound_1 = require("./outbound");
+/**
+ * @description Build the tappable keyboard for an OpenCode question's options.
+ *
+ * The bot offers a question's options twice with different callback wiring —
+ * the live answer buttons (`qa_<qIdx>_<optIdx>`) and the idle-compaction re-ask
+ * buttons (`reask_<optIdx>`) — so `buildCallbackId` is the only thing that
+ * varies. Labels are passed through untouched: the button width cap and its
+ * elision are Telegram's, and belong to the connector's
+ * {@link buildOptionsKeyboard}, not here.
+ *
+ * `buildCallbackId` must produce an id the matching `bot.action` regex accepts.
+ * The index it receives is the 0-based position in `question.options`; the body
+ * shows that option as `index + 1`.
+ */
+function buildQuestionOptionsKeyboard(question, buildCallbackId) {
+    return (0, outbound_1.buildOptionsKeyboard)(question.options.map((option, optionIndex) => ({
+        id: buildCallbackId(optionIndex),
+        label: option.label,
+    })));
+}
+/**
+ * @description Attach an optional inline keyboard to a {@link replyToThread}
+ * `extra`.
+ *
+ * One place owns the `reply_markup` spelling, because getting it wrong fails
+ * SILENTLY: the message still sends, just with no buttons, and Telegram reports
+ * nothing. `base` carries whatever else the send needs (a `parse_mode`).
+ */
+function buildKeyboardExtra(keyboard, base = {}) {
+    return keyboard ? { ...base, reply_markup: keyboard } : { ...base };
+}
+//# sourceMappingURL=questionKeyboards.js.map

package/dist/connectors/telegram/questionKeyboards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"questionKeyboards.js","sourceRoot":"","sources":["../../../src/connectors/telegram/questionKeyboards.ts"],"names":[],"mappings":";;AAqBA,oEAUC;AAUD,gDAKC;AAzCD,yCAAkD;AAElD;;;;;;;;;;;;;GAaG;AACH,SAAgB,4BAA4B,CAC1C,QAA0B,EAC1B,eAAgD;IAEhD,OAAO,IAAA,+BAAoB,EACzB,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,CAAC,CAAC;QAC7C,EAAE,EAAE,eAAe,CAAC,WAAW,CAAC;QAChC,KAAK,EAAE,MAAM,CAAC,KAAK;KACpB,CAAC,CAAC,CACJ,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,kBAAkB,CAChC,QAA0C,EAC1C,OAAgC,EAAE;IAElC,OAAO,QAAQ,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC;AACtE,CAAC"}

package/dist/connectors/telegram/renderAgentHtml.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @description Render the agent adapters' "markdown-ish" output
+ * (`*bold*`, `**bold**`, `# headings`, `` `inline` ``, ```` ```fenced``` ````,
+ * `[text](url)`) into Telegram **HTML**.
+ *
+ * Why HTML instead of the legacy Markdown path: Telegram's classic Markdown
+ * drops the WHOLE message to unformatted plain text on a single stray `*` or
+ * an unbalanced backtick — this is the live "git diff shows literal ``` ``` ```
+ * ``` characters" bug. HTML's only specials are `& < >`, so lone punctuation is
+ * inert and fenced code / diffs render as real monospaced blocks.
+ *
+ * Used ONLY for streamed agent output + status frames. Bot-authored `t(...)`
+ * templates keep their legacy Markdown rendering — they don't have the bug.
+ * Both adapters (Claude + OpenCode) share this single render path.
+ */
+/** HTML-escape the three characters Telegram's HTML parse_mode treats as
+ *  special. Nothing else needs escaping in HTML text nodes / code spans. */
+export declare function escapeHtmlText(text: string): string;
+/**
+ * Code spans are protected first (stashed as placeholders) so prose-level
+ * bold/link substitution can't reach inside them, then everything is
+ * HTML-escaped, then bold/links are applied to the already-escaped prose (so
+ * the tags we insert are not themselves escaped, and a lone `*`/backtick in
+ * prose stays literal instead of breaking the parse).
+ */
+export declare function renderAgentHtml(text: string): string;
+//# sourceMappingURL=renderAgentHtml.d.ts.map

package/dist/connectors/telegram/renderAgentHtml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderAgentHtml.d.ts","sourceRoot":"","sources":["../../../src/connectors/telegram/renderAgentHtml.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH;4EAC4E;AAC5E,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AA0BD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAmDpD"}

package/dist/connectors/telegram/renderAgentHtml.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * @description Render the agent adapters' "markdown-ish" output
+ * (`*bold*`, `**bold**`, `# headings`, `` `inline` ``, ```` ```fenced``` ````,
+ * `[text](url)`) into Telegram **HTML**.
+ *
+ * Why HTML instead of the legacy Markdown path: Telegram's classic Markdown
+ * drops the WHOLE message to unformatted plain text on a single stray `*` or
+ * an unbalanced backtick — this is the live "git diff shows literal ``` ``` ```
+ * ``` characters" bug. HTML's only specials are `& < >`, so lone punctuation is
+ * inert and fenced code / diffs render as real monospaced blocks.
+ *
+ * Used ONLY for streamed agent output + status frames. Bot-authored `t(...)`
+ * templates keep their legacy Markdown rendering — they don't have the bug.
+ * Both adapters (Claude + OpenCode) share this single render path.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escapeHtmlText = escapeHtmlText;
+exports.renderAgentHtml = renderAgentHtml;
+const markdownTableRender_1 = require("../../utils/markdownTableRender");
+/** HTML-escape the three characters Telegram's HTML parse_mode treats as
+ *  special. Nothing else needs escaping in HTML text nodes / code spans. */
+function escapeHtmlText(text) {
+    return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+// Matchers for the adapter's "markdown-ish" intermediate. Hoisted so they
+// aren't recompiled per chunk; `g`-flag regexes are stateful, so every use
+// goes through `String.replace` (which resets `lastIndex`), never `.exec`.
+const FENCE_REGEX = /```([^\n`]*)\n?([\s\S]*?)```/g;
+const INLINE_CODE_REGEX = /`([^`\n]+)`/g;
+// `**bold**` must run BEFORE the single-star `*bold*` matcher: otherwise the
+// single-star regex matches from the 2nd asterisk of `**` and leaves a stray
+// leading `*` (live OpenCode trace: `*<b>bold</b>*`). Non-greedy so adjacent
+// pairs `**a** **b**` don't merge into one span.
+const DOUBLE_BOLD_REGEX = /\*\*([^\n]+?)\*\*/g;
+const BOLD_REGEX = /\*([^*\n]+)\*/g;
+const LINK_REGEX = /\[([^\]\n]+)\]\(([^)\s]+)\)/g;
+// Markdown ATX headings (`#`…`######` + text). Telegram has no heading
+// element, so render the line as bold — the established convention. Anchored
+// to line start with the `m` flag, so a `#` mid-line stays literal.
+const HEADING_REGEX = /^#{1,6}\s+(.+)$/gm;
+const PLACEHOLDER_REGEX = /\x00(\d+)\x00/g;
+/**
+ * C0 control chars except `\n` and `\t`. They never belong in a Telegram
+ * message, and a stray `\x00` would collide with the placeholder sentinel
+ * `\x00N\x00` and resurrect a wrong / `undefined` span — strip up front.
+ */
+const CONTROL_CHARS_REGEX = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g;
+/**
+ * Code spans are protected first (stashed as placeholders) so prose-level
+ * bold/link substitution can't reach inside them, then everything is
+ * HTML-escaped, then bold/links are applied to the already-escaped prose (so
+ * the tags we insert are not themselves escaped, and a lone `*`/backtick in
+ * prose stays literal instead of breaking the parse).
+ */
+function renderAgentHtml(text) {
+    const placeholders = [];
+    const stash = (html) => {
+        placeholders.push(html);
+        return `\x00${placeholders.length - 1}\x00`;
+    };
+    // 0. Drop control chars up front so the placeholder sentinel we add in
+    //    `stash` is the only `\x00` left to restore in step 5.
+    const source = text.replace(CONTROL_CHARS_REGEX, '');
+    // 0.5. Rewrite raw GFM markdown tables (mostly from OpenCode) into a readable
+    //    form: narrow tables become a ```-fenced box (→ <pre> below), wide ones
+    //    become plain "field: value" lines. Fence-aware + leaves non-table text
+    //    untouched, so the downstream passes are unchanged.
+    const withTables = (0, markdownTableRender_1.renderMarkdownTables)(source);
+    // 1. Fenced blocks first — they contain the backticks inline code would
+    //    otherwise mis-match. Escape only `& < >` inside code.
+    let work = withTables.replace(FENCE_REGEX, (_match, info, body) => {
+        // The info string's first token is the language (CommonMark); ignore any
+        // trailing metadata. Escape `"` too, or it would break the class attribute.
+        const language = info.trim().split(/\s+/)[0] ?? '';
+        const cls = language
+            ? ` class="language-${escapeHtmlText(language).replace(/"/g, '&quot;')}"`
+            : '';
+        return stash(`<pre><code${cls}>${escapeHtmlText(body.replace(/\n$/, ''))}</code></pre>`);
+    });
+    // 2. Inline code.
+    work = work.replace(INLINE_CODE_REGEX, (_match, body) => stash(`<code>${escapeHtmlText(body)}</code>`));
+    // 3. Escape the remaining prose.
+    work = escapeHtmlText(work);
+    // 4. Bold + links + headings on the escaped prose. Label/URL are already
+    //    escaped by step 3, so we only additionally guard `"` in the href
+    //    attribute. `**bold**` runs before `*bold*` (see DOUBLE_BOLD_REGEX).
+    work = work.replace(DOUBLE_BOLD_REGEX, '<b>$1</b>');
+    work = work.replace(BOLD_REGEX, '<b>$1</b>');
+    work = work.replace(LINK_REGEX, (_match, label, url) => `<a href="${url.replace(/"/g, '&quot;')}">${label}</a>`);
+    // Headings after bold/links: a heading line may already carry `<b>` from the
+    // bold pass; Telegram accepts nested `<b>`, so no special-casing needed.
+    work = work.replace(HEADING_REGEX, '<b>$1</b>');
+    // 5. Restore the stashed code spans (already valid HTML — do not re-escape).
+    return work.replace(PLACEHOLDER_REGEX, (match, idx) => placeholders[Number(idx)] ?? match);
+}
+//# sourceMappingURL=renderAgentHtml.js.map

package/dist/connectors/telegram/renderAgentHtml.js.map

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

package/dist/connectors/telegram/sessionKeyCodec.d.ts

@@ -0,0 +1,28 @@
+import { type SessionKey, type SessionKeyCodec } from '../../sessionKey';
+/**
+ * @description Telegram's {@link SessionKeyCodec}. `matches` is what lets the
+ * core decode a string with no platform in hand: the all-numeric shape is
+ * unambiguous against every prefixed format a later connector will use.
+ */
+export declare const telegramSessionKeyCodec: SessionKeyCodec;
+/**
+ * @description Build a Telegram {@link SessionKey} from the native numeric ids.
+ *
+ * The single construction point for Telegram keys — production and tests alike.
+ * Funnelling every literal through it is what keeps the string/number boundary
+ * in one place instead of 200 scattered object literals.
+ */
+export declare function makeTelegramKey(chatId: number, threadId: number): SessionKey;
+/**
+ * @description Does this key address the Telegram surface? Core predicates use
+ * it to answer `false` for a foreign key instead of throwing out of the native
+ * accessors below.
+ */
+export declare function checkIsTelegramKey(key: SessionKey): boolean;
+/** How a native accessor's refusal of a foreign key starts — shared with the test that proves none was reached. */
+export declare const foreignKeyAccessorErrorPrefix = "Expected a Telegram SessionKey";
+/** The native Telegram chat id — what the Bot API expects on every send. */
+export declare function getTelegramChatId(key: SessionKey): number;
+/** The native Telegram `message_thread_id` (`0` = owner-DM main thread). */
+export declare function getTelegramThreadId(key: SessionKey): number;
+//# sourceMappingURL=sessionKeyCodec.d.ts.map

package/dist/connectors/telegram/sessionKeyCodec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionKeyCodec.d.ts","sourceRoot":"","sources":["../../../src/connectors/telegram/sessionKeyCodec.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,UAAU,EACf,KAAK,eAAe,EACrB,MAAM,kBAAkB,CAAC;AA2B1B;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,eAyBrC,CAAC;AAYF;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,CAE5E;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAE3D;AAED,mHAAmH;AACnH,eAAO,MAAM,6BAA6B,mCAAmC,CAAC;AAa9E,4EAA4E;AAC5E,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAEzD;AAED,4EAA4E;AAC5E,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAE3D"}

package/dist/connectors/telegram/sessionKeyCodec.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.foreignKeyAccessorErrorPrefix = exports.telegramSessionKeyCodec = void 0;
+exports.makeTelegramKey = makeTelegramKey;
+exports.checkIsTelegramKey = checkIsTelegramKey;
+exports.getTelegramChatId = getTelegramChatId;
+exports.getTelegramThreadId = getTelegramThreadId;
+const sessionKey_1 = require("../../sessionKey");
+/** The platform id this connector answers to. */
+const telegramPlatform = 'telegram';
+/**
+ * @description The historical on-the-wire spelling: `"<chatId>:<threadId>"`.
+ *
+ * Deliberately UNCHANGED from the pre-seam `keyToString`. The same string is a
+ * `state.json` field name, the tail of a tmux session name
+ * (`claude-<chatId>-<threadId>`), a per-thread JSON map key and (with `:` swapped
+ * for `_`) a file-intake directory name. Changing it would rename all four and
+ * orphan every live agent session, so this format is frozen: new platforms
+ * differentiate by prefixing their own id, never by touching this one.
+ *
+ * Chat ids are negative for forum supergroups; thread ids are never negative
+ * (`0` = the owner-DM main thread, `1` = the supergroup General topic). The
+ * per-half strictness matters — a plain `Number()` would accept `1e5`, `0x10`,
+ * `1.5` and `" 42 "`, letting a foreign string masquerade as one of ours.
+ */
+const telegramKeyRe = /^(-?\d+):(\d+)$/;
+function decodeTelegramKey(serialized) {
+    const match = telegramKeyRe.exec(serialized);
+    return match ? { platform: telegramPlatform, space: match[1], thread: match[2] } : null;
+}
+/**
+ * @description Telegram's {@link SessionKeyCodec}. `matches` is what lets the
+ * core decode a string with no platform in hand: the all-numeric shape is
+ * unambiguous against every prefixed format a later connector will use.
+ */
+exports.telegramSessionKeyCodec = {
+    platform: telegramPlatform,
+    encode(key) {
+        return `${key.space}:${key.thread}`;
+    },
+    decode(serialized) {
+        const key = decodeTelegramKey(serialized);
+        if (!key)
+            throw new Error(`Invalid Telegram SessionKey string: "${serialized}"`);
+        return key;
+    },
+    matches(serialized) {
+        return telegramKeyRe.test(serialized);
+    },
+    // The key has exactly one `:`, so the slug splits on its LAST separator: a
+    // negative chat id keeps its own leading minus (`-100123-42` with `-`).
+    decodeSlug(slug, separator) {
+        const lastSeparator = slug.lastIndexOf(separator);
+        if (lastSeparator <= 0)
+            return null;
+        const serialized = `${slug.slice(0, lastSeparator)}:${slug.slice(lastSeparator + separator.length)}`;
+        return decodeTelegramKey(serialized);
+    },
+};
+/**
+ * Self-registering on import so every module that constructs or reads a
+ * Telegram key transitively arms the decoder. The composition roots
+ * (`bot.ts`, the test bootstrap) import this module explicitly for the paths —
+ * `state.ts`, the `DATA_DIR` janitors — that decode without ever building a key.
+ * {@link registerSessionKeyCodec} is idempotent per platform, so a repeated
+ * import is harmless.
+ */
+(0, sessionKey_1.registerSessionKeyCodec)(exports.telegramSessionKeyCodec);
+/**
+ * @description Build a Telegram {@link SessionKey} from the native numeric ids.
+ *
+ * The single construction point for Telegram keys — production and tests alike.
+ * Funnelling every literal through it is what keeps the string/number boundary
+ * in one place instead of 200 scattered object literals.
+ */
+function makeTelegramKey(chatId, threadId) {
+    return { platform: telegramPlatform, space: `${chatId}`, thread: `${threadId}` };
+}
+/**
+ * @description Does this key address the Telegram surface? Core predicates use
+ * it to answer `false` for a foreign key instead of throwing out of the native
+ * accessors below.
+ */
+function checkIsTelegramKey(key) {
+    return key.platform === telegramPlatform;
+}
+/** How a native accessor's refusal of a foreign key starts — shared with the test that proves none was reached. */
+exports.foreignKeyAccessorErrorPrefix = 'Expected a Telegram SessionKey';
+function getTelegramNumber(key, field) {
+    if (!checkIsTelegramKey(key)) {
+        throw new Error(`${exports.foreignKeyAccessorErrorPrefix}, got platform "${key.platform}"`);
+    }
+    const value = Number(key[field]);
+    if (!Number.isFinite(value)) {
+        throw new Error(`Invalid Telegram ${field} in SessionKey: "${key[field]}"`);
+    }
+    return value;
+}
+/** The native Telegram chat id — what the Bot API expects on every send. */
+function getTelegramChatId(key) {
+    return getTelegramNumber(key, 'space');
+}
+/** The native Telegram `message_thread_id` (`0` = owner-DM main thread). */
+function getTelegramThreadId(key) {
+    return getTelegramNumber(key, 'thread');
+}
+//# sourceMappingURL=sessionKeyCodec.js.map

package/dist/connectors/telegram/sessionKeyCodec.js.map

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

package/dist/connectors/telegram/telegramCallGuard.d.ts

@@ -0,0 +1,19 @@
+import type { CallApiHost } from '../../outputTrace';
+/**
+ * @description An instance that does not serve Telegram (Jira connector plan J3,
+ * D9) still constructs the Telegram client — `bot.ts` is built around it — but
+ * must never reach the Bot API: no token is configured, and a call slipping
+ * through means a Telegram path a Jira conversation was supposed to stay out of.
+ * Installed OUTERMOST, so the call fails before anything is sent or traced, and
+ * logged here: many callers treat a failed Bot API call as best-effort and drop
+ * the error, which would hide the very path this guard exists to expose. Logged
+ * once per method: a path reached per output chunk or per timer tick must expose
+ * itself, not flood the log (and the console tee) with the same line.
+ */
+export declare class TelegramDisabledError extends Error {
+    constructor(method: string);
+}
+/** The log line of a refused call — written by the guard itself, as a caller may swallow the rejection. */
+export declare const telegramCallRefusedLogPrefix = "[telegram-guard] refused";
+export declare function installTelegramCallGuard(host: CallApiHost): void;
+//# sourceMappingURL=telegramCallGuard.d.ts.map

package/dist/connectors/telegram/telegramCallGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegramCallGuard.d.ts","sourceRoot":"","sources":["../../../src/connectors/telegram/telegramCallGuard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;;;;;;;GAUG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,MAAM,EAAE,MAAM;CAI3B;AAED,2GAA2G;AAC3G,eAAO,MAAM,4BAA4B,6BAA6B,CAAC;AAEvE,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAShE"}

package/dist/connectors/telegram/telegramCallGuard.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.telegramCallRefusedLogPrefix = exports.TelegramDisabledError = void 0;
+exports.installTelegramCallGuard = installTelegramCallGuard;
+/**
+ * @description An instance that does not serve Telegram (Jira connector plan J3,
+ * D9) still constructs the Telegram client — `bot.ts` is built around it — but
+ * must never reach the Bot API: no token is configured, and a call slipping
+ * through means a Telegram path a Jira conversation was supposed to stay out of.
+ * Installed OUTERMOST, so the call fails before anything is sent or traced, and
+ * logged here: many callers treat a failed Bot API call as best-effort and drop
+ * the error, which would hide the very path this guard exists to expose. Logged
+ * once per method: a path reached per output chunk or per timer tick must expose
+ * itself, not flood the log (and the console tee) with the same line.
+ */
+class TelegramDisabledError extends Error {
+    constructor(method) {
+        super(`Telegram API call "${method}" refused: the telegram connector is off for this instance`);
+        this.name = 'TelegramDisabledError';
+    }
+}
+exports.TelegramDisabledError = TelegramDisabledError;
+/** The log line of a refused call — written by the guard itself, as a caller may swallow the rejection. */
+exports.telegramCallRefusedLogPrefix = '[telegram-guard] refused';
+function installTelegramCallGuard(host) {
+    const loggedMethods = new Set();
+    host.callApi = async (method) => {
+        if (!loggedMethods.has(method)) {
+            loggedMethods.add(method);
+            console.error(`${exports.telegramCallRefusedLogPrefix} ${method}: a Telegram path was reached in an instance without the telegram connector`);
+        }
+        throw new TelegramDisabledError(method);
+    };
+}
+//# sourceMappingURL=telegramCallGuard.js.map

package/dist/connectors/telegram/telegramCallGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegramCallGuard.js","sourceRoot":"","sources":["../../../src/connectors/telegram/telegramCallGuard.ts"],"names":[],"mappings":";;;AAuBA,4DASC;AA9BD;;;;;;;;;;GAUG;AACH,MAAa,qBAAsB,SAAQ,KAAK;IAC9C,YAAY,MAAc;QACxB,KAAK,CAAC,sBAAsB,MAAM,4DAA4D,CAAC,CAAC;QAChG,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AALD,sDAKC;AAED,2GAA2G;AAC9F,QAAA,4BAA4B,GAAG,0BAA0B,CAAC;AAEvE,SAAgB,wBAAwB,CAAC,IAAiB;IACxD,MAAM,aAAa,GAAG,IAAI,GAAG,EAAU,CAAC;IACxC,IAAI,CAAC,OAAO,GAAG,KAAK,EAAE,MAAM,EAAE,EAAE;QAC9B,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YAC/B,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAC1B,OAAO,CAAC,KAAK,CAAC,GAAG,oCAA4B,IAAI,MAAM,6EAA6E,CAAC,CAAC;QACxI,CAAC;QACD,MAAM,IAAI,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC1C,CAAC,CAAC;AACJ,CAAC"}

package/dist/connectors/telegram/timezonePicker.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @description Pure builders + callback codec for the two-level `/timezone`
+ * picker: level 1 is the 10 IANA regions, level 2 is that region's zones,
+ * paginated.
+ *
+ * Two levels rather than one flat list because there are 418 zones — the same
+ * constraint that forced `/model` into a provider → models picker once a
+ * provider with hundreds of models appeared. And every callback carries INDEXES
+ * rather than the zone name: `America/Argentina/Buenos_Aires` plus a region
+ * index and a page number does not reliably fit Telegram's 64-BYTE
+ * `callback_data` cap, and a truncated id resolves to the wrong zone silently.
+ *
+ * Kept pure (no `t()`, no bot state) so the `✓` placement, the pagination
+ * clamping and the codec round-trip are unit-testable without a Telegram
+ * surface. Header TEXT is the caller's job — it is localized, the keyboard is
+ * not.
+ */
+import { Markup } from 'telegraf';
+/** Zones listed per level-2 page — one per row, matching `/model`'s page size. */
+export declare const timezonePageSize = 10;
+/** Back to the region level (level 2 → level 1). */
+export declare const timezonePickerBackCallback = "tzback";
+/** Reset the setting to the host zone. */
+export declare const timezoneAutoCallback = "tzauto";
+/** Anchored matchers for `bot.action(...)` — the wire format's single definition. */
+export declare const regionPageCallbackRe: RegExp;
+export declare const zonePickCallbackRe: RegExp;
+/** A region index paired with a page index (level-2 navigation). */
+export interface RegionPageRef {
+    regionIndex: number;
+    page: number;
+}
+/** A region index paired with a zone index WITHIN that region's list. */
+export interface ZonePickRef {
+    regionIndex: number;
+    zoneIndex: number;
+}
+export declare function buildRegionPageCallback(regionIndex: number, page: number): string;
+export declare function buildZonePickCallback(regionIndex: number, zoneIndex: number): string;
+export declare function parseRegionPageCallback(callbackData: string): RegionPageRef | null;
+export declare function parseZonePickCallback(callbackData: string): ZonePickRef | null;
+/**
+ * @description Resolve a level-2 pick back to its zone name, or `null` when the
+ * indexes no longer resolve. Stale keyboards stay tappable forever in Telegram,
+ * so an out-of-range index must answer "nothing" rather than pick a neighbour.
+ */
+export declare function getTimezoneAt(regionIndex: number, zoneIndex: number): string | null;
+/** The region name at `regionIndex`, or `null` for a stale index. */
+export declare function getTimezoneRegionAt(regionIndex: number): string | null;
+/**
+ * @description Build the level-1 region keyboard, two regions per row, plus a
+ * full-width `🌐 Auto (host zone)` reset row.
+ *
+ * The `✓` marks the region CONTAINING the current zone (so the operator can see
+ * where they are without opening a page), or the Auto row when nothing is
+ * stored. A fixed-offset zone (`+04:00`) belongs to no region, so no region is
+ * marked — that is honest rather than arbitrarily highlighting one.
+ *
+ * `🌐 Auto (host zone)` is a fixed glyph+word rather than a translated string,
+ * mirroring the `/language` picker's Auto row: recognisable across locales and
+ * one less per-locale key to keep in parity.
+ */
+export declare function buildTimezoneRegionPicker(currentZone: string | null): Markup.Markup<import("@telegraf/types").InlineKeyboardMarkup>;
+/**
+ * @description One rendered level-2 page: the keyboard plus the numbers the
+ * caller needs for the localized header. `currentPage` is already CLAMPED by
+ * {@link paginateList}, so a stale page index lands on the last real page rather
+ * than rendering an empty body.
+ */
+export interface TimezonePageRender {
+    region: string;
+    keyboard: ReturnType<typeof Markup.inlineKeyboard>;
+    /** Zero-based, clamped. */
+    currentPage: number;
+    totalPages: number;
+}
+/**
+ * @description Build a region's zone page: one zone per row (names are long),
+ * with a `‹ Prev` / page pill / `⬅ Regions` / `Next ›` navigation row.
+ *
+ * Returns `null` for a region index that no longer resolves — a stale callback
+ * must be answered as expired, not rendered against a different region.
+ */
+export declare function buildTimezoneZonePicker(regionIndex: number, page: number, currentZone: string | null): TimezonePageRender | null;
+//# sourceMappingURL=timezonePicker.d.ts.map