@kingingwang/pi-darwin-arm64 0.84.2 → 0.84.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/bin/CHANGELOG.md +127 -0
  2. package/bin/README.md +13 -8
  3. package/bin/docs/compaction.md +17 -0
  4. package/bin/docs/custom-provider.md +12 -9
  5. package/bin/docs/environment-variables.md +11 -8
  6. package/bin/docs/extensions.md +35 -7
  7. package/bin/docs/json.md +7 -2
  8. package/bin/docs/keybindings.md +9 -9
  9. package/bin/docs/llama-cpp.md +2 -0
  10. package/bin/docs/models.md +8 -2
  11. package/bin/docs/packages.md +2 -2
  12. package/bin/docs/quickstart.md +1 -1
  13. package/bin/docs/rpc.md +32 -3
  14. package/bin/docs/sdk.md +7 -2
  15. package/bin/docs/settings.md +23 -7
  16. package/bin/docs/skills.md +4 -3
  17. package/bin/docs/terminal-setup.md +23 -9
  18. package/bin/docs/usage.md +10 -5
  19. package/bin/docs/windows.md +24 -2
  20. package/bin/examples/extensions/border-status-editor.ts +1 -1
  21. package/bin/examples/extensions/custom-provider-anthropic/package-lock.json +2 -2
  22. package/bin/examples/extensions/custom-provider-anthropic/package.json +1 -1
  23. package/bin/examples/extensions/custom-provider-gitlab-duo/package.json +1 -1
  24. package/bin/examples/extensions/git-checkpoint.ts +2 -2
  25. package/bin/examples/extensions/gondolin/package-lock.json +2 -2
  26. package/bin/examples/extensions/gondolin/package.json +1 -1
  27. package/bin/examples/extensions/notify.ts +3 -1
  28. package/bin/examples/extensions/sandbox/package-lock.json +2 -2
  29. package/bin/examples/extensions/sandbox/package.json +1 -1
  30. package/bin/examples/extensions/subagent/README.md +1 -1
  31. package/bin/examples/extensions/subagent/index.ts +6 -1
  32. package/bin/examples/extensions/titlebar-spinner.ts +1 -1
  33. package/bin/examples/extensions/with-deps/package-lock.json +2 -2
  34. package/bin/examples/extensions/with-deps/package.json +1 -1
  35. package/bin/examples/rpc-extension-ui.ts +1 -1
  36. package/bin/examples/sdk/06-extensions.ts +1 -1
  37. package/bin/examples/sdk/README.md +1 -1
  38. package/bin/package.json +12 -14
  39. package/bin/pi +0 -0
  40. package/package.json +1 -1
  41. package/bin/node_modules/@mariozechner/clipboard-darwin-arm64/README.md +0 -3
  42. package/bin/node_modules/@mariozechner/clipboard-darwin-arm64/clipboard.darwin-arm64.node +0 -0
  43. package/bin/node_modules/@mariozechner/clipboard-darwin-arm64/package.json +0 -22
