@a1hvdy/cc-openclaw 0.29.0 → 0.31.0

package/dist/src/channels/telegram-mirror/card-renderer.js

@@ -30,8 +30,12 @@ function basename(p) {
  * Glyph picked per tool-call status. Mirrors terminal "running / done /
  * errored" iconography that A1 already reads in the live Claude Code TUI.
  */
-function toolGlyph(tc) {
-    if (tc.isError)
+function toolGlyph(tc, suppressToolErrors = false) {
+    // OpenClaw 2026.5.20 #81561 — when the user set messages.suppressToolErrors,
+    // an errored-but-completed tool reads as a normal "✓" rather than the "✗"
+    // error glyph. tc.result is set for an errored tool (it carries the error
+    // body), so the completed-✓ branch below picks it up once "✗" is skipped.
+    if (tc.isError && !suppressToolErrors)
         return '✗';
     if (tc.result !== undefined)
         return '✓';
@@ -260,8 +264,8 @@ export function toolIcon(name) {
         return '🔌';
     return '🔹';
 }
-export function renderToolLine(tc) {
-    const glyph = toolGlyph(tc);
+export function renderToolLine(tc, suppressToolErrors = false) {
+    const glyph = toolGlyph(tc, suppressToolErrors);
     const icon = toolIcon(tc.name);
     // Status glyph + emoji are HTML-safe; the tool name is HTML-escaped and the
     // input detail rides in a <code> span (v0.27.0 M1 HTML styling).
@@ -384,7 +388,7 @@ export function renderTurn(turn, meta) {
         let acc = 0;
         for (let i = turn.toolCalls.length - 1; i >= 0; i--) {
             const tc = turn.toolCalls[i];
-            const line = renderToolLine(tc);
+            const line = renderToolLine(tc, meta?.suppressToolErrors);
             // v0.27.4 M2 — for Edit/Write/MultiEdit show a diff (from input) instead of
             // the "File updated" result; other tools keep the result preview.
             const diffText = toolDiffBlock(tc);

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

@@ -44,14 +44,6 @@ export function parseSlash(text) {
     return { cmd: cmd.toLowerCase(), args: tokens.slice(1) };
 }
 // ── /sessions ────────────────────────────────────────────────────────────
-function enrichRows(entries, stateLookup) {
-    return entries.map((e) => ({
-        slug: e.slug,
-        sessionName: e.sessionName,
-        state: stateLookup(e.slug),
-        lastUsedAt: e.lastUsedAt,
-    }));
-}
 /**
  * v0.28.0 — `/sessions` is now a `claude -r`-style picker over the REAL Claude
  * Code sessions. It mirrors `~/.claude/projects/**` (the store every `claude`

package/dist/src/channels/telegram-mirror/status-line.js

@@ -4,7 +4,7 @@
  * Builds the Claude-Code-CLI-style status line that sits at the top of the
  * Telegram live-mirror card, e.g.:
  *
- *   [Opus 4.7] · CC 2.1.145 · ⏱ 2h13m · 🔧 3 · bypass
+ *   [Opus 4.7] · CC 2.1.145 · GW 2026.5.20 · ⏱ 2h13m · 🔧 3 · bypass
  *
  * STRICT no-fake-data rule (per the v0.26.2 brief): every segment is rendered
  * ONLY when its value is genuinely available. Missing model / version / etc.
@@ -40,6 +40,33 @@ export function getCcVersion() {
 export function _resetCcVersionForTests() {
     _ccVersion = undefined;
 }
+// ── Gateway version (cached; resolved at most once per process) ──────────────
+// `openclaw --version` prints e.g. "OpenClaw 2026.5.20 (e510042)". Mirrors the
+// getCcVersion() resolve-once-and-cache contract (including a failed lookup as
+// `null`). Surfaced on the status line as "GW <ver>" so the card shows which
+// OpenClaw core is actually running alongside the CC CLI version.
+let _gatewayVersion;
+export function getGatewayVersion() {
+    if (_gatewayVersion !== undefined)
+        return _gatewayVersion;
+    try {
+        const out = execFileSync('openclaw', ['--version'], {
+            timeout: 5_000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            encoding: 'utf8',
+        });
+        const m = /(\d+\.\d+\.\d+)/.exec(out);
+        _gatewayVersion = m ? m[1] : null;
+    }
+    catch {
+        _gatewayVersion = null;
+    }
+    return _gatewayVersion;
+}
+/** Test-only — reset the cached gateway version. */
+export function _resetGatewayVersionForTests() {
+    _gatewayVersion = undefined;
+}
 // ── Model id → short label ─────────────────────────────────────────────────
 // "claude-opus-4-7" → "Opus 4.7"; "claude-sonnet-4-6" → "Sonnet 4.6". Unknown
 // shapes pass through unchanged (still real data, just not prettified).
@@ -69,7 +96,7 @@ export function fmtElapsed(ms) {
 /**
  * Render the status line for a turn. Returns `undefined` when NOTHING is
  * available to show (so callers omit the line entirely). Segments, in order:
- *   [model] · CC <ver> · ⏱ <elapsed> · 🔧 <toolCount> · bypass
+ *   [model] · CC <ver> · GW <ver> · ⏱ <elapsed> · 🔧 <toolCount> · bypass
  * Every segment is conditional on real data.
  */
 export function renderStatusLine(turn, meta, now = Date.now()) {
@@ -80,6 +107,9 @@ export function renderStatusLine(turn, meta, now = Date.now()) {
     const ver = getCcVersion();
     if (ver)
         segs.push(`CC ${ver}`);
+    const gwVer = getGatewayVersion();
+    if (gwVer)
+        segs.push(`GW ${gwVer}`);
     // Turn elapsed is always real (Turn.startedAt is set at card creation). Use
     // endedAt once the turn is done so the finalized card shows total duration.
     const elapsedMs = (turn.endedAt ?? now) - turn.startedAt;

package/dist/src/constants.js

@@ -28,14 +28,28 @@ export const SESSION_READY_FALLBACK_MS = 2_000;
  *
  *  v0.20.0: env-overridable via `CC_OPENCLAW_TURN_TIMEOUT_MS` (see
  *  src/lib/env-overrides.ts). Setting `=0` disables the per-turn timer
- *  entirely, matching direct-CLI behavior on long tool turns. */
+ *  entirely, matching direct-CLI behavior on long tool turns.
+ *
+ *  OpenClaw 2026.5.20 (#83979): core now HONORS
+ *  `models.providers.cc-openclaw.timeoutSeconds` above its idle watchdog —
+ *  previously the outer request was killed at ~120s regardless of that value,
+ *  so this 900_000 alignment was a workaround fighting a hidden ceiling. It is
+ *  now a genuine, end-to-end envelope. Keep it aligned to timeoutSeconds (do
+ *  NOT reduce below the configured outer bound). */
 export const TURN_TIMEOUT_MS = 900_000;
 /** Runtime watchdog threshold for "stuck" sessions. If a session is
  *  `isBusy === true` AND its stats.lastActivity hasn't moved in this many
  *  ms, the SessionManager watchdog aborts + disposes the session. Mirrors
  *  the boot-time orphan reaper in gateway-pm2-wrapper.sh:53-60, but runs
  *  continuously on a setInterval. Env-overridable via
- *  CC_OPENCLAW_STALLED_KILL_MS. v0.10.0. */
+ *  CC_OPENCLAW_STALLED_KILL_MS. v0.10.0.
+ *
+ *  NOTE (OpenClaw 2026.5.20 #83979): this is ORTHOGONAL to core's now-honored
+ *  provider idle watchdog — that bounds first-token / inter-token waits on the
+ *  request; this bounds a wedged Claude SUBPROCESS that emits no output at all.
+ *  The core fix does NOT make this redundant. Keep it. Raise (don't remove) via
+ *  CC_OPENCLAW_STALLED_KILL_MS only if legitimately long no-output tool runs
+ *  (e.g. a long Bash) trip it. */
 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;

package/dist/src/lib/cache-parity-decide.js

@@ -0,0 +1,54 @@
+/**
+ * Content-addressed cache-parity decision (v0.30.0).
+ *
+ * Problem (diagnosed 2026-05-23 from the live sysprompt-cost telemetry):
+ * cc-openclaw's cache-parity registry is keyed by sessionKey. The cache HIT
+ * path strips the role:system messages so the Claude CLI subprocess reuses its
+ * already-cached `--append-system-prompt` block; a MISS inlines the full ~7K
+ * system prompt into the user message (uncached). On the live box, 70% of all
+ * cache misses were `session_unknown` — the FIRST turn of a session, where the
+ * registry has no entry yet. Telegram conversations are short (median 1 turn /
+ * session, 23 of 35 single-turn), so cold-start dominated: the hit rate stalled
+ * at ~75% vs the terminal CLI's ~95%. The dynamic-envelope churn we originally
+ * set out to fix was only ~7.5% of turns.
+ *
+ * Key observation: every Savvy session shares the *identical* system prefix
+ * (same SOUL/USER/AGENTS/TOOLS/MEMORY + harness ⇒ same sysHash). So a brand-new
+ * session whose sysHash was already seen for some *other* session is a
+ * known-good prefix — its `--append-system-prompt` will be injected at
+ * startSession from the registry entry the route patch writes this same turn,
+ * so it is SAFE to strip the redundant inline and ride the cached path on
+ * turn 1 instead of re-billing the full prompt.
+ *
+ * Safety: the "warm-hash hit" only applies when the session is NEW (not yet in
+ * the SessionManager) — that guarantees startSession runs and appends the
+ * prompt. An EXISTING session missing its registry entry (e.g. registry wiped
+ * mid-life) keeps the legacy inline path so the model never loses its system
+ * prompt. A `hash_mismatch` (entry exists, different hash = genuine mid-session
+ * churn) also stays on the inline path: the CLI's append still holds the OLD
+ * prompt, so the new one must be delivered in-band.
+ *
+ * Pure + side-effect-free so the decision is unit-testable independent of the
+ * EmbeddedServer route closure (matches the codebase's pure-helper pattern:
+ * isPersistedSessionFresh, shouldWriteThroughResumeId).
+ */
+/**
+ * Decide how the route patch should treat the system prompt this turn.
+ *
+ *  - 'hit'           → registry entry matches this session: strip role:system,
+ *                      ride the already-cached append.
+ *  - 'warm-hash-hit' → new session + known-good prefix: write the registry
+ *                      entry (so startSession appends it), strip role:system,
+ *                      ride the cached path. Closes the cold-start gap.
+ *  - 'miss'          → inline the system prompt into the user message (the safe
+ *                      legacy path): first-ever prefix, genuine churn, or an
+ *                      existing session that lost its registry entry.
+ */
+export function decideCacheParityAction(input) {
+    const { entry, sysHash, knownHash, sessionIsNew } = input;
+    if (entry && entry.hash === sysHash)
+        return 'hit';
+    if (!entry && knownHash && sessionIsNew)
+        return 'warm-hash-hit';
+    return 'miss';
+}

package/dist/src/lib/config.js

@@ -351,6 +351,46 @@ export function _resetTtsAutoModeCacheForTests() {
     _ttsAutoModeCache = null;
     _ttsAutoModeCacheChecked = false;
 }
+// ── Suppress tool errors (OpenClaw 2026.5.20 #81561) ────────────────────────
+// Reads `messages.suppressToolErrors` from `~/.openclaw/openclaw.json` once and
+// caches it. When true, the user has opted out of tool-failure noise, so the
+// Telegram live-card renders an errored-but-completed tool with its normal "✓"
+// glyph instead of the "✗" error glyph (the card-side equivalent of the core's
+// "no separate warning payloads" behavior). The TURN-level "❌ <reason>" header
+// is unaffected — that's terminal turn state, not a per-tool warning.
+//
+// Same custom-file-reader rationale as getTtsAutoMode(): openclaw.json is a
+// plugin-side decision that shouldn't reach through OpenClaw's typed runtime.
+// Tests override via the CC_OPENCLAW_SUPPRESS_TOOL_ERRORS env var.
+let _suppressToolErrorsCache = null;
+let _suppressToolErrorsCacheChecked = false;
+export function getSuppressToolErrors() {
+    // Test-time / explicit override takes precedence.
+    const envOverride = process.env.CC_OPENCLAW_SUPPRESS_TOOL_ERRORS?.trim().toLowerCase();
+    if (envOverride === '1' || envOverride === 'true' || envOverride === 'on')
+        return true;
+    if (envOverride === '0' || envOverride === 'false' || envOverride === 'off')
+        return false;
+    if (!_suppressToolErrorsCacheChecked) {
+        _suppressToolErrorsCacheChecked = true;
+        try {
+            const configPath = process.env.OPENCLAW_CONFIG_PATH || join(homedir(), '.openclaw', 'openclaw.json');
+            const raw = readFileSync(configPath, 'utf8');
+            const parsed = JSON.parse(raw);
+            _suppressToolErrorsCache = parsed.messages?.suppressToolErrors ?? null;
+        }
+        catch {
+            // File missing / unreadable / invalid JSON — fall through to false.
+            _suppressToolErrorsCache = null;
+        }
+    }
+    return _suppressToolErrorsCache === true;
+}
+/** Test-only: reset the suppress-tool-errors cache so the next call re-reads. */
+export function _resetSuppressToolErrorsCacheForTests() {
+    _suppressToolErrorsCache = null;
+    _suppressToolErrorsCacheChecked = false;
+}
 export function getClaudeBin() {
     const cfg = getConfigService();
     if (cfg)

package/dist/src/openai-compat/non-streaming-handler.js

@@ -23,7 +23,7 @@
 import { reportStatus, getToolDescription } from './status-reporter.js';
 import { parseToolCallsFromText } from './tool-calls-parser.js';
 import { formatCompletionResponse } from './response-formatter.js';
-import { getSurfaceThinkingEnabled, getTtsAutoMode, getCardAnswerMirrorEnabled } from '../lib/config.js';
+import { getSurfaceThinkingEnabled, getTtsAutoMode, getCardAnswerMirrorEnabled, getSuppressToolErrors } from '../lib/config.js';
 import { emit as emitTrajectory, emitTurnTrace } from '../lib/trajectory.js';
 import { formatError, ERROR_CODES } from '../lib/error-formatter.js';
 import { applyVoiceRecovery, _logVoiceDebug, detectVoiceIntent, hasTtsMarkers } from './voice-recovery.js';
@@ -55,7 +55,7 @@ slashCommand) {
     // cards THIS module instance sees (see handleStreaming counterpart).
     process.stderr.write(`[cc-openclaw/openai-compat] handleNonStreaming pid=${process.pid} hasTools=${hasTools} ${mirrorCardStateDebug()} session=${sessionName}\n`);
     // v0.26.2 M1+M2 — feed the CC-CLI status line (model + bypass + quota; see streaming).
-    mirrorSetCardMeta({ model, bypassPermissions: true, ...mirrorReadQuotaMeta() });
+    mirrorSetCardMeta({ model, bypassPermissions: true, suppressToolErrors: getSuppressToolErrors(), ...mirrorReadQuotaMeta() });
     // v0.14.0 turn-trace probe: capture wall-clock duration of the turn.
     const turnStartMs = Date.now();
     // v0.15.0 Slice 1: hoist userText so the catch-path probe emit can reference

package/dist/src/openai-compat/streaming-handler.js

@@ -41,7 +41,7 @@ import { formatCompletionChunk } from './response-formatter.js';
 import { isToolStreamMode } from './mode-flags.js';
 import { emit as emitTrajectory, emitTurnTrace } from '../lib/trajectory.js';
 import { formatError, ERROR_CODES } from '../lib/error-formatter.js';
-import { getSurfaceThinkingEnabled, getTtsAutoMode, getCardAnswerMirrorEnabled } from '../lib/config.js';
+import { getSurfaceThinkingEnabled, getTtsAutoMode, getCardAnswerMirrorEnabled, getSuppressToolErrors } from '../lib/config.js';
 import { applyVoiceRecovery, detectVoiceIntent, hasTtsMarkers, _logVoiceDebug } from './voice-recovery.js';
 import { pushToolUse as mirrorPushToolUse, pushToolResult as mirrorPushToolResult, pushAssistantText as mirrorPushAssistantText, pushThinking as mirrorPushThinking, finalizeActiveCards as mirrorFinalizeActiveCards, extractInsightForCard as mirrorExtractInsightForCard, failActiveCards as mirrorFailActiveCards, classifyFailure, setCardMeta as mirrorSetCardMeta, readQuotaMeta as mirrorReadQuotaMeta, } from '../channels/telegram-mirror/turn-bridge.js';
 import { cardStateDebug as mirrorCardStateDebug } from '../channels/telegram-mirror/card-state.js';
@@ -83,7 +83,7 @@ onFinalText) {
     // v0.26.2 M1+M2 — feed the CC-CLI status line. The openai-compat path always
     // runs permissionMode 'bypassPermissions' (openai-compat.ts) so we assert it.
     // Quota is read once here (real status-tee snapshot or omitted).
-    mirrorSetCardMeta({ model, bypassPermissions: true, ...mirrorReadQuotaMeta() });
+    mirrorSetCardMeta({ model, bypassPermissions: true, suppressToolErrors: getSuppressToolErrors(), ...mirrorReadQuotaMeta() });
     // #4 dual-surface seam — hoist once per turn (read off the hot delta loop).
     // Default OFF: card is the activity pane, gateway draft is the answer pane.
     const mirrorAnswerToCard = getCardAnswerMirrorEnabled();

package/dist/src/session-bootstrap/cwd-patch.js

@@ -37,6 +37,7 @@ import { defaultRegisterGuard } from '../lib/register-guard.js';
 import { isTestMode } from '../lib/test-mode.js';
 import { writePerfEvent } from '../observability/perf-telemetry.js';
 import { collapseSkillList } from '../lib/perf/skill-list-collapse.js';
+import { decideCacheParityAction } from '../lib/cache-parity-decide.js';
 import { isCacheParityTrackB, isTokenTelemetryEnabled, isSyspromptDumpEnabled, getMaxConcurrentSessions, getSessionTtlMinutes, ensureUxBridgeAllSessionsDefault, } from '../lib/config.js';
 import { VENDOR_FILES } from '../lib/vendor-paths.js';
 import { OpenClawConfigSchema, findMainAgent, getAgentPrimaryModel, getDefaultsPrimaryModel, isClaudeRoutedModel, } from '../types/upstream.js';
@@ -99,6 +100,7 @@ const METRICS = {
     systemPromptInlined: 0,
     uxMetaSeeded: 0,
     cacheParityHits: 0,
+    cacheParityWarmHashHits: 0,
     cacheParityMisses: 0,
     cacheParityRegistryWrites: 0,
     cacheParityAppendInjections: 0,
@@ -143,6 +145,24 @@ function _setSystemInlineCache(key, val) {
     }
     _systemInlineCache.set(key, val);
 }
+// ── Known sysprompt-hash set (v0.30.0 — content-addressed cache parity) ──────
+// Cross-session record of every sysHash written to the cache-parity registry
+// this process. Lets a brand-new session recognise the shared Savvy system
+// prefix and ride the cached append path on turn 1 instead of inlining the full
+// ~7K prompt — the dominant cold-start miss (see lib/cache-parity-decide.ts).
+// Bounded FIFO: distinct prefixes are few (one per build), 64 is ample headroom.
+const _knownSysHashes = new Set();
+const KNOWN_SYS_HASH_MAX = 64;
+function _rememberSysHash(hash) {
+    if (_knownSysHashes.has(hash))
+        return;
+    if (_knownSysHashes.size >= KNOWN_SYS_HASH_MAX) {
+        const oldest = _knownSysHashes.values().next().value;
+        if (oldest !== undefined)
+            _knownSysHashes.delete(oldest);
+    }
+    _knownSysHashes.add(hash);
+}
 // ── Tool dump hash guard (v0.6.0 — per-session-key cache + fast-skip) ──
 // Pre-v0.6.0: a single global `_lastToolDumpHash` thrashed when multiple
 // sessions had different tool sets. JSON.stringify + SHA1 ran on EVERY
@@ -655,11 +675,30 @@ function applyRoutePatch(EmbeddedServer) {
                         try {
                             const reg = _readCacheParityRegistry();
                             const entry = reg[sessionKey];
-                            if (entry && entry.hash === sysHash) {
+                            // sessionIsNew: no live session in the manager ⇒ startSession will
+                            // run on this request and inject appendSystemPrompt from the
+                            // registry entry we write below. That guarantee is what makes the
+                            // warm-hash strip safe (see lib/cache-parity-decide.ts). Default
+                            // to false on any access failure — conservative: an unproven
+                            // append guarantee falls back to the safe inline path.
+                            let sessionIsNew = false;
+                            try {
+                                const mgr = this.manager;
+                                sessionIsNew = !(mgr?.sessions?.has?.('openai-' + sessionKey) ?? false);
+                            }
+                            catch { /* keep sessionIsNew=false (inline fallback) */ }
+                            const action = decideCacheParityAction({
+                                entry: entry ? { hash: entry.hash } : undefined,
+                                sysHash,
+                                knownHash: _knownSysHashes.has(sysHash),
+                                sessionIsNew,
+                            });
+                            if (action === 'hit') {
                                 body.messages = messages.filter(m => m?.role !== 'system');
                                 METRICS.cacheParityHits++;
                                 METRICS.systemPromptInlined++;
                                 cacheParityHandled = true;
+                                _rememberSysHash(sysHash);
                                 writePerfEvent({
                                     event: 'cache_check',
                                     sessionKey,
@@ -668,8 +707,29 @@ function applyRoutePatch(EmbeddedServer) {
                                     sysHash,
                                 });
                             }
+                            else if (action === 'warm-hash-hit') {
+                                // Cold-start win: new session + known-good Savvy prefix. Write
+                                // the entry so startSession appends it, strip the redundant
+                                // inline, ride the cached path on turn 1.
+                                _writeCacheParityEntry(sessionKey, sysHash, sysContent);
+                                body.messages = messages.filter(m => m?.role !== 'system');
+                                METRICS.cacheParityWarmHashHits++;
+                                METRICS.cacheParityRegistryWrites++;
+                                METRICS.systemPromptInlined++;
+                                cacheParityHandled = true;
+                                _rememberSysHash(sysHash);
+                                logger.info(`${TAG} cache-parity warm-hash hit: session=${sessionKey} hash=${sysHash} sysLen=${sysContent.length} (cold-start dedup; startSession will append)`);
+                                writePerfEvent({
+                                    event: 'cache_check',
+                                    sessionKey,
+                                    outcome: 'hit',
+                                    cause: 'warm_hash',
+                                    sysHash,
+                                });
+                            }
                             else {
                                 _writeCacheParityEntry(sessionKey, sysHash, sysContent);
+                                _rememberSysHash(sysHash);
                                 METRICS.cacheParityMisses++;
                                 METRICS.cacheParityRegistryWrites++;
                                 logger.info(`${TAG} cache-parity miss: session=${sessionKey} oldHash=${entry?.hash || 'none'} newHash=${sysHash} sysLen=${sysContent.length} (registry updated; next session start will append)`);

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "@a1hvdy/cc-openclaw",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "description": "A1xAI's Anthropic CLI bridge plugin for OpenClaw",
   "author": "@a1cy",
   "license": "MIT",
   "type": "module",
   "main": "dist/src/index.js",
-  "types": "dist/src/index.d.ts",
   "homepage": "https://github.com/A1cy/cc-openclaw",
   "repository": "github:A1cy/cc-openclaw",
   "engines": {
@@ -23,6 +22,8 @@
   },
   "files": [
     "dist/",
+    "!dist/**/*.d.ts",
+    "!dist/**/*.d.ts.map",
     "configs/",
     "skills/",
     "openclaw.plugin.json",

package/dist/src/channels/adapter.d.ts

@@ -1,103 +0,0 @@
-/**
- * Channel Adapter — generic interface for delivering session UX
- * to chat channels (Telegram, Discord, Signal, etc.).
- *
- * Telegram is the first concrete implementation (src/channels/telegram/).
- * Discord and Signal are deferred to v1.1 (Nice-to-Have).
- *
- * Each adapter:
- *  - Renders live session cards (progress, tool calls, summaries)
- *  - Receives inbound channel messages and forwards them as session inputs
- *  - Sends session outputs back to the channel
- *  - Provides idempotent register() to wire OpenClaw plugin lifecycle hooks
- *
- * AUDIT — B2 (PRP_v3 §11 vs reality, 2026-04-28):
- *
- * PRP_v3 §11.1 documents an event vocabulary (`session.created`,
- * `session.turn.start`, `session.tool.start`, `plugin.heartbeat`, etc.)
- * that does NOT exist in the actual codebase. Every `api.on()` call
- * site in src/ uses the openclaw-claude-code hook-event vocabulary
- * documented in `ChannelHookEvent` below. Likewise §11.2's
- * `api.emit('session.result', ...)` is unimplemented — no `api.emit`
- * call sites exist.
- *
- * Resolution: this audit treats the *code* as canonical and the spec
- * as drifted. The `ChannelHookEvent` literal union captures the actual
- * contract any future channel adapter must speak. The §11.x doc
- * sections need a v3.1 revision to match — tracked as a docs-tier
- * follow-up (Tier 3 §24), not a code-tier blocker.
- */
-/**
- * Canonical hook event vocabulary — every event name passed to `api.on()`
- * across src/channels/, src/command-router/, and src/session-bootstrap/
- * (verified by `rg "api\\.on\\(" src/`).
- *
- * This is the contract: any channel/handler that wants to subscribe to
- * gateway events MUST use one of these names. Adding a new event name
- * here without a corresponding gateway emitter is dead-code-typing.
- */
-type ChannelHookEvent = 'before_dispatch' | 'before_prompt_build' | 'before_model_resolve' | 'before_tool_call' | 'after_tool_call' | 'reply_dispatch' | 'message_sending';
-/** Hook handler signature — gateway passes (event, ctx?) positional args. */
-type ChannelHookHandler = (...args: unknown[]) => unknown | Promise<unknown>;
-export interface PluginApi {
-    /**
-     * Subscribe to a gateway hook event.
-     *
-     * Accepts `ChannelHookEvent` for compile-time event-name checking, or
-     * `string` as an escape hatch for adapter-specific events not yet
-     * canonicalized into the union. Future tightening: drop the `| string`
-     * overload once all hook sites use the union.
-     */
-    on(event: ChannelHookEvent, handler: ChannelHookHandler): void;
-    on(event: string, handler: ChannelHookHandler): void;
-}
-/**
- * Outbound message from session → channel.
- */
-export interface ChannelMessage {
-    channel: string;
-    target: string;
-    text?: string;
-    buttons?: ChannelButton[];
-    metadata?: Record<string, unknown>;
-}
-export interface ChannelButton {
-    text: string;
-    callbackData?: string;
-    url?: string;
-}
-/**
- * Inbound envelope from channel → session.
- */
-export interface ChannelInbound {
-    channel: string;
-    fromUserId: string;
-    text: string;
-    metadata?: Record<string, unknown>;
-}
-/**
- * Channel adapter contract. Each concrete adapter (e.g. Telegram) implements
- * this interface so cc-openclaw can route session events to any wired channel.
- */
-export interface ChannelAdapter {
-    /** Adapter identifier — must be unique across registered adapters. */
-    readonly id: string;
-    /**
-     * Idempotent registration of OpenClaw plugin lifecycle hooks.
-     * Multiple calls with the same api MUST NOT stack listeners.
-     */
-    register(api: PluginApi): void;
-    /** Send an outbound message to the channel. */
-    send(message: ChannelMessage): Promise<void>;
-    /** Update an existing live card in-place (rendering progress). */
-    updateCard?(target: string, message: ChannelMessage): Promise<void>;
-    /** Render a final completion summary to the channel. */
-    completionSummary?(target: string, summary: ChannelMessage): Promise<void>;
-}
-/**
- * Helper to wire any ChannelAdapter via the plugin's main register() flow.
- * Centralizes the per-adapter `register()` call so src/index.ts can
- * iterate a list of adapters without coupling to each adapter's internals.
- */
-export declare function registerChannelAdapter(api: PluginApi, adapter: ChannelAdapter): void;
-export {};

package/dist/src/channels/telegram-mirror/askuser.d.ts

@@ -1,107 +0,0 @@
-/**
- * src/channels/telegram-mirror/askuser.ts — v0.26.3 M5.
- *
- * Renders Claude Code's AskUserQuestion tool as native Telegram inline
- * keyboards, "next-turn model" (Path A, chosen by A1 2026-05-20):
- *
- *   agent calls AskUserQuestion  → turn ends
- *   → we send a keyboard message (single-select: one button per option +
- *      "✍️ Write something else"; multi-select: checkbox toggles + Submit)
- *   → user taps  → api.registerInteractiveHandler fires
- *   → we answer the callback, edit the message to show the choice, and
- *      api.enqueueNextTurnInjection() queues the answer as context for the
- *      agent's NEXT turn (it is acted on when the next message runs — the
- *      documented primitive injects context, it does not start a turn).
- *
- * Feasibility proven 2026-05-20: the headless subprocess DOES emit an
- * AskUserQuestion tool_use (pushToolUse name=AskUserQuestion). The tool emits
- * twice (dual content_block_start + assistant-block), so capture dedups by
- * tool_use id.
- *
- * Telegram has no ANSI color — checkboxes use ☐/☑ glyphs.
- */
-/** 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 declare const ASKUSER_NS = "ccmirror";
-interface QOption {
-    label: string;
-    description?: string;
-}
-interface ParsedQuestion {
-    header: string;
-    question: string;
-    multiSelect: boolean;
-    options: QOption[];
-}
-/**
- * v0.28.0 — build a single inline button that, when tapped, resumes a Claude
- * Code session. Reuses the proven askuser callback path: the payload is stashed
- * in the shared (globalThis-anchored) CallbackMap and the callback_data is
- * `ccmirror:<id>`, so taps route through the same before_dispatch interceptor.
- */
-export declare function buildResumeButton(uuid: string, label: string): {
-    text: string;
-    callback_data: string;
-};
-/** Minimal subset of the registerInteractiveHandler ctx we use. */
-export interface InteractiveCtx {
-    callback: {
-        id?: string;
-        data?: string;
-        namespace?: string;
-        payload?: string;
-    };
-    chatId?: string | number;
-    conversationId?: string;
-    sessionKey?: string;
-    threadId?: number;
-    respond?: {
-        editMessage?: (text: string) => Promise<unknown>;
-        answer?: (text?: string) => Promise<unknown>;
-    };
-}
-/** Minimal subset of the plugin api we use (next-turn injection). */
-export interface InjectApi {
-    enqueueNextTurnInjection?: (injection: {
-        sessionKey: string;
-        text: string;
-        placement?: 'prepend_context' | 'append_context';
-        idempotencyKey?: string;
-    }) => unknown;
-}
-/** Record the real agent session key for a chat (called from inbound before_dispatch). */
-export declare function rememberSessionKey(chatId: string, sessionKey: string | undefined): void;
-/** Parse the FIRST question from an AskUserQuestion tool input. Defensive —
- *  returns undefined if the shape isn't usable (no fabrication). */
-export declare function parseFirstQuestion(input: Record<string, unknown> | undefined): ParsedQuestion | undefined;
-/**
- * Capture an AskUserQuestion tool_use and render the keyboard. Called from
- * turn-bridge when name === 'AskUserQuestion'. Dedups the dual-emission by
- * tool_use id. Best-effort: a send failure must not break the turn.
- */
-export declare function captureAskUserQuestion(chatId: string, threadId: number | undefined, input: Record<string, unknown> | undefined, toolUseId: string | undefined): Promise<void>;
-/**
- * Handle an inline-button tap routed from api.registerInteractiveHandler.
- * Resolves the callback payload, updates state, and on a terminal choice
- * (single-select option, multi-select Submit) injects the answer for the next
- * turn. "Write something else" just prompts the user to type — their typed
- * message becomes the next turn naturally, so no injection is needed.
- */
-export declare function handleTap(ctx: InteractiveCtx, api: InjectApi): Promise<void>;
-/** True if an inbound message text is actually an AskUserQuestion button tap.
- *  The gateway delivers taps on plugin-sent keyboards as before_dispatch
- *  messages with text = the callback_data (`ccmirror:<id>`), NOT as routed
- *  interactive-handler callbacks — so we intercept them in before_dispatch. */
-export declare function isAskUserCallback(text: string): boolean;
-/**
- * Handle a tap that arrived as a before_dispatch message (text=`ccmirror:<id>`).
- * Builds a synthetic ctx (conversationId = chatId resolves the remembered
- * session key) and runs the normal tap logic. Caller MUST claim the event so
- * the literal callback_data never reaches the agent.
- */
-export declare function handleTapData(text: string, chatId: string, api: InjectApi): Promise<void>;
-/** Test-only — reset module state. */
-export declare function _resetAskUserForTests(): void;
-/** Test-only — peek pending question count. */
-export declare function _pendingCount(): number;
-export {};