@a1hvdy/cc-openclaw 0.27.1 → 0.27.4

package/dist/src/constants.d.ts

@@ -36,6 +36,16 @@ export declare const TURN_TIMEOUT_MS = 900000;
 export declare const STALLED_SESSION_KILL_MS = 180000;
 /** How often the stalled-session watchdog scans the sessions Map. */
 export declare const STALLED_WATCH_INTERVAL_MS = 30000;
+/** v0.27.4 (M4/M6) — resume-freshness window for openai-compat sessions.
+ *  After a gateway restart OR a stalled-session watchdog SIGTERM, the in-process
+ *  session object is gone; without this, the next turn for the same chat spawns
+ *  a FRESH Claude conversation (no --resume) and the user loses all context.
+ *  When an openai-compat session opts in (config.resumeFreshnessMs), the next
+ *  turn resumes the prior Claude session ONLY if it was active within this
+ *  window — older sessions start fresh, preserving the anti-stale intent that
+ *  motivated skipPersistence. Default 30 min; env-overridable at the use site
+ *  via CC_OPENCLAW_RESUME_FRESHNESS_MS. */
+export declare const RESUME_FRESHNESS_MS = 1800000;
 /** Runaway-loop watchdog: max new cc-openclaw subprocess spawns within
  *  RUNAWAY_LOOP_WINDOW_MS before the next spawn is refused.
  *

package/dist/src/constants.js

@@ -39,6 +39,16 @@ export const TURN_TIMEOUT_MS = 900_000;
 export const STALLED_SESSION_KILL_MS = 180_000;
 /** How often the stalled-session watchdog scans the sessions Map. */
 export const STALLED_WATCH_INTERVAL_MS = 30_000;
+/** v0.27.4 (M4/M6) — resume-freshness window for openai-compat sessions.
+ *  After a gateway restart OR a stalled-session watchdog SIGTERM, the in-process
+ *  session object is gone; without this, the next turn for the same chat spawns
+ *  a FRESH Claude conversation (no --resume) and the user loses all context.
+ *  When an openai-compat session opts in (config.resumeFreshnessMs), the next
+ *  turn resumes the prior Claude session ONLY if it was active within this
+ *  window — older sessions start fresh, preserving the anti-stale intent that
+ *  motivated skipPersistence. Default 30 min; env-overridable at the use site
+ *  via CC_OPENCLAW_RESUME_FRESHNESS_MS. */
+export const RESUME_FRESHNESS_MS = 1_800_000;
 /** Runaway-loop watchdog: max new cc-openclaw subprocess spawns within
  *  RUNAWAY_LOOP_WINDOW_MS before the next spawn is refused.
  *

package/dist/src/lib/error-formatter.d.ts

@@ -49,7 +49,12 @@ export interface ErrorContext {
 export interface FormattedError {
     /** NDJSON-ready row */
     jsonlRow: ErrorJsonlRow;