package/bin/CHANGELOG.md CHANGED
@@ -1,5 +1,130 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.84.4] - 2026-08-28
4
+
5
+ ### New Features
6
+
7
+ - **Terminal capability overrides** — Override detected terminal hyperlink, image, and truecolor support. See [Capability Overrides](docs/terminal-setup.md#capability-overrides).
8
+ - **Extension UI prompt events** — Integrations can distinguish active agent work from time spent waiting for `ctx.ui` prompts. See [Extension UI prompt events](docs/extensions.md#ui_prompt_start--ui_prompt_end).
9
+ - **RPC queue clearing** — Retrieve and clear queued steering and follow-up messages with `clear_queue`. See [RPC `clear_queue`](docs/rpc.md#clear_queue).
10
+ - **Fullscreen selection copy controls** — Disable automatic selection copying in fullscreen mode and use Ctrl+X to copy the active selection. See [UI & Display](docs/settings.md#ui--display).
11
+ - **DeepSeek V4 Flash Vision (experimental)** — Use the vision-capable model through the built-in DeepSeek provider. See [API Keys](docs/providers.md#api-keys).
12
+
13
+ ### Added
14
+
15
+ - Added `ui_prompt_start` and `ui_prompt_end` extension events so host integrations can distinguish active agent work from waiting on user-facing `ctx.ui` prompts ([#8355](https://github.com/earendil-works/pi/pull/8355) by [@cristinaponcela](https://github.com/cristinaponcela)).
16
+ - Added `detectSupportedImageMimeTypeFromFile()` to the public library exports ([#8600](https://github.com/earendil-works/pi/pull/8600) by [@xl0](https://github.com/xl0)).
17
+ - Added inherited experimental vision-capable `deepseek-v4-flash-vision-exp` model support.
18
+ - Added transcript usage notices for compaction and branch summaries when cache miss notices are enabled.
19
+ - Added RPC `clear_queue` to retrieve and remove queued steering and follow-up messages ([#8432](https://github.com/earendil-works/pi/issues/8432)).
20
+ - Added environment variables and advanced settings for overriding auto-detected terminal hyperlink, image, and truecolor capabilities ([#8665](https://github.com/earendil-works/pi/issues/8665)).
21
+ - Added `fullscreenCopyOnSelect` to disable automatic fullscreen selection copy; when disabled, `Ctrl+X` copies the active text selection before falling back to the last assistant message, while `/tree` still copies the selected message ([#7720](https://github.com/earendil-works/pi/issues/7720)).
22
+
23
+ ### Fixed
24
+
25
+ - Fixed toggling thinking visibility clearing partial output from running Bash tools ([#8611](https://github.com/earendil-works/pi/issues/8611)).
26
+ - Fixed Windows shell aborts crashing Pi when `taskkill.exe` is unavailable on `PATH` ([#6596](https://github.com/earendil-works/pi/issues/6596)).
27
+ - Fixed resumed sessions corrupting the next appended entry when their JSONL file lacks a trailing newline ([#8345](https://github.com/earendil-works/pi/issues/8345)).
28
+ - Fixed extension messages sent with `triggerTurn: false` while the agent is running being inserted between a tool call and its result, which made providers that validate message order reject the replayed history. They are now appended once the turn's tool results are in ([#8537](https://github.com/earendil-works/pi/issues/8537)).
29
+ - Fixed compaction and branch summaries forcing `toolChoice: "none"` ([#8649](https://github.com/earendil-works/pi/issues/8649), [#8638](https://github.com/earendil-works/pi/issues/8638)).
30
+ - Fixed large tool results crossing the auto-compaction threshold being sent to the provider before compaction. Pi now compacts between tool execution and the next assistant response in the same run, and restores interactive progress when that run resumes ([#6879](https://github.com/earendil-works/pi/issues/6879)).
31
+ - Fixed Google Vertex requests failing with `HttpsProxyAgent is not a constructor` when the bundled Node.js runtime uses an HTTP(S) proxy ([#8610](https://github.com/earendil-works/pi/issues/8610)).
32
+ - Fixed saving a default model from a non-empty model scope so it remains available in that scope.
33
+ - Fixed inherited `@` file autocomplete ranking to prefer direct and shallower matches over similarly ranked nested paths ([#8669](https://github.com/earendil-works/pi/pull/8669)).
34
+ - Fixed inherited OpenAI-compatible streams serializing thinking signatures repeatedly during streaming ([#8671](https://github.com/earendil-works/pi/pull/8671)).
35
+ - Fixed inherited main-screen rendering crashing when image-heavy output exceeded V8's string length limit ([#8028](https://github.com/earendil-works/pi/issues/8028)).
36
+ - Fixed inherited fullscreen double-click word selection splitting paths and kebab-case tokens on `/` and `-` ([#8676](https://github.com/earendil-works/pi/pull/8676)).
37
+ - Fixed inherited Cloudflare AI Gateway catalogs omitting supported `workers-ai/*` passthrough models.
38
+ - Fixed inherited OpenAI-compatible reasoning replay to merge consecutive streamed text and summary `reasoning_details` deltas.
39
+ - Fixed inherited OpenRouter reasoning controls so reasoning-mandatory models do not receive `effort: "none"` ([#8614](https://github.com/earendil-works/pi/pull/8614) by [@davidbrai](https://github.com/davidbrai)).
40
+ - Fixed inherited OpenAI-compatible Chat Completions ignoring an explicitly requested `toolChoice` when no tools are defined.
41
+ - Fixed inherited fragmented Mistral tool calls splitting when continuation chunks omit the tool-call ID ([#8387](https://github.com/earendil-works/pi/issues/8387)).
42
+
43
+ ## [0.84.3] - 2026-08-24
44
+
45
+ ### New Features
46
+
47
+ - **PowerShell tool** — Use optional native PowerShell command execution on Windows. See [PowerShell Tool](docs/windows.md#powershell-tool).
48
+ - **Safer managed updates** — Stage, verify, and atomically activate updates for installer-managed installations. See [Install and Manage](docs/packages.md#install-and-manage).
49
+ - **Model and thinking controls** — Select thinking levels with `/thinking`, search defaults, keep selections session-scoped, and persist them explicitly with Ctrl+S. See [Models and Thinking](docs/keybindings.md#models-and-thinking).
50
+
51
+ ### Breaking Changes
52
+
53
+ - Renamed the inherited `GoogleThinkingLevel` type to `GoogleApiThinkingLevel` and added `ResolvedGoogleThinkingLevel` for normalized adapter levels.
54
+
55
+ ### Added
56
+
57
+ - Added an optional `powershell` tool for Windows, configurable through `defaultTools` and the SDK. See [PowerShell Tool](docs/windows.md#powershell-tool).
58
+ - Added a `/thinking` selector and searchable default choices to the model and thinking selectors; Ctrl+S saves the selected model as the global default. See [Models and Thinking](docs/keybindings.md#models-and-thinking).
59
+ - Added optional routing session IDs to exported compaction summary helpers so callers can preserve provider routing without enabling prompt cache writes.
60
+ - Added
61
+
62
+
63
+
64
+ usage notices for compaction and branch summaries when cache miss notices are enabled.
65
+ - Added `session_compact_failed` extension events so compaction failures and aborts expose their reason, retry state, source, and error message to handlers ([#8175](https://github.com/earendil-works/pi/issues/8175)).
66
+ - Added inherited provider-neutral `toolChoice` support to simple stream requests.
67
+ - Added inherited automatic Anthropic server-side refusal fallback for supported first-party models, including returned-model usage pricing ([#8017](https://github.com/earendil-works/pi/issues/8017)).
68
+ - Added inherited configurable OpenAI-compatible thinking-token budget fields for vLLM, Qwen/SGLang, and llama.cpp servers. See [OpenAI Compatibility](docs/models.md#openai-compatibility) ([#8275](https://github.com/earendil-works/pi/pull/8275) by [@bnsd55](https://github.com/bnsd55)).
69
+ - Added inherited China-specific ZAI Coding Plan models, including GLM-4.6V vision support and API-equivalent usage cost estimates ([#8220](https://github.com/earendil-works/pi/issues/8220)).
70
+ - Added inherited `deepseek-v4-pro-0813` support to the Qwen Token Plan Individual catalog ([#8194](https://github.com/earendil-works/pi/issues/8194)).
71
+
72
+ ### Changed
73
+
74
+ - Changed experimental installer-managed installations so `pi update` stages, verifies, and atomically activates the selected release in place. See [Install and Manage](docs/packages.md#install-and-manage).
75
+ - Changed inherited built-in xAI models to use the Responses API with encrypted reasoning replay and made Grok 4.6 the default xAI model ([#8124](https://github.com/earendil-works/pi/pull/8124) by [@Jaaneek](https://github.com/Jaaneek)).
76
+ - Changed inherited Anthropic, Azure OpenAI, Google, Mistral, and OpenAI adapters to send Pi's default `User-Agent` unless overridden ([#8305](https://github.com/earendil-works/pi/issues/8305)).
77
+ - Changed Windows and WSL keybinding defaults to avoid terminal-reserved shortcuts for image paste, model cycling, editor undo, fullscreen transcript navigation and search, and message queueing ([#8372](https://github.com/earendil-works/pi/issues/8372)).
78
+ - Changed Bun release archives to ship the native clipboard binary only inside the wrapper package, removing a duplicate platform package from each archive.
79
+ - Changed package resource glob expansion to use Node.js's built-in implementation with deterministic visible-path matching, reducing the installed runtime dependency tree.
80
+ - Changed the bundled Node.js runtime to load jiti only when importing an extension and Babel only when uncached source needs transformation, reducing CLI startup time and bundle size.
81
+ - Changed syntax highlighting to initialize only twenty common languages eagerly and defer the remaining grammars until after the initial TUI render, reducing CLI startup time.
82
+ - Changed the Node.js CLI and RPC entrypoints to load a bundled runtime, reducing startup filesystem reads while keeping the public library and legacy module paths on the modular runtime for normal dependency identity.
83
+ - Changed session sharing to render clickable terminal links, display only the canonical Radius artifact URL, and include the current system prompt and active tool definitions in Radius session shares.
84
+
85
+ ### Fixed
86
+
87
+ - Fixed failed extension factories leaving event subscriptions, provider registrations, and default flag state active ([#8424](https://github.com/earendil-works/pi/pull/8424) by [@acmerfight](https://github.com/acmerfight)).
88
+ - Fixed `models.json` typings omitting the documented OpenAI-compatible `compat.supportsFinishReason` provider and model override ([#8487](https://github.com/earendil-works/pi/pull/8487) by [@petrroll](https://github.com/petrroll)).
89
+ - Fixed `/model` and `/thinking` selections being persisted globally unless explicitly saved with Ctrl+S ([#5263](https://github.com/earendil-works/pi/issues/5263)).
90
+ - Fixed JSON and RPC `toolcall_start` events omitting the tool call id and name ([#7953](https://github.com/earendil-works/pi/pull/7953) by [@christianklotz](https://github.com/christianklotz)).
91
+ - Fixed extensions failing to load when the Node.js CLI runs as a single-executable application ([#8237](https://github.com/earendil-works/pi/issues/8237)).
92
+ - Fixed nested Markdown skills inside `.agents/skills/` grouping directories not being discovered.
93
+ - Fixed compaction and branch summarization requests exposing tools to providers.
94
+ - Fixed single-object `edit` tool inputs failing validation by accepting them as one-edit arrays in both coding-agent and harness edit tools ([#7835](https://github.com/earendil-works/pi/issues/7835)).
95
+ - Fixed root Markdown files such as `README.md` and `AGENTS.md` in skill directories being reported as broken skills unless they declare valid skill frontmatter ([#7805](https://github.com/earendil-works/pi/issues/7805)).
96
+ - Fixed the default Cerebras model referencing an unavailable Z.AI model.
97
+ - Fixed inherited OpenAI-compatible Chat Completions reasoning replay to preserve and resend assistant-level `reasoning_details` verbatim and in order ([#7994](https://github.com/earendil-works/pi/issues/7994)).
98
+ - Fixed inherited Anthropic server-side fallback responses being priced with the requested model instead of the returned fallback model ([#8285](https://github.com/earendil-works/pi/issues/8285)).
99
+ - Fixed inherited GitHub Copilot login triggering model-policy rate limits by limiting policy updates, retrying model discovery once, and honoring server retry delays ([#7850](https://github.com/earendil-works/pi/issues/7850)).
100
+ - Fixed inherited Amazon Bedrock dropping and failing to replay opaque redacted reasoning from non-Anthropic models ([#8314](https://github.com/earendil-works/pi/pull/8314) by [@seiji](https://github.com/seiji)).
101
+ - Fixed inherited Z.AI Coding Plan models deriving incomplete reasoning-effort metadata, including missing GLM-5.3 low, high, and max levels ([#8336](https://github.com/earendil-works/pi/issues/8336)).
102
+ - Fixed inherited DeepSeek V4 Flash on OpenCode and OpenCode Go omitting its supported low thinking level ([#8181](https://github.com/earendil-works/pi/pull/8181) by [@tianshuang](https://github.com/tianshuang)).
103
+ - Fixed inherited Azure OpenAI Responses ignoring `toolChoice` in provider-specific stream requests.
104
+ - Fixed inherited Amazon Bedrock response hooks receiving only a synthesized request id instead of the raw response headers ([#8234](https://github.com/earendil-works/pi/issues/8234)).
105
+ - Fixed inherited Kimi usage reporting so top-level `cached_tokens` count as cache reads instead of normal input tokens ([#8075](https://github.com/earendil-works/pi/issues/8075)).
106
+ - Fixed inherited Google custom models ignoring `thinkingLevelMap`, which dropped extended thinking controls ([#8135](https://github.com/earendil-works/pi/issues/8135)).
107
+ - Fixed writes to `auth.json` and `models-store.json` overriding administrator-managed file permissions and ACLs ([#7779](https://github.com/earendil-works/pi/issues/7779)).
108
+ - Fixed UTF-8 BOM markers preventing frontmatter and user configuration files from loading ([#8337](https://github.com/earendil-works/pi/issues/8337)).
109
+ - Fixed invalid settings files being easy to miss during interactive startup by rendering warnings with the file path inside the TUI ([#7829](https://github.com/earendil-works/pi/issues/7829)).
110
+ - Fixed the subagent example repeatedly prompting before running project-local agents in trusted repositories ([#8261](https://github.com/earendil-works/pi/issues/8261)).
111
+ - Added `session_compact_failed` extension events so compaction failures and aborts expose their reason, retry state, source, and error message to handlers ([#8175](https://github.com/earendil-works/pi/issues/8175)).
112
+ - Fixed truncated compaction and branch summaries being persisted when generation reaches its output token limit ([#7048](https://github.com/earendil-works/pi/issues/7048)).
113
+ - Fixed npm package update checks treating older registry versions as available updates, preventing `pi update` from downgrading already-newer installed packages ([#8226](https://github.com/earendil-works/pi/issues/8226)).
114
+ - Fixed built-in llama.cpp models disappearing from `/model` when `/llama` refreshed a configured server under `PI_OFFLINE`, and included idle-slept `sleeping` router models plus autoloadable unloaded presets in the selectable catalog ([#8558](https://github.com/earendil-works/pi/pull/8558) by [@cristinaponcela](https://github.com/cristinaponcela)).
115
+ - Fixed `pi.registerFlag()` accepting default values that do not match the declared flag type ([#8064](https://github.com/earendil-works/pi/issues/8064)).
116
+ - Fixed Z.AI Coding Plan defaults referencing the removed GLM-5.1 model ([#8096](https://github.com/earendil-works/pi/issues/8096)).
117
+ - Fixed repeated ambiguous truncated-response recovery being mislabeled as context overflow ([#8130](https://github.com/earendil-works/pi/issues/8130)).
118
+ - Fixed duplicate fullscreen right-click paste in VS Code-based terminals on Windows ([#8186](https://github.com/earendil-works/pi/issues/8186)).
119
+ - Fixed inherited padded text exceeding narrow terminal widths ([#8252](https://github.com/earendil-works/pi/issues/8252)).
120
+ - Fixed inherited wrapped Markdown table links leaking color into borders and neighboring cells, including tables inside blockquotes ([#8335](https://github.com/earendil-works/pi/issues/8335)).
121
+ - Fixed llama.cpp login guidance to direct users to `/llama` before `/model` when no local models are loaded ([#8203](https://github.com/earendil-works/pi/issues/8203)).
122
+ - Fixed hung pi.dev model catalog requests consuming the entire refresh deadline without retrying ([#8198](https://github.com/earendil-works/pi/issues/8198)).
123
+ - Fixed inherited Xiaomi model catalogs listing shut-down MiMo V2 models in `/model` and `--list-models` ([#8187](https://github.com/earendil-works/pi/issues/8187)).
124
+ - Fixed branch summary entries recording the navigation destination in `fromId` instead of the pre-navigation source leaf.
125
+ - Fixed threshold auto-compaction being skipped when providers omit streaming usage data ([#8328](https://github.com/earendil-works/pi/issues/8328)).
126
+ - Fixed dash-prefixed prompts being parsed as options by supporting `--` as an end-of-options delimiter ([#7269](https://github.com/earendil-works/pi/issues/7269)).
127
+
3
128
  ## [0.84.2] - 2026-08-14
4
129
 
5
130
  ### New Features
@@ -30,6 +155,8 @@
30
155
 
31
156
  ### Fixed
32
157
 
158
+ - Fixed root Markdown files such as `README.md` and `AGENTS.md` in skill directories being reported as broken skills unless they declare valid skill frontmatter ([#7805](https://github.com/earendil-works/pi/issues/7805)).
159
+ - Fixed single-object `edit` tool inputs failing validation by accepting them as one-edit arrays in both coding-agent and harness edit tools ([#7835](https://github.com/earendil-works/pi/issues/7835)).
33
160
  - Fixed managed-tool downloads delaying TUI startup and hiding diagnostics in fullscreen mode by mounting the TUI first and showing download progress and warnings inside it.
34
161
  - Fixed opening a model selector immediately after startup cancelling and restarting the in-progress model catalog refresh.
35
162
  - Fixed inherited GitHub Copilot login triggering API rate limits while enabling model policies by limiting concurrent policy updates ([#6187](https://github.com/earendil-works/pi/issues/6187)).
package/bin/README.md CHANGED
@@ -96,7 +96,7 @@ Then just talk to pi. By default, pi gives the model four tools: `read`, `write`
96
96
 
97
97
  ## Providers & Models
98
98
 
99
- For each built-in provider, pi maintains a list of tool-capable models. Configured provider catalogs refresh automatically; run `pi update --models` to force an immediate refresh. Authenticate via subscription (`/login`) or API key, then select any model from that provider via `/model` (or Ctrl+L).
99
+ For each built-in provider, pi maintains a list of tool-capable models. Configured provider catalogs refresh automatically; run `pi update --models` to force an immediate refresh. Authenticate via subscription (`/login`) or API key, then select any model from that provider via `/model` (or Ctrl+L). Press Ctrl+S in the model picker to save the highlighted model as the startup default.
100
100
 
101
101
  **Subscriptions:**
102
102
  - Anthropic Claude Pro/Max
@@ -178,9 +178,10 @@ Type `/` in the editor to trigger commands. [Extensions](#extensions) can regist
178
178
  |---------|-------------|
179
179
  | `/login`, `/logout` | Manage provider credentials |
180
180
  | [`/llama`](docs/llama-cpp.md) | Download, load, and unload llama.cpp router models |
181
- | `/model` | Switch models |
181
+ | `/model` | Switch models; Ctrl+S in the picker saves the startup default |
182
+ | `/thinking` | Switch thinking level; Ctrl+S in the picker saves the startup default |
182
183
  | `/scoped-models` | Enable/disable models for Ctrl+P cycling |
183
- | `/settings` | Thinking level, theme, message delivery, transport |
184
+ | `/settings` | Theme, message delivery, transport, and other preferences |
184
185
  | `/resume` | Pick from previous sessions |
185
186
  | `/new` | Start a new session |
186
187
  | `/name <name>` | Set session display name |
@@ -216,7 +217,7 @@ See `/hotkeys` for the full list. Customize via `~/.pi/agent/keybindings.json`.
216
217
  | Shift+Tab | Cycle thinking level |
217
218
  | Ctrl+O | Collapse/expand tool output |
218
219
  | Ctrl+T | Collapse/expand thinking blocks |
219
- | Ctrl+X | Copy the last assistant message |
220
+ | Ctrl+X | Copy the last assistant message; with fullscreen copy-on-select disabled, copy the active text selection |
220
221
 
221
222
  ### Message Queue
222
223
 
@@ -514,7 +515,7 @@ Read the [blog post](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/)
514
515
  ## CLI Reference
515
516
 
516
517
  ```bash
517
- pi [options] [@files...] [messages...]
518
+ pi [options] [--] [@files...] [messages...]
518
519
  ```
519
520
 
520
521
  ### Package Commands
@@ -584,7 +585,7 @@ cat README.md | pi -p "Summarize this text"
584
585
  | `--no-builtin-tools`, `-nbt` | Disable built-in tools by default but keep extension/custom tools enabled |
585
586
  | `--no-tools`, `-nt` | Disable all tools by default |
586
587
 
587
- Available built-in tools: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`
588
+ Available built-in tools: `read`, `bash`, `powershell` (Windows), `edit`, `write`, `grep`, `find`, `ls`
588
589
 
589
590
  ### Resource Options
590
591
 
@@ -613,6 +614,7 @@ Combine `--no-*` with explicit flags to load exactly what you need, ignoring set
613
614
  | `--verbose` | Force verbose startup |
614
615
  | `-a`, `--approve` | Trust project-local files for this run |
615
616
  | `-na`, `--no-approve` | Ignore project-local files for this run |
617
+ | `--` | Stop option parsing; remaining arguments are prompts or `@file` inputs |
616
618
  | `-h`, `--help` | Show help |
617
619
  | `-v`, `--version` | Show version |
618
620
 
@@ -635,6 +637,9 @@ pi "List all .ts files in src/"
635
637
  # Non-interactive
636
638
  pi -p "Summarize this codebase"
637
639
 
640
+ # Prompt beginning with a dash
641
+ pi -p -- "- Summarize these points"
642
+
638
643
  # Non-interactive with piped stdin
639
644
  cat README.md | pi -p "Summarize this text"
640
645
 
@@ -678,7 +683,7 @@ pi --thinking high "Solve this complex problem"
678
683
  | `PI_CACHE_RETENTION` | Set to `long` for extended prompt cache (Anthropic: 1h, OpenAI: 24h) |
679
684
  | `VISUAL`, `EDITOR` | Fallback external editor for Ctrl+G when `externalEditor` is unset; defaults to Notepad on Windows and `nano` elsewhere |
680
685
 
681
- Commands run by the LLM-callable bash tool also receive current session metadata:
686
+ Commands run by the LLM-callable `bash` and `powershell` tools also receive current session metadata:
682
687
 
683
688
  | Variable | Description |
684
689
  |----------|-------------|
@@ -688,7 +693,7 @@ Commands run by the LLM-callable bash tool also receive current session metadata
688
693
  | `PI_MODEL` | Currently selected model ID |
689
694
  | `PI_REASONING_LEVEL` | Current effective reasoning level |
690
695
 
691
- These values are resolved when each command starts. See [Environment Variables](docs/environment-variables.md#bash-tool-session-environment) for semantics, examples, and custom-tool opt-out.
696
+ These values are resolved when each command starts. See [Environment Variables](docs/environment-variables.md#shell-tool-session-environment) for semantics, examples, and custom-tool opt-out.
692
697
 
693
698
  ---
694
699
 
package/bin/docs/compaction.md CHANGED
@@ -34,6 +34,8 @@ contextTokens > contextWindow - reserveTokens
34
34
 
35
35
  By default, `reserveTokens` is 16384 tokens (configurable in `~/.pi/agent/settings.json` or `<project-dir>/.pi/settings.json`). This leaves room for the LLM's response.
36
36
 
37
+ During a multi-turn agent run, Pi checks this threshold after tools finish and their results are appended, before starting the next assistant response. If the threshold is crossed, Pi compacts inside the same agent run and resumes with the summary and retained messages. It skips this between-turn check when the completed tool batch terminates the run and no queued message requires another response. Pi also checks the threshold before a new user prompt and after a low-level agent run ends.
38
+
37
39
  You can also trigger manually with `/compact [instructions]`, where optional instructions focus the summary.
38
40
 
39
41
  ### How It Works
@@ -346,6 +348,21 @@ pi.on("session_before_compact", async (event, ctx) => {
346
348
 
347
349
  See [custom-compaction.ts](../examples/extensions/custom-compaction.ts) for a complete example using a different model.
348
350
 
351
+ ### session_compact_failed
352
+
353
+ Fired when manual or automatic compaction fails or is aborted. This is useful for telemetry extensions that need to pair `session_before_compact` attempts with terminal outcomes.
354
+
355
+ ```typescript
356
+ pi.on("session_compact_failed", async (event, ctx) => {
357
+ const { reason, errorMessage, aborted, willRetry, fromExtension } = event;
358
+ // reason - "manual" (/compact), "threshold", or "overflow"
359
+ // errorMessage - present for non-abort failures
360
+ // aborted - true for cancelled/aborted compactions
361
+ // willRetry - whether the aborted turn would have retried after compaction
362
+ // fromExtension - whether extension-provided compaction content was being used
363
+ });
364
+ ```
365
+
349
366
  ### session_before_tree
350
367
 
351
368
  Fired before `/tree` navigation. Always fires regardless of whether user chose to summarize. Can cancel navigation or provide custom summary.
package/bin/docs/custom-provider.md CHANGED
@@ -394,15 +394,15 @@ interface OAuthCredentials {
394
394
 
395
395
  ## Custom Streaming API
396
396
 
397
- For providers with non-standard APIs, implement `streamSimple`. Study the existing provider implementations before writing your own:
397
+ For providers with non-standard APIs, implement `streamSimple`. Study the existing API implementations before writing your own:
398
398
 
399
399
  **Reference implementations:**
400
- - [anthropic.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/providers/anthropic.ts) - Anthropic Messages API
401
- - [mistral.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/providers/mistral.ts) - Mistral Conversations API
402
- - [openai-completions.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/providers/openai-completions.ts) - OpenAI Chat Completions
403
- - [openai-responses.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/providers/openai-responses.ts) - OpenAI Responses API
404
- - [google.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/providers/google.ts) - Google Generative AI
405
- - [amazon-bedrock.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/providers/amazon-bedrock.ts) - AWS Bedrock
400
+ - [anthropic-messages.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/api/anthropic-messages.ts) - Anthropic Messages API
401
+ - [mistral-conversations.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/api/mistral-conversations.ts) - Mistral Conversations API
402
+ - [openai-completions.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/api/openai-completions.ts) - OpenAI Chat Completions
403
+ - [openai-responses.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/api/openai-responses.ts) - OpenAI Responses API
404
+ - [google-generative-ai.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/api/google-generative-ai.ts) - Google Generative AI
405
+ - [bedrock-converse-stream.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/api/bedrock-converse-stream.ts) - AWS Bedrock
406
406
 
407
407
  ### Stream Pattern
408
408
 
@@ -752,8 +752,10 @@ interface ProviderModelConfig {
752
752
  requiresThinkingAsText?: boolean;
753
753
  requiresReasoningContentOnAssistantMessages?: boolean;
754
754
  thinkingFormat?: "openai" | "openrouter" | "deepseek" | "together" | "baseten" | "zai" | "qwen" | "chat-template" | "qwen-chat-template" | "string-thinking" | "ant-ling";
755
- chatTemplateKwargs?: Record<string, string | number | boolean | null | { "$var": "thinking.enabled" | "thinking.effort"; omitWhenOff?: boolean }>;
756
- chatTemplateArgs?: Record<string, string | number | boolean | null | { "$var": "thinking.enabled" | "thinking.effort"; omitWhenOff?: boolean }>;
755
+ chatTemplateKwargs?: Record<string, string | number | boolean | null | { "$var": "thinking.enabled" | "thinking.effort" | "thinking.budget"; omitWhenOff?: boolean }>;
756
+ chatTemplateArgs?: Record<string, string | number | boolean | null | { "$var": "thinking.enabled" | "thinking.effort" | "thinking.budget"; omitWhenOff?: boolean }>;
757
+ thinkingTokenBudgetField?: "thinking_token_budget" | "thinking_budget" | "thinking_budget_tokens";
758
+ supportsThinkingTokenBudget?: boolean;
757
759
  cacheControlFormat?: "anthropic";
758
760
  sessionAffinityFormat?: "openai" | "openai-nosession" | "openrouter";
759
761
  sendSessionAffinityHeaders?: boolean;
@@ -771,4 +773,5 @@ interface ProviderModelConfig {
771
773
  ```
772
774
 
773
775
  `openrouter` sends `reasoning: { effort }`. `deepseek` sends `thinking: { type: "enabled" | "disabled" }` and `reasoning_effort` when enabled. `together` sends `reasoning: { enabled }` and also `reasoning_effort` when `supportsReasoningEffort` is enabled. `qwen` is for DashScope-style top-level `enable_thinking`. Use `qwen-chat-template` for local Qwen-compatible servers that read `chat_template_kwargs.enable_thinking` and need `preserve_thinking`. Use `chat-template` for configurable `chat_template_kwargs`, for example DeepSeek V3.x behind vLLM with `chatTemplateKwargs: { "thinking": { "$var": "thinking.enabled" } }`. Use `thinkingFormat: "baseten"` with `chatTemplateArgs` when the provider expects toggle values under `chat_template_args` and optionally supports top-level `reasoning_effort`.
776
+ `thinkingTokenBudgetField` sends a clamped per-level thinking budget as a top-level request field (`thinking_token_budget` on vLLM, `thinking_budget` on Qwen/SGLang, `thinking_budget_tokens` on llama.cpp). `supportsThinkingTokenBudget: true` is an alias for the vLLM field name. Do not combine it with `reasoning_effort` on DashScope Qwen models.
774
777
  `cacheControlFormat: "anthropic"` applies Anthropic-style `cache_control` markers to the system prompt, last tool definition, and last user, assistant, or tool-result text content.
package/bin/docs/environment-variables.md CHANGED
@@ -4,7 +4,7 @@ Pi uses environment variables in three ways:
4
4
 
5
5
  - Variables such as `PI_OFFLINE` configure the Pi process.
6
6
  - Pi sets process markers so child processes can identify Pi as the launching agent.
7
- - Commands run by the LLM-callable bash tool receive `PI_*` variables describing the current session.
7
+ - Commands run by the LLM-callable shell tools receive `PI_*` variables describing the current session.
8
8
 
9
9
  Provider API-key variables are documented separately in [Providers](providers.md#environment-variables-or-auth-file).
10
10
 
@@ -17,9 +17,9 @@ The CLI and RPC entry points set two process markers:
17
17
 
18
18
  Child processes inherit both markers. They are not session-specific and are not set automatically when Pi is embedded through the SDK.
19
19
 
20
- ## Bash Tool Session Environment
20
+ ## Shell Tool Session Environment
21
21
 
22
- Commands run by the bash tool receive the current Pi session state:
22
+ Commands run by the `bash` and `powershell` tools receive the current Pi session state:
23
23
 
24
24
  | Variable | Description |
25
25
  |----------|-------------|
@@ -29,7 +29,7 @@ Commands run by the bash tool receive the current Pi session state:
29
29
  | `PI_MODEL` | Currently selected model ID |
30
30
  | `PI_REASONING_LEVEL` | Current effective reasoning level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` |
31
31
 
32
- The values are resolved when each command starts. Switching models or changing the reasoning level therefore affects the next bash command without restarting Pi. `PI_PROVIDER` and `PI_MODEL` identify the selected Pi model, not a different upstream model that a router may choose internally.
32
+ The values are resolved when each command starts. Switching models or changing the reasoning level therefore affects the next shell command without restarting Pi. `PI_PROVIDER` and `PI_MODEL` identify the selected Pi model, not a different upstream model that a router may choose internally.
33
33
 
34
34
  When asked which model or provider is running, inspect these variables instead of inferring the answer from the system prompt:
35
35
 
@@ -46,11 +46,11 @@ if [ -n "$PI_SESSION_FILE" ]; then
46
46
  fi
47
47
  ```
48
48
 
49
- These variables are injected into the LLM-callable bash tool. They are not injected into user-entered `!` or `!!` commands.
49
+ These variables are injected into the LLM-callable `bash` and `powershell` tools. They are not injected into user-entered `!` or `!!` commands.
50
50
 
51
- ### Custom Bash Tools
51
+ ### Custom Shell Tools
52
52
 
53
- Bash tools created with `createBashTool()` expose the session environment by default when registered with Pi. Injection happens before `spawnHook`, so a hook receives the variables in `ctx.env`:
53
+ Tools created with `createBashTool()` or `createPowerShellTool()` expose the session environment by default when registered with Pi. Injection happens before `spawnHook`, so a hook receives the variables in `ctx.env`:
54
54
 
55
55
  ```typescript
56
56
  const bashTool = createBashTool(cwd, {
@@ -64,7 +64,7 @@ const bashTool = createBashTool(cwd, {
64
64
  Disable session metadata independently of the spawn hook:
65
65
 
66
66
  ```typescript
67
- const bashTool = createBashTool(cwd, {
67
+ const powershellTool = createPowerShellTool(cwd, {
68
68
  exposeSessionEnvironment: false,
69
69
  spawnHook: (ctx) => ctx,
70
70
  });
@@ -87,6 +87,9 @@ These variables are read by Pi itself:
87
87
  | `PI_CACHE_RETENTION` | Set to `long` for extended provider prompt caching where supported |
88
88
  | `PI_SHARE_VIEWER_URL` | Override the base URL used by `/share` |
89
89
  | `PI_HARDWARE_CURSOR` | Set to `1` to show the hardware cursor; see [Terminal setup](terminal-setup.md) |
90
+ | `PI_HYPERLINKS` | Override OSC 8 hyperlink detection with `1`, `0`, or `auto` |
91
+ | `PI_IMAGE_PROTOCOL` | Override inline image detection with `kitty`, `iterm2`, `none`, or `auto` |
92
+ | `PI_TRUE_COLOR` | Override truecolor detection with `1`, `0`, or `auto` |
90
93
  | `PI_TUI_ESC_TIMEOUT` | How long to wait after a lone ESC before treating it as Escape, in milliseconds; defaults to `100` over SSH and `10` otherwise. Increase if Alt-key input is misread as Escape |
91
94
  | `VISUAL`, `EDITOR` | External editor fallback when `externalEditor` is unset |
92
95
  | `HTTP_PROXY`, `HTTPS_PROXY` | Proxy outbound HTTP requests |
package/bin/docs/extensions.md CHANGED
@@ -330,7 +330,8 @@ user sends another prompt ◄─────────────────
330
330
 
331
331
  /compact or auto-compaction
332
332
  ├─► session_before_compact (can cancel or customize)
333
- └─► session_compact
333
+ ├─► session_compact (success)
334
+ └─► session_compact_failed (failure or abort)
334
335
 
335
336
  /tree navigation
336
337
  ├─► session_before_tree (can cancel or customize)
@@ -448,7 +449,7 @@ pi.on("session_before_fork", async (event, ctx) => {
448
449
  After a successful fork or clone, pi emits `session_shutdown` for the old extension instance, reloads and rebinds extensions for the new session, then emits `session_start` with `reason: "fork"` and `previousSessionFile`.
449
450
  Do cleanup work in `session_shutdown`, then reestablish any in-memory state in `session_start`.
450
451
 
451
- #### session_before_compact / session_compact
452
+ #### session_before_compact / session_compact / session_compact_failed
452
453
 
453
454
  Fired on compaction. See [compaction.md](compaction.md) for details.
454
455
 
@@ -479,6 +480,14 @@ pi.on("session_compact", async (event, ctx) => {
479
480
  // event.reason - "manual" (/compact), "threshold", or "overflow"
480
481
  // event.willRetry - whether the aborted turn is retried after compaction (overflow recovery)
481
482
  });
483
+
484
+ pi.on("session_compact_failed", async (event, ctx) => {
485
+ // event.reason - "manual" (/compact), "threshold", or "overflow"
486
+ // event.errorMessage - present for non-abort failures
487
+ // event.aborted - true for cancelled/aborted compactions
488
+ // event.willRetry - whether the aborted turn would have retried after compaction
489
+ // event.fromExtension - whether extension-provided compaction content was being used
490
+ });
482
491
  ```
483
492
 
484
493
  #### session_before_tree / session_tree
@@ -571,6 +580,24 @@ pi.on("agent_settled", async (_event, ctx) => {
571
580
  });
572
581
  ```
573
582
 
583
+ #### ui_prompt_start / ui_prompt_end
584
+
585
+ Notification-only lifecycle events for blocking user-facing extension UI prompts. They fire around `ctx.ui.select()`, `ctx.ui.confirm()`, `ctx.ui.input()`, `ctx.ui.editor()`, and `ctx.ui.custom()` so host/status integrations can report "waiting for user" instead of just "running".
586
+
587
+ Nested or overlapping prompts are coalesced into one outer waiting span. Handlers are invoked best-effort and are not awaited before showing or closing the prompt.
588
+
589
+ ```typescript
590
+ pi.on("ui_prompt_start", async (event, ctx) => {
591
+ // event.reason === "ui_prompt"
592
+ // event.kind: "select" | "confirm" | "input" | "editor" | "custom"
593
+ // event.title: prompt title when available
594
+ });
595
+
596
+ pi.on("ui_prompt_end", async (event, ctx) => {
597
+ // Pi is no longer waiting on that UI prompt span.
598
+ });
599
+ ```
600
+
574
601
  #### turn_start / turn_end
575
602
 
576
603
  Fired for each turn (one LLM response + tool calls).
@@ -2050,7 +2077,7 @@ pi.registerTool({
2050
2077
 
2051
2078
  ### Overriding Built-in Tools
2052
2079
 
2053
- Extensions can override built-in tools (`read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`) by registering a tool with the same name. Interactive mode displays a warning when this happens.
2080
+ Extensions can override built-in tools (`read`, `bash`, `powershell`, `edit`, `write`, `grep`, `find`, `ls`) by registering a tool with the same name. Interactive mode displays a warning when this happens.
2054
2081
 
2055
2082
  ```bash
2056
2083
  # Extension's read tool replaces built-in read
@@ -2074,6 +2101,7 @@ See [examples/extensions/tool-override.ts](../examples/extensions/tool-override.
2074
2101
  Built-in tool implementations:
2075
2102
  - [read.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/read.ts) - `ReadToolDetails`
2076
2103
  - [bash.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/bash.ts) - `BashToolDetails`
2104
+ - [powershell.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/powershell.ts) - `PowerShellToolDetails`
2077
2105
  - [edit.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/edit.ts)
2078
2106
  - [write.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/write.ts)
2079
2107
  - [grep.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/grep.ts) - `GrepToolDetails`
@@ -2109,11 +2137,11 @@ pi.registerTool({
2109
2137
  });
2110
2138
  ```
2111
2139
 
2112
- **Operations interfaces:** `ReadOperations`, `WriteOperations`, `EditOperations`, `BashOperations`, `LsOperations`, `GrepOperations`, `FindOperations`
2140
+ **Operations interfaces:** `ReadOperations`, `WriteOperations`, `EditOperations`, `BashOperations`, `PowerShellOperations`, `LsOperations`, `GrepOperations`, `FindOperations`
2113
2141
 
2114
2142
  For `user_bash`, extensions can reuse pi's local shell backend via `createLocalBashOperations()` instead of reimplementing local process spawning, shell resolution, and process-tree termination.
2115
2143
 
2116
- The bash tool also supports a spawn hook to adjust the command, cwd, or env before execution:
2144
+ The `bash` and `powershell` tools also support a spawn hook to adjust the command, cwd, or env before execution:
2117
2145
 
2118
2146
  ```typescript
2119
2147
  import { createBashTool } from "@earendil-works/pi-coding-agent";
@@ -2127,7 +2155,7 @@ const bashTool = createBashTool(cwd, {
2127
2155
  });
2128
2156
  ```
2129
2157
 
2130
- `createBashTool()` exposes the current session to commands through `PI_SESSION_ID`, `PI_SESSION_FILE`, `PI_PROVIDER`, `PI_MODEL`, and `PI_REASONING_LEVEL`. Injection happens before `spawnHook`, so hooks receive these values in `env` and preserve them when they spread the existing environment as above. Set `exposeSessionEnvironment: false` to disable them:
2158
+ `createBashTool()` and `createPowerShellTool()` expose the current session to commands through `PI_SESSION_ID`, `PI_SESSION_FILE`, `PI_PROVIDER`, `PI_MODEL`, and `PI_REASONING_LEVEL`. Injection happens before `spawnHook`, so hooks receive these values in `env` and preserve them when they spread the existing environment as above. Set `exposeSessionEnvironment: false` to disable them:
2131
2159
 
2132
2160
  ```typescript
2133
2161
  const bashTool = createBashTool(cwd, {
@@ -2135,7 +2163,7 @@ const bashTool = createBashTool(cwd, {
2135
2163
  });
2136
2164
  ```
2137
2165
 
2138
- See [Bash tool session environment](environment-variables.md#bash-tool-session-environment) for variable semantics. See [examples/extensions/ssh.ts](../examples/extensions/ssh.ts) for a complete SSH example with `--ssh` flag.
2166
+ See [Shell tool session environment](environment-variables.md#shell-tool-session-environment) for variable semantics. See [examples/extensions/ssh.ts](../examples/extensions/ssh.ts) for a complete SSH example with `--ssh` flag.
2139
2167
 
2140
2168
  ### Output Truncation
2141
2169
 
package/bin/docs/json.md CHANGED
@@ -15,12 +15,16 @@ except that streaming message updates omit cumulative snapshots:
15
15
  ```typescript
16
16
  type WithoutPartial<T> = T extends { partial: unknown } ? Omit<T, "partial"> : T;
17
17
 
18
+ type JsonAssistantMessageEvent<T> = T extends { type: "toolcall_start"; partial: unknown }
19
+ ? WithoutPartial<T> & { id: string; toolName: string }
20
+ : WithoutPartial<T>;
21
+
18
22
  type JsonAgentSessionEvent =
19
23
  | Exclude<AgentSessionEvent, { type: "message_update" }>
20
24
  | {
21
25
  type: "message_update";
22
26
  usage: Usage;
23
- assistantMessageEvent: WithoutPartial<AssistantMessageEvent>;
27
+ assistantMessageEvent: JsonAssistantMessageEvent<AssistantMessageEvent>;
24
28
  };
25
29
  ```
26
30
 
@@ -84,7 +88,8 @@ Followed by events as they occur:
84
88
  `assistantMessageEvent.partial` to keep stream size linear. The top-level `usage` field contains
85
89
  the latest cumulative provider-reported usage and may remain zero when a provider only reports
86
90
  usage at completion. Use `contentIndex` and `delta` to assemble live text, thinking, or tool-call
87
- arguments if needed. `message_end` contains the final authoritative message.
91
+ arguments if needed. A `toolcall_start` event also includes the constant-sized `id` and `toolName`
92
+ fields. `message_end` contains the final authoritative message.
88
93
 
89
94
  ## Example
90
95
 
package/bin/docs/keybindings.md CHANGED
@@ -70,7 +70,7 @@ The dedicated history actions always change history entries, regardless of the c
70
70
  |--------|---------|-------------|
71
71
  | `tui.editor.yank` | `ctrl+y` | Paste most recently deleted text |
72
72
  | `tui.editor.yankPop` | `alt+y` | Cycle through deleted text after yank |
73
- | `tui.editor.undo` | `ctrl+-` | Undo last edit |
73
+ | `tui.editor.undo` | `ctrl+-` (`ctrl+z` on Windows; `alt+z` on WSL) | Undo last edit |
74
74
 
75
75
  ### TUI Clipboard and Selection
76
76
 
@@ -107,9 +107,9 @@ This routing remains configurable through the ordinary action bindings. For exam
107
107
  | `tui.altScreen.halfPageDown` | *(none)* | Scroll the transcript down by half a page |
108
108
  | `tui.altScreen.lineUp` | *(none)* | Scroll the transcript up by one line |
109
109
  | `tui.altScreen.lineDown` | *(none)* | Scroll the transcript down by one line |
110
- | `tui.altScreen.previousPrompt` | `ctrl+shift+up` | Jump to the previous marked message |
111
- | `tui.altScreen.nextPrompt` | `ctrl+shift+down` | Jump to the next marked message |
112
- | `tui.altScreen.search` | `ctrl+shift+f` | Search the rendered transcript |
110
+ | `tui.altScreen.previousPrompt` | `ctrl+shift+up`, `ctrl+up` (`ctrl+up` only on Windows and WSL) | Jump to the previous marked message |
111
+ | `tui.altScreen.nextPrompt` | `ctrl+shift+down`, `ctrl+down` (`ctrl+down` only on Windows and WSL) | Jump to the next marked message |
112
+ | `tui.altScreen.search` | `ctrl+shift+f` (`ctrl+f` on Windows and WSL) | Search the rendered transcript |
113
113
  | `tui.altScreen.searchNext` | `enter`, `ctrl+g` | Select the next search match while searching |
114
114
  | `tui.altScreen.searchPrevious` | `shift+enter`, `ctrl+shift+g` | Select the previous search match while searching |
115
115
  | `tui.altScreen.searchClose` | `escape` | Close transcript search |
@@ -125,7 +125,7 @@ This routing remains configurable through the ordinary action bindings. For exam
125
125
  | `app.exit` | `ctrl+d` | Exit (when editor empty) |
126
126
  | `app.suspend` | `ctrl+z` (none on Windows) | Suspend to background |
127
127
  | `app.editor.external` | `ctrl+g` | Open in external editor (`externalEditor`, `$VISUAL`, `$EDITOR`, Notepad on Windows, or `nano` elsewhere) |
128
- | `app.clipboard.pasteImage` | `ctrl+v` (`alt+v` on Windows) | Paste image or text from clipboard |
128
+ | `app.clipboard.pasteImage` | `ctrl+v` (`alt+v` on Windows and WSL) | Paste image or text from clipboard |
129
129
 
130
130
  ### Sessions
131
131
 
@@ -148,7 +148,7 @@ This routing remains configurable through the ordinary action bindings. For exam
148
148
  |--------|---------|-------------|
149
149
  | `app.model.select` | `ctrl+l` | Open model selector |
150
150
  | `app.model.cycleForward` | `ctrl+p` | Cycle to next model |
151
- | `app.model.cycleBackward` | `shift+ctrl+p` | Cycle to previous model |
151
+ | `app.model.cycleBackward` | `shift+ctrl+p` (`alt+p` on Windows and WSL) | Cycle to previous model |
152
152
  | `app.thinking.cycle` | `shift+tab` | Cycle thinking level |
153
153
  | `app.thinking.toggle` | `ctrl+t` | Collapse or expand thinking blocks |
154
154
 
@@ -157,9 +157,9 @@ This routing remains configurable through the ordinary action bindings. For exam
157
157
  | Keybinding id | Default | Description |
158
158
  |--------|---------|-------------|
159
159
  | `app.tools.expand` | `ctrl+o` | Collapse or expand tool output |
160
- | `app.message.copy` | `ctrl+x` | Copy the last assistant message, or the selected message in `/tree` |
161
- | `app.message.followUp` | `alt+enter` | Queue follow-up message |
162
- | `app.message.dequeue` | `alt+up` | Restore queued messages to editor |
160
+ | `app.message.copy` | `ctrl+x` | Copy the selected message in `/tree`; otherwise copy the last assistant message, or the active fullscreen text selection when `fullscreenCopyOnSelect` is disabled |
161
+ | `app.message.followUp` | `alt+enter` (`ctrl+q` on Windows and WSL) | Queue follow-up message |
162
+ | `app.message.dequeue` | `alt+up` (`alt+q` on Windows and WSL) | Restore queued messages to editor |
163
163
 
164
164
  ### Tree Navigation
165
165
 
package/bin/docs/llama-cpp.md CHANGED
@@ -53,6 +53,8 @@ Start Pi and configure the provider:
53
53
 
54
54
  Enter the router URL and optional API key. The default URL is `http://127.0.0.1:8080`.
55
55
 
56
+ If you start the router with `--no-models-autoload`, `/login llama.cpp` only stores the connection. Run `/llama` to load a model, then `/model` to select the loaded model for the current session.
57
+
56
58
  Environment variables can configure the same values without `/login`:
57
59
 
58
60
  ```bash
package/bin/docs/models.md CHANGED
@@ -254,6 +254,8 @@ Current behavior:
254
254
 
255
255
  Only OpenAI-compatible APIs apply it (`openai-completions`, `openai-responses`, `azure-openai-responses`); other APIs ignore it. Keys override pi's named request fields (for example a `temperature` key here beats the request-level temperature), so prefer it as the single source of sampling truth for a model. In `modelOverrides`, `samplingParams` merges per key with the base model's value.
256
256
 
257
+ A constant thinking-token cap can go here too, but it will not follow `thinkingBudgets` or leave room for the answer. Prefer `compat.thinkingTokenBudgetField` (or the `supportsThinkingTokenBudget` alias) for that.
258
+
257
259
  ### Thinking Level Map
258
260
 
259
261
  Use `thinkingLevelMap` on a model to describe model-specific thinking controls. Keys are pi thinking levels: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. Maps may contain holes; for example, a model can expose `high` and `max` without exposing `xhigh`.
@@ -467,8 +469,10 @@ For providers with partial OpenAI compatibility, use the `compat` field.
467
469
  | `requiresThinkingAsText` | Convert thinking blocks to plain text |
468
470
  | `requiresReasoningContentOnAssistantMessages` | Include empty `reasoning_content` on all replayed assistant messages when reasoning is enabled |
469
471
  | `thinkingFormat` | Use `reasoning_effort`, `openrouter`, `deepseek`, `together`, `baseten`, `zai`, `qwen`, `chat-template`, or `qwen-chat-template` thinking parameters |
470
- | `chatTemplateKwargs` | `chat_template_kwargs` values for `thinkingFormat: "chat-template"`; use `{ "$var": "thinking.enabled" }` or `{ "$var": "thinking.effort" }` for pi-controlled thinking values |
471
- | `chatTemplateArgs` | `chat_template_args` values for `thinkingFormat: "baseten"`; use `{ "$var": "thinking.enabled" }` or `{ "$var": "thinking.effort" }` for pi-controlled thinking values |
472
+ | `chatTemplateKwargs` | `chat_template_kwargs` values for `thinkingFormat: "chat-template"`; use `{ "$var": "thinking.enabled" }`, `{ "$var": "thinking.effort" }`, or `{ "$var": "thinking.budget" }` for pi-controlled thinking values |
473
+ | `chatTemplateArgs` | `chat_template_args` values for `thinkingFormat: "baseten"`; use `{ "$var": "thinking.enabled" }`, `{ "$var": "thinking.effort" }`, or `{ "$var": "thinking.budget" }` for pi-controlled thinking values |
474
+ | `thinkingTokenBudgetField` | Top-level request field used to cap reasoning tokens from `thinkingBudgets`, clamped so at least 1024 tokens remain for the answer. `"thinking_token_budget"` (vLLM), `"thinking_budget"` (Qwen/DashScope/SGLang), `"thinking_budget_tokens"` (llama.cpp). Off by default; not set on the generated catalog. |
475
+ | `supportsThinkingTokenBudget` | Alias for `thinkingTokenBudgetField: "thinking_token_budget"` (vLLM). Prefer `thinkingTokenBudgetField`. Default: `false`. |
472
476
  | `cacheControlFormat` | Use Anthropic-style `cache_control` markers on the system prompt, last tool definition, and last user, assistant, or tool-result text content. Currently only `anthropic` is supported. |
473
477
  | `sendSessionAffinityHeaders` | For `openai-completions`, send session-affinity headers from the session id when caching is enabled. Default: `false`. |
474
478
  | `sessionAffinityFormat` | For `openai-completions` and `openai-responses`, the session-affinity header format: `openai` sends `session_id`/`x-client-request-id` (completions also `x-session-affinity`), `openai-nosession` omits the underscore-containing `session_id` header, `openrouter` sends `x-session-id`. Does not affect the `prompt_cache_key` body param. Default: auto-detected. |
@@ -481,6 +485,8 @@ For providers with partial OpenAI compatibility, use the `compat` field.
481
485
 
482
486
  `openrouter` uses `reasoning: { effort }`. `together` uses `reasoning: { enabled }` and also `reasoning_effort` when `supportsReasoningEffort` is enabled. `qwen` uses top-level `enable_thinking`. Use `qwen-chat-template` for local Qwen-compatible servers that require `chat_template_kwargs.enable_thinking` and `preserve_thinking`. Use `chat-template` for vLLM/Hugging Face chat templates that need configurable `chat_template_kwargs`, such as `chatTemplateKwargs: { "thinking": { "$var": "thinking.enabled" } }` for DeepSeek V3.x templates. Use `thinkingFormat: "baseten"` with `chatTemplateArgs` for providers that expose toggle controls through `chat_template_args` and optionally support top-level `reasoning_effort`.
483
487
 
488
+ `thinkingTokenBudgetField` is independent of `thinkingFormat`. Do not enable it on the generated Qwen catalog: those models already send `reasoning_effort`, and DashScope rejects `thinking_budget` together with `reasoning_effort`.
489
+
484
490
  `cacheControlFormat: "anthropic"` is for OpenAI-compatible providers that expose Anthropic-style prompt caching through `cache_control` markers on text content and tool definitions.
485
491
 
486
492
  Example: