pi-openai-toolkit 0.14.4 → 0.14.5
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 +119 -147
- package/README.zh.md +119 -151
- package/package.json +127 -127
- package/src/config.ts +621 -592
- package/src/context-management/codex-provider.ts +260 -260
- package/src/context-management/history-notes.ts +325 -325
- package/src/context-management/types.ts +161 -161
- package/src/image-generation/extension.ts +19 -2
- package/src/image-generation/protocol.ts +473 -405
- package/src/image-generation/service.ts +249 -243
- package/src/image-generation/types.ts +189 -184
- package/src/responses-headers.ts +108 -108
- package/src/runtime.ts +477 -477
- package/src/types.ts +11 -0
package/README.md
CHANGED
|
@@ -1,239 +1,211 @@
|
|
|
1
1
|
# pi-openai-toolkit
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
[](./LICENSE)
|
|
5
|
-
[简体中文](./README.zh.md)
|
|
3
|
+
Add Codex context windows, Responses compaction, hosted tools, and reviewed tool calls to Pi.
|
|
6
4
|
|
|
7
|
-
|
|
5
|
+
[](https://www.npmjs.com/package/pi-openai-toolkit)
|
|
6
|
+
[](LICENSE)
|
|
8
7
|
|
|
9
|
-
|
|
8
|
+
[简体中文](README.zh.md)
|
|
10
9
|
|
|
11
10
|
## Features
|
|
12
11
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
- **Safety guarantees** - no lossy summary on covered models, credentials never leave the machine
|
|
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
|
+
| Hosted Web Search | Give selected models OpenAI's hosted search tool. |
|
|
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. |
|
|
21
19
|
|
|
22
|
-
|
|
20
|
+
The package uses Pi's existing model, authentication, and session configuration. It does not add a provider or model.
|
|
23
21
|
|
|
24
22
|
## Install
|
|
25
23
|
|
|
24
|
+
Requires Pi 0.85.1 or newer and Node.js 22.19.0 or newer.
|
|
25
|
+
|
|
26
|
+
Install the extension:
|
|
27
|
+
|
|
26
28
|
```bash
|
|
27
29
|
pi install npm:pi-openai-toolkit
|
|
28
30
|
```
|
|
29
31
|
|
|
30
|
-
|
|
32
|
+
Use `--local` to install it in the current project.
|
|
31
33
|
|
|
32
|
-
|
|
33
|
-
pi install npm:pi-openai-toolkit --local
|
|
34
|
-
```
|
|
34
|
+
Installing the package alone does not enable every feature. With no extension config, compaction is enabled but Remote Context is off, the Web Search model list is empty, image generation is disabled, and Auto Mode has no allowed models or reviewer.
|
|
35
35
|
|
|
36
|
-
|
|
36
|
+
The extension config file is:
|
|
37
37
|
|
|
38
|
-
|
|
39
|
-
pi install git:github.com/awoaCrim/pi-openai-toolkit
|
|
40
|
-
```
|
|
38
|
+
`~/.pi/agent/extensions/pi-openai-toolkit/config.json`
|
|
41
39
|
|
|
42
|
-
|
|
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.
|
|
43
41
|
|
|
44
|
-
## Quick start
|
|
42
|
+
## Quick start: enable Remote Context
|
|
45
43
|
|
|
46
|
-
|
|
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:
|
|
47
51
|
|
|
48
52
|
```json
|
|
49
53
|
{
|
|
50
54
|
"compaction": {
|
|
51
|
-
"contextManagement": "remote"
|
|
52
|
-
"contextReminderThresholdPercent": 10
|
|
55
|
+
"contextManagement": "remote"
|
|
53
56
|
}
|
|
54
57
|
}
|
|
55
58
|
```
|
|
56
59
|
|
|
57
|
-
|
|
60
|
+
Start Pi with a model from your existing Codex catalog:
|
|
58
61
|
|
|
59
62
|
```bash
|
|
60
|
-
pi --model
|
|
63
|
+
pi --model openai-codex/<model-id>
|
|
61
64
|
```
|
|
62
65
|
|
|
63
|
-
|
|
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.
|
|
64
67
|
|
|
65
|
-
|
|
68
|
+
### Use a compatible gateway
|
|
66
69
|
|
|
67
|
-
|
|
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.
|
|
68
73
|
|
|
69
74
|
```json
|
|
70
75
|
{
|
|
71
76
|
"providers": {
|
|
72
|
-
"
|
|
73
|
-
"baseUrl": "https
|
|
74
|
-
"
|
|
75
|
-
"
|
|
77
|
+
"my-gateway": {
|
|
78
|
+
"baseUrl": "https://your-gateway.example/v1",
|
|
79
|
+
"api": "openai-responses",
|
|
80
|
+
"apiKey": "$MY_GATEWAY_KEY",
|
|
76
81
|
"models": [{
|
|
77
|
-
"id": "gpt-6-
|
|
78
|
-
"name": "GPT-6
|
|
79
|
-
"api": "openai-responses",
|
|
82
|
+
"id": "gpt-5.6-luna",
|
|
83
|
+
"name": "GPT-5.6 Luna",
|
|
80
84
|
"reasoning": true,
|
|
81
85
|
"input": ["text"],
|
|
82
86
|
"contextWindow": 272000,
|
|
83
|
-
"maxTokens":
|
|
84
|
-
"compat": {"thinkingLevelMap": {"off": 0, "minimal": 0.1, "low": 0.2, "medium": 0.5, "high": 1, "xhigh": 2, "max": 2}}
|
|
87
|
+
"maxTokens": 128000
|
|
85
88
|
}]
|
|
86
89
|
}
|
|
87
90
|
}
|
|
88
91
|
}
|
|
89
92
|
```
|
|
90
93
|
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
### Codex Remote Context
|
|
94
|
-
|
|
95
|
-
This is Codex's own context-window mechanism, implemented for Pi by this toolkit. Covered sessions run like they do in the Codex client: the model works in context windows, checkpoints state into `notes`, and calls `new_context` before the window fills. Nothing is summarized; earlier windows remain fully readable through `history`. A rollover is refused unless a notes checkpoint succeeded in the current window, and the session survives resume and fork with the same rules. Reminder and exhausted-window messages only advise the model; every rollover is the model's own tool call.
|
|
94
|
+
Set the referenced key before starting Pi. In PowerShell:
|
|
96
95
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
96
|
+
```powershell
|
|
97
|
+
$env:MY_GATEWAY_KEY = "replace-with-your-gateway-key"
|
|
98
|
+
```
|
|
100
99
|
|
|
101
|
-
|
|
100
|
+
In a POSIX shell:
|
|
102
101
|
|
|
103
|
-
|
|
102
|
+
```bash
|
|
103
|
+
export MY_GATEWAY_KEY="replace-with-your-gateway-key"
|
|
104
|
+
```
|
|
104
105
|
|
|
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:
|
|
106
107
|
|
|
107
108
|
```json
|
|
108
109
|
{
|
|
109
|
-
"
|
|
110
|
+
"compaction": {
|
|
111
|
+
"contextManagement": "remote",
|
|
112
|
+
"gatewayContextModels": ["my-gateway/gpt-5.6-luna"]
|
|
113
|
+
}
|
|
110
114
|
}
|
|
111
115
|
```
|
|
112
116
|
|
|
113
|
-
|
|
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.
|
|
114
132
|
|
|
115
|
-
###
|
|
133
|
+
### Enable hosted Web Search
|
|
134
|
+
|
|
135
|
+
List exact model specifications under `webSearch.models`:
|
|
116
136
|
|
|
117
137
|
```json
|
|
118
138
|
{
|
|
119
|
-
"
|
|
139
|
+
"webSearch": {
|
|
140
|
+
"models": ["my-gateway/gpt-5.6-luna"]
|
|
141
|
+
}
|
|
120
142
|
}
|
|
121
143
|
```
|
|
122
144
|
|
|
123
|
-
|
|
145
|
+
For those models, the extension replaces Pi's local `web_search` tool with OpenAI's hosted Responses search tool.
|
|
124
146
|
|
|
125
|
-
###
|
|
147
|
+
### Generate an image
|
|
148
|
+
|
|
149
|
+
Image generation requires a Responses session and may incur provider charges. Enable it with:
|
|
126
150
|
|
|
127
151
|
```json
|
|
128
152
|
{
|
|
129
|
-
"
|
|
153
|
+
"imageGeneration": {
|
|
130
154
|
"enabled": true,
|
|
131
|
-
"models": ["
|
|
132
|
-
"reviewerModel": "uwoacrimson/gpt-5.6-luna"
|
|
155
|
+
"models": ["gpt-image-2.5", "grok-imagine-image-2.0"]
|
|
133
156
|
}
|
|
134
157
|
}
|
|
135
158
|
```
|
|
136
159
|
|
|
137
|
-
|
|
160
|
+
`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.
|
|
138
161
|
|
|
139
|
-
|
|
162
|
+
The `openai_generate_image` tool supports text-to-image requests and edits using explicitly supplied local reference images.
|
|
140
163
|
|
|
141
|
-
|
|
164
|
+
### Review tool calls automatically
|
|
142
165
|
|
|
143
|
-
|
|
144
|
-
<summary><b>Full option reference</b> (compaction, webSearch, imageGeneration, autoMode)</summary>
|
|
166
|
+
Allow a model and reviewer in `autoMode`:
|
|
145
167
|
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
| `allowCompactionContinuityBreak` | *boolean*, `false` | v2: rebuild a fresh encrypted chain when the latest compaction came from another strategy (e.g. a pre-install text summary). |
|
|
155
|
-
| `remoteCompactModel` | *string \| null*, `null` | v2: model for the server-side compaction request only; the session model never switches. Must resolve to the same base URL as the active model. |
|
|
156
|
-
| `nativeFallback.enabled` | *boolean*, `true` | Native compaction fallback, only after a remote attempt actually failed. |
|
|
157
|
-
| `nativeFallback.model` | *string \| null*, `null` | Summary model for models that cannot use v2 at all. `null` keeps the active model. |
|
|
158
|
-
| `nativeFallback.thinkingLevel` | *string*, `"off"` | Thinking level for the fallback summary (`off`...`max`). |
|
|
159
|
-
| `responsesApis` | *string[]*, both APIs | Which Responses API identifiers may use v2 compaction. v2 only applies to models that Remote Context does not cover. |
|
|
160
|
-
| `notifyOnLoad` | *boolean*, `false` | Startup banner. |
|
|
161
|
-
| `debug` | *boolean*, `false` | Write lifecycle and compaction artifacts under `artifactRoot`, including the activation reason per `session_start`. |
|
|
162
|
-
| `logProviderPayloads` / `logCompactResponses` | *boolean*, `false` | Also write raw provider payloads and SSE bodies. Off unless debugging one request. |
|
|
163
|
-
| `redactSensitiveData` | *boolean*, `true` | Artifact redaction; credentials, account ids, and encrypted payloads are always redacted. |
|
|
164
|
-
| `artifactRoot` | *string*, `~/.pi/agent/artifacts/pi-openai-toolkit/compaction` | Artifact root; relative paths resolve against the config directory. |
|
|
165
|
-
|
|
166
|
-
### `webSearch`
|
|
167
|
-
|
|
168
|
-
| Key | Type / default | Meaning |
|
|
169
|
-
| --- | --- | --- |
|
|
170
|
-
| `enabled` | *boolean*, `true` | Master switch. |
|
|
171
|
-
| `models` | *string[]*, `[]` | Sessions receiving OpenAI's hosted `web_search`: the local `web_search` tool is removed and the native responses-API tool injected. |
|
|
168
|
+
```json
|
|
169
|
+
{
|
|
170
|
+
"autoMode": {
|
|
171
|
+
"models": ["my-gateway/gpt-5.6-luna"],
|
|
172
|
+
"reviewerModel": "my-gateway/gpt-5.6-luna"
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
```
|
|
172
176
|
|
|
173
|
-
|
|
177
|
+
Use `/auto on` in the session. 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.
|
|
174
178
|
|
|
175
|
-
|
|
176
|
-
| --- | --- | --- |
|
|
177
|
-
| `enabled` | *boolean*, `false` | Exposes `openai_generate_image` to all Responses-wire sessions. No model allowlist by design. |
|
|
179
|
+
## Common configuration
|
|
178
180
|
|
|
179
|
-
|
|
181
|
+
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.
|
|
180
182
|
|
|
181
|
-
| Key |
|
|
183
|
+
| Key | Default | Use |
|
|
182
184
|
| --- | --- | --- |
|
|
183
|
-
| `enabled` |
|
|
184
|
-
| `
|
|
185
|
-
| `
|
|
186
|
-
| `
|
|
187
|
-
| `
|
|
188
|
-
| `
|
|
189
|
-
| `
|
|
190
|
-
| `
|
|
191
|
-
| `
|
|
192
|
-
| `
|
|
193
|
-
| `
|
|
194
|
-
|
|
195
|
-
### `codexAstra`
|
|
196
|
-
|
|
197
|
-
Removed section. The Astra compatibility layer activates silently for any `gpt-6-astra` session on a Responses-family API; old `codexAstra` config sections are ignored with a warning. If another host (e.g. Oh My Pi) implements the same rewrite, enable only one.
|
|
198
|
-
|
|
199
|
-
</details>
|
|
200
|
-
|
|
201
|
-
## Security
|
|
202
|
-
|
|
203
|
-
- On covered models, every Pi-native compaction path (threshold, manual `/compact`, overflow) is cancelled while Remote Context owns the session; no lossy summary is possible.
|
|
204
|
-
- Gateway mode forwards only the configured data-plane API key. OAuth tokens, account cookies, and account ids are never sent to a gateway and are always redacted from artifacts.
|
|
205
|
-
- `new_context` cannot discard unsaved state: a successful notes checkpoint (or explicit user `force`) is required.
|
|
206
|
-
- Image generation (billed) and Auto Mode are opt-in; Auto Mode fails closed where nobody can approve.
|
|
207
|
-
|
|
208
|
-
For host-level insurance, set `"compaction": { "enabled": false }` in Pi's `settings.json`.
|
|
185
|
+
| `compaction.enabled` | `true` | Master switch for compaction. |
|
|
186
|
+
| `compaction.contextManagement` | `"off"` | Enables Codex Remote Context when set to `"remote"`. |
|
|
187
|
+
| `compaction.gatewayContextModels` | `[]` | Gateway models allowed to use Remote Context. |
|
|
188
|
+
| `compaction.remoteCompactModel` | unset | Optional model used only for a v2 compaction request. |
|
|
189
|
+
| `compaction.contextReminderThresholdPercent` | `5` | Remaining budget percentage for the once-per-window reminder. `0` disables the reminder and exhausted-window fallback. |
|
|
190
|
+
| `webSearch.models` | `[]` | Models that receive hosted Web Search. |
|
|
191
|
+
| `imageGeneration.enabled` | `false` | Enables `openai_generate_image`. |
|
|
192
|
+
| `imageGeneration.models` | `["gpt-image-2.5"]` | Bare image-generation model IDs; the first entry is the default. |
|
|
193
|
+
| `autoMode.models` | `[]` | Models allowed to use Auto Mode. |
|
|
194
|
+
| `autoMode.reviewerModel` | unset | Model that reviews Auto Mode calls. |
|
|
195
|
+
| `autoMode.gate` | `"side-effect"` | Use `"all"` to review every tool call. |
|
|
196
|
+
| `autoMode.timeoutMs` | `30000` | Review timeout in milliseconds. |
|
|
209
197
|
|
|
210
198
|
## Development
|
|
211
199
|
|
|
200
|
+
From the repository root, after dependencies are installed:
|
|
201
|
+
|
|
212
202
|
```bash
|
|
213
|
-
npm run typecheck #
|
|
214
|
-
bun test #
|
|
215
|
-
npm run test:pi # Pi
|
|
216
|
-
npm pack --dry-run #
|
|
203
|
+
npm run typecheck # Type-check
|
|
204
|
+
bun test # Run tests
|
|
205
|
+
npm run test:pi # Run the Pi smoke test
|
|
206
|
+
npm pack --dry-run # Inspect the package contents
|
|
217
207
|
```
|
|
218
208
|
|
|
219
|
-
## Documentation
|
|
220
|
-
|
|
221
|
-
- [docs/internals.md](docs/internals.md) - protocol endpoints, rollover lifecycle, v2 wire contract, artifacts, provenance
|
|
222
|
-
- [README.zh.md](README.zh.md) - 简体中文
|
|
223
|
-
- [NOTICE](./NOTICE) - third-party attribution
|
|
224
|
-
|
|
225
|
-
## Contributing
|
|
226
|
-
|
|
227
|
-
Issues and pull requests are welcome at the [issue tracker](https://github.com/awoaCrim/pi-openai-toolkit/issues). Open an issue before behavior-changing work so protocol assumptions can be discussed. Run `bun test` and `npm run typecheck` before submitting; new wire behavior needs fixture-based tests.
|
|
228
|
-
|
|
229
|
-
## Maintainers
|
|
230
|
-
|
|
231
|
-
[awoaCrim](https://github.com/awoaCrim)
|
|
232
|
-
|
|
233
209
|
## License
|
|
234
210
|
|
|
235
|
-
MIT © awoaCrim and contributors. See [LICENSE](
|
|
236
|
-
|
|
237
|
-
## Thanks
|
|
238
|
-
|
|
239
|
-
Thanks to the [Linux.do](https://linux.do/) community for the support and discussions.
|
|
211
|
+
MIT © awoaCrim and contributors. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
|