pi-ui-extend 1.0.39 → 1.0.41

package/external/pi-tools-suite/README.md

@@ -100,7 +100,13 @@ DCP settings are stored only under `dcp` in the user shared config file `~/.conf
       "nudgeFrequency": 1,
       "iterationNudgeThreshold": 6,
       "nudgeForce": "strong",
-      "protectedTools": ["compress", "write", "edit", "subagents"]
+      "protectedTools": ["compress", "write", "edit", "subagents"],
+      "autoCompress": {
+        "enabled": false,
+        "patience": 2,
+        "summarizerModel": [],
+        "timeoutMs": 20000
+      }
     },
     "strategies": {
       "emergencyCurrentTurnPruning": {
@@ -170,7 +176,11 @@ DCP settings are stored only under `dcp` in the user shared config file `~/.conf
 
 `minContextPercent` / `maxContextPercent` accept legacy fractions (`0.25`), percent strings (`"25%"`), or absolute token counts when Pi knows the current model context window. `minContextLimit` / `maxContextLimit` and `modelMinContextLimits` / `modelMaxContextLimits` are explicit absolute-or-percent aliases. `modelOverrides` and the `modelMin*` / `modelMax*` maps support exact model keys plus `*` / `?` wildcard patterns; matching is applied from generic to specific so exact bare-model matches override bare wildcards, and exact `provider/model` matches override provider wildcards. Array fields are union-merged, so model-specific `protectedTools` extend the defaults instead of replacing them. If `compress.protectUserMessages` is enabled, range compression appends selected user messages verbatim instead of rejecting the range; individual message compression still skips protected raw user messages. Protected tool outputs are copied into summaries for tools protected by name or `protectedFilePatterns`; protected `subagents` result reads also try to include the saved `result.md` artifact when available.
 
-`strategies.emergencyCurrentTurnPruning` is the default-enabled lossy safety floor for a single unfinished turn that has no normal compression candidate. DCP first emits emergency reminders and offers only safe old same-turn tool-result candidates. After `patience` ignored reminders, or at the model-independent `hardContextPercent`, it replaces eligible oldest result bodies until the estimated provider context reaches `targetContextPercent` or a margin below the model emergency threshold. User messages, configured/protected data, the newest `keepRecentToolPairs`, and results not present in an accepted provider request are never selected. The raw session transcript is unchanged. Setting `enabled` to `false` disables same-turn candidates and lossy pruning, but keeps the non-destructive emergency reminder.
+`compress.autoCompress.enabled` is `false` by default. When explicitly enabled, its `patience` counts completed correlated main-provider opportunities, not repeated context transforms; `summarizerModel: []` uses the bounded extractive fallback without a model call, while configured models share the single `timeoutMs` summarizer deadline. If that deadline expires, DCP still has a bounded finalization grace to commit the extractive fallback. Auto commit is accepted only when the full projected replacement has positive gain and meets the current budget-recovery target.
+
+`strategies.emergencyCurrentTurnPruning` is the default-enabled lossy safety floor for a single unfinished turn that has no normal compression candidate. DCP first emits emergency reminders and offers only safe old same-turn tool-result candidates. After `patience` completed ignored opportunities, or at the model-independent `hardContextPercent`, it replaces eligible oldest result bodies until the estimated provider context reaches `targetContextPercent` or a margin below the model emergency threshold. User messages, configured/protected data, the newest `keepRecentToolPairs`, and results without **completed** provider evidence are never selected. HTTP 2xx alone is not evidence; DCP promotes eligibility only after an unambiguously correlated successful finalized assistant response, and ambiguous retries/interleaving fail closed. The raw session transcript is unchanged. Setting `enabled` to `false` disables same-turn candidates and lossy pruning, but keeps the non-destructive emergency reminder.
+
+DCP sidecars are session-private versioned generation envelopes under `<sessionDir>/dcp-state/`. Saves use private atomic files, retain a last-valid `.prev` generation, validate payload/block-graph integrity on load, quarantine corrupt primaries, and use a cross-process exclusive lock rather than silent last-writer-wins. Live paused sessions are not deleted merely for age. Protected subagent artifacts are optional bounded recovery input: reads are async, rooted at the session cwd, reject symlink escapes and oversized files, and never silently truncate a required protected artifact.
 
 Set `dcp.debug: true` to write a JSONL debug log of DCP context/prune/compress events to `~/.pi/agent/dcp-debug.jsonl` (override the path with `PI_DCP_DEBUG_LOG`, or enable without config via `PI_DCP_DEBUG=1`); off by default. The log is size-limited and rotated: once it reaches `dcp.debugLog.maxBytes` (default `5242880` = 5 MB) it is renamed to `.1`, older backups shift down (`.1`→`.2`, …) and the oldest beyond `dcp.debugLog.maxBackups` (default `3`, minimum `1`) is dropped; override either with `PI_DCP_DEBUG_MAX_BYTES` / `PI_DCP_DEBUG_MAX_BACKUPS`.
 
@@ -188,9 +198,28 @@ Install the language servers used by the bundled example config. The commands be
 # TypeScript / JavaScript
 npm install -g typescript typescript-language-server
 
+# Svelte
+npm install -g svelte-language-server
+
+# Vue
+npm install -g @vue/language-server
+
 # Python
 python3 -m pip install --user python-lsp-server
 
