@kingingwang/pi-windows-x64 0.84.3 → 0.85.1

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 (41) hide show
  1. package/bin/CHANGELOG.md +117 -1
  2. package/bin/README.md +6 -5
  3. package/bin/docs/compaction.md +2 -0
  4. package/bin/docs/containerization.md +45 -0
  5. package/bin/docs/custom-provider.md +7 -7
  6. package/bin/docs/development.md +19 -0
  7. package/bin/docs/environment-variables.md +5 -0
  8. package/bin/docs/extensions.md +23 -2
  9. package/bin/docs/keybindings.md +6 -3
  10. package/bin/docs/models.md +4 -1
  11. package/bin/docs/quickstart.md +1 -1
  12. package/bin/docs/rpc.md +24 -1
  13. package/bin/docs/sdk.md +5 -0
  14. package/bin/docs/settings.md +17 -9
  15. package/bin/docs/skills.md +1 -1
  16. package/bin/docs/terminal-setup.md +27 -0
  17. package/bin/docs/themes.md +8 -6
  18. package/bin/docs/tui.md +20 -1
  19. package/bin/docs/usage.md +4 -3
  20. package/bin/examples/README.md +3 -0
  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/dynamic-resources/dynamic.json +2 -0
  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/sandbox/package-lock.json +2 -2
  28. package/bin/examples/extensions/sandbox/package.json +1 -1
  29. package/bin/examples/extensions/with-deps/package-lock.json +2 -2
  30. package/bin/examples/extensions/with-deps/package.json +1 -1
  31. package/bin/examples/plugins/pi-example-plugin/README.md +38 -0
  32. package/bin/examples/plugins/pi-example-plugin/package.json +10 -0
  33. package/bin/examples/plugins/pi-example-plugin/src/contract.ts +13 -0
  34. package/bin/examples/plugins/pi-example-plugin/src/session.ts +23 -0
  35. package/bin/examples/plugins/pi-example-plugin/src/tui.ts +31 -0
  36. package/bin/package.json +15 -8
  37. package/bin/pi.exe +0 -0
  38. package/bin/theme/dark.json +2 -1
  39. package/bin/theme/light.json +2 -1
  40. package/bin/theme/theme-schema.json +6 -2
  41. package/package.json +1 -1
