@epoch-agent/plugin-lsp 0.1.0 → 0.3.1

package/README.md

@@ -122,9 +122,14 @@ pull 模式（`initialize` 的结果里没有 `diagnosticProvider`）。server
 跳过。**「没装」不计入失败次数**：那不是「试了没成」，计进去的话用户装完 server
 还得重启 epoch 才能用上。
 
-**退出时宿主什么都不用做**：进程在 infra 的进程表里，`cleanupBackgroundProcesses()`
-会一并收掉。`disposeLspServers()` 是给「想早点收、且要走 LSP `shutdown` 礼节」的
-宿主用的。
+**退出时宿主什么都不用做**：进程在 infra 的**进程级兜底表**里，最后一个 runtime
+`dispose()` 时一并收掉。`disposeLspServers()` 是给「想早点收、且要走 LSP `shutdown`
+礼节」的宿主用的。
+
+⚠️ 落在兜底表而不是某个 runtime 名下是**刻意的**（方案 60 §2.6）：这个池按项目根
+共享，两个 runtime 开在同一个项目上时它们本来就该共用同一个 tsserver ——
+它不是任何一个 runtime 的私产。代价写下来不掩饰：同进程里 A 和 B 并存时，
+B 的 `dispose()` 收不掉这些 server，要等 A 也走。
 
 ## 为什么是 `file_read` 而不是 `command`
 

package/dist/index.d.ts