+# Go
+go install golang.org/x/tools/gopls@latest
+
+# C / C++ (clangd)
+brew install llvm
+# or use your distro's clangd package: apt install clangd, dnf install clang-tools-extra, ...
+
+# Lua
+brew install lua-language-server
+
+# Bash
+npm install -g bash-language-server
+
 # C# / Unity
 dotnet tool install -g Microsoft.CodeAnalysis.LanguageServer
 
@@ -252,23 +281,276 @@ Minimal shared config shape:
 
 Project-local overrides can be added in `.pi/pi-tools-suite.jsonc`; pi-tools-suite asks for trust before using project-local LSP binaries.
 
+### Popular language-server examples
+
+Copy the entries you need into `lsp.servers` of the shared config. Values mirror the commented templates shipped in the generated config file; where they disagree, the generated file is authoritative. Both diagnostics modes are on by default: servers that support pull diagnostics (`textDocument/diagnostic`) are queried directly, and push diagnostics (`publishDiagnostics`) are awaited for every server — `pullDiagnostics: false` / `waitForPublishDiagnostics: false` disable either side explicitly. Servers start lazily: one spawns only after a mutating tool (Edit/Write/ast-grep/apply_patch) touches a file matching `include`, and diagnostics land in that tool's result.
+
+```jsonc
+{
+  "lsp": {
+    "servers": [
+      // Svelte (verified with svelte-language-server): compiler + embedded TS/JS diagnostics
+      {
+        "id": "svelte",
+        "include": ["**/*.svelte"],
+        "exclude": ["**/node_modules/**"],
+        "rootMarkers": ["svelte.config.js", "package.json"],
+        "bin": "svelteserver",
+        "args": ["--stdio"],
+        "startupTimeoutMs": 30000,
+        "diagnosticsWaitMs": 8000,
+        "languageIdByExtension": { ".svelte": "svelte" }
+      },
+      // Vue (Volar)
+      {
+        "id": "vue",
+        "include": ["**/*.vue"],
+        "exclude": ["**/node_modules/**"],
+        "rootMarkers": ["package.json"],
+        "bin": "vue-language-server",
+        "args": ["--stdio"],
+        "startupTimeoutMs": 30000,
+        "diagnosticsWaitMs": 8000,
+        "languageIdByExtension": { ".vue": "vue" }
+      },
+      // Python (python-lsp-server)
+      {
+        "id": "python",
+        "include": ["**/*.py", "**/*.pyi"],
+        "exclude": ["**/.git/**", "**/node_modules/**", "**/__pycache__/**", "**/.venv/**", "**/venv/**", "**/.tox/**", "**/.mypy_cache/**", "**/.ruff_cache/**"],
+        "rootMarkers": ["pyproject.toml", "setup.py", "setup.cfg", "requirements.txt", "Pipfile", "poetry.lock", ".git"],
+        "bin": "pylsp",
+        "args": [],
+        "languageIdByExtension": { ".py": "python", ".pyi": "python" }
+      },
+      // Go (gopls, push diagnostics)
+      {
+        "id": "go",
+        "include": ["**/*.go"],
+        "exclude": ["**/.git/**", "**/vendor/**"],
+        "rootMarkers": ["go.mod", ".git"],
+        "bin": "gopls",
+        "args": [],
+        "startupTimeoutMs": 20000,
+        "diagnosticsWaitMs": 8000,
+        "languageIdByExtension": { ".go": "go" }
+      },
+      // Rust (rust-analyzer, push diagnostics)
+      {
+        "id": "rust",
+        "include": ["**/*.rs"],
+        "exclude": ["**/.git/**", "**/node_modules/**", "**/target/**"],
+        "rootMarkers": ["Cargo.toml", "rust-project.json", ".git"],
+        "bin": "rust-analyzer",
+        "args": [],
+        "startupTimeoutMs": 20000,
+        "diagnosticsWaitMs": 20000,
+        "pullDiagnostics": false,
+        "waitForPublishDiagnostics": true,
+        "languageIdByExtension": { ".rs": "rust" }
+      },
+      // C / C++ (clangd, push diagnostics)
+      {
+        "id": "clangd",
+        "include": ["**/*.c", "**/*.cc", "**/*.cpp", "**/*.cxx", "**/*.h", "**/*.hh", "**/*.hpp"],
+        "exclude": ["**/.git/**", "**/node_modules/**"],
+        "rootMarkers": ["compile_commands.json", "CMakeLists.txt", "Makefile", ".clang-format", ".git"],
+        "bin": "clangd",
+        "args": [],
+        "startupTimeoutMs": 20000,
+        "diagnosticsWaitMs": 8000,
+        "languageIdByExtension": {
+          ".c": "c", ".cc": "cpp", ".cpp": "cpp", ".cxx": "cpp",
+          ".h": "c", ".hh": "cpp", ".hpp": "cpp"
+        }
+      },
+      // C# / Unity (Roslyn)
+      {
+        "id": "csharp",
+        "include": ["**/*.cs", "**/*.csx"],
+        "exclude": ["**/.git/**", "**/node_modules/**", "**/bin/**", "**/obj/**", "**/.vs/**", "**/Library/**", "**/Temp/**", "**/Logs/**"],
+        "rootMarkers": ["*.sln", "*.csproj", "global.json", "Directory.Build.props", "Directory.Packages.props", "Packages/manifest.json", "ProjectSettings/ProjectVersion.txt", ".git"],
+        "bin": "~/.dotnet/tools/roslyn-language-server",
+        "args": ["--stdio", "--autoLoadProjects", "--logLevel", "Error"],
+        "startupTimeoutMs": 30000,
+        "diagnosticsWaitMs": 15000,
+        "languageIdByExtension": { ".cs": "csharp", ".csx": "csharp" }
+      },
+      // Ruby
+      {
+        "id": "ruby",
+        "include": ["**/*.rb", "**/*.rake", "**/Gemfile", "**/Rakefile", "**/*.gemspec"],
+        "exclude": ["**/.git/**", "**/node_modules/**", "**/vendor/bundle/**", "**/.bundle/**", "**/tmp/**", "**/log/**"],
+        "rootMarkers": ["Gemfile.lock", "*.gemspec", "Rakefile", ".ruby-version", ".git"],
+        "bin": "ruby-lsp",
+        "args": [],
+        "startupTimeoutMs": 60000,
+        "diagnosticsWaitMs": 10000,
+        "languageIdByExtension": { ".rb": "ruby", ".rake": "ruby", ".gemspec": "ruby" }
+      },
+      // Lua (lua-language-server)
+      {
+        "id": "lua",
+        "include": ["**/*.lua"],
+        "exclude": ["**/.git/**", "**/node_modules/**"],
+        "rootMarkers": [".luarc.json", ".git"],
+        "bin": "lua-language-server",
+        "args": [],
+        "startupTimeoutMs": 30000,
+        "diagnosticsWaitMs": 6000,
+        "languageIdByExtension": { ".lua": "lua" }
+      },
+      // Bash
+      {
+        "id": "bash",
+        "include": ["**/*.sh", "**/*.bash"],
+        "exclude": ["**/.git/**", "**/node_modules/**"],
+        "rootMarkers": [".git"],
+        "bin": "bash-language-server",
+        "args": ["start"],
+        "startupTimeoutMs": 15000,
+        "diagnosticsWaitMs": 5000,
+        "languageIdByExtension": { ".sh": "shellscript", ".bash": "shellscript" }
+      },
+      // Markdown (link validation settings ship in the generated config template)
+      {
+        "id": "markdown",
+        "include": ["**/*.md", "**/*.markdown", "**/*.mdown", "**/*.mkd", "**/*.mmd"],
+        "exclude": ["**/.git/**", "**/node_modules/**"],
+        "rootMarkers": [".git", "package.json", "README.md"],
+        "bin": "vscode-markdown-language-server",
+        "args": ["--stdio"],
+        "startupTimeoutMs": 15000,
+        "diagnosticsWaitMs": 5000,
+        "languageIdByExtension": { ".md": "markdown", ".markdown": "markdown", ".mdown": "markdown", ".mkd": "markdown", ".mmd": "markdown" }
+      }
+    ]
+  }
+}
+```
+
+Notes:
+
+- Svelte resolves `svelte` and `typescript` from the workspace `node_modules`, so project-local versions win; `.svelte.js`/`.svelte.ts` runes modules are not covered because their extensions collide with the TypeScript server.
+- Vue requires `@vue/language-server` v2+ (the `vue-language-server` binary) plus the workspace's `vue` package for template type-checking.
+- The full commented templates (including GDScript via a headless Godot wrapper and the complete Markdown link-validation `settings`) are written to the shared config file on first run.
+
 ## Async sub-agents
 
