pi-openai-toolkit 0.14.11 → 0.14.13
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.
- package/README.md +241 -240
- package/README.zh.md +241 -240
- package/docs/internals.md +128 -122
- package/package.json +127 -117
- package/src/config.ts +739 -720
- package/src/context-management/messages.ts +123 -0
- package/src/context-management/tools.ts +11 -0
- package/src/context-management/window-bulk.ts +149 -0
- package/src/context-management/window-manager.ts +693 -570
- package/src/extension-runtime.ts +1329 -1208
- package/src/native-fallback.ts +218 -145
- package/src/types.ts +628 -619
package/README.md
CHANGED
|
@@ -1,240 +1,241 @@
|
|
|
1
|
-
# pi-openai-toolkit
|
|
2
|
-
|
|
3
|
-
Add Codex context windows, Responses compaction, hosted tools, and reviewed tool calls to Pi.
|
|
4
|
-
|
|
5
|
-
[](https://www.npmjs.com/package/pi-openai-toolkit)
|
|
6
|
-
[](LICENSE)
|
|
7
|
-
|
|
8
|
-
[简体中文](README.zh.md)
|
|
9
|
-
|
|
10
|
-
## Features
|
|
11
|
-
|
|
12
|
-
| Feature | Use it to |
|
|
13
|
-
| --- | --- |
|
|
14
|
-
| Codex Remote Context | Start a new context window and retrieve earlier windows with `history`. |
|
|
15
|
-
| Remote Compaction v2 | Continue an eligible Responses session with an encrypted server checkpoint. |
|
|
16
|
-
| Web Search routes | Choose local `pi-web-access`, hosted Responses `web_search`, or CPA standalone `web.run` per exact model route. |
|
|
17
|
-
| Image generation | Generate images or edit explicitly supplied local reference images. |
|
|
18
|
-
| Tool-call review | Ask a reviewer model whether selected tool calls may run. |
|
|
19
|
-
|
|
20
|
-
The package uses Pi's existing model, authentication, and session configuration. It does not add a provider or model.
|
|
21
|
-
|
|
22
|
-
## Install
|
|
23
|
-
|
|
24
|
-
Requires Pi 0.85.1 or newer and Node.js 22.19.0 or newer.
|
|
25
|
-
|
|
26
|
-
Install the extension:
|
|
27
|
-
|
|
28
|
-
```bash
|
|
29
|
-
pi install npm:pi-openai-toolkit
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
Use `--local` to install it in the current project.
|
|
33
|
-
|
|
34
|
-
Installing the package alone does not enable every feature. With no extension config, compaction is enabled but Remote Context is off, Web Search has no toolkit-selected route, image generation is disabled, and Auto Mode has no allowed models or reviewer.
|
|
35
|
-
|
|
36
|
-
The extension config file is:
|
|
37
|
-
|
|
38
|
-
`~/.pi/agent/extensions/pi-openai-toolkit/config.json`
|
|
39
|
-
|
|
40
|
-
All JSON configuration examples below, except the `models.json` example, go in this file. If it does not exist, create the file and its parent directory. If it already exists, merge fields into the matching objects and keep the other settings.
|
|
41
|
-
|
|
42
|
-
## Quick start: enable Remote Context
|
|
43
|
-
|
|
44
|
-
This section is for users who want Codex-style context windows. If you only want Web Search, image generation, or tool-call review, skip to [Common tasks](#common-tasks).
|
|
45
|
-
|
|
46
|
-
### Use Pi's built-in Codex provider
|
|
47
|
-
|
|
48
|
-
You must already be signed in to Pi's built-in `openai-codex` provider.
|
|
49
|
-
|
|
50
|
-
Create or merge this extension config:
|
|
51
|
-
|
|
52
|
-
```json
|
|
53
|
-
{
|
|
54
|
-
"compaction": {
|
|
55
|
-
"contextManagement": "remote"
|
|
56
|
-
}
|
|
57
|
-
}
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
Start Pi with a model from your existing Codex catalog:
|
|
61
|
-
|
|
62
|
-
```bash
|
|
63
|
-
pi --model openai-codex/<model-id>
|
|
64
|
-
```
|
|
65
|
-
|
|
66
|
-
Replace `<model-id>` with the model ID shown by your Pi setup. The session is activated when `new_context`, `get_context_remaining`, `history`, and `notes` appear as available tools.
|
|
67
|
-
|
|
68
|
-
### Use a compatible gateway
|
|
69
|
-
|
|
70
|
-
This route requires the `openai-responses` API and a gateway that preserves the Codex protocol fields used by Remote Context. A successful ordinary chat request does not prove Remote Context compatibility.
|
|
71
|
-
|
|
72
|
-
If `~/.pi/agent/models.json` already contains a gateway model that meets these conditions, skip model configuration and set the extension allowlist directly. Otherwise, add or merge the provider entry below. Replace `my-gateway`, the URL, the environment variable name, and the model values with values from your setup. The numeric values shown are examples, not project defaults; they must match the actual model and gateway.
|
|
73
|
-
|
|
74
|
-
```json
|
|
75
|
-
{
|
|
76
|
-
"providers": {
|
|
77
|
-
"my-gateway": {
|
|
78
|
-
"baseUrl": "https://your-gateway.example/v1",
|
|
79
|
-
"api": "openai-responses",
|
|
80
|
-
"apiKey": "$MY_GATEWAY_KEY",
|
|
81
|
-
"models": [{
|
|
82
|
-
"id": "gpt-5.6-luna",
|
|
83
|
-
"name": "GPT-5.6 Luna",
|
|
84
|
-
"reasoning": true,
|
|
85
|
-
"input": ["text"],
|
|
86
|
-
"contextWindow": 272000,
|
|
87
|
-
"maxTokens": 128000
|
|
88
|
-
}]
|
|
89
|
-
}
|
|
90
|
-
}
|
|
91
|
-
}
|
|
92
|
-
```
|
|
93
|
-
|
|
94
|
-
Set the referenced key before starting Pi. In PowerShell:
|
|
95
|
-
|
|
96
|
-
```powershell
|
|
97
|
-
$env:MY_GATEWAY_KEY = "replace-with-your-gateway-key"
|
|
98
|
-
```
|
|
99
|
-
|
|
100
|
-
In a POSIX shell:
|
|
101
|
-
|
|
102
|
-
```bash
|
|
103
|
-
export MY_GATEWAY_KEY="replace-with-your-gateway-key"
|
|
104
|
-
```
|
|
105
|
-
|
|
106
|
-
Use the same terminal session to start Pi. Create or merge the extension config, and make the allowlist entry exactly match the provider and model ID:
|
|
107
|
-
|
|
108
|
-
```json
|
|
109
|
-
{
|
|
110
|
-
"compaction": {
|
|
111
|
-
"contextManagement": "remote",
|
|
112
|
-
"gatewayContextModels": ["my-gateway/gpt-5.6-luna"]
|
|
113
|
-
}
|
|
114
|
-
}
|
|
115
|
-
```
|
|
116
|
-
|
|
117
|
-
Start Pi with the same model specification:
|
|
118
|
-
|
|
119
|
-
```bash
|
|
120
|
-
pi --model my-gateway/gpt-5.6-luna
|
|
121
|
-
```
|
|
122
|
-
|
|
123
|
-
The enablement check is the same: the session should expose `new_context`, `get_context_remaining`, `history`, and `notes`. If they do not appear, read the toolkit notification and check the exact provider/model string, API, key, base URL, and allowlist entry.
|
|
124
|
-
|
|
125
|
-
Earlier windows remain available through `history`, but they are not all automatically added to the current context.
|
|
126
|
-
|
|
127
|
-
## Common tasks
|
|
128
|
-
|
|
129
|
-
### Continue a session with server-side compaction
|
|
130
|
-
|
|
131
|
-
Leave Remote Context off when you want the Responses compaction path instead. Remote Compaction v2 stores and replays an encrypted checkpoint for eligible Responses models. Set `compaction.remoteCompactModel` only when the compaction request should use a separate model.
|
|
132
|
-
|
|
133
|
-
When `compaction.remoteV2ContextSource` is omitted, Remote V2 keeps the original `"legacy"` input chain: first compaction uses Pi's current session context (or the supplied preparation as a last resort), and recursive compaction uses the raw branch tail. This preserves existing behavior, but can diverge from provider-visible context when other extensions rewrite messages.
|
|
134
|
-
|
|
135
|
-
Set `compaction.remoteV2ContextSource` to `"pi-context-hook"` to opt into the Pi 0.85.1 runtime bridge. The toolkit then uses the same ordered `context` hook chain as the live provider request. If Pi cannot expose that public hook path, Remote V2 cancels instead of sending an unprojected history. Checkpoint replay is accepted only when its source marker matches the current setting. Switching between the two modes requires a new Remote V2 checkpoint; disable Remote V2 or use Pi's native compaction when custom-only state must survive inside the opaque checkpoint.
|
|
136
|
-
|
|
137
|
-
### Choose a Web Search route
|
|
138
|
-
|
|
139
|
-
Web Search has three mutually exclusive routes. Configure one global default and, when needed, exact `provider/model-id` overrides:
|
|
140
|
-
|
|
141
|
-
```json
|
|
142
|
-
{
|
|
143
|
-
"webSearch": {
|
|
144
|
-
"enabled": true,
|
|
145
|
-
"defaultRoute": "hosted",
|
|
146
|
-
"routes": {
|
|
147
|
-
"uwoacrimson/gpt-6-astra": "standalone-alpha",
|
|
148
|
-
"my-gateway/gpt-5.6-luna": "local"
|
|
149
|
-
}
|
|
150
|
-
}
|
|
151
|
-
}
|
|
152
|
-
```
|
|
153
|
-
|
|
154
|
-
Route selection is exact and deterministic: `routes[provider/model-id]` wins over `defaultRoute`; `defaultRoute` wins over the legacy `models` list. There is no wildcard, fuzzy model matching, capability guessing, fallback, or retry between routes. Invalid route values/keys are ignored with warnings rather than guessed, and overlapping new/legacy fields produce migration warnings. `enabled: false` releases toolkit ownership and disables all three toolkit-selected paths.
|
|
155
|
-
|
|
156
|
-
- **`local`** keeps the already-installed `pi-web-access` `web_search` tool. The toolkit does not activate it when it was not active, and it does not add a hosted provider tool or `web.run`.
|
|
157
|
-
- **`hosted`** removes the local function named `web_search` and injects the native Responses `{ "type": "web_search" }` tool plus source annotations. The legacy configuration remains valid:
|
|
158
|
-
|
|
159
|
-
```json
|
|
160
|
-
{
|
|
161
|
-
"webSearch": {
|
|
162
|
-
"models": ["my-gateway/gpt-5.6-luna"]
|
|
163
|
-
}
|
|
164
|
-
}
|
|
165
|
-
```
|
|
166
|
-
|
|
167
|
-
With no new route fields, only models in this exact list and the existing Responses-family APIs (`openai-responses` or `openai-codex-responses`) use hosted search.
|
|
168
|
-
- **`standalone-alpha`** exposes one sequential `web.run` tool and sends one isolated `POST` request to the provider-relative `/alpha/search` endpoint. A base URL such as `https://gateway.example/v1` therefore receives `https://gateway.example/v1/alpha/search`, not a Responses endpoint. Supported command families are `search_query`, `image_query`, `open`, `click`, `find`, `screenshot`, `finance`, `weather`, `sports`, and `time`; `response_length` controls the requested result size.
|
|
169
|
-
|
|
170
|
-
The standalone route is an experimental CPA/Codex gateway protocol, not a stable public OpenAI Responses endpoint. The gateway/provider must expose `/alpha/search`, enable its `alpha-search` capability, and support standalone web search (Codex providers commonly expose this as `supports_standalone_web_search = true`). The request reuses Pi's current model, authentication, provider headers, session identity, and Codex/gateway affinity; it does not change the active model. The MVP sends the bounded command envelope rather than the full conversation transcript, relies on provider session/reference handling for `ref_id` follow-ups, makes at most one request per tool call, and fails closed on invalid configuration, unavailable routes, cancellation, timeout, non-2xx, malformed, or oversized responses.
|
|
171
|
-
|
|
172
|
-
### Generate an image
|
|
173
|
-
|
|
174
|
-
Image generation requires a Responses session and may incur provider charges. Enable it with:
|
|
175
|
-
|
|
176
|
-
```json
|
|
177
|
-
{
|
|
178
|
-
"imageGeneration": {
|
|
179
|
-
"enabled": true,
|
|
180
|
-
"models": ["gpt-image-2.5", "grok-imagine-image-2.0"]
|
|
181
|
-
}
|
|
182
|
-
}
|
|
183
|
-
```
|
|
184
|
-
|
|
185
|
-
`models` contains the bare model IDs used by the nested Responses `image_generation` tool. The first entry is the default; `openai_generate_image` also accepts an optional `model` argument for a one-call override, but it must match a configured entry exactly. If `models` is omitted, the default is `gpt-image-2.5`. Empty or invalid lists are ignored with a warning and fall back to that default; set `enabled` to `false` to disable the tool. The provider or gateway must support the configured image model.
|
|
186
|
-
|
|
187
|
-
The `openai_generate_image` tool supports text-to-image requests and edits using explicitly supplied local reference images.
|
|
188
|
-
|
|
189
|
-
### Review tool calls automatically
|
|
190
|
-
|
|
191
|
-
Allow a model and reviewer in `autoMode`:
|
|
192
|
-
|
|
193
|
-
```json
|
|
194
|
-
{
|
|
195
|
-
"autoMode": {
|
|
196
|
-
"models": ["my-gateway/gpt-5.6-luna"],
|
|
197
|
-
"reviewerModel": "my-gateway/gpt-5.6-luna"
|
|
198
|
-
}
|
|
199
|
-
}
|
|
200
|
-
```
|
|
201
|
-
|
|
202
|
-
Use `/auto on` in the session, or start Pi with `--auto`. The TUI shows an activation notice and temporarily changes the working indicator to `Auto mode: reviewing <tool>` while a gated call is being reviewed; the footer keeps the active gate visible. On Pi versions that expose the compatible tool renderer, each tool block in Auto Mode also gets a bottom line: reviewed calls show states such as `allowed by reviewer · low risk · authorization medium` or `denied · <reason>`, while calls outside the configured gate show `not reviewed · outside the configured gate`. If that renderer seam is unavailable, the extension warns once and keeps the footer-only status. The default `side-effect` gate reviews `bash`, `write`, `edit`, and configured extra tools. Set `gate` to `"all"` when every tool call needs review. A reviewer timeout does not approve a call.
|
|
203
|
-
|
|
204
|
-
## Common configuration
|
|
205
|
-
|
|
206
|
-
The config file is `~/.pi/agent/extensions/pi-openai-toolkit/config.json`. Unknown keys are ignored with a warning. Most model lists use exact `provider/model-id` strings, not globs; `imageGeneration.models` is an exception and contains bare nested image-generation model IDs.
|
|
207
|
-
|
|
208
|
-
| Key | Default | Use |
|
|
209
|
-
| --- | --- | --- |
|
|
210
|
-
| `compaction.enabled` | `true` | Master switch for compaction. |
|
|
211
|
-
| `compaction.contextManagement` | `"off"` | Enables Codex Remote Context when set to `"remote"`. |
|
|
212
|
-
| `compaction.gatewayContextModels` | `[]` | Gateway models allowed to use Remote Context. |
|
|
213
|
-
| `compaction.remoteCompactModel` | unset | Optional model used only for a v2 compaction request. |
|
|
214
|
-
| `compaction.remoteV2ContextSource` | `"legacy"` | Preserve the original raw session/branch input path. Set `"pi-context-hook"` to opt into Pi's ordered context-hook projection. Checkpoints are mode-specific. |
|
|
215
|
-
| `compaction.
|
|
216
|
-
| `
|
|
217
|
-
| `webSearch.
|
|
218
|
-
| `webSearch.
|
|
219
|
-
| `webSearch.
|
|
220
|
-
| `
|
|
221
|
-
| `imageGeneration.
|
|
222
|
-
| `
|
|
223
|
-
| `autoMode.
|
|
224
|
-
| `autoMode.
|
|
225
|
-
| `autoMode.
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
npm
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
1
|
+
# pi-openai-toolkit
|
|
2
|
+
|
|
3
|
+
Add Codex context windows, Responses compaction, hosted tools, and reviewed tool calls to Pi.
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/pi-openai-toolkit)
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
|
|
8
|
+
[简体中文](README.zh.md)
|
|
9
|
+
|
|
10
|
+
## Features
|
|
11
|
+
|
|
12
|
+
| Feature | Use it to |
|
|
13
|
+
| --- | --- |
|
|
14
|
+
| Codex Remote Context | Start a new context window and retrieve earlier windows with `history`. |
|
|
15
|
+
| Remote Compaction v2 | Continue an eligible Responses session with an encrypted server checkpoint. |
|
|
16
|
+
| Web Search routes | Choose local `pi-web-access`, hosted Responses `web_search`, or CPA standalone `web.run` per exact model route. |
|
|
17
|
+
| Image generation | Generate images or edit explicitly supplied local reference images. |
|
|
18
|
+
| Tool-call review | Ask a reviewer model whether selected tool calls may run. |
|
|
19
|
+
|
|
20
|
+
The package uses Pi's existing model, authentication, and session configuration. It does not add a provider or model.
|
|
21
|
+
|
|
22
|
+
## Install
|
|
23
|
+
|
|
24
|
+
Requires Pi 0.85.1 or newer and Node.js 22.19.0 or newer.
|
|
25
|
+
|
|
26
|
+
Install the extension:
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
pi install npm:pi-openai-toolkit
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Use `--local` to install it in the current project.
|
|
33
|
+
|
|
34
|
+
Installing the package alone does not enable every feature. With no extension config, compaction is enabled but Remote Context is off, Web Search has no toolkit-selected route, image generation is disabled, and Auto Mode has no allowed models or reviewer.
|
|
35
|
+
|
|
36
|
+
The extension config file is:
|
|
37
|
+
|
|
38
|
+
`~/.pi/agent/extensions/pi-openai-toolkit/config.json`
|
|
39
|
+
|
|
40
|
+
All JSON configuration examples below, except the `models.json` example, go in this file. If it does not exist, create the file and its parent directory. If it already exists, merge fields into the matching objects and keep the other settings.
|
|
41
|
+
|
|
42
|
+
## Quick start: enable Remote Context
|
|
43
|
+
|
|
44
|
+
This section is for users who want Codex-style context windows. If you only want Web Search, image generation, or tool-call review, skip to [Common tasks](#common-tasks).
|
|
45
|
+
|
|
46
|
+
### Use Pi's built-in Codex provider
|
|
47
|
+
|
|
48
|
+
You must already be signed in to Pi's built-in `openai-codex` provider.
|
|
49
|
+
|
|
50
|
+
Create or merge this extension config:
|
|
51
|
+
|
|
52
|
+
```json
|
|
53
|
+
{
|
|
54
|
+
"compaction": {
|
|
55
|
+
"contextManagement": "remote"
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Start Pi with a model from your existing Codex catalog:
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
pi --model openai-codex/<model-id>
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Replace `<model-id>` with the model ID shown by your Pi setup. The session is activated when `new_context`, `get_context_remaining`, `history`, and `notes` appear as available tools.
|
|
67
|
+
|
|
68
|
+
### Use a compatible gateway
|
|
69
|
+
|
|
70
|
+
This route requires the `openai-responses` API and a gateway that preserves the Codex protocol fields used by Remote Context. A successful ordinary chat request does not prove Remote Context compatibility.
|
|
71
|
+
|
|
72
|
+
If `~/.pi/agent/models.json` already contains a gateway model that meets these conditions, skip model configuration and set the extension allowlist directly. Otherwise, add or merge the provider entry below. Replace `my-gateway`, the URL, the environment variable name, and the model values with values from your setup. The numeric values shown are examples, not project defaults; they must match the actual model and gateway.
|
|
73
|
+
|
|
74
|
+
```json
|
|
75
|
+
{
|
|
76
|
+
"providers": {
|
|
77
|
+
"my-gateway": {
|
|
78
|
+
"baseUrl": "https://your-gateway.example/v1",
|
|
79
|
+
"api": "openai-responses",
|
|
80
|
+
"apiKey": "$MY_GATEWAY_KEY",
|
|
81
|
+
"models": [{
|
|
82
|
+
"id": "gpt-5.6-luna",
|
|
83
|
+
"name": "GPT-5.6 Luna",
|
|
84
|
+
"reasoning": true,
|
|
85
|
+
"input": ["text"],
|
|
86
|
+
"contextWindow": 272000,
|
|
87
|
+
"maxTokens": 128000
|
|
88
|
+
}]
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Set the referenced key before starting Pi. In PowerShell:
|
|
95
|
+
|
|
96
|
+
```powershell
|
|
97
|
+
$env:MY_GATEWAY_KEY = "replace-with-your-gateway-key"
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
In a POSIX shell:
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
export MY_GATEWAY_KEY="replace-with-your-gateway-key"
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Use the same terminal session to start Pi. Create or merge the extension config, and make the allowlist entry exactly match the provider and model ID:
|
|
107
|
+
|
|
108
|
+
```json
|
|
109
|
+
{
|
|
110
|
+
"compaction": {
|
|
111
|
+
"contextManagement": "remote",
|
|
112
|
+
"gatewayContextModels": ["my-gateway/gpt-5.6-luna"]
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Start Pi with the same model specification:
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
pi --model my-gateway/gpt-5.6-luna
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
The enablement check is the same: the session should expose `new_context`, `get_context_remaining`, `history`, and `notes`. If they do not appear, read the toolkit notification and check the exact provider/model string, API, key, base URL, and allowlist entry.
|
|
124
|
+
|
|
125
|
+
Earlier windows remain available through `history`, but they are not all automatically added to the current context.
|
|
126
|
+
|
|
127
|
+
## Common tasks
|
|
128
|
+
|
|
129
|
+
### Continue a session with server-side compaction
|
|
130
|
+
|
|
131
|
+
Leave Remote Context off when you want the Responses compaction path instead. Remote Compaction v2 stores and replays an encrypted checkpoint for eligible Responses models. Set `compaction.remoteCompactModel` only when the compaction request should use a separate model.
|
|
132
|
+
|
|
133
|
+
When `compaction.remoteV2ContextSource` is omitted, Remote V2 keeps the original `"legacy"` input chain: first compaction uses Pi's current session context (or the supplied preparation as a last resort), and recursive compaction uses the raw branch tail. This preserves existing behavior, but can diverge from provider-visible context when other extensions rewrite messages.
|
|
134
|
+
|
|
135
|
+
Set `compaction.remoteV2ContextSource` to `"pi-context-hook"` to opt into the Pi 0.85.1 runtime bridge. The toolkit then uses the same ordered `context` hook chain as the live provider request. If Pi cannot expose that public hook path, Remote V2 cancels instead of sending an unprojected history. Checkpoint replay is accepted only when its source marker matches the current setting. Switching between the two modes requires a new Remote V2 checkpoint; disable Remote V2 or use Pi's native compaction when custom-only state must survive inside the opaque checkpoint.
|
|
136
|
+
|
|
137
|
+
### Choose a Web Search route
|
|
138
|
+
|
|
139
|
+
Web Search has three mutually exclusive routes. Configure one global default and, when needed, exact `provider/model-id` overrides:
|
|
140
|
+
|
|
141
|
+
```json
|
|
142
|
+
{
|
|
143
|
+
"webSearch": {
|
|
144
|
+
"enabled": true,
|
|
145
|
+
"defaultRoute": "hosted",
|
|
146
|
+
"routes": {
|
|
147
|
+
"uwoacrimson/gpt-6-astra": "standalone-alpha",
|
|
148
|
+
"my-gateway/gpt-5.6-luna": "local"
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
Route selection is exact and deterministic: `routes[provider/model-id]` wins over `defaultRoute`; `defaultRoute` wins over the legacy `models` list. There is no wildcard, fuzzy model matching, capability guessing, fallback, or retry between routes. Invalid route values/keys are ignored with warnings rather than guessed, and overlapping new/legacy fields produce migration warnings. `enabled: false` releases toolkit ownership and disables all three toolkit-selected paths.
|
|
155
|
+
|
|
156
|
+
- **`local`** keeps the already-installed `pi-web-access` `web_search` tool. The toolkit does not activate it when it was not active, and it does not add a hosted provider tool or `web.run`.
|
|
157
|
+
- **`hosted`** removes the local function named `web_search` and injects the native Responses `{ "type": "web_search" }` tool plus source annotations. The legacy configuration remains valid:
|
|
158
|
+
|
|
159
|
+
```json
|
|
160
|
+
{
|
|
161
|
+
"webSearch": {
|
|
162
|
+
"models": ["my-gateway/gpt-5.6-luna"]
|
|
163
|
+
}
|
|
164
|
+
}
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
With no new route fields, only models in this exact list and the existing Responses-family APIs (`openai-responses` or `openai-codex-responses`) use hosted search.
|
|
168
|
+
- **`standalone-alpha`** exposes one sequential `web.run` tool and sends one isolated `POST` request to the provider-relative `/alpha/search` endpoint. A base URL such as `https://gateway.example/v1` therefore receives `https://gateway.example/v1/alpha/search`, not a Responses endpoint. Supported command families are `search_query`, `image_query`, `open`, `click`, `find`, `screenshot`, `finance`, `weather`, `sports`, and `time`; `response_length` controls the requested result size.
|
|
169
|
+
|
|
170
|
+
The standalone route is an experimental CPA/Codex gateway protocol, not a stable public OpenAI Responses endpoint. The gateway/provider must expose `/alpha/search`, enable its `alpha-search` capability, and support standalone web search (Codex providers commonly expose this as `supports_standalone_web_search = true`). The request reuses Pi's current model, authentication, provider headers, session identity, and Codex/gateway affinity; it does not change the active model. The MVP sends the bounded command envelope rather than the full conversation transcript, relies on provider session/reference handling for `ref_id` follow-ups, makes at most one request per tool call, and fails closed on invalid configuration, unavailable routes, cancellation, timeout, non-2xx, malformed, or oversized responses.
|
|
171
|
+
|
|
172
|
+
### Generate an image
|
|
173
|
+
|
|
174
|
+
Image generation requires a Responses session and may incur provider charges. Enable it with:
|
|
175
|
+
|
|
176
|
+
```json
|
|
177
|
+
{
|
|
178
|
+
"imageGeneration": {
|
|
179
|
+
"enabled": true,
|
|
180
|
+
"models": ["gpt-image-2.5", "grok-imagine-image-2.0"]
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
`models` contains the bare model IDs used by the nested Responses `image_generation` tool. The first entry is the default; `openai_generate_image` also accepts an optional `model` argument for a one-call override, but it must match a configured entry exactly. If `models` is omitted, the default is `gpt-image-2.5`. Empty or invalid lists are ignored with a warning and fall back to that default; set `enabled` to `false` to disable the tool. The provider or gateway must support the configured image model.
|
|
186
|
+
|
|
187
|
+
The `openai_generate_image` tool supports text-to-image requests and edits using explicitly supplied local reference images.
|
|
188
|
+
|
|
189
|
+
### Review tool calls automatically
|
|
190
|
+
|
|
191
|
+
Allow a model and reviewer in `autoMode`:
|
|
192
|
+
|
|
193
|
+
```json
|
|
194
|
+
{
|
|
195
|
+
"autoMode": {
|
|
196
|
+
"models": ["my-gateway/gpt-5.6-luna"],
|
|
197
|
+
"reviewerModel": "my-gateway/gpt-5.6-luna"
|
|
198
|
+
}
|
|
199
|
+
}
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
Use `/auto on` in the session, or start Pi with `--auto`. The TUI shows an activation notice and temporarily changes the working indicator to `Auto mode: reviewing <tool>` while a gated call is being reviewed; the footer keeps the active gate visible. On Pi versions that expose the compatible tool renderer, each tool block in Auto Mode also gets a bottom line: reviewed calls show states such as `allowed by reviewer · low risk · authorization medium` or `denied · <reason>`, while calls outside the configured gate show `not reviewed · outside the configured gate`. If that renderer seam is unavailable, the extension warns once and keeps the footer-only status. The default `side-effect` gate reviews `bash`, `write`, `edit`, and configured extra tools. Set `gate` to `"all"` when every tool call needs review. A reviewer timeout does not approve a call.
|
|
203
|
+
|
|
204
|
+
## Common configuration
|
|
205
|
+
|
|
206
|
+
The config file is `~/.pi/agent/extensions/pi-openai-toolkit/config.json`. Unknown keys are ignored with a warning. Most model lists use exact `provider/model-id` strings, not globs; `imageGeneration.models` is an exception and contains bare nested image-generation model IDs.
|
|
207
|
+
|
|
208
|
+
| Key | Default | Use |
|
|
209
|
+
| --- | --- | --- |
|
|
210
|
+
| `compaction.enabled` | `true` | Master switch for compaction. |
|
|
211
|
+
| `compaction.contextManagement` | `"off"` | Enables Codex Remote Context when set to `"remote"`. |
|
|
212
|
+
| `compaction.gatewayContextModels` | `[]` | Gateway models allowed to use Remote Context. |
|
|
213
|
+
| `compaction.remoteCompactModel` | unset | Optional model used only for a v2 compaction request. |
|
|
214
|
+
| `compaction.remoteV2ContextSource` | `"legacy"` | Preserve the original raw session/branch input path. Set `"pi-context-hook"` to opt into Pi's ordered context-hook projection. Checkpoints are mode-specific. |
|
|
215
|
+
| `compaction.leaveManagedMode` | `"warn"` | What to do when a session is about to hand a model the whole durable transcript instead of its remote window. `"warn"` notices once per window and model; `"compact"` additionally runs a compaction when the retired history also passes 80% of that model's context window - on a model switch, or at the end of a turn that still has a queued rollover trim. Print (`-p`) runs and turns without a queued trim stay at the warning, because a compaction started there cannot finish. |
|
|
216
|
+
| `compaction.contextReminderThresholdPercent` | `5` | Remaining budget percentage for the once-per-window reminder. `0` disables the reminder and exhausted-window fallback. |
|
|
217
|
+
| `webSearch.enabled` | `true` | Total switch for the toolkit's Web Search route selection. `false` selects no toolkit route. |
|
|
218
|
+
| `webSearch.defaultRoute` | unset | Default route: `local`, `hosted`, or `standalone-alpha`. Unset preserves legacy behavior. |
|
|
219
|
+
| `webSearch.routes` | unset | Exact `provider/model-id` to route overrides. Exact entries take precedence over `defaultRoute`. |
|
|
220
|
+
| `webSearch.models` | `[]` | Legacy exact allowlist; without the new route fields, listed Responses-family models receive hosted Web Search. |
|
|
221
|
+
| `imageGeneration.enabled` | `false` | Enables `openai_generate_image`. |
|
|
222
|
+
| `imageGeneration.models` | `["gpt-image-2.5"]` | Bare image-generation model IDs; the first entry is the default. |
|
|
223
|
+
| `autoMode.models` | `[]` | Models allowed to use Auto Mode. |
|
|
224
|
+
| `autoMode.reviewerModel` | unset | Model that reviews Auto Mode calls. |
|
|
225
|
+
| `autoMode.gate` | `"side-effect"` | Use `"all"` to review every tool call. |
|
|
226
|
+
| `autoMode.timeoutMs` | `30000` | Review timeout in milliseconds. |
|
|
227
|
+
|
|
228
|
+
## Development
|
|
229
|
+
|
|
230
|
+
From the repository root, after dependencies are installed:
|
|
231
|
+
|
|
232
|
+
```bash
|
|
233
|
+
npm run typecheck # Type-check
|
|
234
|
+
bun test # Run tests
|
|
235
|
+
npm run test:pi # Run the Pi smoke test
|
|
236
|
+
npm pack --dry-run # Inspect the package contents
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
## License
|
|
240
|
+
|
|
241
|
+
MIT © awoaCrim and contributors. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
|