pi-web-ui 0.62.0 → 0.63.0

package/dist/server/wait-subscription-scan.js

@@ -24,7 +24,7 @@
 // background subagent run, so its runtime must be kept alive across project /
 // conversation switches. See the Chinese block above for the persistence layout
 // and the fail-open vs fail-closed rationale.
-import { readdirSync, readFileSync } from "node:fs";
+import { readdirSync, readFileSync, statSync } from "node:fs";
 import { homedir, tmpdir, userInfo } from "node:os";
 import path from "node:path";
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
@@ -37,15 +37,17 @@ function parseRecord(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return undefined;
     const record = value;
-    if (record.version !== 1
-        || typeof record.token !== "string"
-        || !UUID_RE.test(record.token)
-        || typeof record.sessionId !== "string"
-        || (record.targetKind !== "async" && record.targetKind !== "foreground")
-        || typeof record.runId !== "string"
-        || typeof record.requestedId !== "string"
-        || typeof record.createdAt !== "number" || !Number.isFinite(record.createdAt)
-        || typeof record.expiresAt !== "number" || !Number.isFinite(record.expiresAt))
+    if (record.version !== 1 ||
+        typeof record.token !== "string" ||
+        !UUID_RE.test(record.token) ||
+        typeof record.sessionId !== "string" ||
+        (record.targetKind !== "async" && record.targetKind !== "foreground") ||
+        typeof record.runId !== "string" ||
+        typeof record.requestedId !== "string" ||
+        typeof record.createdAt !== "number" ||
+        !Number.isFinite(record.createdAt) ||
+        typeof record.expiresAt !== "number" ||
+        !Number.isFinite(record.expiresAt))
         return undefined;
     return record;
 }
@@ -98,13 +100,89 @@ export function resolveTempScopeId(env = process.env, getuid = process.getuid?.b
     }
     return "shared";
 }