-Sub-agent model routing normally follows task overrides, subagent type config, then `ASYNC_SUBAGENTS_MODEL` / `PI_SUBAGENTS_MODEL` fallbacks. Set `ASYNC_SUBAGENTS_FORCE_CURRENT_MODEL=1` (or `PI_SUBAGENTS_FORCE_CURRENT_MODEL=1`) to ignore task/config/env model choices and launch every sub-agent with the current parent session model. When this flag is enabled, any `--model` entries in sub-agent extra args are stripped so they cannot override the current model.
+Model selection uses the ordered candidates from each agent's Markdown file,
+filtered by the selected preset's available models and runtime capabilities.
+Explicit task/CLI model overrides bypass the pool. Setting
+`ASYNC_SUBAGENTS_FORCE_CURRENT_MODEL=1` (or
+`PI_SUBAGENTS_FORCE_CURRENT_MODEL=1`) deliberately selects the parent model and
+strips conflicting model arguments; this is not the economical default.
+
+The five built-in modes are `research` (read-only evidence and independent
+review), `implement` (bounded code, docs, tests, or UI changes), `verify`
+(run checks and diagnose logs without fixing files), `browser-qa` (trusted
+browser workflow), and `oracle` (deliberate strong second opinion).
+Ordinary workers use economical model candidates; no built-in parent-tier
+rule promotes them to a flagship. Oracle is the exception, not an automatic
+retry for difficult work. Task-specific discipline belongs in the brief.
+
+Delegate when a suitable lower-cost worker can handle bounded work or noisy
+intermediate evidence should stay outside the parent context. One sequential
+task can qualify. Keep decisions and integration in the parent; read compact
+results and verify selectively rather than repeating the worker's investigation.
+Do trivial reads/edits directly. Redirect a noisy command to a log without an
+extra LLM when no interpretation is needed. `verify`'s no-edit instruction is
+a behavioral contract, not a read-only filesystem sandbox for its shell.
+
+Run `/ultrawork` or `/ulw` for orchestration, `/hyperplan` to pressure-test a
+plan, or set `ULTRAWORK=1` to apply the orchestration prompt to normal inputs.
+`ULTRAWORK_AUTO=1` classifies only the first normal input on non-GPT parents;
+GPT-like parents skip that automatic transform, not ordinary delegation.
+
+See [Model pools and migration](docs/subagent-model-pools.md) for the selection
+contract, configuration examples, override rules and legacy compatibility.
+
+### Parent-first role selection
+
+The parent normally selects an explicit `subagentType` from the effective
+system-prompt catalog, preferring a matching project-local specialist. Valid
+explicit types bypass the LLM router entirely; presets, model selection, tools,
+skills, and role instructions are still applied by the normal config resolver.
+Model/thinking overrides are not substitutes for selecting a role.
+
+The router remains enabled as a fallback for omitted types: use it when the role
+is unclear or the user explicitly requests automatic routing. Only omitted
+tasks are classified, in one batch; the parent's explicit choices are preserved.
+Real-browser QA still requires explicit `subagentType: "browser-qa"`.
+
+Unknown explicit types and failed/incomplete automatic routing reject the
+**entire spawn batch before run state or child processes are created**. The tool
+returns an error with affected task IDs and available types; the parent should
+correct the roles and resubmit the whole batch. Provider error responses are
+failures too, not successful routes. Configured fallback router models may be
+tried, but missing routes are never silently replaced with `quick`/`defaultType`.
+
+With `routing.enabled: false`, every spawn task must supply a valid explicit
+type. `defaultType` remains a preference for genuinely ambiguous LLM choices
+and a legacy config-resolver default, not a spawn error fallback. Existing
+callers relying on an implicit default must now choose a type explicitly.
+
+### Project-local agents (`.pi/agents/*.md`)
+
+A project can ship sub-agent roles as individual Markdown files in
+`<project>/.pi/agents/`. The first such directory found walking up from the
+session cwd is used; each top-level `*.md` file becomes a `subagentType` named
+after the file. Parent and router see the short `description`; only the child
+receives the Markdown body. A project's ordered `models` are filtered through
+the same active preset pool as built-in agents.
+
+```markdown
+---
+description: Use for reviewing this repo's diff — knows the house rules.
+icon: eye
+models:
+  - zai/glm-5-turbo
+  - openai-codex/gpt-5.6-luna
+thinking: low
+tools: read, grep
+retry:
+  maxRetries: 1
+  backoffMs: 2000
+---
+
+You are this project's staff reviewer. Apply the repo rules from
+AGENTS.md before approving anything; cite file paths first.
+```
 