-    /** Telegram message text (MarkdownV2-safe) */
+    /**
+     * Telegram message text (HTML parse_mode). v0.27.3 — converted from
+     * MarkdownV2 to HTML so the entire Telegram surface (live card + error
+     * alerts) renders through ONE parse mode. error-renderer sends this with
+     * parse_mode: 'HTML'.
+     */
     telegramText: string;
 }
 export interface ErrorJsonlRow {
@@ -64,7 +69,14 @@ export interface ErrorJsonlRow {
 }
 /** Extract a usable message from unknown thrown values. */
 export declare function extractMessage(error: unknown): string;
-/** Escape characters special to Telegram MarkdownV2. */
+/**
+ * Escape characters special to Telegram MarkdownV2.
+ *
+ * v0.27.3 — RETAINED for back-compat (and its own unit tests) but no longer
+ * used by formatError, which now emits HTML (see the telegramText block) so the
+ * whole Telegram surface renders through one parse mode. Kept exported in case a
+ * caller still needs MarkdownV2 escaping.
+ */
 export declare function escapeMdV2(text: string): string;
 /**
  * Pure formatter — no side effects on the return value, but DOES emit

package/dist/src/lib/error-formatter.js

@@ -80,7 +80,14 @@ function extractStack(error) {
     }
     return undefined;
 }
-/** Escape characters special to Telegram MarkdownV2. */
+/**
+ * Escape characters special to Telegram MarkdownV2.
+ *
+ * v0.27.3 — RETAINED for back-compat (and its own unit tests) but no longer
+ * used by formatError, which now emits HTML (see the telegramText block) so the
+ * whole Telegram surface renders through one parse mode. Kept exported in case a
+ * caller still needs MarkdownV2 escaping.
+ */
 export function escapeMdV2(text) {
     // Per Telegram docs, these must be escaped: _ * [ ] ( ) ~ ` > # + - = | { } . !
     return text.replace(/[_*[\]()~`>#+=|{}.!\\-]/g, (c) => `\\${c}`);
@@ -97,6 +104,7 @@ const SEVERITY_EMOJI = {
 // are unset, so the import itself has zero runtime cost.
 import { emit as emitTrajectory } from './trajectory.js';
 import { metricsRegistry } from '../health/metrics.js';
+import { escapeHtml } from './html-render.js';
 /**
  * Pure formatter — no side effects on the return value, but DOES emit
  * trajectory + metrics events for centralized observability per Pillars A+B.
@@ -128,27 +136,31 @@ export function formatError(error, context) {
         ...(stack !== undefined ? { stack } : {}),
         ...(context.details !== undefined ? { details: context.details } : {}),
     };
+    // v0.27.3 — emit Telegram HTML (sent with parse_mode: 'HTML' by
+    // error-renderer) so error alerts share the live card's single render path.
+    // <b> code, <code> message, <i> timestamp; all interpolated text is
+    // HTML-escaped (& < >) so a stray < in a message can't break the parser.
     const emoji = SEVERITY_EMOJI[severity];
-    const safeCode = escapeMdV2(context.code);
-    const safeMsg = escapeMdV2(message.length > 300 ? message.slice(0, 300) + '...' : message);
-    const safeTs = escapeMdV2(ts.slice(0, 19).replace('T', ' '));
+    const safeCode = escapeHtml(context.code);
+    const safeMsg = escapeHtml(message.length > 300 ? message.slice(0, 300) + '...' : message);
+    const safeTs = escapeHtml(ts.slice(0, 19).replace('T', ' '));
     const lines = [
-        `${emoji} *${safeCode}*`,
-        `\`${safeMsg}\``,
-        `_${safeTs}_`,
+        `${emoji} <b>${safeCode}</b>`,
+        `<code>${safeMsg}</code>`,
+        `<i>${safeTs}</i>`,
     ];
     if (context.sessionId) {
-        lines.push(`session: \`${escapeMdV2(context.sessionId)}\``);
+        lines.push(`session: <code>${escapeHtml(context.sessionId)}</code>`);
     }
     if (context.laptopId) {
-        lines.push(`laptop: \`${escapeMdV2(context.laptopId)}\``);
+        lines.push(`laptop: <code>${escapeHtml(context.laptopId)}</code>`);
     }
     if (context.details && Object.keys(context.details).length > 0) {
         const detailParts = Object.entries(context.details)
             .slice(0, 5)
-            .map(([k, v]) => `${escapeMdV2(k)}: ${escapeMdV2(String(v))}`)
+            .map(([k, v]) => `${escapeHtml(k)}: ${escapeHtml(String(v))}`)
             .join(', ');
-        lines.push(`_${detailParts}_`);
+        lines.push(`<i>${detailParts}</i>`);
     }
     const telegramText = lines.join('\n');
     return { jsonlRow, telegramText };

package/dist/src/lib/error-renderer.js

@@ -67,7 +67,9 @@ export async function renderError(formatted, opts = {}) {
     const params = {
         chat_id: chatId,
         text: telegramText,
-        parse_mode: 'MarkdownV2',
+        // v0.27.3 — HTML (formatter now emits HTML) so error alerts share the live
+        // card's single render path. The 400-fallback below sends plain text.
+        parse_mode: 'HTML',
     };
     if (opts.threadId)
         params.message_thread_id = opts.threadId;

package/dist/src/lib/html-render.d.ts

@@ -18,26 +18,18 @@
 export declare function escapeHtml(text: string | null | undefined): string;
 /** Inline monospace span: `<code>escaped</code>`. */
 export declare function code(s: string): string;
+/**
+ * Strip Telegram HTML markup back to readable plain text (v0.27.3). Used
+ * by editTg's plain-text fallback: when an HTML edit is rejected, re-sending the
+ * SAME string without parse_mode would dump literal `<b>`/`<pre>` tags into the
+ * chat. This removes the tags and decodes the basic entities so the fallback
+ * stays legible. Not a general sanitizer — scoped to the tags this module emits.
+ */
+export declare function stripHtml(input: string | null | undefined): string;
 /**
  * Fenced code block: `<pre><code class="language-LANG">escaped</code></pre>`.
  * Omits the class when no language is given. Body is HTML-escaped (the only
  * escaping Telegram requires inside pre/code).
  */
 export declare function pre(body: string, lang?: string): string;
-/**
- * Convert a subset of CommonMark Markdown to Telegram HTML with structure
- * preserved (`**bold**`→`<b>`, fenced blocks→`<pre><code>`, etc.). Returns ''
- * for null/undefined.
- *
- * Algorithm (placeholder substitution, NUL-sentinel keyed — mirrors
- * markdown-to-mdv2.ts so behaviour is auditable side-by-side):
- *   1. code fences  → <pre><code [class]>…</code></pre>
- *   2. inline code  → <code>…</code>
- *   3. bold (**…**) → <b>…</b>
- *   4. italic (*…* / _…_) → <i>…</i>
- *   5. ATX headers (#…) at line start → <b>…</b>
- *   6. links [label](url) → <a href="url">label</a>
- *   7. escape remaining text (& < >)
- *   8. restore placeholders verbatim
- */
 export declare function markdownToHtml(input: string | null | undefined): string;

package/dist/src/lib/html-render.js

@@ -14,6 +14,7 @@
  * pre+code[class=language-X], blockquote, tg-spoiler. Everything else in text
  * content must have &, <, > escaped.
  */
+/* eslint-disable no-control-regex -- NUL-byte sentinel delimiters intentionally guard placeholders through the bulk-escape step, then are restored */
 /** Escape the three HTML-significant chars for Telegram HTML text content. */
 export function escapeHtml(text) {
     if (text == null)
@@ -27,6 +28,23 @@ export function escapeHtml(text) {
 export function code(s) {
     return `<code>${escapeHtml(s)}</code>`;
 }
+/**
+ * Strip Telegram HTML markup back to readable plain text (v0.27.3). Used
+ * by editTg's plain-text fallback: when an HTML edit is rejected, re-sending the
+ * SAME string without parse_mode would dump literal `<b>`/`<pre>` tags into the
+ * chat. This removes the tags and decodes the basic entities so the fallback
+ * stays legible. Not a general sanitizer — scoped to the tags this module emits.
+ */
+export function stripHtml(input) {
+    if (input == null)
+        return '';
+    return String(input)
+        .replace(/<\/?(?:b|strong|i|em|u|s|a|code|pre|blockquote|tg-spoiler)\b[^>]*>/gi, '')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&amp;/g, '&');
+}
 /**
  * Fenced code block: `<pre><code class="language-LANG">escaped</code></pre>`.
  * Omits the class when no language is given. Body is HTML-escaped (the only
@@ -52,16 +70,73 @@ export function pre(body, lang) {
  *   7. escape remaining text (& < >)
  *   8. restore placeholders verbatim
  */
+/** Split a GFM table row into trimmed cells, dropping the empty cells produced
+ *  by leading/trailing pipes (`| a | b |` → ['a','b']). */
+function splitTableRow(row) {
+    const cells = row.split('|').map((c) => c.trim());
+    if (cells.length && cells[0] === '')
+        cells.shift();
+    if (cells.length && cells[cells.length - 1] === '')
+        cells.pop();
+    return cells;
+}
+/** Render parsed table rows as a padded monospace block. Telegram HTML has no
+ *  <table>, so column-aligned text inside <pre> is the faithful terminal-style
+ *  rendering. Returns a ready <pre><code> string (content HTML-escaped by pre()). */
+function renderPaddedTable(rows) {
+    const cols = Math.max(...rows.map((r) => r.length));
+    const widths = [];
+    for (let c = 0; c < cols; c++) {
+        widths[c] = Math.max(...rows.map((r) => (r[c] ?? '').length));
+    }
+    const body = rows
+        .map((r) => Array.from({ length: cols }, (_v, c) => (r[c] ?? '').padEnd(widths[c]))
+        .join(' | ')
+        .replace(/\s+$/, ''))
+        .join('\n');
+    return pre(body);
+}
 export function markdownToHtml(input) {
     if (input == null)
         return '';
     let text = String(input);
     const codeBlocks = [];
-    text = text.replace(/```([a-zA-Z0-9_+\-]*)\n?([\s\S]*?)```/g, (_m, lang, body) => {
+    text = text.replace(/```([a-zA-Z0-9_+-]*)\n?([\s\S]*?)```/g, (_m, lang, body) => {
         const idx = codeBlocks.length;
         codeBlocks.push(pre(body.replace(/\n$/, ''), lang || undefined));
         return `\x00CODEBLOCK${idx}\x00`;
     });
+    // v0.27.4 M4 — GFM pipe tables → padded monospace <pre> (gap #5). Telegram HTML
+    // has no <table>; column-aligned text is the terminal-faithful rendering. A
+    // table is a row containing `|` immediately followed by a `---` separator row.
+    const tables = [];
+    {
+        const lines = text.split('\n');
+        const out = [];
+        let i = 0;
+        while (i < lines.length) {
+            const header = lines[i];
+            const sep = lines[i + 1];
+            const isSep = sep != null && sep.includes('-') && /^\s*\|?[\s:|-]+\|?\s*$/.test(sep);
+            if (header != null && header.includes('|') && isSep) {
+                const block = [splitTableRow(header)];
+                let j = i + 2;
+                while (j < lines.length && lines[j].includes('|') && lines[j].trim() !== '') {
+                    block.push(splitTableRow(lines[j]));
+                    j++;
+                }
+                const idx = tables.length;
+                tables.push(renderPaddedTable(block));
+                out.push(`\x00TABLE${idx}\x00`);
+                i = j;
+            }
+            else {
+                out.push(header);
+                i++;
+            }
+        }
+        text = out.join('\n');
+    }
     const inlineCodes = [];
     text = text.replace(/`([^`\n]+)`/g, (_m, body) => {
         const idx = inlineCodes.length;
@@ -74,6 +149,14 @@ export function markdownToHtml(input) {
         bolds.push(`<b>${escapeHtml(body)}</b>`);
         return `\x00BOLD${idx}\x00`;
     });
+    // v0.27.4 M4 — strikethrough ~~text~~ → <s> (gap #5). After bold so the `~~`
+    // pass never sees `**`-delimited spans.
+    const strikes = [];
+    text = text.replace(/~~([^~\n]+)~~/g, (_m, body) => {
+        const idx = strikes.length;
+        strikes.push(`<s>${escapeHtml(body)}</s>`);
+        return `\x00STRIKE${idx}\x00`;
+    });
     const italics = [];
     text = text.replace(/(?<![\w*])\*([^*\n]+)\*(?!\w)/g, (_m, body) => {
         const idx = italics.length;
@@ -99,10 +182,17 @@ export function markdownToHtml(input) {
         links.push(`<a href="${safeUrl}">${escapeHtml(label)}</a>`);
         return `\x00LINK${idx}\x00`;
     });
+    // v0.27.4 M4 — unordered list markers (-, *, +) at line start → "• " bullet
+    // (gap #5). Ordered lists (1. 2.) already read fine as plain text. The bullet
+    // glyph isn't HTML-significant, so it survives the escape below. Uses [ \t]
+    // (not \s) so it never consumes the line break.
+    text = text.replace(/^([ \t]*)[-*+][ \t]+/gm, (_m, indent) => `${indent}• `);
     text = escapeHtml(text);
     text = text.replace(/\x00CODEBLOCK(\d+)\x00/g, (_m, idx) => codeBlocks[Number(idx)]);
+    text = text.replace(/\x00TABLE(\d+)\x00/g, (_m, idx) => tables[Number(idx)]);
     text = text.replace(/\x00INLINECODE(\d+)\x00/g, (_m, idx) => inlineCodes[Number(idx)]);
     text = text.replace(/\x00BOLD(\d+)\x00/g, (_m, idx) => bolds[Number(idx)]);
+    text = text.replace(/\x00STRIKE(\d+)\x00/g, (_m, idx) => strikes[Number(idx)]);
     text = text.replace(/\x00ITALIC(\d+)\x00/g, (_m, idx) => italics[Number(idx)]);
     text = text.replace(/\x00HEADER(\d+)\x00/g, (_m, idx) => headers[Number(idx)]);
     text = text.replace(/\x00LINK(\d+)\x00/g, (_m, idx) => links[Number(idx)]);

package/dist/src/lib/markdown-to-mdv2.js

@@ -46,6 +46,7 @@
  *   - "CODE"/"BOLD"/etc letters are not in the special-char set
  *   So placeholders survive the bulk-escape step intact.
  */
+/* eslint-disable no-control-regex -- NUL-byte sentinel delimiters intentionally guard placeholders through the bulk-escape step, then are restored */
 /** MarkdownV2 special characters (Telegram Bot API spec). Outside code spans
  *  / pre blocks, these MUST be backslash-escaped when intended as content. */
 const MDV2_TEXT_SPECIAL = /[_*[\]()~`>#+\-=|{}.!\\]/g;
@@ -73,7 +74,7 @@ export function markdownToMdv2(input) {
     // Step 1 — extract code fences (triple-backtick blocks). Body verbatim
     // except backticks and backslashes are escaped per Telegram spec.
     const codeBlocks = [];
-    text = text.replace(/```([a-zA-Z0-9_+\-]*)\n?([\s\S]*?)```/g, (_m, lang, body) => {
+    text = text.replace(/```([a-zA-Z0-9_+-]*)\n?([\s\S]*?)```/g, (_m, lang, body) => {
         const idx = codeBlocks.length;
         const langStr = lang || '';
         const escapedBody = escapeCodeContent(body);

package/dist/src/lib/probes.d.ts

@@ -0,0 +1,50 @@
+/**
+ * src/lib/probes.ts — Phase-0 empirical probe instrumentation (planning P0-A/B/C).
+ *
+ * OBSERVE-ONLY. Gated by `CC_OPENCLAW_PROBE=1` so it is completely silent — zero
+ * behavior change, no log output — in normal operation. The operator (A1)
+ * enables it for a single probe session, exercises the relevant Telegram
+ * interaction, then greps stderr for the `[cc-openclaw/probe]` markers. The
+ * runbook (PROBES-RUNBOOK in the planning dir) has the exact steps + how to read
+ * the results.
+ *
+ * These resolve the load-bearing seams that CANNOT be read from source because
+ * they depend on OpenClaw gateway runtime behavior:
+ *   P0-A: does `enqueueNextTurnInjection` trigger a run, or only stage context
+ *         for the next user message? (decides feature #1 Approve + #3 /send)
+ *   P0-B: does an `ExitPlanMode` tool_use ever fire on the bypassPermissions
+ *         Telegram path? (decides feature #1's trigger)
+ *   P0-C: does a Telegram photo reach the plugin as an image block — at
+ *         before_dispatch and/or in the openai-compat request body (where
+ *         message-extractor strips non-text parts) — or is it gateway-stripped?
+ *         (decides whether feature #2 is plugin-side feasible at all)
+ */
+/**
+ * P0-A — log each `enqueueNextTurnInjection` call site. The operator correlates
+ * this with whether a reply arrives in Telegram WITHOUT typing a follow-up
+ * message: if it does, injection triggers a run; if not, it only stages context.
+ */
+export declare function probeInjectionEnqueued(sessionKey: string, source: string): void;
+/**
+ * P0-B — log when a tool_use is `ExitPlanMode` (and any other tool name, for
+ * context). Looks across the known event field paths, mirroring
+ * inbound-handler.extractToolUse so it works whatever shape the gateway uses.
+ */
+export declare function probeToolUse(ev: Record<string, unknown> | undefined): void;
+/**
+ * P0-C (inbound surface) — dump the before_dispatch event, flagging whether it
+ * carries any media field, so the operator sees whether photo/document surface
+ * to the plugin at all.
+ */
+export declare function probeInboundShape(event: unknown): void;
+/**
+ * P0-C (openai-compat body) — the PRECISE probe. Does an image block survive to
+ * the request body, where `message-extractor.ts` strips non-text parts? Logs
+ * each non-text content-part type. If image parts appear here, feature #2 is
+ * feasible plugin-side (preserve them through extractUserMessage); if nothing
+ * non-text ever appears, the image is gateway-stripped upstream → hands-off-blocked.
+ */
+export declare function probeMultimodalContent(messages: Array<{
+    role?: string;
+    content?: unknown;
+}> | undefined): void;

package/dist/src/lib/probes.js

@@ -0,0 +1,96 @@
+/**
+ * src/lib/probes.ts — Phase-0 empirical probe instrumentation (planning P0-A/B/C).
+ *
+ * OBSERVE-ONLY. Gated by `CC_OPENCLAW_PROBE=1` so it is completely silent — zero
+ * behavior change, no log output — in normal operation. The operator (A1)
+ * enables it for a single probe session, exercises the relevant Telegram
+ * interaction, then greps stderr for the `[cc-openclaw/probe]` markers. The
+ * runbook (PROBES-RUNBOOK in the planning dir) has the exact steps + how to read
+ * the results.
+ *
+ * These resolve the load-bearing seams that CANNOT be read from source because
+ * they depend on OpenClaw gateway runtime behavior:
+ *   P0-A: does `enqueueNextTurnInjection` trigger a run, or only stage context
+ *         for the next user message? (decides feature #1 Approve + #3 /send)
+ *   P0-B: does an `ExitPlanMode` tool_use ever fire on the bypassPermissions
+ *         Telegram path? (decides feature #1's trigger)
+ *   P0-C: does a Telegram photo reach the plugin as an image block — at
+ *         before_dispatch and/or in the openai-compat request body (where
+ *         message-extractor strips non-text parts) — or is it gateway-stripped?
+ *         (decides whether feature #2 is plugin-side feasible at all)
+ */
+const TAG = '[cc-openclaw/probe]';
+/** Read on every call so the operator can flip it without restarting. */
+function probeOn() {
+    return process.env.CC_OPENCLAW_PROBE === '1';
+}
+function emit(line) {
+    // stderr so PM2 captures it regardless of stdout-only filtering.
+    process.stderr.write(`${TAG} ${line} ts=${Date.now()}\n`);
+}
+/**
+ * P0-A — log each `enqueueNextTurnInjection` call site. The operator correlates
+ * this with whether a reply arrives in Telegram WITHOUT typing a follow-up
+ * message: if it does, injection triggers a run; if not, it only stages context.
+ */
+export function probeInjectionEnqueued(sessionKey, source) {
+    if (!probeOn())
+        return;
+    emit(`P0-A injection-enqueued source=${source} sessionKey=${sessionKey}`);
+}
+/**
+ * P0-B — log when a tool_use is `ExitPlanMode` (and any other tool name, for
+ * context). Looks across the known event field paths, mirroring
+ * inbound-handler.extractToolUse so it works whatever shape the gateway uses.
+ */
+export function probeToolUse(ev) {
+    if (!probeOn() || !ev)
+        return;
+    const tool = ev.tool;
+    const name = ev.toolName ??
+        tool?.['name'] ??
+        ev.name;
+    if (name === 'ExitPlanMode')
+        emit('P0-B ExitPlanMode-fired');
+    else if (name)
+        emit(`P0-B tool_use name=${name}`);
+}
+/**
+ * P0-C (inbound surface) — dump the before_dispatch event, flagging whether it
+ * carries any media field, so the operator sees whether photo/document surface
+ * to the plugin at all.
+ */
+export function probeInboundShape(event) {
+    if (!probeOn())
+        return;
+    try {
+        const ev = event;
+        const msg = ev?.raw?.message;
+        const hasMedia = !!(msg && (msg.photo || msg.document || msg.video || msg.voice || msg.audio || msg.sticker));
+        const dump = JSON.stringify(event, (_k, v) => (typeof v === 'function' ? '[fn]' : v));
+        emit(`P0-C before_dispatch hasMedia=${hasMedia} shape=${dump.slice(0, 1200)}`);
+    }
+    catch (err) {
+        emit(`P0-C inbound dump failed: ${err.message}`);
+    }
+}
+/**
+ * P0-C (openai-compat body) — the PRECISE probe. Does an image block survive to
+ * the request body, where `message-extractor.ts` strips non-text parts? Logs
+ * each non-text content-part type. If image parts appear here, feature #2 is
+ * feasible plugin-side (preserve them through extractUserMessage); if nothing
+ * non-text ever appears, the image is gateway-stripped upstream → hands-off-blocked.
+ */
+export function probeMultimodalContent(messages) {
+    if (!probeOn() || !messages)
+        return;
+    for (const m of messages) {
+        if (!Array.isArray(m.content))
+            continue;
+        const parts = m.content;
+        const nonText = parts.filter((p) => p && p.type && p.type !== 'text').map((p) => p.type);
+        if (nonText.length > 0) {
+            emit(`P0-C openai-body role=${m.role ?? '?'} nonTextParts=${nonText.join(',')}`);
+        }
+    }
+}

package/dist/src/lib/telegram-bot-api.d.ts

@@ -87,14 +87,60 @@ export interface TelegramApiResponse {
  */
 export declare function telegramApi(method: string, params: Record<string, unknown>): Promise<TelegramApiResponse>;
 /**
- * sendMessage with MarkdownV2 first + plain-text fallback. The fallback
- * is the v0.20.1 fix: prior implementation stripped punctuation on
- * MarkdownV2 parse errors; current behaviour retries with parse_mode
- * omitted so all content survives.
+ * v0.27.4 M6 — CLI-parity gap #8: split a message that exceeds Telegram's 4096
+ * char cap into ≤max-char chunks so long cc-openclaw-originated content sends as
+ * sequential messages instead of being rejected outright. Splits on newline
+ * boundaries (never mid-line) so HTML constructs mostly stay intact; a single
+ * line longer than max is hard-split. Returns [text] unchanged when ≤max (the
+ * common path — no behavior change for normal messages).
+ *
+ * Scope note: this covers cc-openclaw's OWN sends (slash/error responses). The
+ * live card is one edited message (truncated by design) and the model's final
+ * answer is delivered by the OpenClaw gateway — neither flows through here.
+ */
+export declare function splitForTelegram(text: string, max?: number): string[];
+/**
+ * sendMessage with HTML parse_mode first + plain-text fallback. The fallback
+ * is the v0.20.1 fix: prior implementation stripped punctuation on parse
+ * errors; current behaviour retries with parse_mode omitted so all content
+ * survives. (v0.27.0 switched the live mirror MarkdownV2 → HTML; v0.27.3
+ * converted the last MarkdownV2 emitter, error-formatter, so the whole
+ * Telegram surface is now one HTML render path.) v0.27.4 M6 — auto-chunks
+ * over-cap text and the plain fallback now strips HTML (was: re-sent raw tags).
  */
 export declare function sendTg(chatId: string | number, text: string, threadId?: string | number, replyMarkup?: unknown, replyToMessageId?: number | null): Promise<TelegramApiResponse>;
 /**
- * editMessageText with MarkdownV2-first + 429 retry-after handling +
- * plain-text fallback.
+ * editMessageText with HTML parse_mode + 429 retry-after handling +
+ * plain-text fallback (v0.27.3 stripHtml fallback on rejection).
  */
 export declare function editTg(chatId: string | number, messageId: number, text: string, replyMarkup?: unknown): Promise<TelegramApiResponse>;
+export interface SendDocumentOptions {
+    caption?: string;
+    parseMode?: 'HTML' | 'MarkdownV2';
+    threadId?: string | number;
+    replyMarkup?: unknown;
+}
+/**
+ * Build a multipart/form-data body for sendDocument. PURE — no I/O — so the
+ * encoding (the R-3 risk) is unit-testable without a network round-trip.
+ *
+ * The document is sent as an inline InputFile (Content-Type text/markdown). The
+ * boundary MUST NOT appear in any field value or the file content; callers use a
+ * random 16-byte boundary (sendDocumentTg) so collision is astronomically
+ * unlikely against Markdown plan bodies.
+ */
+export declare function buildDocumentMultipart(opts: {
+    boundary: string;
+    chatId: string | number;
+    filename: string;
+    content: string;
+    caption?: string;
+    parseMode?: 'HTML' | 'MarkdownV2';
+    threadId?: string | number;
+    replyMarkup?: unknown;
+}): Buffer;
+/**
+ * Upload a text document (e.g. a plan .md) to a chat via sendDocument. Returns
+ * the API response, or {ok:false} on network/encoding failure (never throws).
+ */
+export declare function sendDocumentTg(chatId: string | number, filename: string, content: string, opts?: SendDocumentOptions): Promise<TelegramApiResponse>;