pi-web-ui 0.2.0 → 0.2.2

package/README.md

@@ -72,7 +72,7 @@ PORT=9000 PI_WEB_CWD=/path/to/project pi-web-ui      # custom port / workspace
 ```
 
 To run it in the background or auto-start on boot, use a system service —
-see [Deploy & auto-start on boot](#deploy--auto-start-on-boot) (systemd /
+see [Deploy & auto-start on boot](#deploy--auto-start-on-boot) (systemd /
 launchd / Docker).
 
 The `pi-web-ui` command serves the built frontend and the WebSocket API from
@@ -85,6 +85,9 @@ wherever the package is installed — no repo checkout needed. It uses **your**
 - **Foreground**: press `Ctrl+C` in the terminal running it.
 - **systemd**: `sudo systemctl stop pi-web-ui`
 - **launchd**: `launchctl bootout gui/$(id -u)/com.xingshuyin.pi-web-ui`
+- **Windows (scheduled task)**: `pi-web-ui server stop` (or
+  `schtasks /End /TN pi-web-ui`; stops the running instance, auto-start stays
+  until `server uninstall`)
 - **Docker**: `docker compose stop` (stop + remove the container: `docker compose down`)
 
 (Background processes should be managed by a system service, not `nohup` —
@@ -134,23 +137,28 @@ pi-web-ui server uninstall             # remove the service entirely
 - **Linux** → systemd unit (auto-sudo): writes
   `/etc/systemd/system/pi-web-ui.service` and runs `systemctl enable --now`,
   logs via `journalctl -u pi-web-ui -f`.
+- **Windows** → Task Scheduler (no admin): creates a user task that starts at
+  logon (same as a launchd agent). It runs a `.cmd` wrapper generated at
+  `%APPDATA%\pi-web-ui\pi-web-ui.cmd` (sets env, cd's to the workspace,
+  launches node, appends logs to `%USERPROFILE%\pi-web-ui.log`). The task XML
+  is saved next to it; restarts on failure.
 - Options: `--port` (default 8787 or `$PORT`), `--cwd` (default `$PI_WEB_CWD`
   or the current directory), `--data-dir` (sessions), `--name` (custom service
   name; on macOS the label is `com.xingshuyin.pi-web-ui`, custom names become
-  `com.<name>.server`). `--print` previews the generated unit/plist without
-  applying it.
+  `com.<name>.server`). `--print` previews the generated unit/plist/task files
+  without applying it.
 - Rerunning `install` with new options regenerates the config and restarts the
   service — that's how you change the port/cwd of an installed service.
 
 ## Configuration
 
-| Env var | Default | Description |
-| --- | --- | --- |
-| `PORT` | `8787` | HTTP/WebSocket port |
-| `PI_WEB_CWD` | server's cwd | The workspace directory the agent operates in (read/edit/bash/write) |
-| `PI_WEB_DATA_DIR` | `<cwd>/.pi-web` | Where per-client session dirs are stored |
-| `PI_WEB_INLINE_FILE_MAX` | `12288` (12KB) | Text attachments at or below this size are inlined into the model context; larger files are passed as path references and the model reads them on demand (saves tokens for small edits) |
-| `PI_CODING_AGENT_DIR` | `~/.pi/agent` | pi config dir (auth.json, models.json, skills, extensions) |
+| Env var                    | Default           | Description                                                                                                                                                                             |
+| -------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PORT`                   | `8787`          | HTTP/WebSocket port                                                                                                                                                                     |
+| `PI_WEB_CWD`             | server's cwd      | The workspace directory the agent operates in (read/edit/bash/write)                                                                                                                    |
+| `PI_WEB_DATA_DIR`        | `<cwd>/.pi-web` | Where per-client session dirs are stored                                                                                                                                                |
+| `PI_WEB_INLINE_FILE_MAX` | `12288` (12KB)  | Text attachments at or below this size are inlined into the model context; larger files are passed as path references and the model reads them on demand (saves tokens for small edits) |
+| `PI_CODING_AGENT_DIR`    | `~/.pi/agent`   | pi config dir (auth.json, models.json, skills, extensions)                                                                                                                              |
 
 Example — point the agent at a project:
 
