pi-web-ui 0.59.0 → 0.60.0

package/deploy/com.xingshuyin.pi-web-ui.plist

@@ -1,48 +1,48 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<!--
-  pi-web-ui launchd agent — macOS auto-start at login.
-
-  Install:
-    npm i -g pi-web-ui
-    cp deploy/com.xingshuyin.pi-web-ui.plist ~/Library/LaunchAgents/
-    # edit ProgramArguments / WorkingDirectory / PI_WEB_CWD for your setup
-    launchctl load ~/Library/LaunchAgents/com.xingshuyin.pi-web-ui.plist
-    # (or: launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.xingshuyin.pi-web-ui.plist)
-
-  Find the pi-web-ui binary path with: which pi-web-ui
--->
-<plist version="1.0">
-<dict>
-  <key>Label</key>
-  <string>com.xingshuyin.pi-web-ui</string>
-
-  <key>ProgramArguments</key>
-  <array>
-    <string>/usr/local/bin/pi-web-ui</string>
-  </array>
-
-  <key>RunAtLoad</key>
-  <true/>
-
-  <!-- Restart if it crashes -->
-  <key>KeepAlive</key>
-  <true/>
-
-  <key>WorkingDirectory</key>
-  <string>/Users/YOUR_USER</string>
-
-  <key>EnvironmentVariables</key>
-  <dict>
-    <key>PI_WEB_PORT</key>
-    <string>8787</string>
-    <key>PI_WEB_CWD</key>
-    <string>/Users/YOUR_USER</string>
-  </dict>
-
-  <key>StandardOutPath</key>
-  <string>/tmp/pi-web-ui.log</string>
-  <key>StandardErrorPath</key>
-  <string>/tmp/pi-web-ui.err</string>
-</dict>
-</plist>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!--
+  pi-web-ui launchd agent — macOS auto-start at login.
+
+  Install:
+    npm i -g pi-web-ui
+    cp deploy/com.xingshuyin.pi-web-ui.plist ~/Library/LaunchAgents/
+    # edit ProgramArguments / WorkingDirectory / PI_WEB_CWD for your setup
+    launchctl load ~/Library/LaunchAgents/com.xingshuyin.pi-web-ui.plist
+    # (or: launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.xingshuyin.pi-web-ui.plist)
+
+  Find the pi-web-ui binary path with: which pi-web-ui
+-->
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.xingshuyin.pi-web-ui</string>
+
+  <key>ProgramArguments</key>
+  <array>
+    <string>/usr/local/bin/pi-web-ui</string>
+  </array>
+
+  <key>RunAtLoad</key>
+  <true/>
+
+  <!-- Restart if it crashes -->
+  <key>KeepAlive</key>
+  <true/>
+
+  <key>WorkingDirectory</key>
+  <string>/Users/YOUR_USER</string>
+
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PI_WEB_PORT</key>
+    <string>8787</string>
+    <key>PI_WEB_CWD</key>
+    <string>/Users/YOUR_USER</string>
+  </dict>
+
+  <key>StandardOutPath</key>
+  <string>/tmp/pi-web-ui.log</string>
+  <key>StandardErrorPath</key>
+  <string>/tmp/pi-web-ui.err</string>
+</dict>
+</plist>

package/deploy/nginx-subpath.conf

