@wangchenglai/dsh-acp-session 0.1.0 → 0.1.1

package/index.js

@@ -1,526 +1,526 @@
-/**
- * ACP 会话管理插件（DeepSeek Harness）
- * ====================================
- *
- * 为什么需要它
- * ------------
- * dsh 自带的 ACP 插件（@deepseek-ai/dsh-acp）实现了：
- *   session/new, session/list, session/resume, session/prompt,
- *   session/cancel, session/close, session/set_config_option
- *
- * 但 ACP 1.4 里还有两件事它没做，另外 session/list 少填两个字段：
- *   - session/load   ：回放某个历史会话（ACP 用它做"恢复会话"）
- *   - session/delete ：删除会话
- *   - session/list   ：返回的 SessionInfo 只填了 sessionId 和 cwd，
- *                      没填 title / updatedAt（ACP 为此定义了字段）
- *
- * 于是平台之前只能在 backend 里加一个"外置会话管理器"：用 Python 去解
- * dsh 的 zstd 日志，再开三个 REST 接口给前端。那个方案能用，但把 dsh 的
- * 私有存储格式复制到了 dsh 外面。
- *
- * 这个插件怎么工作
- * ----------------
- * 它不修改 dsh 的源码，而是"套"在 dsh-acp 外面做一个消息中继：
- *
- *   浏览器 ──stdio──▶ [本插件] ──进程内 stream──▶ dsh-acp（原样运行）
- *
- * 绝大多数 JSON-RPC 消息原样双向转发；只有三条被截获：
- *   - session/list  ：转发后，用 dsh 的 sessionPersistence 补上 title/updatedAt
- *   - session/load  ：先发 session/resume 让 dsh 恢复上下文，再把历史按
- *                     session/update 通知回放给客户端，最后回一个空结果
- *   - session/delete：先 session/close（若在跑），再删掉会话目录
- *
- * 这样客户端（net-agent）看到的就是完整的标准 ACP，平台后端那套会话接口
- * 可以整个删掉。
- *
- * 依赖的是 dsh 自己的服务：ctx.sessionPersistence（list / resolveCurrentLog /
- * readStoredLog），所以不需要自己解压 zstd，也不会跟存储格式的演进脱节。
- */
-
-import { Readable, Writable } from 'node:stream';
-import { ndJsonStream } from '@agentclientprotocol/sdk';
-import * as acpPlugin from '@deepseek-ai/dsh-acp';
-import { describeSession, readSessionEvents, removeSession } from './lib/store.js';
-import { replayUpdates } from './lib/replay.js';
-
-/** Cordis 插件名，profile 的 patch 里用它做 id。 */
-export const name = 'acp-session';
-
-/** 需要的 dsh 核心服务；acpAppStartup 保证 --help 时不会抢占 stdio。 */
-export const inject = ['agents', 'llm', 'sessionPersistence', 'sessions', 'acpAppStartup'];
-
-const JSON_RPC_INTERNAL_ERROR = -32603;
-
-function describeError(error) {
-  if (error instanceof Error) return error.message;
-  if (error && typeof error === 'object' && typeof error.message === 'string') return error.message;
-  return String(error);
-}
-
-/** 给内部请求加超时，避免上游卡住时调用方无限等待。 */
-function withTimeout(promise, ms, label) {
-  return new Promise((resolve, reject) => {
-    const timer = setTimeout(() => reject(new Error(`${label} 超时（${ms}ms）`)), ms);
-    promise.then(
-      (value) => {
-        clearTimeout(timer);
-        resolve(value);
-      },
-      (error) => {
-        clearTimeout(timer);
-        reject(error);
-      },
-    );
-  });
-}
-
-/**
- * 挂载插件。
- *
- * @param ctx - Cordis 上下文
- * @param config - provider/model（透传给 dsh-acp），以及可选的 stream（测试用）
- */
-export function apply(ctx, config = {}) {
-  const persistence = ctx.sessionPersistence;
-  const logger = ctx.logger;
-
-  // 对客户端的那一端：生产环境是 stdio，测试时可以注入。
-  const clientStream = config.stream ?? ndJsonStream(
-    Writable.toWeb(process.stdout),
-    Readable.toWeb(process.stdin),
-  );
-
-  // 进程内双工通道：本插件 ↔ 上游 dsh-acp。
-  const toAgent = new TransformStream();
-  const toBridge = new TransformStream();
-  const agentSide = { readable: toBridge.readable, writable: toAgent.writable };
-  const bridgeSide = { readable: toAgent.readable, writable: toBridge.writable };
-
-  // 上游 dsh-acp 原样挂载，只是把 transport 换成我们的进程内通道。
-  ctx.plugin(acpPlugin, {
-    provider: config.provider,
-    model: config.model,
-    stream: agentSide,
-  });
-
-  const clientReader = clientStream.readable.getReader();
-  const clientWriter = clientStream.writable.getWriter();
-  const bridgeReader = bridgeSide.readable.getReader();
-  const bridgeWriter = bridgeSide.writable.getWriter();
-
-  /** 客户端发来的 session/list 请求 id -> 该请求的 cwd（收到响应时补字段并过滤）。 */
-  const listRequestIds = new Map();
-  /** 客户端发来的 initialize 请求 id，收到响应时要补能力声明。 */
-  const initializeRequestIds = new Set();
-  /** 客户端发来的 session/new 请求 id -> cwd，用来记住新会话属于哪个工作目录。 */
-  const newRequestCwd = new Map();
-  /**
-   * 本连接里创建/恢复过的会话。
-   *
-   * dsh 的 session/list 会把**所有还活着的会话**排除掉（不只是当前那个），
-   * 所以点"新建会话"之后，上一条会从列表里消失。这里记下来，统一补回列表。
-   */
-  const liveSessions = new Map(); // sessionId -> { cwd, hasContent }
-  /** 最近一次创建/恢复的会话 id，用于跟踪输入内容与标题。 */
-  let activeSessionId = null;
-  /** 会话摘要缓存：活动会话被上游排除时，用它把标题/时间补回来。 */
-  const summaryCache = new Map();
-  /** 最近一次见到的 configOptions（模型、推理强度），load 时作为兜底。 */
-  let lastConfigOptions = null;
-  /** 我们发给上游、还在等响应的请求。 */
-  const pendingUpstream = new Map();
-  let upstreamSeq = 0;
-  let disposed = false;
-
-  async function writeClient(message) {
-    if (disposed) return;
-    try {
-      await clientWriter.write(message);
-    } catch (error) {
-      logger.warn(`acp-session: 写给客户端失败: ${describeError(error)}`);
-    }
-  }
-
-  async function writeAgent(message) {
-    try {
-      await bridgeWriter.write(message);
-    } catch (error) {
-      logger.warn(`acp-session: 写给上游失败: ${describeError(error)}`);
-    }
-  }
-
-  /** 向上游发一个请求并等它的响应；错误信息原样抛出。 */
-  function requestUpstream(method, params) {
-    const id = `cnic-${++upstreamSeq}`;
-    return new Promise((resolve, reject) => {
-      pendingUpstream.set(id, { resolve, reject });
-      writeAgent({ jsonrpc: '2.0', id, method, params });
-    });
-  }
-
-  async function answerError(id, error) {
-    await writeClient({
-      jsonrpc: '2.0',
-      id,
-      error: { code: JSON_RPC_INTERNAL_ERROR, message: describeError(error) },
-    });
-  }
-
-  /** session/delete：先尽量关掉会话，再删目录。 */
-  async function handleDelete(message) {
-    const sessionId = message?.params?.sessionId;
-    if (!sessionId) {
-      await answerError(message.id, new Error('缺少 sessionId'));
-      return;
-    }
-
-    // 会话没在跑时 close 会报 unknown session，忽略即可；超时也不阻塞删除。
-    await withTimeout(requestUpstream('session/close', { sessionId }), 5_000, 'session/close')
-      .catch(() => {});
-
-    let removed = false;
-    try {
-      removed = await removeSession(persistence, sessionId);
-    } catch (error) {
-      await answerError(message.id, error);
-      return;
-    }
-
-    logger.info(`acp-session: 删除会话 ${sessionId} -> ${removed ? '已删除' : '不存在'}`);
-    liveSessions.delete(sessionId);
-    if (activeSessionId === sessionId) activeSessionId = null;
-    summaryCache.delete(sessionId);
-    await writeClient({ jsonrpc: '2.0', id: message.id, result: {} });
-  }
-
-  /** session/load：resume 上游 + 回放历史。 */
-  async function handleLoad(message) {
-    const params = message?.params ?? {};
-    const sessionId = params.sessionId;
-    if (!sessionId) {
-      await answerError(message.id, new Error('缺少 sessionId'));
-      return;
-    }
-
-    try {
-      // 恢复的是历史会话，必然有内容
-      liveSessions.set(sessionId, { cwd: params.cwd ?? null, hasContent: true });
-      activeSessionId = sessionId;
-
-      let resumeResult = null;
-      try {
-        resumeResult = await requestUpstream('session/resume', {
-          sessionId,
-          cwd: params.cwd,
-          mcpServers: params.mcpServers ?? [],
-        });
-      } catch (error) {
-        // 会话已经在当前 dsh 进程里加载着时，resume 会被拒绝
-        // （Invalid params: session is already active）。
-        // 那正是我们想要的状态，继续回放历史即可。
-        if (!/already active/i.test(describeError(error))) throw error;
-      }
-
-      // 读不到日志（例如会话正被当前进程持有）时没有可回放的历史
-      const events = (await readSessionEvents(persistence, sessionId)) ?? [];
-      for (const update of replayUpdates(events)) {
-        await writeClient({
-          jsonrpc: '2.0',
-          method: 'session/update',
-          params: { sessionId, update },
-        });
-      }
-
-      // resume 的响应里带着当前的 configOptions（模型、推理强度），
-      // 一并回给客户端，避免恢复会话后模型选择器被清空。
-      // resume 没带回配置时（例如会话已在当前进程里激活、resume 被拒），
-      // 用最近一次见到的 configOptions 兜底，避免恢复会话后模型选择器变空。
-      const configOptions = resumeResult?.configOptions ?? lastConfigOptions;
-      await writeClient({
-        jsonrpc: '2.0',
-        id: message.id,
-        result: Array.isArray(configOptions) && configOptions.length > 0 ? { configOptions } : {},
-      });
-    } catch (error) {
-      logger.warn(`acp-session: 恢复会话 ${sessionId} 失败: ${describeError(error)}`);
-      await answerError(message.id, error);
-    }
-  }
-
-  /**
-   * session/list：转发后补 title / updatedAt，并按 cwd 过滤、去掉空会话。
-   *
-   * 上游的 list 会把所有工作目录的会话都返回，也不区分"打开页面就自动创建的空会话"，
-   * 直接透传给客户端会让侧边栏混进别的应用、以及一堆没有内容的条目。
-   */
-  async function enrichListResponse(message, requestCwd) {
-    const sessions = message?.result?.sessions;
-    if (!Array.isArray(sessions)) return message;
-
-    const enriched = [];
-    for (const session of sessions) {
-      try {
-        const meta = await describeSession(persistence, session.sessionId);
-
-        // 空会话（只有会话头）不在列表里显示。
-        // messageCount 为 null 表示读不到日志（会话正被当前进程持有），
-        // 那是"未知"而不是"空"，必须保留——否则正在聊的那条会从列表里消失。
-        if (meta.messageCount === 0) continue;
-
-        // 客户端指定了 cwd 时，只返回该工作目录下的会话
-        const cwd = meta.cwd || session.cwd;
-        if (requestCwd && cwd !== requestCwd) continue;
-
-        const item = {
-          ...session,
-          cwd: cwd || session.cwd,
-          title: meta.title || session.title || null,
-          updatedAt: meta.updatedAt ?? session.updatedAt ?? null,
-        };
-        enriched.push(item);
-        summaryCache.set(item.sessionId, {
-          cwd: item.cwd,
-          title: item.title,
-          updatedAt: item.updatedAt,
-        });
-      } catch (error) {
-        logger.warn(`acp-session: 读取会话摘要失败 ${session?.sessionId}: ${describeError(error)}`);
-        enriched.push(session);
-      }
-    }
-
-    // dsh 的 session/list 会排除所有还活着的会话（不只是当前那个）：
-    // 刚聊完的那条、以及点"新建会话"之前的那些，都需要补回来。
-    for (const [sessionId, live] of liveSessions) {
-      if (!live.hasContent) continue; // 空会话不进列表
-      if (enriched.some((item) => item.sessionId === sessionId)) continue;
-      if (requestCwd && live.cwd && requestCwd !== live.cwd) continue;
-
-      let cached = summaryCache.get(sessionId) ?? {};
-      if (!cached.title) {
-        try {
-          const meta = await describeSession(persistence, sessionId);
-          cached = { ...cached, ...meta };
-        } catch (error) {
-          logger.warn(`acp-session: 读取活动会话摘要失败 ${sessionId}: ${describeError(error)}`);
-        }
-      }
-
-      enriched.unshift({
-        sessionId,
-        cwd: live.cwd ?? cached.cwd ?? requestCwd ?? '',
-        title: cached.title ?? null,
-        updatedAt: cached.updatedAt ?? null,
-      });
-    }
-
-    return { ...message, result: { ...message.result, sessions: enriched } };
-  }
-
-  /**
-   * initialize：把本插件补齐的能力声明出来。
-   *
-   * 上游只说支持 list / resume / close，客户端据此就不会调用
-   * session/load 与 session/delete。ACP 里 load 的能力位是顶层
-   * `loadSession: boolean`，delete 在 `sessionCapabilities.delete`。
-   */
-  function enrichInitializeResponse(message) {
-    const result = message?.result;
-    if (!result || typeof result !== 'object') return message;
-
-    const capabilities = result.agentCapabilities ?? {};
-    const sessionCapabilities = capabilities.sessionCapabilities ?? {};
-
-    return {
-      ...message,
-      result: {
-        ...result,
-        agentCapabilities: {
-          ...capabilities,
-          loadSession: true,
-          sessionCapabilities: {
-            ...sessionCapabilities,
-            delete: sessionCapabilities.delete ?? {},
-          },
-        },
-      },
-    };
-  }
-
-  // 客户端 → 上游
-  const clientPump = (async () => {
-    while (!disposed) {
-      let chunk;
-      try {
-        chunk = await clientReader.read();
-      } catch {
-        break;
-      }
-      if (chunk.done) break;
-
-      const message = chunk.value;
-      const isRequest = message && message.id !== undefined && typeof message.method === 'string';
-
-      try {
-        if (isRequest && message.method === 'session/delete') {
-          await handleDelete(message);
-          continue;
-        }
-        if (isRequest && message.method === 'session/load') {
-          await handleLoad(message);
-          continue;
-        }
-        if (isRequest && message.method === 'session/list') {
-          listRequestIds.set(message.id, message.params?.cwd ?? null);
-        }
-        if (isRequest && message.method === 'session/new') {
-          newRequestCwd.set(message.id, message.params?.cwd ?? null);
-        }
-        if (
-          isRequest &&
-          message.method === 'session/prompt' &&
-          liveSessions.has(message.params?.sessionId)
-        ) {
-          const sessionId = message.params.sessionId;
-          const live = liveSessions.get(sessionId);
-          live.hasContent = true;
-          // 读不到活动会话的日志，就把用户这次输入当作列表标题
-          if (!summaryCache.get(sessionId)?.title) {
-            const block = (message.params?.prompt ?? []).find((item) => item?.type === 'text');
-            const text = typeof block?.text === 'string' ? block.text.trim() : '';
-            if (text) {
-              summaryCache.set(sessionId, {
-                cwd: live.cwd,
-                title: text.slice(0, 20),
-                updatedAt: new Date().toISOString(),
-              });
-            }
-          }
-        }
-        if (
-          isRequest &&
-          message.method === 'session/close'
-        ) {
-          const closedId = message.params?.sessionId;
-          liveSessions.delete(closedId);
-          if (activeSessionId === closedId) activeSessionId = null;
-        }
-        if (isRequest && message.method === 'initialize') {
-          initializeRequestIds.add(message.id);
-        }
-        await writeAgent(message);
-      } catch (error) {
-        if (isRequest) await answerError(message.id, error);
-      }
-    }
-  })();
-
-  // 上游 → 客户端
-  const agentPump = (async () => {
-    while (!disposed) {
-      let chunk;
-      try {
-        chunk = await bridgeReader.read();
-      } catch {
-        break;
-      }
-      if (chunk.done) break;
-
-      const message = chunk.value;
-
-      if (Array.isArray(message?.result?.configOptions) && message.result.configOptions.length > 0) {
-        lastConfigOptions = message.result.configOptions;
-      }
-
-      // session/new 的响应：记住当前会话（列表要把它补回来）
-      if (message && message.id !== undefined && newRequestCwd.has(message.id)) {
-        const cwd = newRequestCwd.get(message.id);
-        newRequestCwd.delete(message.id);
-        const sessionId = message.result?.sessionId;
-        if (sessionId) {
-          liveSessions.set(sessionId, { cwd, hasContent: false });
-          activeSessionId = sessionId;
-        }
-        await writeClient(message);
-        continue;
-      }
-
-      // 活动会话每收到一次更新就刷新它的时间
-      if (
-        message &&
-        message.method === 'session/update' &&
-        liveSessions.has(message.params?.sessionId)
-      ) {
-        const sessionId = message.params.sessionId;
-        const live = liveSessions.get(sessionId);
-        const cached = summaryCache.get(sessionId);
-        const update = message.params?.update ?? {};
-        if (
-          update.sessionUpdate === 'user_message_chunk' ||
-          update.sessionUpdate === 'agent_message_chunk' ||
-          update.sessionUpdate === 'agent_thought_chunk' ||
-          update.sessionUpdate === 'tool_call'
-        ) {
-          live.hasContent = true;
-        }
-        // 读不到活动会话的日志时，用第一条用户消息当标题
-        if (
-          update.sessionUpdate === 'user_message_chunk' &&
-          !summaryCache.get(sessionId)?.title &&
-          typeof update.content?.text === 'string'
-        ) {
-          summaryCache.set(sessionId, {
-            cwd: live.cwd,
-            title: update.content.text.slice(0, 20),
-            updatedAt: new Date().toISOString(),
-          });
-        } else if (cached) {
-          cached.updatedAt = new Date().toISOString();
-        }
-      }
-
-      // 我们自己发的请求（session/resume、session/close）的响应
-      if (message && message.id !== undefined && pendingUpstream.has(message.id)) {
-        const pending = pendingUpstream.get(message.id);
-        pendingUpstream.delete(message.id);
-        if (message.error) {
-          const error = new Error(message.error.message ?? '上游返回错误');
-          error.code = message.error.code;
-          pending.reject(error);
-        } else {
-          pending.resolve(message.result);
-        }
-        continue;
-      }
-
-      // 客户端的 session/list 响应，补完再转回去
-      if (message && message.id !== undefined && listRequestIds.has(message.id)) {
-        const requestCwd = listRequestIds.get(message.id);
-        listRequestIds.delete(message.id);
-        await writeClient(await enrichListResponse(message, requestCwd));
-        continue;
-      }
-
-      // 客户端的 initialize 响应，补能力声明
-      if (message && message.id !== undefined && initializeRequestIds.has(message.id)) {
-        initializeRequestIds.delete(message.id);
-        await writeClient(enrichInitializeResponse(message));
-        continue;
-      }
-
-      await writeClient(message);
-    }
-  })();
-
-  ctx.effect(() => () => {
-    disposed = true;
-    for (const pending of pendingUpstream.values()) {
-      pending.reject(new Error('acp-session 插件已卸载'));
-    }
-    pendingUpstream.clear();
-    clientReader.cancel().catch(() => {});
-    bridgeReader.cancel().catch(() => {});
-    clientPump.catch(() => {});
-    agentPump.catch(() => {});
-  }, 'acp-session.relay');
-}
+/**
+ * ACP 会话管理插件（DeepSeek Harness）
+ * ====================================
+ *
+ * 为什么需要它
+ * ------------
+ * dsh 自带的 ACP 插件（@deepseek-ai/dsh-acp）实现了：
+ *   session/new, session/list, session/resume, session/prompt,
+ *   session/cancel, session/close, session/set_config_option
+ *
+ * 但 ACP 1.4 里还有两件事它没做，另外 session/list 少填两个字段：
+ *   - session/load   ：回放某个历史会话（ACP 用它做"恢复会话"）
+ *   - session/delete ：删除会话
+ *   - session/list   ：返回的 SessionInfo 只填了 sessionId 和 cwd，
+ *                      没填 title / updatedAt（ACP 为此定义了字段）
+ *
+ * 于是平台之前只能在 backend 里加一个"外置会话管理器"：用 Python 去解
+ * dsh 的 zstd 日志，再开三个 REST 接口给前端。那个方案能用，但把 dsh 的
+ * 私有存储格式复制到了 dsh 外面。
+ *
+ * 这个插件怎么工作
+ * ----------------
+ * 它不修改 dsh 的源码，而是"套"在 dsh-acp 外面做一个消息中继：
+ *
+ *   浏览器 ──stdio──▶ [本插件] ──进程内 stream──▶ dsh-acp（原样运行）
+ *
+ * 绝大多数 JSON-RPC 消息原样双向转发；只有三条被截获：
+ *   - session/list  ：转发后，用 dsh 的 sessionPersistence 补上 title/updatedAt
+ *   - session/load  ：先发 session/resume 让 dsh 恢复上下文，再把历史按
+ *                     session/update 通知回放给客户端，最后回一个空结果
+ *   - session/delete：先 session/close（若在跑），再删掉会话目录
+ *
+ * 这样客户端（net-agent）看到的就是完整的标准 ACP，平台后端那套会话接口
+ * 可以整个删掉。
+ *
+ * 依赖的是 dsh 自己的服务：ctx.sessionPersistence（list / resolveCurrentLog /
+ * readStoredLog），所以不需要自己解压 zstd，也不会跟存储格式的演进脱节。
+ */
+
+import { Readable, Writable } from 'node:stream';
+import { ndJsonStream } from '@agentclientprotocol/sdk';
+import * as acpPlugin from '@deepseek-ai/dsh-acp';
+import { describeSession, readSessionEvents, removeSession } from './lib/store.js';
+import { replayUpdates } from './lib/replay.js';
+
+/** Cordis 插件名，profile 的 patch 里用它做 id。 */
+export const name = 'acp-session';
+
+/** 需要的 dsh 核心服务；acpAppStartup 保证 --help 时不会抢占 stdio。 */
+export const inject = ['agents', 'llm', 'sessionPersistence', 'sessions', 'acpAppStartup'];
+
+const JSON_RPC_INTERNAL_ERROR = -32603;
+
+function describeError(error) {
+  if (error instanceof Error) return error.message;
+  if (error && typeof error === 'object' && typeof error.message === 'string') return error.message;
+  return String(error);
+}
+
+/** 给内部请求加超时，避免上游卡住时调用方无限等待。 */
+function withTimeout(promise, ms, label) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(`${label} 超时（${ms}ms）`)), ms);
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (error) => {
+        clearTimeout(timer);
+        reject(error);
+      },
+    );
+  });
+}
+
+/**
+ * 挂载插件。
+ *
+ * @param ctx - Cordis 上下文
+ * @param config - provider/model（透传给 dsh-acp），以及可选的 stream（测试用）
+ */
+export function apply(ctx, config = {}) {
+  const persistence = ctx.sessionPersistence;
+  const logger = ctx.logger;
+
+  // 对客户端的那一端：生产环境是 stdio，测试时可以注入。
+  const clientStream = config.stream ?? ndJsonStream(
+    Writable.toWeb(process.stdout),
+    Readable.toWeb(process.stdin),
+  );
+
+  // 进程内双工通道：本插件 ↔ 上游 dsh-acp。
+  const toAgent = new TransformStream();
+  const toBridge = new TransformStream();
+  const agentSide = { readable: toBridge.readable, writable: toAgent.writable };
+  const bridgeSide = { readable: toAgent.readable, writable: toBridge.writable };
+
+  // 上游 dsh-acp 原样挂载，只是把 transport 换成我们的进程内通道。
+  ctx.plugin(acpPlugin, {
+    provider: config.provider,
+    model: config.model,
+    stream: agentSide,
+  });
+
+  const clientReader = clientStream.readable.getReader();
+  const clientWriter = clientStream.writable.getWriter();
+  const bridgeReader = bridgeSide.readable.getReader();
+  const bridgeWriter = bridgeSide.writable.getWriter();
+
+  /** 客户端发来的 session/list 请求 id -> 该请求的 cwd（收到响应时补字段并过滤）。 */
+  const listRequestIds = new Map();
+  /** 客户端发来的 initialize 请求 id，收到响应时要补能力声明。 */
+  const initializeRequestIds = new Set();
+  /** 客户端发来的 session/new 请求 id -> cwd，用来记住新会话属于哪个工作目录。 */
+  const newRequestCwd = new Map();
+  /**
+   * 本连接里创建/恢复过的会话。
+   *
+   * dsh 的 session/list 会把**所有还活着的会话**排除掉（不只是当前那个），
+   * 所以点"新建会话"之后，上一条会从列表里消失。这里记下来，统一补回列表。
+   */
+  const liveSessions = new Map(); // sessionId -> { cwd, hasContent }
+  /** 最近一次创建/恢复的会话 id，用于跟踪输入内容与标题。 */
+  let activeSessionId = null;
+  /** 会话摘要缓存：活动会话被上游排除时，用它把标题/时间补回来。 */
+  const summaryCache = new Map();
+  /** 最近一次见到的 configOptions（模型、推理强度），load 时作为兜底。 */
+  let lastConfigOptions = null;
+  /** 我们发给上游、还在等响应的请求。 */
+  const pendingUpstream = new Map();
+  let upstreamSeq = 0;
+  let disposed = false;
+
+  async function writeClient(message) {
+    if (disposed) return;
+    try {
+      await clientWriter.write(message);
+    } catch (error) {
+      logger.warn(`acp-session: 写给客户端失败: ${describeError(error)}`);
+    }
+  }
+
+  async function writeAgent(message) {
+    try {
+      await bridgeWriter.write(message);
+    } catch (error) {
+      logger.warn(`acp-session: 写给上游失败: ${describeError(error)}`);
+    }
+  }
+
+  /** 向上游发一个请求并等它的响应；错误信息原样抛出。 */
+  function requestUpstream(method, params) {
+    const id = `cnic-${++upstreamSeq}`;
+    return new Promise((resolve, reject) => {
+      pendingUpstream.set(id, { resolve, reject });
+      writeAgent({ jsonrpc: '2.0', id, method, params });
+    });
+  }
+
+  async function answerError(id, error) {
+    await writeClient({
+      jsonrpc: '2.0',
+      id,
+      error: { code: JSON_RPC_INTERNAL_ERROR, message: describeError(error) },
+    });
+  }
+
+  /** session/delete：先尽量关掉会话，再删目录。 */
+  async function handleDelete(message) {
+    const sessionId = message?.params?.sessionId;
+    if (!sessionId) {
+      await answerError(message.id, new Error('缺少 sessionId'));
+      return;
+    }
+
+    // 会话没在跑时 close 会报 unknown session，忽略即可；超时也不阻塞删除。
+    await withTimeout(requestUpstream('session/close', { sessionId }), 5_000, 'session/close')
+      .catch(() => {});
+
+    let removed = false;
+    try {
+      removed = await removeSession(persistence, sessionId);
+    } catch (error) {
+      await answerError(message.id, error);
+      return;
+    }
+
+    logger.info(`acp-session: 删除会话 ${sessionId} -> ${removed ? '已删除' : '不存在'}`);
+    liveSessions.delete(sessionId);
+    if (activeSessionId === sessionId) activeSessionId = null;
+    summaryCache.delete(sessionId);
+    await writeClient({ jsonrpc: '2.0', id: message.id, result: {} });
+  }
+
+  /** session/load：resume 上游 + 回放历史。 */
+  async function handleLoad(message) {
+    const params = message?.params ?? {};
+    const sessionId = params.sessionId;
+    if (!sessionId) {
+      await answerError(message.id, new Error('缺少 sessionId'));
+      return;
+    }
+
+    try {
+      // 恢复的是历史会话，必然有内容
+      liveSessions.set(sessionId, { cwd: params.cwd ?? null, hasContent: true });
+      activeSessionId = sessionId;
+
+      let resumeResult = null;
+      try {
+        resumeResult = await requestUpstream('session/resume', {
+          sessionId,
+          cwd: params.cwd,
+          mcpServers: params.mcpServers ?? [],
+        });
+      } catch (error) {
+        // 会话已经在当前 dsh 进程里加载着时，resume 会被拒绝
+        // （Invalid params: session is already active）。
+        // 那正是我们想要的状态，继续回放历史即可。
+        if (!/already active/i.test(describeError(error))) throw error;
+      }
+
+      // 读不到日志（例如会话正被当前进程持有）时没有可回放的历史
+      const events = (await readSessionEvents(persistence, sessionId)) ?? [];
+      for (const update of replayUpdates(events)) {
+        await writeClient({
+          jsonrpc: '2.0',
+          method: 'session/update',
+          params: { sessionId, update },
+        });
+      }
+
+      // resume 的响应里带着当前的 configOptions（模型、推理强度），
+      // 一并回给客户端，避免恢复会话后模型选择器被清空。
+      // resume 没带回配置时（例如会话已在当前进程里激活、resume 被拒），
+      // 用最近一次见到的 configOptions 兜底，避免恢复会话后模型选择器变空。
+      const configOptions = resumeResult?.configOptions ?? lastConfigOptions;
+      await writeClient({
+        jsonrpc: '2.0',
+        id: message.id,
+        result: Array.isArray(configOptions) && configOptions.length > 0 ? { configOptions } : {},
+      });
+    } catch (error) {
+      logger.warn(`acp-session: 恢复会话 ${sessionId} 失败: ${describeError(error)}`);
+      await answerError(message.id, error);
+    }
+  }
+
+  /**
+   * session/list：转发后补 title / updatedAt，并按 cwd 过滤、去掉空会话。
+   *
+   * 上游的 list 会把所有工作目录的会话都返回，也不区分"打开页面就自动创建的空会话"，
+   * 直接透传给客户端会让侧边栏混进别的应用、以及一堆没有内容的条目。
+   */
+  async function enrichListResponse(message, requestCwd) {
+    const sessions = message?.result?.sessions;
+    if (!Array.isArray(sessions)) return message;
+
+    const enriched = [];
+    for (const session of sessions) {
+      try {
+        const meta = await describeSession(persistence, session.sessionId);
+
+        // 空会话（只有会话头）不在列表里显示。
+        // messageCount 为 null 表示读不到日志（会话正被当前进程持有），
+        // 那是"未知"而不是"空"，必须保留——否则正在聊的那条会从列表里消失。
+        if (meta.messageCount === 0) continue;
+
+        // 客户端指定了 cwd 时，只返回该工作目录下的会话
+        const cwd = meta.cwd || session.cwd;
+        if (requestCwd && cwd !== requestCwd) continue;
+
+        const item = {
+          ...session,
+          cwd: cwd || session.cwd,
+          title: meta.title || session.title || null,
+          updatedAt: meta.updatedAt ?? session.updatedAt ?? null,
+        };
+        enriched.push(item);
+        summaryCache.set(item.sessionId, {
+          cwd: item.cwd,
+          title: item.title,
+          updatedAt: item.updatedAt,
+        });
+      } catch (error) {
+        logger.warn(`acp-session: 读取会话摘要失败 ${session?.sessionId}: ${describeError(error)}`);
+        enriched.push(session);
+      }
+    }
+
+    // dsh 的 session/list 会排除所有还活着的会话（不只是当前那个）：
+    // 刚聊完的那条、以及点"新建会话"之前的那些，都需要补回来。
+    for (const [sessionId, live] of liveSessions) {
+      if (!live.hasContent) continue; // 空会话不进列表
+      if (enriched.some((item) => item.sessionId === sessionId)) continue;
+      if (requestCwd && live.cwd && requestCwd !== live.cwd) continue;
+
+      let cached = summaryCache.get(sessionId) ?? {};
+      if (!cached.title) {
+        try {
+          const meta = await describeSession(persistence, sessionId);
+          cached = { ...cached, ...meta };
+        } catch (error) {
+          logger.warn(`acp-session: 读取活动会话摘要失败 ${sessionId}: ${describeError(error)}`);
+        }
+      }
+
+      enriched.unshift({
+        sessionId,
+        cwd: live.cwd ?? cached.cwd ?? requestCwd ?? '',
+        title: cached.title ?? null,
+        updatedAt: cached.updatedAt ?? null,
+      });
+    }
+
+    return { ...message, result: { ...message.result, sessions: enriched } };
+  }
+
+  /**
+   * initialize：把本插件补齐的能力声明出来。
+   *
+   * 上游只说支持 list / resume / close，客户端据此就不会调用
+   * session/load 与 session/delete。ACP 里 load 的能力位是顶层
+   * `loadSession: boolean`，delete 在 `sessionCapabilities.delete`。
+   */
+  function enrichInitializeResponse(message) {
+    const result = message?.result;
+    if (!result || typeof result !== 'object') return message;
+
+    const capabilities = result.agentCapabilities ?? {};
+    const sessionCapabilities = capabilities.sessionCapabilities ?? {};
+
+    return {
+      ...message,
+      result: {
+        ...result,
+        agentCapabilities: {
+          ...capabilities,
+          loadSession: true,
+          sessionCapabilities: {
+            ...sessionCapabilities,
+            delete: sessionCapabilities.delete ?? {},
+          },
+        },
+      },
+    };
+  }
+
+  // 客户端 → 上游
+  const clientPump = (async () => {
+    while (!disposed) {
+      let chunk;
+      try {
+        chunk = await clientReader.read();
+      } catch {
+        break;
+      }
+      if (chunk.done) break;
+
+      const message = chunk.value;
+      const isRequest = message && message.id !== undefined && typeof message.method === 'string';
+
+      try {
+        if (isRequest && message.method === 'session/delete') {
+          await handleDelete(message);
+          continue;
+        }
+        if (isRequest && message.method === 'session/load') {
+          await handleLoad(message);
+          continue;
+        }
+        if (isRequest && message.method === 'session/list') {
+          listRequestIds.set(message.id, message.params?.cwd ?? null);
+        }
+        if (isRequest && message.method === 'session/new') {
+          newRequestCwd.set(message.id, message.params?.cwd ?? null);
+        }
+        if (
+          isRequest &&
+          message.method === 'session/prompt' &&
+          liveSessions.has(message.params?.sessionId)
+        ) {
+          const sessionId = message.params.sessionId;
+          const live = liveSessions.get(sessionId);
+          live.hasContent = true;
+          // 读不到活动会话的日志，就把用户这次输入当作列表标题
+          if (!summaryCache.get(sessionId)?.title) {
+            const block = (message.params?.prompt ?? []).find((item) => item?.type === 'text');
+            const text = typeof block?.text === 'string' ? block.text.trim() : '';
+            if (text) {
+              summaryCache.set(sessionId, {
+                cwd: live.cwd,
+                title: text.slice(0, 20),
+                updatedAt: new Date().toISOString(),
+              });
+            }
+          }
+        }
+        if (
+          isRequest &&
+          message.method === 'session/close'
+        ) {
+          const closedId = message.params?.sessionId;
+          liveSessions.delete(closedId);
+          if (activeSessionId === closedId) activeSessionId = null;
+        }
+        if (isRequest && message.method === 'initialize') {
+          initializeRequestIds.add(message.id);
+        }
+        await writeAgent(message);
+      } catch (error) {
+        if (isRequest) await answerError(message.id, error);
+      }
+    }
+  })();
+
+  // 上游 → 客户端
+  const agentPump = (async () => {
+    while (!disposed) {
+      let chunk;
+      try {
+        chunk = await bridgeReader.read();
+      } catch {
+        break;
+      }
+      if (chunk.done) break;
+
+      const message = chunk.value;
+
+      if (Array.isArray(message?.result?.configOptions) && message.result.configOptions.length > 0) {
+        lastConfigOptions = message.result.configOptions;
+      }
+
+      // session/new 的响应：记住当前会话（列表要把它补回来）
+      if (message && message.id !== undefined && newRequestCwd.has(message.id)) {
+        const cwd = newRequestCwd.get(message.id);
+        newRequestCwd.delete(message.id);
+        const sessionId = message.result?.sessionId;
+        if (sessionId) {
+          liveSessions.set(sessionId, { cwd, hasContent: false });
+          activeSessionId = sessionId;
+        }
+        await writeClient(message);
+        continue;
+      }
+
+      // 活动会话每收到一次更新就刷新它的时间
+      if (
+        message &&
+        message.method === 'session/update' &&
+        liveSessions.has(message.params?.sessionId)
+      ) {
+        const sessionId = message.params.sessionId;
+        const live = liveSessions.get(sessionId);
+        const cached = summaryCache.get(sessionId);
+        const update = message.params?.update ?? {};
+        if (
+          update.sessionUpdate === 'user_message_chunk' ||
+          update.sessionUpdate === 'agent_message_chunk' ||
+          update.sessionUpdate === 'agent_thought_chunk' ||
+          update.sessionUpdate === 'tool_call'
+        ) {
+          live.hasContent = true;
+        }
+        // 读不到活动会话的日志时，用第一条用户消息当标题
+        if (
+          update.sessionUpdate === 'user_message_chunk' &&
+          !summaryCache.get(sessionId)?.title &&
+          typeof update.content?.text === 'string'
+        ) {
+          summaryCache.set(sessionId, {
+            cwd: live.cwd,
+            title: update.content.text.slice(0, 20),
+            updatedAt: new Date().toISOString(),
+          });
+        } else if (cached) {
+          cached.updatedAt = new Date().toISOString();
+        }
+      }
+
+      // 我们自己发的请求（session/resume、session/close）的响应
+      if (message && message.id !== undefined && pendingUpstream.has(message.id)) {
+        const pending = pendingUpstream.get(message.id);
+        pendingUpstream.delete(message.id);
+        if (message.error) {
+          const error = new Error(message.error.message ?? '上游返回错误');
+          error.code = message.error.code;
+          pending.reject(error);
+        } else {
+          pending.resolve(message.result);
+        }
+        continue;
+      }
+
+      // 客户端的 session/list 响应，补完再转回去
+      if (message && message.id !== undefined && listRequestIds.has(message.id)) {
+        const requestCwd = listRequestIds.get(message.id);
+        listRequestIds.delete(message.id);
+        await writeClient(await enrichListResponse(message, requestCwd));
+        continue;
+      }
+
+      // 客户端的 initialize 响应，补能力声明
+      if (message && message.id !== undefined && initializeRequestIds.has(message.id)) {
+        initializeRequestIds.delete(message.id);
+        await writeClient(enrichInitializeResponse(message));
+        continue;
+      }
+
+      await writeClient(message);
+    }
+  })();
+
+  ctx.effect(() => () => {
+    disposed = true;
+    for (const pending of pendingUpstream.values()) {
+      pending.reject(new Error('acp-session 插件已卸载'));
+    }
+    pendingUpstream.clear();
+    clientReader.cancel().catch(() => {});
+    bridgeReader.cancel().catch(() => {});
+    clientPump.catch(() => {});
+    agentPump.catch(() => {});
+  }, 'acp-session.relay');
+}