-For an oh-my-openagent-style workflow, run `/ultrawork` or `/ulw` to ask the parent agent to split broad work into configured async-subagents roles (`quick`, `scan`, `research`, `docs`, `frontend`, `browser-qa`, `implement`, `tests`, `review`, `deep`, `oracle`). Set `ULTRAWORK=1` before launching Pi to apply that compact routing prompt to normal non-slash user inputs automatically. Set `ULTRAWORK_AUTO=1` to ask the lightweight router model to classify only the first normal user input on non-GPT parent models: clear broad/parallel work is transformed into ultrawork, vague potentially-complex work gets a soft delegation hint, and narrow work is left unchanged. GPT-like parent models skip only this automatic transform; they can still use `/ultrawork` and `subagents` normally. `frontend` is for UI/UX, styling, layout, responsive behavior, and visual component polish; `browser-qa` reproduces browser bugs and proves fixes with deterministic assertions plus screenshot/video/trace evidence; `review` covers security/performance/audit tracks; `implement` covers refactors; `deep` covers debugging/root-cause; `oracle` is for sparse cross-provider second opinions on high-stakes uncertainty. Run `/hyperplan` to pressure-test a plan before implementation.
+- Frontmatter keys: `name` (must match the filename), `description`, `icon`, `models`, `thinking`, `tools`, `isolatedSkills`, `extraArgs`, `promptAppend`, `promptOverride`, `retry`, `maxResultBytes`, `timeoutMs`. Legacy `model`, `fallbackModels`, and `modelByParent` still load. Unknown keys are rejected with an error naming the file.
+- Array fields accept block lists (`- item`), inline arrays (`[a, b]`), or comma-separated strings (`tools: read, grep, bash`). The frontmatter YAML subset is intentionally small: scalars, quoted strings, numbers, comments, lists, and nested maps for `modelByParent`/`retry`. Tabs, block scalars (`|`/`>`), anchors/aliases, and flow maps are hard errors naming file and line.
+- The markdown body becomes `promptAppend`: it is appended after the standard generated prompt (parent objective + task + output format), so the agent still receives its task in the usual structure. Use frontmatter `promptOverride` for full prompt replacement.
+- Precedence: project agent fields override same-named types from user/project JSONC config (field-level; other fields are kept), which in turn override built-ins. Setting `ASYNC_SUBAGENTS_CONFIG` / `PI_SUBAGENTS_CONFIG` disables the directory (explicit config = full control).
+- Files without frontmatter are skipped (a `README.md` there is fine). Definition loading is uncached: edits apply on the next config read/spawn without a restart, and the effective system-prompt catalog is rebuilt at parent-agent start.
+- Bundled roles use the same format internally under `src/async-subagents/agents/*.md`; built-in and project-local profiles therefore share one parser and normalization path instead of maintaining a second role-description schema in TypeScript.
+- `icon` names an agent glyph for UIs that render sub-agent widgets (pix TUI panel, Pix Desktop subagents panel): `agent` (neutral default), `search`, `code`, `flask`, `globe`, `sparkles`, `brain`, `wrench`, `terminal`, `bug`, `book`, `eye`, `zap`, `rocket`. The value is passed through opaquely; unknown names render as the neutral agent icon, and status stays color-coded next to it.
 
 ### Private browser QA and project auth
 
 The built-in `browser-qa` role runs on `zai/glm-5.3-flash`, with
