@chainingintention/pi-web-cn 1.202608.5 → 1.202608.7

package/docs/config.md

@@ -46,7 +46,8 @@ Process restarts depend on the key:
 
 - `host` / `port`: restart the gateway web/API service or process.
 - `maxUploadBytes`: restart both the web/API process and the session daemon on that machine.
-- `agent.command` / `agent.dir` / `spawnSessions` / `subsessions` / `askUser`: restart the session daemon on that machine.
+- `agent.command` / `agent.dir` / `spawnSessions` / `subsessions` / `askUser` / `extensionDialogsTimeoutMs`: restart the session daemon on that machine.
+- `workbenchIntegration`: restart both the web/API process and session daemon; both processes must use the same endpoints and limits.
 - `pathAccess`: applies on the next request; existing file views may need a browser refresh.
 - `uploads.defaultFolder`: applies to newly opened Files upload dialogs and new direct drag/drop batches after config/workspace refresh.
 - `plugins`: reload the browser tab after changing PI WEB plugin enablement.
@@ -73,6 +74,29 @@ Process restarts depend on the key:
   "spawnSessions": true,
   "subsessions": false,
   "askUser": true,
+  "extensionDialogsTimeoutMs": 300000,
+  "workbenchIntegration": {
+    "baseUrl": "http://ai-platform-backend:8787",
+    "mcpUrl": "http://mcp:8000/mcp",
+    "requestTimeoutMs": 10000,
+    "capabilityTimeoutMs": 30000,
+    "skillBundleMaxBytes": 10485760,
+    "skillFileMaxBytes": 2097152,
+    "skillFileCountMax": 200
+  },
+  "auditLog": {
+    "normalMode": {
+      "enabled": true,
+      "retentionDays": 90,
+      "maxRows": 500000
+    },
+    "managementMode": {
+      "enabled": true,
+      "baseUrl": "https://elasticsearch.internal:9200",
+      "indexPrefix": "pi-web-management-audit",
+      "retentionDays": 365
+    }
+  },
   "plugins": {
     "workspace-tasks": { "enabled": true },
     "updates": { "enabled": true },
@@ -125,6 +149,10 @@ Rows with JSON key `—` are runtime-only environment variables, not config-file
 | Agent can spawn sessions | `spawnSessions` | `PI_WEB_SPAWN_SESSIONS` | Global/session daemon | Not supported locally | Restart session daemon on that machine |
 | Tracked subsessions (beta) | `subsessions` | `PI_WEB_SUBSESSIONS` | Global/session daemon | Not supported locally; also requires `spawnSessions` | Restart session daemon on that machine |
 | Agent can post question forms | `askUser` | `PI_WEB_ASK_USER` | Global/session daemon | Not supported locally | Restart session daemon on that machine |
+| 扩展对话框自动取消超时 | `extensionDialogsTimeoutMs` | — | 全局/会话守护进程 | 不支持项目级配置 | 重启对应机器上的会话守护进程 |
+| Workbench/MCP integration | `workbenchIntegration.*` | `PI_WEB_WORKBENCH_URL`, `PI_WEB_MCP_URL`, `PI_WEB_WORKBENCH_TIMEOUT_MS`, `PI_WEB_MCP_TIMEOUT_MS`, `PI_WEB_SKILL_BUNDLE_MAX_BYTES`, `PI_WEB_SKILL_FILE_MAX_BYTES`, `PI_WEB_SKILL_FILE_COUNT_MAX` | Web/API + session daemon | Not supported locally | Restart web/API and session daemon; both must match |
+| Ordinary tool audit | `auditLog.normalMode.*` | — | Global/session daemon | Not supported locally | Restart session daemon |
+| Management tool audit | `auditLog.managementMode.*` | `PI_WEB_AUDIT_ES_URL`, `PI_WEB_AUDIT_ES_API_KEY`, `PI_WEB_AUDIT_ES_USERNAME`, `PI_WEB_AUDIT_ES_PASSWORD` | Global/session daemon | Not supported locally | Restart session daemon |
 | Plugin enablement/settings | `plugins.<id>.enabled`, `plugins.<id>.settings` | — | Global | Not core local config; plugins may read their own project files | Reload browser tab |
 | Keyboard shortcuts | `shortcuts.<actionId>` | — | Global | Not supported locally | Applies after settings save/config refresh |
 | Project config version | `version` | — | Project | Project-local only; must be `1` when present | Next project-config read |
@@ -144,6 +172,45 @@ Rows with JSON key `—` are runtime-only environment variables, not config-file
 
 ## Key details
 
+### Ordinary-mode tool audit
+
+PI WEB stores metadata-only ordinary-mode tool calls in `$PI_WEB_DATA_DIR/audit/normal-tool-calls.sqlite` while keeping the existing Pino/service logs. Management-embed calls are not written to this database. Each row contains the session and workspace, tool and call identifiers, start/end timestamps, duration, and `started`, `completed`, `failed`, or `interrupted` status. Arguments, results, prompts, model replies, and credentials are never stored.
+
+`auditLog.normalMode.enabled` defaults to `true`. `retentionDays` defaults to `90`, and `maxRows` defaults to `500000`. The session daemon prunes at startup and every 24 hours. Database failures are reported through the existing logger and do not stop tool execution.
+
+Use the CLI to inspect and maintain the database:
+
+```bash
+pi-web audit list --since 24h
+pi-web audit list --status failed --since 7d
+pi-web audit stats --since 30d
+pi-web audit export --since 30d --format csv --output audit.csv
+pi-web audit prune --before 2026-05-01
+pi-web audit vacuum
+```
+
+The database uses WAL mode so these read operations can run while sessiond is active. A graceful sessiond shutdown and the next startup mark unfinished calls as `interrupted`; changing audit configuration requires restarting sessiond.
+
+### Management-mode Elasticsearch audit
+
+Management-embed audit records can be sent to Elasticsearch while the existing Pino/service logs remain enabled. Set `auditLog.managementMode.enabled` to `true` and provide `baseUrl`, or set `PI_WEB_AUDIT_ES_URL`. Authentication is read only from the session daemon environment: `PI_WEB_AUDIT_ES_API_KEY` takes precedence, while basic authentication requires both `PI_WEB_AUDIT_ES_USERNAME` and `PI_WEB_AUDIT_ES_PASSWORD`. Credentials must not be included in `baseUrl`.
+
+Records are written to Shanghai-calendar ISO-week indices such as `pi-web-management-audit-2026-w32`. `indexPrefix` defaults to `pi-web-management-audit`; `retentionDays` defaults to `365`. Sessiond installs a strict index template, batches writes through the Elasticsearch Bulk API, and runs retention at startup and daily. The first successful maintenance in each Shanghai calendar month deletes documents whose `@timestamp` is older than the retention cutoff.
+
+Each document identifies `user.id`, `user.root_user_id`, the authorized project owning the actual workspace, the Pi session, and, when applicable, the Workbench Agent Session. Tool calls include tool/call identifiers and status. Capability and Skill events add fixed resource versions, authorization revision, run/trace identifiers, status, duration, and retry metadata. Prompts, tool arguments, tool results, model replies, access tokens, API keys, cookies, and capability tickets are excluded.
+
+Elasticsearch failures are reported through Pino and do not stop management sessions. Failed batches remain in a bounded in-memory retry queue and are flushed during graceful sessiond shutdown; a process crash can lose records that have not yet reached Elasticsearch. Use Elasticsearch or Kibana index permissions to limit user-level audit access.
+
+### Workbench and MCP integration
+
+`workbenchIntegration` enables the controlled management-embed adapter for the network model workbench. These resource, tool, and Skill restrictions apply only to management-embed sessions; normal-mode sessions keep PI WEB's existing behavior. `baseUrl` is the server-reachable workbench backend origin, while `mcpUrl` is the MCP Streamable HTTP endpoint. Both are required; the environment variables override the corresponding JSON URLs.
+
+The adapter exchanges the one-time management token for a private Agent Session, loads only the resulting fixed resource snapshot, and exposes `icnoc_search_capabilities` and `icnoc_call_capability` alongside the managed file tools and sandboxed `python` tool. Python runs without network access in an isolated Bubblewrap environment that binds only the managed workspace. Generic MCP, HTTP, web search, shell, and terminal tools remain denied in management mode. Skill bundles are downloaded only from the MCP origin, checked against the authorized fixed version and manifest, and stored under the managed project's `.pi/skills/` directory. Tokens and tickets remain server-side.
+
+The session daemon emits metadata-only tool execution audit entries for both normal and management sessions. These entries include the mode, session, workspace, tool name, call id, and execution status; tool arguments and results are deliberately excluded. Workbench capability calls additionally emit their business and MCP trace identifiers.
+
+Set the same effective config and environment on the web/API and session daemon services. Changing any integration endpoint or limit requires restarting both services.
+
 ### Managed data directory
 
 `PI_WEB_DATA_DIR` sets the root for PI WEB-managed runtime state and defaults to `~/.pi-web`. Unless a more specific path override is configured, PI WEB stores its project and machine registries, locally discovered plugins, default session-daemon socket, and session archives beneath this root.
@@ -278,6 +345,8 @@ A completion notice wakes an idle parent or queues behind in-flight work. Each n
 
 `list_subsessions`, `check_subsession`, and `read_subsession` never yield or change control flow. They are for deliberate inspection or recovery, not completion polling. While a child works, agent-facing `check_subsession` and `read_subsession` withhold partial output and direct the parent to continue independent work or yield at the join point. Output becomes available when the child stops. Included output and transcripts follow a labeled marker and come last, after PI WEB guidance.
 
+`spawn_session` 和 `spawn_subsession` 都接受可选的 `model` 参数，其值必须是精确的 `provider/model-id`，例如 `anthropic/claude-sonnet-4-5`。设置后，新会话会使用该模型，而不是继承发起会话的模型。匹配是严格的：未知值或格式错误的值会被拒绝并返回错误。用户可以在提示词中通过 `#provider/model-id` 引用指定模型（见[提示词补全](#prompt-completions)），代理会将该引用作为此参数传递。新会话还会继承发起会话当前的思考级别，并根据所选模型的能力自动限制该级别。
+
 In **Settings → Session daemon**, these keys are saved on the selected machine. Restart the session daemon on that machine after changing them.
 
 #### `askUser` and `ask_user`
@@ -296,6 +365,14 @@ Sending an ordinary chat message while a form is open voids the form: the card c
 
 Restart the session daemon after changing `askUser` or after upgrading PI WEB to a version that introduces this tool. For the systemd user service, run `systemctl --user restart pi-web-sessiond`.
 
+### 扩展对话框
+
+Pi 扩展可以通过 `ctx.ui.confirm()`、`ctx.ui.select()` 和 `ctx.ui.input()` 向用户提问，包括从 `session_start` 钩子以及运行中的 `tool_call` 钩子发起。PI WEB 会在会话记录中以内联方式显示这些对话框，并通过独立的会话守护进程通道返回回答，不经过提示词队列，因此等待回答的 `tool_call` 钩子不会阻塞运行。对话框支持始终启用，没有单独的启用开关。行为细节和扩展开发说明见 [PI WEB 中的 Pi 扩展对话框](https://pi-web.dev/plugins#pi-extension-dialogs)。
+
+`extensionDialogsTimeoutMs` 是无人处理对话框时的安全超时：会话守护进程等待回答的最长时间，超时后将以对应类型的取消值结束对话框（确认框为 `false`，选择框和输入框为 `undefined`）。默认值为 `300000`（5 分钟）；设为 `0` 时永久等待。扩展自身设置的 `timeout` 仍然生效，最终期限取两者中较早的时间。
+
+该配置项直接在全局配置文件中编辑。修改后需要重启会话守护进程；使用 systemd 用户服务时运行 `systemctl --user restart pi-web-sessiond`。
+
 ### Plugin config
 
 The `plugins` key is only for PI WEB browser plugin enablement/settings on the machine whose config you are editing. It does not install, remove, or update Pi packages; use **Settings → Pi packages** or Pi's package manager for package operations. In a federated setup, **Settings → PI WEB plugins** and **Settings → Pi packages** both target the currently selected machine, and each panel labels where changes will be saved or run.
@@ -328,6 +405,14 @@ Shortcut values are keyed by action id. Values are shortcut strings such as `mod
 
 Prefer Settings → Keyboard for editing shortcuts interactively.
 
+## 提示词补全
+
+聊天输入框会在键入以下三个触发字符时打开补全菜单：
+
+- 在草稿开头键入 `/` 可补全会话命令。
+- `@` 用于补全文件路径：`@` 显示已跟踪文件，`@ `（先键入 `@`，再键入空格）或 `!@` 显示所有文件。选中后会把 `@path` 引用插入草稿；路径包含空格时会自动加引号。
+- `#` 用于补全当前会话可用的模型；输入时不区分大小写地筛选，最多显示 12 项。选中后会把 `#provider/model-id` 引用插入草稿，提示代理应使用该模型执行请求，例如作为 `spawn_session` 的 `model` 参数。
+
 ## Optional completion tools
 
 File and path `@` completions work without extra tools. If `fzf` is available on the PI WEB server's `PATH`, PI WEB uses it to improve completion filtering/ranking; otherwise it falls back to built-in ranking.

package/docs/plugins.md

@@ -29,6 +29,20 @@ Use **Settings → PI WEB plugins** to enable or disable discovered PI WEB brows
 
 After installing, removing, or updating a Pi package, type `/reload` in each idle PI WEB session on the target machine to refresh ordinary Pi resources such as extensions, skills, prompt templates, themes, and context/system prompt files. Reload the browser page separately for newly discovered or changed PI WEB browser plugins. A provider-registering Pi extension follows a separate daemon-start policy; see [Pi extension provider baseline](https://pi-web.dev/config#pi-extension-provider-baseline).
 
+## PI WEB 中的 Pi 扩展对话框
+
+运行在 PI WEB 会话守护进程中的 Pi 扩展可以通过 `ctx.ui.confirm()`、`ctx.ui.select()` 和 `ctx.ui.input()` 向用户提问。PI WEB 会报告 `ctx.hasUI === true`，并且这三种对话框方法确实可用：调用后会在会话记录中以内联方式显示对话框卡片，返回的 Promise 将以用户的实际回答结束，确认框返回布尔值，选择框返回所选项，输入框返回输入文本。
+
+- **可在钩子中使用，不经过提示词队列。** 回答通过独立的会话守护进程通道传递，因此运行中的 `tool_call` 钩子可以安全等待对话框；代理循环会等待钩子，并在收到回答后继续运行。支持在 `tool_call` 钩子中使用对话框进行工具授权确认。
+- **启动阶段的对话框可以回答。** 无论创建新会话还是打开已有会话，`session_start` 钩子发起的对话框都能在会话仍在启动时回答；对话框结束后启动流程继续。
+- **浏览器刷新后可恢复，最先提交的回答生效。** 浏览器刷新后会根据会话状态重新显示打开的对话框。同一会话打开多个标签页时，最先提交的回答会结束对话框，其他标签页随后显示结束状态。
+- **结束状态卡片会保留到用户关闭。** 已回答或已关闭的对话框会在会话记录中保留结果卡片。回答只会传给扩展，因此该卡片是这次交互唯一的可见记录。卡片属于浏览器本地状态：只有见过对话框打开的浏览器会显示它，切换会话或刷新页面后会清除。
+- **超时。** 扩展自身的 `timeout` 仍然生效，守护进程还提供 `extensionDialogsTimeoutMs` 安全超时（默认 5 分钟，设为 `0` 时永久等待；见[扩展对话框](https://pi-web.dev/config#extension-dialogs)）。最终期限取两者中较早的时间。没有回答就关闭的对话框会返回对应类型的取消值：确认框为 `false`，选择框和输入框为 `undefined`。
+- **中止和运行时替换。** 中止当前运行时，本轮运行中打开的对话框会立即以取消值结束。替换会话运行时（例如 `/reload` 或销毁会话）也会结束所有仍打开的对话框；新运行时的钩子可以重新打开对话框。扩展传入的 `AbortSignal` 同样有效，中止信号会关闭对话框并返回取消值。
+- **其他 UI 能力仍为空实现。** 除这三种对话框外，PI WEB 尚未实现 `ExtensionUIContext` 的其他方法（组件、状态、编辑器和 `custom`）。即使 `hasUI` 为 `true`，也不能仅凭它判断这些能力可用。
+
+浏览器本地存在一个限制：新会话仍在创建时刷新页面，会丢失浏览器保存的待启动行，因此对话框卡片会消失。守护进程中的对话框仍会在期限到达时结束，会话创建完成后仍会出现在侧边栏中。
+
 ## Trust model
 
 Plugins run as JavaScript in the browser app. Treat them as trusted code:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chainingintention/pi-web-cn",
-  "version": "1.202608.5",
+  "version": "1.202608.7",
   "description": "Remote web UI and browser control plane for persistent Pi Coding Agent sessions.",
   "license": "MIT",
   "author": "Federico Jaramillo Martinez",
@@ -79,7 +79,8 @@
     "marked": "^18.0.6",
     "node-pty": "^1.1.0",
     "typebox": "1.3.6",
-    "ws": "^8.21.0"
+    "ws": "^8.21.0",
+    "yauzl": "^3.4.0"
   },
   "devDependencies": {
     "@changesets/cli": "^2.31.0",
@@ -89,6 +90,8 @@
     "@eslint/js": "^10.0.1",
     "@types/node": "^24.13.3",
     "@types/ws": "^8.18.1",
+    "@types/yauzl": "^2.10.3",
+    "@types/yazl": "^2.4.6",
     "eslint": "^10.6.0",
     "globals": "^17.7.0",
     "happy-dom": "^20.11.1",
@@ -97,7 +100,8 @@
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.63.0",
     "vite": "^8.1.4",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.10",
+    "yazl": "^3.3.1"
   },
   "publishConfig": {
     "access": "public"