@brierb/brier-cli 0.0.7 → 0.0.9

package/dist/tunnel/transport.js

@@ -0,0 +1,112 @@
+import { WebSocket } from 'ws';
+/**
+ * WebSocket 传输层封装：屏蔽 ws 库细节，向骨架暴露统一事件与命令。
+ *
+ * 职责边界：
+ * - connect() 每次调用会先清理上一个连接（移除监听 + terminate），再建立新连接；
+ * - 事件（open/message/close/error）通过 on() 订阅，订阅一次后跨多次重连保持有效；
+ * - 协议层 ping 自动回 pong，调用方无需感知；
+ * - send() 返回是否已入队：未连接或发送缓冲积压超限（背压）时返回 false，
+ *   由上层决定丢弃或重试，本模块不抛错。
+ */
+/** 发送缓冲上限（字节）：超过该值 send() 返回 false 触发背压，防止慢网时内存无上限增长 */
+const MAX_BUFFERED_AMOUNT_BYTES = 4 * 1024 * 1024;
+export const createWebSocketTransport = () => {
+    let ws = null;
+    const listeners = {
+        open: new Set(),
+        close: new Set(),
+        message: new Set(),
+        error: new Set(),
+    };
+    const emit = (event, ...args) => {
+        // 泛型下 Parameters 的元组关系无法直接展开，统一按 rest 参数调用
+        for (const callback of listeners[event]) {
+            callback(...args);
+        }
+    };
+    const teardown = () => {
+        if (ws) {
+            ws.removeAllListeners();
+            if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
+                ws.terminate();
+            }
+            ws = null;
+        }
+    };
+    const readyState = () => (ws ? ws.readyState : -1);
+    return {
+        connect(url, headers) {
+            teardown();
+            const socket = new WebSocket(url, { headers });
+            ws = socket;
+            socket.on('open', () => emit('open'));
+            socket.on('message', (data) => emit('message', data.toString()));
+            socket.on('close', (code, reason) => emit('close', code, reason.toString()));
+            socket.on('error', (err) => emit('error', err.message));
+            socket.on('ping', () => socket.pong());
+        },
+        send(data) {
+            if (ws === null || ws.readyState !== WebSocket.OPEN) {
+                return false;
+            }
+            if (ws.bufferedAmount > MAX_BUFFERED_AMOUNT_BYTES) {
+                return false;
+            }
+            try {
+                ws.send(data);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        close(code, reason) {
+            if (ws && (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING)) {
+                ws.close(code, reason);
+            }
+        },
+        terminate() {
+            ws?.terminate();
+        },
+        isOpen() {
+            return readyState() === WebSocket.OPEN;
+        },
+        isConnecting() {
+            return readyState() === WebSocket.CONNECTING;
+        },
+        isClosed() {
+            return ws === null || ws.readyState === WebSocket.CLOSED;
+        },
+        waitClosed(timeoutMs) {
+            return new Promise((resolve) => {
+                let settled = false;
+                const onClose = () => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    cleanup();
+                    resolve();
+                };
+                const timer = setTimeout(() => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    cleanup();
+                    resolve();
+                }, timeoutMs);
+                const cleanup = () => {
+                    clearTimeout(timer);
+                    listeners.close.delete(onClose);
+                };
+                listeners.close.add(onClose);
+            });
+        },
+        on(event, callback) {
+            listeners[event].add(callback);
+            return () => {
+                listeners[event].delete(callback);
+            };
+        },
+    };
+};

package/dist/tunnel/url.js