@@ -201,8 +201,16 @@ declare function resolveServer(spec: ServerSpec, projectRoot: string, options?:
  * （外加 `didClose` 做逐出、`shutdown` + `exit` 做优雅退出）。
  *
  * 进程**一律走 infra 的 `startLongLivedProcess`**（方案 36），这个包里不长
- * 第二套进程管理 —— 顺带的好处是 `epoch` 退出时 `killAllTrackedProcesses()`
- * 天然把 server 一并收掉（验收 7），我们一行清理代码都不用写。
+ * 第二套进程管理 —— 顺带的好处是 `epoch` 退出时 server 被天然一并收掉（验收 7），
+ * 我们一行清理代码都不用写。
+ *
+ * 收它的那条链子（方案 60 之后）：`startLongLivedProcess` 登记进的是**进程级
+ * 兜底表** —— 这个池是模块级单例、按项目根共享，压根没有 `sessionId`，归兜底表
+ * 是结论不是妥协（判据在 [README](../README.md)）。最后一个 runtime
+ * `dispose()` → `OwnedProcessTable.release()` 把兜底表的引用计数减到 0，那一下
+ * 连兜底表一起收。一个进程一个 runtime 的 CLI / TUI 每次 dispose 都归零，
+ * 所以和方案 60 之前逐字节相同；两个 runtime 并存时先走的那个碰不到这个池
+ * （否则表现是「跑了条定时任务，之后 `lsp_diagnostics` 每次都要重新冷启 tsserver」）。
  *
  * ## 诊断是**推**过来的，所以「什么时候算收全了」得自己判
  *

package/dist/index.js

@@ -1,7 +1,6 @@
 // src/diagnose.ts
 import { readFile, stat } from "fs/promises";
 import { extname, isAbsolute, relative, resolve as resolve2, sep } from "path";
-
 // src/client.ts
 import { basename } from "path";
 import { pathToFileURL } from "url";
@@ -24,8 +23,8 @@ import {
   WorkDoneProgressCreateRequest
 } from "vscode-languageserver-protocol";
 import {
-  collectProcessTree,
-  killPids,
+  collectProcessTreeStamped,
+  killStampedPids,
   killTrackedProcess,
   startLongLivedProcess
 } from "@epoch-agent/infra";
@@ -73,13 +72,9 @@ var LspClient = class _LspClient {
   connection;
   pidValue;
   spec;
-  /** 归一键 → 打开状态。按插入顺序逐出 */
   openDocs = /* @__PURE__ */ new Map();
-  /** 归一键 → server 最近一次推来的诊断 */
   latest = /* @__PURE__ */ new Map();
-  /** 最近一次「有动静」的时刻 —— 我们发出去的和 server 推回来的都算 */
   lastActivityAt = 0;
-  /** 这一批里已经答过的文件 */
   answered = /* @__PURE__ */ new Set();
   dead = null;
   disposing = false;
@@ -87,17 +82,9 @@ var LspClient = class _LspClient {
   get pid() {
     return this.pidValue;
   }
-  /** 还能用吗。池按这个决定要不要重启（验收 9） */
   get alive() {
     return this.dead === null;
   }
-  /**
-   * 起进程 + `initialize` + `initialized`。
-   *
-   * 起不来 / 初始化超时都**返回 `null` 而不抛** —— 调用方据此把这个语言标记
-   * 不可用，整轮照常出结果（验收 8）。抛出去的话一个慢 server 就能让整次工具
-   * 调用失败，而那正是这条验收要避免的。
-   */
   static async start(options) {
     const { spec, launch, projectRoot } = options;
     let self = null;
@@ -106,13 +93,8 @@ var LspClient = class _LspClient {
       args: launch.args,
       cwd: projectRoot,
       spawnOptions: {
-        // infra 的默认值是 `['ignore', 'pipe', 'pipe']`，而 LSP over stdio **要
-        // stdin**。`spawnOptions` 在 infra 里是最后展开的，所以这里盖得掉
         stdio: ["pipe", "pipe", "pipe"],
         ...launch.verbatim ? { windowsVerbatimArguments: true } : {},
-        // `launch.env` 只有项目本地那一档有（它拿 `execPath` 当 node 使）。
-        // **必须连 `process.env` 一起摊开**：给 `env` 赋值是整份替换而不是叠加，
-        // 只放那一格等于把 PATH / HOME 抽掉，server 当场起不来
         ...launch.env ? { env: { ...process.env, ...launch.env } } : {}
       },
       onOutput: (chunk, stream) => {
@@ -141,7 +123,6 @@ var LspClient = class _LspClient {
     }
     return self;
   }
-  /** 订阅推送 + 兜住 server 反过来发的那几种请求 */
   wire() {
     this.connection.onNotification(
       PublishDiagnosticsNotification.type,
@@ -184,9 +165,6 @@ var LspClient = class _LspClient {
             willSaveWaitUntil: false,
             didSave: false
           },
-          // **这一段不能省**：typescript-language-server 用它算
-          // `features.diagnosticsSupport`，不声明就一条诊断都不推 ——
-          // 表现成「所有文件都没问题」，最坏的那种失败
           publishDiagnostics: { relatedInformation: true, versionSupport: false }
         }
       },
@@ -204,11 +182,6 @@ var LspClient = class _LspClient {
       return false;
     }
   }
-  /**
-   * 打开 / 更新这批文件，等到静默，交出诊断。
-   *
-   * @throws {LspServerDownError} 进程中途没了（验收 9 的输入）
-   */
   async diagnose(documents, wait) {
     if (this.dead) throw new LspServerDownError(this.dead);
     if (documents.length === 0) return { byPath: /* @__PURE__ */ new Map(), pending: [] };
@@ -237,7 +210,6 @@ var LspClient = class _LspClient {
     }
     return { byPath, pending };
   }
-  /** 没打开过就 `didOpen`，打开过就 `didChange`（全量） */
   async sync(doc) {
     const uri = pathToFileURL(doc.path).toString();
     const key = uriKey(uri);
@@ -253,12 +225,9 @@ var LspClient = class _LspClient {
     open.version += 1;
     await this.connection.sendNotification(DidChangeTextDocumentNotification.type, {
       textDocument: { uri: open.uri, version: open.version },
-      // 全量替换。增量同步要自己维护一份影子文档才算得出 range，而我们每次拿到的
-      // 本来就是磁盘上的完整内容 —— 算 diff 只是把复杂度换成一个新的错误来源
       contentChanges: [{ text: doc.text }]
     });
   }
-  /** 超过上限就把最早打开、且不在本批里的文档关掉 */
   async evictOverflow(keep) {
     for (const [key, open] of [...this.openDocs]) {
       if (this.openDocs.size <= MAX_OPEN_DOCUMENTS) return;
@@ -270,31 +239,10 @@ var LspClient = class _LspClient {
       });
     }
   }
-  /**
-   * 关掉这个 server。
-   *
-   * 先按协议 `shutdown` + `exit`，给它清临时文件的机会；超预算就直接杀树。
-   * **杀树那一步不能省** —— `typescript-language-server` 自己还 fork 了一个
-   * `tsserver.js`，只杀父进程会留下孤儿（验收 7）。
-   *
-   * ## ⚠️ 三步的**顺序**是判据：拍快照 → 优雅关 → 清扫快照
-   *
-   * 这里原来只有两步（优雅关 → `killTrackedProcess`），而那是**漏的**：
-   * `killTrackedProcess` 底下是 `killProcessTree`，靠的是**现场遍历**
-   * （`pgrep -P` / `taskkill /t`）。等我们优雅关完，直接子进程已经退了 ——
-   * 树的根没了，孙进程的 PPID 指向一个死 pid，遍历再也找不到它们。
-   * 于是 `tsserver` 那一层在 POSIX 上被 init 收养、在 Windows 上直接常驻到关机。
-   *
-   * 所以快照必须在**动手之前**拍。这不是新发明：`plugin-mcp` 的
-   * `closeTransportAndReap` 就是这三步，而它有一条会红的用例守着；
-   * 我们这边验收 #7 一直挂着「双平台手验」没人做，于是漏了一年半。
-   * 2026-08-12 补的 [orphan-reap.test.ts](../__tests__/orphan-reap.test.ts)
-   * 把这条钉死了 —— 把下面的快照挪到 `killTrackedProcess` 之后，它当场红。
-   */
   async dispose() {
     if (this.disposing) return;
     this.disposing = true;
-    const tree = await collectProcessTree(this.pidValue).catch(() => []);
+    const tree = await collectProcessTreeStamped(this.pidValue).catch(() => []);
     try {
       await withTimeoutOrNull(
         (async () => {
@@ -311,7 +259,7 @@ var LspClient = class _LspClient {
     }
     this.dead ??= "\u5DF2\u4E3B\u52A8\u5173\u95ED";
     await killTrackedProcess(this.pidValue);
-    if (tree.length > 0) await killPids(tree, { escalate: true });
+    if (tree.length > 0) await killStampedPids(tree, { escalate: true });
   }
 };
 function sleep(ms) {
@@ -333,10 +281,8 @@ async function withTimeoutOrNull(promise, ms) {
     if (timer) clearTimeout(timer);
   }
 }
-
 // src/servers.ts
 import { dirname as dirname2, join as join2 } from "path";
-
 // src/find-up.ts
 import { existsSync } from "fs";
 import { dirname, join, resolve } from "path";
@@ -353,7 +299,6 @@ function findUp(startDir, relativePath, options = {}) {
   }
   return null;
 }
-
 // src/servers.ts
 var TS_LANGUAGE_IDS = {
   ".ts": "typescript",
@@ -391,15 +336,10 @@ function serverForExtension(ext) {
 function supportedExtensions() {
   return Object.keys(TS_LANGUAGE_IDS).sort();
 }
-
 // src/diagnose.ts
 var MAX_FILES_PER_CALL = 50;
 var DEFAULT_WAIT = {
-  // tsserver 一个文件分三次推（语法 / 语义 / 建议），各带 50ms 去抖。
-  // 400ms 静默足够让三次都落地，又不会平白给每次调用加一秒
   settleMs: 400,
-  // 内容没变时 server 干脆不推（见 client.ts）。这时要等的是
-  // typescript-language-server 那个 300–800ms 的触发延迟走完，确认它真的不打算说话
   fallbackMs: 1500,
   timeoutMs: 15e3
 };
@@ -425,7 +365,6 @@ function messageOf(message) {
 function toItem(diag, file) {
   const item = {
     file,
-    // LSP 的行列都是 0 起的，人和其它工具用的是 1 起
     line: diag.range.start.line + 1,
     column: diag.range.start.character + 1,
     severity: severityOf(diag.severity),
@@ -566,7 +505,6 @@ async function diagnosePaths(input) {
   sortItems(outcome.diagnostics);
   return outcome;
 }
-
 // src/format.ts
 var MAX_ITEMS = 100;
 var MAX_MESSAGE = 400;
@@ -638,7 +576,6 @@ function formatOutcome(outcome) {
   }
   return lines.join("\n");
 }
-
 // src/detect.ts
 import { existsSync as existsSync2, readFileSync } from "fs";
 import { dirname as dirname3, join as join3, posix, win32 } from "path";
@@ -686,8 +623,6 @@ function projectLaunch(spec, projectRoot, o) {
     file: o.execPath,
     args: [entry, ...spec.args],
     origin: `\u9879\u76EE node_modules\uFF08${packageDir}\uFF09`,
-    // 嵌进 Electron 的宿主里 `execPath` 是宿主自己的可执行文件，少了这一格
-    // 起 language server 等于启动第二个 app 实例
     env: EXEC_PATH_AS_NODE_ENV
   };
 }
@@ -697,8 +632,6 @@ function shimLaunch(shim, spec, o) {
   return {
     tier: "path",
     file: o.env["ComSpec"] ?? o.env["COMSPEC"] ?? "cmd.exe",
-    // 整条命令再包一层引号是 cmd 的老规矩：`/s` 让它只剥最外层，
-    // 里面那对（路径带空格时的）引号才留得住
     args: ["/d", "/s", "/c", `"${command}"`],
     origin: `PATH\uFF08${shim}\uFF09`,
     verbatim: true
@@ -734,7 +667,6 @@ function resolveServer(spec, projectRoot, options = {}) {
     install: spec.install
   };
 }
-
 // src/pool.ts
 var DEFAULT_IDLE_MS = 10 * 60 * 1e3;
 var DEFAULT_SWEEP_MS = 60 * 1e3;
@@ -742,7 +674,6 @@ var MAX_FAILURES = 2;
 var LspServerPool = class {
   entries = /* @__PURE__ */ new Map();
   failures = /* @__PURE__ */ new Map();
-  /** 同一个 key 上并发的 acquire 共用一次启动，不然会起出两个 tsserver */
   starting = /* @__PURE__ */ new Map();
   timer = null;
   sweeping = false;
@@ -758,11 +689,9 @@ var LspServerPool = class {
     this.resolve = options.resolve ?? ((spec, root) => resolveServer(spec, root));
     this.start = options.start ?? ((opts) => LspClient.start(opts));
   }
-  /** 活着的实例数。验收 5（懒启动）就是断言它一开始是 0 */
   get size() {
     return this.entries.size;
   }
-  /** 拿一个可用的 client；拿不到就说清为什么 */
   async acquire(spec, projectRoot) {
     const key = `${projectRoot}\0${spec.id}`;
     const existing = this.entries.get(key);
@@ -821,12 +750,6 @@ var LspServerPool = class {
     const prev = this.failures.get(key);
     this.failures.set(key, { count: (prev?.count ?? 0) + 1, detail });
   }
-  /**
-   * 回收空闲实例。定时器调它，测试也直接调它。
-   *
-   * 重入保护不是洁癖：`dispose()` 里有一次最多 2s 的优雅退出，而扫描间隔是
-   * 1 分钟 —— 真卡住的时候两次扫描会叠在一起，对同一个 client 调两次 dispose。
-   */
   async sweep() {
     if (this.sweeping) return;
     this.sweeping = true;
@@ -844,7 +767,6 @@ var LspServerPool = class {
       this.sweeping = false;
     }
   }
-  /** 全部关掉。宿主 dispose 时调；也是测试的收尾 */
   async disposeAll() {
     this.stopSweeper();
     const all = [...this.entries.values()].map((e) => e.client);
@@ -862,7 +784,6 @@ var LspServerPool = class {
     this.timer = null;
   }
 };
-
 // src/index.ts
 var ERR_BAD_PATHS = 8001;
 var ERR_UNEXPECTED = 8002;
@@ -908,16 +829,8 @@ var lspPlugin = {
         },
         required: ["paths"]
       },
-      // 只读 + 不碰网络。`idempotentHint: false` 是因为文件内容会变 ——
-      // 同一批路径这一秒和下一秒的诊断可以不一样
       annotations: { readOnlyHint: true, idempotentHint: false, openWorldHint: false },
-      // `file_read` 而不是 `command`：这个工具对外的语义就是「读几个文件、报问题」。
-      // 底下确实起了子进程，但那个进程是**我们表里写死的**（`servers.ts`），
-      // 参数里没有任何一段来自模型 —— 归到 command 只会让每次诊断都弹一次审批，
-      // 而 system prompt 恰恰要求模型每轮改完都调它
       operation: "file_read",
-      // 审批目标是文件清单。不给的话调度侧会退回 `JSON.stringify(args)`，
-      // 换个顺序传同样几个文件就不命中缓存了
       describeTarget: (args) => (toPaths(args["paths"]) ?? []).join(", "),
       execute: async (args, ctx) => {
         const started = Date.now();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epoch-agent/plugin-lsp",
-  "version": "0.1.0",
+  "version": "0.3.1",
   "private": false,
   "description": "LSP 诊断插件 — 探测项目自带的 language server，按文件取语义诊断",
   "repository": {
@@ -24,8 +24,8 @@
   "dependencies": {
     "vscode-jsonrpc": "^9.0.1",
     "vscode-languageserver-protocol": "^3.17.5",
-    "@epoch-agent/infra": "0.1.0",
-    "@epoch-agent/protocol": "0.1.0"
+    "@epoch-agent/protocol": "0.3.1",
+    "@epoch-agent/infra": "0.3.1"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",