@@ -228,10 +236,10 @@ with three panes:
   `${pwd}` resolves to the agent's current working directory (the one shown in the chat
   view's file panel, changeable via set_cwd); `~` and relative paths also work. The `+`
   button at the top of the command panel creates a new entry.
-
-- **Middle — the terminal**: each tab is a real PTY (your `$SHELL`); output streams live
-  and you can type, Ctrl+C, resize, etc. exactly like a desktop terminal.
-
+- **Middle — the terminal**: each tab is a real PTY (your `$SHELL` on
+  macOS/Linux; PowerShell or cmd.exe — `$COMSPEC` — on Windows); output
+  streams live and you can type, Ctrl+C, resize, etc. exactly like a desktop
+  terminal. Git Bash users on Windows get their `$SHELL` automatically.
 - **Right — 终端 (tabs)**: VSCode-style vertical tab strip. `+` opens a plain shell in the
   current directory. Closing a tab kills its process.
 
@@ -254,13 +262,13 @@ Server → client: `ready`, `snapshot` (full `UiState`), `tool_delta`, `notice`,
 
 ## Scripts
 
-| Script | What it does |
-| --- | --- |
-| `npm run dev` | server (tsx watch) + Vite dev server with WS proxy |
-| `npm run build` | type-check + build frontend and server |
-| `npm start` | run the production server (serves `web/dist`) |
-| `npm run typecheck` | `tsc --noEmit` for both server and web |
-| `node terminal-smoke-test.mjs` | WS-level terminal/commands protocol test (build first) |
+| Script                             | What it does                                            |
+| ---------------------------------- | ------------------------------------------------------- |
+| `npm run dev`                    | server (tsx watch) + Vite dev server with WS proxy      |
+| `npm run build`                  | type-check + build frontend and server                  |
+| `npm start`                      | run the production server (serves`web/dist`)          |
+| `npm run typecheck`              | `tsc --noEmit` for both server and web                |
+| `node terminal-smoke-test.mjs`   | WS-level terminal/commands protocol test (build first)  |
 | `node terminal-browser-test.mjs` | headless-browser E2E of the terminal view (build first) |
 
 ## Deploy & auto-start on boot
