pi-openai-toolkit 0.14.1 → 0.14.3
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 +251 -246
- package/README.zh.md +251 -246
- package/package.json +1 -1
- package/src/context-management/window-manager.ts +479 -421
- package/src/extension-runtime.ts +12 -1
package/README.md
CHANGED
|
@@ -1,246 +1,251 @@
|
|
|
1
|
-
# pi-openai-toolkit
|
|
2
|
-
|
|
3
|
-
[](https://www.npmjs.com/package/pi-openai-toolkit)
|
|
4
|
-
[](./LICENSE)
|
|
5
|
-
|
|
6
|
-
[简体中文](./README.zh.md)
|
|
7
|
-
|
|
8
|
-
OpenAI toolkit for Pi: Codex Remote Context windows, remote compaction v2, hosted Web Search, image gen, auto mode.
|
|
9
|
-
|
|
10
|
-
`pi-openai-toolkit` bundles five Pi extensions for the OpenAI Responses wire family (`openai-responses` and `openai-codex-responses`):
|
|
11
|
-
|
|
12
|
-
1. **Compaction & Remote Context** (`extensions/compaction.ts`): two long-context strategies. [Codex Remote Context management](#codex-remote-context-management) ports Codex's native window lifecycle to Pi — no-summary `new_context` rollover with a hard notes-checkpoint gate, cross-window `history` / `notes` tools with encrypted argument transport, and budgeted checkpoint reminders. With it off, the extension runs **Remote Compaction v2**: server-side opaque encrypted compaction that never re-summarizes your conversation into lossy text.
|
|
13
|
-
2. **Web Search** (`extensions/web-search.ts`): hosted `web_search` injection for an exact `provider/model-id` allowlist, reusing the live model connection.
|
|
14
|
-
3. **Image Generation** (`extensions/image-generation.ts`): a local `openai_generate_image` tool backed by the hosted `image_generation` tool, for text-to-image and explicit local-reference edits without putting image bytes into session history.
|
|
15
|
-
4. **Auto Mode** (`extensions/auto-mode.ts`): a reviewer-model approval gate on state-changing tool calls so the agent keeps working without interrupting you.
|
|
16
|
-
5. **Codex Astra** (`extensions/codex-astra.ts`): Codex backend version-gate headers and cache-preserving `configuration_update` effort changes for `gpt-6-astra`. Activated silently by model id; no configuration section.
|
|
17
|
-
|
|
18
|
-
The package is a Pi extension set, not an importable library: everything is configured through one JSON file and activated automatically inside Pi.
|
|
19
|
-
|
|
20
|
-
## Table of Contents
|
|
21
|
-
- [Security](#security)
|
|
22
|
-
- [Background](#background)
|
|
23
|
-
- [Install](#install)
|
|
24
|
-
- [Usage](#usage)
|
|
25
|
-
- [Configuration](#configuration)
|
|
26
|
-
- [Feature guides](#feature-guides)
|
|
27
|
-
- [Development](#development)
|
|
28
|
-
- [API](#api)
|
|
29
|
-
- [Remote Context tools](#remote-context-tools)
|
|
30
|
-
- [HTTP protocol reference](#http-protocol-reference)
|
|
31
|
-
- [Maintainers](#maintainers)
|
|
32
|
-
- [Contributing](#contributing)
|
|
33
|
-
- [License](#license)
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
- **
|
|
39
|
-
- **
|
|
40
|
-
- **
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
"
|
|
87
|
-
"
|
|
88
|
-
"
|
|
89
|
-
"
|
|
90
|
-
"
|
|
91
|
-
"
|
|
92
|
-
"
|
|
93
|
-
"
|
|
94
|
-
"
|
|
95
|
-
"
|
|
96
|
-
"
|
|
97
|
-
"
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
"
|
|
101
|
-
"
|
|
102
|
-
|
|
103
|
-
"
|
|
104
|
-
"
|
|
105
|
-
"
|
|
106
|
-
|
|
107
|
-
}
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
|
124
|
-
|
|
|
125
|
-
| `
|
|
126
|
-
| `
|
|
127
|
-
| `
|
|
128
|
-
| `
|
|
129
|
-
| `
|
|
130
|
-
| `nativeFallback.
|
|
131
|
-
| `nativeFallback.
|
|
132
|
-
| `
|
|
133
|
-
| `
|
|
134
|
-
| `
|
|
135
|
-
| `
|
|
136
|
-
| `
|
|
137
|
-
| `
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
|
143
|
-
|
|
|
144
|
-
| `
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
|
150
|
-
|
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
|
156
|
-
|
|
|
157
|
-
| `
|
|
158
|
-
| `
|
|
159
|
-
| `
|
|
160
|
-
| `
|
|
161
|
-
| `
|
|
162
|
-
| `
|
|
163
|
-
| `
|
|
164
|
-
| `
|
|
165
|
-
| `
|
|
166
|
-
| `
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
- **
|
|
182
|
-
- **
|
|
183
|
-
- **
|
|
184
|
-
- **
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
npm
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
|
217
|
-
|
|
|
218
|
-
| `
|
|
219
|
-
| `
|
|
220
|
-
| `
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
POST {base}/alpha/
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
1
|
+
# pi-openai-toolkit
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/pi-openai-toolkit)
|
|
4
|
+
[](./LICENSE)
|
|
5
|
+
|
|
6
|
+
[简体中文](./README.zh.md)
|
|
7
|
+
|
|
8
|
+
OpenAI toolkit for Pi: Codex Remote Context windows, remote compaction v2, hosted Web Search, image gen, auto mode.
|
|
9
|
+
|
|
10
|
+
`pi-openai-toolkit` bundles five Pi extensions for the OpenAI Responses wire family (`openai-responses` and `openai-codex-responses`):
|
|
11
|
+
|
|
12
|
+
1. **Compaction & Remote Context** (`extensions/compaction.ts`): two long-context strategies. [Codex Remote Context management](#codex-remote-context-management) ports Codex's native window lifecycle to Pi — no-summary `new_context` rollover with a hard notes-checkpoint gate, cross-window `history` / `notes` tools with encrypted argument transport, and budgeted checkpoint reminders. With it off, the extension runs **Remote Compaction v2**: server-side opaque encrypted compaction that never re-summarizes your conversation into lossy text.
|
|
13
|
+
2. **Web Search** (`extensions/web-search.ts`): hosted `web_search` injection for an exact `provider/model-id` allowlist, reusing the live model connection.
|
|
14
|
+
3. **Image Generation** (`extensions/image-generation.ts`): a local `openai_generate_image` tool backed by the hosted `image_generation` tool, for text-to-image and explicit local-reference edits without putting image bytes into session history.
|
|
15
|
+
4. **Auto Mode** (`extensions/auto-mode.ts`): a reviewer-model approval gate on state-changing tool calls so the agent keeps working without interrupting you.
|
|
16
|
+
5. **Codex Astra** (`extensions/codex-astra.ts`): Codex backend version-gate headers and cache-preserving `configuration_update` effort changes for `gpt-6-astra`. Activated silently by model id; no configuration section.
|
|
17
|
+
|
|
18
|
+
The package is a Pi extension set, not an importable library: everything is configured through one JSON file and activated automatically inside Pi.
|
|
19
|
+
|
|
20
|
+
## Table of Contents
|
|
21
|
+
- [Security](#security)
|
|
22
|
+
- [Background](#background)
|
|
23
|
+
- [Install](#install)
|
|
24
|
+
- [Usage](#usage)
|
|
25
|
+
- [Configuration](#configuration)
|
|
26
|
+
- [Feature guides](#feature-guides)
|
|
27
|
+
- [Development](#development)
|
|
28
|
+
- [API](#api)
|
|
29
|
+
- [Remote Context tools](#remote-context-tools)
|
|
30
|
+
- [HTTP protocol reference](#http-protocol-reference)
|
|
31
|
+
- [Maintainers](#maintainers)
|
|
32
|
+
- [Contributing](#contributing)
|
|
33
|
+
- [License](#license)
|
|
34
|
+
- [Thanks](#thanks)
|
|
35
|
+
|
|
36
|
+
## Security
|
|
37
|
+
|
|
38
|
+
- **No silent lossy summaries on covered models.** While `contextManagement: "remote"` covers a model, Pi-native compaction is cancelled on every path (threshold, manual `/compact`, overflow) even if the remote runtime is inactive, and v2 is never sent. If you additionally want host-level belt-and-braces, set `"compaction": { "enabled": false }` in Pi's `settings.json`; uncovered models keep Pi's normal policy either way.
|
|
39
|
+
- **Gateway isolation.** Gateway-mode Remote Context forwards only the configured data-plane key; OAuth tokens, account cookies, and account ids are stripped, and artifacts always redact credentials, account ids, and opaque encrypted payloads.
|
|
40
|
+
- **Checkpoint gate.** `new_context` cannot discard unsaved working state without either a successful notes write in the window or an explicit `force` the user authorized — the failure mode reported against Codex's own experimental rollout is blocked here.
|
|
41
|
+
- **Billing and review boundaries.** Image generation is opt-in and may incur charges; auto mode reviews run with caching disabled, grant the reviewer read-only tools only, and fail closed in headless sessions.
|
|
42
|
+
|
|
43
|
+
## Background
|
|
44
|
+
|
|
45
|
+
Pi's built-in compaction summarizes old turns into text, which loses detail; the OpenAI Codex backend instead offers two lossless mechanisms that plain clients do not get for free: the `remote_compaction_v2` SSE protocol (an encrypted opaque checkpoint replaces the summarized prefix) and the experimental **context-window system** (`new_context`, `history`, `notes`) that rolls the window over without any summary at all. This toolkit implements both against the live backends, verified end to end on Codex OAuth and on a Codex-compatible gateway relay (NEWapi + CLIProxyAPI).
|
|
46
|
+
|
|
47
|
+
Provenance: the Remote Context protocol was reverse-engineered from `@howaboua/pi-codex-conversion@3.0.29` (source commit `7021ae48e8efe36a3becc5830d529696ff798e5e`); the Astra compatibility layer is adapted from Oh My Pi 18.1.8 (MIT); Web Search behavior was adapted from [`pi-openai-web-search`](https://github.com/code-yeongyu/pi-openai-web-search) (commit `3964338`). Attribution details are in [NOTICE](./NOTICE). The alpha `history`/`notes` endpoints may change upstream without notice; endpoint and header fixtures in this repository must be updated together with them.
|
|
48
|
+
|
|
49
|
+
Requires **Pi >= 0.85.1** and **Node.js >= 22.19.0**. Pi supplies the model catalog and Codex/API-key login; this toolkit never implements its own login flow and never touches the credential store directly.
|
|
50
|
+
|
|
51
|
+
## Install
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
pi install npm:pi-openai-toolkit
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
This registers the package in Pi's global settings; verify with `pi list`. For a single project instead:
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
pi install npm:pi-openai-toolkit --local
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
From git (development or pinned builds):
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
pi install git:github.com/awoaCrim/pi-openai-toolkit
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### Updating
|
|
70
|
+
|
|
71
|
+
`pi update --extensions` updates Pi packages including this toolkit. Published versions are on [npm](https://www.npmjs.com/package/pi-openai-toolkit).
|
|
72
|
+
|
|
73
|
+
### Conflict warning
|
|
74
|
+
|
|
75
|
+
Do not run `pi-remote-compact`, `@lll9p/pi-better-compaction`, or a standalone `pi-openai-web-search` alongside this toolkit: duplicate hooks cause race conditions and duplicated system prompts.
|
|
76
|
+
|
|
77
|
+
## Usage
|
|
78
|
+
|
|
79
|
+
All features are controlled by one configuration file, plus per-session commands. With no config file present, compaction runs with its defaults; Web Search, image generation, auto mode, and Remote Context stay opt-in. The Astra compatibility layer and gateway Remote Context are keyed off the built-in `gpt-6-astra` model id, not off any allowlist.
|
|
80
|
+
|
|
81
|
+
Create `~/.pi/agent/extensions/pi-openai-toolkit/config.json` (Windows: `C:\Users\<user>\.pi\agent\extensions\pi-openai-toolkit\config.json`):
|
|
82
|
+
|
|
83
|
+
```json
|
|
84
|
+
{
|
|
85
|
+
"compaction": {
|
|
86
|
+
"enabled": true,
|
|
87
|
+
"contextManagement": "remote",
|
|
88
|
+
"contextReminderThresholdPercent": 10,
|
|
89
|
+
"allowCompactionContinuityBreak": false,
|
|
90
|
+
"remoteCompactModel": "uwoacrimson/gpt-5.6-luna",
|
|
91
|
+
"nativeFallback": { "enabled": true, "model": null, "thinkingLevel": "off" },
|
|
92
|
+
"responsesApis": ["openai-responses", "openai-codex-responses"],
|
|
93
|
+
"notifyOnLoad": false,
|
|
94
|
+
"debug": false,
|
|
95
|
+
"logProviderPayloads": false,
|
|
96
|
+
"logCompactResponses": false,
|
|
97
|
+
"redactSensitiveData": true,
|
|
98
|
+
"artifactRoot": "~/.pi/agent/artifacts/pi-openai-toolkit/compaction"
|
|
99
|
+
},
|
|
100
|
+
"webSearch": { "enabled": true, "models": ["uwoacrimson/gpt-5.6-luna"] },
|
|
101
|
+
"imageGeneration": { "enabled": false },
|
|
102
|
+
"autoMode": {
|
|
103
|
+
"enabled": true,
|
|
104
|
+
"models": ["uwoacrimson/gpt-5.6-luna"],
|
|
105
|
+
"reviewerModel": "uwoacrimson/gpt-5.6-luna",
|
|
106
|
+
"gate": "side-effect"
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Then start Pi as usual; the toolkit loads automatically and hooks every session:
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
pi --model uwoacrimson/gpt-6-astra "resume the deploy task"
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
### Configuration
|
|
118
|
+
|
|
119
|
+
Every key is optional; unknown keys are ignored with a warning rather than written back to your file. `models`-style keys are exact `provider/model-id` allowlists — trimming only, no globbing — so each feature is off until you list a model for it.
|
|
120
|
+
|
|
121
|
+
#### `compaction`
|
|
122
|
+
|
|
123
|
+
| Key | Type / default | Meaning |
|
|
124
|
+
| --- | --- | --- |
|
|
125
|
+
| `enabled` | *boolean*, `true` | Master switch for the compaction extension's hooks. |
|
|
126
|
+
| `contextManagement` | `"off"` \| `"remote"`, `"off"` | Opt into Codex Remote Context management. Covered models are native Codex models plus `gpt-6-astra` on a Codex-compatible gateway (`openai-responses`); the match is built in, there is no allowlist. While it owns a covered model, `remote_compaction_v2` is never sent and Pi-native compaction is cancelled (see [Security](#security)). Set back to `"off"` to roll back. |
|
|
127
|
+
| `contextReminderThresholdPercent` | *integer* `0`-`100`, `5` | Remote Context: inject the once-per-window checkpoint reminder when remaining tokens fall below this percentage of the context window. `0` disables reminders; the exhausted-window fallback still fires. Set it comfortably above Pi's native reserve band (default 16384 tokens ≈ 6% of a 272k window) so the model can roll over before the native threshold. |
|
|
128
|
+
| `allowCompactionContinuityBreak` | *boolean*, `false` | v2 path: restart a fresh opaque chain from current session text when the latest compaction was made by another strategy (e.g. a text summary). |
|
|
129
|
+
| `remoteCompactModel` | *string \| null*, `null` | v2 path: `provider/model-id` used only for the synthetic `remote_compaction_v2` request; the session model never switches. Must resolve to the same effective base URL as the active model. |
|
|
130
|
+
| `nativeFallback.enabled` | *boolean*, `true` | Toolkit-driven native compaction with an explicit summary model when the remote request was attempted and failed. Never touches a successful remote chain. |
|
|
131
|
+
| `nativeFallback.model` | *string \| null*, `null` | Summary model for models that cannot use v2 at all (non-Responses API, or excluded via `responsesApis`). `null` keeps the active model. |
|
|
132
|
+
| `nativeFallback.thinkingLevel` | *string*, `"off"` | Thinking level passed to Pi's `compact()` when this extension supplies the model (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`). |
|
|
133
|
+
| `responsesApis` | *string[]*, both APIs | Narrow which Responses API identifiers may use remote compaction. Applies only when `contextManagement` is `"off"`. |
|
|
134
|
+
| `notifyOnLoad` | *boolean*, `false` | Startup notification banner. |
|
|
135
|
+
| `debug` | *boolean*, `false` | Write lifecycle and compaction artifacts under `artifactRoot`, including the Remote Context activation reason per `session_start`. |
|
|
136
|
+
| `logProviderPayloads` / `logCompactResponses` | *boolean*, `false` | Additionally write raw provider request payloads and compact SSE bodies to artifacts. Keep off unless inspecting a specific request. |
|
|
137
|
+
| `redactSensitiveData` | *boolean*, `true` | Full artifact redaction. Authorization credentials, API keys/tokens, Codex account ids, and opaque `encrypted_content` / `encrypted_output` are always redacted even when this is `false`. |
|
|
138
|
+
| `artifactRoot` | *string*, `~/.pi/agent/artifacts/pi-openai-toolkit/compaction` | Artifact directory root; relative paths resolve against the config directory. |
|
|
139
|
+
|
|
140
|
+
#### `webSearch`
|
|
141
|
+
|
|
142
|
+
| Key | Type / default | Meaning |
|
|
143
|
+
| --- | --- | --- |
|
|
144
|
+
| `enabled` | *boolean*, `true` | Master switch. |
|
|
145
|
+
| `models` | *string[]*, `[]` | Exact allowlist of `provider/model-id` sessions that receive hosted `web_search` injection on `openai-responses` / `openai-codex-responses`. For a listed model the local `web_search` function tool is removed from the payload so native search is the only path; switching away restores it. |
|
|
146
|
+
|
|
147
|
+
#### `imageGeneration`
|
|
148
|
+
|
|
149
|
+
| Key | Type / default | Meaning |
|
|
150
|
+
| --- | --- | --- |
|
|
151
|
+
| `enabled` | *boolean*, `false` | Single opt-in switch for the `openai_generate_image` tool. Off by default because every successful request may incur a charge. No model allowlist: the hosted tool is a capability of the Responses API, so it is exposed to every active model on a Responses wire and hidden elsewhere. |
|
|
152
|
+
|
|
153
|
+
#### `autoMode`
|
|
154
|
+
|
|
155
|
+
| Key | Type / default | Meaning |
|
|
156
|
+
| --- | --- | --- |
|
|
157
|
+
| `enabled` | *boolean*, `true` | Master switch; the mode still cannot engage until a model is allowlisted and `reviewerModel` is set. |
|
|
158
|
+
| `models` | *string[]*, `[]` | Allowlist of active session models permitted to run in auto mode. |
|
|
159
|
+
| `reviewerModel` | *string \| null*, `null` | Approving model (`provider/model-id`, resolved through Pi's registry). Used only for one-off reviews; never becomes the conversation model. |
|
|
160
|
+
| `gate` | `"side-effect"` \| `"all"`, `"side-effect"` | Which tool calls are reviewed. `/auto all` flips the session scope to everything. |
|
|
161
|
+
| `extraTools` | *string[]*, `[]` | Additional reviewed names on top of the side-effect set (`bash`, `write`, `edit`). |
|
|
162
|
+
| `timeoutMs` | *integer* 1000-120000, `30000` | Reviewer deadline across all rounds. Expiry is never approval. |
|
|
163
|
+
| `transcript` | *boolean*, `true` | Give the reviewer a bounded view of the conversation so it can judge authorization, not just intrinsic risk. |
|
|
164
|
+
| `evidenceTools` | *boolean*, `true` | Let the reviewer run Pi's read-only tools (`read`, `grep`, `find`, `ls`) to establish facts. It never receives `bash`, write tools, or network access. |
|
|
165
|
+
| `maxEvidenceRounds` | *integer* 0-8, `3` | Investigation rounds before the reviewer must answer; `0` is a single completion. |
|
|
166
|
+
| `classifier.*` | see code comments | Optional non-blocking low-risk pre-scorer (`enabled` `false`, `model`, `timeoutMs` `15000`, `maxLag` `2`). Can only fast-path ordinary calls, never deny. |
|
|
167
|
+
| `circuitBreaker.*` | — | Denials that end the turn instead of letting agent and reviewer negotiate forever (`consecutiveDenials` `3`, `recentDenials` `10` within `windowSize` `50`; `0` disables). |
|
|
168
|
+
|
|
169
|
+
#### `codexAstra`
|
|
170
|
+
|
|
171
|
+
Removed. The Astra compatibility layer (backend version-gate headers for all `openai-codex-responses` requests, plus the cache-preserving `configuration_update` effort rewrite) now activates silently for any model whose id is `gpt-6-astra` on a Responses-family API — no configuration needed, and old `codexAstra` sections in existing configs are ignored with an unknown-field warning. Only caveat left: do not run it together with another host that implements the same rewrite (e.g. Oh My Pi) to avoid double-splicing.
|
|
172
|
+
|
|
173
|
+
Catalog note: Pi's bundled `openai-codex` list may not include `gpt-6-astra` yet. Register it in `~/.pi/agent/models.json` under the built-in provider (`api: "openai-codex-responses"`, `baseUrl: "https://chatgpt.com/backend-api"`, `contextWindow: 272000`, `maxTokens: 128000`, `thinkingLevelMap` `low`…`max`); Pi's Codex OAuth supplies the token.
|
|
174
|
+
|
|
175
|
+
### Feature guides
|
|
176
|
+
|
|
177
|
+
#### Codex Remote Context management
|
|
178
|
+
|
|
179
|
+
When `contextManagement` is `"remote"` and the session model is covered (native `openai-codex`, or `gpt-6-astra` on `openai-responses`; the model match is built in), the toolkit takes the session through the Codex window lifecycle:
|
|
180
|
+
|
|
181
|
+
- **Window identity.** `session_start` initializes a window (first/current/previous ids, window number) persisted as a `codex-context-window` custom message in the Pi session; boundaries replay on resume and rebuild after forks. Live requests carry `x-codex-window-id` and `x-codex-turn-metadata`.
|
|
182
|
+
- **No-summary rollover.** `new_context` installs a fresh window and trims the previous one from model context. Nothing is re-summarized; old turns stay retrievable server-side through `history`.
|
|
183
|
+
- **Checkpoint gate.** A rollover requires a *successful* `notes` `append_to_file` / `write_file` inside the current window, verified against the persisted session branch (so it survives restarts). Without it, `new_context` refuses; `force: true` is the explicit user-authorized escape, and the toolkit's exhausted-context fallback bypasses the gate automatically after instructing one final notes write.
|
|
184
|
+
- **Budget.** `get_context_remaining` reports the live window budget; `contextReminderThresholdPercent` controls the once-per-window checkpoint reminder.
|
|
185
|
+
- **Ownership.** For covered models the toolkit owns every compaction event: `remote_compaction_v2` is not sent, and Pi-native compaction is cancelled on all paths — including while the remote runtime is temporarily inactive, so no lossy summary can slip in behind its back. The inactive reason is surfaced as a notification (and in the `session_start` lifecycle artifact when `debug` is on); fix that cause rather than expecting compaction.
|
|
186
|
+
|
|
187
|
+
The native route reuses Pi's Codex OAuth through `ModelRegistry`; gateway route requests use the configured data-plane API key only — local OAuth credentials, account cookies, and account ids are never forwarded to a gateway.
|
|
188
|
+
|
|
189
|
+
**Verifying activation.** After `/reload` or a new session, the session should contain a `codex-context-window` boundary message and `new_context` / `get_context_remaining` / `history` / `notes` tools. With `debug: true`, each `session_start` writes a lifecycle artifact under `artifactRoot` whose `activation` field records `active` and, when inactive, the exact reason (e.g. `tool-name-conflict`, `missing-api-key`, `auth-resolution-failed`).
|
|
190
|
+
|
|
191
|
+
#### Remote Compaction v2
|
|
192
|
+
|
|
193
|
+
With `contextManagement` off, eligible Responses sessions compact through `remote_compaction_v2`: a `compaction_trigger` item appended to the live streaming request yields one output item of `type: "compaction"` with non-empty `encrypted_content`, stored in `CompactionEntry.details.compactedWindow`. On later requests the opaque checkpoint is replayed ahead of live turns — zero-loss, no text summary. Replay fails closed: if the summary anchor cannot be located, the request is aborted with a notification and a content-free failure artifact; the sentinel-only payload is never sent. Fallback tiers: a failed remote attempt may use Pi's native compaction (`remoteCompactModel`/active model); models that cannot use v2 at all use `nativeFallback`. Pi 0.85.1+ owns automatic compaction driving; the toolkit never starts its own driver.
|
|
194
|
+
|
|
195
|
+
#### Auto Mode
|
|
196
|
+
|
|
197
|
+
Engage per session with `pi --auto` or `/auto on` (footer shows state; engaging never stalls the current turn). Each gated call is reviewed by `reviewerModel`, which scores intrinsic risk and conversation authorization separately and derives `allow`/`deny` from a fixed table; it may investigate with read-only tools first; denials return the reason plus an anti-workaround clause; unfinished reviews are reported as failures, never safety verdicts. Every decision is persisted as a non-context session entry for audit. In headless (`-p`/JSON) sessions there is nobody to escalate to, so unavailable reviews block.
|
|
198
|
+
|
|
199
|
+
## Development
|
|
200
|
+
|
|
201
|
+
```bash
|
|
202
|
+
npm run typecheck # tsc project check
|
|
203
|
+
bun test # full unit suite
|
|
204
|
+
npm run test:pi # Pi integration smoke tests
|
|
205
|
+
npm pack --dry-run # inspect the published archive
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
The Remote Context protocol fixtures (`src/context-management/`) must be updated together with any upstream alpha endpoint change.
|
|
209
|
+
|
|
210
|
+
## API
|
|
211
|
+
|
|
212
|
+
### Remote Context tools
|
|
213
|
+
|
|
214
|
+
The four tools the extension registers when Remote Context is active:
|
|
215
|
+
|
|
216
|
+
| Tool | Parameters | Result / errors |
|
|
217
|
+
| --- | --- | --- |
|
|
218
|
+
| `new_context` | `{ force?: boolean }` | Rolls to the next window without summarizing. Refuses unless a successful notes checkpoint exists in the current window (`force` overrides). Reports "already scheduled" if a rollover is pending. |
|
|
219
|
+
| `get_context_remaining` | none | Remaining tokens and window identity for the current budget; `unknown` when no usage source exists yet. |
|
|
220
|
+
| `history` | `{ action: "list_windows" \| "list_items" \| "read_item" \| "search_contents", ... }` | Reads prior windows. Pass returned `item_id` / window ids **unchanged**. Search text is sent under the encrypted-argument policy. |
|
|
221
|
+
| `notes` | `{ action: "list_files_by_prefix" \| "read_file" \| "search_contents" \| "append_to_file" \| "write_file", path, text, ... }` | Cross-window working memory. Paths resolve under the session agent (e.g. `/root/notes/<file>` or a relative note path); an invalid path is rejected by the backend. Successful append/write is what satisfies the `new_context` gate. |
|
|
222
|
+
|
|
223
|
+
All four throw explicit tool errors on timeout, abort, non-2xx, malformed JSON, authentication, or protocol failures — they never silently degrade.
|
|
224
|
+
|
|
225
|
+
### HTTP protocol reference
|
|
226
|
+
|
|
227
|
+
Internal alpha endpoints, adapted from `@howaboua/pi-codex-conversion` (see [Background](#background)):
|
|
228
|
+
|
|
229
|
+
```text
|
|
230
|
+
POST {base}/alpha/history/v2/list_windows | list_items | read_item | search_contents
|
|
231
|
+
POST {base}/alpha/notes/v2/list_files_by_prefix | read_file | search_contents | append_to_file | write_file
|
|
232
|
+
GET {base}/alpha/notes/v2/thread_hint
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
Native route uses `{base} = <backend-api>/codex` with `Authorization: Bearer <oauth token>`, `ChatGPT-Account-ID`, and Codex CLI headers. Gateway route uses the configured `/v1` base with the data-plane API key, `originator: codex_cli_rs`, `X-Codex-Affinity-Scope`, and `X-Codex-Model` carrying the bare model id — never local credentials. Both set `Session-Id` / `X-Client-Request-Id` to the bounded Pi session id, `x-openai-tool-output-truncation-policy`, and `x-openai-encrypted-tool-arguments` for endpoints with encrypted parameters; encrypted results come back as `encrypted_output` and are re-encoded into later requests. These are alpha contracts: the upstream backend may change them at any time.
|
|
236
|
+
|
|
237
|
+
## Maintainers
|
|
238
|
+
|
|
239
|
+
[awoaCrim](https://github.com/awoaCrim)
|
|
240
|
+
|
|
241
|
+
## Contributing
|
|
242
|
+
|
|
243
|
+
Issues and pull requests are welcome at the [issue tracker](https://github.com/awoaCrim/pi-openai-toolkit/issues). For behavior-changing work, open an issue first so protocol assumptions (especially alpha `history`/`notes` contracts) can be discussed. Run `bun test` and `npm run typecheck` before submitting; new wire-protocol behavior needs fixture-based tests.
|
|
244
|
+
|
|
245
|
+
## License
|
|
246
|
+
|
|
247
|
+
MIT © awoaCrim and contributors. See [LICENSE](./LICENSE) and the third-party attribution in [NOTICE](./NOTICE).
|
|
248
|
+
|
|
249
|
+
## Thanks
|
|
250
|
+
|
|
251
|
+
Thanks to the [Linux.do](https://linux.do/) community for the support and discussions.
|