@a1hvdy/cc-openclaw 0.27.0 → 0.27.2

package/dist/src/channels/telegram-mirror/askuser.js

@@ -23,6 +23,7 @@
 import { CallbackMap } from './callback-mapping.js';
 import { sendTg, editTg, telegramApi } from '../../lib/telegram-bot-api.js';
 import { escapeHtml } from '../../lib/html-render.js';
+import { probeInjectionEnqueued } from '../../lib/probes.js';
 /** Namespace prefix for callback_data so api.registerInteractiveHandler routes
  *  taps here. Matched at the first ':' by the gateway (must be [A-Za-z0-9._-]+). */
 export const ASKUSER_NS = 'ccmirror';
@@ -165,6 +166,7 @@ function injectAnswer(api, ctx, text) {
         return;
     }
     try {
+        probeInjectionEnqueued(sessionKey, 'askuser'); // P0-A (observe-only, gated)
         api.enqueueNextTurnInjection({
             sessionKey,
             text: `[User answered the AskUserQuestion]: ${text}`,

package/dist/src/channels/telegram-mirror/commands.js

@@ -98,17 +98,21 @@ export function handleNew(ctx) {
         };
     }
     const existing = getBySlug(slug);
-    // Session-name comes from the engine; M4 stores a placeholder that M5+ overwrites.
+    // Session-name comes from the engine when a real turn fronts this slug; until
+    // then we store a placeholder. The registry IS the real state that /sessions
+    // and /status read — so the confirmation reflects the actual registry count
+    // (planning D-5/D-2), not a false "engine wire-up lands in M5" promise.
     const sessionName = existing?.sessionName ?? `pending-${slug}-${Date.now()}`;
     register(slug, sessionName);
+    const total = list().length;
     return {
         actions: [
             {
                 type: 'sendMessage',
                 chat_id: ctx.chatId,
                 text: existing
-                    ? `Session "${slug}" already registered — fronted.`
-                    : `Session "${slug}" registered. Engine wire-up lands in M5.`,
+                    ? `Session "${slug}" already registered (${total} total). Open it from /sessions.`
+                    : `Session "${slug}" registered (${total} total). Open it from /sessions.`,
             },
         ],
     };
@@ -128,13 +132,14 @@ export function handleStop(ctx) {
         };
     }
     const removed = unregister(slug);
+    const remaining = list().length;
     return {
         actions: [
             {
                 type: 'sendMessage',
                 chat_id: ctx.chatId,
                 text: removed
-                    ? `Session "${slug}" stopped.`
+                    ? `Session "${slug}" stopped (${remaining} remaining).`
                     : `No registered session named "${slug}".`,
             },
         ],
@@ -166,16 +171,17 @@ export function handleStatus(ctx) {
 }
 // ── /compact ─────────────────────────────────────────────────────────────
 export function handleCompact(ctx) {
-    // M4: surface the intent. Actual context-compaction wiring runs through
-    // the cc-handler module (existing /cc compact path) — bridging the
-    // mirror to that handler lands in M5 alongside the rest of the engine
-    // integration. Without the bridge, the user sees a clear "queued" state.
+    // D-6 (planning): honest stub. The Telegram bridge has no session-control
+    // primitive to trigger context compaction on the running session — the only
+    // plugin levers are enqueueNextTurnInjection (text, next-turn only) and
+    // registerInteractiveHandler. So /compact is CLI-only until/unless OpenClaw
+    // exposes a control primitive. Claiming "queued" would be a lie (it never runs).
     return {
         actions: [
             {
                 type: 'sendMessage',
                 chat_id: ctx.chatId,
-                text: '⏳ Compact queued — engine wire-up lands in M5.',
+                text: "⚠️ /compact is CLI-only — the Telegram bridge can't trigger context compaction (no session-control primitive). Run it from Claude Code directly.",
             },
         ],
     };
@@ -212,14 +218,15 @@ export function handleCost(ctx) {
 }
 // ── /rewind ──────────────────────────────────────────────────────────────
 export function handleRewind(ctx) {
-    // M4: queued — actual rewind walks the cc-handler resume path (deferred
-    // to M5 with the rest of engine bridging).
+    // D-6 (planning): honest stub — same rationale as /compact. Rewinding a
+    // running session needs a session-control primitive the plugin can't reach;
+    // it's CLI-only. "Queued" would never actually run, so we say so plainly.
     return {
         actions: [
             {
                 type: 'sendMessage',
                 chat_id: ctx.chatId,
-                text: '⏪ Rewind queued — engine wire-up lands in M5.',
+                text: "⚠️ /rewind is CLI-only — the Telegram bridge can't rewind a session (no session-control primitive). Run it from Claude Code directly.",
             },
         ],
     };

package/dist/src/channels/telegram-mirror/inbound-handler.d.ts

@@ -22,9 +22,14 @@
  * Single shared CallbackMap + ComposeBuffer per process so callback
  * resolution and compose state survive across handler invocations.
  */
+import { type TelegramAction } from './commands.js';
 import { CallbackMap } from './callback-mapping.js';
 import { ComposeBuffer } from './compose-buffer.js';
 import { type InteractiveCtx, type InjectApi } from './askuser.js';
+interface InboundLogger {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+}
 export interface InboundHandlerApi {
     on(event: string, handler: (...args: unknown[]) => unknown | Promise<unknown>): void;
     logger?: {
@@ -50,6 +55,19 @@ export interface HandlerState {
     composeBuffer: ComposeBuffer;
 }
 export declare function createHandlerState(): HandlerState;
+/**
+ * Forward a single TelegramAction to the actual Telegram API. Returns
+ * the API response (or {ok:false} on failure). Pure I/O — no state
+ * mutation. Exported for unit testing (planning M-B/B2).
+ *
+ * planning M-B/B2 (D-3): the `sendDocument` branch is now wired to the
+ * multipart `sendDocumentTg` helper (was a no-op warn). NOTE: the PRODUCER of
+ * sendDocument actions — ExitPlanMode detection → buildPlanAttachment — is
+ * milestone M-B/B3, deferred pending probe P0-B. Until B3 lands this branch is
+ * dormant forwarding infrastructure, not yet a user-reachable feature.
+ */
+export declare function forwardAction(action: TelegramAction, threadId: number | undefined, logger: InboundLogger): Promise<void>;
 /** Test-only — reset module-level dispatch + card state. */
 export declare function _resetSubscriptionForTests(): void;
 export declare function registerInboundHandler(api: InboundHandlerApi, state?: HandlerState): HandlerState;
+export {};

package/dist/src/channels/telegram-mirror/inbound-handler.js

@@ -23,13 +23,14 @@
  * resolution and compose state survive across handler invocations.
  */
 import { dispatchCommand, parseSlash, COMMAND_HANDLERS } from './commands.js';
-import { sendTg, editTg } from '../../lib/telegram-bot-api.js';
+import { sendTg, editTg, sendDocumentTg } from '../../lib/telegram-bot-api.js';
 import { CallbackMap } from './callback-mapping.js';
 import { ComposeBuffer } from './compose-buffer.js';
 import { TurnStateMachine } from './state-machine.js';
 import { renderTurn } from './card-renderer.js';
 import { cardState as _cardState, cardStateDebug } from './card-state.js';
 import { handleTap, handleTapData, isAskUserCallback, rememberSessionKey, ASKUSER_NS, } from './askuser.js';
+import { probeInboundShape, probeToolUse } from '../../lib/probes.js';
 const PLUGIN_TAG = '[cc-openclaw/telegram-mirror/inbound]';
 // v0.26.3 M5 — register the AskUserQuestion interactive tap handler exactly
 // once per process (registerInboundHandler runs on every register() call).
@@ -76,12 +77,15 @@ const MIRROR_COMMANDS = new Set(Object.keys(COMMAND_HANDLERS));
 /**
  * Forward a single TelegramAction to the actual Telegram API. Returns
  * the API response (or {ok:false} on failure). Pure I/O — no state
- * mutation.
+ * mutation. Exported for unit testing (planning M-B/B2).
  *
- * editMessageText and sendDocument variants land in v0.25.2 when the
- * render pipeline and plan-attachment dispatch wire up.
+ * planning M-B/B2 (D-3): the `sendDocument` branch is now wired to the
+ * multipart `sendDocumentTg` helper (was a no-op warn). NOTE: the PRODUCER of
+ * sendDocument actions — ExitPlanMode detection → buildPlanAttachment — is
+ * milestone M-B/B3, deferred pending probe P0-B. Until B3 lands this branch is
+ * dormant forwarding infrastructure, not yet a user-reachable feature.
  */
-async function forwardAction(action, threadId, logger) {
+export async function forwardAction(action, threadId, logger) {
     try {
         if (action.type === 'sendMessage') {
             await sendTg(String(action.chat_id), action.text, threadId !== undefined ? String(threadId) : undefined, action.reply_markup);
@@ -91,8 +95,15 @@ async function forwardAction(action, threadId, logger) {
             await editTg(String(action.chat_id), action.message_id, action.text, action.reply_markup);
             return;
         }
-        // sendDocument: v0.25.2 — plan-mode attachment wire-up.
-        logger.warn(`${PLUGIN_TAG} action type "${action.type}" not yet forwarded (deferred to v0.25.2)`);
+        if (action.type === 'sendDocument') {
+            await sendDocumentTg(String(action.chat_id), action.filename, action.content, {
+                caption: action.caption,
+                replyMarkup: action.reply_markup,
+                threadId,
+            });
+            return;
+        }
+        logger.warn(`${PLUGIN_TAG} action type "${action.type}" not forwarded (no handler)`);
     }
     catch (err) {
         logger.warn(`${PLUGIN_TAG} forwardAction failed: ${err.message}`);
@@ -205,6 +216,7 @@ export function registerInboundHandler(api, state = createHandlerState()) {
         // Per-event-id dedup at dispatch layer (purpose=slash).
         if (_seenOrMark('slash', _eventId(event)))
             return undefined;
+        probeInboundShape(event); // P0-C inbound surface (observe-only, gated)
         // Extract text from the canonical (2026.5.x) `event.content` field;
         // fall back to legacy nested paths if a future gateway version reverts.
         const text = (typeof event.content === 'string' ? event.content : undefined) ??
@@ -413,6 +425,7 @@ export function registerInboundHandler(api, state = createHandlerState()) {
         const event = args[0];
         dumpShapeOnce('before_tool_call', event);
         const ev = event;
+        probeToolUse(ev); // P0-B ExitPlanMode detection (observe-only, gated)
         const evId = _eventId({ sessionKey: (ev?.sessionKey ?? ev?.ctx?.['SessionKey']), timestamp: ev?.timestamp, content: `tool_use:${String((ev?.id ?? ev?.tool_use_id ?? ''))}` });
         if (_seenOrMark('tool_use', evId))
             return undefined;

package/dist/src/engines/base-oneshot-session.js

@@ -102,6 +102,8 @@ export class BaseOneShotSession extends EventEmitter {
             isReady: this._isReady,
             startTime: this._startTime,
             lastActivity: this._stats.lastActivity,
+            // v0.27.x — oneshot engine doesn't separate progress; mirror lastActivity.
+            lastProgressAt: this._stats.lastActivity,
             contextPercent: 0,
             retries: 0,
             sessionId: this.sessionId,

package/dist/src/engines/persistent-custom-session.js

@@ -797,6 +797,9 @@ export class PersistentCustomSession extends EventEmitter {
             isReady: this._isReady,
             startTime: this._startTime,
             lastActivity: this._stats.lastActivity,
+            // v0.27.x — custom engine doesn't separate progress from activity; mirror
+            // lastActivity so the shared watchdog behaves exactly as before for it.
+            lastProgressAt: this._stats.lastActivity,
             contextPercent: this.engineConfig.persistent
                 ? Math.min(100, Math.round(((this._stats.tokensIn + this._stats.tokensOut) / ctxWindow) * 100))
                 : 0,

package/dist/src/engines/persistent-session.d.ts

@@ -25,6 +25,8 @@ interface InternalStats {
     costUsd: number;
     startTime: string | null;
     lastActivity: string | null;
+    /** v0.27.x — last PROGRESS event ts (excludes api_retry); watchdog keys off it. */
+    lastProgressAt: string | null;
     history: Array<{
         time: string;
         type: string;

package/dist/src/engines/persistent-session.js

@@ -58,6 +58,7 @@ export class PersistentClaudeSession extends EventEmitter {
             costUsd: 0,
             startTime: null,
             lastActivity: null,
+            lastProgressAt: null,
             history: [],
             retries: 0,
             lastRetryError: undefined,
@@ -346,6 +347,16 @@ export class PersistentClaudeSession extends EventEmitter {
     _handleEvent(event) {
         const type = event.type;
         this.stats.lastActivity = new Date().toISOString();
+        // v0.27.x — progress signal for the stalled-session watchdog. Every event
+        // EXCEPT `system/api_retry` counts as progress. api_retry fires during an
+        // API retry-storm WITHOUT producing output; counting it as activity (as
+        // lastActivity does) defeated the watchdog — it never saw 180s of
+        // no-progress, so a stalled/retrying model call hung to the 900s envelope
+        // (the gateway's `recovery=none lastProgressAge=353s`). Keying the watchdog
+        // off lastProgressAt fast-fails it at the threshold instead.
+        const isApiRetry = type === 'system' && event.subtype === 'api_retry';
+        if (!isApiRetry)
+            this.stats.lastProgressAt = this.stats.lastActivity;
         // Track history (keep last 100)
         this.stats.history.push({ time: this.stats.lastActivity, type, event });
         if (this.stats.history.length > MAX_HISTORY_ITEMS)
@@ -769,6 +780,7 @@ export class PersistentClaudeSession extends EventEmitter {
             isReady: this._isReady,
             startTime: this.stats.startTime,
             lastActivity: this.stats.lastActivity,
+            lastProgressAt: this.stats.lastProgressAt,
             // v0.6.0: contextPercent now reflects ACTUAL per-turn context occupancy
             // (input + cache-read tokens from the last `result` event), not lifetime
             // cumulative tokens. Pre-fix it saturated at 100% by turn 3 of any

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

@@ -98,3 +98,33 @@ export declare function sendTg(chatId: string | number, text: string, threadId?:
  * plain-text fallback.
  */
 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>;

package/dist/src/lib/telegram-bot-api.js

@@ -27,6 +27,7 @@ import { request as httpsRequest } from 'node:https';
 import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
 export const OPENCLAW_CONFIG_PATH = join(homedir(), '.openclaw', 'openclaw.json');
 const PLUGIN_TAG = '[cc-openclaw/telegram-bot-api]';
 // ─── Bot token state ───────────────────────────────────────────────────────
@@ -201,3 +202,89 @@ export async function editTg(chatId, messageId, text, replyMarkup) {
         return { ok: false };
     }
 }
+/**
+ * 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 function buildDocumentMultipart(opts) {
+    const { boundary } = opts;
+    const parts = [];
+    const textField = (name, value) => {
+        parts.push(Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="${name}"\r\n\r\n${value}\r\n`, 'utf8'));
+    };
+    textField('chat_id', String(opts.chatId));
+    if (opts.caption)
+        textField('caption', opts.caption);
+    if (opts.parseMode)
+        textField('parse_mode', opts.parseMode);
+    if (opts.threadId !== undefined)
+        textField('message_thread_id', String(opts.threadId));
+    if (opts.replyMarkup)
+        textField('reply_markup', JSON.stringify(opts.replyMarkup));
+    // The document file part — header, then raw content, then CRLF.
+    parts.push(Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="document"; filename="${opts.filename}"\r\nContent-Type: text/markdown\r\n\r\n`, 'utf8'));
+    parts.push(Buffer.from(opts.content, 'utf8'));
+    parts.push(Buffer.from(`\r\n--${boundary}--\r\n`, 'utf8'));
+    return Buffer.concat(parts);
+}
+/** Low-level multipart POST. Mirrors `telegramApi` but sets a multipart
+ *  Content-Type + a Buffer body. */
+function telegramApiMultipart(method, boundary, body) {
+    return new Promise((resolve, reject) => {
+        const options = {
+            hostname: 'api.telegram.org',
+            path: `/bot${_botToken}/${method}`,
+            method: 'POST',
+            headers: {
+                'Content-Type': `multipart/form-data; boundary=${boundary}`,
+                'Content-Length': body.length,
+            },
+        };
+        const req = httpsRequest(options, (res) => {
+            let data = '';
+            res.on('data', (chunk) => (data += chunk));
+            res.on('end', () => {
+                try {
+                    resolve(JSON.parse(data));
+                }
+                catch {
+                    resolve({ ok: false, description: 'JSON parse error' });
+                }
+            });
+        });
+        req.on('error', (err) => reject(err));
+        req.setTimeout(15_000, () => {
+            req.destroy(new Error('Telegram API timeout'));
+        });
+        req.write(body);
+        req.end();
+    });
+}
+/**
+ * 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 async function sendDocumentTg(chatId, filename, content, opts = {}) {
+    try {
+        const boundary = `----ccopenclaw${randomBytes(16).toString('hex')}`;
+        const body = buildDocumentMultipart({
+            boundary,
+            chatId,
+            filename,
+            content,
+            caption: opts.caption,
+            parseMode: opts.parseMode,
+            threadId: opts.threadId,
+            replyMarkup: opts.replyMarkup,
+        });
+        return await telegramApiMultipart('sendDocument', boundary, body);
+    }
+    catch {
+        return { ok: false };
+    }
+}

package/dist/src/openai-compat/message-extractor.js

@@ -32,6 +32,7 @@ import { serializeToolResults, serializeToolResultsAsBlocks, } from './tool-resu
 import { isToolStreamMode } from './mode-flags.js';
 import { detectSlashCommand, maybeInlineSkill } from './skill-resolver.js';
 import { isOpenaiCompatNewConvoHeuristic } from '../lib/config.js';
+import { probeMultimodalContent } from '../lib/probes.js';
 /**
  * Extract the relevant parts from an OpenAI messages array.
  *
@@ -59,6 +60,9 @@ export function extractUserMessage(messages, headers) {
     if (!messages || messages.length === 0) {
         throw new Error('messages array is empty');
     }
+    // P0-C openai-body probe (observe-only, gated): does an image block survive to
+    // the request body before textOf() below strips non-text parts? See lib/probes.ts.
+    probeMultimodalContent(messages);
     // Normalize content from any message: OpenAI API allows content as a string
     // OR an array of content parts (e.g. multimodal messages with text + images).
     // We need a string for the CLI, so arrays are joined.

package/dist/src/session/watchdogs.d.ts

@@ -22,9 +22,11 @@
 export interface WatchdogManagedSession {
     session: {
         isBusy: boolean;
-        /** Returns at least { lastActivity }. Other stats fields are ignored. */
+        /** Returns at least { lastActivity, lastProgressAt }. The watchdog prefers
+         *  lastProgressAt (excludes api_retry pings); other stats fields ignored. */
         getStats(): {
             lastActivity?: string | null | undefined;
+            lastProgressAt?: string | null | undefined;
         };
         stop(): void;
     };

package/dist/src/session/watchdogs.js

@@ -46,18 +46,20 @@ export function watchStalledSessions(opts) {
         if (!managed.session.isBusy)
             continue;
         const stats = managed.session.getStats();
-        const lastActivityIso = stats.lastActivity;
-        const lastEventMs = lastActivityIso
-            ? new Date(lastActivityIso).getTime()
-            : managed.lastActivity;
+        // v0.27.x — prefer the PROGRESS timestamp (real output: text/tool/result),
+        // which excludes `system/api_retry` pings. Keying off lastActivity let a
+        // retry-storm reset the clock forever so the watchdog never fired. Fall back
+        // to lastActivity, then the SessionManager wall-clock.
+        const progressIso = stats.lastProgressAt ?? stats.lastActivity;
+        const lastEventMs = progressIso ? new Date(progressIso).getTime() : managed.lastActivity;
         const ageMs = now - lastEventMs;
         if (ageMs <= thresholdMs)
             continue;
-        opts.logger.warn(`[watchdog] killing stalled session ${name} (busy, no subprocess event for ${Math.round(ageMs / 1000)}s, threshold=${Math.round(thresholdMs / 1000)}s)`);
+        opts.logger.warn(`[watchdog] killing stalled session ${name} (busy, no progress for ${Math.round(ageMs / 1000)}s, threshold=${Math.round(thresholdMs / 1000)}s)`);
         try {
             trajectory.emit('session_stalled_killed', {
                 ageMs,
-                lastActivity: lastActivityIso,
+                lastProgressAt: progressIso,
                 thresholdMs,
                 model: managed.config.model,
                 cwd: managed.cwd,

package/dist/src/types.d.ts

@@ -184,6 +184,12 @@ export interface SessionStats {
     isReady: boolean;
     startTime: string | null;
     lastActivity: string | null;
+    /** v0.27.x — wall-clock ISO of the last PROGRESS event (text / tool_use /
+     *  tool_result / thinking / result / init) — i.e. the subprocess produced
+     *  real output. Distinct from lastActivity, which also moves on non-progress
+     *  events like `system/api_retry`. The stalled-session watchdog keys off this
+     *  so an API retry-storm (no output) is fast-failed instead of looking busy. */
+    lastProgressAt: string | null;
     /**
      * Approximate context window utilization (0-100).
      * Estimated as (tokensIn + tokensOut) / 200,000 * 100.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a1hvdy/cc-openclaw",
-  "version": "0.27.0",
+  "version": "0.27.2",
   "description": "A1xAI's Anthropic CLI bridge plugin for OpenClaw",
   "author": "@a1cy",
   "license": "MIT",