-`openai-codex/gpt-5.6-luna` as its fallback. Its browser
-workflow is an explicit private skill under `src/async-subagents/private-skills/`,
-outside normal Pi skill discovery. The role's first-class `isolatedSkills` setting launches the child with
-`--no-skills` plus one self-contained private workflow. It bundles the relevant
-scenario-design, locator, waiting, assertion, evidence, and cleanup guidance next
-to its trusted runner, so browser QA does not depend on a separately installed
-skill or CLI. The private workflow remains mandatory when configuration appends
-other isolated skills; parent and ordinary sub-agent sessions do not discover it.
+`openai-codex/gpt-5.6-luna` as its fallback. Its complete workflow and detailed
+scenario-design guidance live in the Markdown body of
+`src/async-subagents/agents/browser-qa.md`. The normal profile loader appends
+that body to the QA child's task prompt; the parent and LLM router receive only
+the short `description`. There is no additional QA skill to discover or read.
+
+Executable resources live under `src/async-subagents/agents/browser-qa/`.
+The launcher supplies the installed runner's absolute path in
+`PI_BROWSER_QA_RUNNER`; the child invokes `node "$PI_BROWSER_QA_RUNNER"` from
+the delegated project's cwd. This non-secret path is set only for QA children.
+QA always launches with `--no-skills`, even when `isolatedSkills` is empty,
+and skill flags in `extraArgs` cannot bypass that isolation. Explicitly
+configured `isolatedSkills` remain supported as optional additions; no built-in
+QA `--skill` is injected. Other roles retain their normal discovery behavior.
+
+Model/thinking/tool-only profile overrides inherit the Markdown workflow.
+An explicit profile `promptAppend` replaces the inherited body under the usual
+field-level merge rules; custom QA instructions must preserve the runner-only,
+credential, target, and evidence contracts. Runner-enforced isolation and
+credential handling remain in code, not in the prompt.
 
 Public browser QA does not require an auth profile or `.pi/qa_auth.jsonc`: run it
 with an explicit base URL, whose exact origin becomes the fail-closed allowlist.
@@ -325,8 +607,8 @@ creating a template. Only an explicit authenticated request may create the
 private template. Missing, rejected, or expired selected auth returns
 `QA_AUTH_UPDATE_REQUIRED`, naming only the profile/file/reason needed for the
 parent to ask the user for an update and rerun. See
-`src/async-subagents/private-skills/browser-qa/references/qa-auth.example.jsonc`
-for complete profile shapes and `references/qa-flow.example.jsonc` beside it for
+`src/async-subagents/agents/browser-qa/examples/qa-auth.example.jsonc`
+for complete profile shapes and `examples/qa-flow.example.jsonc` beside it for
 the declarative, non-executable QA action/assertion format.
 
 Browser QA videos automatically visualize pointer interactions. Clicks and
@@ -341,68 +623,92 @@ Async-subagents also injects a lightweight oh-my-openagent-style system-prompt s
 
 For blind-model screenshot/image inspection, use the main-session `coding-discipline` lookup tool; the bundled default uses vision-capable `zai/glm-5.3-flash`. Async-subagents still supports `imagePaths` on tasks when a broader delegated track genuinely needs images, but it no longer ships a dedicated `vision` role. Dynamic provider capabilities can be missing or stale after switching models, so blind parent models can still be configured explicitly with case-insensitive `*` masks under `asyncSubagents.vision.blindModelPatterns` in `~/.config/pi/pi-tools-suite.jsonc`; do not include `zai/glm-5.3-flash` because it accepts image input. This keeps guidance honest, not a sub-agent role.
 