@@ -1,88 +1,88 @@
-# pi-web-ui behind nginx at a sub-path: http://<host>:83/pi/
-# Backend app: http://127.0.0.1:8787  (default PI_WEB_PORT env)
-#
-# IMPORTANT: pi-web-ui 0.23+ checks the WebSocket Origin against the request
-# Host (hostname AND port). Every proxied location MUST forward the original
-# Host with $http_host (keeps the port). Using $host (drops the port) or
-# leaving Host unset (defaults to 127.0.0.1:8787) makes the upgrade fail with
-# 403 — the page loads but chat/terminal keep reconnecting.
-#
-# Topology (two listeners on one port: frp + LAN coexist):
-#   frp (public)  -> <PUBLIC_IP>:<PUBLIC_PORT> -> 127.0.0.1:83 (PROXY protocol v2)
-#   LAN users     -> http://<LAN_IP>:83/pi/      (plain HTTP listener)
-#
-# frpc sends PROXY v2 to nginx (transport.proxyProtocolVersion = "v2"):
-#   * 127.0.0.1:83        proxy_protocol — only the local frp client connects
-#     here (it speaks PROXY v2; nginx then sees the real visitor IP).
-#   * <LAN_IP>:83    plain HTTP — LAN browsers, no PROXY header needed.
-#
-# Simpler alternative (no real client IPs): drop proxy_protocol entirely and
-# use a single `listen 83;` — then frpc must NOT set proxyProtocolVersion.
-#
-# The frontend uses absolute paths (/ws WebSocket, /assets/*, /favicon.svg,
-# /api/file…) so those get their own proxied locations next to /pi/.
-
-# Reuse for Upgrade/Connection headers (WebSocket).
-map $http_upgrade $connection_upgrade {
-    default upgrade;
-    ''      close;
-}
-
-server {
-    listen 127.0.0.1:83 proxy_protocol;
-    listen <LAN_IP>:83;
-
-    server_name _;
-
-    # Trust PROXY-protocol headers only from the local frp client; plain
-    # (LAN) connections keep their real $remote_addr untouched.
-    set_real_ip_from 127.0.0.1;
-    real_ip_header proxy_protocol;
-
-    # ---- main entry: strip /pi/ and forward to the app root ----
-    location /pi/ {
-        proxy_pass http://127.0.0.1:8787/;
-        proxy_http_version 1.1;
-        # $http_host keeps the port — origin check compares hostname AND port.
-        proxy_set_header Host $http_host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-        proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection $connection_upgrade;
-    }
-
-    # ---- WebSocket (the frontend connects to ws://<host>/ws) ----
-    location /ws {
-        proxy_pass http://127.0.0.1:8787;
-        proxy_http_version 1.1;
-        proxy_set_header Host $http_host;
-        proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection $connection_upgrade;
-        proxy_read_timeout 3600s;
-        proxy_send_timeout 3600s;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-    }
-
-    # ---- absolute asset paths baked into index.html ----
-    location /assets/ {
-        proxy_pass http://127.0.0.1:8787;
-    }
-    location = /favicon.svg {
-        proxy_pass http://127.0.0.1:8787;
-    }
-    location = /favicon-streaming.svg {
-        proxy_pass http://127.0.0.1:8787;
-    }
-
-    # ---- media preview / download / health API ----
-    location /api/ {
-        proxy_pass http://127.0.0.1:8787;
-    }
-
-    # bare root → app entry
-    location = / {
-        return 302 /pi/;
-    }
-}
+# pi-web-ui behind nginx at a sub-path: http://<host>:83/pi/
+# Backend app: http://127.0.0.1:8787  (default PI_WEB_PORT env)
+#
+# IMPORTANT: pi-web-ui 0.23+ checks the WebSocket Origin against the request
+# Host (hostname AND port). Every proxied location MUST forward the original
+# Host with $http_host (keeps the port). Using $host (drops the port) or
+# leaving Host unset (defaults to 127.0.0.1:8787) makes the upgrade fail with
+# 403 — the page loads but chat/terminal keep reconnecting.
+#
+# Topology (two listeners on one port: frp + LAN coexist):
+#   frp (public)  -> <PUBLIC_IP>:<PUBLIC_PORT> -> 127.0.0.1:83 (PROXY protocol v2)
+#   LAN users     -> http://<LAN_IP>:83/pi/      (plain HTTP listener)
+#
+# frpc sends PROXY v2 to nginx (transport.proxyProtocolVersion = "v2"):
+#   * 127.0.0.1:83        proxy_protocol — only the local frp client connects
+#     here (it speaks PROXY v2; nginx then sees the real visitor IP).
+#   * <LAN_IP>:83    plain HTTP — LAN browsers, no PROXY header needed.
+#
+# Simpler alternative (no real client IPs): drop proxy_protocol entirely and
+# use a single `listen 83;` — then frpc must NOT set proxyProtocolVersion.
+#
+# The frontend uses absolute paths (/ws WebSocket, /assets/*, /favicon.svg,
+# /api/file…) so those get their own proxied locations next to /pi/.
+
+# Reuse for Upgrade/Connection headers (WebSocket).
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    ''      close;
+}
+
+server {
+    listen 127.0.0.1:83 proxy_protocol;
+    listen <LAN_IP>:83;
+
+    server_name _;
+
+    # Trust PROXY-protocol headers only from the local frp client; plain
+    # (LAN) connections keep their real $remote_addr untouched.
+    set_real_ip_from 127.0.0.1;
+    real_ip_header proxy_protocol;
+
+    # ---- main entry: strip /pi/ and forward to the app root ----
+    location /pi/ {
+        proxy_pass http://127.0.0.1:8787/;
+        proxy_http_version 1.1;
+        # $http_host keeps the port — origin check compares hostname AND port.
+        proxy_set_header Host $http_host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+    }
+
+    # ---- WebSocket (the frontend connects to ws://<host>/ws) ----
+    location /ws {
+        proxy_pass http://127.0.0.1:8787;
+        proxy_http_version 1.1;
+        proxy_set_header Host $http_host;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+        proxy_read_timeout 3600s;
+        proxy_send_timeout 3600s;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    }
+
+    # ---- absolute asset paths baked into index.html ----
+    location /assets/ {
+        proxy_pass http://127.0.0.1:8787;
+    }
+    location = /favicon.svg {
+        proxy_pass http://127.0.0.1:8787;
+    }
+    location = /favicon-streaming.svg {
+        proxy_pass http://127.0.0.1:8787;
+    }
+
+    # ---- media preview / download / health API ----
+    location /api/ {
+        proxy_pass http://127.0.0.1:8787;
+    }
+
+    # bare root → app entry
+    location = / {
+        return 302 /pi/;
+    }
+}

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

