pi-openai-toolkit 0.14.4 → 0.14.6
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/docs/internals.md +42 -21
- package/package.json +127 -127
- package/src/auto-mode/classifier.ts +165 -165
- package/src/auto-mode/policy.ts +146 -146
- package/src/auto-mode/prompt.ts +279 -279
- package/src/auto-mode/reviewer.ts +325 -325
- package/src/auto-mode/transcript.ts +133 -133
- package/src/auto-mode/types.ts +137 -137
- package/src/codex-astra/effort-planner.ts +175 -175
- package/src/codex-astra/extension.ts +122 -122
- package/src/config.ts +621 -592
- package/src/context-management/codex-provider.ts +260 -260
- package/src/context-management/history-notes.ts +357 -325
- package/src/context-management/messages.ts +112 -106
- package/src/context-management/namespace-tools.ts +426 -426
- package/src/context-management/tool-contract.ts +23 -23
- package/src/context-management/tools.ts +306 -311
- package/src/context-management/types.ts +168 -161
- package/src/context-management/window-budget.ts +83 -83
- package/src/context-management/window-manager.ts +60 -51
- package/src/context-management/window-request.ts +125 -125
- package/src/debug.ts +1 -1
- package/src/extension-runtime.ts +34 -9
- package/src/image-generation/artifacts.ts +237 -237
- package/src/image-generation/client.ts +248 -248
- package/src/image-generation/eligibility.ts +18 -18
- package/src/image-generation/extension.ts +19 -2
- package/src/image-generation/protocol.ts +473 -405
- package/src/image-generation/references.ts +194 -194
- package/src/image-generation/render.ts +252 -252
- package/src/image-generation/service.ts +249 -243
- package/src/image-generation/types.ts +189 -184
- package/src/model-scope.ts +17 -17
- package/src/provider-headers.ts +23 -23
- package/src/responses-headers.ts +173 -108
- package/src/runtime.ts +513 -477
- package/src/types.ts +11 -0
- package/src/web-search/extension.ts +80 -80
- package/src/web-search/payload.ts +96 -96
- package/src/web-search/prompt.ts +20 -20
- package/src/web-search/types.ts +45 -45
package/README.zh.md
CHANGED
|
@@ -1,243 +1,211 @@
|
|
|
1
1
|
# pi-openai-toolkit
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
[](./LICENSE)
|
|
5
|
-
[English](./README.md)
|
|
3
|
+
为 Pi 添加 Codex 上下文窗口、Responses 压缩、托管工具和工具调用审查。
|
|
6
4
|
|
|
7
|
-
|
|
5
|
+
[](https://www.npmjs.com/package/pi-openai-toolkit)
|
|
6
|
+
[](LICENSE)
|
|
8
7
|
|
|
9
|
-
|
|
8
|
+
[英文版](README.md)
|
|
10
9
|
|
|
11
|
-
##
|
|
10
|
+
## 功能
|
|
12
11
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
- **安全承诺** - 覆盖模型上杜绝有损摘要，凭据不出本机
|
|
12
|
+
| 功能 | 用途 |
|
|
13
|
+
| --- | --- |
|
|
14
|
+
| Codex 远程上下文 | 切换到新上下文窗口，并通过 `history` 按需检索较早窗口。 |
|
|
15
|
+
| 远程压缩 v2 | 使用服务端返回的加密检查点继续符合条件的 Responses 会话。 |
|
|
16
|
+
| 托管联网搜索 | 为指定模型启用 OpenAI 托管的搜索工具。 |
|
|
17
|
+
| 图像生成 | 生成图片，或根据明确传入的本地参考图片进行编辑。 |
|
|
18
|
+
| 工具调用审查 | 在指定范围的工具调用执行前，由审查模型判断是否允许执行。 |
|
|
21
19
|
|
|
22
|
-
|
|
20
|
+
本包沿用 Pi 已有的模型、认证和会话配置，不新增提供商或模型。
|
|
23
21
|
|
|
24
22
|
## 安装
|
|
25
23
|
|
|
24
|
+
需要 Pi 0.85.1 或更高版本，以及 Node.js 22.19.0 或更高版本。
|
|
25
|
+
|
|
26
|
+
安装扩展：
|
|
27
|
+
|
|
26
28
|
```bash
|
|
27
29
|
pi install npm:pi-openai-toolkit
|
|
28
30
|
```
|
|
29
31
|
|
|
30
|
-
|
|
32
|
+
在当前项目中安装时，在命令后加上 `--local`。
|
|
31
33
|
|
|
32
|
-
|
|
33
|
-
pi install npm:pi-openai-toolkit --local
|
|
34
|
-
```
|
|
34
|
+
只安装扩展不会自动启用所有功能。没有扩展配置时，压缩模块处于开启状态，但远程上下文关闭，联网搜索没有目标模型，图像生成关闭，自动模式也没有允许的模型和审查模型。
|
|
35
35
|
|
|
36
|
-
|
|
36
|
+
扩展配置文件位于：
|
|
37
37
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
38
|
+
`~/.pi/agent/extensions/pi-openai-toolkit/config.json`
|
|
39
|
+
|
|
40
|
+
下文除 `models.json` 示例外，其他 JSON 配置示例都写入此文件。文件不存在时，创建文件及所需目录；已有配置时，将字段合并到对应对象中，保留其他设置。
|
|
41
|
+
|
|
42
|
+
## 快速开始：启用远程上下文
|
|
41
43
|
|
|
42
|
-
|
|
44
|
+
本节适用于想使用 Codex 风格上下文窗口的用户。如果只需要联网搜索、图像生成或工具调用审查，请直接跳到[常见用法](#常见用法)。
|
|
43
45
|
|
|
44
|
-
|
|
46
|
+
### 使用 Pi 内置的 Codex 提供商
|
|
45
47
|
|
|
46
|
-
|
|
48
|
+
你需要先登录 Pi 内置的 `openai-codex` 提供商。
|
|
49
|
+
|
|
50
|
+
创建或合并扩展配置：
|
|
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
|
+
使用已有 Codex 模型目录中的模型启动 Pi：
|
|
58
61
|
|
|
59
62
|
```bash
|
|
60
|
-
pi --model
|
|
63
|
+
pi --model openai-codex/<model-id>
|
|
61
64
|
```
|
|
62
65
|
|
|
63
|
-
|
|
66
|
+
将 `<model-id>` 换成 Pi 配置中实际显示的模型 ID。会话中出现 `new_context`、`get_context_remaining`、`history` 和 `notes` 工具，说明扩展已经完成启用检查。
|
|
64
67
|
|
|
65
|
-
|
|
68
|
+
### 使用兼容网关
|
|
66
69
|
|
|
67
|
-
|
|
70
|
+
本路线要求使用 `openai-responses` 接口，并且网关保留远程上下文所需的 Codex 协议字段。普通对话请求成功，不代表已经验证远程上下文兼容性。
|
|
71
|
+
|
|
72
|
+
如果 `~/.pi/agent/models.json` 中已有符合上述条件的网关模型，可以跳过模型配置，直接设置扩展白名单。否则，先添加或合并下面的提供商配置。请把 `my-gateway`、地址、环境变量名称和模型字段替换成实际值。示例中的数字只是示意值，不是项目默认值，必须改成符合实际模型与网关能力的上下文窗口和最大输出 token 数。
|
|
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
|
+
在启动 Pi 之前设置配置中引用的密钥。PowerShell 使用：
|
|
94
95
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
生命周期机制与协议契约：[docs/internals.md](docs/internals.md#rollover-lifecycle)。
|
|
96
|
+
```powershell
|
|
97
|
+
$env:MY_GATEWAY_KEY = "replace-with-your-gateway-key"
|
|
98
|
+
```
|
|
100
99
|
|
|
101
|
-
|
|
100
|
+
POSIX shell 使用：
|
|
102
101
|
|
|
103
|
-
|
|
102
|
+
```bash
|
|
103
|
+
export MY_GATEWAY_KEY="replace-with-your-gateway-key"
|
|
104
|
+
```
|
|
104
105
|
|
|
105
|
-
|
|
106
|
+
使用同一个终端启动 Pi。创建或合并扩展配置，并确保白名单条目与提供商名称和模型 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
|
+
使用相同的模型标识启动 Pi：
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
pi --model my-gateway/gpt-5.6-luna
|
|
121
|
+
```
|
|
114
122
|
|
|
115
|
-
|
|
123
|
+
启用检查方式相同：会话中应该出现 `new_context`、`get_context_remaining`、`history` 和 `notes`。如果没有出现，先查看工具包通知，再检查提供商和模型字符串、接口、密钥、基础 URL 和白名单条目。
|
|
124
|
+
|
|
125
|
+
较早窗口的历史仍可通过 `history` 检索和读取，但不会全部自动加入当前上下文。
|
|
126
|
+
|
|
127
|
+
## 常见用法
|
|
128
|
+
|
|
129
|
+
### 使用服务端压缩继续会话
|
|
130
|
+
|
|
131
|
+
如果希望使用 Responses 压缩路径，就保持远程上下文关闭。远程压缩 v2 会为符合条件的 Responses 模型保存并回放加密检查点。只有在压缩请求需要使用其他模型时，才设置 `compaction.remoteCompactModel`。
|
|
132
|
+
|
|
133
|
+
### 启用托管联网搜索
|
|
134
|
+
|
|
135
|
+
在 `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
|
+
对于这些模型，扩展会用 OpenAI 托管的 Responses 搜索工具替代 Pi 本地的 `web_search` 工具。
|
|
124
146
|
|
|
125
|
-
###
|
|
147
|
+
### 生成图片
|
|
148
|
+
|
|
149
|
+
图像生成需要 Responses 会话，并且可能产生服务商费用。启用方式如下：
|
|
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` 填写嵌套 Responses `image_generation` 工具使用的裸模型 ID。列表第一项是默认模型；`openai_generate_image` 也支持通过可选的 `model` 参数在单次调用中切换，但该值必须与配置列表中的某一项完全一致。省略 `models` 时默认使用 `gpt-image-2.5`。列表为空或格式无效时会告警并回退到默认模型；如果要关闭工具，将 `enabled` 设置为 `false`。服务商或网关必须实际支持配置的生图模型。
|
|
138
161
|
|
|
139
|
-
|
|
162
|
+
`openai_generate_image` 支持文生图，也支持使用明确传入的本地参考图片进行编辑。
|
|
140
163
|
|
|
141
|
-
|
|
164
|
+
### 启用工具调用自动审查
|
|
142
165
|
|
|
143
|
-
|
|
144
|
-
<summary><b>完整选项参考</b>（compaction、webSearch、imageGeneration、autoMode）</summary>
|
|
166
|
+
在 `autoMode` 中设置允许使用的模型和审查模型：
|
|
145
167
|
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
| `allowCompactionContinuityBreak` | *boolean*, `false` | v2：最近一次压缩来自其他策略（如安装前的文本摘要）时，重建全新密文链。 |
|
|
155
|
-
| `remoteCompactModel` | *string \| null*, `null` | v2：仅用于服务端压缩请求的模型，会话模型不切换。必须与当前模型同 base URL。 |
|
|
156
|
-
| `nativeFallback.enabled` | *boolean*, `true` | 仅在远端压缩确实失败后回退到原生压缩。 |
|
|
157
|
-
| `nativeFallback.model` | *string \| null*, `null` | 完全无法使用 v2 的模型的摘要模型。`null` 沿用当前模型。 |
|
|
158
|
-
| `nativeFallback.thinkingLevel` | *string*, `"off"` | 回退摘要的 thinking level（`off`...`max`）。 |
|
|
159
|
-
| `responsesApis` | *string[]*, 两个 API | 允许使用 v2 压缩的 Responses API 标识。v2 只作用于未被 Remote Context 覆盖的模型。 |
|
|
160
|
-
| `notifyOnLoad` | *boolean*, `false` | 启动横幅。 |
|
|
161
|
-
| `debug` | *boolean*, `false` | 向 `artifactRoot` 写生命周期与压缩 artifact，含每次 `session_start` 的激活原因。 |
|
|
162
|
-
| `logProviderPayloads` / `logCompactResponses` | *boolean*, `false` | 额外写原始载荷与 SSE 响应体，排查特定请求时再开。 |
|
|
163
|
-
| `redactSensitiveData` | *boolean*, `true` | artifact 脱敏；凭据、account ID、密文永远脱敏。 |
|
|
164
|
-
| `artifactRoot` | *string*, `~/.pi/agent/artifacts/pi-openai-toolkit/compaction` | artifact 根目录；相对路径按配置目录解析。 |
|
|
165
|
-
|
|
166
|
-
### `webSearch`
|
|
167
|
-
|
|
168
|
-
| 键 | 类型 / 默认值 | 含义 |
|
|
169
|
-
| --- | --- | --- |
|
|
170
|
-
| `enabled` | *boolean*, `true` | 总开关。 |
|
|
171
|
-
| `models` | *string[]*, `[]` | 接收 OpenAI 托管 `web_search` 的会话：本地 `web_search` 工具被移除，原生 Responses API 工具被注入。 |
|
|
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
|
+
在会话中使用 `/auto on`。默认的 `side-effect` 审查范围覆盖 `bash`、`write`、`edit` 和额外配置的工具。如果需要审查所有工具调用，将 `gate` 设置为 `"all"`。审查超时不会自动放行调用。
|
|
174
178
|
|
|
175
|
-
|
|
176
|
-
| --- | --- | --- |
|
|
177
|
-
| `enabled` | *boolean*, `false` | 向所有 Responses 协议会话开放 `openai_generate_image`。有意不设模型白名单。 |
|
|
179
|
+
## 常用配置
|
|
178
180
|
|
|
179
|
-
|
|
181
|
+
配置文件为 `~/.pi/agent/extensions/pi-openai-toolkit/config.json`。未知键会告警后忽略。大多数模型列表必须使用精确的 `provider/model-id` 字符串，不支持通配符；`imageGeneration.models` 是例外，填写嵌套生图工具使用的裸模型 ID。
|
|
180
182
|
|
|
181
|
-
|
|
|
183
|
+
| 配置项 | 默认值 | 用途 |
|
|
182
184
|
| --- | --- | --- |
|
|
183
|
-
| `enabled` |
|
|
184
|
-
| `
|
|
185
|
-
| `
|
|
186
|
-
| `
|
|
187
|
-
| `
|
|
188
|
-
| `
|
|
189
|
-
| `
|
|
190
|
-
| `
|
|
191
|
-
| `
|
|
192
|
-
| `
|
|
193
|
-
| `
|
|
194
|
-
|
|
195
|
-
### `codexAstra`
|
|
196
|
-
|
|
197
|
-
已移除的配置段。Astra 兼容层对所有 Responses 系 API 的 `gpt-6-astra` 会话静默启用；旧 `codexAstra` 配置按未知字段告警忽略。若其他宿主（如 Oh My Pi）实现了同款改写，只启用一边。
|
|
198
|
-
|
|
199
|
-
</details>
|
|
200
|
-
|
|
201
|
-
## 安全
|
|
202
|
-
|
|
203
|
-
- 覆盖模型被 Remote Context 接管期间，Pi 原生压缩全部路径（阈值、手动 `/compact`、溢出）取消，无法产生有损摘要。
|
|
204
|
-
- 网关模式只转发配置的数据面 API key。OAuth token、account cookie、account ID 绝不发给网关，artifact 中永远脱敏。
|
|
205
|
-
- `new_context` 无法丢弃未保存状态：必须有本窗口成功的 notes 存档，或用户显式 `force`。
|
|
206
|
-
- 图像生成（计费）与 Auto 模式均需显式开启；无人可批准的场景下 Auto 模式阻断。
|
|
207
|
-
|
|
208
|
-
需要宿主层保险时，在 Pi 的 `settings.json` 设置 `"compaction": { "enabled": false }`。
|
|
185
|
+
| `compaction.enabled` | `true` | 压缩功能总开关。 |
|
|
186
|
+
| `compaction.contextManagement` | `"off"` | 设置为 `"remote"` 后启用 Codex 远程上下文。 |
|
|
187
|
+
| `compaction.gatewayContextModels` | `[]` | 允许使用远程上下文的网关模型。 |
|
|
188
|
+
| `compaction.remoteCompactModel` | 未设置 | 仅用于 v2 压缩请求的可选模型。 |
|
|
189
|
+
| `compaction.contextReminderThresholdPercent` | `5` | 每个窗口触发一次提醒的剩余预算百分比。设置为 `0` 会关闭提醒和窗口耗尽兜底。 |
|
|
190
|
+
| `webSearch.models` | `[]` | 使用托管联网搜索的模型。 |
|
|
191
|
+
| `imageGeneration.enabled` | `false` | 启用 `openai_generate_image`。 |
|
|
192
|
+
| `imageGeneration.models` | `["gpt-image-2.5"]` | 裸生图模型 ID；列表第一项是默认模型。 |
|
|
193
|
+
| `autoMode.models` | `[]` | 允许使用自动模式的模型。 |
|
|
194
|
+
| `autoMode.reviewerModel` | 未设置 | 审查自动模式调用的模型。 |
|
|
195
|
+
| `autoMode.gate` | `"side-effect"` | 设置为 `"all"` 后审查所有工具调用。 |
|
|
196
|
+
| `autoMode.timeoutMs` | `30000` | 审查超时时间，单位为毫秒。 |
|
|
209
197
|
|
|
210
198
|
## 开发
|
|
211
199
|
|
|
200
|
+
在仓库根目录安装依赖后运行：
|
|
201
|
+
|
|
212
202
|
```bash
|
|
213
|
-
npm run typecheck #
|
|
214
|
-
bun test #
|
|
215
|
-
npm run test:pi # Pi
|
|
203
|
+
npm run typecheck # 类型检查
|
|
204
|
+
bun test # 运行测试
|
|
205
|
+
npm run test:pi # 运行 Pi 冒烟测试
|
|
216
206
|
npm pack --dry-run # 检查发布包内容
|
|
217
207
|
```
|
|
218
208
|
|
|
219
|
-
## 文档
|
|
220
|
-
|
|
221
|
-
- [docs/internals.md](docs/internals.md) - 协议端点、换窗生命周期、v2 线路契约、artifact、来源归属
|
|
222
|
-
- [README.md](README.md) - 英文原版（canonical）
|
|
223
|
-
- [NOTICE](./NOTICE) - 第三方归属
|
|
224
|
-
|
|
225
|
-
## 贡献
|
|
226
|
-
|
|
227
|
-
欢迎在 [issue 区](https://github.com/awoaCrim/pi-openai-toolkit/issues)提问和提交 PR。行为变更前先开 issue 讨论协议假设；提交前运行 `bun test` 与 `npm run typecheck`，线路变更需要 fixture 测试。
|
|
228
|
-
|
|
229
|
-
## 维护者
|
|
230
|
-
|
|
231
|
-
[awoaCrim](https://github.com/awoaCrim)
|
|
232
|
-
|
|
233
209
|
## 许可证
|
|
234
210
|
|
|
235
|
-
MIT © awoaCrim
|
|
236
|
-
|
|
237
|
-
## 致谢
|
|
238
|
-
|
|
239
|
-
感谢 [Linux.do](https://linux.do/) 社区的支持与讨论。
|
|
240
|
-
|
|
241
|
-
---
|
|
242
|
-
|
|
243
|
-
*本文译自 [README.md](README.md)。若两版内容冲突，以英文版为准。*
|
|
211
|
+
MIT © awoaCrim 与贡献者。见 [LICENSE](LICENSE) 和 [NOTICE](NOTICE)。
|
package/docs/internals.md
CHANGED
|
@@ -1,8 +1,10 @@
|
|
|
1
1
|
# Toolkit Internals
|
|
2
2
|
|
|
3
|
-
Developer-facing reference for [pi-openai-toolkit](../README.md).
|
|
3
|
+
Developer-facing reference for [pi-openai-toolkit](../README.md). The README keeps this protocol and implementation detail out of the installation path. If you are changing wire behavior, fixtures, or the compaction strategy code, start here.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
### Table of Contents
|
|
6
8
|
|
|
7
9
|
- [Remote Context protocol](#remote-context-protocol)
|
|
8
10
|
- [Rollover lifecycle](#rollover-lifecycle)
|
|
@@ -10,28 +12,34 @@ Developer-facing reference for [pi-openai-toolkit](../README.md). This is the pr
|
|
|
10
12
|
- [Artifacts and debugging](#artifacts-and-debugging)
|
|
11
13
|
- [Provenance](#provenance)
|
|
12
14
|
|
|
13
|
-
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
### Remote Context protocol
|
|
14
18
|
|
|
15
19
|
Internal alpha endpoints, adapted from `@howaboua/pi-codex-conversion`:
|
|
16
20
|
|
|
17
21
|
```text
|
|
18
22
|
POST {base}/alpha/history/v2/list_windows | list_items | read_item | search_contents
|
|
19
23
|
POST {base}/alpha/notes/v2/list_files_by_prefix | read_file | search_contents | append_to_file | write_file
|
|
20
|
-
|
|
24
|
+
POST {base}/alpha/notes/v2/thread_hint
|
|
21
25
|
```
|
|
22
26
|
|
|
23
|
-
|
|
27
|
+
The native route uses `{base} = <backend-api>/codex` with `Authorization: Bearer <oauth token>`, `ChatGPT-Account-ID`, and Codex CLI headers. The gateway route uses the configured `/v1` base with the API key configured for that provider, `originator: codex_cli_rs`, `X-Codex-Affinity-Scope`, and `X-Codex-Model` carrying the bare model ID. Inherited OAuth headers, cookies, and account IDs are stripped before the request leaves the process. Both routes set `Session-Id` and `X-Client-Request-Id` to the bounded Pi session ID, plus `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, so the upstream backend may change them at any time.
|
|
24
28
|
|
|
25
29
|
Search text and note bodies are sent under the encrypted-argument policy. Live model requests carry `x-codex-window-id` and `x-codex-turn-metadata` request headers derived from the active window identity.
|
|
26
30
|
|
|
27
|
-
Coverage is never inferred from model names. A native session
|
|
31
|
+
Coverage is never inferred from model names. A native session uses provider `openai-codex` with API `openai-codex-responses` for any model ID. A gateway session uses API `openai-responses` and must carry an exact `provider/model` key listed in `compaction.gatewayContextModels`; the list ships empty and there is no built-in gateway SKU. See [src/context-management/codex-provider.ts](../src/context-management/codex-provider.ts). The toolkit registers no provider or model with Pi. It resolves credentials and base URLs through Pi's `ModelRegistry`.
|
|
28
32
|
|
|
29
|
-
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
### Rollover lifecycle
|
|
30
36
|
|
|
31
37
|
The `new_context` happy path, end to end:
|
|
32
38
|
|
|
33
39
|
```mermaid
|
|
34
40
|
sequenceDiagram
|
|
41
|
+
accTitle: Remote Context rollover
|
|
42
|
+
accDescr: A Pi model checkpoints notes, requests a local new_context boundary, and sends the next request with the new window identity.
|
|
35
43
|
participant Model
|
|
36
44
|
participant Toolkit
|
|
37
45
|
participant Pi
|
|
@@ -41,6 +49,7 @@ sequenceDiagram
|
|
|
41
49
|
Backend-->>Toolkit: encrypted_output
|
|
42
50
|
Model->>Toolkit: new_context
|
|
43
51
|
Toolkit->>Toolkit: verify successful notes write in this window
|
|
52
|
+
Toolkit-->>Model: checkpoint receipt with the successful note path
|
|
44
53
|
Toolkit-->>Pi: window marker appended, previous window trim scheduled
|
|
45
54
|
Model->>Backend: next request with the new x-codex-window-id
|
|
46
55
|
Pi->>Toolkit: session_before_compact
|
|
@@ -49,25 +58,37 @@ sequenceDiagram
|
|
|
49
58
|
|
|
50
59
|
State invariants the lifecycle code must keep honest:
|
|
51
60
|
|
|
52
|
-
- The checkpoint gate verifies a
|
|
53
|
-
-
|
|
54
|
-
-
|
|
55
|
-
-
|
|
61
|
+
- The checkpoint gate verifies a successful `notes` `append_to_file` or `write_file` against the persisted session branch after the latest window boundary, so it survives restarts and forks. A response with `ok: false` or `success: false` is not successful, even when HTTP returns 200.
|
|
62
|
+
- Every rollover carries the most recent successful checkpoint path in its handoff message. The optional `thread_hint` is supplemental; a hint failure must not erase the local receipt.
|
|
63
|
+
- `new_context` has no force escape hatch: a successful notes checkpoint is always required before rollover.
|
|
64
|
+
- Budget checks are skipped until the current window has produced its own assistant usage. Acting on the previous window's usage anchor would burn the once-per-window reminder on a false alarm.
|
|
65
|
+
- The scheduled trim is consumed exactly once, synchronously, by the first compaction attempt whose boundary window ID matches. Every other compaction path, including a threshold without a scheduled rollover, manual `/compact`, and overflow, is cancelled.
|
|
66
|
+
- A window boundary is persisted as a `codex-context-window` custom message. `session_start` replays boundaries from the branch and rebuilds identity after forks.
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
### Remote Compaction v2 wire contract
|
|
71
|
+
|
|
72
|
+
v2 is what an uncovered session gets. Any model that Remote Context declines, such as a gateway model absent from `gatewayContextModels`, can still compact through v2 when its API appears in `responsesApis`. The two strategies never compete for one session.
|
|
73
|
+
|
|
74
|
+
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, with 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.
|
|
75
|
+
|
|
76
|
+
A v2 response with a missing or empty checkpoint is never stored, and the `nativeFallback` tier is skipped. Pi's own threshold drives the next attempt, which may use `remoteCompactModel` when configured. `remoteCompactModel` must resolve to the same effective base URL as the active model.
|
|
56
77
|
|
|
57
|
-
|
|
78
|
+
---
|
|
58
79
|
|
|
59
|
-
|
|
80
|
+
### Artifacts and debugging
|
|
60
81
|
|
|
61
|
-
|
|
82
|
+
With `debug: true`, the toolkit writes lifecycle and compaction artifacts under `artifactRoot` (default `~/.pi/agent/artifacts/pi-openai-toolkit/compaction`):
|
|
62
83
|
|
|
63
|
-
|
|
84
|
+
- Each `session_start` writes a lifecycle artifact whose `activation` field records `active` or the exact inactive reason, such as `unsupported-model`, `unsupported-api`, `missing-api-key`, `auth-resolution-failed`, or `tool-name-conflict`.
|
|
85
|
+
- `logProviderPayloads` additionally writes provider request metadata and payloads, while `logCompactResponses` writes compact status and structural summaries with complete response and body fields critically redacted. Keep both off unless inspecting a specific request.
|
|
86
|
+
- Artifacts always redact Authorization credentials, API keys and tokens, Codex account IDs, and opaque `encrypted_content` or `encrypted_output`, even when `redactSensitiveData` is `false`.
|
|
64
87
|
|
|
65
|
-
|
|
66
|
-
- `logProviderPayloads` additionally writes raw provider request payloads, `logCompactResponses` the compact SSE bodies; keep both off unless inspecting a specific request;
|
|
67
|
-
- artifacts always redact Authorization credentials, API keys/tokens, Codex account ids, and opaque `encrypted_content` / `encrypted_output`, even with `redactSensitiveData: false`.
|
|
88
|
+
---
|
|
68
89
|
|
|
69
|
-
|
|
90
|
+
### Provenance
|
|
70
91
|
|
|
71
|
-
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 [
|
|
92
|
+
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).
|
|
72
93
|
|
|
73
|
-
Protocol fixtures live in [src/context-management/](../src/context-management/) and must be updated together with any upstream alpha endpoint change
|
|
94
|
+
Protocol fixtures live in [src/context-management/](../src/context-management/) and must be updated together with any upstream alpha endpoint change. New wire behavior requires fixture-based tests.
|