-When a task omits `subagentType`, async-subagents asks a lightweight router model to choose one configured type for each task from the task text/scope and the `types.<name>.description` metadata. Explicit task `subagentType` still wins. Keep type descriptions short, literal, and distinct because they are inserted into the router prompt for a small model. Router settings live under `asyncSubagents.routing` (`enabled`, `model`, `maxTaskChars`, `maxTokens`, `maxRetries`, `timeoutMs`, `debug`); the default router model is `zai/glm-4.5-air`. If the router is disabled, unavailable, aborted, or returns invalid JSON, omitted types fall back to `defaultType`.
-
-Define optional `presets` under `asyncSubagents` in `~/.config/pi/pi-tools-suite.jsonc`, `$PI_CONFIG_DIR/pi-tools-suite.jsonc`, or project `.pi/pi-tools-suite.jsonc`, then use `/subagent-preset` or `/subagent-preset-config` to pick one persistent active preset for future spawns across all sessions. Set `AGENTS_PRESET=<name>` before launching Pi to override the saved preset for only the current process/session without changing the saved selection. If Pi is already running, use `/subagent-preset session <name>` for the same process-only override, and `/subagent-preset session-clear` to remove that runtime override. The TUI only selects presets already present in config; it does not edit JSON. If no `asyncSubagents` section exists, run `/subagent-preset init` to insert the bundled sample from `src/async-subagents/async-subagents.sample.jsonc` into the shared config (or to copy a standalone override file when `ASYNC_SUBAGENTS_CONFIG` / `PI_SUBAGENTS_CONFIG` is set). Existing config sections/files are never overwritten. Presets select an agent/model configuration: they can provide global fallback `model`/`thinking`/`extraArgs` and per-role overrides under `asyncSubagents.presets.<name>.types.<subagentType>`. They can also provide ordered `fallbackModels` globally or per-role; when a sub-agent fails with quota/rate-limit errors such as 429, async-subagents immediately tries the next fallback model and remembers the exhausted provider for the current Pi process/session, so later spawns skip that provider until Pi exits. This is intended for provider-level fallback chains such as `antigravity/* → openai-codex/* → zai/*` or `openai-codex/* → zai/*`; omit fallbacks for effectively unlimited providers. Antigravity account rotation has priority over preset fallback: async-subagents only falls back after Antigravity reports that all configured accounts are exhausted for that model. Explicit task model overrides and force-current-model disable preset fallback for that task. The active preset name is stored separately in `~/.pi/agent/subagent-preset-selection.json`.
+When `subagentType` is omitted, the lightweight role router classifies the task
+using the descriptions. Explicit types bypass it. Unknown types or failed
+routing reject the batch, never substitute `defaultType`. Choosing a worker
+model from its candidate list does not involve an LLM call.
+
+### Presets are available-model pools
+
+Each agent declares an ordered `models` list in Markdown. A preset declares
+which model references may be used, not another role/model/thinking matrix.
+Selection preserves agent order, intersects it with `preset.models`, checks
+runtime registration/auth availability, and takes the first usable candidate.
+Pool order does not change preference and pool-only models are never appended.
+Without a preset, the full agent list is eligible. Candidate order expresses
+the configured budget preference; runtime does not infer current API prices.
+
+Image-bearing tasks and `browser-qa` require confirmed image support; configured
+blind-model masks override runtime image metadata. Remaining eligible models
+form the quota fallback chain, so neither quota history nor image fallback can
+escape the pool. Antigravity account rotation still happens before provider
+fallback. No match, no usable model, or an explicitly empty list rejects the
+whole batch before run directories or child processes are created. A new custom
+agent must supply candidates instead of silently inheriting the parent model.
+
+Oracle uses its separate strong-model list and prefers another provider when
+available, but also respects the pool. A same-provider choice is allowed when
+the pool offers no alternative; cross-provider independence is not guaranteed.
+Explicit task/CLI model overrides and `FORCE_CURRENT_MODEL` remain deliberate
+escape hatches and disable automatic model fallback for that task. They do not
+bypass the image-capability check.
+
+Define pools in the shared or project `pi-tools-suite.jsonc`. Select a saved
+pool with `/subagent-preset`; use `AGENTS_PRESET=<name>` or
+`/subagent-preset session <name>` for a process-only override and
+`/subagent-preset session-clear` to remove it. The saved selection lives in
+`~/.pi/agent/subagent-preset-selection.json`. `/subagent-preset init` inserts the
+sample only when config is missing. The shipped pools are `cheap` (GLM), `gpt`,
+and `deep` (the retained legacy name for the mixed pool, not worker escalation).
+Initial user config and the sample share one source; descriptions and worker
+model order exist only in the agent files. Existing user files are not rewritten.
 
 Example shared async-subagents config section:
 
 ```jsonc
 {
   "asyncSubagents": {
-    "defaultType": "quick",
+    "defaultType": "research",
     "routing": {
       "enabled": true,
-      "model": "zai/glm-4.5-air",
+      "model": "zai/glm-5-turbo",
       "timeoutMs": 12000
     },
     "presets": {
       "cheap": {
-        "description": "Use GLM by role, including GLM-5.3 Flash for multimodal work.",
-        "types": {
-          "quick": { "model": "zai/glm-5.3", "thinking": "off" },
-          "frontend": { "model": "zai/glm-5.3-flash", "thinking": "medium" },
-          "browser-qa": { "model": "zai/glm-5.3-flash", "fallbackModels": ["openai-codex/gpt-5.6-luna"], "thinking": "low" },
-          "review": { "model": "zai/glm-5.3", "thinking": "high" }
-        }
+        "description": "GLM workers with a strong oracle candidate.",
+        "models": ["zai/glm-5-turbo", "zai/glm-5.3-flash", "zai/glm-5.3"]
       }
     },
     "types": {
-      "frontend": {
-        "description": "Use for frontend UI/UX visual work: styling, layout, typography, animation, responsive states, component polish, accessibility. Avoid backend/business logic unless needed for UI behavior.",
-        "thinking": "medium"
-      },
-      "review": {
-        "description": "Use for review/audit of existing code or changes: correctness, security, performance, maintainability, API risks, quality. Do not implement new code.",
-        "thinking": "high"
+      "research": {
+        "models": ["zai/glm-5-turbo", "openai-codex/gpt-5.6-luna"],
+        "thinking": "low"
       }
     }
   }
 }
 ```
 