@@ -1,54 +1,54 @@
-<?xml version="1.0" encoding="UTF-16"?>
-<!--
-  pi-web-ui Task Scheduler task — Windows auto-start at logon.
-
-  pi-web-ui server install 默认使用「登录 Run 键 + wscript 隐藏启动」（HKCU，无需管理员、
-  无黑窗），并自动迁移旧版计划任务安装。本 XML 仅保留给需要手动注册计划任务的场景
-  （例如管理员环境），不是默认路径。
--->
-<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\WindowsPowerShell\v1.0\powershell.exe</Command>
-      <Arguments>-NoProfile -NonInteractive -ExecutionPolicy Bypass -WindowStyle Hidden -File "%APPDATA%\pi-web-ui\pi-web-ui.ps1"</Arguments>
-      <WorkingDirectory>%USERPROFILE%</WorkingDirectory>
-    </Exec>
-  </Actions>
-</Task>
+<?xml version="1.0" encoding="UTF-16"?>
+<!--
+  pi-web-ui Task Scheduler task — Windows auto-start at logon.
+
+  pi-web-ui server install 默认使用「登录 Run 键 + wscript 隐藏启动」（HKCU，无需管理员、
+  无黑窗），并自动迁移旧版计划任务安装。本 XML 仅保留给需要手动注册计划任务的场景
+  （例如管理员环境），不是默认路径。
+-->
+<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\WindowsPowerShell\v1.0\powershell.exe</Command>
+      <Arguments>-NoProfile -NonInteractive -ExecutionPolicy Bypass -WindowStyle Hidden -File "%APPDATA%\pi-web-ui\pi-web-ui.ps1"</Arguments>
+      <WorkingDirectory>%USERPROFILE%</WorkingDirectory>
+    </Exec>
+  </Actions>
+</Task>

package/deploy/pi-web-ui.service

