pi-openai-toolkit 0.10.0 → 0.11.1

package/NOTICE

@@ -1,33 +1,55 @@
-pi-openai-toolkit
-Copyright (c) 2026 awoaCrim and contributors
-
-The native OpenAI Web Search behavior in this package was adapted from
-code-yeongyu/pi-openai-web-search at commit
-39643380682f02f306b0de2673ff136c45ccc2a2.
-
-Upstream copyright and license notice:
-
-Copyright (c) 2026 Yeongyu Kim
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
-The adapted implementation targets the @earendil-works Pi interfaces and is
-integrated with pi-openai-toolkit's independent compaction and Web Search
-extension entry points. The upstream NOTICE also identifies the behavior as a
-standalone port of the senpi-mono built-in openai-web-search extension.
+pi-openai-toolkit
+Copyright (c) 2026 awoaCrim and contributors
+
+The native OpenAI Web Search behavior in this package was adapted from
+code-yeongyu/pi-openai-web-search at commit
+39643380682f02f306b0de2673ff136c45ccc2a2.
+
+Upstream copyright and license notice:
+
+Copyright (c) 2026 Yeongyu Kim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+The adapted implementation targets the @earendil-works Pi interfaces and is
+integrated with pi-openai-toolkit's independent compaction and Web Search
+extension entry points. The upstream NOTICE also identifies the behavior as a
+standalone port of the senpi-mono built-in openai-web-search extension.
+
+The stable reasoning-effort planner in src/codex-astra/effort-planner.ts was
+ported from Oh My Pi (@oh-my-pi/pi-ai, providers/openai-configuration-update.ts)
+at version 18.1.8.
+
+Upstream copyright and license notice:
+
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+Copyright (c) 2025-2026 Can Bölük
+Copyright (c) 2026 Stencil Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.

package/README.md

@@ -10,12 +10,13 @@
 
 ---
 
-`pi-openai-toolkit` is an all-in-one OpenAI enhancement package for **Pi (>= 0.84.x)**. It bundles four extensions designed for OpenAI Responses endpoints:
+`pi-openai-toolkit` is an all-in-one OpenAI enhancement package for **Pi (>= 0.84.x)**. It bundles five extensions designed for OpenAI Responses endpoints:
 
 1. **Remote Responses Compaction v2** (`extensions/compaction.ts`): Server-side opaque context compaction using the `remote_compaction_v2` SSE streaming protocol. Preserves context fidelity without lossy text re-summarization.
 2. **Model-Scoped Web Search** (`extensions/web-search.ts`): Toolkit-owned hosted Web Search for an exact `provider/model-id` allowlist configured with `webSearch.models`, across the supported `openai-responses` and `openai-codex-responses` APIs.
 3. **Native Image Generation** (`extensions/image-generation.ts`): A sequential local tool backed by the hosted Responses `image_generation` tool. It supports text-to-image and explicit local-reference edits while keeping binary image data out of session history.
 4. **Model-Reviewed Auto Mode** (`extensions/auto-mode.ts`): Pi does not prompt before running tools. Auto mode adds a gate on state-changing tool calls and lets a reviewer model you configure approve or deny each one, so the agent keeps working without interrupting you.
+5. **Codex GPT-6 Astra Compatibility** (`extensions/codex-astra.ts`): Sends the Codex backend version-gate header on live requests and keeps prompt caching alive across thinking-level changes on `gpt-6-astra` by carrying later effort changes as `configuration_update` transcript items.
 
 ## Installation
 
@@ -67,6 +68,11 @@ pi --no-extensions -e /absolute/path/to/pi-openai-toolkit/extensions/image-gener
 pi --no-extensions -e /absolute/path/to/pi-openai-toolkit/extensions/auto-mode.ts
 ```
 
+```bash
+# Load only the Codex Astra compatibility layer
+pi --no-extensions -e /absolute/path/to/pi-openai-toolkit/extensions/codex-astra.ts
+```
+
 > ⚠️ **Conflict Warning**: Do not run `pi-remote-compact`, `@lll9p/pi-better-compaction`, or standalone `pi-openai-web-search` alongside `pi-openai-toolkit`. Duplicate hooks cause race conditions and duplicated system prompts.
 
 ---
@@ -148,6 +154,12 @@ C:\Users\<user>\.pi\agent\extensions\pi-openai-toolkit\config.json
       "recentDenials": 10,
       "windowSize": 50
     }
+  },
+  "codexAstra": {
+    "enabled": true,
+    "models": [
+      "openai-codex/gpt-6-astra"
+    ]
   }
 }
 ```