-### Parent-model-aware model selection (`modelByParent`)
+### Legacy configuration compatibility
 
-Any type profile can carry `modelByParent`: a map from glob model refs (matched against the **current parent model**, e.g. `"zai/*"`) to a model for that role. The first matching key wins. Values may be a model string or `{ "model": "...", "fallbackModels": [...] }`. It is resolved after an explicit task `model` / `forcedModel`, but **before** the preset/static profile `model`, so a role can always pick a model based on who the parent is — independent of the active preset.
+Old built-in role names are no longer implicit aliases. `quick`, `scan`,
+`review`, `deep`, `docs`, `frontend`, and `tests` are valid only when explicitly
+defined as ordinary custom/project types. Old preset per-role keys likewise
+apply only when a type with that exact name exists.
 
-The canonical use case is an **`oracle`** role that consults a flagship model from a *different* provider than the parent for a second opinion:
+Legacy `model` plus `fallbackModels` remains readable. `models` is a complete
+replacement list: it clears inherited legacy model/fallback/parent routing.
+A later old-format model override still replaces the primary candidate, and a
+later `fallbackModels` replaces the remaining candidates; `[]` disables them.
+Old `modelByParent` configs remain supported, but ordinary roles give legacy
+preset models precedence. New built-ins contain no parent-tier escalation maps.
 
-```jsonc
-"oracle": {
-  "description": "Cross-provider second opinion: consult a flagship from a different provider than the parent to pressure-test a hard decision. Read-only; advise, do not edit.",
-  "model": "openai-codex/gpt-5.6-sol",
-  "fallbackModels": ["zai/glm-5.3"],
-  "thinking": "max",
-  "modelByParent": {
-    "zai/*":         { "model": "openai-codex/gpt-5.6-sol", "fallbackModels": ["zai/glm-5.3"] },
-    "openai-codex/*": "zai/glm-5.3",
-    "antigravity/*": { "model": "zai/glm-5.3", "fallbackModels": ["openai-codex/gpt-5.6-sol"] },
-    "anthropic/*":   { "model": "openai-codex/gpt-5.6-sol", "fallbackModels": ["zai/glm-5.3"] }
-  }
-}
-```
-
-With this config a GLM parent (`zai/*`) spawns the oracle on `gpt-5.6-sol`, a GPT parent (`openai-codex/*`) spawns it on `glm-5.3`, and so on — automatically, at spawn time, with no `task.model` needed. The parent model ref is read from the spawn context (`ctx.model`) and passed into resolution. Pattern matching is case-insensitive `*` glob (same engine as `vision.blindModelPatterns`). When no key matches (or no parent model is known), the role falls back to its static `model` + `fallbackModels`. An explicit `task.model` or `ASYNC_SUBAGENTS_FORCE_CURRENT_MODEL=1` still overrides the match.
+When a preset specifies `models`, it is exclusively a pool; inherited legacy
+`model`, `types`, thinking, arguments and timeout overrides do not run. A later
+explicit old-format preset selector can still replace a pool for compatibility.
+Runtime retry structures and the separate role router continue to use the
+term `fallbackModels` for actual fallback-only lists, not agent candidates.
 
 Sub-agents run with `--no-session` by default to avoid writing duplicate Pi session JSONL files for fire-and-forget background work. Set `ASYNC_SUBAGENTS_ENABLE_SESSIONS=1` to restore persisted per-agent sessions under each agent's `sessions/` directory; this also registers the session-navigation slash commands (`/sub-open`, `/sub-back`, `/sub-where`) needed for switching and deeper post-mortem navigation.
 
@@ -520,6 +826,40 @@ npm run test:prompt-evals:dcp
 
 The default live model is `zai/glm-5-turbo`. Override it for the whole suite with `PI_TOOLS_SUITE_E2E_MODEL=provider/model`, or use the existing component variables such as `TOOL_SELECTION_E2E_MODEL`, `ASYNC_SUBAGENTS_MODEL`, `ASYNC_SUBAGENTS_ROUTING_E2E_MODEL`, and `DCP_SUMMARY_E2E_MODEL`. The normal deterministic coverage remains `npm test`; run prompt evals after changing tool descriptions, routing/classifier prompts, DCP summary prompts, or the default evaluation model.
 
