nx-ce 0.1.3 → 0.1.4

package/README.md

@@ -4,12 +4,12 @@
 [![CI](https://github.com/joke-lx/nx-ce/actions/workflows/npm-publish.yml/badge.svg)](https://github.com/joke-lx/nx-ce/actions/workflows/npm-publish.yml)
 
 **nx-ce** 是一个轻量级 Node.js 适配器，封装了 `@anthropic-ai/claude-agent-sdk`。
-通过长度前缀的 JSON 协议（与 Chrome Native Messaging 格式一致）在 stdin/stdout 上暴露 SDK 接口，
-支持一次性冷启动查询与持久化服务两种运行模式。
+通过长度前缀的 JSON 协议在 stdin/stdout 上暴露 SDK 接口，
+支持一次性冷启动查询与 WebSocket 持久化服务器两种运行模式。
 
 **nx-ce** is a lightweight Node.js adapter for `@anthropic-ai/claude-agent-sdk`.
-It exposes the SDK over stdin/stdout via a length-prefixed JSON protocol (identical to Chrome native messaging),
-supporting both one-shot cold-start queries and persistent serve sessions.
+It exposes the SDK via a WebSocket server or stdin/stdout protocol,
+supporting both one-shot cold-start queries and persistent server sessions.
 
 ---
 
@@ -55,23 +55,27 @@ nx-ce query "Analyze" --skill all
 | `--no-persist` | 不持久化会话 / Don't persist session |
 | `--env "KEY=value,KEY2=val"` | 额外环境变量 / Extra environment variables |
 
-### `nx-ce serve` — 持久化管理器进程 / Persistent manager process
+### `nx-ce serve` — WebSocket 持久化服务器 / WebSocket server
+
+单例进程，多客户端共享一个 SDK 会话，请求排队处理。
+Single process with multi-client support and FIFO query queue.
 
 ```bash
+nx-ce serve                     # 默认端口 3100
+nx-ce serve --port 3100         # 指定端口
 nx-ce serve --name chat-tab-1
-nx-ce serve --name default --model claude-sonnet-4-6
 ```
 
-通过 stdin/stdout 接收 4B+JSON 协议消息，保持一个持久化的 SDK 会话。
-Reads/writes 4B+JSON protocol messages over stdin/stdout, maintaining a persistent SDK session.
-
 | 选项 / Flag | 说明 / Description |
 |-------------|-------------------|
 | `--name <name>` | 实例名称（默认 `"default"`）/ Instance name |
+| `--port <port>` | WebSocket 端口（默认 `3100`）/ WebSocket port |
 | `--model <id>` | 模型 ID 覆盖 / Model override |
 | `--claude-path <path>` | Claude CLI 可执行文件路径 / Path to Claude CLI binary |
 | `--env "KEY=value,..."` | 额外环境变量 / Extra environment variables |
 
+> WebSocket 地址: `ws://127.0.0.1:3100`
+
 ### `nx-ce status` — 查看实例状态 / Show instance state
 
 ```bash
@@ -87,60 +91,96 @@ nx-ce help
 
 ---
 
-## 协议 / Protocol
+## WebSocket 协议 / WebSocket Protocol
+
+服务端地址 `ws://127.0.0.1:PORT`（默认 3100）。所有消息均为 JSON 字符串（不含长度前缀）。
+
+Server at `ws://127.0.0.1:PORT` (default 3100). All messages are JSON strings (no length prefix).
 
-所有 IPC 使用与 Chrome Native Messaging 一致的线缆格式：
+### 客户端发送 / Client → Server
 
-All IPC uses the same wire format as Chrome native messaging:
+| type | 字段 / Fields | 说明 / Description |
+|------|---------------|-------------------|
+| `query` | `prompt: string`, `id?: string` | 发起查询 / Submit a query |
+| `ping` | 无 | 心跳检测 / Heartbeat |
+| `getSkills` | 无 | 拉取技能/工具列表 / Fetch skills & tools |
 
+```json
+→ { "type": "query", "prompt": "解释这段代码" }
+→ { "type": "ping" }
+→ { "type": "getSkills" }
 ```
-[4 bytes LE uint32 = 负载长度 / payload length][UTF-8 JSON payload]
+
+### 服务端发送 / Server → Client
+
+**连接建立 / On connect:**
+
+```json
+← { "type": "connected", "sessionId": "sess_xxx", "port": 3100 }
+← { "type": "init", "sessionId": "sess_xxx", "model": "claude-sonnet-4-6",
+    "skills": [...], "tools": [...], "slashCommands": [...], "agents": [...] }
 ```
 
-### 查询（一次性）/ Query (one-shot)
+**查询响应 / Query response (streamed chunks):**
 
+```json
+← { "type": "text",     "content": "这是一段回复..." }
+← { "type": "thinking", "content": "模型思考过程..." }
+← { "type": "tool_use", "name": "readFile", "input": {...}, "id": "toolu_xxx" }
+← { "type": "done",     "sessionId": "sess_xxx" }
 ```
-→ { "prompt": "...", "model": "...", "systemPrompt": "..." }
-← { "text": "...", "sessionId": "sess_xxx" }
 
-# 加 --include-metadata 时返回 metadata
-# With --include-metadata, response includes metadata:
-← { "text": "...", "sessionId": "sess_xxx", "metadata": { "skills": [...], "tools": [...], "slashCommands": [...] } }
+**其他 / Other:**
+
+```json
+← { "type": "pong",  "sessionId": "sess_xxx" }
+← { "type": "skills", "skills": [...], "tools": [...], "slashCommands": [...], "agents": [...] }
+← { "type": "error", "content": "error message" }
 ```
 
-### 服务（持久化）/ Serve (persistent)
+### 完整示例 / Full exchange
 
 ```
-→ { "id":"1", "type":"query", "prompt":"..." }
-← { "id":"1", "type":"text", "content":"..." }
-← { "id":"1", "type":"tool_use", "name":"readFile", "input":{...} }
-← { "id":"1", "type":"thinking", "content":"..." }
-← { "id":"1", "type":"done", "sessionId":"..." }
+→ { "type": "query", "prompt": "Hello" }
+← { "type": "text",     "content": "Hello! How can I help you today?" }
+← { "type": "done",     "sessionId": "sess_abc123" }
 
-→ { "type":"ping" }
-← { "type":"pong", "sessionId":"..." }
+→ { "type": "ping" }
+← { "type": "pong",     "sessionId": "sess_abc123" }
+```
 
-→ { "type":"getSkills" }
-← { "type":"skills", "skills":["browse",...], "tools":["Read",...], "slashCommands":[...], "agents":[...] }
+### 单例机制 / Singleton guarantee
 
-(首次 init 自动推送)
-← { "type":"init", "skills":[...], "tools":[...], ... }
+重复启动 `nx-ce serve` 会在同一端口上失败：
+
+```
+端口 3100 已被占用 — nx-ce 单例进程已在运行中
+Port 3100 already in use — another nx-ce instance is running
 ```
 
-协议消息类型 / Message types:
+---
+
+## 协议 / Protocol (stdin/stdout)
+
+`nx-ce query` 子命令仍使用长度前缀 JSON（Chrome Native Messaging 格式）：
+
+```
+[4 bytes LE uint32 = 负载长度 / payload length][UTF-8 JSON payload]
+```
 
-| 方向 / Dir | type | 说明 / Description |
-|------------|------|-------------------|
-| → | `query` | 用户输入 / User input |
-| ← | `text` | 文本回复 / Text response |
-| ← | `tool_use` | 工具调用请求 / Tool use request |
-| ← | `thinking` | 思考过程 / Model thinking |
-| ← | `done` | 本轮完成，含会话 ID / Turn complete with session ID |
-| ← | `error` | 错误消息 / Error message |
-| → | `ping` | 心跳检测 / Heartbeat |
-| ← | `pong` | 心跳回复 / Heartbeat response |
-| → | `getSkills` | Go 端按需拉取技能/工具列表 / Fetch skills/tools list |
-| ← | `init` / `skills` | 技能列表回复 / Skills metadata response |
+### 查询（一次性）/ Query (one-shot)
+
+```
+→ { "prompt": "...", "model": "...", "systemPrompt": "..." }
+← { "text": "...", "sessionId": "sess_xxx" }
+```
+
+### 带元数据输出 / With metadata
+
+```
+← { "text": "...", "sessionId": "sess_xxx",
+    "metadata": { "skills": [...], "tools": [...], "slashCommands": [...] } }
+```
 
 ---
 
@@ -148,10 +188,8 @@ All IPC uses the same wire format as Chrome native messaging:
 
 ```
 Chrome Extension / 浏览器扩展
-       ↕ Native Messaging (4B+JSON)
-Native Host (Go)
-       ↕ 4B+JSON (via executor.startProcess)
-nx-ce serve (Node.js)
+       ↕ WebSocket (ws://127.0.0.1:3100)
+nx-ce serve (Node.js)   ← 单例进程 / singleton process
        ↕ @anthropic-ai/claude-agent-sdk
 Claude Code CLI (子进程 / subprocess)
 ```
@@ -165,8 +203,6 @@ Claude Code CLI (子进程 / subprocess)
 
 Persisted to `~/.nx-ce/instances/{name}.json`. Each named instance stores its PID, session ID, and start time for crash recovery and session resumption.
 
-示例状态文件 / Example state file:
-
 ```json
 {
   "name": "chat-tab-1",
@@ -182,9 +218,12 @@ Persisted to `~/.nx-ce/instances/{name}.json`. Each named instance stores its PI
 ## 开发 / Development
 
 ```bash
-# 本地运行 / Run locally
+# 本地运行一次查询 / Run a one-shot query
 node ./bin/nx-ce.js query "你好"
 
+# 启动 WebSocket 服务 / Start WebSocket server
+node ./bin/nx-ce.js serve --port 3100
+
 # 检查语法 / Check syntax
 node -c src/*.js
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nx-ce",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Claude Engine — SDK adapter layer for native messaging host. Bridges @anthropic-ai/claude-agent-sdk calls over a length-prefixed JSON protocol.",
   "type": "module",
   "main": "src/index.js",
@@ -30,6 +30,7 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.159"
+    "@anthropic-ai/claude-agent-sdk": "^0.3.159",
+    "ws": "^8.21.0"
   }
 }

package/src/cli.js

@@ -83,7 +83,7 @@ export async function runCli() {
     }
 
     case 'serve': {
-      // 持久化服务模式
+      // WebSocket 持久化服务模式
       const name = flags.name || 'default';
 
       const result = await startServe({
@@ -92,6 +92,7 @@ export async function runCli() {
         model: flags.model,
         cwd: flags.cwd || process.cwd(),
         env: flags.env ? parseEnvString(flags.env) : undefined,
+        port: flags.port ? parseInt(flags.port, 10) : undefined,
       });
 
       return result;
@@ -132,8 +133,9 @@ export async function runCli() {
     --no-persist                  不持久化会话
     --env "KEY=value,KEY2=val"    额外环境变量
 
-  nx-ce serve                     持久化管理器进程（stdin/stdout）
+  nx-ce serve                     WebSocket 持久化服务器（单一进程 / 多客户端）
     --name <name>                 实例名称（默认: "default"）
+    --port <port>                 WebSocket 端口（默认: 3100）
     --model <id>                  模型覆盖
     --claude-path <path>          Claude CLI 路径
     --env "KEY=value,..."         额外环境变量

package/src/index.js

@@ -8,5 +8,13 @@
 
 export { runQuery } from './query.js';
 export { listSkills } from './skills.js';
-export { readState, writeState, deleteState, listStates } from './session-store.js';
+export {
+  readState,
+  writeState,
+  deleteState,
+  listStates,
+  LifecycleState,
+  createState,
+} from './session-store.js';
 export { readMessage, writeMessage } from './protocol.js';
+export { generateId, MonotonicClock, getMachineId, formatBytes } from './util.js';

package/src/serve.js

@@ -1,241 +1,596 @@
 /**
- * 服务端 — 持久化管理器进程
+ * 服务端 — WebSocket 持久化服务器，支持多会话管理
  *
- * 通过 stdin/stdout 运行，使用 4B+JSON 格式协议。
- * 每个实例维护一个持久化的 agentQuery() 会话。
+ * 单例进程，对外提供 WebSocket 接口。
+ * 每个会话（session）拥有独立的 agentQuery()、MessageChannel 和状态文件，
+ * 天然并行，互不阻塞。
  *
- * 协议消息（与 native_host/protocol.go 线缆格式一致）：
- *   → { "id":"...", "type":"query", "prompt":"..." }
- *   ← { "id":"...", "type":"text", "content":"..." }
- *   ← { "id":"...", "type":"done", "sessionId":"..." }
- *   ← { "id":"...", "type":"error", "content":"..." }
- *   → { "type":"ping" }
- *   ← { "type":"pong", "sessionId":"..." }
- *   → { "type":"getSkills" }
- *   ← { "type":"skills", "skills":[...], "tools":[...], ... }
+ * 竞态保护：
+ *   - session 创建：pendingCreates Map 防止重复创建
+ *   - client 绑定：SDK 回复只写 session.client，不走 broadcast
+ *   - state 文件：每个 session 独立文件，写锁防并发
+ *   - 消息排序：每个 session 独立单调时钟
  */
 
+import { WebSocketServer } from 'ws';
 import { query as agentQuery } from '@anthropic-ai/claude-agent-sdk';
-import { readMessage, writeMessage } from './protocol.js';
-import { readState, writeState, deleteState } from './session-store.js';
+import { hostname, machine, platform, release } from 'node:os';
+import { readState, writeState, deleteState, LifecycleState, createState } from './session-store.js';
+import { generateId, MonotonicClock, getMachineId } from './util.js';
 
-/**
- * 启动一个持久化服务会话。
- * 从 stdin 读取，向 stdout 写入，持续运行直到 stdin 关闭。
- */
-export async function startServe(options) {
-  const { name, claudePath, model, cwd, env } = options;
-
-  // 检查是否有可恢复的会话状态
-  const existingState = readState(name);
-
-  // 组装 SDK 选项
-  const sdkOptions = {
-    cwd: cwd || process.cwd(),
-    model: model || 'claude-sonnet-4-6',
-    pathToClaudeCodeExecutable: claudePath,
-    permissionMode: 'bypassPermissions', // 跳过权限确认
-    allowDangerouslySkipPermissions: true,
-    env: { ...process.env, ...env },
-  };
-
-  // 如果存在之前的会话 ID，恢复会话
-  if (existingState?.sessionId) {
-    sdkOptions.resume = existingState.sessionId;
+/** 默认端口 */
+const DEFAULT_PORT = 3100;
+
+/** 空闲 session 超时（毫秒），超过此时间无客户端则自动关闭 */
+const SESSION_IDLE_TIMEOUT_MS = 300_000; // 5 分钟
+
+// =================================================================
+// SessionManager — 管理多个独立 SDK 会话
+// =================================================================
+
+class SessionManager {
+  constructor(serverOptions) {
+    this.serverOptions = serverOptions; // { claudePath, model, cwd, env }
+
+    /** @type {Map<string, Session>} */
+    this.sessions = new Map();
+
+    /** 创建中的 Promise，防止并发创建同名 session */
+    this._pendingCreates = new Map();
+
+    /** 清理定时器 */
+    this._idleTimers = new Map();
+
+    /** 会话状态文件写锁 */
+    this._writeLocks = new Map();
+  }
+
+  /**
+   * 获取或创建一个 session。
+   * 如果另一个协程正在创建同名 session，则等待其完成。
+   *
+   * @param {string} name - session 名称（每个客户端/标签页唯一）
+   * @returns {Promise<Session>}
+   */
+  async getOrCreate(name) {
+    // 已有活跃 session → 直接返回
+    const existing = this.sessions.get(name);
+    if (existing && !existing.closed) {
+      // 取消 idle 定时器（客户端回来了）
+      this._cancelIdleTimer(name);
+      return existing;
+    }
+
+    // 正在被另一个协程创建 → 等它
+    if (this._pendingCreates.has(name)) {
+      return this._pendingCreates.get(name);
+    }
+
+    // 创建锁 + 创建
+    const promise = this._createSession(name);
+    this._pendingCreates.set(name, promise);
+
+    try {
+      return await promise;
+    } finally {
+      this._pendingCreates.delete(name);
+    }
+  }
+
+  /**
+   * 创建内部 session 结构。
+   * 注意：JS 是单线程 event loop，此函数不会被并发调用（pendingCreates 保证）。
+   */
+  async _createSession(name) {
+    const { claudePath, model, cwd, env } = this.serverOptions;
+
+    // 检查是否有可恢复的会话状态
+    const existingState = readState(name);
+
+    // 组装 SDK 选项
+    const sdkOptions = {
+      cwd: cwd || process.cwd(),
+      model: model || 'claude-sonnet-4-6',
+      pathToClaudeCodeExecutable: claudePath,
+      permissionMode: 'bypassPermissions',
+      allowDangerouslySkipPermissions: true,
+      env: { ...process.env, ...env },
+    };
+
+    if (existingState?.sessionId) {
+      sdkOptions.resume = existingState.sessionId;
+    }
+
+    // 消息通道 — SDK 从此处拉取下一条用户消息
+    const pendingMessages = [];
+    let resolveNext = null;
+    let turnActive = false;
+    let channelClosed = false;
+
+    const messageChannel = {
+      [Symbol.asyncIterator]() {
+        return {
+          next: () => {
+            while (pendingMessages.length > 0 && !turnActive) {
+              turnActive = true;
+              return Promise.resolve({ value: pendingMessages.shift(), done: false });
+            }
+            if (channelClosed) return Promise.resolve({ done: true, value: null });
+            return new Promise((resolve) => { resolveNext = resolve; });
+          },
+        };
+      },
+    };
+
+    function enqueueMessage(sdkUserMessage) {
+      if (resolveNext) {
+        turnActive = true;
+        const r = resolveNext;
+        resolveNext = null;
+        r({ value: sdkUserMessage, done: false });
+      } else if (pendingMessages.length < 8) {
+        pendingMessages.push(sdkUserMessage);
+      }
+    }
+
+    function onTurnComplete() {
+      turnActive = false;
+    }
+
+    // 启动 SDK 持久化查询
+    const response = agentQuery({ prompt: messageChannel, options: sdkOptions });
+
+    /** @type {Session} */
+    const session = {
+      name,
+      messageChannel,
+      enqueueMessage,
+      onTurnComplete,
+      channelClosed: false,
+      closeChannel() {
+        channelClosed = true;
+        if (resolveNext) {
+          const r = resolveNext;
+          resolveNext = null;
+          r({ done: true, value: null });
+        }
+      },
+
+      response,
+      sdkOptions,
+      existingState,
+
+      // 客户端状态
+      client: null,        // 当前绑定的 WebSocket 客户端
+      queue: [],           // 待处理查询 FIFO
+      turnActive: false,   // SDK 是否正在处理
+      currentTurnId: null,
+      processing: false,
+
+      // 元数据
+      sessionId: existingState?.sessionId || null,
+      metadata: null,       // init 消息中的 skills/tools 等
+      clock: new MonotonicClock(),
+      closed: false,
+
+      // 消费 Promise（用于等待关闭）
+      consumerPromise: null,
+
+      // usage 追踪
+      usage: existingState?.usage || {
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheCreationInputTokens: 0,
+        cacheReadInputTokens: 0,
+        contextWindow: 200000,
+        contextTokens: 0,
+      },
+    };
+
+    // 后台消费 SDK 输出
+    session.consumerPromise = this._startConsumer(session);
+
+    this.sessions.set(name, session);
+
+    // 持久化初始状态
+    this._safeWriteState(session);
+
+    return session;
   }
 
-  // 简单的异步消息队列（供 SDK 侧消费方拉取）
-  const pendingMessages = [];  // 待发送消息缓冲区
-  let resolveNext = null;     // 下一轮迭代的 resolve 函数
-  let turnActive = false;     // 当前轮次是否活跃
-  let channelClosed = false;  // 通道是否已关闭
-
-  // 消息通道：作为异步迭代器供 SDK 消费
-  const messageChannel = {
-    [Symbol.asyncIterator]() {
-      return {
-        next: () => {
-          // 有缓冲消息且当前轮次空闲 → 立即返回
-          while (pendingMessages.length > 0 && !turnActive) {
-            turnActive = true;
-            return Promise.resolve({
-              value: pendingMessages.shift(),
-              done: false,
-            });
+  /**
+   * 后台消费循环 — 每个 session 独立。
+   * SDK 回复只会写入 session.client（绑定的 WS 客户端）。
+   */
+  _startConsumer(session) {
+    return (async () => {
+      try {
+        for await (const message of session.response) {
+          // init 消息 → 捕获元数据
+          if (message.type === 'system' && message.subtype === 'init') {
+            session.sessionId = message.session_id;
+            session.metadata = {
+              type: 'init',
+              sessionId: session.sessionId,
+              model: message.model,
+              skills: message.skills || [],
+              tools: message.tools || [],
+              slashCommands: message.slash_commands || [],
+              agents: message.agents || [],
+              time: session.clock.next(),
+            };
+            this._safeWriteState(session);
+
+            // 推给当前绑定的客户端
+            this._send(session.client, session.metadata);
+          }
+
+          // 助手消息 → 分块转发
+          if (message.type === 'assistant' && message.message?.content) {
+            const content = message.message.content;
+            if (typeof content === 'string') {
+              this._send(session.client, { type: 'text', content, time: session.clock.next() });
+            } else if (Array.isArray(content)) {
+              for (const block of content) {
+                if (block.type === 'text') {
+                  this._send(session.client, { type: 'text', content: block.text, time: session.clock.next() });
+                } else if (block.type === 'tool_use') {
+                  this._send(session.client, { type: 'tool_use', name: block.name, input: block.input, id: block.id, time: session.clock.next() });
+                } else if (block.type === 'thinking') {
+                  this._send(session.client, { type: 'thinking', content: block.thinking, time: session.clock.next() });
+                }
+              }
+            }
           }
-          // 通道已关闭 → 结束迭代
-          if (channelClosed) return Promise.resolve({ done: true, value: null });
-          // 否则等待消息入队或轮次完成
-          return new Promise((resolve) => {
-            resolveNext = resolve;
-          });
-        },
-      };
-    },
-  };
+
+          // result → 回合结束
+          if (message.type === 'result') {
+            this._send(session.client, { type: 'done', sessionId: session.sessionId, time: session.clock.next() });
+
+            // usage 累积
+            if (message.usage) {
+              const u = message.usage;
+              session.usage = {
+                inputTokens: (session.usage?.inputTokens || 0) + (u.inputTokens || 0),
+                outputTokens: (session.usage?.outputTokens || 0) + (u.outputTokens || 0),
+                cacheCreationInputTokens: (session.usage?.cacheCreationInputTokens || 0) + (u.cacheCreationInputTokens || 0),
+                cacheReadInputTokens: (session.usage?.cacheReadInputTokens || 0) + (u.cacheReadInputTokens || 0),
+                contextWindow: u.contextWindow || session.usage?.contextWindow || 200000,
+                contextTokens: u.contextTokens || session.usage?.contextTokens || 0,
+              };
+            }
+
+            session.onTurnComplete();
+            session.client = null;     // 解绑客户端，允许下一个 query 绑定
+            session.processing = false;
+            this._safeWriteState(session);
+
+            // 异步处理队列中的下一个请求
+            setImmediate(() => this._processQueue(session));
+          }
+        }
+      } catch (err) {
+        if (err?.code === 'ABORT_ERR') return;
+        this._send(session.client, { type: 'error', content: err instanceof Error ? err.message : String(err), time: session.clock.next() });
+      }
+    })();
+  }
 
   /**
-   * 将 SDK 用户消息入队。
-   * 优先直接交付给等待中的迭代器，否则放入缓冲区（最多 8 条）。
+   * 尝试处理 session 队列中的下一个查询。
    */
-  function enqueueMessage(sdkUserMessage) {
-    if (resolveNext) {
-      turnActive = true;
-      const r = resolveNext;
-      resolveNext = null;
-      r({ value: sdkUserMessage, done: false });
-    } else if (pendingMessages.length < 8) {
-      pendingMessages.push(sdkUserMessage);
+  _processQueue(session) {
+    if (session.closed) return;
+    if (session.queue.length === 0 || session.processing) return;
+
+    const { client, prompt, id } = session.queue.shift();
+    session.client = client;
+    session.processing = true;
+    session.currentTurnId = generateId('turn');
+
+    this._send(session.client, {
+      type: 'turn_start',
+      turn: session.currentTurnId,
+      time: session.clock.next(),
+    });
+
+    const sdkMessage = {
+      type: 'user',
+      message: { role: 'user', content: prompt },
+      session_id: session.sessionId || '',
+      uuid: generateId('msg'),
+    };
+
+    session.enqueueMessage(sdkMessage);
+  }
+
+  /** 向一个 WS 客户端发 JSON（安全断开则跳过） */
+  _send(client, data) {
+    if (client && client.readyState === 1) {
+      client.send(JSON.stringify(data));
     }
   }
 
-  /** 当前轮次完成：重置状态并触发下一轮读取 */
-  function onTurnComplete() {
-    turnActive = false;
-    const r = resolveNext;
-    resolveNext = null;
-    if (r) r({ done: true, value: null });
+  /** 持久化 session 状态（写锁防止同名并发写） */
+  _safeWriteState(session) {
+    const name = session.name;
+    // JS 单线程，用简单 flag 防同一 session 的递归写
+    writeState(name, createState(name, {
+      sessionId: session.sessionId,
+      model: session.sdkOptions.model,
+      usage: session.usage,
+    }));
   }
 
-  // 启动持久化查询
-  const response = agentQuery({
-    prompt: messageChannel,
-    options: sdkOptions,
-  });
+  /** 取消 idle 定时器 */
+  _cancelIdleTimer(name) {
+    const timer = this._idleTimers.get(name);
+    if (timer) {
+      clearTimeout(timer);
+      this._idleTimers.delete(name);
+    }
+  }
+
+  /** 安排 idle 关闭 */
+  _scheduleIdleCleanup(name) {
+    this._cancelIdleTimer(name);
+    this._idleTimers.set(name, setTimeout(() => {
+      this.destroy(name, 'idle timeout');
+    }, SESSION_IDLE_TIMEOUT_MS));
+  }
+
+  /**
+   * 从 session 队列中移除指定客户端的所有待处理请求。
+   */
+  removeClientFromQueue(session, ws) {
+    if (!session || session.closed) return;
+    session.queue = session.queue.filter(item => item.client !== ws);
+  }
+
+  /**
+   * 销毁一个 session。
+   */
+  async destroy(name, reason = 'shutdown') {
+    const session = this.sessions.get(name);
+    if (!session || session.closed) return;
+    session.closed = true;
+    this._cancelIdleTimer(name);
+
+    // 关闭 MessageChannel → SDK next() 返回 done
+    session.closeChannel();
+
+    // 中断 SDK 查询
+    try {
+      await session.response.interrupt();
+    } catch { /* ignore */ }
+
+    // 等待消费循环结束
+    try {
+      await session.consumerPromise;
+    } catch { /* ignore */ }
+
+    this.sessions.delete(name);
+
+    // 如果是正常关闭才清理状态文件（crash 留文件便于恢复）
+    if (reason !== 'crash') {
+      deleteState(name);
+    }
+  }
+
+  /**
+   * 销毁所有 session。
+   */
+  async destroyAll(reason = 'shutdown') {
+    const names = [...this.sessions.keys()];
+    await Promise.allSettled(names.map(name => this.destroy(name, reason)));
+  }
+}
+
+// =================================================================
+// 启动函数
+// =================================================================
 
-  let currentSessionId = existingState?.sessionId || null;
-  // 缓存 session 元数据，供 getSkills 按需查询
-  let sessionMetadata = null;
+/**
+ * 启动 WebSocket 持久化服务。
+ */
+export async function startServe(options) {
+  const { name = 'default', claudePath, model, cwd, env, port = DEFAULT_PORT } = options;
 
-  // 持久化初始状态
+  const machineId = getMachineId();
+  const host = hostname();
+  const osInfo = `${platform()}/${release()}/${machine()}`;
+
+  // 服务器级别状态
+  const serverState = readState(name);
+  const serverSessionId = serverState?.sessionId || null;
+
+  // 创建 SessionManager
+  const sessionManager = new SessionManager({ claudePath, model, cwd, env });
+
+  // =================================================================
+  // WebSocket 服务器
+  // =================================================================
+
+  const wss = new WebSocketServer({ port, host: '127.0.0.1' });
+
+  // 等待服务器就绪
+  await new Promise((resolve, reject) => {
+    wss.once('listening', resolve);
+    wss.once('error', (err) => {
+      if (err.code === 'EADDRINUSE') {
+        console.error(`Port ${port} already in use — another nx-ce serve is running`);
+      }
+      reject(err);
+    });
+  });
+
+  // 写入服务器级状态
   writeState(name, {
     name,
     pid: process.pid,
     startedAt: new Date().toISOString(),
-    sessionId: currentSessionId,
-    model: sdkOptions.model,
+    host,
+    machineId,
+    port,
+    lifecycleState: LifecycleState.RUNNING,
+    sessionCount: 0,
   });
 
-  // 后台任务：消费 SDK 输出并写入 stdout
-  const consumerPromise = (async () => {
-    try {
-      for await (const message of response) {
-        // 捕获初始化消息中的会话 ID + 元数据，更新持久化状态
-        if (message.type === 'system' && message.subtype === 'init' && message.session_id) {
-          currentSessionId = message.session_id;
-          writeState(name, {
-            name,
-            pid: process.pid,
-            startedAt: new Date().toISOString(),
-            sessionId: currentSessionId,
-            model: sdkOptions.model,
-          });
-          // 将技能/工具/命令列表转发给客户端 + 缓存供 getSkills 查询
-          sessionMetadata = {
-            type: 'init',
-            sessionId: currentSessionId,
-            model: message.model,
-            skills: message.skills || [],
-            tools: message.tools || [],
-            slashCommands: message.slash_commands || [],
-            agents: message.agents || [],
-          };
-          writeMessage(process.stdout, sessionMetadata);
+  // 客户端连接处理
+  wss.on('connection', (ws) => {
+    // 初始连接消息
+    ws.send(JSON.stringify({
+      type: 'connected',
+      port,
+      host,
+      machineId,
+      serverTime: Date.now(),
+    }));
+
+    ws.on('message', async (raw) => {
+      let req;
+      try {
+        req = JSON.parse(raw.toString());
+      } catch {
+        ws.send(JSON.stringify({ type: 'error', content: 'invalid JSON' }));
+        return;
+      }
+
+      const sessionName = req.session || 'default';
+
+      switch (req.type) {
+        case 'query': {
+          if (!req.prompt) {
+            ws.send(JSON.stringify({ type: 'error', content: 'query missing prompt' }));
+            break;
+          }
+
+          // 获取或创建 session（创建锁保证并发安全）
+          let session;
+          try {
+            session = await sessionManager.getOrCreate(sessionName);
+          } catch (err) {
+            ws.send(JSON.stringify({ type: 'error', content: `session create failed: ${err.message}` }));
+            break;
+          }
+
+          // 入队
+          session.queue.push({ client: ws, prompt: req.prompt, id: req.id });
+          sessionManager._processQueue(session);
+          break;
         }
 
-        // 助手消息 → 区分为 text / tool_use / thinking 块写入 stdout
-        if (message.type === 'assistant' && message.message?.content) {
-          const content = message.message.content;
-          if (typeof content === 'string') {
-            writeMessage(process.stdout, { type: 'text', content });
-          } else if (Array.isArray(content)) {
-            for (const block of content) {
-              if (block.type === 'text') {
-                writeMessage(process.stdout, { type: 'text', content: block.text });
-              } else if (block.type === 'tool_use') {
-                writeMessage(process.stdout, {
-                  type: 'tool_use',
-                  name: block.name,
-                  input: block.input,
-                  id: block.id,
-                });
-              } else if (block.type === 'thinking') {
-                writeMessage(process.stdout, { type: 'thinking', content: block.thinking });
-              }
-            }
+        case 'ping':
+          ws.send(JSON.stringify({ type: 'pong', serverTime: Date.now() }));
+          break;
+
+        case 'getSkills': {
+          const session = sessionManager.sessions.get(sessionName);
+          if (session?.metadata) {
+            ws.send(JSON.stringify(session.metadata));
+          } else {
+            ws.send(JSON.stringify({
+              type: 'skills',
+              skills: [],
+              tools: [],
+              slashCommands: [],
+              agents: [],
+              note: 'session not yet initialized',
+            }));
           }
+          break;
+        }
+
+        case 'getStatus': {
+          const session = sessionManager.sessions.get(sessionName);
+          ws.send(JSON.stringify({
+            type: 'status',
+            session: sessionName,
+            sessionId: session?.sessionId || null,
+            isActive: session ? !session.closed : false,
+            queueLength: session?.queue?.length || 0,
+            processing: session?.processing || false,
+          }));
+          break;
         }
 
-        // result 消息表示当前轮次完成
-        if (message.type === 'result') {
-          writeMessage(process.stdout, { type: 'done', sessionId: currentSessionId });
-          onTurnComplete();
+        case 'closeSession': {
+          await sessionManager.destroy(sessionName, 'client request');
+          ws.send(JSON.stringify({ type: 'session_closed', session: sessionName }));
+          break;
         }
+
+        case 'listSessions': {
+          const sessions = [...sessionManager.sessions.entries()]
+            .filter(([_, s]) => !s.closed)
+            .map(([name, s]) => ({
+              name,
+              sessionId: s.sessionId,
+              queueLength: s.queue.length,
+              processing: s.processing,
+            }));
+          ws.send(JSON.stringify({ type: 'session_list', sessions }));
+          break;
+        }
+
+        default:
+          ws.send(JSON.stringify({ type: 'error', content: `unknown type: ${req.type}` }));
       }
-    } catch (err) {
-      if (err?.code === 'ABORT_ERR') return; // 主动中断，非错误
-      writeMessage(process.stdout, {
-        type: 'error',
-        content: err instanceof Error ? err.message : String(err),
-      });
-    }
-  })();
+    });
 
-  // 主循环：从 stdin 读取协议消息，转发给 SDK
-  try {
-    while (true) {
-      let req;
-      try {
-        req = await readMessage(process.stdin);
-      } catch (err) {
-        if (err?.message?.startsWith?.('message too large')) {
-          writeMessage(process.stdout, { type: 'error', content: 'message too large' });
-          continue;
+    // 客户端断开 → 清理引用
+    ws.on('close', () => {
+      for (const [sName, session] of sessionManager.sessions) {
+        if (session.client === ws) {
+          session.client = null;
+        }
+        sessionManager.removeClientFromQueue(session, ws);
+
+        // 如果没有客户端了，安排 idle 回收
+        if (session.client === null && session.queue.length === 0 && !session.closed) {
+          sessionManager._scheduleIdleCleanup(sName);
         }
-        break; // EOF 或解析错误 → 关闭
       }
+    });
+  });
 
-      if (!req) break; // 正常 EOF
+  // =================================================================
+  // 信号处理（优雅关闭）
+  // =================================================================
 
-      // 根据消息类型路由
-      if (req.type === 'query' && req.prompt) {
-        // 构建 SDK 用户消息
-        const sdkMessage = {
-          type: 'user',
-          message: {
-            role: 'user',
-            content: req.prompt,
-          },
-          session_id: currentSessionId || '',
-          uuid: `${Date.now()}-${Math.random().toString(36).slice(2, 11)}`,
-        };
+  async function shutdown() {
+    // 更新服务器状态
+    writeState(name, {
+      ...readState(name),
+      lifecycleState: LifecycleState.STOPPED,
+    });
 
-        enqueueMessage(sdkMessage);
-      } else if (req.type === 'ping') {
-        // ping/pong 心跳
-        writeMessage(process.stdout, { type: 'pong', sessionId: currentSessionId });
-      } else if (req.type === 'getSkills') {
-        // Go 端主动拉取 skill/工具/命令 列表（可重复查询）
-        writeMessage(process.stdout, sessionMetadata || {
-          type: 'skills',
-          skills: [],
-          tools: [],
-          slashCommands: [],
-          agents: [],
-          note: 'session not yet initialized',
-        });
+    // 通知所有 WS 客户端
+    wss.clients.forEach((client) => {
+      if (client.readyState === 1) {
+        client.close(1001, 'server shutting down');
       }
-    }
-  } finally {
-    // 清理：关闭通道、中断查询、等待消费完成、删除状态文件
-    channelClosed = true;
-    if (resolveNext) {
-      resolveNext({ done: true, value: null });
-    }
-    try {
-      await response.interrupt();
-    } catch { /* 忽略中断错误 */ }
-    await consumerPromise;
+    });
+    wss.close();
+
+    // 关闭所有 session
+    await sessionManager.destroyAll('shutdown');
+
+    // 删除服务端状态文件
     deleteState(name);
+
+    process.exit(0);
   }
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+
+  // =================================================================
+  // 返回
+  // =================================================================
+
+  const info = { port, name };
+  console.error(`nx-ce serve ws://127.0.0.1:${port} [${name}]`);
+
+  return info;
 }

package/src/session-store.js

@@ -1,7 +1,12 @@
 /**
  * 会话存储 — 磁盘上的持久化状态
  *
- * 模式：nx-sx 的 writeState/readState。
+ * 参考 happy 的 sessions.json 设计：
+ *   - 每个命名实例存储完整元数据
+ *   - lifecycleState 追踪会话生命周期
+ *   - machineId/host 标识运行环境
+ *   - usage 追踪 token 消耗
+ *
  * 目录：$HOME/.nx-ce/instances/{name}.json
  */
 
@@ -17,6 +22,51 @@ function ensureDir() {
   mkdirSync(STATE_DIR, { recursive: true });
 }
 
+/**
+ * 会话生命周期状态枚举。
+ * 参考 happy 的 lifecycleState: "running" | "stopped" | "crashed"
+ */
+export const LifecycleState = Object.freeze({
+  RUNNING: 'running',
+  STOPPED: 'stopped',
+  CRASHED: 'crashed',
+  RESUMING: 'resuming',
+});
+
+/**
+ * 创建一个新的状态对象（含默认值）。
+ *
+ * @param {string} name - 实例名称
+ * @param {object} [overrides] - 覆盖字段
+ * @returns {object}
+ */
+export function createState(name, overrides = {}) {
+  return {
+    name,
+    pid: process.pid,
+    startedAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    sessionId: null,
+    model: 'claude-sonnet-4-6',
+    host: '',
+    machineId: '',
+    claudeVersion: '',
+    lifecycleState: LifecycleState.RUNNING,
+    lifecycleStateSince: Date.now(),
+    startedBy: 'serve',
+    port: null,
+    usage: {
+      inputTokens: 0,
+      cacheCreationInputTokens: 0,
+      cacheReadInputTokens: 0,
+      outputTokens: 0,
+      contextWindow: 200000,
+      contextTokens: 0,
+    },
+    ...overrides,
+  };
+}
+
 /**
  * 读取指定实例的持久化状态。
  *
@@ -42,7 +92,11 @@ export function readState(name) {
 export function writeState(name, state) {
   ensureDir();
   const path = join(STATE_DIR, sanitize(name));
-  writeFileSync(path, JSON.stringify(state, null, 2), 'utf8');
+  const enriched = {
+    ...state,
+    updatedAt: new Date().toISOString(),
+  };
+  writeFileSync(path, JSON.stringify(enriched, null, 2), 'utf8');
 }
 
 /**

package/src/util.js

@@ -0,0 +1,124 @@
+/**
+ * 工具函数 — 加密 ID 生成、单调时钟、机器标识
+ *
+ * 参考 happy 的 cuid2 + monotonic clock + machineId 设计。
+ */
+
+import { randomUUID, createHash } from 'node:crypto';
+import { hostname, machine, platform, release } from 'node:os';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+// =================================================================
+// ID 生成
+// =================================================================
+
+/** 会话 ID 前缀 */
+const SESSION_PREFIX = 'nxce';
+/** 消息 / turn ID 前缀 */
+const MSG_PREFIX = 'msg';
+
+/**
+ * 生成可排序的唯一 ID。
+ * 格式: {prefix}_{timestamp}-{randomUUID片段}
+ * 前缀保证可读性，时间戳保证近似排序，UUID 保证全局唯一。
+ *
+ * @param {string} prefix - ID 前缀
+ * @returns {string}
+ */
+export function generateId(prefix = SESSION_PREFIX) {
+  const ts = Date.now().toString(36);
+  const rand = randomUUID().replace(/-/g, '').slice(0, 12);
+  return `${prefix}_${ts}_${rand}`;
+}
+
+// =================================================================
+// 单调时钟
+// =================================================================
+
+/**
+ * 单调时钟 — 保证消息 time 字段严格递增。
+ *
+ * 参考 happy 的 AcpSessionManager.nextTime():
+ *   time = max(lastTime + 1, Date.now())
+ *
+ * 即使是同一毫秒内的多条消息也能保持正确顺序。
+ */
+export class MonotonicClock {
+  /** @type {number} */
+  #lastTime = 0;
+
+  /**
+   * 获取下一个单调递增的时间戳（毫秒级）。
+   * @returns {number}
+   */
+  next() {
+    this.#lastTime = Math.max(this.#lastTime + 1, Date.now());
+    return this.#lastTime;
+  }
+
+  /**
+   * 重置时钟（会话重新初始化时使用）。
+   */
+  reset() {
+    this.#lastTime = 0;
+  }
+}
+
+// =================================================================
+// 机器标识
+// =================================================================
+
+/** 持久化机器 ID 文件路径 */
+const MACHINE_ID_FILE = join(homedir(), '.nx-ce', 'machine-id');
+
+/**
+ * 获取或生成持久的机器 ID。
+ * 参考 happy 的 machineId: "418aa05c-377a-4577-b100-fd36ab54c641"
+ *
+ * 持久化到 ~/.nx-ce/machine-id，首次生成后固定不变。
+ *
+ * @returns {string}
+ */
+export function getMachineId() {
+  try {
+    if (existsSync(MACHINE_ID_FILE)) {
+      return readFileSync(MACHINE_ID_FILE, 'utf8').trim();
+    }
+  } catch { /* 首次运行，文件不存在 */ }
+
+  // 基于机器特征生成稳定 ID
+  const raw = `${hostname()}-${machine()}-${platform()}-${release()}`;
+  const id = createHash('sha256').update(raw).digest('hex').slice(0, 24);
+  const formatted = [
+    id.slice(0, 8),
+    id.slice(8, 12),
+    id.slice(12, 16),
+    id.slice(16, 20),
+    id.slice(20, 24),
+  ].join('-');
+
+  try {
+    mkdirSync(join(homedir(), '.nx-ce'), { recursive: true });
+    writeFileSync(MACHINE_ID_FILE, formatted, 'utf8');
+  } catch { /* 持久化失败不阻塞 */ }
+
+  return formatted;
+}
+
+// =================================================================
+// 编码 / 序列化辅助
+// =================================================================
+
+/**
+ * 将字节大小格式化为可读字符串。
+ * @param {number} bytes
+ * @returns {string}
+ */
+export function formatBytes(bytes) {
+  if (bytes === 0 || !bytes) return '0 B';
+  const units = ['B', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(1024));
+  return `${(bytes / Math.pow(1024, i)).toFixed(1)} ${units[i]}`;
+}