@@ -0,0 +1,10 @@
+/**
+ * 隧道接入端点工具：把服务端 http(s) 地址转换为 WebSocket 隧道地址。
+ * 纯字符串转换（wss/ws://host/tunnel），无状态、无副作用。
+ */
+export const toWsUrl = (serverUrl) => {
+    return (serverUrl
+        .replace(/^https:\/\//, 'wss://')
+        .replace(/^http:\/\//, 'ws://')
+        .replace(/\/$/, '') + '/tunnel');
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brierb/brier-cli",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "Brier 平台接入命令行工具：通过加密隧道将本机接入 Brier 远程编码池，接收并执行远程任务",
   "keywords": [
     "brier",
@@ -19,8 +19,8 @@
       "types": "./types/index.d.ts"
     },
     "./tunnel": {
-      "import": "./dist/tunnel/TunnelClient.js",
-      "types": "./types/tunnel/TunnelClient.d.ts"
+      "import": "./dist/tunnel/index.js",
+      "types": "./types/tunnel/index.d.ts"
     }
   },
   "files": [

package/types/commands/log.d.ts

@@ -0,0 +1,5 @@
+/**
+ * `brier daemon log`：查看后台服务日志。
+ * 输出 ~/.brier/daemon.log 最近 100 行；文件不存在时给出提示与路径。
+ */
+export declare const logCommand: () => void;

package/types/commands/run.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 命令执行包装：统一 try/catch 与失败退出码。
+ * commander 的 action 直接返回 runCommand(...)，消除各命令重复的错误处理样板。
+ */
+export declare const runCommand: (fn: () => void | Promise<void>) => Promise<void>;

package/types/commands/status.d.ts

@@ -1 +1,2 @@
+/** `brier daemon status`：展示 daemon 运行状态与状态文件详情。 */
 export declare const statusCommand: () => void;

package/types/config/credentials.d.ts

@@ -0,0 +1,8 @@
+/** 读取持久化的接入令牌；文件缺失或损坏时返回 undefined。 */
+export declare const readStoredToken: () => string | undefined;
+/**
+ * 持久化接入令牌到 ~/.brier/credentials.json。
+ * 写入使用 mode 0600，并对已存在的文件强制收紧权限（防止先前被宽权限创建）。
+ * 失败会抛错，由调用方决定是否阻断启动。
+ */
+export declare const writeCredentials: (token: string) => void;

package/types/config/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 配置域统一出口：提供 daemon 装配所需的全部环境信息。
+ *
+ * 目录内文件职责：
+ * - load.ts：  loadConfig()，从环境变量装配 DaemonConfig
+ * - paths.ts： 应用路径常量（~/.brier 下的 PID/日志文件）
+ * - version.ts：CLI 版本读取（package.json）
+ */
+/** daemon 装配配置（BRIER_SERVER_URL / BRIER_TOKEN → DaemonConfig） */
+export { loadConfig } from './load.js';
+/** 应用路径常量：BRIER_DIR / DAEMON_STATE_FILE / LOG_FILE / CREDENTIALS_FILE */
+export { BRIER_DIR, DAEMON_STATE_FILE, LOG_FILE, CREDENTIALS_FILE } from './paths.js';
+/** CLI 版本读取 */
+export { readCliVersion } from './version.js';
+/** 接入令牌持久化（credentials.json，0600） */
+export { readStoredToken, writeCredentials } from './credentials.js';

package/types/config/load.d.ts

@@ -0,0 +1,7 @@
+import type { DaemonConfig } from '../definitions/index.js';
+/**
+ * daemon 装配配置加载：从 BRIER_SERVER_URL / BRIER_TOKEN 环境变量
+ * 读取 serverUrl / token，并组合本机信息（hostname/os/runtimes/version）。
+ * 校验失败（缺少必填项）时抛出带说明的错误。
+ */
+export declare const loadConfig: () => DaemonConfig;

package/types/config/paths.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 应用文件路径常量。
+ * 集中到 ~/.brier/ 下，保证与 daemon 启动时的工作目录无关。
+ */
+/** Brier 用户数据目录（~/.brier） */
+export declare const BRIER_DIR: string;
+/** daemon 运行状态文件（JSON，结构见 definitions/daemon.ts 的 DaemonState） */
+export declare const DAEMON_STATE_FILE: string;
+/** daemon 运行日志文件 */
+export declare const LOG_FILE: string;
+/** daemon 接入令牌持久化文件（0600，供 `daemon restart` 无参回退） */
+export declare const CREDENTIALS_FILE: string;

package/types/config/version.d.ts

@@ -0,0 +1,2 @@
+/** CLI 自身版本：读取 dist 两级的 package.json（与 `brier --version` 同源）。 */
+export declare const readCliVersion: () => string;

package/types/core/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 公共底座统一出口：无业务依赖的基础能力，供 config/daemon/tunnel/commands 各域使用。
+ *
+ * 目录内文件职责：
+ * - logger.ts： 文件日志（configureLogger / logger）
+ * - runtimes.ts：AI runtime 注册表、可执行文件解析与已安装探测
+ */
+/** 文件日志 */
+export { configureLogger, logger } from './logger.js';
+/** AI runtime 注册表 / 命令 / prompt 参数 / 解析 / 探测 */
+export * from './runtimes.js';

package/types/{runtimes.d.ts → core/runtimes.d.ts}

@@ -21,3 +21,9 @@ export declare const RUNTIME_PROMPT_FLAGS: Record<string, readonly string[]>;
  * runtime 一定可被执行，不依赖 daemon 进程的 PATH。
  */
 export declare const resolveRuntimeExecutable: (runtime: string) => string | null;
+/**
+ * 探测本机已安装的 AI runtime 名称列表。
+ * 过滤注册表：只保留 resolveRuntimeExecutable 能解析出可执行文件的项
+ * （探测与执行共用同一解析，保证“探测到”的 runtime 一定能被 spawn）。
+ */
+export declare const detectInstalledRuntimes: () => string[];

package/types/daemon/DaemonManager.d.ts

@@ -1,4 +1,4 @@
-import type { DaemonStatus } from '../types.js';
+import type { DaemonStatus } from '../definitions/index.js';
 export interface DaemonManager {
     start: (options: {
         serverUrl: string;

package/types/daemon/OutputBatcher.d.ts

@@ -0,0 +1,39 @@
+import type { StreamType } from '../definitions/index.js';
+/**
+ * 任务输出批量发送器（micro-batching）。
+ *
+ * 动机：task-output 是高频小消息，逐块上行会在传输、序列化与服务端逐帧 DB 写入上
+ * 放大开销。本模块按 (taskId, stream) 缓冲，满足以下任一条件即 flush：
+ * - 单缓冲累计达到 maxBatchBytes（大输出即时发送，不等时间窗）；
+ * - 到达 flushIntervalMs（低流量输出不会滞留过久，保证可感知延迟有上界）。
+ *
+ * 语义保证：
+ * - 同一 (taskId, stream) 严格保序，合并为一条消息发出；
+ * - 不同 task/stream 互不阻塞，各自独立 flush；
+ * - 只聚合、不截断、不背压（背压仍由上层 safeSend/连接层负责）。
+ */
+export interface OutputChunk {
+    taskId: string;
+    stream: StreamType;
+    /** 该缓冲项合并后的完整数据 */
+    data: string;
+}
+export interface OutputBatcherOptions {
+    /** 单个 (taskId, stream) 缓冲的字节阈值（按字符串 length 近似），达到即立即 flush */
+    maxBatchBytes?: number;
+    /** 周期 flush 时间窗（ms），保证低流量也有延迟上界 */
+    flushIntervalMs?: number;
+    /** flush 回调：一次回调可含多个缓冲项 */
+    onFlush: (chunks: OutputChunk[]) => void;
+}
+export interface OutputBatcher {
+    /** 追加一块输出；达到字节阈值会立即触发 flush */
+    push: (taskId: string, stream: StreamType, data: string) => void;
+    /** 立即 flush 指定 task 的全部缓冲（发送终态消息前调用，避免尾输出丢失） */
+    flushTask: (taskId: string) => void;
+    /** 立即 flush 全部缓冲（停止前调用） */
+    flushAll: () => void;
+    /** 清理定时器与残留缓冲（调用前应先 flushAll） */
+    dispose: () => void;
+}
+export declare const createOutputBatcher: (options: OutputBatcherOptions) => OutputBatcher;

package/types/daemon/TaskExecutor.d.ts

@@ -1,4 +1,4 @@
-import type { TaskInfo } from '../types.js';
+import type { TaskInfo } from '../definitions/index.js';
 export interface TaskExecutorCallbacks {
     onOutput: (taskId: string, stream: 'stdout' | 'stderr', data: string) => void;
     onComplete: (taskId: string, exitCode: number) => void;
@@ -6,7 +6,9 @@ export interface TaskExecutorCallbacks {
 }
 export interface TaskExecutor {
     execute: (task: TaskInfo) => void;
+    /** 取消单个任务：SIGTERM，宽限期后 SIGKILL */
     cancel: (taskId: string) => void;
-    cancelAll: () => void;
+    /** 停止并收尾：对全部运行中任务 SIGTERM，等待退出，未退出的 SIGKILL */
+    dispose: () => Promise<void>;
 }
 export declare const createTaskExecutor: (callbacks: TaskExecutorCallbacks) => TaskExecutor;

package/types/daemon/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * daemon 域统一出口。
+ *
+ * 说明：DaemonRunner.ts 是 daemon 子进程的入口脚本（模块顶层即执行 main()，
+ * 并校验 BRIER_DAEMON_MODE），由 DaemonManager 以文件路径 spawn，
+ * 不应被 import，故不在此导出。本目录其余模块均无副作用，可安全经此导入。
+ */
+/** daemon 进程生命周期管理（前台 CLI 使用） */
+export { createDaemonManager, type DaemonManager } from './DaemonManager.js';
+/** 任务执行器（daemon 子进程内 spawn runtime） */
+export { createTaskExecutor, type TaskExecutor, type TaskExecutorCallbacks, } from './TaskExecutor.js';
+/** daemon 运行状态读取（status/restart 展示与回退） */
+export { readDaemonState } from './state.js';

package/types/daemon/state.d.ts

@@ -0,0 +1,19 @@
+import type { DaemonState } from '../definitions/index.js';
+/** 仅判断 pid 是否存活（kill 0）。 */
+export declare const isProcessAlive: (pid: number) => boolean;
+/**
+ * 校验状态记录对应的 daemon 是否存活：
+ * pid 存活 + 命令行含 DaemonRunner（防止 PID 复用后指向无关进程）。
+ * ps 不可用时退化为仅存活判断，避免跨平台误伤。
+ */
+export declare const isDaemonRunning: (state: DaemonState) => boolean;
+/** 读取运行状态；文件缺失或字段不全（含旧版格式）时返回 null。 */
+export declare const readDaemonState: () => DaemonState | null;
+/** 写入完整运行状态（Manager 启动时调用）。 */
+export declare const writeDaemonState: (state: DaemonState) => void;
+/** 合并更新状态（Runner 侧置 ready/bootError/tunnelState，保留其余字段）。 */
+export declare const updateDaemonState: (patch: Partial<DaemonState>) => void;
+/** 清理运行状态文件（不存在时静默）。 */
+export declare const removeDaemonState: () => void;
+/** 轮询等待 pid 退出；超时返回 false。 */
+export declare const waitForProcessExit: (pid: number, timeoutMs?: number) => Promise<boolean>;

package/types/definitions/daemon.d.ts

@@ -0,0 +1,58 @@
+/**
+ * daemon 的装配配置、生命周期状态与进程间通信文件。
+ * 本文件三个类型均为“daemon 进程自身/前台 CLI 管理 daemon”使用，不参与隧道线协议。
+ */
+/**
+ * daemon 后台服务运行状态（前台 CLI 使用，如 `brier daemon status`）。
+ *
+ * 当前实现实际只产出 running | stopped（进程不在即清理状态文件并返回 stopped）；
+ * error 为预留值，尚无产出点。
+ */
+export type DaemonStatus = 'running' | 'stopped' | 'error';
+/**
+ * daemon 装配配置。
+ *
+ * 由 config.loadConfig() 从 BRIER_SERVER_URL / BRIER_TOKEN 环境变量加载，
+ * DaemonRunner 启动后整体注入 TunnelClient；其中 hostname/os/runtimes/version
+ * 在握手时随 auth 消息上报服务端用于展示与任务路由。
+ */
+export interface DaemonConfig {
+    /** Brier 服务端地址（http/https，连接时由 toWsUrl 转换为 ws/wss 并拼接 /tunnel） */
+    serverUrl: string;
+    /** 接入令牌（BRIER_TOKEN），同时用于 wss Authorization 头与 auth 消息 */
+    token: string;
+    /** 本机主机名（同时作为服务端按用户维度 upsert 工作电脑的标识键） */
+    hostname: string;
+    /** 操作系统描述（`${type} ${platform} ${arch}`，仅供展示） */
+    os: string;
+    /** 探测到的已安装 AI runtime 列表（探测与执行共用 resolveRuntimeExecutable） */
+    runtimes: string[];
+    /** CLI 自身版本（读取 package.json），供服务端展示客户端版本 */
+    version: string;
+}
+/**
+ * daemon 运行状态文件内容（~/.brier/daemon.json）。
+ *
+ * 前台 CLI 与 daemon 子进程之间没有 IPC 通道，二者通过该文件 + 信号协作：
+ * - 前台 DaemonManager：启动时写入（ready=false），轮询 ready 做就绪握手；
+ * - daemon 子进程（Runner）：配置加载成功进入运行后置 ready=true，
+ *   启动早期失败时写 bootError，隧道状态变化时更新 tunnelState；
+ * - 前台 status/restart：读取展示与回退（serverUrl）。
+ *
+ * 身份校验：以 pid + 进程命令行（含 DaemonRunner）双重匹配，
+ * 避免 PID 被系统复用后误判/误杀其他进程。
+ */
+export interface DaemonState {
+    /** daemon 子进程 PID */
+    pid: number;
+    /** 启动时间戳（ms） */
+    startTime: number;
+    /** 启动时连接的服务端地址，restart 未传 --server-url 时回退使用 */
+    serverUrl: string;
+    /** 子进程是否已完成启动（Runner 进入运行循环后置 true） */
+    ready: boolean;
+    /** 启动早期失败原因（仅失败时写入） */
+    bootError?: string;
+    /** 最近一次隧道状态（Runner 随状态机更新，供 status 展示） */
+    tunnelState?: string;
+}

package/types/definitions/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 类型契约统一出口。
+ *
+ * 目录按功能域拆分：
+ * - tunnel.ts：隧道域（线协议 StreamType / ClientMessage / ServerMessage + 连接状态机 TunnelState）
+ * - task.ts：  本地任务执行上下文（消息 → 子进程执行）
+ * - daemon.ts：daemon 装配配置 / 生命周期状态 / PID 文件
+ *
+ * 约定：业务模块一律从本文件（'../definitions/index.js'）导入，不要跨层直接引用子文件，
+ * 以便后续调整目录结构时只需改这里，不动各调用方。
+ */
+/** 隧道域：输出流来源、线协议上行/下行消息、连接状态机 */
+export type { StreamType, ClientMessage, ServerMessage, TunnelState } from './tunnel.js';
+/** 本地任务执行上下文（TaskExecutor 入参） */
+export type { TaskInfo } from './task.js';
+/** daemon 生命周期相关：DaemonStatus / DaemonConfig / DaemonState */
+export type { DaemonStatus, DaemonConfig, DaemonState } from './daemon.js';

package/types/definitions/task.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 本地任务执行上下文。
+ *
+ * TunnelClient 收到下行 task-start 消息后，将其转换为本结构交给
+ * TaskExecutor.execute() 执行——是“隧道传输形态”（ServerMessage）
+ * 与“子进程执行形态”之间的进程内中间对象，不上报服务端。
+ */
+export interface TaskInfo {
+    taskId: string;
+    /** 所属 AI runtime 名称；command 模式为空串 */
+    runtime: string;
+    /**
+     * 可执行命令：
+     * - command 模式：服务端下发的显式 shell 命令
+     * - runtime 模式：由 resolveRuntimeExecutable 解析为绝对路径（保证脱离受限 PATH 也能 spawn）
+     */
+    command: string;
+    args: string[];
+    /** 子进程工作目录（可选） */
+    cwd?: string;
+    /** 注入子进程的额外环境变量（可选） */
+    env?: Record<string, string>;
+    /** 自然语言指令（可选）：存在时按 RUNTIME_PROMPT_FLAGS 拼到命令参数中执行 */
+    prompt?: string;
+}

package/types/definitions/tunnel.d.ts

@@ -0,0 +1,112 @@
+/**
+ * 隧道域类型（daemon ⇄ Brier 服务端 的连接与消息）。
+ *
+ * 聚合三组归属不同的类型：
+ * 1. StreamType / ClientMessage / ServerMessage：线协议（WebSocket JSON 文本帧），
+ *    与服务端 Rust `brier_type::tunnel::*` 镜像，任何命名/字段改动两端必须同步；
+ * 2. TunnelState：daemon 进程内的连接状态机（服务端无对应，不上报）。
+ */
+/**
+ * 任务输出流的来源。
+ *
+ * 由 daemon 的 TaskExecutor 转发子进程输出时标记（stdout / stderr），
+ * 随上行消息 task-output 一并上报给服务端。
+ *
+ * 注意：序列化值需与服务端 Rust 侧 `brier_type::tunnel::StreamType` 保持一致（lowercase），
+ * 新增流类型时两端必须同步修改。
+ */
+export type StreamType = 'stdout' | 'stderr';
+/**
+ * 隧道线协议消息（daemon ⇄ Brier 服务端，WebSocket JSON 文本帧）。
+ *
+ * 使用可辨识联合：以 `type` 字段区分消息，type 值为 kebab-case（如 task-output / auth-ok），
+ * 字段名为 camelCase。与服务端 Rust `brier_type::tunnel::{ClientMessage, ServerMessage}`
+ * 经 serde（tag="type", rename_all="kebab-case" + 字段 rename）逐字段对齐，
+ * 任何一端新增/删除字段或改动命名时，另一端必须同步修改，否则 JSON 解析会失败或丢字段。
+ */
+/**
+ * 上行消息（daemon → 服务端）。
+ *
+ * - auth：连接建立后的第一条鉴权消息；token 同时通过 wss Authorization 头携带（双通道，服务端以 header 为准）
+ * - heartbeat：应用层心跳，触发服务端落库 last_seen_at 并回执 heartbeat-ack
+ * - task-output：任务实时输出；当前实现为 stdout/stderr 每收到一个数据块即发一条
+ * - task-complete：子进程正常退出（exitCode 为进程退出码）
+ * - task-error：执行失败（如找不到可执行文件、超过并发上限）
+ * - runtime-info：runtime 清单上报（服务端目前仅记录日志，属预留能力）
+ */
+export type ClientMessage = {
+    type: 'auth';
+    token: string;
+    hostname: string;
+    os: string;
+    runtimes: string[];
+    /** CLI 自身版本（package.json），旧版客户端可能不带该字段 */
+    version?: string;
+} | {
+    type: 'heartbeat';
+    timestamp: number;
+} | {
+    type: 'task-output';
+    taskId: string;
+    stream: StreamType;
+    data: string;
+} | {
+    type: 'task-complete';
+    taskId: string;
+    exitCode: number;
+} | {
+    type: 'task-error';
+    taskId: string;
+    error: string;
+} | {
+    type: 'runtime-info';
+    runtimes: string[];
+};
+/**
+ * 下行消息（服务端 → daemon）。
+ *
+ * - auth-ok：鉴权通过并完成注册，computerId 为本机在服务端的工作电脑 ID
+ * - auth-failed：鉴权失败（令牌无效等），reason 为失败原因
+ * - heartbeat-ack：心跳回执（echo 客户端发送的 timestamp）
+ * - task-start：下发任务执行；prompt 模式由 CLI 按 runtime 拼参数，command 模式直接执行
+ * - task-cancel：请求终止正在执行的子进程（SIGTERM）
+ * - query-runtimes：查询本机 runtime 清单（当前服务端不会主动发送，属预留；CLI 保留处理以兼容旧服务端）
+ */
+export type ServerMessage = {
+    type: 'auth-ok';
+    computerId: string;
+} | {
+    type: 'auth-failed';
+    reason: string;
+} | {
+    type: 'heartbeat-ack';
+    timestamp: number;
+} | {
+    type: 'task-start';
+    taskId: string;
+    /** 所属 AI runtime 名称（如 Claude Code / OpenCode）；command 模式为空串 */
+    runtime: string;
+    /** 可执行命令：command 模式为显式命令；runtime 模式为空，由 CLI 探测解析 */
+    command: string;
+    args: string[];
+    /** 子进程工作目录（可选） */
+    cwd?: string;
+    /** 注入子进程的额外环境变量（可选） */
+    env?: Record<string, string>;
+    /** 自然语言指令（可选）：存在时按 RUNTIME_PROMPT_FLAGS 拼入执行参数 */
+    prompt?: string;
+} | {
+    type: 'task-cancel';
+    taskId: string;
+} | {
+    type: 'query-runtimes';
+};
+/**
+ * 隧道连接状态机。
+ *
+ * 仅存在于 daemon 进程内（TunnelClient 内部维护、DaemonRunner 订阅打印），不上报服务端：
+ * connecting（握手）→ connected（收到 auth-ok）→ 断线进入 reconnecting；
+ * 收到 auth-failed 或重连次数耗尽（50 次退避上限）时进入 error 并停止，
+ * 主动 stop 时进入 disconnected。
+ */
+export type TunnelState = 'connecting' | 'connected' | 'disconnected' | 'reconnecting' | 'error';

package/types/tunnel/backoff.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 重连退避策略（纯逻辑，无 IO、无副作用）。
+ *
+ * 与原实现的等价行为：指数退避（1s 起步、封顶 maxMs），累计 maxAttempts 次后放弃。
+ * next() 返回 -1 表示“已耗尽、应停止重连”；attempts 仅供日志展示尝试次数。
+ */
+export interface BackoffOptions {
+    /** 基础延迟（ms），首次重连即使用该值 */
+    baseMs: number;
+    /** 延迟封顶（ms） */
+    maxMs: number;
+    /** 最大重连尝试次数，达到后放弃 */
+    maxAttempts: number;
+    /**
+     * 是否启用 full jitter：在 [0, 计算延迟] 内取随机值，
+     * 避免大量客户端同时断线后以完全相同的节奏重连（重连风暴）。
+     * 默认开启。
+     */
+    jitter?: boolean;
+}
+export interface Backoff {
+    /**
+     * 计算下一次等待毫秒数。
+     * 已尝试次数达到 maxAttempts 时返回 -1（调用方应停止重连）。
+     */
+    next(): number;
+    /** 已排定/已执行的尝试次数（供日志与判断） */
+    readonly attempts: number;
+    /** 连接成功后归零 */
+    reset(): void;
+}
+export declare const createBackoff: (options: BackoffOptions) => Backoff;

package/types/tunnel/dispatcher.d.ts

@@ -0,0 +1,26 @@
+import type { ServerMessage } from '../definitions/index.js';
+/**
+ * 服务端下行消息解析与分发。
+ *
+ * 只做两件事：把 WS 文本帧 JSON.parse 成 ServerMessage，再按 type 分发给对应回调。
+ * 不接触 ws、状态机或执行器——骨架通过回调把“协议 → 业务动作”接起来，
+ * 本模块因此不依赖网络与运行状态，职责保持单一。
+ */
+export interface ServerMessageHandlers {
+    /** 鉴权通过（携带服务端分配的工作电脑 ID） */
+    onAuthOk: (computerId: string) => void;
+    /** 鉴权失败（reason 为原因） */
+    onAuthFailed: (reason: string) => void;
+    /** 心跳回执 */
+    onHeartbeatAck: (timestamp: number) => void;
+    /** 任务下发 */
+    onTaskStart: (message: Extract<ServerMessage, {
+        type: 'task-start';
+    }>) => void;
+    /** 任务取消 */
+    onTaskCancel: (taskId: string) => void;
+    /** 服务端查询本机 runtime 清单 */
+    onQueryRuntimes: () => void;
+}
+/** 解析并分发一条服务端消息；JSON 解析失败或未知 type 记日志后静默返回。 */
+export declare const dispatchServerMessage: (raw: string, handlers: ServerMessageHandlers) => void;

package/types/tunnel/heartbeat.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 应用层心跳策略。
+ *
+ * 只负责节奏：到点调用 onBeat() 发送心跳；onBeat 返回 true（已发出）时启动
+ * ack 超时计时，收到 ack 由调用方调 ack() 解除；超时触发 onTimeout()。
+ * 本模块“只上报不决策”——超时后如何处理（如关闭连接）由上层骨架决定。
+ *
+ * 注意：每次触发心跳前先清理上一次的 ack 超时计时器，避免重复计时器叠加。
+ */
+export interface HeartbeatOptions {
+    /** 心跳发送间隔（ms） */
+    intervalMs: number;
+    /** 等待 ack 的超时（ms） */
+    timeoutMs: number;
+    /**
+     * 心跳发送回调。返回是否已真正发出（连接未打开时返回 false，
+     * 此时不启动 ack 超时计时）。
+     */
+    onBeat: () => boolean;
+    /** ack 超时（对端无响应）回调，由上层决定如何处置 */
+    onTimeout: () => void;
+    /**
+     * onBeat 抛错时的回调（可选）。setInterval 回调中的异常会作为
+     * uncaughtException 直接杀死进程，因此 beat() 内部必须吞掉。
+     */
+    onBeatError?: (error: unknown) => void;
+}
+export interface Heartbeat {
+    /** 启动心跳（幂等：先停止已有计时器再开始） */
+    start(): void;
+    /** 停止心跳并清理所有计时器 */
+    stop(): void;
+    /** 收到 ack 时调用：解除当前 ack 超时计时 */
+    ack(): void;
+}
+export declare const createHeartbeat: (options: HeartbeatOptions) => Heartbeat;