@@ -1,31 +1,31 @@
-# pi-web-ui systemd unit — Linux auto-start on boot.
-#
-# Install (adjust User/WorkingDirectory/Environment to taste):
-#   sudo npm i -g pi-web-ui
-#   sudo cp deploy/pi-web-ui.service /etc/systemd/system/
-#   sudo systemctl daemon-reload
-#   sudo systemctl enable --now pi-web-ui
-#   sudo systemctl status pi-web-ui
-#
-# Logs: journalctl -u pi-web-ui -f
-
-[Unit]
-Description=pi-web-ui — web chat for the pi coding agent
-After=network.target
-
-[Service]
-Type=simple
-# Run as an unprivileged user (change to your user, e.g. yourname)
-User=YOUR_USER
-# The workspace the agent operates in (read/edit/bash/write)
-WorkingDirectory=/home/YOUR_USER
-Environment=PI_WEB_PORT=8787
-# Point at your pi config dir if it's not the default ~/.pi/agent
-#Environment=PI_CODING_AGENT_DIR=/home/YOUR_USER/.pi/agent
-ExecStart=/usr/bin/pi-web-ui
-Restart=on-failure
-RestartSec=5
-# npm global bin may live elsewhere (nvm, etc.) — find with: which pi-web-ui
-
-[Install]
-WantedBy=multi-user.target
+# pi-web-ui systemd unit — Linux auto-start on boot.
+#
+# Install (adjust User/WorkingDirectory/Environment to taste):
+#   sudo npm i -g pi-web-ui
+#   sudo cp deploy/pi-web-ui.service /etc/systemd/system/
+#   sudo systemctl daemon-reload
+#   sudo systemctl enable --now pi-web-ui
+#   sudo systemctl status pi-web-ui
+#
+# Logs: journalctl -u pi-web-ui -f
+
+[Unit]
+Description=pi-web-ui — web chat for the pi coding agent
+After=network.target
+
+[Service]
+Type=simple
+# Run as an unprivileged user (change to your user, e.g. yourname)
+User=YOUR_USER
+# The workspace the agent operates in (read/edit/bash/write)
+WorkingDirectory=/home/YOUR_USER
+Environment=PI_WEB_PORT=8787
+# Point at your pi config dir if it's not the default ~/.pi/agent
+#Environment=PI_CODING_AGENT_DIR=/home/YOUR_USER/.pi/agent
+ExecStart=/usr/bin/pi-web-ui
+Restart=on-failure
+RestartSec=5
+# npm global bin may live elsewhere (nvm, etc.) — find with: which pi-web-ui
+
+[Install]
+WantedBy=multi-user.target

package/dist/server/agent-service.js

@@ -27,7 +27,7 @@ import { ModelAdminService } from "./model-admin.js";
 import { FilesService, workspacePath } from "./files-service.js";
 import { isExtensionDisabled, ClientStateStore, } from "./client-state.js";
 import { saveUpload } from "./uploads.js";
-import { makePersistentTerminalTools, makeTerminalBashTool, stripAnsi, TERMINAL_TOOLS_GUIDANCE, TERMINAL_TOOL_NAMES, } from "./terminals.js";
+import { applyHeadTail, makePersistentTerminalTools, makeTerminalBashTool, stripAnsi, TERMINAL_TOOLS_GUIDANCE, TERMINAL_TOOL_NAMES, } from "./terminals.js";
 import { WebUIContext } from "./webui-context.js";
 import { buildAttachmentMessages, parseModelSpec, } from "./attachments.js";
 import { serializeMessage, serializeStreamingMessage, } from "./serialize.js";
