@brierb/brier-cli 0.0.6 → 0.0.8

package/dist/tunnel/index.js

@@ -0,0 +1,220 @@
+import { toWsUrl } from './url.js';
+import { logger } from '../core/index.js';
+import { createBackoff } from './backoff.js';
+import { dispatchServerMessage } from './dispatcher.js';
+import { createHeartbeat } from './heartbeat.js';
+import { createWebSocketTransport } from './transport.js';
+const HEARTBEAT_INTERVAL_MS = 30_000;
+const HEARTBEAT_TIMEOUT_MS = 10_000;
+/** auth 消息发出后等待 auth-ok/auth-failed 的最长时间，超时视为握手失败并重连 */
+const AUTH_HANDSHAKE_TIMEOUT_MS = 10_000;
+const BASE_RECONNECT_DELAY_MS = 1_000;
+const MAX_RECONNECT_DELAY_MS = 30_000;
+const MAX_RECONNECT_ATTEMPTS = 50;
+/**
+ * 隧道骨架：连接生命周期编排与状态仲裁的唯一入口。
+ *
+ * 本文件只做“编排”，不接触 ws 细节、不算退避、不解析消息：
+ * - transport：负责底层连接与收发帧
+ * - heartbeat：负责心跳节奏（只上报不决策）
+ * - backoff：负责重连延迟计算（纯逻辑）
+ * - dispatcher：负责服务端消息解析与分发
+ *
+ * 关键时序不变式（重构后保持与原实现一致）：
+ * 1. 心跳仅在 auth-ok 后启动；
+ * 2. close 后仅当 running 才退避重连，stop() 后绝不再连；
+ * 3. 仅 auth-ok 归零退避计数；
+ * 4. stop 时先优雅 close，3s 兜底 terminate。
+ */
+export const createTunnelClient = (config, messageHandlers) => {
+    const transport = createWebSocketTransport();
+    const backoff = createBackoff({
+        baseMs: BASE_RECONNECT_DELAY_MS,
+        maxMs: MAX_RECONNECT_DELAY_MS,
+        maxAttempts: MAX_RECONNECT_ATTEMPTS,
+    });
+    let state = 'disconnected';
+    let running = false;
+    let reconnectTimer = null;
+    /** auth 握手超时计时器（open 后启动，auth-ok/auth-failed/close 时清除） */
+    let handshakeTimer = null;
+    /**
+     * 本次运行是否以“错误”终止（auth 失败 / 重连耗尽）。
+     * 区分于 stop() 的正常停止：保证随后的 close 事件不把 error 覆盖成 disconnected。
+     */
+    let exitAsError = false;
+    const listeners = new Set();
+    const notifyStateChange = (newState) => {
+        state = newState;
+        for (const callback of listeners) {
+            callback(newState);
+        }
+    };
+    const onStateChange = (callback) => {
+        listeners.add(callback);
+        return () => {
+            listeners.delete(callback);
+        };
+    };
+    const getState = () => state;
+    const send = (message) => transport.send(JSON.stringify(message));
+    const sendHeartbeat = () => send({ type: 'heartbeat', timestamp: Date.now() });
+    const clearHandshakeTimer = () => {
+        if (handshakeTimer) {
+            clearTimeout(handshakeTimer);
+            handshakeTimer = null;
+        }
+    };
+    /**
+     * 启动握手超时：若服务端不回 auth-ok/auth-failed，10s 后主动断开走重连，
+     * 避免永久停留在 connecting（此时心跳尚未启动，无其他自愈路径）。
+     */
+    const armHandshakeTimeout = () => {
+        clearHandshakeTimer();
+        handshakeTimer = setTimeout(() => {
+            logger.warn('Auth handshake timed out, reconnecting');
+            transport.close(4000, 'auth timeout');
+        }, AUTH_HANDSHAKE_TIMEOUT_MS);
+    };
+    const heartbeat = createHeartbeat({
+        intervalMs: HEARTBEAT_INTERVAL_MS,
+        timeoutMs: HEARTBEAT_TIMEOUT_MS,
+        onBeat: sendHeartbeat,
+        onTimeout: () => {
+            logger.warn('Heartbeat timeout, forcing reconnect');
+            transport.close(4000, 'heartbeat timeout');
+        },
+        onBeatError: (error) => {
+            logger.error('Heartbeat send failed:', error);
+        },
+    });
+    const connect = () => {
+        logger.info('Connecting to', toWsUrl(config.serverUrl));
+        notifyStateChange('connecting');
+        transport.connect(toWsUrl(config.serverUrl), {
+            Authorization: `Bearer ${config.token}`,
+            'X-Brier-Hostname': config.hostname,
+            'X-Brier-OS': config.os,
+        });
+    };
+    const scheduleReconnect = () => {
+        if (!running)
+            return;
+        const delay = backoff.next();
+        if (delay < 0) {
+            logger.error('Max reconnect attempts reached, stopping');
+            exitAsError = true;
+            running = false;
+            notifyStateChange('error');
+            return;
+        }
+        logger.info(`Reconnecting in ${(delay / 1000).toFixed(0)}s (attempt ${backoff.attempts}/${MAX_RECONNECT_ATTEMPTS})`);
+        notifyStateChange('reconnecting');
+        reconnectTimer = setTimeout(() => {
+            if (running) {
+                connect();
+            }
+        }, delay);
+    };
+    const dispatchHandlers = {
+        onAuthOk: (computerId) => {
+            clearHandshakeTimer();
+            logger.info('Tunnel authenticated, computerId:', computerId);
+            backoff.reset();
+            notifyStateChange('connected');
+            heartbeat.start();
+        },
+        onAuthFailed: (reason) => {
+            clearHandshakeTimer();
+            logger.error('Authentication failed:', reason);
+            exitAsError = true;
+            running = false;
+            notifyStateChange('error');
+        },
+        onHeartbeatAck: () => {
+            heartbeat.ack();
+        },
+        onTaskStart: (message) => {
+            logger.info('Task start:', message.taskId, message.command);
+            messageHandlers.onTaskStart(message);
+        },
+        onTaskCancel: (taskId) => {
+            logger.info('Task cancel:', taskId);
+            messageHandlers.onTaskCancel(taskId);
+        },
+        onQueryRuntimes: () => {
+            send({ type: 'runtime-info', runtimes: config.runtimes });
+        },
+    };
+    // 传输事件 → 骨架仲裁（订阅一次，跨多次重连保持有效）
+    transport.on('open', () => {
+        logger.info('WebSocket connected, authenticating...');
+        send({
+            type: 'auth',
+            token: config.token,
+            hostname: config.hostname,
+            os: config.os,
+            runtimes: config.runtimes,
+            version: config.version,
+        });
+        armHandshakeTimeout();
+    });
+    transport.on('message', (data) => dispatchServerMessage(data, dispatchHandlers));
+    transport.on('close', (code, reason) => {
+        const reasonStr = reason || `code ${code}`;
+        logger.warn(`WebSocket closed: ${reasonStr}`);
+        clearHandshakeTimer();
+        heartbeat.stop();
+        if (running) {
+            scheduleReconnect();
+        }
+        else {
+            // 失败停机（auth 失败/重连耗尽）保持 error，正常 stop 才是 disconnected
+            notifyStateChange(exitAsError ? 'error' : 'disconnected');
+        }
+    });
+    transport.on('error', (err) => {
+        logger.error('WebSocket error:', err);
+    });
+    const start = () => {
+        if (running) {
+            logger.warn('Tunnel is already running');
+            return;
+        }
+        running = true;
+        exitAsError = false;
+        backoff.reset();
+        connect();
+    };
+    const stop = async () => {
+        running = false;
+        heartbeat.stop();
+        clearHandshakeTimer();
+        // 取消运行中任务由宿主（DaemonRunner）在自身 shutdown 里处理，隧道只负责关闭连接
+        if (reconnectTimer) {
+            clearTimeout(reconnectTimer);
+            reconnectTimer = null;
+        }
+        // 连接已完全关闭（从未连接/已断开/已 teardown）：close 事件不会再触发，
+        // 直接返回，避免空等 waitClosed 的 3s 兜底超时。
+        if (transport.isClosed()) {
+            notifyStateChange('disconnected');
+            logger.info('Tunnel stopped');
+            return;
+        }
+        transport.close(1000, 'client shutdown');
+        await transport.waitClosed(3000);
+        if (transport.isOpen() || transport.isConnecting()) {
+            transport.terminate();
+        }
+        notifyStateChange('disconnected');
+        logger.info('Tunnel stopped');
+    };
+    return {
+        start,
+        stop,
+        send,
+        getState,
+        onStateChange,
+    };
+};

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.6",
+  "version": "0.0.8",
   "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/core/runtimes.d.ts

@@ -0,0 +1,29 @@
+export interface RuntimeEntry {
+    name: string;
+    command: string;
+    /** 命令不在 PATH 时的兜底可执行文件（~ 开头表示用户主目录），存在即视为已安装 */
+    fallbacks?: readonly string[];
+}
+export declare const RUNTIME_REGISTRY: readonly RuntimeEntry[];
+export declare const RUNTIME_COMMANDS: Record<string, string>;
+/**
+ * AI runtime 单次（非交互）执行参数模板：命令前缀 flags，后面紧跟 prompt。
+ * 服务端 task-start 携带 prompt 时，CLI 用它拼出
+ * `spawn(<command>, [...flags, prompt])`；未列出的 runtime 按裸参数执行。
+ */
+export declare const RUNTIME_PROMPT_FLAGS: Record<string, readonly string[]>;
+/**
+ * 解析 runtime 的可执行文件**绝对路径**：
+ * 1. PATH 中查找（排除系统目录误报，如 /usr/sbin/gpt）
+ * 2. 未命中则检查官方安装目录（如 opencode → ~/.opencode/bin/opencode）
+ *
+ * 探测（runtimes 上报）与执行（spawn 任务）都走这里，保证"探测到"的
+ * 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';