+### Unified eval harness
+
+`test/evals/` adds a shared deterministic + live-model eval layer. The coverage
+gate requires every registered extension and model-facing tool to have a
+deterministic contract. The initial live corpus contains 20 cases across tool
+selection, coding quality, orchestration/escalation, and negative overuse
+controls. Coding-quality fixtures use executable behavioral checks rather than
+an LLM judge, while reports compare parent/worker tokens, provider-reported cost,
+tool calls, changed files, and elapsed time.
+
+```bash
+# Deterministic coverage/contract gate only
+npm run test:evals:contracts
+
+# Live matrix as Bun tests. Models are comma/semicolon separated.
+PI_TOOLS_SUITE_EVAL_MODELS='zai/glm-5.3,openai-codex/gpt-5.6-luna,openai-codex/gpt-5.6-terra,openai-codex/gpt-5.6-sol' \
+  npm run test:evals:live
+
+# Produce JSON + Markdown comparison artifacts.
+PI_TOOLS_SUITE_EVAL_MODELS='zai/glm-5.3,openai-codex/gpt-5.6-terra,openai-codex/gpt-5.6-sol' \
+  npm run evals:report
+
+# Focus the report runner when iterating
+PI_TOOLS_SUITE_EVAL_MODELS='zai/glm-5.3' \
+PI_TOOLS_SUITE_EVAL_CATEGORIES='coding-quality,negative' \
+  npm run evals:report
+```
+
+Live evals are opt-in. The deterministic coverage registry is part of normal
+tests, so adding an extension or tool without eval coverage fails the gate. See
+[`docs/evals.md`](docs/evals.md) for the architecture, complete 20-case catalog,
+fixtures, assertions, metrics, model matrix, report format, environment
+variables, CI recommendations, and the procedure for adding new evals.
+
 Supporting docs and historical standalone README content are kept in `docs/`; third-party license texts are kept in `licenses/`.
 
 ## SDK pin

package/external/pi-tools-suite/docs/browser-qa-subagent.md

@@ -4,25 +4,32 @@
 
 Provide a cheap, fast `browser-qa` async-subagent that reproduces browser bugs
 and proves fixes with deterministic assertions plus screenshot, video, and trace
-evidence. The role uses `zai/glm-5.3-flash`, falling back to
-`openai-codex/gpt-5.6-luna`.
-
-## Private skill isolation
-
-- The browser QA skill lives under `src/async-subagents/private-skills/`, outside
-  Pi's normal skill discovery roots.
+evidence. Its ranked `models` list prefers `zai/glm-5.3-flash`, then
+`openai-codex/gpt-5.6-luna`, filtered by the active preset's model pool and
+confirmed runtime image support.
+
+## Inline agent workflow and skill isolation
+
+- All operating instructions, flow contracts, scenario-design guidance, and
+  auth-scaffolding rules live in `src/async-subagents/agents/browser-qa.md`.
+  Its body becomes the QA child's `promptAppend` through the shared agent
+  loader. Parent and router catalogs include only its short `description`.
+- Runner code, vendor dependencies/licenses, and optional JSONC examples live
+  under `src/async-subagents/agents/browser-qa/`; none is a discoverable skill.
 - Sub-agent processes disable normal extension discovery, then always load the
-  suite's model-tools and Antigravity provider extensions explicitly, regardless
-  of the selected model. This keeps the process isolated without making any
-  Antigravity-backed role unavailable.
+  suite's model-tools extension. They load the Antigravity provider extension
+  only when an Antigravity model is explicitly selected.
 - A type profile may declare `isolatedSkills`. Spawning that profile adds
   `--no-skills` followed by one explicit `--skill` per configured path.
-- The `browser-qa` profile always loads one self-contained private workflow.
-  Relevant browser-test design guidance is bundled beside its trusted runner;
-  no separately discovered skill or browser CLI is required. Configuration may
-  append isolated skills but cannot remove the mandatory private workflow.
-- Other sub-agent profiles and the parent session must not discover the private
-  skill automatically.
+- `browser-qa` always disables normal skill discovery and filters skill flags
+  out of `extraArgs`, even without configured skills. It no longer injects a
+  mandatory QA skill. Explicitly configured skills are optional additions.
+- The launcher sets `PI_BROWSER_QA_RUNNER` to the absolute installed runner path,
+  replacing inherited values, and strips it from ordinary child environments.
+  QA invokes `node "$PI_BROWSER_QA_RUNNER"` without guessing paths from cwd.
+- Model-only profile overrides inherit the workflow. An explicit profile
+  `promptAppend` replaces the body like any other agent profile; it is not an
+  immutable security boundary. Runtime protections remain in the runner.
 
 ## Authentication contract
 
@@ -98,7 +105,7 @@ evidence. The role uses `zai/glm-5.3-flash`, falling back to
 
 ## Reliability and shutdown contract
 
-- The built-in `browser-qa` profile has a 120-second wall-clock budget unless
+- The built-in `browser-qa` profile has a 300-second wall-clock budget unless
   the caller explicitly supplies a task or spawn timeout. This bounds model
   stalls as well as browser work.
 - The trusted runner has its own bounded lifecycle. Browser launch, context
@@ -124,11 +131,14 @@ evidence. The role uses `zai/glm-5.3-flash`, falling back to
 
 ## Acceptance criteria
 
-1. `browser-qa` resolves to the intended model/fallback and its self-contained
-   private workflow, and its isolated child process can register the configured
+1. `browser-qa` resolves to the intended model/fallback and its inline Markdown
+   workflow, and its isolated child process can register the configured
    model provider.
-2. Spawn args contain `--no-skills` and the mandatory private skill for this
-   profile; ordinary profiles retain existing skill discovery behavior.
+2. Default QA spawn args contain `--no-skills` but no `--skill`. The child
+   receives the full workflow in its initial prompt and can invoke the bundled
+   runner through `PI_BROWSER_QA_RUNNER` from an unrelated project directory.
+   Optional configured skills still load; ordinary profiles retain existing
+   skill discovery behavior and do not receive QA-only environment paths.
 3. Auth profile listing and all error output are redacted; model-authored input
    cannot execute code in the credential-bearing process.
 4. Runner tests cover public execution without an auth file, explicit profile