@@ -205,6 +217,11 @@ The request uses the current model's resolved Responses endpoint, authentication
 
 Auto mode is opt-in through the empty-by-default `models` allowlist because it authorizes a model to approve writes and shell commands on your behalf. Enable it for a session with `pi --auto` or `/auto on`, and use `/auto all` to review every tool at once. See [Core Mechanics](#core-mechanics) section 5 for the exact decision and fallback rules.
 
+#### `codexAstra`
+
+- `enabled` (*boolean*, default: `false`): Master switch for the GPT-6 Astra compatibility layer: the Codex backend version-gate header on live requests, and the stable-effort `configuration_update` rewrite described in section 6 of Core Mechanics.
+- `models` (*string[]*, default: `[]`): Exact `provider/model-id` allowlist of models that accept the `configuration_update` input item. Only Astra-era models answer it correctly (today `["openai-codex/gpt-6-astra"]`, or your gateway's equivalent key such as `"uwoacrimson/gpt-6-astra"`); the rewrite is never applied to any other model, and the version header applies to all `openai-codex-responses` requests regardless of this list.
+
 ---
 
 ## Core Mechanics
@@ -289,6 +306,18 @@ Pi does not prompt before running `bash`, `write`, or `edit`; the only built-in
 - **Bounded audit trail**: Every decision is persisted as a custom session entry (`pi-openai-toolkit.auto-mode-decision.v1`) containing the tool name, call id, decision, bounded rationale, reviewer model, risk level, user authorization, investigation rounds used, and decision source (`reviewer`, `classifier`, `human`, `policy`, or `circuit-breaker`). Custom entries never enter LLM context, and tool arguments are not recorded.
 - **Cost boundary**: Each gated call costs at least one reviewer completion, and enabling `evidenceTools` lets that review expand into up to `maxEvidenceRounds` extra completions. The pre-scorer adds one small completion per gated tool result when enabled. Reviewer completions run with prompt caching disabled, and the reviewer can execute nothing beyond the read-only tools listed above.
 
+### 6. Codex GPT-6 Astra Compatibility
+
+GPT-6 Astra is a Codex-backend (ChatGPT OAuth) model with two wire behaviors that a plain OpenAI client does not get for free. This layer covers both, adapted from Oh My Pi 18.1.8 (MIT).
+
+- **Backend version gate**: The Codex backend admits or hides model SKUs by the `version` header, and `gpt-6-astra` requires at least `0.153.0`. The extension sets that pin on every live `openai-codex-responses` request via `before_provider_headers` (only when the host has not set one), and the package's own synthetic requests - remote compaction v2, native compact v1, hosted image generation - carry the same pin from the shared header builder. The pinned value tracks the upstream `CODEX_CLIENT_VERSION`; when OpenAI raises the gate, that constant is what changes.
+- **Stable effort with `configuration_update`**: OpenAI prompt caching compares the request from the first byte, and the request-level `reasoning.effort` sits at the top - changing thinking level mid-conversation normally busts the whole cached prefix. Astra instead accepts a `configuration_update` input item that changes effort from that point onward while the request-level field stays put. This extension implements that for the active conversation: the first request pins the baseline effort, every later change is spliced into the transcript at the position it should take effect (before the user message it applies to, or after the latest tool result inside a tool loop), and the same item is replayed at that position on every following request. The request body keeps the baseline byte-stable, so the cache prefix survives level changes.
+- **History-rewrite safety**: Each spliced item is anchored to a fingerprint of the transcript position it was inserted at. If a later request's history no longer matches - compaction, branch switch, `/clear`, anything rewrote the transcript - the baseline is discarded and the next request re-pins its own effort, rather than placing an update at a stale position.
+- **Compaction isolation**: The compact endpoints reject histories containing `configuration_update` items. This is enforced in two places: the payload rewriter never splices items into a `compaction_trigger`-shaped request, and both compaction clients strip any such item defensively from replayed input, so an Astra session can still be compacted by this package.
+- **Scope**: The rewrite applies only to models listed in `codexAstra.models` on either Responses wire family (Astra is the only SKU known to accept the item; anything else answers HTTP 400 on it - the allowlist is what encodes that knowledge for gateways that proxy it), only when the request actually carries a wire-level effort, and never to `off`/`none`. Everything runs inside a try/catch: any unexpected payload shape or planner failure leaves the request untouched. To avoid double-splicing when both this toolkit and a host that implements the same behavior (Oh My Pi itself) are active, enable this layer on only one side.
+
+Catalog note: Pi's bundled `openai-codex` model list does not include `gpt-6-astra` yet. Register it in `~/.pi/agent/models.json` under the built-in provider (custom models merge into the built-in list): `api: "openai-codex-responses"`, `baseUrl: "https://chatgpt.com/backend-api"`, `contextWindow: 272000`, `maxTokens: 128000`, and a `thinkingLevelMap` exposing `low` through `max`. Pi's Codex OAuth login supplies the token; this package reads it through Pi's `ModelRegistry` and never touches the credential store directly.
+
 ---
 
 ## Development & Testing

package/README_zh.md

@@ -10,12 +10,13 @@
 
 ---
 
-`pi-openai-toolkit` 是专为 **Pi (>= 0.84.x)** 打造的 OpenAI 增强工具包，集成了四项针对 OpenAI Responses 协议的扩展：
+`pi-openai-toolkit` 是专为 **Pi (>= 0.84.x)** 打造的 OpenAI 增强工具包，集成了五项针对 OpenAI Responses 协议的扩展：
 
 1. **远端无损压缩 (Remote Compaction v2)** (`extensions/compaction.ts`): 基于 `remote_compaction_v2` SSE 流式协议实现的服务端密文无损会话压缩，彻底告别会话变长后丢失细节的文本二次摘要。
 2. **按模型启用的联网搜索** (`extensions/web-search.ts`): 通过 `webSearch.models` 精确匹配 `provider/model-id`，由 Toolkit 为符合条件的 `openai-responses` 与 `openai-codex-responses` 会话提供并拥有原生联网搜索。
 3. **原生图像生成** (`extensions/image-generation.ts`): 注册由 Responses 托管 `image_generation` 工具驱动的本地顺序工具，支持文生图和显式本地参考图编辑，同时避免把图像二进制写入会话历史。
 4. **模型审批 Auto 模式** (`extensions/auto-mode.ts`): Pi 默认不会为工具调用弹出审批确认。Auto 模式为改变状态的工具调用加上一道审批门，由你指定的审批模型判定放行或拦截，让 Agent 不必停下来等你确认也能继续推进。
+5. **Codex GPT-6 Astra 适配** (`extensions/codex-astra.ts`): 为实时请求补发 Codex 后端版本门禁头，并在 `gpt-6-astra` 上把思考档位变更改写为 `configuration_update` 会话项，换档位不再打断提示缓存。
 
 ## 安装使用
 
@@ -65,6 +66,9 @@ pi --no-extensions -e /本地绝对路径/pi-openai-toolkit/extensions/image-gen
 
 # 仅加载 Auto 模式
 pi --no-extensions -e /本地绝对路径/pi-openai-toolkit/extensions/auto-mode.ts
+
+# 仅加载 Codex Astra 适配
+pi --no-extensions -e /本地绝对路径/pi-openai-toolkit/extensions/codex-astra.ts
 ```
 
 > ⚠️ **冲突提示**：请勿同时启用 `pi-remote-compact`、`@lll9p/pi-better-compaction` 或独立的 `pi-openai-web-search`。多重钩子会产生竞态或注入重复的 System Prompt。
@@ -148,6 +152,12 @@ C:\Users\<user>\.pi\agent\extensions\pi-openai-toolkit\config.json
       "recentDenials": 10,
       "windowSize": 50
     }
+  },
+  "codexAstra": {
+    "enabled": true,
+    "models": [
+      "openai-codex/gpt-6-astra"
+    ]
   }
 }
 ```
@@ -201,10 +211,15 @@ C:\Users\<user>\.pi\agent\extensions\pi-openai-toolkit\config.json
 - `classifier.model` (*string | null*): 预评分模型，格式 `provider/model-id`，未设置时沿用 `reviewerModel`。预评分只能把调用退回阻塞审批；除了缓存的 `low` 快速通道之外它无权放行，也永不拒绝。
 - `classifier.timeoutMs` (*整数*, 默认 `15000`) 与 `classifier.maxLag` (*整数*, 默认 `2`，范围 `0`–`20`): 经过超过 `maxLag` 个工具调用、或用户又说了新话之后，分数作废并强制走阻塞审批。
 - `circuitBreaker.consecutiveDenials` (*整数*, 默认 `3`，`0` 关闭): 单轮内连续拒绝多少次就直接结束这一轮，而不是让主模型无限拉锯。
-- `circuitBreaker.recentDenials` (*整数*, 默认 `10`，`0` 关闭) 与 `circuitBreaker.windowSize` (*整数*, 默认 `50`，范围 `1`–`200`): 最近 N 次受审调用里拒绝多少次就结束这一轮。它拓的是没有连续出现但密度很高的拒绝。
+- `circuitBreaker.recentDenials` (*整数*, 默认 `10`，`0` 关闭) 与 `circuitBreaker.windowSize` (*整数*, 默认 `50`，范围 `1`–`200`): 最近 N 次受审调用里拒绝多少次就结束这一轮。它抓的是没有连续出现但密度很高的拒绝。
 
 Auto 模式需要显式启用（`models` 默认为空），因为它相当于允许一个模型代你批准文件写入和命令执行。会话内可用 `pi --auto` 或 `/auto on` 开启，`/auto all` 一次审批全部工具。具体判定与降级规则见「核心工作原理解析」第 5 节。
 
+#### `codexAstra`（Codex GPT-6 Astra 适配配置）
+
+- `enabled` (*boolean*, 默认 `false`): Astra 适配层总开关：实时请求的版本门禁头，以及「核心工作原理解析」第 6 节描述的 stable-effort 改写。
+- `models` (*string[]*, 默认 `[]`): 接受 `configuration_update` 会话项的精确 `provider/model-id` 白名单。只有 Astra 世代模型能正确响应它（目前 `["openai-codex/gpt-6-astra"]`，或网关上对应的键如 `"uwoacrimson/gpt-6-astra"`）；其他模型绝不会被改写。版本门禁头则对所有 `openai-codex-responses` 实时请求生效，不受这个列表限制。
+
 ---
 
 ## 核心工作原理解析
@@ -289,6 +304,18 @@ Pi 本身在运行 `bash`、`write`、`edit` 前不会询问确认，内置的
 - **有界审计记录**：每次判定都以自定义会话条目（`pi-openai-toolkit.auto-mode-decision.v1`）落盘，包含工具名、调用 id、结论、有界理由、审批模型、风险等级、用户授权程度、取证轮数，以及判定来源（`reviewer`、`classifier`、`human`、`policy` 或 `circuit-breaker`）。自定义条目不进入 LLM 上下文，且不记录工具参数。
 - **费用边界**：每个受控调用至少产生一次审批补全；开启 `evidenceTools` 后，这一次审批最多可膨胀为 `maxEvidenceRounds` 轮额外补全。开启预评分时，每个受控工具结果多一次小补全。审批请求禁用提示缓存，除上述只读工具外不能执行任何操作。
 
+### 6. Codex GPT-6 Astra 适配
+
+GPT-6 Astra 是 Codex 后端（ChatGPT OAuth）上的模型，有两个普通 OpenAI 客户端不会自动处理的线协议行为。本适配层全部覆盖，代码改写自 Oh My Pi 18.1.8（MIT）。
+
+- **后端版本门禁**：Codex 后端按 `version` 头决定放行或隐藏模型 SKU，`gpt-6-astra` 要求至少 `0.153.0`。扩展通过 `before_provider_headers` 给每条实时 `openai-codex-responses` 请求补发这个固定值（host 已设置时不覆盖）；本包自己的合成请求（远端 v2、原生 v1、托管图像）由共享头构造器携带同一固定值。这个常量跟随上游 `CODEX_CLIENT_VERSION`：OpenAI 提高门禁时，改的就是它。
+- **stable effort + `configuration_update`**：OpenAI 提示缓存从请求第一个字节开始比对，而请求级 `reasoning.effort` 就在头部——中途换思考档位通常会打爆整个缓存前缀。Astra 接受一种 `configuration_update` 输入项，从该项位置起改档位而不动请求级字段。本扩展把这套机制接到当前会话：首个请求钉住基线档位，之后的每次变更插入到它应生效的会话位置（作效于哪条用户消息就插在哪条之前，工具循环中途变更插在最近一条工具结果之后），后续请求在同一位置重放该项，请求体开头始终字节不变，缓存前缀存活。
+- **历史重写安全**：每个插入项都锚定在它所在位置前一条内容的指纹上。后续请求的历史对不上（压缩、切分支、`/clear`，任何历史重写），基线直接作废，下一次请求用自己的档位重新钉基线，而不是把更新插到过期位置。
+- **压缩隔离**：compact 端点拒绝含 `configuration_update` 的历史。两层防御：payload 改写器对带 `compaction_trigger` 的请求绝不插入；两个压缩客户端对回放输入里的该类项一律防御性剥离——所以 Astra 会话照常被本包压缩。
+- **适用范围**：改写只作用于两种 Responses 线协议家族内 `codexAstra.models` 白名单中的模型（目前已知只有 astra 接受该 item，其他模型碰它就 400——网关代理同一模型时，白名单就是声明这件事的地方），且只改真正携带线上级 effort 的请求，`off`/`none` 不动。整个钩子在 try/catch 里，任何意外形状或规划失败都原样放行请求。若 host 自身已实现同样行为（例如 Oh My Pi），两边只开一个，避免双重插入。
+
+目录说明：Pi 内置的 `openai-codex` 模型列表还没有 `gpt-6-astra`，需要在 `~/.pi/agent/models.json` 内置 provider 下注册（自定义 models 会与内置列表合并）：`api: "openai-codex-responses"`、`baseUrl: "https://chatgpt.com/backend-api"`、`contextWindow: 272000`、`maxTokens: 128000`，并用 `thinkingLevelMap` 声明 `low` 到 `max`。登录用 Pi 的 Codex OAuth 流程；本包通过 Pi 的 `ModelRegistry` 读凭据，不碰存储文件。
+
 ---
 
 ## 测试与验证

package/extensions/codex-astra.ts

@@ -0,0 +1 @@
+export { default } from "../src/codex-astra/extension.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-openai-toolkit",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "private": false,
   "type": "module",
   "description": "OpenAI-focused Pi toolkit providing remote Responses compaction, native Web Search, native image generation, and model-reviewed auto mode.",
@@ -34,7 +34,8 @@
       "./extensions/compaction.ts",
       "./extensions/web-search.ts",
       "./extensions/image-generation.ts",
-      "./extensions/auto-mode.ts"
+      "./extensions/auto-mode.ts",
+      "./extensions/codex-astra.ts"
     ]
   },
   "files": [
@@ -65,6 +66,9 @@
     "src/auto-mode/reviewer.ts",
     "src/auto-mode/classifier.ts",
     "src/auto-mode/types.ts",
+    "extensions/codex-astra.ts",
+    "src/codex-astra/effort-planner.ts",
+    "src/codex-astra/extension.ts",
     "src/model-scope.ts",
     "src/native-fallback.ts",
     "src/payload-rewrite.ts",

package/src/codex-astra/effort-planner.ts

@@ -0,0 +1,175 @@
+import { createHash } from "node:crypto";
+
+/**
+ * Stable request-level reasoning effort via `configuration_update` input items
+ * (GPT-6 Astra), ported from Oh My Pi (`@oh-my-pi/pi-ai`, MIT licensed,
+ * Copyright (c) 2025-2026 Can Bölük / Stencil Labs) to an extension-side
+ * payload rewrite.
+ *
+ * The request-level `reasoning.effort` is pinned to the value of the session's
+ * first request so the cached prompt prefix survives an effort change. Each
+ * later change is carried as a `configuration_update` item inserted at the
+ * tail of the transcript — before the user message it takes effect on, or
+ * after the latest tool result when the level changes inside a tool loop — and
+ * replayed at that position on every subsequent request until another update
+ * overrides it.
+ *
+ * Wire constraints (verified upstream against the Codex backend): only
+ * `gpt-6-astra` accepts the item type, consecutive updates are rejected, and
+ * `/responses/compact` rejects histories containing them — compaction
+ * requests are built outside this planner and never carry the items.
+ */
+
+/** `configuration_update` input item; only `reasoning.effort` is updatable. */
+export type ConfigurationUpdateItem = {
+	type: "configuration_update";
+	reasoning: { effort: string };
+};
+
+export type PlannableInputItem = {
+	type?: string | null;
+	role?: string;
+	id?: string | null;
+	status?: string | null;
+	[key: string]: unknown;
+};
+
+type EffortTransition = {
+	/** Input-array position the item is spliced into (before `input[index]`). */
+	index: number;
+	/** Fingerprint of `input[index - 1]` at record time; a mismatch means the history was rewritten. */
+	anchor: string;
+	effort: string;
+};
+
+/** Per-conversation effort baseline and recorded transitions. */
+export type EffortControlState = {
+	baseEffort?: string;
+	currentEffort?: string;
+	transitions: EffortTransition[];
+};
+
+export type EffortPlanResult = {
+	/** The request-level effort that must accompany the returned input. */
+	effort: string;
+	/** Number of `configuration_update` items spliced into this request. */
+	spliced: number;
+};
+
+export function createEffortControlState(): EffortControlState {
+	return { transitions: [] };
+}
+
+const MAX_EFFORT_CONTROL_STATES = 16;
+
+/**
+ * Fetch (or create) the control state for one conversation from a bounded
+ * LRU map, refreshing its slot.
+ */
+export function getEffortControlState(states: Map<string, EffortControlState>, key: string): EffortControlState {
+	const existing = states.get(key);
+	if (existing) {
+		states.delete(key);
+		states.set(key, existing);
+		return existing;
+	}
+	const created = createEffortControlState();
+	states.set(key, created);
+	if (states.size > MAX_EFFORT_CONTROL_STATES) {
+		const oldest = states.keys().next().value;
+		if (oldest !== undefined) states.delete(oldest);
+	}
+	return created;
+}
+
+/**
+ * Fingerprint of the item a transition sits after. Output-only lifecycle
+ * fields are excluded: a live response item carries `id`/`status` that the
+ * sanitized replay of the same item drops.
+ */
+function transitionAnchor(input: readonly PlannableInputItem[], index: number): string {
+	if (index === 0) return "";
+	const item = input[index - 1];
+	if (!item) return "";
+	const { id: _id, status: _status, ...stable } = item;
+	return createHash("sha1").update(JSON.stringify(stable)).digest("hex");
+}
+
+function resetEffortControlState(state: EffortControlState): void {
+	state.baseEffort = undefined;
+	state.currentEffort = undefined;
+	state.transitions = [];
+}
+
+/**
+ * Discard the baseline when the request no longer continues the conversation
+ * it was captured for: a wire history that shrank or was rewritten under a
+ * recorded transition (compaction, branch switch, `/clear`). The next request
+ * re-baselines from its own effort, which is what the API asks for after
+ * compaction anyway.
+ */
+function syncEffortControlState(state: EffortControlState, input: readonly PlannableInputItem[]): void {
+	for (const transition of state.transitions) {
+		if (transition.index > input.length || transition.anchor !== transitionAnchor(input, transition.index)) {
+			resetEffortControlState(state);
+			return;
+		}
+	}
+}
+
+/**
+ * Pin the request-level effort to the session baseline and splice pending
+ * `configuration_update` items into a copy of `input`.
+ *
+ * `input` is the freshly built transcript for this request, without any
+ * `configuration_update` items. `requested` is the wire effort the caller
+ * would otherwise send at the request level.
+ */
+export function planStableEffort(
+	state: EffortControlState,
+	input: readonly PlannableInputItem[],
+	requested: string,
+): { input: Array<PlannableInputItem | ConfigurationUpdateItem>; result: EffortPlanResult } {
+	const next: Array<PlannableInputItem | ConfigurationUpdateItem> = [...input];
+	syncEffortControlState(state, next);
+	if (state.baseEffort === undefined) {
+		state.baseEffort = requested;
+		state.currentEffort = requested;
+		return { input: next, result: { effort: requested, spliced: 0 } };
+	}
+	if (state.currentEffort !== requested) {
+		const last = next[next.length - 1];
+		const index = last && last.role === "user" ? next.length - 1 : next.length;
+		const existing = state.transitions.find((transition) => transition.index === index);
+		if (existing) {
+			existing.effort = requested;
+		} else {
+			state.transitions.push({ index, anchor: transitionAnchor(next, index), effort: requested });
+		}
+		// A change back to the effort already in force at that position is a
+		// no-op on the wire; drop it rather than send a redundant item.
+		let preceding = state.baseEffort;
+		let precedingIndex = -1;
+		for (const transition of state.transitions) {
+			if (transition.index < index && transition.index > precedingIndex) {
+				preceding = transition.effort;
+				precedingIndex = transition.index;
+			}
+		}
+		if (requested === preceding) {
+			state.transitions = state.transitions.filter((transition) => transition.index !== index);
+		}
+		state.currentEffort = requested;
+	}
+	// Splice in ascending order so each insertion offsets only the ones after it.
+	state.transitions.sort((a, b) => a.index - b.index);
+	let offset = 0;
+	for (const transition of state.transitions) {
+		next.splice(transition.index + offset, 0, {
+			type: "configuration_update",
+			reasoning: { effort: transition.effort },
+		});
+		offset++;
+	}
+	return { input: next, result: { effort: state.baseEffort, spliced: state.transitions.length } };
+}

package/src/codex-astra/extension.ts

@@ -0,0 +1,128 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadToolkitConfig } from "../config";
+import { isExactModelAllowed } from "../model-scope";
+import { CODEX_CLIENT_VERSION } from "../responses-headers";
+import {
+	getEffortControlState,
+	planStableEffort,
+	type EffortControlState,
+	type PlannableInputItem,
+} from "./effort-planner";
+
+type AstraPayload = {
+	model: string;
+	input: PlannableInputItem[];
+	reasoning: { effort: string; [key: string]: unknown };
+	[key: string]: unknown;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Recognize the live Codex Responses request body: model + wire input array
+ * + a request-level string effort. Anything else (titles, embeddings, or a
+ * shape we do not understand) is left untouched.
+ */
+function parseAstraPayload(payload: unknown): AstraPayload | undefined {
+	if (!isRecord(payload)) return undefined;
+	if (typeof payload.model !== "string") return undefined;
+	if (!Array.isArray(payload.input)) return undefined;
+	const reasoning = payload.reasoning;
+	if (!isRecord(reasoning) || typeof reasoning.effort !== "string") return undefined;
+	if (reasoning.effort.length === 0 || reasoning.effort === "none") return undefined;
+	if (!payload.input.every((item) => isRecord(item))) return undefined;
+	return payload as unknown as AstraPayload;
+}
+
+function isCompactionShaped(payload: AstraPayload): boolean {
+	// A `compaction_trigger` history belongs to a compact endpoint request,
+	// which rejects `configuration_update` items. Our compaction clients use
+	// direct fetch and never reach this hook; this guard covers any future
+	// provider-routed compaction.
+	const last = payload.input[payload.input.length - 1];
+	return !!last && isRecord(last) && last.type === "compaction_trigger";
+}
+
+function getSessionId(ctx: { sessionManager: { getSessionId(): string } }): string | undefined {
+	try {
+		return ctx.sessionManager.getSessionId();
+	} catch {
+		return undefined;
+	}
+}
+
+export function registerCodexAstraExtension(
+	pi: ExtensionAPI,
+	loadConfig: typeof loadToolkitConfig = loadToolkitConfig,
+): void {
+	const states = new Map<string, EffortControlState>();
+
+	// Switching or forking a session rebuilds the runtime and re-fires
+	// session_start; clearing there covers every replacement path.
+	pi.on("session_start", () => {
+		states.clear();
+	});
+
+	pi.on("before_provider_request", (event, ctx) => {
+		try {
+			const { config } = loadConfig();
+			const astra = config.codexAstra;
+			if (!astra.enabled || astra.models.length === 0) return undefined;
+
+			const model = ctx.model;
+			// Both Responses wire families carry the same reasoning.effort prefix
+			// problem, and upstream OMP plans on both providers; which models
+			// accept the item is decided by the allowlist, not by API family.
+			if (!model || (model.api !== "openai-codex-responses" && model.api !== "openai-responses")) {
+				return undefined;
+			}
+			if (!isExactModelAllowed(model, astra.models)) return undefined;
+
+			const payload = parseAstraPayload(event.payload);
+			// The payload must belong to the model the eligibility check just
+			// passed; a mismatch means this request is not ours to plan.
+			if (!payload || payload.model !== model.id) return undefined;
+			if (isCompactionShaped(payload)) return undefined;
+
+			const sessionId = getSessionId(ctx);
+			const state = getEffortControlState(
+				states,
+				`${model.baseUrl ?? ""}\u0000${model.id}\u0000${sessionId ?? "no-session"}`,
+			);
+
+			// Idempotence: never plan on top of items a previous pass injected.
+			const history = payload.input.filter((item) => item.type !== "configuration_update");
+			const { input, result } = planStableEffort(state, history, payload.reasoning.effort);
+			if (result.effort === payload.reasoning.effort && result.spliced === 0) return undefined;
+
+			return {
+				...payload,
+				input,
+				reasoning: { ...payload.reasoning, effort: result.effort },
+			};
+		} catch {
+			// A planner failure must never break the provider request path.
+			return undefined;
+		}
+	});
+
+	pi.on("before_provider_headers", (event, ctx) => {
+		try {
+			const model = ctx.model;
+			if (!model || model.api !== "openai-codex-responses") return;
+			// Live requests need the same backend version gate as our synthetic
+			// ones: an old or missing `version` never reaches gated SKUs.
+			if (!event.headers.version) {
+				event.headers.version = CODEX_CLIENT_VERSION;
+			}
+		} catch {
+			// Header injection is best-effort.
+		}
+	});
+}
+
+export default function codexAstraExtension(pi: ExtensionAPI): void {
+	registerCodexAstraExtension(pi);
+}

package/src/compact-client.ts

@@ -1,5 +1,6 @@
 import { writeDebugArtifact } from "./debug";
 import { buildResponsesRequestHeaders } from "./responses-headers";
+import { stripConfigurationUpdateItems } from "./remote-v2-client";
 import type { NativeCompactionRuntime } from "./runtime";
 import type { NativeCompactionRequestBody } from "./serializer";
 import type { ArtifactContext, CompactionConfig } from "./types";
@@ -114,7 +115,10 @@ export function extractCompactedSummaryText(output: readonly unknown[]): string
 
 function toHeaders(runtime: NativeCompactionRuntime): Record<string, string> {
 	return Object.fromEntries(
-		buildResponsesRequestHeaders(runtime, { accept: JSON_CONTENT_TYPE }).entries(),
+		buildResponsesRequestHeaders(runtime, {
+			accept: JSON_CONTENT_TYPE,
+			sessionId: runtime.sessionId,
+		}).entries(),
 	);
 }
 
@@ -133,7 +137,13 @@ function writeCompactArtifact(
 export async function executeNativeCompaction(
 	options: ExecuteNativeCompactionOptions,
 ): Promise<NativeCompactionClientResult> {
-	const { runtime, request, signal, settings, context } = options;
+	const { runtime, signal, settings, context } = options;
+	// Same Astra-history rejection as remote v2: `/responses/compact` rejects
+	// `configuration_update` items, so a replayed history never carries one.
+	const request: NativeCompactionRequestBody = {
+		...options.request,
+		input: stripConfigurationUpdateItems(options.request.input) as NativeCompactionRequestBody["input"],
+	};
 	const headers = toHeaders(runtime);
 
 	if (signal?.aborted) {

package/src/config.ts

@@ -8,6 +8,7 @@ import {
 	DEFAULT_AUTO_COMPACTION_CONFIG,
 	DEFAULT_AUTO_MODE_CONFIG,
 	DEFAULT_IMAGE_GENERATION_CONFIG,
+	DEFAULT_CODEX_ASTRA_CONFIG,
 	DEFAULT_NATIVE_FALLBACK_CONFIG,
 	DEFAULT_WEB_SEARCH_CONFIG,
 	RESPONSES_COMPACT_CAPABLE_APIS,
@@ -28,6 +29,7 @@ import {
 	type AutoModeClassifierConfig,
 	type AutoModeConfig,
 	type AutoModeGate,
+	type CodexAstraConfig,
 	type CompactionConfig,
 	type ImageGenerationConfig,
 	type LoadedToolkitConfig,
@@ -39,7 +41,7 @@ import {
 export const CONFIG_DIR = path.join(os.homedir(), ".pi", "agent", "extensions", TOOLKIT_ID);
 export const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
 
-const TOP_LEVEL_FIELDS = new Set(["compaction", "webSearch", "imageGeneration", "autoMode"]);
+const TOP_LEVEL_FIELDS = new Set(["compaction", "webSearch", "imageGeneration", "autoMode", "codexAstra"]);
 const COMPACTION_FIELDS = new Set([
 	"enabled",
 	"allowCompactionContinuityBreak",
@@ -58,6 +60,7 @@ const NATIVE_FALLBACK_FIELDS = new Set(["enabled", "model", "thinkingLevel"]);
 const AUTO_COMPACTION_FIELDS = new Set(["enabled", "continuation", "unsupportedFallback", "reserveTokens"]);
 const WEB_SEARCH_FIELDS = new Set(["enabled", "models"]);
 const IMAGE_GENERATION_FIELDS = new Set(["enabled"]);
+const CODEX_ASTRA_FIELDS = new Set(["enabled", "models"]);
 const AUTO_MODE_FIELDS = new Set([
 	"enabled",
 	"models",
@@ -269,6 +272,10 @@ function cloneDefaults(): ToolkitConfig {
 			models: [...DEFAULT_WEB_SEARCH_CONFIG.models],
 		},
 		imageGeneration: { ...DEFAULT_IMAGE_GENERATION_CONFIG },
+		codexAstra: {
+			...DEFAULT_CODEX_ASTRA_CONFIG,
+			models: [...DEFAULT_CODEX_ASTRA_CONFIG.models],
+		},
 		autoMode: {
 			...DEFAULT_AUTO_MODE_CONFIG,
 			models: [...DEFAULT_AUTO_MODE_CONFIG.models],
@@ -417,6 +424,20 @@ function applyImageGenerationConfig(
 		toBoolean(raw.enabled, "imageGeneration.enabled", warnings) ?? resolved.enabled;
 }
 
+function applyCodexAstraConfig(
+	raw: Record<string, unknown>,
+	resolved: CodexAstraConfig,
+	warnings: string[],
+): void {
+	warnUnknownFields(raw, CODEX_ASTRA_FIELDS, "codexAstra", warnings);
+	resolved.enabled = toBoolean(raw.enabled, "codexAstra.enabled", warnings) ?? resolved.enabled;
+
+	const models = toStringList(raw.models, "codexAstra.models", warnings);
+	if (models !== undefined) {
+		resolved.models = models;
+	}
+}
+
 function applyAutoModeConfig(
 	raw: Record<string, unknown>,
 	resolved: AutoModeConfig,
@@ -604,6 +625,14 @@ export function loadToolkitConfig(configPath: string = CONFIG_PATH): LoadedToolk
 				warnings.push("Ignoring autoMode: expected a JSON object.");
 			}
 		}
+
+		if (raw.codexAstra !== undefined) {
+			if (isRecord(raw.codexAstra)) {
+				applyCodexAstraConfig(raw.codexAstra, resolved.codexAstra, warnings);
+			} else {
+				warnings.push("Ignoring codexAstra: expected a JSON object.");
+			}
+		}
 	}
 
 	resolved.compaction.artifactRoot = resolveConfiguredPath(

package/src/remote-v2-client.ts

@@ -119,16 +119,32 @@ function toHeaders(runtime: NativeCompactionRuntime): Record<string, string> {
 		buildResponsesRequestHeaders(runtime, {
 			accept: SSE_CONTENT_TYPE,
 			contentType: JSON_CONTENT_TYPE,
+			sessionId: runtime.sessionId,
 		}).entries(),
 	);
 }
 
+/**
+ * Codex `/responses` rejects histories that mix this Astra-only item into a
+ * compaction request (verified upstream in Oh My Pi: the compaction path is
+ * deliberately built outside the effort planner). The host never emits the
+ * item into a payload we would replay today, but the item is transparently
+ * carried by our opaque-window replay, so strip it defensively on every
+ * remote v2 request regardless of API family.
+ */
+export function stripConfigurationUpdateItems(input: readonly unknown[]): unknown[] {
+	return input.filter((item) => !isRecord(item) || item["type"] !== "configuration_update");
+}
+
 export function buildRemoteV2CompactionRequest(
 	request: NativeCompactionRequestBody,
 ): RemoteV2CompactionRequestBody {
 	return {
 		...structuredClone(request),
-		input: [...structuredClone(request.input), { type: "compaction_trigger" }],
+		input: [
+			...(stripConfigurationUpdateItems(structuredClone(request.input)) as ResponsesInputItem[]),
+			{ type: "compaction_trigger" },
+		],
 		store: false,
 		stream: true,
 	};

package/src/responses-headers.ts

@@ -5,6 +5,7 @@ export type ResponsesHeaderRuntime = {
 	api: string;
 	apiKey: string;
 	headers?: ProviderHeaders;
+	sessionId?: string;
 	currentModel: {
 		headers?: ProviderHeaders;
 	};
@@ -38,9 +39,34 @@ function buildCodexUserAgent(): string {
 	return `pi (${platform}; ${arch})`;
 }
 
+/**
+ * The Codex backend version-gates model availability on the `version` header
+ * (the pinned @openai/codex client version). `gpt-6-astra` requires >= 0.153.0;
+ * an older or absent pin makes the SKU invisible to discovery and rejects
+ * requests that name it. Keep this in sync with the newest gate Oh My Pi pins
+ * in @oh-my-pi/pi-wire/codex (`CODEX_CLIENT_VERSION`).
+ */
+export const CODEX_CLIENT_VERSION = "0.153.0";
+
+/** Prompt cache keys are clamped by the same host rule (`OPENAI_PROMPT_CACHE_KEY_MAX_LENGTH`). */
+const CODEX_SESSION_ID_MAX_LENGTH = 64;
+
+export function clampCodexSessionId(sessionId: string | undefined): string | undefined {
+	if (!sessionId) return undefined;
+	const chars = Array.from(sessionId);
+	return chars.length <= CODEX_SESSION_ID_MAX_LENGTH ? sessionId : chars.slice(0, CODEX_SESSION_ID_MAX_LENGTH).join("");
+}
+
+export type ResponsesHeaderOptions = {
+	accept: string;
+	contentType?: string;
+	/** Conversation identity for Codex cache-affinity headers; clamped to 64 chars here. */
+	sessionId?: string;
+};
+
 export function buildResponsesRequestHeaders(
 	runtime: ResponsesHeaderRuntime,
-	options: { accept: string; contentType?: string },
+	options: ResponsesHeaderOptions,
 ): Headers {
 	const headers = new Headers(
 		mergeProviderHeaders(runtime.currentModel.headers, runtime.headers),
@@ -57,6 +83,21 @@ export function buildResponsesRequestHeaders(
 		headers.set("originator", "pi");
 		headers.set("user-agent", buildCodexUserAgent());
 		headers.set("openai-beta", "responses=experimental");
+		// Codex backend gating: a request without a new-enough `version` never
+		// reaches model SKUs that arrived behind the gate (gpt-6-astra).
+		headers.set("version", CODEX_CLIENT_VERSION);
+		// Prompt-cache affinity rides on the conversation identity: the backend
+		// keeps a conversation's cache prefix on the node that wrote it, so our
+		// synthetic compaction requests must present the same id the live
+		// transcript requests used, or every compact pays a full cache miss.
+		const sessionId = clampCodexSessionId(options.sessionId ?? runtime.sessionId);
+		if (sessionId) {
+			// Header names match the installed host's live-request builder
+			// (`buildSSEHeaders`: `session-id` + `x-client-request-id`) so our
+			// synthetic requests land in the same conversation affinity group.
+			headers.set("session-id", sessionId);
+			headers.set("x-client-request-id", sessionId);
+		}
 	}
 
 	return headers;

package/src/runtime.ts

@@ -54,6 +54,12 @@ export type ResponsesRuntime = {
 	headers?: ProviderHeaders;
 	responsesPath: string;
 	responsesUrl: string;
+	/**
+	 * Conversation identity for Codex prompt-cache affinity headers. Synthetic
+	 * compaction/review requests must present the same id the live transcript
+	 * requests used or the backend treats them as a new conversation.
+	 */
+	sessionId?: string;
 	currentModel: RuntimeModel;
 };
 
@@ -229,6 +235,15 @@ export function getRuntimeModelDescriptor(model: RuntimeModel | undefined): {
 	};
 }
 
+/** Best-effort conversation id; header emission then simply skips the affinity headers. */
+export function resolveRuntimeSessionId(ctx: ExtensionContext): string | undefined {
+	try {
+		return ctx.sessionManager.getSessionId();
+	} catch {
+		return undefined;
+	}
+}
+
 async function resolveNativeCompactionEnvironmentForModel(
 	ctx: ExtensionContext,
 	currentModel: RuntimeModel | undefined,
@@ -336,6 +351,7 @@ async function resolveNativeCompactionEnvironmentForModel(
 			responsesUrl: buildResponsesUrl(baseUrl, descriptor.api),
 			compactPath: buildCompactPath(descriptor.api),
 			compactUrl: buildCompactUrl(baseUrl, descriptor.api),
+			sessionId: resolveRuntimeSessionId(ctx),
 			payload: requestPayload,
 			currentModel,
 		},
@@ -361,6 +377,7 @@ export async function resolveResponsesEnvironment(
 			headers: runtime.headers,
 			responsesPath: runtime.responsesPath,
 			responsesUrl: runtime.responsesUrl,
+			sessionId: runtime.sessionId,
 			currentModel: runtime.currentModel,
 		},
 	};

package/src/types.ts

@@ -97,6 +97,12 @@ export type ImageGenerationConfig = {
 	enabled: boolean;
 };
 
+export type CodexAstraConfig = {
+	enabled: boolean;
+	/** Exact provider/model keys that receive the stable-effort `configuration_update` rewrite. */
+	models: string[];
+};
+
 /** `side-effect` reviews bash/write/edit plus extras; `all` reviews every tool call. */
 export type AutoModeGate = "side-effect" | "all";
 
@@ -162,6 +168,7 @@ export type ToolkitConfig = {
 	webSearch: WebSearchConfig;
 	imageGeneration: ImageGenerationConfig;
 	autoMode: AutoModeConfig;
+	codexAstra: CodexAstraConfig;
 };
 
 export type LoadedToolkitConfig = {
@@ -524,6 +531,11 @@ export const DEFAULT_IMAGE_GENERATION_CONFIG: ImageGenerationConfig = {
 	enabled: false,
 };
 
+export const DEFAULT_CODEX_ASTRA_CONFIG: CodexAstraConfig = {
+	enabled: false,
+	models: [],
+};
+
 export const DEFAULT_AUTO_MODE_CONFIG: AutoModeConfig = {
 	enabled: true,
 	models: [],
@@ -552,4 +564,5 @@ export const DEFAULT_TOOLKIT_CONFIG: ToolkitConfig = {
 	webSearch: DEFAULT_WEB_SEARCH_CONFIG,
 	imageGeneration: DEFAULT_IMAGE_GENERATION_CONFIG,
 	autoMode: DEFAULT_AUTO_MODE_CONFIG,
+	codexAstra: DEFAULT_CODEX_ASTRA_CONFIG,
 };