pi-openai-toolkit 0.14.3 → 0.14.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +150 -162
- package/README.zh.md +156 -164
- package/docs/internals.md +73 -0
- package/extensions/auto-mode.ts +1 -1
- package/extensions/codex-astra.ts +1 -1
- package/extensions/compaction.ts +1 -1
- package/extensions/image-generation.ts +1 -1
- package/extensions/web-search.ts +1 -1
- package/package.json +2 -1
- package/src/config.ts +10 -0
- package/src/context-management/codex-provider.ts +12 -14
- package/src/context-management/history-notes.ts +8 -2
- package/src/context-management/tools.ts +5 -3
- package/src/context-management/types.ts +2 -1
- package/src/extension-runtime.ts +9 -5
- package/src/types.ts +7 -0
- package/src/web-search/prompt.ts +1 -1
package/README.md
CHANGED
|
@@ -2,51 +2,24 @@
|
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/pi-openai-toolkit)
|
|
4
4
|
[](./LICENSE)
|
|
5
|
-
|
|
6
5
|
[简体中文](./README.zh.md)
|
|
7
6
|
|
|
8
|
-
OpenAI toolkit for Pi:
|
|
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
|
|
7
|
+
OpenAI toolkit for Pi: lossless long-session context management, hosted web search, image generation, and approval-gated auto mode.
|
|
37
8
|
|
|
38
|
-
-
|
|
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.
|
|
9
|
+
Pi's built-in compaction summarizes older turns into text, permanently losing detail. The OpenAI Codex backend solves this with mechanisms generic clients never received: a context-window system (`new_context`, `history`, `notes`), encrypted lossless compaction, and hosted tools. This package ports those Codex capabilities into Pi by implementing their protocols against the live backends; Auto Mode is its own feature. One note: the context-window tools you see in a covered session are Codex's mechanism, surfaced by this toolkit, not something Pi or this package invented independently.
|
|
42
10
|
|
|
43
|
-
##
|
|
11
|
+
## Features
|
|
44
12
|
|
|
45
|
-
|
|
13
|
+
- **Context windows** (Codex mechanism, ported) - roll over to a fresh window with `new_context`; nothing is re-summarized
|
|
14
|
+
- **Cross-window recall** - search and read earlier windows with `history`
|
|
15
|
+
- **Working-memory notes** - persistent checkpoint files with `notes`, gating every rollover
|
|
16
|
+
- **Encrypted compaction (v2)** - OpenAI backend compaction capability, surfaced for Responses models
|
|
17
|
+
- **Hosted web search** - OpenAI Responses native `web_search`, swapped in for Pi's local tool on listed models
|
|
18
|
+
- **Image generation** - hosted `image_generation` (gpt-image-2) wrapped in a Pi tool that keeps image bytes out of history
|
|
19
|
+
- **Auto mode** - this package's own feature: a reviewer-model approval gate for side-effecting tool calls
|
|
20
|
+
- **Safety guarantees** - no lossy summary on covered models, credentials never leave the machine
|
|
46
21
|
|
|
47
|
-
|
|
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.
|
|
22
|
+
Requires Pi >= 0.85.1 and Node.js >= 22.19.0. The toolkit registers no provider or model of its own; it works entirely through Pi's existing catalog, auth, and session storage. Do not run `pi-remote-compact`, `@lll9p/pi-better-compaction`, or a standalone `pi-openai-web-search` alongside it: duplicate hooks cause race conditions.
|
|
50
23
|
|
|
51
24
|
## Install
|
|
52
25
|
|
|
@@ -54,197 +27,212 @@ Requires **Pi >= 0.85.1** and **Node.js >= 22.19.0**. Pi supplies the model cata
|
|
|
54
27
|
pi install npm:pi-openai-toolkit
|
|
55
28
|
```
|
|
56
29
|
|
|
57
|
-
|
|
30
|
+
Per-project install:
|
|
58
31
|
|
|
59
32
|
```bash
|
|
60
33
|
pi install npm:pi-openai-toolkit --local
|
|
61
34
|
```
|
|
62
35
|
|
|
63
|
-
|
|
36
|
+
Install from git for development or pinned builds:
|
|
64
37
|
|
|
65
38
|
```bash
|
|
66
39
|
pi install git:github.com/awoaCrim/pi-openai-toolkit
|
|
67
40
|
```
|
|
68
41
|
|
|
69
|
-
|
|
42
|
+
Update later with `pi update --extensions`.
|
|
43
|
+
|
|
44
|
+
## Quick start
|
|
45
|
+
|
|
46
|
+
**1.** Create `~/.pi/agent/extensions/pi-openai-toolkit/config.json` (Windows: `C:\Users\<user>\.pi\agent\extensions\pi-openai-toolkit\config.json`):
|
|
47
|
+
|
|
48
|
+
```json
|
|
49
|
+
{
|
|
50
|
+
"compaction": {
|
|
51
|
+
"contextManagement": "remote",
|
|
52
|
+
"contextReminderThresholdPercent": 10
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
**2.** Start Pi on a covered model: any session on Pi's built-in Codex provider (`openai-codex`), or a gateway model listed in `gatewayContextModels`:
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
pi --model uwoacrimson/gpt-6-astra
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
**3.** Confirm activation: the four Codex context tools (`new_context`, `get_context_remaining`, `history`, `notes`) appear in the session.
|
|
70
64
|
|
|
71
|
-
|
|
65
|
+
When the window drops below the reminder threshold, the model gets one nudge to save notes and roll over. Everything earlier stays searchable through `history`. With no config file, Pi's defaults apply and every optional feature stays off.
|
|
72
66
|
|
|
73
|
-
|
|
67
|
+
Gateway coverage is an explicit allowlist: `compaction.gatewayContextModels` holds exact `provider/model` keys, each on the `openai-responses` wire and actually relayed by your gateway with Codex window markers intact. If your gateway isn't configured in Pi yet, add it to `~/.pi/agent/models.json`:
|
|
74
68
|
|
|
75
|
-
|
|
69
|
+
```json
|
|
70
|
+
{
|
|
71
|
+
"providers": {
|
|
72
|
+
"uwoacrimson": {
|
|
73
|
+
"baseUrl": "https://<your-gateway>/v1",
|
|
74
|
+
"apiKeyRef": "uwoacrimson",
|
|
75
|
+
"api": "openai",
|
|
76
|
+
"models": [{
|
|
77
|
+
"id": "gpt-6-astra",
|
|
78
|
+
"name": "GPT-6 Astra",
|
|
79
|
+
"api": "openai-responses",
|
|
80
|
+
"reasoning": true,
|
|
81
|
+
"input": ["text"],
|
|
82
|
+
"contextWindow": 272000,
|
|
83
|
+
"maxTokens": 16384,
|
|
84
|
+
"compat": {"thinkingLevelMap": {"off": 0, "minimal": 0.1, "low": 0.2, "medium": 0.5, "high": 1, "xhigh": 2, "max": 2}}
|
|
85
|
+
}]
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
```
|
|
76
90
|
|
|
77
91
|
## Usage
|
|
78
92
|
|
|
79
|
-
|
|
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.
|
|
96
|
+
|
|
97
|
+
The toolkit owns compaction for covered models: Pi-native compaction is cancelled on every path, so no lossy summary can enter the session. If Remote Context cannot activate, the exact reason is reported as a notification.
|
|
80
98
|
|
|
81
|
-
|
|
99
|
+
Lifecycle mechanics and protocol contracts: [docs/internals.md](docs/internals.md#rollover-lifecycle).
|
|
100
|
+
|
|
101
|
+
### Remote Compaction v2
|
|
102
|
+
|
|
103
|
+
For other Responses models: when compaction triggers, the toolkit asks the OpenAI backend's compaction capability for an encrypted checkpoint of the old prefix instead of allowing a text summary to replace it; the server computes the checkpoint, the client only stores and replays it. Later requests replay the checkpoint ahead of recent turns. Failed attempts degrade to Pi's native compaction (`nativeFallback`). Wire contract: [docs/internals.md](docs/internals.md#remote-compaction-v2-wire-contract).
|
|
104
|
+
|
|
105
|
+
### Web search
|
|
106
|
+
|
|
107
|
+
```json
|
|
108
|
+
{
|
|
109
|
+
"webSearch": { "enabled": true, "models": ["uwoacrimson/gpt-5.6-luna"] }
|
|
110
|
+
}
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Listed models get OpenAI's hosted `web_search`; their local `web_search` tool is removed from the payload. The live model connection is reused, no extra key.
|
|
114
|
+
|
|
115
|
+
### Image generation
|
|
116
|
+
|
|
117
|
+
```json
|
|
118
|
+
{
|
|
119
|
+
"imageGeneration": { "enabled": true }
|
|
120
|
+
}
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Adds `openai_generate_image` to every Responses-wire session, wrapping OpenAI's hosted `image_generation` tool (`gpt-image-2`): text-to-image and edits from explicitly passed local reference files. The wrapper stores image bytes as artifacts instead of session history. Each successful request may incur a charge, hence the default off.
|
|
124
|
+
|
|
125
|
+
### Auto mode
|
|
82
126
|
|
|
83
127
|
```json
|
|
84
128
|
{
|
|
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
129
|
"autoMode": {
|
|
103
130
|
"enabled": true,
|
|
104
131
|
"models": ["uwoacrimson/gpt-5.6-luna"],
|
|
105
|
-
"reviewerModel": "uwoacrimson/gpt-5.6-luna"
|
|
106
|
-
"gate": "side-effect"
|
|
132
|
+
"reviewerModel": "uwoacrimson/gpt-5.6-luna"
|
|
107
133
|
}
|
|
108
134
|
}
|
|
109
135
|
```
|
|
110
136
|
|
|
111
|
-
|
|
137
|
+
Engage per session with `/auto on`. Side-effecting tool calls are approved by `reviewerModel` (intrinsic risk plus conversation authorization) instead of blocking on the user. The reviewer has read-only tools only, a timeout is never approval, and headless sessions block instead of guessing. Decisions are persisted for audit.
|
|
112
138
|
|
|
113
|
-
|
|
114
|
-
pi --model uwoacrimson/gpt-6-astra "resume the deploy task"
|
|
115
|
-
```
|
|
139
|
+
## Configuration
|
|
116
140
|
|
|
117
|
-
|
|
141
|
+
One JSON file at `~/.pi/agent/extensions/pi-openai-toolkit/config.json`. Every key is optional; unknown keys are ignored with a warning. `models` keys are exact `provider/model-id` allowlists (no globbing); each feature stays off until a model is listed.
|
|
118
142
|
|
|
119
|
-
|
|
143
|
+
<details>
|
|
144
|
+
<summary><b>Full option reference</b> (compaction, webSearch, imageGeneration, autoMode)</summary>
|
|
120
145
|
|
|
121
|
-
|
|
146
|
+
### `compaction`
|
|
122
147
|
|
|
123
148
|
| Key | Type / default | Meaning |
|
|
124
149
|
| --- | --- | --- |
|
|
125
|
-
| `enabled` | *boolean*, `true` | Master switch for the compaction extension
|
|
126
|
-
| `contextManagement` | `"off"` \| `"remote"`, `"off"` |
|
|
127
|
-
| `
|
|
128
|
-
| `
|
|
129
|
-
| `
|
|
130
|
-
| `
|
|
131
|
-
| `nativeFallback.
|
|
132
|
-
| `nativeFallback.
|
|
133
|
-
| `
|
|
134
|
-
| `
|
|
135
|
-
| `
|
|
136
|
-
| `
|
|
137
|
-
| `
|
|
138
|
-
| `
|
|
139
|
-
|
|
140
|
-
|
|
150
|
+
| `enabled` | *boolean*, `true` | Master switch for the compaction extension. |
|
|
151
|
+
| `contextManagement` | `"off"` \| `"remote"`, `"off"` | Enables Codex Remote Context for covered models: any `openai-codex` session on the `openai-codex-responses` API, plus gateway models listed below. |
|
|
152
|
+
| `gatewayContextModels` | *string[]*, `[]` | Exact `provider/model` keys allowed to use Codex Remote Context over the `openai-responses` gateway wire. Coverage is operator-configured; the native Codex route ignores this list. |
|
|
153
|
+
| `contextReminderThresholdPercent` | *integer* `0`-`100`, `5` | Percentage of the usable budget (context window minus a fixed 16384-token output reserve) below which the once-per-window checkpoint reminder fires. `0` suppresses the reminder and, in the current implementation, the exhausted-window fallback too; keep it above 0. The threshold measures the toolkit's budget, a fixed pairing with Pi's native reserve rather than a live sync. |
|
|
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`
|
|
141
167
|
|
|
142
168
|
| Key | Type / default | Meaning |
|
|
143
169
|
| --- | --- | --- |
|
|
144
170
|
| `enabled` | *boolean*, `true` | Master switch. |
|
|
145
|
-
| `models` | *string[]*, `[]` |
|
|
171
|
+
| `models` | *string[]*, `[]` | Sessions receiving OpenAI's hosted `web_search`: the local `web_search` tool is removed and the native responses-API tool injected. |
|
|
146
172
|
|
|
147
|
-
|
|
173
|
+
### `imageGeneration`
|
|
148
174
|
|
|
149
175
|
| Key | Type / default | Meaning |
|
|
150
176
|
| --- | --- | --- |
|
|
151
|
-
| `enabled` | *boolean*, `false` |
|
|
177
|
+
| `enabled` | *boolean*, `false` | Exposes `openai_generate_image` to all Responses-wire sessions. No model allowlist by design. |
|
|
152
178
|
|
|
153
|
-
|
|
179
|
+
### `autoMode`
|
|
154
180
|
|
|
155
181
|
| Key | Type / default | Meaning |
|
|
156
182
|
| --- | --- | --- |
|
|
157
|
-
| `enabled` | *boolean*, `true` | Master switch;
|
|
158
|
-
| `models` | *string[]*, `[]` |
|
|
159
|
-
| `reviewerModel` | *string \| null*, `null` | Approving model
|
|
160
|
-
| `gate` | `"side-effect"` \| `"all"`, `"side-effect"` |
|
|
161
|
-
| `extraTools` | *string[]*, `[]` | Additional reviewed
|
|
162
|
-
| `timeoutMs` | *integer* 1000-120000, `30000` |
|
|
163
|
-
| `transcript` | *boolean*, `true` |
|
|
164
|
-
| `evidenceTools` | *boolean*, `true` |
|
|
165
|
-
| `maxEvidenceRounds` | *integer* 0-8, `3` | Investigation rounds before the
|
|
166
|
-
| `classifier.*` |
|
|
167
|
-
| `circuitBreaker.*` |
|
|
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.
|
|
183
|
+
| `enabled` | *boolean*, `true` | Master switch; engaging still needs a listed model and `reviewerModel`. |
|
|
184
|
+
| `models` | *string[]*, `[]` | Session models allowed to run auto mode. |
|
|
185
|
+
| `reviewerModel` | *string \| null*, `null` | Approving model for one-off reviews; never becomes the conversation model. |
|
|
186
|
+
| `gate` | `"side-effect"` \| `"all"`, `"side-effect"` | Review scope; `/auto all` switches per session. |
|
|
187
|
+
| `extraTools` | *string[]*, `[]` | Additional reviewed tools beyond `bash`, `write`, `edit`. |
|
|
188
|
+
| `timeoutMs` | *integer* 1000-120000, `30000` | Review deadline. Expiry is never approval. |
|
|
189
|
+
| `transcript` | *boolean*, `true` | Bounded conversation view so the reviewer can judge authorization. |
|
|
190
|
+
| `evidenceTools` | *boolean*, `true` | Reviewer may use `read`, `grep`, `find`, `ls`. Never `bash`, writes, or network. |
|
|
191
|
+
| `maxEvidenceRounds` | *integer* 0-8, `3` | Investigation rounds before the verdict; `0` is a single completion. |
|
|
192
|
+
| `classifier.*` | *object* | Optional non-blocking low-risk pre-scorer. Fast-path only, never denies. |
|
|
193
|
+
| `circuitBreaker.*` | *object* | End the turn after repeated denials (`consecutiveDenials` `3`, or `recentDenials` `10` within `windowSize` `50`; `0` disables). |
|
|
174
194
|
|
|
175
|
-
###
|
|
195
|
+
### `codexAstra`
|
|
176
196
|
|
|
177
|
-
|
|
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.
|
|
178
198
|
|
|
179
|
-
|
|
199
|
+
</details>
|
|
180
200
|
|
|
181
|
-
|
|
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.
|
|
201
|
+
## Security
|
|
194
202
|
|
|
195
|
-
|
|
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.
|
|
196
207
|
|
|
197
|
-
|
|
208
|
+
For host-level insurance, set `"compaction": { "enabled": false }` in Pi's `settings.json`.
|
|
198
209
|
|
|
199
210
|
## Development
|
|
200
211
|
|
|
201
212
|
```bash
|
|
202
|
-
npm run typecheck
|
|
203
|
-
bun test
|
|
204
|
-
npm run test:pi
|
|
205
|
-
npm pack --dry-run
|
|
213
|
+
npm run typecheck # tsc project check
|
|
214
|
+
bun test # unit suite
|
|
215
|
+
npm run test:pi # Pi integration smoke tests
|
|
216
|
+
npm pack --dry-run # inspect the published archive
|
|
206
217
|
```
|
|
207
218
|
|
|
208
|
-
|
|
219
|
+
## Documentation
|
|
209
220
|
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
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. |
|
|
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
|
|
222
224
|
|
|
223
|
-
|
|
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
|
-
```
|
|
225
|
+
## Contributing
|
|
234
226
|
|
|
235
|
-
|
|
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.
|
|
236
228
|
|
|
237
229
|
## Maintainers
|
|
238
230
|
|
|
239
231
|
[awoaCrim](https://github.com/awoaCrim)
|
|
240
232
|
|
|
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
233
|
## License
|
|
246
234
|
|
|
247
|
-
MIT © awoaCrim and contributors. See [LICENSE](./LICENSE) and
|
|
235
|
+
MIT © awoaCrim and contributors. See [LICENSE](./LICENSE) and [NOTICE](./NOTICE).
|
|
248
236
|
|
|
249
237
|
## Thanks
|
|
250
238
|
|