@@ -82,14 +82,14 @@ export class QuiesceRejectedError extends Error {
  *  programs wait for input that never comes. Legacy Chinese files are often
  *  GBK/GB2312 — read them with the right encoding, never paste mojibake into
  *  reasoning/answers. */
-const WINDOWS_PERSONA = `You are a coding agent running on Windows. The bash tool runs Git Bash (bash.exe), not PowerShell. Follow these rules to avoid hanging the session:
-
-
-
-- ALWAYS pass a timeout parameter to the bash tool (in seconds). There is NO default timeout — a command that never finishes (servers, watchers, infinite loops, slow downloads/installs) will hang the entire conversation indefinitely. Pick a generous timeout for long-running work, but never omit it.
-- NEVER run interactive or foreground long-running commands through the bash tool (vi, less, top, python -, node -, npm run dev, sleep 10000). For servers/daemons use background execution with output redirected to a log file, then poll the log; stop them when done.
-- In the interactive terminal (TTY) — which is Git Bash too, not PowerShell — NEVER use heredocs (<<'EOF' ... EOF) or here-strings, and NEVER start interactive programs (vi, less, python -, node -, npm init): they wait for keyboard input that never arrives and hang the terminal forever. Prefer writing a temp script file (e.g. .pi-tmp.sh) and running it non-interactively. ALWAYS pass a timeout to long-running commands (e.g. \`timeout 120 npm run dev\`).
-
+const WINDOWS_PERSONA = `You are a coding agent running on Windows. The bash tool runs Git Bash (bash.exe), not PowerShell. Follow these rules to avoid hanging the session:
+
+
+
+- ALWAYS pass a timeout parameter to the bash tool (in seconds). There is NO default timeout — a command that never finishes (servers, watchers, infinite loops, slow downloads/installs) will hang the entire conversation indefinitely. Pick a generous timeout for long-running work, but never omit it.
+- NEVER run interactive or foreground long-running commands through the bash tool (vi, less, top, python -, node -, npm run dev, sleep 10000). For servers/daemons use background execution with output redirected to a log file, then poll the log; stop them when done.
+- In the interactive terminal (TTY) — which is Git Bash too, not PowerShell — NEVER use heredocs (<<'EOF' ... EOF) or here-strings, and NEVER start interactive programs (vi, less, python -, node -, npm init): they wait for keyboard input that never arrives and hang the terminal forever. Prefer writing a temp script file (e.g. .pi-tmp.sh) and running it non-interactively. ALWAYS pass a timeout to long-running commands (e.g. \`timeout 120 npm run dev\`).
+
 Many legacy Chinese text files (.html/.txt/.md/.log, exported documents) are GBK/GB2312 encoded: the read tool decodes UTF-8 only and will show mojibake (乱码) for them. If a file's content looks garbled, read it through the terminal instead: in Git Bash use \`cat file | iconv -f GBK -t UTF-8\` (or \`iconv -f GBK -t UTF-8 file\`); in cmd use \`chcp 65001 && type file\`; in PowerShell use \`Get-Content -Encoding Default file\`. Never paste mojibake into your reasoning or answer — describe the decoded content instead.`;
 /** bash 工具输出限制/过滤管道引导：模型习惯套 `| tail/-n`、`| head`、`| grep`、`| less`
  *  等限输出。这些管道在持久终端里会①缓冲（可见终端全程哑火、看不到实时进度）②把退出码
@@ -97,13 +97,14 @@ Many legacy Chinese text files (.html/.txt/.md/.log, exported documents) are GBK
  *  让模型改用 bash 的 `tail` 参数限输出；长驻/交互任务改走持久终端工具。 */
 const PIPELESS_BASH_GUIDANCE = `Bash tool output-limiting/filtering: do NOT chain shell pipes to trim or filter output. Avoid \`| tail\`, \`| head\`, \`| grep\`, \`| less\`, \`| more\`, \`| cat\`, \`| sort\`, \`| awk\`, \`| sed\`. They buffer output (so the visible terminal shows nothing live), turn the real exit code into the last pipe command's (tail always 0, grep 1 when no match — hiding the actual failure), and can hang a long-running or failing command until timeout. Instead:\n- To limit returned output use the bash \`tail\` parameter (e.g. \`bash(command=..., tail=20)\`) — the underlying command still streams live to the visible terminal.\n- For a long-running server / watcher / interactive program, use the persistent terminal tools (terminal_create then terminal_read / terminal_input / terminal_key / terminal_wait) instead of piping through bash.\nThe bash tool auto-detects a trailing \`| tail\`/\`| grep\` etc. and runs the underlying command directly so it never hides a failure — but you should still prefer the \`tail\` parameter.`;
 /**
- * Killable bash tool: wraps the SDK bash tool with operations that register
- * their own AbortController into a client-level set. abortBash() aborts only
- * those controllers → the command's process tree is killed while the agent
- * run and the conversation continue (the tool returns an aborted error and
- * the model moves on). Injected as a customTool overriding the builtin bash.
+ * Killable bash tool: wraps the SDK bash tool (native process spawn, NO terminal).
+ * Used when the「默认 bash 覆盖」setting is OFF. Registers its own AbortController
+ * into a client-level set (kills) so abortBash() kills only these commands while the
+ * agent run and the conversation continue. Exposes persist (ignored — native has no
+ * terminal) plus head/tail (post-processed on the returned output) so the parameter
+ * schema stays consistent with the terminal-backed tool.
  */
-function makeKillableBashTool(cwd, kills) {
+export function makeKillableBashTool(cwd, kills) {
     const base = createLocalBashOperations();
     const tool = createBashTool(cwd, {
         operations: {
@@ -127,20 +128,50 @@ function makeKillableBashTool(cwd, kills) {
     return {
         name: tool.name,
         label: tool.label,
-        description: tool.description,
-        parameters: tool.parameters,
+        description: "Run a shell command natively (process spawn, no terminal) and return its full output plus exit code — the SDK's plain bash tool. persist is ignored here (no terminal); use head/tail to trim the returned output.",
+        parameters: Type.Object({
+            command: Type.String({ description: "The shell command to run" }),
+            timeout: Type.Optional(Type.Number({ description: "Optional timeout in seconds" })),
+            persist: Type.Optional(Type.Boolean({
+                description: "Ignored in native mode (no terminal). Only meaningful when the terminal-backed bash is active.",
+            })),
+            head: Type.Optional(Type.Integer({
+                minimum: 1,
+                maximum: 5000,
+                description: "Only return the FIRST N lines of output (like `| head -N`).",
+            })),
+            tail: Type.Optional(Type.Integer({
+                minimum: 1,
+                maximum: 5000,
+                description: "Only return the LAST N lines of output (like `| tail -N`).",
+            })),
+        }),
         prepareArguments: tool.prepareArguments,
         executionMode: tool.executionMode,
-        execute: (toolCallId, params, signal, onUpdate) => tool.execute(toolCallId, params, signal, onUpdate),
+        execute: async (toolCallId, params, signal, onUpdate) => {
+            const result = (await tool.execute(toolCallId, params, signal, onUpdate));
+            // head/tail 后处理（native 无终端，直接截返回行即可）。
+            const p = params;
+            if ((p?.head || p?.tail) && result?.content?.[0]?.text != null) {
+                result.content[0].text = applyHeadTail(result.content[0].text, p.head, p.tail);
+            }
+            return result;
+        },
     };
 }
 /**
- * 动态分流 bash：调用时按设置决定走哪套实现——「终端接管 bash」开关因此
- * 即时生效（customTools 在 runtime 创建时固定，不能在创建时二选一）。
+ * 动态分流 bash：按「默认 bash 覆盖」设置（terminalBash）在调用时决定走哪套——
+ * 关 = 原生 SDK bash（纯进程、不开终端）；开 = 终端接管 bash（persist 决定一次性/
+ * 持久）。开关因此即时生效（customTools 固定于 runtime 创建，不能在创建时二选一）。
  */
-function makeAdaptiveBashTool(killable, terminalBacked, useTerminal) {
+export function makeAdaptiveBashTool(killable, terminalBacked, useTerminal) {
     return {
         ...killable,
+        description: "Run a shell command and return its full output plus exit code. Behavior depends on the「default bash override」setting (terminalBash):\n" +
+            "Setting OFF → runs natively (process spawn, no terminal) — the SDK's plain bash tool. persist has no effect.\n" +
+            "Setting ON → runs in a visible terminal. persist=true keeps that terminal alive ('ai-bash': shell state such as cd/venv/ssh retained across calls, silent commands move to the background and notify when done); persist=false (default in terminal mode) creates a one-shot terminal that exits when the command finishes while its output stays for review.\n" +
+            "Run the bare command — do NOT pipe through head/tail/more/less (use the head/tail parameters to trim the returned output instead; piping also hides live progress in the visible terminal). For interactive commands (REPLs, prompts, installers asking y/n) set persist=true (terminal mode) and drive them with terminal_input / terminal_key.",
+        promptSnippet: "run shell commands",
         execute: (id, params, signal, onUpdate, ctx) => (useTerminal() ? terminalBacked : killable).execute(id, params, signal, onUpdate, ctx),
     };
 }
@@ -772,21 +803,20 @@ export class ClientSession {
             const created = await createAgentSessionFromServices({
                 services,
                 sessionManager,
-                // 可手动停止的 bash 工具：覆盖 SDK 内置 bash（customTools 按 name
-                // 覆盖），执行时把自己的 AbortController 注册进客户端集合——
-                // abortBash() 只杀这些命令，agent run 与对话继续。
+                // 覆盖 SDK 内置 bash（customTools 按 name 覆盖）。双实现分流：
+                // 「默认 bash 覆盖」开关（terminalBash）关 → 原生 SDK bash（纯进程、不开终端）；
+                // 开 → 终端接管 bash（persist 决定一次性/持久，可静默自动转后台）。
                 customTools: [
-                    // bash 双实现动态分流：「终端接管」开启时命令跑进持久可见终端
-                    // （保留 shell 状态、静默自动转后台），关闭时是原生 killable bash。
                     makeAdaptiveBashTool(makeKillableBashTool(effectiveCwd, this.bashKills), makeTerminalBashTool(terminals, {
                         cwd: effectiveCwd,
-                        idleMs: () => this.settingsSvc.current.terminalBash
-                            ? Math.max(0, Math.floor(this.settingsSvc.current.terminalBashIdleMs) ||
-                                0)
-                            : 0,
+                        // 设置开 = 用终端；此分支里 persist 未显式给时默认一次性（false）。
+                        defaultPersist: () => false,
+                        idleMs: () => Math.max(0, Math.floor(this.settingsSvc.current.terminalBashIdleMs) || 0),
                         kills: this.bashKills,
                         notifyBackgroundDone: (info) => this.notifyTerminalBashDone(terminals, info),
-                    }), () => this.settingsSvc.current.terminalBash),
+                    }), 
+                    // 设置关 → 原生 bash；开 → 终端 bash。
+                    () => this.settingsSvc.current.terminalBash),
                     ...makePersistentTerminalTools(terminals, effectiveCwd),
                     // 插件注册的 AI 工具（创建时刻的实时快照；后续注册经
                     // refreshPluginTools 动态补入已有会话）。
@@ -2056,8 +2086,8 @@ export class ClientSession {
     }
     /** Kill only the running bash command(s) — the agent run itself continues
      *  (the bash tool returns an aborted error and the model moves on). Uses
-     *  the per-client AbortController set registered by
-     *  makeKillableBashTool. */
+     *  the per-client AbortController set registered by the bash tool paths
+     *  ({@link makeKillableBashTool} / {@link makeTerminalBashTool}). */
     async abortBash() {
         if (this.bashKills.size === 0) {
             this.emit({

package/dist/server/attachments.js

@@ -448,9 +448,9 @@ export async function buildAttachmentMessages(ctx, attachments) {
                         content: [
                             {
                                 type: "text",
-                                text: `
-<vision-bridge>
-${transcript}
+                                text: `
+<vision-bridge>
+${transcript}
 </vision-bridge>`,
                             },
                             ...(pathImg