@@ -306,8 +314,36 @@ launchctl bootout gui/$(id -u)/com.xingshuyin.pi-web-ui   # stop + remove auto-s
 # logs: /tmp/pi-web-ui.log, /tmp/pi-web-ui.err
 ```
 
-Both templates use `KeepAlive`/`Restart=on-failure` so the server survives
-crashes, and start at login/boot automatically.
+### Windows — Task Scheduler
+
+Easiest path (no admin, generates everything):
+
+```bat
+npm i -g pi-web-ui
+pi-web-ui server install --port 8787 --cwd C:\path\to\project
+pi-web-ui server status
+pi-web-ui server restart
+pi-web-ui server stop        :: stop the running instance (auto-start stays)
+pi-web-ui server uninstall   :: remove the task entirely
+```
+
+What it does: writes `%APPDATA%\pi-web-ui\pi-web-ui.cmd` (a `.cmd` wrapper
+that sets `PORT`/`PI_WEB_CWD`, cd's to the workspace, launches node and
+appends output to `%USERPROFILE%\pi-web-ui.log`) plus the Task Scheduler XML,
+then registers a **logon** task (`schtasks /Create /XML` — the task runs when
+you log in, same as a launchd agent; no admin needed). Preview both generated
+files without installing: `pi-web-ui server install --print`.
+
+Manual alternative with `deploy/pi-web-ui-task.xml`: edit the paths, save the
+file as **UTF-16 LE** (schtasks requires it), then
+`schtasks /Create /TN "pi-web-ui" /XML pi-web-ui-task.xml /F` and
+`schtasks /Run /TN "pi-web-ui"`.
+
+> **Boot-start without login?** A logon task needs an interactive session, just
+> like a launchd agent. For headless/always-on Windows use Docker (see above).
+
+The three templates use `KeepAlive` / `Restart=on-failure` / `RestartOnFailure`
+so the server survives crashes, and start at login/boot automatically.
 
 ## License
 

package/bin/pi-web-ui.mjs

@@ -10,9 +10,11 @@
  *   pi-web-ui server start|stop|restart|status [选项]
  *
  * 系统服务：
- *   - macOS  → launchd 用户代理，label 默认 com.xingshuyin.pi-web-ui
- *             （--name 自定义时 com.<name>.server），无需 sudo
- *   - Linux  → systemd 单元 <name>.service（/etc/systemd/system/，自动 sudo）
+ *   - macOS   → launchd 用户代理，label 默认 com.xingshuyin.pi-web-ui
+ *              （--name 自定义时 com.<name>.server），无需 sudo
+ *   - Linux   → systemd 单元 <name>.service（/etc/systemd/system/，自动 sudo）
+ *   - Windows → 计划任务（Task Scheduler / schtasks，登录后自启，无需管理员），
+ *              包装脚本与任务 XML 生成在 %APPDATA%\pi-web-ui\
  *
  * 环境变量（前台与系统服务均适用）：PORT / PI_WEB_CWD / PI_WEB_DATA_DIR /
  * PI_CODING_AGENT_DIR。
@@ -59,6 +61,9 @@ server 选项:
                     为 com.xingshuyin.pi-web-ui，自定义名时为 com.<name>.server）
   --print           只打印将生成的配置文件，不实际安装
 
+平台: macOS → launchd 用户代理 · Linux → systemd · Windows → 计划任务（schtasks）
+      （Windows 任务登录后自启、无需管理员；stop 停止，uninstall 移除）
+
 环境变量（前台与系统服务均适用）:
   PORT / PI_WEB_CWD / PI_WEB_DATA_DIR / PI_CODING_AGENT_DIR
 `;