+/** <pi-subagents 临时根>：PI_SUBAGENTS_TEMP_ROOT 优先，否则 tmpdir()/pi-subagents-<scope>。 */
+function resolveTempRoot(env) {
+    const configured = env.PI_SUBAGENTS_TEMP_ROOT?.trim();
+    return configured ? path.resolve(configured) : path.join(tmpdir(), `pi-subagents-${resolveTempScopeId(env)}`);
+}
 /** wait-subscriptions 目录默认位置（与 pi-subagents 的推导一致）。 */
 export function resolveSubscriptionsDir(env = process.env) {
-    const configured = env.PI_SUBAGENTS_TEMP_ROOT?.trim();
-    const root = configured
-        ? path.resolve(configured)
-        : path.join(tmpdir(), `pi-subagents-${resolveTempScopeId(env)}`);
-    return path.join(path.dirname(path.join(root, "async-subagent-runs")), "wait-subscriptions");
+    return path.join(resolveTempRoot(env), "wait-subscriptions");
+}
+/** 异步 run 目录根（asyncDirRoot）默认位置：<TEMP_ROOT>/async-subagent-runs。 */
+export function resolveAsyncRunsDir(env = process.env) {
+    return path.join(resolveTempRoot(env), "async-subagent-runs");
+}
+/**
+ * 活跃 run marker 的最长可信存活期：对齐 pi-subagents
+ * active-run-index.ts 的 DEFAULT_STALE_TERMINAL_ACTIVE_MARKER_MS（24h）。
+ * 崩溃遗留的 marker 超过该时长即视为孤儿，不阻止运行时释放（保留自限）。
+ */
+export const DEFAULT_STALE_ACTIVE_MARKER_MS = 24 * 60 * 60 * 1000;
+/** 活跃 marker 索引目录名，与 pi-subagents 的 ACTIVE_RUN_INDEX_DIR 一致。 */
+const ACTIVE_RUN_INDEX_DIR = ".active-runs";
+/**
+ * 磁盘扫描：该会话是否还有活跃（queued/running）的 pi-subagents 异步 run。
+ * 任何 I/O / 解析 / 过期错误都按「无证据」处理（fail-open，见文件头说明）。
+ * ENOENT（目录/文件尚不存在、marker 刚被清掉）保持静默；其余 I/O 错误
+ * console.warn 一次（与 hasPendingWaitSubscription 对齐）。
+ */
+export function hasActiveSubagentRun(options) {
+    const sessionId = options.sessionId;
+    if (!sessionId)
+        return false;
+    const now = options.now ?? Date.now;
+    const staleMarkerMs = options.staleMarkerMs ?? DEFAULT_STALE_ACTIVE_MARKER_MS;
+    const warn = options.warn ?? ((message, error) => console.warn(message, error));
+    const isNotFound = (error) => typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT";
+    const runsDir = options.asyncRunsDir ?? resolveAsyncRunsDir();
+    const indexDir = path.join(runsDir, ACTIVE_RUN_INDEX_DIR);
+    let markers;
+    try {
+        markers = readdirSync(indexDir);
+    }
+    catch (error) {
+        if (!isNotFound(error))
+            warn(`Failed to scan active-run index in '${indexDir}':`, error);
+        return false; // 索引目录缺失 / 不可读 → 无证据
+    }
+    for (const runId of markers) {
+        if (runId.startsWith("."))
+            continue; // 不把隐藏文件当 run 证据
+        const markerFile = path.join(indexDir, runId);
+        // 孤儿防护：marker 太久没被 touch（崩溃遗留，run 早已不在）→ 无证据。
+        try {
+            const ageMs = now() - statSync(markerFile).mtimeMs;
+            if (ageMs > staleMarkerMs)
+                continue;
+        }
+        catch (error) {
+            if (!isNotFound(error))
+                warn(`Failed to stat active-run marker '${markerFile}':`, error);
+            continue; // ENOENT（刚被清除的竞态）→ 无证据
+        }
+        let status;
+        try {
+            status = JSON.parse(readFileSync(path.join(runsDir, runId, "status.json"), "utf-8"));
+        }
+        catch (error) {
+            if (!isNotFound(error))
+                warn(`Failed to read async run status '${path.join(runsDir, runId, "status.json")}':`, error);
+            continue; // 缺失 / 损坏 → 无证据（fail-open）
+        }
+        if (!status || typeof status !== "object" || Array.isArray(status))
+            continue;
+        const probe = status;
+        if (probe.sessionId !== sessionId)
+            continue; // 别的会话的 run
+        if (probe.state !== "queued" && probe.state !== "running")
+            continue; // 已结束
+        return true;
+    }
+    return false;
 }
 /**
  * 磁盘扫描：该会话是否还有未过期的 wake 订阅记录。
@@ -119,8 +197,10 @@ export function hasPendingWaitSubscription(options) {
         return false;
     const now = options.now ?? Date.now;
     const warn = options.warn ?? ((message, error) => console.warn(message, error));
-    const isNotFound = (error) => typeof error === "object" && error !== null && "code" in error
-        && error.code === "ENOENT";
+    const isNotFound = (error) => typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT";
     const dir = options.subscriptionsDir ?? resolveSubscriptionsDir();
     let files;
     try {
@@ -163,7 +243,7 @@ export function hasPendingWaitSubscription(options) {
  * 纯函数版置换决策：true = 保留（不得 dispose），false = 调用方可释放。
  * Pure decision core of displaceActive(): true = retain, false = may dispose.
  * 顺序与 displaceActive 保持一致：review/wizard → streaming → terminals →
- * pending wake → listed+continued（「打开后继续过」的会话也保留）。
+ * active subagent run → pending wake → listed+continued（「打开后继续过」的会话也保留）。
  */
 export function shouldRetainActive(input) {
     if (input.reviewing || input.wizardRunning)
@@ -172,9 +252,10 @@ export function shouldRetainActive(input) {
         return true;
     if (input.openTerminals > 0)
         return true;
-    const hasPendingWake = typeof input.hasPendingWake === "function"
-        ? input.hasPendingWake()
-        : input.hasPendingWake;
+    const hasActiveRun = typeof input.hasActiveSubagentRun === "function" ? input.hasActiveSubagentRun() : input.hasActiveSubagentRun;
+    if (hasActiveRun)
+        return true;
+    const hasPendingWake = typeof input.hasPendingWake === "function" ? input.hasPendingWake() : input.hasPendingWake;
     if (hasPendingWake)
         return true;
     if (input.listed && input.promptedSinceActive)

package/dist/server/webui-context.js

@@ -17,7 +17,7 @@ const mockTheme = new Proxy({
         if (prop in target)
             return target[prop];
         // Unknown theme methods → no-op passthrough.
-        return (_arg, text) => text !== undefined ? text : "";
+        return (_arg, text) => (text !== undefined ? text : "");
     },
 });
 /** Mock TUI: any method call is a safe no-op. */

package/extensions/webui.ts

@@ -1,192 +1,190 @@
-/**
- * pi-web-ui 的 pi 扩展 —— 提供命令行集成。
- *
- * 能力：
- *   /webui                      启动本机 pi-web-ui 服务器，打开浏览器访问
- *   /webui --port 9000          指定端口启动
- *   /webui --no-browser         启动但不开浏览器
- *   /webui stop                 停止已启动的服务器
- *   /webui status               查看运行状态 / URL
- *
- * 实现说明：
- *   - 不依赖全局 bin（pi install 后 pi-web-ui 命令不一定在 PATH），直接用
- *     node 调包内 dist/server/index.js，通过环境变量 PORT / PI_WEB_CWD /
- *     PI_WEB_DATA_DIR 控制。
- *   - 工作目录默认用当前 pi 会话的 ctx.cwd；可用 --cwd / path 覆盖。
- *   - 服务器作为子进程后台运行，/webui 不阻塞 pi。
- *   - 每个 pi 会话管理一个子进程；session_shutdown 时清理，避免孤儿进程。
- */
-
-import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import net from "node:net";
-import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-
-// 本文件位于 <pkg>/extensions/webui.ts → 包根在上一级
-const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const SERVER_ENTRY = join(PKG_ROOT, "dist", "server", "index.js");
-const NODE = process.execPath;
-
-/** 每个会话的服务器子进程 + 元数据 */
-interface RunningServer {
-	proc: ReturnType<typeof spawn>;
-	port: number;
-	cwd: string;
-	url: string;
-}
-
-// 会话 → 运行实例（模块级 Map；每会话一个会话对象，无需清理全局）
-const running = new Map<string, RunningServer>();
-
-/** 找一个空闲端口 */
-function findFreePort(from = 8787): Promise<number> {
-	return new Promise((resolve_, reject) => {
-		const srv = net.createServer();
-		srv.listen(from, () => {
-			const port = (srv.address() as net.AddressInfo).port;
-			srv.close(() => resolve_(port));
-		});
-		srv.on("error", () => {
-			// 端口被占则顺延
-			findFreePort(from + 1).then(resolve_, reject);
-		});
-	});
-}
-
-/** 解析 --key value / --flag 参数 */
-function parseArgs(args: string): { port?: number; cwd?: string; noBrowser: boolean } {
-	const out: { port?: number; cwd?: string; noBrowser: boolean } = { noBrowser: false };
-	const toks = args.split(/\s+/).filter(Boolean);
-	for (let i = 0; i < toks.length; i++) {
-		const t = toks[i];
-		if ((t === "--port" || t === "-p") && toks[i + 1]) {
-			const n = Number(toks[++i]);
-			if (Number.isInteger(n) && n > 0 && n < 65536) out.port = n;
-		} else if ((t === "--cwd") && toks[i + 1]) {
-			out.cwd = resolve(toks[++i]);
-		} else if (t === "--no-browser") {
-			out.noBrowser = true;
-		}
-	}
-	return out;
-}
-
-/** 打开浏览器 */
-async function openBrowser(url: string): Promise<void> {
-	const { platform } = process;
-	const [cmd, ...rest] =
-		platform === "darwin"
-			? ["open", url]
-			: platform === "win32"
-				? ["cmd", "/c", "start", "", url]
-				: ["xdg-open", url];
-	// 无界面环境缺少 xdg-open 等打开器时，ENOENT 以异步 'error' 事件触发，
-	// try/catch 拦不住会崩掉整个进程 —— 必须挂 error 监听。
-	spawn(cmd, rest, { stdio: "ignore", detached: true })
-		.on("error", (err) => {
-			if ((err as NodeJS.ErrnoException)?.code === "ENOENT") {
-				console.warn(
-					`[webui] 未找到浏览器打开器 (${(err as NodeJS.ErrnoException).path || "command not found"})，请用 --no-browser 关闭自动打开`
-				);
-			} else {
-				console.warn("[webui] 打开浏览器失败:", err.message);
-			}
-		})
-		.unref();
-}
-
-export default function (pi: ExtensionAPI): void {
-	pi.registerCommand("webui", {
-		description: "启动本机 pi-web-ui Web 界面（/webui [--port N] [--cwd PATH] [--no-browser] | stop | status）",
-		handler: async (args: string, ctx: ExtensionCommandContext) => {
-			const sid = ctx.sessionManager.getSessionId();
-			const opts = parseArgs(args);
-			const action = (args.split(/\s+/)[0] || "start").toLowerCase();
-
-			// 停止
-			if (action === "stop" || action === "kill") {
-				const inst = running.get(sid);
-				if (!inst) {
-					ctx.ui.notify("没有正在运行的本机 pi-web-ui 服务器", "info");
-					return;
-				}
-				inst.proc.kill("SIGTERM");
-				running.delete(sid);
-				ctx.ui.notify(`已停止 pi-web-ui (${inst.url})`, "info");
-				return;
-			}
-
-			// 状态
-			if (action === "status") {
-				const inst = running.get(sid);
-				if (!inst) {
-					ctx.ui.notify("本机 pi-web-ui 未运行", "info");
-					return;
-				}
-				const alive = inst.proc.exitCode === null;
-				ctx.ui.notify(
-					alive ? `pi-web-ui 运行中 → ${inst.url}\n端口 ${inst.port} · cwd ${inst.cwd}` : `已退出(exit=${inst.proc.exitCode})`,
-					alive ? "info" : "warning",
-				);
-				return;
-			}
-
-			// 默认 start
-			if (action !== "start" && action !== "run") {
-				ctx.ui.notify(`未知动作 ${action}（可用 start|stop|status）`, "warning");
-				return;
-			}
-
-			// 已运行则提示
-			const existing = running.get(sid);
-			if (existing && existing.proc.exitCode === null) {
-				ctx.ui.notify(`pi-web-ui 已在运行 → ${existing.url}`, "info");
-				return;
-			}
-
-			// 检查是否已构建
-			if (!existsSync(SERVER_ENTRY)) {
-				ctx.ui.notify(
-					"缺少 dist/ 产物（当前安装未包含已构建前端）。请运行 `npm run build` 后重试，或用 pi-web-ui 官方 npm 包。",
-					"warning",
-				);
-				return;
-			}
-
-			const port = opts.port ?? (await findFreePort());
-			const cwd = opts.cwd ?? ctx.cwd;
-			const url = `http://localhost:${port}`;
-
-			const env = {
-				...process.env,
-				PORT: String(port),
-				PI_WEB_CWD: cwd,
-				...(process.env.PI_WEB_DATA_DIR ? {} : { PI_WEB_DATA_DIR: join(cwd, ".pi-web") }),
-			};
-			const proc = spawn(NODE, [SERVER_ENTRY], { cwd, env, stdio: "ignore", detached: true });
-			proc.unref();
-			running.set(sid, { proc, port, cwd, url });
-
-			ctx.ui.notify(`pi-web-ui 启动中 → ${url}\n端口 ${port} · cwd ${cwd}\n(几秒后可用，/webui status 查看)`);
-
-			if (!opts.noBrowser) await openBrowser(url);
-
-			// 进程退出时清理
-			proc.on("exit", () => {
-				if (running.get(sid)?.proc === proc) running.delete(sid);
-			});
-		},
-	});
-
-	// 会话结束清理子进程，避免孤儿
-	pi.on("session_shutdown", async (_event, ctx) => {
-		const sid = ctx.sessionManager.getSessionId();
-		const inst = running.get(sid);
-		if (inst && inst.proc.exitCode === null) {
-			inst.proc.kill("SIGTERM");
-			running.delete(sid);
-		}
-	});
-}
+/**
+ * pi-web-ui 的 pi 扩展 —— 提供命令行集成。
+ *
+ * 能力：
+ *   /webui                      启动本机 pi-web-ui 服务器，打开浏览器访问
+ *   /webui --port 9000          指定端口启动
+ *   /webui --no-browser         启动但不开浏览器
+ *   /webui stop                 停止已启动的服务器
+ *   /webui status               查看运行状态 / URL
+ *
+ * 实现说明：
+ *   - 不依赖全局 bin（pi install 后 pi-web-ui 命令不一定在 PATH），直接用
+ *     node 调包内 dist/server/index.js，通过环境变量 PORT / PI_WEB_CWD /
+ *     PI_WEB_DATA_DIR 控制。
+ *   - 工作目录默认用当前 pi 会话的 ctx.cwd；可用 --cwd / path 覆盖。
+ *   - 服务器作为子进程后台运行，/webui 不阻塞 pi。
+ *   - 每个 pi 会话管理一个子进程；session_shutdown 时清理，避免孤儿进程。
+ */
+
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import net from "node:net";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+// 本文件位于 <pkg>/extensions/webui.ts → 包根在上一级
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const SERVER_ENTRY = join(PKG_ROOT, "dist", "server", "index.js");
+const NODE = process.execPath;
+
+/** 每个会话的服务器子进程 + 元数据 */
+interface RunningServer {
+	proc: ReturnType<typeof spawn>;
+	port: number;
+	cwd: string;
+	url: string;
+}
+
+// 会话 → 运行实例（模块级 Map；每会话一个会话对象，无需清理全局）
+const running = new Map<string, RunningServer>();
+
+/** 找一个空闲端口 */
+function findFreePort(from = 8787): Promise<number> {
+	return new Promise((resolve_, reject) => {
+		const srv = net.createServer();
+		srv.listen(from, () => {
+			const port = (srv.address() as net.AddressInfo).port;
+			srv.close(() => resolve_(port));
+		});
+		srv.on("error", () => {
+			// 端口被占则顺延
+			findFreePort(from + 1).then(resolve_, reject);
+		});
+	});
+}
+
+/** 解析 --key value / --flag 参数 */
+function parseArgs(args: string): { port?: number; cwd?: string; noBrowser: boolean } {
+	const out: { port?: number; cwd?: string; noBrowser: boolean } = { noBrowser: false };
+	const toks = args.split(/\s+/).filter(Boolean);
+	for (let i = 0; i < toks.length; i++) {
+		const t = toks[i];
+		if ((t === "--port" || t === "-p") && toks[i + 1]) {
+			const n = Number(toks[++i]);
+			if (Number.isInteger(n) && n > 0 && n < 65536) out.port = n;
+		} else if (t === "--cwd" && toks[i + 1]) {
+			out.cwd = resolve(toks[++i]);
+		} else if (t === "--no-browser") {
+			out.noBrowser = true;
+		}
+	}
+	return out;
+}
+
+/** 打开浏览器 */
+async function openBrowser(url: string): Promise<void> {
+	const { platform } = process;
+	const [cmd, ...rest] =
+		platform === "darwin" ? ["open", url] : platform === "win32" ? ["cmd", "/c", "start", "", url] : ["xdg-open", url];
+	// 无界面环境缺少 xdg-open 等打开器时，ENOENT 以异步 'error' 事件触发，
+	// try/catch 拦不住会崩掉整个进程 —— 必须挂 error 监听。
+	spawn(cmd, rest, { stdio: "ignore", detached: true })
+		.on("error", (err) => {
+			if ((err as NodeJS.ErrnoException)?.code === "ENOENT") {
+				console.warn(
+					`[webui] 未找到浏览器打开器 (${(err as NodeJS.ErrnoException).path || "command not found"})，请用 --no-browser 关闭自动打开`,
+				);
+			} else {
+				console.warn("[webui] 打开浏览器失败:", err.message);
+			}
+		})
+		.unref();
+}
+
+export default function (pi: ExtensionAPI): void {
+	pi.registerCommand("webui", {
+		description: "启动本机 pi-web-ui Web 界面（/webui [--port N] [--cwd PATH] [--no-browser] | stop | status）",
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			const sid = ctx.sessionManager.getSessionId();
+			const opts = parseArgs(args);
+			const action = (args.split(/\s+/)[0] || "start").toLowerCase();
+
+			// 停止
+			if (action === "stop" || action === "kill") {
+				const inst = running.get(sid);
+				if (!inst) {
+					ctx.ui.notify("没有正在运行的本机 pi-web-ui 服务器", "info");
+					return;
+				}
+				inst.proc.kill("SIGTERM");
+				running.delete(sid);
+				ctx.ui.notify(`已停止 pi-web-ui (${inst.url})`, "info");
+				return;
+			}
+
+			// 状态
+			if (action === "status") {
+				const inst = running.get(sid);
+				if (!inst) {
+					ctx.ui.notify("本机 pi-web-ui 未运行", "info");
+					return;
+				}
+				const alive = inst.proc.exitCode === null;
+				ctx.ui.notify(
+					alive
+						? `pi-web-ui 运行中 → ${inst.url}\n端口 ${inst.port} · cwd ${inst.cwd}`
+						: `已退出(exit=${inst.proc.exitCode})`,
+					alive ? "info" : "warning",
+				);
+				return;
+			}
+
+			// 默认 start
+			if (action !== "start" && action !== "run") {
+				ctx.ui.notify(`未知动作 ${action}（可用 start|stop|status）`, "warning");
+				return;
+			}
+
+			// 已运行则提示
+			const existing = running.get(sid);
+			if (existing && existing.proc.exitCode === null) {
+				ctx.ui.notify(`pi-web-ui 已在运行 → ${existing.url}`, "info");
+				return;
+			}
+
+			// 检查是否已构建
+			if (!existsSync(SERVER_ENTRY)) {
+				ctx.ui.notify(
+					"缺少 dist/ 产物（当前安装未包含已构建前端）。请运行 `npm run build` 后重试，或用 pi-web-ui 官方 npm 包。",
+					"warning",
+				);
+				return;
+			}
+
+			const port = opts.port ?? (await findFreePort());
+			const cwd = opts.cwd ?? ctx.cwd;
+			const url = `http://localhost:${port}`;
+
+			const env = {
+				...process.env,
+				PORT: String(port),
+				PI_WEB_CWD: cwd,
+				...(process.env.PI_WEB_DATA_DIR ? {} : { PI_WEB_DATA_DIR: join(cwd, ".pi-web") }),
+			};
+			const proc = spawn(NODE, [SERVER_ENTRY], { cwd, env, stdio: "ignore", detached: true });
+			proc.unref();
+			running.set(sid, { proc, port, cwd, url });
+
+			ctx.ui.notify(`pi-web-ui 启动中 → ${url}\n端口 ${port} · cwd ${cwd}\n(几秒后可用，/webui status 查看)`);
+
+			if (!opts.noBrowser) await openBrowser(url);
+
+			// 进程退出时清理
+			proc.on("exit", () => {
+				if (running.get(sid)?.proc === proc) running.delete(sid);
+			});
+		},
+	});
+
+	// 会话结束清理子进程，避免孤儿
+	pi.on("session_shutdown", async (_event, ctx) => {
+		const sid = ctx.sessionManager.getSessionId();
+		const inst = running.get(sid);
+		if (inst && inst.proc.exitCode === null) {
+			inst.proc.kill("SIGTERM");
+			running.delete(sid);
+		}
+	});
+}