@wu529778790/open-im 1.11.8-beta.2 → 1.11.8-beta.21

package/dist/qq/client.js

@@ -1,6 +1,6 @@
 import WebSocket from "ws";
 import { createLogger } from "../logger.js";
-import { jitteredDelay, SLOW_PROBE_MS } from "../shared/reconnect.js";
+import { ReconnectManager, HeartbeatMonitor } from "../shared/connection-manager.js";
 const log = createLogger("QQ");
 const TOKEN_URL = "https://bots.qq.com/app/getAppAccessToken";
 const API_BASE = "https://api.sgroup.qq.com";
@@ -12,25 +12,23 @@ const INTENTS = {
 };
 let client = null;
 let ws = null;
-let heartbeatTimer = null;
-let reconnectTimer = null;
 let stopped = false;
 let seq = null;
 let sessionId = null;
-let reconnectAttempt = 0;
 let connecting = false; // 防止并发 connectWebSocket
 let currentConfig = null;
 let currentHandler = null;
 let tokenState = null;
-let lastServerResponseTime = 0;
-function clearTimers() {
-    if (heartbeatTimer) {
-        clearInterval(heartbeatTimer);
-        heartbeatTimer = null;
-    }
-    if (reconnectTimer) {
-        clearTimeout(reconnectTimer);
-        reconnectTimer = null;
+// Connection infrastructure (shared managers replace raw timers/counters)
+const heartbeatMonitor = new HeartbeatMonitor();
+const reconnectManager = new ReconnectManager({
+    name: 'QQ',
+    backoff: { mode: 'stepped', delays: RECONNECT_DELAYS_MS },
+    onReconnect: () => reconnectFn(),
+});
+async function reconnectFn() {
+    if (currentConfig && currentHandler) {
+        await connectWebSocket(currentConfig, currentHandler);
     }
 }
 function buildAuthHeaders(token) {
@@ -143,28 +141,28 @@ function normalizeInboundEvent(payload) {
     }
     return null;
 }
-function startHeartbeat(intervalMs) {
-    lastServerResponseTime = Date.now();
-    if (heartbeatTimer)
-        clearInterval(heartbeatTimer);
-    heartbeatTimer = setInterval(() => {
-        if (!ws || ws.readyState !== WebSocket.OPEN)
-            return;
-        const elapsed = Date.now() - lastServerResponseTime;
-        if (lastServerResponseTime > 0 && elapsed > intervalMs * 3) {
-            log.warn(`QQ dead connection: no response for ${Math.round(elapsed / 1000)}s, reconnecting`);
-            clearTimers();
-            ws?.terminate();
-            connectWebSocket(currentConfig, currentHandler);
-            return;
-        }
-        try {
-            ws.send(JSON.stringify({ op: 1, d: seq }));
-        }
-        catch (err) {
-            log.warn('QQ heartbeat send failed:', err);
-        }
-    }, intervalMs);
+/**
+ * Heartbeat tick: send ping and detect stale connections.
+ * The heartbeat interval is dynamic (from QQ gateway HELLO message).
+ */
+let heartbeatIntervalMs = 30000;
+function heartbeatTick() {
+    if (!ws || ws.readyState !== WebSocket.OPEN)
+        return;
+    if (heartbeatMonitor.isStale(heartbeatIntervalMs * 3)) {
+        const elapsed = Date.now() - heartbeatMonitor.lastResponseTime;
+        log.warn(`QQ dead connection: no response for ${Math.round(elapsed / 1000)}s, reconnecting`);
+        heartbeatMonitor.stop();
+        ws?.terminate();
+        reconnectFn().catch((err) => log.error('QQ reconnect from heartbeat failed:', err));
+        return;
+    }
+    try {
+        ws.send(JSON.stringify({ op: 1, d: seq }));
+    }
+    catch (err) {
+        log.warn('QQ heartbeat send failed:', err);
+    }
 }
 async function connectWebSocket(config, handler) {
     // 防止并发连接
@@ -196,17 +194,17 @@ async function connectWebSocket(config, handler) {
             };
             socket.on("open", () => {
                 log.info("QQ gateway connected");
-                reconnectAttempt = 0;
+                reconnectManager.reset();
             });
             socket.on("message", async (raw) => {
-                lastServerResponseTime = Date.now();
+                heartbeatMonitor.recordResponse();
                 try {
                     const payload = JSON.parse(raw.toString());
                     if (typeof payload.s === "number")
                         seq = payload.s;
                     if (payload.op === 10) {
-                        const heartbeatInterval = Number(payload.d?.heartbeat_interval ?? 30000);
-                        startHeartbeat(heartbeatInterval);
+                        heartbeatIntervalMs = Number(payload.d?.heartbeat_interval ?? 30000);
+                        heartbeatMonitor.start(heartbeatIntervalMs, heartbeatTick);
                         socket.send(JSON.stringify({
                             op: sessionId ? 6 : 2,
                             d: sessionId
@@ -253,7 +251,7 @@ async function connectWebSocket(config, handler) {
             });
             socket.on("close", (code, reason) => {
                 settle(() => { }); // 清理 ready timeout
-                clearTimers();
+                heartbeatMonitor.stop();
                 ws = null;
                 const reasonStr = reason.toString();
                 if (code === 4009) {
@@ -273,19 +271,11 @@ async function connectWebSocket(config, handler) {
                     seq = null;
                 }
                 const isFatalClose = code === 4004 || code === 4006 || code === 4007;
-                const baseDelay = RECONNECT_DELAYS_MS[Math.min(reconnectAttempt, RECONNECT_DELAYS_MS.length - 1)];
-                const delay = isFatalClose ? jitteredDelay(SLOW_PROBE_MS) : jitteredDelay(baseDelay);
                 if (isFatalClose) {
-                    log.warn(`QQ 致命关闭码 ${code}（鉴权失败），转慢探测（每 ${Math.round(SLOW_PROBE_MS / 1000)}s 一次）`);
+                    reconnectManager.setFatal(true);
+                    log.warn(`QQ 致命关闭码 ${code}（鉴权失败），转慢探测（每 ${Math.round(5 * 60)}s 一次）`);
                 }
-                reconnectAttempt += 1;
-                reconnectTimer = setTimeout(() => {
-                    if (currentConfig && currentHandler) {
-                        connectWebSocket(currentConfig, currentHandler).catch((err) => {
-                            log.error("QQ reconnect failed:", err);
-                        });
-                    }
-                }, delay);
+                reconnectManager.schedule();
             });
         });
     }
@@ -306,6 +296,8 @@ export async function initQQ(config, eventHandler) {
     stopped = false;
     currentConfig = config;
     currentHandler = eventHandler;
+    reconnectManager.reset();
+    reconnectManager.resume();
     client = {
         sendPrivateMessage: async (openid, content, replyToMessageId) => {
             const res = await apiRequest(config, "POST", `/v2/users/${openid}/messages`, buildMessageBody(content, replyToMessageId));
@@ -328,7 +320,8 @@ export async function initQQ(config, eventHandler) {
 }
 export async function stopQQ() {
     stopped = true;
-    clearTimers();
+    heartbeatMonitor.stop();
+    reconnectManager.stop();
     if (ws) {
         ws.close(1000);
         ws = null;
@@ -339,5 +332,4 @@ export async function stopQQ() {
     tokenState = null;
     sessionId = null;
     seq = null;
-    lastServerResponseTime = 0;
 }

package/dist/shared/ai-task.d.ts

@@ -4,9 +4,24 @@
 import type { Config } from '../config.js';
 import type { SessionManager } from '../session/session-manager.js';
 import type { ToolAdapter } from '../adapters/tool-adapter.interface.js';
+/** 查询指定用户的 autopilot 等待状态（供 /autopilot 命令使用）。 */
+export declare function getAutopilotPendingStatus(userId: string): {
+    retryAt: Date;
+    type: string;
+    retryCount: number;
+} | undefined;
+/** 清除指定用户的 autopilot 状态（测试用）。 */
+export declare function clearAutopilotState(userId: string): void;
 export interface TaskDeps {
     config: Config;
     sessionManager: SessionManager;
+    /**
+     * Autopilot 回调：限流恢复后调用，将 autoResumePrompt 作为新消息
+     * 通过平台的请求队列重新入队。如果不提供，autopilot 不执行恢复动作。
+     */
+    autopilot?: {
+        onAutoPilotContinue: (prompt: string) => void;
+    };
 }
 export interface TaskContext {
     userId: string;

package/dist/shared/ai-task.js

@@ -6,8 +6,99 @@ import { captureError } from './sentry.js';
 import { formatToolStats, formatToolCallNotification, getContextWarning, getAIToolDisplayName, toReplyPlainText, } from './utils.js';
 import { createLogger } from '../logger.js';
 const log = createLogger('AITask');
+/** 每用户连续 autopilot 重试计数。成功完成或遇到非限流错误时清零。 */
+const autopilotRetryCount = new Map();
+/** 当前等待中的 autopilot 定时器（用于 /autopilot 状态查询）。 */
+const pendingAutopilotTimers = new Map();
+/** 查询指定用户的 autopilot 等待状态（供 /autopilot 命令使用）。 */
+export function getAutopilotPendingStatus(userId) {
+    return pendingAutopilotTimers.get(userId);
+}
+/** 清除指定用户的 autopilot 状态（测试用）。 */
+export function clearAutopilotState(userId) {
+    autopilotRetryCount.delete(userId);
+    pendingAutopilotTimers.delete(userId);
+}
+/**
+ * 判断错误是否为限流类错误（用于决定是否保留 session）。
+ * 覆盖所有已知的限流模式：429/529/session limit/overloaded/temporary throttle。
+ */
 function isUsageLimitError(error) {
-    return /usage limit/i.test(error) || /try again at\s+\d{1,2}:\d{2}\s*(AM|PM)/i.test(error);
+    return /usage\s*limit/i.test(error)
+        || /try\s+again\s+at\s+\d{1,2}:\d{2}/i.test(error)
+        || /rate\s*limit/i.test(error)
+        || /\b429\b/.test(error)
+        || /\b529\b/.test(error)
+        || /overloaded/i.test(error)
+        || /temporarily\s+limiting/i.test(error)
+        || /session\s+limit/i.test(error)
+        || /you['\u2019]ve\s+hit\s+your/i.test(error);
+}
+/**
+ * 从错误消息中提取限流详情。仅在 isUsageLimitError() 返回 true 后调用。
+ */
+function classifyRateLimit(error, config) {
+    const now = Date.now();
+    const shortMs = config.autopilot.shortRetrySeconds * 1000;
+    const defaultMs = config.autopilot.defaultIntervalHours * 3600 * 1000;
+    // Session quota / usage limit（最常见，等待时间最长）
+    if (/session\s*limit|usage\s*limit|opus\s*limit|you['\u2019]ve\s+hit\s+your/i.test(error)) {
+        const timeMatch = error.match(/try\s+again\s+at\s+(\d{1,2}):(\d{2})\s*(AM|PM)?/i);
+        if (timeMatch) {
+            let hours = parseInt(timeMatch[1], 10);
+            const minutes = parseInt(timeMatch[2], 10);
+            const ampm = timeMatch[3]?.toUpperCase();
+            if (ampm === 'PM' && hours < 12)
+                hours += 12;
+            if (ampm === 'AM' && hours === 12)
+                hours = 0;
+            const retryAt = new Date();
+            retryAt.setHours(hours, minutes, 0, 0);
+            if (retryAt.getTime() <= now)
+                retryAt.setDate(retryAt.getDate() + 1);
+            return { detected: true, type: 'session_limit', retryAt, isLongWait: true };
+        }
+        return { detected: true, type: 'session_limit', retryAt: new Date(now + defaultMs), isLongWait: true };
+    }
+    // 529 overloaded / temporarily limiting（短延迟）
+    if (/\b529\b|overloaded|temporarily\s+limiting/i.test(error)) {
+        return {
+            detected: true,
+            type: /overloaded/i.test(error) ? 'overloaded' : 'temporary',
+            retryAt: new Date(now + shortMs),
+            isLongWait: false,
+        };
+    }
+    // 429 rate limit（使用默认周期）
+    if (/\b429\b|rate\s*limit/i.test(error)) {
+        return { detected: true, type: 'api_rate_limit', retryAt: new Date(now + defaultMs), isLongWait: true };
+    }
+    return { detected: false, type: null, retryAt: null, isLongWait: false };
+}
+function rateLimitTypeLabel(type) {
+    switch (type) {
+        case 'session_limit': return '会话额度限制';
+        case 'api_rate_limit': return 'API 速率限制';
+        case 'overloaded': return '服务器过载';
+        case 'temporary': return '临时限流';
+        default: return '限流';
+    }
+}
+function formatTimeHHMM(date) {
+    return `${date.getHours().toString().padStart(2, '0')}:${date.getMinutes().toString().padStart(2, '0')}`;
+}
+function formatDuration(ms) {
+    if (ms <= 0)
+        return '即将';
+    const totalSec = Math.ceil(ms / 1000);
+    const hours = Math.floor(totalSec / 3600);
+    const minutes = Math.floor((totalSec % 3600) / 60);
+    const seconds = totalSec % 60;
+    if (hours > 0)
+        return `${hours}小时${minutes > 0 ? `${minutes}分钟` : ''}`;
+    if (minutes > 0)
+        return `${minutes}分钟${seconds > 0 ? `${seconds}秒` : ''}`;
+    return `${seconds}秒`;
 }
 /**
  * 将 AI/CLI 错误文本归类为一个稳定的 errorType 字符串，用于遥测聚合。
@@ -211,6 +302,8 @@ export function runAITask(deps, ctx, prompt, toolAdapter, platformAdapter) {
                     if (settled)
                         return;
                     settled = true;
+                    // 成功完成 → 清除 autopilot 重试计数
+                    autopilotRetryCount.delete(ctx.userId);
                     if (pendingUpdate) {
                         clearTimeout(pendingUpdate);
                         pendingUpdate = null;
@@ -263,6 +356,83 @@ export function runAITask(deps, ctx, prompt, toolAdapter, platformAdapter) {
                     }
                     settled = true;
                     log.error(`Task error for user ${ctx.userId}: ${error}`);
+                    // ── Autopilot 拦截 ──
+                    const apConfig = config.autopilot;
+                    const currentRetries = autopilotRetryCount.get(ctx.userId) ?? 0;
+                    if (apConfig?.enabled &&
+                        deps.autopilot &&
+                        isUsageLimitError(error) &&
+                        currentRetries < apConfig.maxRetries) {
+                        const rateInfo = classifyRateLimit(error, config);
+                        if (rateInfo.detected && rateInfo.retryAt) {
+                            const retryCount = currentRetries + 1;
+                            autopilotRetryCount.set(ctx.userId, retryCount);
+                            // 记录等待状态
+                            pendingAutopilotTimers.set(ctx.userId, {
+                                retryAt: rateInfo.retryAt,
+                                type: rateInfo.type,
+                                retryCount,
+                            });
+                            // 通知用户
+                            const typeLabel = rateLimitTypeLabel(rateInfo.type);
+                            const timeStr = formatTimeHHMM(rateInfo.retryAt);
+                            const remaining = formatDuration(rateInfo.retryAt.getTime() - Date.now());
+                            const statusMsg = `⏳ 检测到${typeLabel}，将在 ${timeStr}（${remaining}后）自动恢复 (${retryCount}/${apConfig.maxRetries})`;
+                            log.info(`[Autopilot] ${statusMsg} for user ${ctx.userId}`);
+                            try {
+                                await platformAdapter.sendError(hadSessionInvalid
+                                    ? '当前 Claude 会话已失效，已自动执行 /new 重置会话，请重新发送刚才的问题。'
+                                    : `${error}\n\n${statusMsg}`);
+                            }
+                            catch (err) {
+                                log.error('Failed to send autopilot status:', err);
+                            }
+                            cleanup();
+                            resolve();
+                            // 异步等待 → 恢复（不阻塞 Promise 解决）
+                            const retryAt = rateInfo.retryAt;
+                            const delayMs = Math.max(retryAt.getTime() - Date.now(), 0);
+                            log.info(`[Autopilot] Scheduling retry in ${delayMs}ms for user ${ctx.userId}`);
+                            // 分段定时器（setTimeout 最大 ~24.8 天）
+                            const MAX_SEGMENT = 2_147_483_647; // 2^31 - 1
+                            const scheduleRetry = (remaining) => {
+                                if (remaining <= 0) {
+                                    // 定时器到期 → 清除状态 → 发送恢复消息
+                                    pendingAutopilotTimers.delete(ctx.userId);
+                                    log.info(`[Autopilot] Timer fired for user ${ctx.userId}, sending "${apConfig.autoResumePrompt}"`);
+                                    try {
+                                        platformAdapter.streamUpdate('', `🔄 限额已恢复，正在自动重试... (${retryCount})`);
+                                    }
+                                    catch {
+                                        /* ignore */
+                                    }
+                                    deps.autopilot.onAutoPilotContinue(apConfig.autoResumePrompt);
+                                    return;
+                                }
+                                const segment = Math.min(remaining, MAX_SEGMENT);
+                                const timer = setTimeout(() => scheduleRetry(remaining - segment), segment);
+                                if (typeof timer === 'object' && 'unref' in timer)
+                                    timer.unref();
+                                // 如果任务被 abort（/new、cancelUser），取消待执行的定时器
+                                if (ctx.signal) {
+                                    if (ctx.signal.aborted) {
+                                        clearTimeout(timer);
+                                        pendingAutopilotTimers.delete(ctx.userId);
+                                        return;
+                                    }
+                                    ctx.signal.addEventListener('abort', () => {
+                                        clearTimeout(timer);
+                                        pendingAutopilotTimers.delete(ctx.userId);
+                                        log.info(`[Autopilot] Timer cancelled by abort for user ${ctx.userId}`);
+                                    }, { once: true });
+                                }
+                            };
+                            scheduleRetry(delayMs);
+                            return;
+                        }
+                    }
+                    // ── 非限流错误或 autopilot 未启用/耗尽重试 ──
+                    autopilotRetryCount.delete(ctx.userId);
                     if (isUsageLimitError(error)) {
                         // Usage limit errors: keep session for all tools (user can retry later)
                         log.warn(`Keeping ${aiCommand} session for user ${ctx.userId} after usage limit error`);
@@ -290,7 +460,9 @@ export function runAITask(deps, ctx, prompt, toolAdapter, platformAdapter) {
             }, {
                 model: aiCommand === 'claude'
                     ? (sessionManager.getModel(ctx.userId, ctx.threadId) ?? config.claudeModel)
-                    : undefined,
+                    : aiCommand === 'opencode'
+                        ? config.opencodeModel
+                        : undefined,
                 chatId: ctx.chatId,
                 // 默认跳过权限确认，保持全自动执行（可通过 config 或环境变量关闭）
                 skipPermissions: config.skipPermissions ?? true,

package/dist/shared/cli-runner-base.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Shared CLI runner utilities — stderr buffering, finalize gating,
+ * wall-clock timeout, and abort handle.
+ *
+ * Used by codex, codebuddy, and opencode CLI runners to eliminate
+ * duplicated process lifecycle management code.
+ */
+import { type ChildProcess, type SpawnOptions } from 'node:child_process';
+import type { Interface as ReadlineInterface } from 'node:readline';
+import type { RunHandle } from '../adapters/tool-adapter.interface.js';
+export declare const MAX_STDERR_HEAD: number;
+export declare const MAX_STDERR_TAIL: number;
+export interface StderrBuffer {
+    head: string;
+    tail: string;
+    total: number;
+    headFull: boolean;
+}
+export declare function createStderrBuffer(): StderrBuffer;
+export declare function appendStderr(buf: StderrBuffer, text: string): void;
+export declare function reconstructStderr(buf: StderrBuffer): string;
+export interface FinalizeGate {
+    rlClosed: boolean;
+    childClosed: boolean;
+}
+export declare function createFinalizeGate(): FinalizeGate;
+export declare function isFinalizeReady(gate: FinalizeGate): boolean;
+export declare function startWallClockTimeout(child: ChildProcess, timeoutMs: number, toolName: string, log: {
+    warn: (...args: unknown[]) => void;
+}, onTimeout: () => void, extraCleanup?: () => void): ReturnType<typeof setTimeout>;
+export declare function clearWallClockTimeout(handle: ReturnType<typeof setTimeout> | null): void;
+export declare function createAbortHandle(completed: {
+    value: boolean;
+}, child: ChildProcess, timeoutHandle: {
+    value: ReturnType<typeof setTimeout> | null;
+}, rl?: ReadlineInterface): RunHandle;
+export declare function buildBaseEnv(extra?: Record<string, string | undefined>): NodeJS.ProcessEnv;
+export declare function buildBaseSpawnOptions(workDir: string, stdio?: ('pipe' | 'ignore' | 'inherit')[], extraEnv?: Record<string, string | undefined>): SpawnOptions;
+export declare function spawnCliProcess(command: string, args: string[], workDir: string, stdio?: ('pipe' | 'ignore' | 'inherit')[], extraEnv?: Record<string, string | undefined>): ChildProcess;

package/dist/shared/cli-runner-base.js

@@ -0,0 +1,108 @@
+/**
+ * Shared CLI runner utilities — stderr buffering, finalize gating,
+ * wall-clock timeout, and abort handle.
+ *
+ * Used by codex, codebuddy, and opencode CLI runners to eliminate
+ * duplicated process lifecycle management code.
+ */
+import { spawn } from 'node:child_process';
+import { processEnvForNonClaudeCliChild } from '../config/file-io.js';
+import { killProcessTree, trackChild } from './process-kill.js';
+// ── stderr head/tail buffer ──────────────────────────────────────
+export const MAX_STDERR_HEAD = 4 * 1024;
+export const MAX_STDERR_TAIL = 6 * 1024;
+export function createStderrBuffer() {
+    return { head: '', tail: '', total: 0, headFull: false };
+}
+export function appendStderr(buf, text) {
+    buf.total += text.length;
+    if (!buf.headFull) {
+        const room = MAX_STDERR_HEAD - buf.head.length;
+        if (room > 0) {
+            buf.head += text.slice(0, room);
+            if (buf.head.length >= MAX_STDERR_HEAD)
+                buf.headFull = true;
+        }
+    }
+    buf.tail += text;
+    if (buf.tail.length > MAX_STDERR_TAIL) {
+        buf.tail = buf.tail.slice(-MAX_STDERR_TAIL);
+    }
+}
+export function reconstructStderr(buf) {
+    if (buf.total === 0)
+        return '';
+    if (!buf.headFull)
+        return buf.head;
+    if (buf.total <= MAX_STDERR_HEAD + MAX_STDERR_TAIL) {
+        return buf.head + buf.tail.slice(buf.tail.length - (buf.total - MAX_STDERR_HEAD));
+    }
+    return (buf.head +
+        `\n\n... (omitted ${buf.total - MAX_STDERR_HEAD - MAX_STDERR_TAIL} bytes) ...\n\n` +
+        buf.tail);
+}
+export function createFinalizeGate() {
+    return { rlClosed: false, childClosed: false };
+}
+export function isFinalizeReady(gate) {
+    return gate.rlClosed && gate.childClosed;
+}
+// ── wall-clock timeout ───────────────────────────────────────────
+export function startWallClockTimeout(child, timeoutMs, toolName, log, onTimeout, extraCleanup) {
+    const handle = setTimeout(() => {
+        log.warn(`${toolName} CLI 超过 ${timeoutMs}ms，强制终止 (pid=${child.pid})`);
+        extraCleanup?.();
+        onTimeout();
+        killProcessTree(child);
+    }, timeoutMs);
+    handle.unref();
+    return handle;
+}
+export function clearWallClockTimeout(handle) {
+    if (handle)
+        clearTimeout(handle);
+}
+// ── abort handle ─────────────────────────────────────────────────
+export function createAbortHandle(completed, child, timeoutHandle, rl) {
+    return {
+        abort: () => {
+            if (completed.value)
+                return;
+            completed.value = true;
+            clearWallClockTimeout(timeoutHandle.value);
+            timeoutHandle.value = null;
+            rl?.close();
+            killProcessTree(child);
+        },
+    };
+}
+// ── environment and spawn configuration ─────────────────────────
+export function buildBaseEnv(extra) {
+    const env = processEnvForNonClaudeCliChild();
+    if (process.platform === 'win32') {
+        env.LANG = env.LANG || 'C.UTF-8';
+        env.LC_ALL = env.LC_ALL || 'C.UTF-8';
+    }
+    if (extra) {
+        for (const [key, value] of Object.entries(extra)) {
+            if (value !== undefined)
+                env[key] = value;
+        }
+    }
+    return env;
+}
+export function buildBaseSpawnOptions(workDir, stdio = ['pipe', 'pipe', 'pipe'], extraEnv) {
+    const opts = {
+        cwd: workDir,
+        detached: process.platform !== 'win32',
+        stdio,
+        env: buildBaseEnv(extraEnv),
+        windowsHide: process.platform === 'win32',
+    };
+    return opts;
+}
+export function spawnCliProcess(command, args, workDir, stdio = ['pipe', 'pipe', 'pipe'], extraEnv) {
+    const child = spawn(command, args, buildBaseSpawnOptions(workDir, stdio, extraEnv));
+    trackChild(child);
+    return child;
+}

package/dist/shared/connection-manager.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Shared connection management infrastructure for self-managing platform clients.
+ *
+ * Encapsulates three cross-cutting concerns duplicated across wework, clawbot,
+ * qq, and workbuddy clients:
+ *
+ * - **ReconnectManager**: jittered backoff scheduling with fatal→slow-probe mode
+ * - **HeartbeatMonitor**: interval-based heartbeat / watchdog timer
+ * - **StateManager**: state variable with change-notification callback
+ */
+export interface ReconnectManagerConfig {
+    /** Platform name used in log messages. */
+    name: string;
+    /**
+     * Delay strategy:
+     * - `{ mode: 'exponential', baseMs, maxMs, cap }` — exponential backoff
+     *   `min(baseMs * 1.5^floor(attempt / cap), maxMs)`.
+     * - `{ mode: 'stepped', delays }` — stepped array; last entry repeats.
+     */
+    backoff: {
+        mode: 'exponential';
+        baseMs: number;
+        maxMs: number;
+        cap?: number;
+    } | {
+        mode: 'stepped';
+        delays: number[];
+    };
+    /**
+     * After this many attempts the counter resets and retries continue
+     * (avoids permanent disconnection). 0 = unlimited (no reset).
+     */
+    maxAttempts?: number;
+    /** Callback invoked after the computed delay. */
+    onReconnect: () => void | Promise<void>;
+}
+/**
+ * Manages reconnection scheduling with jittered backoff and fatal→slow-probe.
+ *
+ * Replaces the duplicated `scheduleReconnect()` pattern across 4 client files:
+ * timer cleanup, attempt counting, backoff computation, jitter, logging.
+ */
+export declare class ReconnectManager {
+    private timer;
+    private attempt;
+    private _fatal;
+    private _stopped;
+    private readonly log;
+    private readonly cfg;
+    constructor(cfg: ReconnectManagerConfig);
+    get attemptCount(): number;
+    get fatal(): boolean;
+    get stopped(): boolean;
+    /** Mark a fatal (auth) error — next scheduleReconnect uses slow-probe delay. */
+    setFatal(value: boolean): void;
+    /** Reset attempt counter and fatal flag after a successful connection. */
+    reset(): void;
+    /**
+     * Schedule a reconnect attempt.  Clears any pending timer, computes the
+     * backoff delay (with jitter), and invokes `onReconnect` after the delay.
+     */
+    schedule(): void;
+    /** Cancel any pending reconnect timer. */
+    stop(): void;
+    /** Allow scheduling again (undo `stop`). */
+    resume(): void;
+    private clearTimer;
+    private computeBaseDelay;
+}
+/**
+ * Manages a setInterval-based heartbeat or watchdog timer.
+ *
+ * Replaces duplicated `heartbeatTimer` / `watchdogTimer` patterns:
+ * timer cleanup on re-start, clearInterval on stop.
+ */
+export declare class HeartbeatMonitor {
+    private timer;
+    private _lastResponseTime;
+    get lastResponseTime(): number;
+    /** Record that a response was received (for watchdog stale detection). */
+    recordResponse(): void;
+    /**
+     * Start a periodic callback.  Clears any existing timer first.
+     * @param intervalMs  Interval in milliseconds.
+     * @param onTick      Callback invoked on each tick.
+     */
+    start(intervalMs: number, onTick: () => void | Promise<void>): void;
+    /** Clear the heartbeat timer. */
+    stop(): void;
+    /**
+     * Watchdog convenience: returns true if more than `staleMs` have elapsed
+     * since the last `recordResponse()` call.
+     */
+    isStale(staleMs: number): boolean;
+}
+/**
+ * Manages a connection state variable with change-notification callback.
+ *
+ * Replaces duplicated `connectionState` / `channelState` + `stateChangeHandler`
+ * patterns across wework, clawbot, and workbuddy clients.
+ */
+export declare class StateManager<T extends string> {
+    private _state;
+    private onChange?;
+    constructor(initialState: T);
+    get current(): T;
+    /** Register a callback invoked whenever the state changes. */
+    setOnChange(handler: ((state: T) => void) | undefined): void;
+    /** Transition to a new state and notify the callback if it changed. */
+    set(newState: T): void;
+}