@@ -146,6 +151,7 @@ async function startForeground(opts) {
 
 const isMac = process.platform === "darwin";
 const isLinux = process.platform === "linux";
+const isWin = process.platform === "win32";
 
 function uid() {
 	try {
@@ -155,7 +161,7 @@ function uid() {
 	}
 }
 
-/** launchd label / systemd unit name for a service name. */
+/** launchd label / systemd unit name / Windows task name for a service name. */
 function serviceLabel(name) {
 	if (isMac) {
 		return name === "pi-web-ui"
@@ -178,6 +184,110 @@ function systemdUnitPath(name) {
 	return `/etc/systemd/system/${name}.service`;
 }
 
+/** Windows: per-user config dir (%APPDATA%\pi-web-ui) holding the .cmd wrapper + task XML. */
+function winServiceDir() {
+	return join(
+		process.env.APPDATA ?? join(homedir(), "AppData", "Roaming"),
+		"pi-web-ui",
+	);
+}
+
+function winCmdPath(name) {
+	return join(winServiceDir(), `${name}.cmd`);
+}
+
+function winTaskXmlPath(name) {
+	return join(winServiceDir(), `${name}.xml`);
+}
+
+function winLogPath() {
+	return join(homedir(), "pi-web-ui.log");
+}
+
+/** True when a scheduled task with this name exists (schtasks exits 0). */
+function winTaskExists(name) {
+	return (
+		spawnSync("schtasks", ["/Query", "/TN", name], { stdio: "ignore" })
+			.status === 0
+	);
+}
+
+/** Build the .cmd wrapper the scheduled task runs (set env → cd → launch node → log). */
+function buildWinCmd(cwd, env, logPath) {
+	const sets = Object.entries(env)
+		.map(([k, v]) => `set "${k}=${v}"`)
+		.join("\r\n");
+	return [
+		"@echo off",
+		"rem Generated by: pi-web-ui server install (rerun to change)",
+		sets,
+		`cd /d "${cwd}"`,
+		`"${NODE}" "${SERVER_ENTRY}" >> "${logPath}" 2>&1`,
+		"",
+	].join("\r\n");
+}
+
+/**
+ * Build the Task Scheduler XML for a user task: LogonTrigger (starts at logon,
+ * like a launchd agent — no admin needed), InteractiveToken, auto-restart on
+ * failure. The task runs the .cmd wrapper via cmd.exe.
+ */
+function buildWinTaskXml(cmdPath, cwd) {
+	const cmdExe = join(
+		process.env.SystemRoot ?? "C:\\Windows",
+		"System32",
+		"cmd.exe",
+	);
+	return `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>pi-web-ui — web chat for the pi coding agent (auto-start at logon)</Description>
+  </RegistrationInfo>
+  <Triggers>
+    <LogonTrigger>
+      <Enabled>true</Enabled>
+    </LogonTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <AllowHardTerminate>true</AllowHardTerminate>
+    <StartWhenAvailable>false</StartWhenAvailable>
+    <RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>
+    <IdleSettings>
+      <StopOnIdleEnd>false</StopOnIdleEnd>
+      <RestartOnIdle>false</RestartOnIdle>
+    </IdleSettings>
+    <AllowStartOnDemand>true</AllowStartOnDemand>
+    <Enabled>true</Enabled>
+    <Hidden>false</Hidden>
+    <RunOnlyIfIdle>false</RunOnlyIfIdle>
+    <WakeToRun>false</WakeToRun>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <Priority>7</Priority>
+    <RestartOnFailure>
+      <Interval>PT1M</Interval>
+      <Count>3</Count>
+    </RestartOnFailure>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>${esc(cmdExe)}</Command>
+      <Arguments>/c ""${esc(cmdPath)}""</Arguments>
+      <WorkingDirectory>${esc(cwd)}</WorkingDirectory>
+    </Exec>
+  </Actions>
+</Task>
+`;
+}
+
 function esc(s) {
 	return s
 		.replace(/&/g, "&amp;")
@@ -288,8 +398,10 @@ function serviceEnv(port, cwd, dataDir) {
 	const env = {
 		PORT: port,
 		PI_WEB_CWD: cwd,
-		PATH: process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin",
 	};
+	// Interactive Windows tasks inherit the user's PATH; only systemd/launchd
+	// run with a minimal environment that needs an explicit PATH.
+	if (!isWin) env.PATH = process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin";
 	if (dataDir) env.PI_WEB_DATA_DIR = dataDir;
 	return env;
 }
@@ -363,6 +475,52 @@ function uninstallSystemd(opts) {
 	console.log(`🗑  已卸载 ${name}.service（不再开机自启）`);
 }
 
+function installWindows(opts) {
+	const { name, port, cwd, dataDir } = serviceOptions(opts);
+	const env = serviceEnv(port, cwd, dataDir);
+	const cmdPath = winCmdPath(name);
+	const xmlPath = winTaskXmlPath(name);
+	const cmd = buildWinCmd(cwd, env, winLogPath());
+	const xml = buildWinTaskXml(cmdPath, cwd);
+	if (opts.print) {
+		console.log(`# ${cmdPath}\n${cmd}`);
+		console.log(`# ${xmlPath}\n${xml}`);
+		return;
+	}
+	mkdirSync(dirname(cmdPath), { recursive: true });
+	writeFileSync(cmdPath, cmd);
+	// schtasks /Create /XML requires a UTF-16 file (with BOM).
+	writeFileSync(xmlPath, "\uFEFF" + xml, "utf16le");
+	if (winTaskExists(name)) {
+		run("schtasks", ["/Delete", "/TN", name, "/F"], {
+			ignoreError: true,
+			silent: true,
+		});
+	}
+	run("schtasks", ["/Create", "/TN", name, "/XML", xmlPath, "/F"]);
+	run("schtasks", ["/Run", "/TN", name], { ignoreError: true });
+	console.log(`✅ 已安装并启动计划任务 ${name}`);
+	console.log(`   端口 : ${port}`);
+	console.log(`   目录 : ${cwd}`);
+	console.log(`   访问 : http://localhost:${port}`);
+	console.log(`   日志 : ${winLogPath()}`);
+	console.log(
+		`   说明 : 登录后自启（与 launchd 用户代理一致）；stop 停止，uninstall 移除`,
+	);
+	console.log(`   管理 : pi-web-ui server status|restart|stop|uninstall`);
+}
+
+function uninstallWindows(opts) {
+	const name = opts.name ?? "pi-web-ui";
+	if (winTaskExists(name)) {
+		run("schtasks", ["/Delete", "/TN", name, "/F"], { ignoreError: true });
+	}
+	for (const f of [winCmdPath(name), winTaskXmlPath(name)]) {
+		if (existsSync(f)) rmSync(f);
+	}
+	console.log(`🗑  已卸载 ${name}（计划任务已删除，不再自启）`);
+}
+
 function controlService(action, opts) {
 	const name = opts.name ?? "pi-web-ui";
 
@@ -430,7 +588,74 @@ function controlService(action, opts) {
 		return;
 	}
 
-	fail(`不支持的系统服务平台: ${process.platform}（仅 macOS / Linux）`);
+	if (isWin) {
+		const exists = winTaskExists(name);
+
+		if (action === "status") {
+			if (!exists) {
+				console.log(`${name}: 未安装（运行 pi-web-ui server install 安装）`);
+				return;
+			}
+			// Get-ScheduledTask outputs English state enums — locale-independent,
+			// unlike `schtasks /Query` tables on localized Windows.
+			const ps = spawnSync(
+				"powershell.exe",
+				[
+					"-NoProfile",
+					"-NonInteractive",
+					"-Command",
+					"$t=Get-ScheduledTask -TaskName '" +
+						name +
+						"' -ErrorAction SilentlyContinue;" +
+						"if(!$t){'NOT_INSTALLED';exit}" +
+						"$i=$t|Get-ScheduledTaskInfo;" +
+						"'State: '+$t.State;" +
+						"'LastRunTime: '+$i.LastRunTime;" +
+						"'LastTaskResult: '+$i.LastTaskResult",
+				],
+				{ encoding: "utf8" },
+			);
+			if (ps.status !== 0 || (ps.stdout ?? "").includes("NOT_INSTALLED")) {
+				console.log(`${name}: 未安装（运行 pi-web-ui server install 安装）`);
+				return;
+			}
+			console.log(`${name}: 计划任务\n${(ps.stdout ?? "").trim()}`);
+			return;
+		}
+
+		if (action === "start") {
+			if (!exists) fail(`${name} 不存在，请先运行 pi-web-ui server install`);
+			run("schtasks", ["/Run", "/TN", name]);
+			console.log(`✅ 已启动 ${name}`);
+			return;
+		}
+
+		if (action === "restart") {
+			if (!exists) fail(`${name} 不存在，请先运行 pi-web-ui server install`);
+			run("schtasks", ["/End", "/TN", name], {
+				ignoreError: true,
+				silent: true,
+			});
+			run("schtasks", ["/Run", "/TN", name]);
+			console.log(`✅ 已重启 ${name}`);
+			return;
+		}
+
+		if (action === "stop") {
+			run("schtasks", ["/End", "/TN", name], {
+				ignoreError: true,
+				silent: true,
+			});
+			console.log(`⏹  已停止 ${name}（自启保留；uninstall 移除）`);
+			return;
+		}
+
+		fail(`未知操作: ${action}`);
+	}
+
+	fail(
+		`不支持的系统服务平台: ${process.platform}（仅 macOS / Linux / Windows）`,
+	);
 }
 
 async function serverCmd(argv) {
@@ -454,8 +679,10 @@ async function serverCmd(argv) {
 				installLaunchd(opts);
 			} else if (isLinux) {
 				installSystemd(opts);
+			} else if (isWin) {
+				installWindows(opts);
 			} else {
-				fail(`不支持的系统服务平台: ${process.platform}（仅 macOS / Linux）`);
+				fail(`不支持的系统服务平台: ${process.platform}`);
 			}
 			break;
 		}
@@ -464,8 +691,10 @@ async function serverCmd(argv) {
 				uninstallLaunchd(opts);
 			} else if (isLinux) {
 				uninstallSystemd(opts);
+			} else if (isWin) {
+				uninstallWindows(opts);
 			} else {
-				fail(`不支持的系统服务平台: ${process.platform}（仅 macOS / Linux）`);
+				fail(`不支持的系统服务平台: ${process.platform}`);
 			}
 			break;
 		}

package/deploy/pi-web-ui-task.xml

@@ -0,0 +1,69 @@
+<?xml version="1.0" encoding="UTF-16"?>
+<!--
+  pi-web-ui Task Scheduler task — Windows auto-start at logon.
+
+  The easy way (no admin needed, generates everything for you):
+    npm i -g pi-web-ui
+    pi-web-ui server install --port 8787 --cwd C:\path\to\project
+    pi-web-ui server status | restart | stop | uninstall
+
+  Manual install with this template (edit the paths below first):
+    schtasks /Create /TN "pi-web-ui" /XML pi-web-ui-task.xml /F
+    schtasks /Run /TN "pi-web-ui"
+
+  Notes:
+    - The task points at the .cmd wrapper the CLI generates at
+      %APPDATA%\pi-web-ui\pi-web-ui.cmd (it sets PORT/PI_WEB_CWD, cd's to the
+      workspace, launches node, and appends output to %USERPROFILE%\pi-web-ui.log).
+      Preview both generated files with: pi-web-ui server install --print
+    - Save this file as UTF-16 LE (schtasks requires it; the CLI does this
+      automatically when it writes the task XML).
+    - LogonTrigger = starts when you log in, same as a launchd user agent.
+      For boot-start without login, use Docker instead (see README).
+-->
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>pi-web-ui — web chat for the pi coding agent (auto-start at logon)</Description>
+  </RegistrationInfo>
+  <Triggers>
+    <LogonTrigger>
+      <Enabled>true</Enabled>
+    </LogonTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <AllowHardTerminate>true</AllowHardTerminate>
+    <StartWhenAvailable>false</StartWhenAvailable>
+    <RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>
+    <IdleSettings>
+      <StopOnIdleEnd>false</StopOnIdleEnd>
+      <RestartOnIdle>false</RestartOnIdle>
+    </IdleSettings>
+    <AllowStartOnDemand>true</AllowStartOnDemand>
+    <Enabled>true</Enabled>
+    <Hidden>false</Hidden>
+    <RunOnlyIfIdle>false</RunOnlyIfIdle>
+    <WakeToRun>false</WakeToRun>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <Priority>7</Priority>
+    <RestartOnFailure>
+      <Interval>PT1M</Interval>
+      <Count>3</Count>
+    </RestartOnFailure>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>C:\Windows\System32\cmd.exe</Command>
+      <Arguments>/c ""%APPDATA%\pi-web-ui\pi-web-ui.cmd""</Arguments>
+      <WorkingDirectory>%USERPROFILE%</WorkingDirectory>
+    </Exec>
+  </Actions>
+</Task>

package/dist/server/agent-service.js

@@ -12,7 +12,7 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, getAgentDir, SessionManager, } from "@earendil-works/pi-coding-agent";
-import { serializeMessage, serializeStreamingMessage } from "./serialize.js";
+import { serializeMessage, serializeStreamingMessage, } from "./serialize.js";
 import { loadCommands, saveCommandsFile, TerminalManager, } from "./terminals.js";
 const SNAPSHOT_INTERVAL_MS = 60;
 const WIDGET_REFRESH_MS = 2000;
@@ -286,7 +286,20 @@ export class ClientSession {
     snapshotTimer = null;
     sessionsTimer = null;
     version = 0;
-    seq = 0;
+    /**
+     * Stable per-message ids: assigned once per (role, timestamp) so snapshot ids
+     * don't change every 60ms — changing ids would remount the whole list in
+     * React (collapse open thinking blocks, reset scroll, jank on long chats).
+     */
+    msgIds = new Map();
+    nextMsgId = 1;
+    /** Serialized UiMessage cache — object-reference-stable across snapshots, so
+     *  the frontend's React.memo can skip unchanged messages entirely. */
+    uiMessageCache = new Map();
+    /** Reused when the message set didn't change, keeping state.messages
+     *  reference-stable so the frontend can memoize derived maps. */
+    lastMessagesSig = "";
+    lastMessagesArray = [];
     queueSteering = 0;
     queueFollowUp = 0;
     disposed = false;
@@ -434,6 +447,25 @@ export class ClientSession {
                 void this.pushSessions();
         }, 800);
     }
+    /** Serialize a persisted message with a STABLE id + cached object reference. */
+    serializeCached(m) {
+        const key = m.role === "toolResult"
+            ? `t:${m.toolCallId}`
+            : `${m.role}:${m.timestamp}`;
+        let n = this.msgIds.get(key);
+        if (n === undefined) {
+            n = this.nextMsgId++;
+            this.msgIds.set(key, n);
+        }
+        const cacheKey = `${key}#${n}`;
+        const cached = this.uiMessageCache.get(cacheKey);
+        if (cached)
+            return cached;
+        const msg = serializeMessage(m, n);
+        if (msg)
+            this.uiMessageCache.set(cacheKey, msg);
+        return msg;
+    }
     snapshot() {
         const state = this.session.agent.state;
         const model = state.model;
@@ -461,14 +493,22 @@ export class ClientSession {
         catch {
             // stats are best-effort
         }
+        const rawMessages = state.messages
+            .map((m) => this.serializeCached(m))
+            .filter((m) => m !== null);
+        // Reuse the previous array when nothing changed: the element objects are
+        // cached (reference-stable) anyway, and a stable array reference lets the
+        // frontend memoize derived maps instead of rebuilding them every 60ms.
+        const sig = rawMessages.map((m) => m.id).join("\u0001");
+        const messages = sig === this.lastMessagesSig ? this.lastMessagesArray : rawMessages;
+        this.lastMessagesSig = sig;
+        this.lastMessagesArray = rawMessages;
         return {
             clientId: this.clientId,
             cwd: this.cwd,
             sessionId: this.session.sessionId,
             sessionFile: this.session.sessionFile,
-            messages: state.messages
-                .map((m) => serializeMessage(m, ++this.seq))
-                .filter((m) => m !== null),
+            messages,
             // The in-progress assistant message lives in state.streamingMessage
             // (the SDK only pushes it into state.messages at message_end). Surfacing
             // it here is what makes thinking + text stream into the browser at

package/dist/server/terminals.js

@@ -101,8 +101,17 @@ export async function saveCommandsFile(workspaceRoot, commands) {
         return { path, error: `保存命令文件失败：${err.message}` };
     }
 }
-const SHELL = process.env.SHELL || "bash";
-const SHELL_ARGS = ["-i"];
+const isWindows = process.platform === "win32";
+/**
+ * Interactive shell for PTYs. Windows has no $SHELL: use Git Bash if the user
+ * has it, otherwise the console host from $COMSPEC (always set → cmd.exe).
+ * POSIX uses the user's login shell, falling back to bash.
+ */
+const SHELL = isWindows
+    ? process.env.SHELL || process.env.COMSPEC || "powershell.exe"
+    : process.env.SHELL || "bash";
+/** `-i` is POSIX-only; cmd.exe / powershell.exe start interactively on their own. */
+const SHELL_ARGS = isWindows ? [] : ["-i"];
 /**
  * Owns one or more PTYs for a client. All output is forwarded as
  * `terminal_output` messages through the provided emit (broadcast to every

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-web-ui",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Web chat interface for the pi coding agent, powered by the pi SDK (@earendil-works/pi-coding-agent) — one-command run, Docker/systemd/launchd deployable",
   "license": "MIT",
   "type": "module",