package/bin/CHANGELOG.md CHANGED
@@ -1,5 +1,118 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.85.1] - 2026-09-05
4
+
5
+ ### New Features
6
+
7
+ - **GPT-6 Astra** — Available through OpenAI API keys and OpenAI Codex subscriptions. See [API Keys](docs/providers.md#api-keys) and [OpenAI Codex](docs/providers.md#openai-codex).
8
+
9
+ ### Added
10
+
11
+ - Added GPT-6 Astra for OpenAI API keys and OpenAI Codex subscriptions.
12
+ - Added five-times-faster mouse wheel scrolling while holding Alt in fullscreen mode ([#9166](https://github.com/earendil-works/pi/pull/9166) by [@xl0](https://github.com/xl0)).
13
+
14
+ ### Fixed
15
+
16
+ - Fixed configurable save keybindings in the model and thinking selectors ([#9149](https://github.com/earendil-works/pi/pull/9149) by [@rwachtler](https://github.com/rwachtler)).
17
+ - Fixed SDK import failures caused by unintentionally publishing internal experimental code and dependencies in 0.85.0. The experimental `client` and `experimental/plugin` subpaths and server/client commands are now source-only through `pi-test.sh`; the supported local SDK and stdio RPC API are unchanged ([#9132](https://github.com/earendil-works/pi/issues/9132)).
18
+ - Fixed mouse hover changing selection and recentering autocomplete and settings lists, causing clicks to target a different item.
19
+ - Fixed long prompt-cache requests for GPT-5.6+ Responses models to use `prompt_cache_options.ttl: "30m"` instead of `prompt_cache_retention: "24h"`.
20
+
21
+ ## [0.85.0] - 2026-09-04
22
+
23
+ ### New Features
24
+
25
+ - **Persistent Claude thinking effort** — Supported Anthropic transports preserve per-turn effort and recover safely from signed-thinking mismatches. See [Model Configuration](docs/models.md#model-configuration).
26
+ - **Fullscreen transcript controls** — Jump to the latest message from a scrolled transcript and use the embedded working indicator. See [TUI Fullscreen Viewport](docs/keybindings.md#tui-fullscreen-viewport).
27
+ - **Restorable in-memory sessions** — Resume externally stored session entries through the SDK. See [Session Management](docs/sdk.md#session-management).
28
+
29
+ ### Added
30
+
31
+ - Added `SessionManager.inMemory()` support for restoring externally managed session entries ([#8980](https://github.com/earendil-works/pi/pull/8980) by [@y-nk](https://github.com/y-nk)).
32
+ - Added inherited OpenAI-compatible `vllmPriority` and `supportsMaxOutputTokens` model settings for vLLM scheduler priority and OpenAI Responses output-token limits ([#9004](https://github.com/earendil-works/pi/pull/9004) by [@AppleDannyClegg](https://github.com/AppleDannyClegg), [#8941](https://github.com/earendil-works/pi/pull/8941) by [@scturtle](https://github.com/scturtle)).
33
+ - Added inherited LaTeX rendering for relational algebra join symbols ([#9050](https://github.com/earendil-works/pi/pull/9050) by [@haoqixu](https://github.com/haoqixu)).
34
+ - Added a clickable "Jump to latest message" label with the `tui.altScreen.bottom` shortcut to the fullscreen transcript while it is scrolled up ([#9080](https://github.com/earendil-works/pi/pull/9080) by [@rwachtler](https://github.com/rwachtler)).
35
+
36
+ ### Changed
37
+
38
+ - Moved the streaming working indicator into the default editor border and matched its default spinner and label to the thinking-level border color. Custom editors retain the standalone indicator unless they opt in to embedding it ([#8799](https://github.com/earendil-works/pi/pull/8799) by [@cristinaponcela](https://github.com/cristinaponcela)).
39
+ - Reduced inherited fullscreen transcript search latency on large transcripts by caching unchanged search results, indexing ASCII runs, and limiting highlight work to visible matches ([#8800](https://github.com/earendil-works/pi/pull/8800) by [@cristinaponcela](https://github.com/cristinaponcela)).
40
+
41
+ ### Fixed
42
+
43
+ - Fixed managed `fd` and ripgrep downloads on Linux musl systems ([#9070](https://github.com/earendil-works/pi/pull/9070) by [@Charlie0113-T](https://github.com/Charlie0113-T)).
44
+ - Removed the unavailable inherited Grok Build 0.1 model from `/model` ([#9093](https://github.com/earendil-works/pi/pull/9093) by [@Jaaneek](https://github.com/Jaaneek)).
45
+ - Fixed inherited provider streams emitting incompatible event sequences and custom tool-call deltas.
46
+ - Restored the `@earendil-works/pi-coding-agent/client` compatibility entry point.
47
+ - Fixed the inherited Qwen Token Plan Individual catalog to include Qwen3.8 Flash ([#9021](https://github.com/earendil-works/pi/issues/9021)).
48
+ - Fixed inherited OpenAI Codex SSE parsing to process terminal events that are not followed by a blank line ([#9047](https://github.com/earendil-works/pi/issues/9047)).
49
+ - Fixed inherited GitHub Copilot Claude Fable 5 requests so selected reasoning levels are sent ([#8961](https://github.com/earendil-works/pi/issues/8961)).
50
+ - Fixed inherited Baseten GLM-5.2 models incorrectly advertising image input support ([#8293](https://github.com/earendil-works/pi/pull/8293) by [@Panoplos](https://github.com/Panoplos)).
51
+ - Fixed skills being unavailable when Bash is the only enabled tool ([#8552](https://github.com/earendil-works/pi/pull/8552) by [@xl0](https://github.com/xl0)).
52
+ - Fixed concurrent session shares overwriting one another ([#8613](https://github.com/earendil-works/pi/pull/8613) by [@wutongyuonce](https://github.com/wutongyuonce)).
53
+ - Fixed image orientation detection skipping EXIF data after non-EXIF APP1 segments ([#8616](https://github.com/earendil-works/pi/pull/8616) by [@wutongyuonce](https://github.com/wutongyuonce)).
54
+ - Fixed imported sessions overwriting an existing session with the same filename ([#8985](https://github.com/earendil-works/pi/pull/8985) by [@wutongyuonce](https://github.com/wutongyuonce)).
55
+ - Fixed session forks losing their compaction boundary ([#8990](https://github.com/earendil-works/pi/pull/8990) by [@acmerfight](https://github.com/acmerfight)).
56
+ - Fixed in-memory session forks before an active turn settled ([#8937](https://github.com/earendil-works/pi/pull/8937) by [@acmerfight](https://github.com/acmerfight)).
57
+ - Fixed inherited Fireworks GLM models using the wrong API adapter.
58
+ - Fixed inherited `NO_PROXY` matching for root domains and subdomains ([#8737](https://github.com/earendil-works/pi/pull/8737) by [@MeiSiristhebest](https://github.com/MeiSiristhebest)).
59
+ - Fixed `bash`, `edit`, `find`, `grep`, `ls`, `read`, and `write` tools ignoring `ctx.cwd` ([#8627](https://github.com/earendil-works/pi/pull/8627) by [@vmizg](https://github.com/vmizg)).
60
+ - Fixed inherited terminal startup under restricted seccomp policies that reject the `SIGWINCH` self-signal ([#8898](https://github.com/earendil-works/pi/pull/8898) by [@bartlomiejkida](https://github.com/bartlomiejkida)).
61
+ - Fixed inherited Zed terminal image capability detection ([#8828](https://github.com/earendil-works/pi/pull/8828) by [@Perlence](https://github.com/Perlence)).
62
+ - Fixed drag selection continuing over the fullscreen editor.
63
+ - Fixed managed `fd` and ripgrep downloads requiring the GitHub Releases API ([#8708](https://github.com/earendil-works/pi/pull/8708) by [@Terminator666666](https://github.com/Terminator666666)).
64
+ - Fixed branch summaries failing when reasoning consumes the previous 2048-token output cap ([#8845](https://github.com/earendil-works/pi/issues/8845)).
65
+ - Fixed the write tool reporting UTF-16 code-unit counts as byte counts by removing the misleading count ([#8979](https://github.com/earendil-works/pi/issues/8979)).
66
+ - Fixed proxied plain-HTTP provider requests hanging after a tool call by tunneling them with CONNECT ([#8134](https://github.com/earendil-works/pi/issues/8134)).
67
+ - Fixed RPC `abort` reporting success without cancelling an in-progress manual compaction ([#8920](https://github.com/earendil-works/pi/issues/8920)).
68
+
69
+ ## [0.84.4] - 2026-08-28
70
+
71
+ ### New Features
72
+
73
+ - **Terminal capability overrides** — Override detected terminal hyperlink, image, and truecolor support. See [Capability Overrides](docs/terminal-setup.md#capability-overrides).
74
+ - **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).
75
+ - **RPC queue clearing** — Retrieve and clear queued steering and follow-up messages with `clear_queue`. See [RPC `clear_queue`](docs/rpc.md#clear_queue).
76
+ - **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).
77
+ - **DeepSeek V4 Flash Vision (experimental)** — Use the vision-capable model through the built-in DeepSeek provider. See [API Keys](docs/providers.md#api-keys).
78
+
79
+ ### Added
80
+
81
+ - Added `supportsMidConvoEffort` to custom Anthropic Messages model compatibility settings.
82
+ - Added transcript notices for Anthropic thinking blocks dropped during provider recovery when cache miss notices are enabled.
83
+ - 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)).
84
+ - Added `detectSupportedImageMimeTypeFromFile()` to the public library exports ([#8600](https://github.com/earendil-works/pi/pull/8600) by [@xl0](https://github.com/xl0)).
85
+ - Added inherited experimental vision-capable `deepseek-v4-flash-vision-exp` model support.
86
+ - Added transcript usage notices for compaction and branch summaries when cache miss notices are enabled.
87
+ - Added RPC `clear_queue` to retrieve and remove queued steering and follow-up messages ([#8432](https://github.com/earendil-works/pi/issues/8432)).
88
+ - 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)).
89
+ - 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)).
90
+
91
+ ### Changed
92
+ - Changed fullscreen scrollbars to reveal on pointer entry, support optional `scrollbarTrack` and `scrollbarThumb` theme colors with muted and text fallbacks, keep one thumb color across normal and expanded states, and support track-click jumping.
93
+ - Changed fullscreen transcript search arrows to underline on hover and capitalized the search placeholder.
94
+ - Changed selectors in `/thinking`, `/model`, `/scoped-models`, `/trust`, per-model thinking settings, and theme settings to keep active options marked while browsing. `/scoped-models` now uses consistent per-item toggles and strikes through unavailable models ([#8900](https://github.com/earendil-works/pi/pull/8900)).
95
+
96
+ ### Fixed
97
+
98
+ - Fixed toggling thinking visibility clearing partial output from running Bash tools ([#8611](https://github.com/earendil-works/pi/issues/8611)).
99
+ - Fixed Windows shell aborts crashing Pi when `taskkill.exe` is unavailable on `PATH` ([#6596](https://github.com/earendil-works/pi/issues/6596)).
100
+ - 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)).
101
+ - 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)).
102
+ - 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)).
103
+ - 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)).
104
+ - 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)).
105
+ - Fixed saving a default model from a non-empty model scope so it remains available in that scope.
106
+ - 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)).
107
+ - Fixed inherited OpenAI-compatible streams serializing thinking signatures repeatedly during streaming ([#8671](https://github.com/earendil-works/pi/pull/8671)).
108
+ - 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)).
109
+ - Fixed inherited fullscreen double-click word selection splitting paths and kebab-case tokens on `/` and `-` ([#8676](https://github.com/earendil-works/pi/pull/8676)).
110
+ - Fixed inherited Cloudflare AI Gateway catalogs omitting supported `workers-ai/*` passthrough models.
111
+ - Fixed inherited OpenAI-compatible reasoning replay to merge consecutive streamed text and summary `reasoning_details` deltas.
112
+ - 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)).
113
+ - Fixed inherited OpenAI-compatible Chat Completions ignoring an explicitly requested `toolChoice` when no tools are defined.
114
+ - Fixed inherited fragmented Mistral tool calls splitting when continuation chunks omit the tool-call ID ([#8387](https://github.com/earendil-works/pi/issues/8387)).
115
+
3
116
  ## [0.84.3] - 2026-08-24
4
117
 
5
118
  ### New Features
@@ -64,8 +177,10 @@
64
177
  - Fixed UTF-8 BOM markers preventing frontmatter and user configuration files from loading ([#8337](https://github.com/earendil-works/pi/issues/8337)).
65
178
  - 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)).
66
179
  - Fixed the subagent example repeatedly prompting before running project-local agents in trusted repositories ([#8261](https://github.com/earendil-works/pi/issues/8261)).
180
+ - 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)).
181
+ - Fixed truncated compaction and branch summaries being persisted when generation reaches its output token limit ([#7048](https://github.com/earendil-works/pi/issues/7048)).
67
182
  - 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)).
68
- - 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 in the selectable catalog ([#8167](https://github.com/earendil-works/pi/issues/8167)).
183
+ - 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)).
69
184
  - Fixed `pi.registerFlag()` accepting default values that do not match the declared flag type ([#8064](https://github.com/earendil-works/pi/issues/8064)).
70
185
  - Fixed Z.AI Coding Plan defaults referencing the removed GLM-5.1 model ([#8096](https://github.com/earendil-works/pi/issues/8096)).
71
186
  - Fixed repeated ambiguous truncated-response recovery being mislabeled as context overflow ([#8130](https://github.com/earendil-works/pi/issues/8130)).
@@ -89,6 +204,7 @@
89
204
 
90
205
  ### Added
91
206
 
207
+ - Added per-block fullscreen mouse expansion for thinking sections and tool results, while preserving drag selection and link activation.
92
208
  - Added fullscreen transcript search with `Ctrl+Shift+F`, incremental match highlighting, configurable search match theme colors, and next/previous navigation with `Enter`/`Ctrl+G` and `Shift+Enter`/`Ctrl+Shift+G`.
93
209
  - Added experimental strict JSON-schema constrained sampling for the default `read`, `bash`, `edit`, and `write` tools under `PI_EXPERIMENTAL=1`.
94
210
  - Added a fullscreen exit output setting to choose between printing the final transcript and only a session resume hint.
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
@@ -152,7 +152,7 @@ The interface from top to bottom:
152
152
 
153
153
  - **Startup header** - Shows shortcuts (`/hotkeys` for all), loaded AGENTS.md files, prompt templates, skills, and extensions
154
154
  - **Messages** - Your messages, assistant responses, tool calls and results, notifications, errors, and extension UI
155
- - **Editor** - Where you type; border color indicates thinking level
155
+ - **Editor** - Where you type; border color indicates thinking level and the border shows the streaming working indicator
156
156
  - **Footer** - Working directory, session name, total token/cache usage (`↑` input, `↓` output, `R` cache read, `W` cache write, `CH` latest cache hit rate), cost, context usage, current model. Totals include assistant responses, usage reported by tools, and summary generation.
157
157
 
158
158
  The editor can be temporarily replaced by other UI, like built-in `/settings` or custom UI from extensions (e.g., a Q&A tool that lets the user answer model questions in a structured format). [Extensions](#extensions) can also replace the editor, add widgets above/below it, a status line, custom footer, or overlays.
@@ -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
 
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
package/bin/docs/containerization.md CHANGED
@@ -13,6 +13,7 @@ There are two general options. You can either
13
13
  | Gondolin extension | Built-in tools and `!` commands | Local micro-VM isolation while keeping auth on host | See [`examples/extensions/gondolin/`](../examples/extensions/gondolin/). |
14
14
  | Plain Docker | Whole `pi` process in a local container | Simple local isolation | Provider API keys enter the container. |
15
15
  | OpenShell | Whole `pi` process in a policy-controlled sandbox | Local or remote managed sandbox | Requires an OpenShell gateway |
16
+ | Docker Sandboxes | Whole `pi` process in a managed sandbox | Local isolation with provider keys kept on the host | Requires Docker Sandboxes (`sbx`). |
16
17
 
17
18
  Extensions run wherever the `pi` process runs. If you run host `pi` with a tool-routing extension, other custom extension tools still run on the host unless they also delegate their operations.
18
19
 
@@ -109,3 +110,47 @@ openshell sandbox download pi-sandbox /workspace/repo ./repo-out
109
110
  OpenShell providers can keep raw model API keys outside the sandbox.
110
111
  When inference routing is configured, code inside the sandbox can call `https://inference.local`, and the gateway injects the configured provider credentials upstream.
111
112
  Configure Pi to use the corresponding OpenAI-compatible or Anthropic-compatible endpoint if you want model traffic to use this route.
113
+
114
+ ## Docker Sandboxes
115
+
116
+ [Docker Sandboxes](https://docs.docker.com/ai/sandboxes/) is a managed sandbox runtime from Docker that runs the whole `pi` process inside a sandbox.
117
+ It is one of the container boundaries [No Built-in Sandbox](security.md#no-built-in-sandbox) points to.
118
+
119
+ Unlike the Plain Docker pattern above, the provider credential is not passed into the container.
120
+ The sandbox receives a sentinel value instead, and the `sbx` proxy substitutes the real credential on egress to `api.anthropic.com`.
121
+ Credentials are wired at creation time, so store yours on the host before you create the sandbox.
122
+
123
+ For a Claude Pro/Max subscription, run `claude setup-token` on a machine with Claude Code, then store the result on the host.
124
+ If an `anthropic` secret is already bound, remove it first: otherwise the proxy adds an `x-api-key` header alongside the Bearer token and Anthropic rejects the request.
125
+ `sbx secret set-custom` reads the token from stdin, so it stays out of shell history.
126
+
127
+ ```bash
128
+ sbx secret rm anthropic
129
+
130
+ sbx secret set-custom \
131
+ --host api.anthropic.com \
132
+ --env ANTHROPIC_OAUTH_TOKEN \
133
+ --placeholder 'sk-ant-oat01-{rand}'
134
+ ```
135
+
136
+ The sandbox gets an OAuth-shaped placeholder, not the real token, and the proxy swaps it on egress to that host; `ANTHROPIC_OAUTH_TOKEN` is a variable pi already reads and prefers over an API key, so no extra pi configuration is needed.
137
+
138
+ For an API key, store it with `sbx secret set anthropic` instead. The kit wires it the same way, as a sentinel the proxy substitutes on egress.
139
+
140
+ With the credential stored, launch `pi` from the project you want mounted:
141
+
142
+ ```bash
143
+ sbx run --kit "docker.io/sbx/pi-kit:latest" pi
144
+ ```
145
+
146
+ The kit pre-bakes `pi` into its image, so the sandbox starts without installing anything, and the current directory is the sandbox workspace.
147
+
148
+ Do not authenticate from inside the sandbox: `/login` there writes a real token into the container and defeats the proxy model.
149
+
150
+ Scripted use works the same way:
151
+
152
+ ```bash
153
+ sbx exec <sandbox-name> -- pi -p "list the failing tests"
154
+ ```
155
+
156
+ See the [kit documentation](https://github.com/docker/sbx-kits-contrib/tree/main/pi) for the full credential matrix, troubleshooting, and pinning.
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
 
package/bin/docs/development.md CHANGED
@@ -19,6 +19,19 @@ Run from source:
19
19
 
20
20
  The script can be run from any directory. Pi keeps the caller's current working directory.
21
21
 
22
+ ### Experimental remote harness
23
+
24
+ The remote harness server/client integration is development-only. Run it from the repository with:
25
+
26
+ ```bash
27
+ PI_EXPERIMENTAL=1 ./pi-test.sh server
28
+ PI_EXPERIMENTAL=1 ./pi-test.sh client
29
+ ```
30
+
31
+ `PI_SERVER_DIR` overrides the server profile and socket directory (default: `~/.pi/server`). `PI_SERVER_ID` selects the logical server ID when `--server-id` is omitted.
32
+
33
+ The `client` and `experimental/plugin` package subpaths resolve only under the `source` condition in a checkout. Their implementations and the server/client commands are excluded from npm packages and standalone binaries. `pi-client`, `pi-protocol`, and `pi-server` are development dependencies of coding-agent, not runtime dependencies. The local SDK and stdio RPC API are unchanged.
34
+
22
35
  ## Forking / Rebranding
23
36
 
24
37
  Configure via `package.json`:
@@ -60,6 +73,12 @@ npm test # Run all tests
60
73
  npm test -- test/specific.test.ts # Run specific test
61
74
  ```
62
75
 
76
+ ### Published package smoke test
77
+
78
+ After building, run `npm run check:package-install`. It packs the public packages and installs only coding-agent as a direct dependency in a temporary directory outside the repository. Local tarball overrides select declared transitive dependencies without installing development-only packages. The check verifies SDK imports and CLI startup without credentials or model requests.
79
+
80
+ `npm run check` also checks runtime dependency declarations and rejects excluded development sources pulled into a package's build through imports.
81
+
63
82
  ## Project Structure
64
83
 
65
84
  ```
package/bin/docs/environment-variables.md CHANGED
@@ -87,8 +87,13 @@ 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 |
93
96
 
94
97
  Provider credentials such as `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and cloud-provider configuration are listed in [Providers](providers.md#environment-variables-or-auth-file).
98
+
99
+ `PI_SERVER_DIR` and `PI_SERVER_ID` apply only to the source-only [experimental remote harness](development.md#experimental-remote-harness), not distributed builds.
package/bin/docs/extensions.md CHANGED
@@ -580,6 +580,24 @@ pi.on("agent_settled", async (_event, ctx) => {
580
580
  });
581
581
  ```
582
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
+
583
601
  #### turn_start / turn_end
584
602
 
585
603
  Fired for each turn (one LLM response + tool calls).
@@ -1685,7 +1703,7 @@ Typical `sourceInfo.source` values:
1685
1703
 
1686
1704
  ### pi.setModel(model)
1687
1705
 
1688
- Set the current model. Returns `false` if no API key is available for the model. See [models.md](models.md) for configuring custom models.
1706
+ Set the model for the current session. The change is recorded in session history and restored when that session is resumed, but it does not change the configured `defaultProvider` or `defaultModel` used by new sessions. Returns `false` if authentication is not configured for the model's provider. See [models.md](models.md) for configuring custom models.
1689
1707
 
1690
1708
  ```typescript
1691
1709
  const model = ctx.modelRegistry.find("anthropic", "claude-sonnet-4-5");
@@ -1699,7 +1717,9 @@ if (model) {
1699
1717
 
1700
1718
  ### pi.getThinkingLevel() / pi.setThinkingLevel(level)
1701
1719
 
1702
- Get or set the thinking level. Level is clamped to model capabilities (non-reasoning models always use "off"). Changes emit `thinking_level_select`.
1720
+ Get the current thinking level. Level is clamped to model capabilities (non-reasoning models always use "off"). Changes emit `thinking_level_select`.
1721
+
1722
+ `pi.setThinkingLevel()` changes the thinking level for the current session. The change is recorded in session history and restored when that session is resumed, but it does not change the configured default used by new sessions.
1703
1723
 
1704
1724
  ```typescript
1705
1725
  const current = pi.getThinkingLevel(); // "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max"
@@ -2809,6 +2829,7 @@ export default function (pi: ExtensionAPI) {
2809
2829
  **Key points:**
2810
2830
  - Extend `CustomEditor` (not base `Editor`) to get app keybindings (escape to abort, ctrl+d, model switching)
2811
2831
  - Call `super.handleInput(data)` for keys you don't handle
2832
+ - Custom editors keep the standalone working row by default. Pass `{ embedWorkingStatus: true }` as the fourth `CustomEditor` constructor argument to use the built-in editor-border spinner instead.
2812
2833
  - Factory receives `tui`, `theme`, and `keybindings` from the app
2813
2834
  - Use `ctx.ui.getEditorComponent()` before `setEditorComponent()` to wrap the previously configured custom editor
2814
2835
  - Pass `undefined` to restore default: `ctx.ui.setEditorComponent(undefined)`
package/bin/docs/keybindings.md CHANGED
@@ -86,10 +86,12 @@ The dedicated history actions always change history entries, regardless of the c
86
86
 
87
87
  ### TUI Fullscreen Viewport
88
88
 
89
- These actions apply when interactive mode uses `--tui-mode fullscreen` and target the primary transcript scroll region. Two-finger trackpad and mouse-wheel input scroll the region under the pointer, falling back to the transcript over the fixed editor/status/footer dock. Clicking an OSC 8 hyperlink opens it in the default handler. Dragging with the primary mouse button selects text and copies it to the clipboard; holding at the transcript's top or bottom edge auto-scrolls into off-screen content. See [Terminal setup](terminal-setup.md) for terminal-specific mouse and trackpad behavior.
89
+ These actions apply when interactive mode uses `--tui-mode fullscreen` and target the primary transcript scroll region. Two-finger trackpad and mouse-wheel input scroll the region under the pointer, falling back to the transcript over the fixed editor/status/footer dock. Clicking an OSC 8 hyperlink opens it in the default handler. Dragging with the primary mouse button selects text and copies it to the clipboard; holding at the transcript's top or bottom edge auto-scrolls into off-screen content. While the transcript is scrolled up, a clickable "Jump to latest message" label on its bottom row shows the `tui.altScreen.bottom` shortcut. See [Terminal setup](terminal-setup.md) for terminal-specific mouse and trackpad behavior.
90
90
 
91
91
  Fullscreen transcript bindings take precedence over editor bindings. The default unmodified navigation keys therefore control the transcript in fullscreen mode, while their `ctrl` variants continue to control the editor. Outside fullscreen mode, both variants control the editor.
92
92
 
93
+ The transcript search panel shows the configured previous/next shortcuts and clickable arrow controls. Press `tui.altScreen.search` again, or use `tui.altScreen.searchClose`, to close it.
94
+
93
95
  | Key | Default mode | Fullscreen mode |
94
96
  |-----|--------------|-----------------|
95
97
  | `home`, `end` | Editor | Transcript |
@@ -149,7 +151,9 @@ This routing remains configurable through the ordinary action bindings. For exam
149
151
  | `app.model.select` | `ctrl+l` | Open model selector |
150
152
  | `app.model.cycleForward` | `ctrl+p` | Cycle to next model |
151
153
  | `app.model.cycleBackward` | `shift+ctrl+p` (`alt+p` on Windows and WSL) | Cycle to previous model |
154
+ | `app.models.save` | `ctrl+s` | Save the selected default model or scoped model configuration to settings |
152
155
  | `app.thinking.cycle` | `shift+tab` | Cycle thinking level |
156
+ | `app.thinking.save` | `ctrl+s` | Save current thinking level to settings |
153
157
  | `app.thinking.toggle` | `ctrl+t` | Collapse or expand thinking blocks |
154
158
 
155
159
  ### Display and Message Queue
@@ -157,7 +161,7 @@ This routing remains configurable through the ordinary action bindings. For exam
157
161
  | Keybinding id | Default | Description |
158
162
  |--------|---------|-------------|
159
163
  | `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` |
164
+ | `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
165
  | `app.message.followUp` | `alt+enter` (`ctrl+q` on Windows and WSL) | Queue follow-up message |
162
166
  | `app.message.dequeue` | `alt+up` (`alt+q` on Windows and WSL) | Restore queued messages to editor |
163
167
 
@@ -183,7 +187,6 @@ Used inside the scoped models selector (opened via `/scoped-models`).
183
187
 
184
188
  | Keybinding id | Default | Description |
185
189
  |--------|---------|-------------|
186
- | `app.models.save` | `ctrl+s` | Save current model selection to settings |
187
190
  | `app.models.enableAll` | `ctrl+a` | Enable all models (or all matching the current search) |
188
191
  | `app.models.clearAll` | `ctrl+x` | Clear all models (or all matching the current search) |
189
192
  | `app.models.toggleProvider` | `ctrl+p` | Toggle all models for the current provider |
package/bin/docs/models.md CHANGED
@@ -394,6 +394,8 @@ By default pi sends per-tool `eager_input_streaming: true`. If a proxy or Anthro
394
394
 
395
395
  Some Anthropic models require adaptive thinking (`thinking.type: "adaptive"` plus `output_config.effort`) instead of the legacy budget-based thinking payload. Built-in models set this automatically. For custom providers or aliases that route to those models, set `forceAdaptiveThinking` to `true`.
396
396
 
397
+ Claude models with per-turn effort support use `supportsMidConvoEffort`. Pi then persists each response's provider effort, reconstructs effort-only system messages on later requests, and sends thinking binding controls with `prefix_mismatch_behavior: "drop_block"` to avoid stale signed-thinking prefixes causing persistent 400 responses. Set this only for the exact supported Claude model on a faithful Anthropic Messages transport; do not enable it for APIs that merely imitate the Messages shape.
398
+
397
399
  Some Anthropic-compatible providers emit thinking blocks with empty signatures and still expect them on replay. Set `allowEmptySignature` to `true` only for those providers; real Anthropic rejects empty thinking signatures.
398
400
 
399
401
  Built-in Anthropic models enable `supportsStrictTools` in their model metadata. Custom Anthropic-compatible models must set it to `true` when their endpoint accepts strict JSON-schema tool definitions.
@@ -430,6 +432,7 @@ Built-in Anthropic models enable `supportsStrictTools` in their model metadata.
430
432
  | `sendSessionAffinityHeaders` | Whether to send `x-session-affinity` from the session id when caching is enabled. Default: auto-detected for known providers. |
431
433
  | `supportsCacheControlOnTools` | Whether the provider accepts Anthropic-style `cache_control` markers on tool definitions. Default: `true`. |
432
434
  | `forceAdaptiveThinking` | Whether to send adaptive thinking (`thinking.type: "adaptive"` plus `output_config.effort`) for this model. Built-in adaptive models set this automatically. Default: `false`. |
435
+ | `supportsMidConvoEffort` | Whether the exact Claude model transport supports per-turn effort system messages and thinking binding controls. Pi persists native effort levels and always sends `drop_block` when enabled. Default: `false`. |
433
436
  | `allowEmptySignature` | Whether to replay empty thinking signatures as `signature: ""` instead of converting thinking to text. Default: `false`. |
434
437
  | `supportsStrictTools` | Whether the provider accepts strict JSON-schema tool definitions. Default: `false`; built-in Anthropic models enable it in generated metadata. |
435
438
 
@@ -479,7 +482,7 @@ For providers with partial OpenAI compatibility, use the `compat` field.
479
482
  | `supportsStrictMode` | Whether the provider accepts strict JSON-schema function tool definitions. Defaults depend on the API; built-in OpenAI models carry explicit capability metadata. |
480
483
  | `supportsOpenAIGrammarTools` | Whether OpenAI-compatible APIs emit custom Lark/regex grammar tools. When `false`, grammar-constrained tools fall back to normal function tools. Default: `false`; the built-in model catalog enables it for GPT-5+ models on OpenAI, OpenAI Codex, Azure OpenAI, GitHub Copilot, opencode, and Cloudflare AI Gateway. |
481
484
  | `deferredToolsMode` | Use provider-specific deferred tool serialization. Currently only `"kimi"` is supported for Kimi's OpenAI-compatible Chat Completions format. |
482
- | `supportsLongCacheRetention` | Whether the provider accepts long cache retention when cache retention is `long`: `prompt_cache_retention: "24h"` for OpenAI prompt caching, or `cache_control.ttl: "1h"` when `cacheControlFormat` is `anthropic`. Default: `true`. |
485
+ | `supportsLongCacheRetention` | Whether the provider accepts long cache retention when cache retention is `long`: `prompt_cache_options.ttl: "30m"` for GPT-5.6+ Responses models, `prompt_cache_retention: "24h"` for earlier OpenAI models, or `cache_control.ttl: "1h"` when `cacheControlFormat` is `anthropic`. Default: `true`. |
483
486
  | `openRouterRouting` | OpenRouter provider routing preferences. This object is sent as-is in the `provider` field of the [OpenRouter API request](https://openrouter.ai/docs/guides/routing/provider-selection). |
484
487
  | `vercelGatewayRouting` | Vercel AI Gateway routing config for provider selection (`only`, `order`) |
485
488
 
package/bin/docs/quickstart.md CHANGED
@@ -129,7 +129,7 @@ The command output is sent to the model. Use `!!command` to run a command withou
129
129
 
130
130
  ### Switch models
131
131
 
132
- Use `/model` or Ctrl+L to choose a model. Use Shift+Tab to cycle thinking level. Use Ctrl+P / Shift+Ctrl+P to cycle through scoped models.
132
+ Use `/model` or Ctrl+L to choose a model for the current session. Press Ctrl+S in the model picker to save the highlighted model as the startup default. Use `/thinking` to choose a thinking level for the current session, or Ctrl+S in that picker to save the startup default thinking level. Use Shift+Tab to cycle thinking level. Use Ctrl+P / Shift+Ctrl+P to cycle through scoped models.
133
133
 
134
134
  ### Continue later
135
135
 
package/bin/docs/rpc.md CHANGED
@@ -123,7 +123,7 @@ See [set_follow_up_mode](#set_follow_up_mode) for controlling how follow-up mess
123
123
 
124
124
  #### abort
125
125
 
126
- Abort the current agent operation.
126
+ Abort the current operation and wait for the session to become idle before responding.
127
127
 
128
128
  ```json
129
129
  {"type": "abort"}
@@ -134,6 +134,29 @@ Response:
134
134
  {"type": "response", "command": "abort", "success": true}
135
135
  ```
136
136
 
137
+ #### clear_queue
138
+
139
+ Remove queued steering and follow-up messages and return their text.
140
+
141
+ ```json
142
+ {"type": "clear_queue"}
143
+ ```
144
+
145
+ Response:
146
+ ```json
147
+ {
148
+ "type": "response",
149
+ "command": "clear_queue",
150
+ "success": true,
151
+ "data": {
152
+ "steering": ["Change direction"],
153
+ "followUp": ["Summarize when finished"]
154
+ }
155
+ }
156
+ ```
157
+
158
+ To implement interactive Esc behavior, send `clear_queue` before `abort`, then restore the returned text in the client editor. `abort` continues queued messages when they remain in the session.
159
+
137
160
  #### new_session
138
161
 
139
162
  Start a fresh session. Can be cancelled by a `session_before_switch` extension event handler.
package/bin/docs/sdk.md CHANGED
@@ -788,6 +788,11 @@ const { session: opened } = await createAgentSession({
788
788
  sessionManager: SessionManager.open("/path/to/session.jsonl"),
789
789
  });
790
790
 
791
+ // Resume a session kept outside the filesystem, e.g. in a database
792
+ const { session: restored } = await createAgentSession({
793
+ sessionManager: SessionManager.inMemory(process.cwd(), { id: sessionId }, entries),
794
+ });
795
+
791
796
  // List sessions
792
797
  const currentProjectSessions = await SessionManager.list(process.cwd());
793
798
  const allSessions = await SessionManager.listAll(process.cwd());
package/bin/docs/settings.md CHANGED
@@ -7,7 +7,7 @@ Pi uses JSON settings files with project settings overriding global settings.
7
7
  | `~/.pi/agent/settings.json` | Global (all projects) |
8
8
  | `.pi/settings.json` | Project (current directory) |
9
9
 
10
- Edit directly or use `/settings` for common options.
10
+ Edit directly or use `/settings` for common options. To save startup model defaults interactively, use `/model` and press Ctrl+S on the desired model. To save the startup thinking level, use `/thinking` and press Ctrl+S.
11
11
 
12
12
  ## Project Trust
13
13
 
@@ -27,11 +27,12 @@ Use `/trust` in interactive mode to save a project trust decision for future ses
27
27
 
28
28
  | Setting | Type | Default | Description |
29
29
  |---------|------|---------|-------------|
30
- | `defaultProvider` | string | - | Default provider (e.g., `"anthropic"`, `"openai"`) |
31
- | `defaultModel` | string | - | Default model ID |
32
- | `defaultThinkingLevel` | string | - | `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"` |
30
+ | `defaultProvider` | string | - | Startup provider (e.g., `"anthropic"`, `"openai"`; saved with Ctrl+S in `/model`, or edited manually) |
31
+ | `defaultModel` | string | - | Startup model ID (saved with Ctrl+S in `/model`, or edited manually) |
32
+ | `defaultThinkingLevel` | string | - | Startup thinking level (saved with Ctrl+S in `/thinking`, or edited manually): `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"` |
33
+ | `modelThinkingLevels` | object | - | Per-model startup thinking levels keyed by `"provider/modelId"`; configure from `/settings` → Default thinking level per model or edit manually |
33
34
  | `hideThinkingBlock` | boolean | `false` | Hide thinking blocks in output |
34
- | `showCacheMissNotices` | boolean | `false` | Show transcript notices for significant prompt-cache misses and compaction or branch-summary usage |
35
+ | `showCacheMissNotices` | boolean | `false` | Show transcript notices for significant prompt-cache misses, compaction or branch-summary usage, and provider recovery diagnostics such as dropped Anthropic thinking blocks |
35
36
  | `thinkingBudgets` | object | - | Custom token budgets per thinking level. Anthropic, Google, and Bedrock use these natively. OpenAI-compatible models use them when `compat.thinkingTokenBudgetField` (or `supportsThinkingTokenBudget`) is set. |
36
37
 
37
38
  #### thinkingBudgets
@@ -56,7 +57,7 @@ Use `/trust` in interactive mode to save a project trust decision for future ses
56
57
  | `quietStartup` | boolean | `false` | Hide startup header |
57
58
  | `defaultProjectTrust` | string | `"ask"` | Fallback project trust behavior: `"ask"`, `"always"`, or `"never"`. Global setting only |
58
59
  | `collapseChangelog` | boolean | `false` | Show condensed changelog after updates |
59
- | `enableInstallTelemetry` | boolean | `true` | Send an anonymous install/update version ping after first install or changelog-detected updates. This does not control update checks |
60
+ | `enableInstallTelemetry` | boolean | `true` | Send the anonymous install/update ping and selected provider attribution headers. This does not control update checks |
60
61
  | `enableAnalytics` | boolean | `false` | Opt-in analytics data sharing. Currently only asked for during the experimental first-time setup (`PI_EXPERIMENTAL=1`) |
61
62
  | `trackingId` | string | - | Analytics tracking identifier, generated when `enableAnalytics` is turned on |
62
63
  | `doubleEscapeAction` | string | `"tree"` | Action for double-escape: `"tree"`, `"fork"`, or `"none"` |
@@ -67,7 +68,8 @@ Use `/trust` in interactive mode to save a project trust decision for future ses
67
68
  | `showHardwareCursor` | boolean | `false` | Show the terminal cursor while TUI positions it for IME support |
68
69
  | `tuiMode` | string | `"regular"` | Interactive TUI mode: `"regular"` or experimental `"fullscreen"`. Changes from `/settings` apply immediately; `--tui-mode` overrides this setting at startup |
69
70
  | `fullscreenExitOutput` | string | `"transcript"` | Fullscreen exit output: `"transcript"` prints the final transcript and resume hint, while `"resume-hint"` restores the previous screen and prints only the resume hint. Has no effect in regular TUI mode |
70
- | `fullscreenScrollbar` | string | `"auto"` | Fullscreen transcript scrollbar: `"auto"` shows it temporarily while scrolling, `"always"` reserves the rightmost column and keeps it visible, and `"hidden"` hides it. Has no effect in regular TUI mode |
71
+ | `fullscreenScrollbar` | string | `"auto"` | Fullscreen transcript scrollbar: `"auto"` shows it temporarily while scrolling or while the pointer is over its rightmost-column track, `"always"` reserves that column and keeps it visible, and `"hidden"` hides it. Has no effect in regular TUI mode |
72
+ | `fullscreenCopyOnSelect` | boolean | `true` | Automatically copy selected text in fullscreen mode. When disabled, selections stay highlighted and `Ctrl+X` copies the active selection |
71
73
 
72
74
  For VS Code, include `--wait` so pi resumes after the editor exits:
73
75
 
@@ -79,7 +81,7 @@ For VS Code, include `--wait` so pi resumes after the editor exits:
79
81
 
80
82
  ### Telemetry and update checks
81
83
 
82
- `enableInstallTelemetry` only controls the anonymous install/update ping to `https://pi.dev/api/report-install`. Opting out of telemetry does not disable update checks; Pi can still fetch `https://pi.dev/api/latest-version` to look for the latest version.
84
+ `enableInstallTelemetry` controls the anonymous install/update ping to `https://pi.dev/api/report-install` and Pi attribution headers for OpenRouter, NVIDIA NIM, and Cloudflare provider requests. Opting out disables both. It does not disable update checks; Pi can still fetch `https://pi.dev/api/latest-version` to look for the latest version.
83
85
 
84
86
  Set `PI_SKIP_VERSION_CHECK=1` to disable the Pi version update check. Use `--offline` or `PI_OFFLINE=1` to disable all startup network operations described here, including update checks, package update checks, and install/update telemetry.
85
87
 
@@ -131,7 +133,7 @@ Set `PI_SKIP_VERSION_CHECK=1` to disable the Pi version update check. Use `--off
131
133
 
132
134
  | Setting | Type | Default | Description |
133
135
  |---------|------|---------|-------------|
134
- | `branchSummary.reserveTokens` | number | `16384` | Tokens reserved for branch summarization |
136
+ | `branchSummary.reserveTokens` | number | `16384` | Tokens reserved when selecting branch history; output is capped at 4096 tokens |
135
137
  | `branchSummary.skipPrompt` | boolean | `false` | Skip "Summarize branch?" prompt on `/tree` navigation (defaults to no summary) |
136
138
 
137
139
  ### Retry
@@ -188,6 +190,9 @@ Keep `retry.provider.maxRetries` at `0` unless provider-level retries are explic
188
190
  | `terminal.showImages` | boolean | `true` | Show images in terminal (if supported) |
189
191
  | `terminal.imageWidthCells` | number | `60` | Preferred inline image width in terminal cells |
190
192
  | `terminal.clearOnShrink` | boolean | `false` | Clear empty rows when content shrinks (can cause flicker) |
193
+ | `terminal.hyperlinks` | boolean or `"auto"` | `"auto"` | Override OSC 8 hyperlink support (advanced, JSON-only) |
194
+ | `terminal.images` | string or boolean | `"auto"` | Override image protocol support with `"kitty"`, `"iterm2"`, `false`, or `"auto"` (advanced, JSON-only) |
195
+ | `terminal.trueColor` | boolean or `"auto"` | `"auto"` | Override truecolor support (advanced, JSON-only) |
191
196
  | `images.autoResize` | boolean | `true` | Resize images to 2000x2000 max. Applies to `@file` attachments, `read`, and images returned by tools |
192
197
  | `images.blockImages` | boolean | `false` | Block all images from being sent to LLM |
193
198
 
@@ -326,6 +331,9 @@ See [packages.md](packages.md) for package management details.
326
331
  "defaultProvider": "anthropic",
327
332
  "defaultModel": "claude-sonnet-4-20250514",
328
333
  "defaultThinkingLevel": "medium",
334
+ "modelThinkingLevels": {
335
+ "anthropic/claude-sonnet-4-20250514": "high"
336
+ },
329
337
  "theme": "dark",
330
338
  "compaction": {
331
339
  "enabled": true,
package/bin/docs/skills.md CHANGED
@@ -66,7 +66,7 @@ For project-level Claude Code skills, add to `.pi/settings.json`:
66
66
 
67
67
  1. At startup, pi scans skill locations and extracts names and descriptions
68
68
  2. The system prompt includes available skills in XML format per the [specification](https://agentskills.io/integrate-skills)
69
- 3. When a task matches, the agent uses `read` to load the full SKILL.md (models don't always do this; use prompting or `/skill:name` to force it)
69
+ 3. When a task matches, the agent uses `read`, or `bash` when `read` is unavailable, to load the full SKILL.md (models don't always do this; use prompting or `/skill:name` to force it)
70
70
  4. The agent follows the instructions, using relative paths to reference scripts and assets
71
71
 
72
72
  This is progressive disclosure: only descriptions are always in context, full instructions load on-demand.
package/bin/docs/terminal-setup.md CHANGED
@@ -2,6 +2,18 @@
2
2
 
3
3
  Pi uses the [Kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/) for reliable modifier key detection. Most modern terminals support this protocol, but some require configuration.
4
4
 
5
+ ## Capability Overrides
6
+
7
+ Pi auto-detects OSC 8 hyperlinks, inline image protocols, and truecolor. If detection fails behind a terminal proxy or multiplexer, use these advanced overrides:
8
+
9
+ | Capability | Environment variable | JSON setting |
10
+ |------------|----------------------|--------------|
11
+ | OSC 8 hyperlinks | `PI_HYPERLINKS=1\|0\|auto` | `terminal.hyperlinks: true\|false\|"auto"` |
12
+ | Inline images | `PI_IMAGE_PROTOCOL=kitty\|iterm2\|none\|auto` | `terminal.images: "kitty"\|"iterm2"\|false\|"auto"` |
13
+ | Truecolor | `PI_TRUE_COLOR=1\|0\|auto` | `terminal.trueColor: true\|false\|"auto"` |
14
+
15
+ Settings take precedence over environment variables; unset or `auto` preserves detection. Only force capabilities supported by the complete terminal path, since unsupported escape sequences can corrupt rendering.
16
+
5
17
  ## Kitty
6
18
 
7
19
  Works out of the box.
@@ -118,6 +130,21 @@ Add to `keybindings.json`:
118
130
  }
119
131
  ```
120
132
 
133
+ ## Zed (Integrated Terminal)
134
+
135
+ Add these key bindings to your Zed `keymap.json`:
136
+
137
+ ```json
138
+ {
139
+ "context": "Terminal",
140
+ "bindings": {
141
+ "shift-enter": ["terminal::SendText", "\u001b[13;2u"],
142
+ "ctrl--": ["terminal::SendText", "\u001b[45;5u"],
143
+ "ctrl-alt-]": ["terminal::SendText", "\u001b[93;7u"]
144
+ }
145
+ }
146
+ ```
147
+
121
148
  ## Windows Terminal
122
149
 
123
150
  Pi uses Windows-style keybindings when running natively on Windows or in WSL:
package/bin/docs/themes.md CHANGED
@@ -88,7 +88,8 @@ vim ~/.pi/agent/themes/my-theme.json
88
88
  "text": "",
89
89
  "thinkingText": "secondary",
90
90
  "selectedBg": "#2d2d30",
91
- "scrollbarThumb": "#555566",
91
+ "scrollbarTrack": "secondary",
92
+ "scrollbarThumb": "",
92
93
  "searchMatchBg": "#2d2d30",
93
94
  "searchMatchText": "",
94
95
  "userMessageBg": "#2d2d30",
@@ -160,15 +161,15 @@ vim ~/.pi/agent/themes/my-theme.json
160
161
 
161
162
  - `name` is required, must be unique, and must not contain `/`.
162
163
  - `vars` is optional. Define reusable colors here, then reference them in `colors`.
163
- - `colors` must define all 51 required tokens. `thinkingMax`, `scrollbarThumb`, and the two search highlight tokens are optional and use the fallbacks listed below.
164
+ - `colors` must define all 53 required tokens. `thinkingMax` and the two search highlight tokens are optional and use the fallbacks listed below.
164
165
 
165
166
  The `$schema` field enables editor auto-completion and validation.
166
167
 
167
168
  ## Color Tokens
168
169
 
169
- Every theme must define all 51 required color tokens. The optional tokens preserve compatibility with existing themes: `thinkingMax` falls back to `thinkingXhigh`, `scrollbarThumb` and `searchMatchBg` fall back to `selectedBg`, and `searchMatchText` falls back to `text`. Other search matches use `searchMatchText` on `searchMatchBg` with an underline; the current match reverses that foreground/background pair and uses bold text.
170
+ Every theme must define all 53 required color tokens. The optional tokens preserve compatibility with existing themes: `thinkingMax` falls back to `thinkingXhigh`, `searchMatchBg` falls back to `selectedBg`, and `searchMatchText` falls back to `text`. Other search matches use `searchMatchText` on `searchMatchBg` with an underline; the current match reverses that foreground/background pair and uses bold text.
170
171
 
171
- ### Core UI (11 colors)
172
+ ### Core UI (13 colors)
172
173
 
173
174
  | Token | Purpose |
174
175
  |-------|---------|
@@ -183,13 +184,14 @@ Every theme must define all 51 required color tokens. The optional tokens preser
183
184
  | `dim` | Tertiary text |
184
185
  | `text` | Default text (usually `""`) |
185
186
  | `thinkingText` | Thinking block text |
187
+ | `scrollbarTrack` | Fullscreen scrollbar track foreground |
188
+ | `scrollbarThumb` | Fullscreen scrollbar thumb foreground, shared by normal and expanded states |
186
189
 
187
- ### Backgrounds & Content (11 required, 3 optional)
190
+ ### Backgrounds & Content (11 required, 2 optional)
188
191
 
189
192
  | Token | Purpose |
190
193
  |-------|---------|
191
194
  | `selectedBg` | Selected line background |
192
- | `scrollbarThumb` | Fullscreen scrollbar thumb background; optional, falls back to `selectedBg` |
193
195
  | `searchMatchBg` | Transcript search match background and current-match text; optional, falls back to `selectedBg` |
194
196
  | `searchMatchText` | Transcript search match text and current-match background; optional, falls back to `text` |
195
197
  | `userMessageBg` | User message background |
package/bin/docs/tui.md CHANGED
@@ -14,6 +14,7 @@ All components implement:
14
14
  interface Component {
15
15
  render(width: number): string[];
16
16
  handleInput?(data: string): void;
17
+ handleMouse?(event: TuiMouseEvent): TuiMouseEventResult | undefined;
17
18
  wantsKeyRelease?: boolean;
18
19
  invalidate(): void;
19
20
  }
@@ -23,6 +24,7 @@ interface Component {
23
24
  |--------|-------------|
24
25
  | `render(width)` | Return array of strings (one per line). Each line **must not exceed `width`**. |
25
26
  | `handleInput?(data)` | Receive keyboard input when component has focus. |
27
+ | `handleMouse?(event)` | Receive normalized pointer input in fullscreen mode. |
26
28
  | `wantsKeyRelease?` | If true, component receives key release events (Kitty protocol). Default: false. |
27
29
  | `invalidate()` | Clear cached render state. Called on theme changes. |
28
30
 
@@ -52,7 +54,7 @@ When a `Focusable` component has focus, TUI:
52
54
  3. Positions the hardware terminal cursor at that location
53
55
  4. Shows the hardware cursor only when `showHardwareCursor` is enabled
54
56
 
55
- The cursor remains hidden by default. This keeps the fake cursor rendering, while still positioning the hardware cursor for terminals that track IME candidate windows with hidden cursors. Some terminals require a visible hardware cursor for IME positioning; enable it with `showHardwareCursor`, `setShowHardwareCursor(true)`, or `PI_HARDWARE_CURSOR=1`. The `Editor` and `Input` built-in components already implement this interface.
57
+ The cursor remains hidden by default. This keeps the fake cursor rendering, while still positioning the hardware cursor for terminals that track IME candidate windows with hidden cursors. Some terminals require a visible hardware cursor for IME positioning; enable it with the renderer's `showHardwareCursor` constructor argument or `setShowHardwareCursor(true)`. Pi also maps `PI_HARDWARE_CURSOR=1` to this setting before it creates its renderer. The `Editor` and `Input` built-in components already implement this interface.
56
58
 
57
59
  ### Container Components with Embedded Inputs
58
60
 
@@ -307,6 +309,22 @@ handleInput(data: string) {
307
309
  - With modifiers: `Key.ctrl("c")`, `Key.shift("tab")`, `Key.alt("left")`, `Key.ctrlShift("p")`
308
310
  - String format also works: `"enter"`, `"ctrl+c"`, `"shift+tab"`, `"ctrl+shift+p"`
309
311
 
312
+ ## Mouse Input
313
+
314
+ Fullscreen mode routes normalized press, release, click, move, drag, and wheel events to components and overlays. Return `{ handled: true }` to suppress default behavior, `capture: true` to retain drag/release ownership, `focus: true` to request keyboard focus, and `render: true` when a hover or release visibly changes the component. Press, click, drag, and wheel render by default; no-op move/release events do not.
315
+
316
+ ```typescript
317
+ import { MouseRegion } from "@earendil-works/pi-tui";
318
+
319
+ const clickable = new MouseRegion(content, (event) => {
320
+ if (event.type !== "click" || event.button !== "left") return undefined;
321
+ expanded = !expanded;
322
+ return { handled: true };
323
+ });
324
+ ```
325
+
326
+ Unhandled wheel input scrolls the nearest `ScrollView`; unhandled primary-button drags retain transcript selection. OSC 8 links take precedence over parent click regions. `Input`, `Editor`, `SelectList`, and `SettingsList` include fullscreen mouse behavior. Regular mode does not capture mouse input because the terminal owns its scrollback.
327
+
310
328
  ## Line Width
311
329
 
312
330
  **Critical:** Each line from `render()` must not exceed the `width` parameter.
@@ -912,6 +930,7 @@ export default function (pi: ExtensionAPI) {
912
930
 
913
931
  - **Extend `CustomEditor`** (not base `Editor`) to get app keybindings (escape to abort, ctrl+d to exit, model switching, etc.)
914
932
  - **Call `super.handleInput(data)`** for keys you don't handle
933
+ - **Working status**: custom editors keep the standalone working row by default. Pass `{ embedWorkingStatus: true }` as the fourth `CustomEditor` constructor argument to use the built-in editor-border spinner instead.
915
934
  - **Factory pattern**: `setEditorComponent` receives a factory function that gets `tui`, `theme`, and `keybindings`
916
935
  - **Pass `undefined`** to restore the default editor: `ctx.ui.setEditorComponent(undefined)`
917
936
 
package/bin/docs/usage.md CHANGED
@@ -22,7 +22,7 @@ The editor can be replaced temporarily by built-in UI such as `/settings` or by
22
22
  | File reference | Type `@` to fuzzy-search project files |
23
23
  | Path completion | Press Tab to complete paths |
24
24
  | Multi-line input | Shift+Enter, or Ctrl+Enter on Windows Terminal |
25
- | Copy response | Ctrl+X copies the last assistant message; in `/tree`, it copies the selected message |
25
+ | Copy response | Ctrl+X copies the selected message in `/tree`; otherwise it copies the last assistant message, or the active fullscreen text selection when `fullscreenCopyOnSelect` is disabled |
26
26
  | Images | Paste with Ctrl+V, Alt+V on Windows, or drag into the terminal |
27
27
  | Shell command | `!command` runs and sends output to the model |
28
28
  | Hidden shell command | `!!command` runs without sending output to the model |
@@ -38,9 +38,10 @@ Type `/` in the editor to open command completion. Extensions can register custo
38
38
  |---------|-------------|
39
39
  | `/login`, `/logout` | Manage OAuth or API-key credentials |
40
40
  | [`/llama`](llama-cpp.md) | Download, load, and unload llama.cpp router models |
41
- | `/model` | Switch models |
41
+ | `/model` | Switch models; Ctrl+S in the picker saves the startup default |
42
+ | `/thinking` | Switch thinking level; Ctrl+S in the picker saves the startup default |
42
43
  | `/scoped-models` | Enable/disable models for Ctrl+P cycling |
43
- | `/settings` | Thinking level, theme, message delivery, transport |
44
+ | `/settings` | Theme, message delivery, transport, and other preferences |
44
45
  | `/resume` | Pick from previous sessions |
45
46
  | `/new` | Start a new session |
46
47
  | `/name <name>` | Set session display name |
package/bin/examples/README.md CHANGED
@@ -18,6 +18,9 @@ Example extensions demonstrating:
18
18
  - External integrations (SSH, file watchers, system theme sync)
19
19
  - Custom providers (Anthropic with custom streaming, GitLab Duo)
20
20
 
21
+ ### [plugins/pi-example-plugin/](plugins/pi-example-plugin/)
22
+ An experimental plugin package that Pi automatically builds into separate Session-worker and TUI Chord facets.
23
+
21
24
  ## Documentation
22
25
 
23
26
  - [SDK Reference](sdk/README.md)
package/bin/examples/extensions/custom-provider-anthropic/package-lock.json CHANGED
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "name": "pi-extension-custom-provider",
3
- "version": "0.84.3",
3
+ "version": "0.85.1",
4
4
  "lockfileVersion": 3,
5
5
  "requires": true,
6
6
  "packages": {
7
7
  "": {
8
8
  "name": "pi-extension-custom-provider",
9
- "version": "0.84.3",
9
+ "version": "0.85.1",
10
10
  "dependencies": {
11
11
  "@anthropic-ai/sdk": "^0.52.0"
12
12
  }
package/bin/examples/extensions/custom-provider-anthropic/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "pi-extension-custom-provider-anthropic",
3
3
  "private": true,
4
- "version": "0.84.3",
4
+ "version": "0.85.1",
5
5
  "type": "module",
6
6
  "scripts": {
7
7
  "clean": "echo 'nothing to clean'",
package/bin/examples/extensions/custom-provider-gitlab-duo/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "pi-extension-custom-provider-gitlab-duo",
3
3
  "private": true,
4
- "version": "0.84.3",
4
+ "version": "0.85.1",
5
5
  "type": "module",
6
6
  "scripts": {
7
7
  "clean": "echo 'nothing to clean'",
package/bin/examples/extensions/dynamic-resources/dynamic.json CHANGED
@@ -30,6 +30,8 @@
30
30
  "dim": "dimGray",
31
31
  "text": "",
32
32
  "thinkingText": "gray",
33
+ "scrollbarTrack": "darkGray",
34
+ "scrollbarThumb": "",
33
35
  "selectedBg": "selectedBg",
34
36
  "userMessageBg": "userMsgBg",
35
37
  "userMessageText": "",
package/bin/examples/extensions/gondolin/package-lock.json CHANGED
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "name": "pi-extension-gondolin",
3
- "version": "0.84.3",
3
+ "version": "0.85.1",
4
4
  "lockfileVersion": 3,
5
5
  "requires": true,
6
6
  "packages": {
7
7
  "": {
8
8
  "name": "pi-extension-gondolin",
9
- "version": "0.84.3",
9
+ "version": "0.85.1",
10
10
  "dependencies": {
11
11
  "@earendil-works/gondolin": "0.12.0"
12
12
  }
package/bin/examples/extensions/gondolin/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "pi-extension-gondolin",
3
3
  "private": true,
4
- "version": "0.84.3",
4
+ "version": "0.85.1",
5
5
  "type": "module",
6
6
  "scripts": {
7
7
  "clean": "echo 'nothing to clean'",
package/bin/examples/extensions/sandbox/package-lock.json CHANGED
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "name": "pi-extension-sandbox",
3
- "version": "1.14.3",
3
+ "version": "1.15.1",
4
4
  "lockfileVersion": 3,
5
5
  "requires": true,
6
6
  "packages": {
7
7
  "": {
8
8
  "name": "pi-extension-sandbox",
9
- "version": "1.14.3",
9
+ "version": "1.15.1",
10
10
  "dependencies": {
11
11
  "@anthropic-ai/sandbox-runtime": "^0.0.26"
12
12
  }
package/bin/examples/extensions/sandbox/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "pi-extension-sandbox",
3
3
  "private": true,
4
- "version": "1.14.3",
4
+ "version": "1.15.1",
5
5
  "type": "module",
6
6
  "scripts": {
7
7
  "clean": "echo 'nothing to clean'",
package/bin/examples/extensions/with-deps/package-lock.json CHANGED
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "name": "pi-extension-with-deps",
3
- "version": "0.84.3",
3
+ "version": "0.85.1",
4
4
  "lockfileVersion": 3,
5
5
  "requires": true,
6
6
  "packages": {
7
7
  "": {
8
8
  "name": "pi-extension-with-deps",
9
- "version": "0.84.3",
9
+ "version": "0.85.1",
10
10
  "dependencies": {
11
11
  "ms": "^2.1.3"
12
12
  },
package/bin/examples/extensions/with-deps/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "pi-extension-with-deps",
3
3
  "private": true,
4
- "version": "0.84.3",
4
+ "version": "0.85.1",
5
5
  "type": "module",
6
6
  "scripts": {
7
7
  "clean": "echo 'nothing to clean'",
package/bin/examples/plugins/pi-example-plugin/README.md ADDED
@@ -0,0 +1,38 @@
1
+ # `@earendil-works/pi-example-plugin`
2
+
3
+ This package provides conventional `session` and `tui` Chord facets. The Session-worker facet provides a remote greeting service. The TUI facet contributes `/hello` and calls that service.
4
+
5
+ The package needs no build script. Pi asks Chord to discover `src/session.ts` and `src/tui.ts`, builds both entries into its server-owned plugin cache, and sends the TUI artifact to clients.
6
+
7
+ From the repository root:
8
+
9
+ ```bash
10
+ PI_EXPERIMENTAL=1 ./pi-test.sh server \
11
+ -e "$PWD/packages/coding-agent/examples/plugins/pi-example-plugin"
12
+ ```
13
+
14
+ Alternatively, a client can select the plugin for the Session it creates or resumes on one local server:
15
+
16
+ ```bash
17
+ PI_EXPERIMENTAL=1 ./pi-test.sh client \
18
+ -e "$PWD/packages/coding-agent/examples/plugins/pi-example-plugin"
19
+ ```
20
+
21
+ Repeat `-e` to select multiple plugin packages. Client paths are resolved locally and sent only to a Unix server; Radius clients cannot select server filesystem paths. The Session and matching TUI facets are stored with that Session, so later server generations and clients can resume it without plugin arguments. Other Sessions and their workers are unaffected. An active Session rejects a different package selection instead of being restarted.
22
+
23
+ `server -e` establishes the server profile's default Session and TUI facets. Starting an explicit foreground server without `-e` clears that default. Client selection never changes the server's root facet generation.
24
+
25
+ Run `/hello Armin` in the TUI. After editing a facet, run `/reload`. The server atomically rebuilds the package, reloads the attached Session-worker generation, updates the current TUI generation, and serves the new artifact to future clients.
26
+
27
+ Package metadata can override or disable conventional entries:
28
+
29
+ ```json
30
+ {
31
+ "chord": {
32
+ "facets": {
33
+ "session": "./src/worker.ts",
34
+ "tui": false
35
+ }
36
+ }
37
+ }
38
+ ```
package/bin/examples/plugins/pi-example-plugin/package.json ADDED
@@ -0,0 +1,10 @@
1
+ {
2
+ "name": "@earendil-works/pi-example-plugin",
3
+ "version": "1.0.0",
4
+ "private": true,
5
+ "type": "module",
6
+ "peerDependencies": {
7
+ "@earendil-works/chord": "^0.84.4",
8
+ "@earendil-works/pi-coding-agent": "^0.84.4"
9
+ }
10
+ }
package/bin/examples/plugins/pi-example-plugin/src/contract.ts ADDED
@@ -0,0 +1,13 @@
1
+ import { type Context, defineService, type ReplicatedState } from "@earendil-works/chord";
2
+
3
+ export interface ExampleFacetReply {
4
+ readonly message: string;
5
+ readonly workerActivations: number;
6
+ }
7
+
8
+ export interface ExampleFacetService {
9
+ readonly workerActivations: ReplicatedState<{ count: number }>;
10
+ greet(input: { readonly name: string }, context: Context): Promise<ExampleFacetReply>;
11
+ }
12
+
13
+ export const ExampleFacetService = defineService<ExampleFacetService>("pi.example-plugin.greeting");
package/bin/examples/plugins/pi-example-plugin/src/session.ts ADDED
@@ -0,0 +1,23 @@
1
+ import { defineFacet } from "@earendil-works/chord";
2
+ import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
3
+ import { ExampleFacetService } from "./contract.ts";
4
+
5
+ export default defineFacet({
6
+ id: "@earendil-works/pi-example-plugin/session",
7
+ setup(env) {
8
+ const workerActivations = env.replicatedState({ count: 0 });
9
+ env.provide(ExampleFacetService, {
10
+ workerActivations,
11
+ async greet({ name }) {
12
+ return {
13
+ message: `Hello ${name} from the bundled Session worker facet!!!`,
14
+ workerActivations: workerActivations.value.count,
15
+ };
16
+ },
17
+ });
18
+ env.onActivate(() => {
19
+ workerActivations.state.count += 1;
20
+ workerActivations.publish(BACKGROUND_CONTEXT);
21
+ });
22
+ },
23
+ });
package/bin/examples/plugins/pi-example-plugin/src/tui.ts ADDED
@@ -0,0 +1,31 @@
1
+ import { defineFacet } from "@earendil-works/chord";
2
+ import { AgentController, PresentationUI, SlashCommands } from "@earendil-works/pi-coding-agent/experimental/plugin";
3
+ import { ExampleFacetService } from "./contract.ts";
4
+
5
+ export default defineFacet({
6
+ id: "@earendil-works/pi-example-plugin/tui",
7
+ setup(env) {
8
+ const example = env.use(ExampleFacetService);
9
+ const commands = env.use(SlashCommands);
10
+ const controller = env.use(AgentController);
11
+ const ui = env.use(PresentationUI);
12
+ env.onActivate(() => {
13
+ env.own(
14
+ commands.replace({
15
+ name: "hello",
16
+ description: "Call the bundled Session worker facet",
17
+ argumentHint: "<name>",
18
+ async run(args, context) {
19
+ const message = args.length === 0 ? "from the TUI" : args;
20
+ const reply = await example.greet({ name: message }, context);
21
+ ui.showStatus(
22
+ `We got this: ${reply.message} Worker activations: ${reply.workerActivations}.`,
23
+ context,
24
+ );
25
+ return controller.prompt({ message: `pong: ${message}`, images: null }, context);
26
+ },
27
+ }),
28
+ );
29
+ });
30
+ },
31
+ });
package/bin/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@earendil-works/pi-coding-agent",
3
- "version": "0.84.3",
3
+ "version": "0.85.1",
4
4
  "description": "Coding agent CLI with read, bash, edit, write tools and session management",
5
5
  "type": "module",
6
6
  "piConfig": {
@@ -20,12 +20,17 @@
20
20
  "import": "./dist/bundle/rpc-entry.js"
21
21
  },
22
22
  "./client": {
23
- "types": "./dist/client/index.d.ts",
24
- "import": "./dist/client/index.js"
23
+ "source": "./src/client/index.ts"
24
+ },
25
+ "./experimental/plugin": {
26
+ "source": "./src/experimental/plugin.ts"
25
27
  }
26
28
  },
27
29
  "files": [
28
30
  "dist",
31
+ "!dist/client",
32
+ "!dist/experimental",
33
+ "!dist/cli/experimental",
29
34
  "docs",
30
35
  "examples",
31
36
  "containerization.md",
@@ -44,11 +49,10 @@
44
49
  "prepublishOnly": "npm run clean && npm run build && npm run shrinkwrap"
45
50
  },
46
51
  "dependencies": {
47
- "@earendil-works/pi-agent-core": "^0.84.3",
48
- "@earendil-works/pi-ai": "^0.84.3",
49
- "@earendil-works/pi-client": "^0.84.3",
50
- "@earendil-works/pi-protocol": "^0.84.3",
51
- "@earendil-works/pi-tui": "^0.84.3",
52
+ "@earendil-works/chord": "^0.85.1",
53
+ "@earendil-works/pi-agent-core": "^0.85.1",
54
+ "@earendil-works/pi-ai": "^0.85.1",
55
+ "@earendil-works/pi-tui": "^0.85.1",
52
56
  "@silvia-odwyer/photon-node": "0.3.4",
53
57
  "chalk": "5.6.2",
54
58
  "cross-spawn": "7.0.6",
@@ -76,6 +80,9 @@
76
80
  "@mariozechner/clipboard": "0.3.9"
77
81
  },
78
82
  "devDependencies": {
83
+ "@earendil-works/pi-client": "^0.85.1",
84
+ "@earendil-works/pi-protocol": "^0.85.1",
85
+ "@earendil-works/pi-server": "^0.85.1",
79
86
  "@types/cross-spawn": "6.0.6",
80
87
  "@types/hosted-git-info": "3.0.5",
81
88
  "@types/node": "22.19.19",
package/bin/pi.exe CHANGED
Binary file
package/bin/theme/dark.json CHANGED
@@ -33,7 +33,8 @@
33
33
  "thinkingText": "gray",
34
34
 
35
35
  "selectedBg": "selectedBg",
36
- "scrollbarThumb": "selectedBg",
36
+ "scrollbarTrack": "darkGray",
37
+ "scrollbarThumb": "text",
37
38
  "searchMatchBg": "selectedBg",
38
39
  "searchMatchText": "text",
39
40
  "userMessageBg": "userMsgBg",
package/bin/theme/light.json CHANGED
@@ -32,7 +32,8 @@
32
32
  "thinkingText": "mediumGray",
33
33
 
34
34
  "selectedBg": "selectedBg",
35
- "scrollbarThumb": "selectedBg",
35
+ "scrollbarTrack": "lightGray",
36
+ "scrollbarThumb": "text",
36
37
  "searchMatchBg": "selectedBg",
37
38
  "searchMatchText": "text",
38
39
  "userMessageBg": "userMsgBg",
package/bin/theme/theme-schema.json CHANGED
@@ -34,7 +34,7 @@
34
34
  },
35
35
  "colors": {
36
36
  "type": "object",
37
- "description": "Theme color definitions (thinkingMax, scrollbarThumb, and search highlight colors are optional and use compatible fallbacks)",
37
+ "description": "Theme color definitions (scrollbar, thinkingMax, and search highlight colors are optional and use compatible fallbacks)",
38
38
  "required": [
39
39
  "accent",
40
40
  "border",
@@ -137,9 +137,13 @@
137
137
  "$ref": "#/$defs/colorValue",
138
138
  "description": "Selected item background"
139
139
  },
140
+ "scrollbarTrack": {
141
+ "$ref": "#/$defs/colorValue",
142
+ "description": "Fullscreen scrollbar track foreground (falls back to muted when omitted)"
143
+ },
140
144
  "scrollbarThumb": {
141
145
  "$ref": "#/$defs/colorValue",
142
- "description": "Fullscreen scrollbar thumb background (falls back to selectedBg when omitted)"
146
+ "description": "Fullscreen scrollbar thumb foreground (falls back to text when omitted)"
143
147
  },
144
148
  "searchMatchBg": {
145
149
  "$ref": "#/$defs/colorValue",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kingingwang/pi-windows-x64",
3
- "version": "0.84.3",
3
+ "version": "0.85.1",
4
4
  "description": "Pi standalone binary for windows-x64 (fork distribution)",
5
5
  "license": "MIT",
6
6
  "os": [