codex-516-guard 0.1.0__py3-none-any.whl

codex_516_guard-0.1.0.dist-info/METADATA

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: codex-516-guard
+Version: 0.1.0
+Summary: Local Responses proxy for OpenAI Codex CLI: folds gpt-5.5 518n-2 reasoning truncation (516 degradation) via the official openai_base_url wiring — no provider change, WebSocket-first, no fallback noise.
+Project-URL: Homepage, https://github.com/dzshzx/codex-516-guard
+Project-URL: Repository, https://github.com/dzshzx/codex-516-guard
+Project-URL: Issues, https://github.com/dzshzx/codex-516-guard/issues
+Author: dzshzx
+License-Expression: MIT
+License-File: LICENSE
+Keywords: 516,codex,gpt-5.5,openai,proxy,reasoning
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: Proxy Servers
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: starlette>=0.41
+Requires-Dist: uvicorn[standard]>=0.32
+Requires-Dist: zstandard>=0.23
+Description-Content-Type: text/markdown
+
+# codex-516-guard
+
+> Local Responses proxy for OpenAI Codex CLI: detects the gpt-5.5 "516" reasoning-truncation
+> fingerprint (`reasoning_tokens == 518*n - 2`), auto-continues the model's thinking, and folds
+> all rounds into one response — **without changing `model_provider`**, so session grouping,
+> remote compaction and remote-control stay intact. WebSocket-first: no
+> "Falling back from WebSockets" retry noise.
+
+自研本地 Responses 代理，缓解 Codex gpt-5.5 的「516 降智」：思考在
+`reasoning_tokens == 518*n - 2`（516、1034、1552…）处被截断，答案质量骤降
+（上游 issue：[openai/codex#30364](https://github.com/openai/codex/issues/30364)，无官方修复）。
+本代理检测该指纹后自动让模型继续思考，并把多轮续写**折叠为单个下游响应**。
+
+机制思路来自 [neteroster/CodexCont](https://github.com/neteroster/CodexCont)（MIT），
+实现为全新代码。与其关键差异：
+
+| | codex-516-guard | CodexCont |
+| --- | --- | --- |
+| Codex 侧接线 | 顶层 `openai_base_url`（**不新建 provider**） | 新建 `[model_providers]`（会话按 provider 分组被隐藏、remote-control 不可用、丢远程压缩） |
+| 下游传输 | **WebSocket 第一传输**（完整实现 `responses_websockets` 协议）+ SSE 兜底 | 仅 SSE（codex 先试 ws → 405 → 每会话约 5 次重连告警后回退） |
+| zstd 请求压缩（0.142.x 内置 provider 默认开） | 原生解压，无需改 codex 配置 | 需 `[features] enable_request_compression = false` |
+| `GET /v1/models` 模型目录刷新 | `/v1/*` 透传 | 未代理（静默失败，靠本地缓存） |
+| 续写方法 | commentary 法（`phase:"commentary"` 消息 + encrypted reasoning 重放） | commentary + tool_pair legacy + 跨轮 repair 等更多可配置项 |
+
+## 原理
+
+1. 上游每轮结束时读取 `usage.output_tokens_details.reasoning_tokens`，命中 `518n-2`（n∈[1,6]，最多续写 3 轮）即判定思考被截断；
+2. 丢弃该轮的**暂定输出**（message / tool calls——它们基于被截断的思考），把该轮 reasoning items（含 `encrypted_content`）+ 一条 `Continue thinking...` 的 `phase:"commentary"` 助手消息追加进 input 重放，开下一轮；
+3. 思考流实时透传给 agent，只有干净收尾那一轮的最终输出被放行；terminal 事件重建为单响应口径的 usage（input 取第 1 轮防止「假爆上下文」，reasoning 求和），真实累计成本记在 `metadata.proxy_billed_usage`。
+
+## 安装
+
+要求：[uv](https://docs.astral.sh/uv/)（自带 Python 管理）、Codex CLI（ChatGPT OAuth 登录，0.142.x 实测）。
+
+```bash
+uv tool install codex-516-guard          # 从 PyPI 安装
+# 或直接从源码仓库：
+# uv tool install git+https://github.com/dzshzx/codex-516-guard
+```
+
+uv 会建一个隔离环境并把可执行文件放进 uv 的 bin 目录（Unix/macOS 默认 `~/.local/bin`，
+Windows 用 `where.exe codex-516-guard` 查实际路径；`uv tool update-shell` 可把该目录加进 PATH）。
+之后：
+
+```bash
+codex-516-guard                          # 前台跑起（默认 127.0.0.1:8787）
+codex-516-guard --port 8790 --log-level debug   # 可选参数：--host/--port/--upstream/--log-level
+```
+
+升级 / 卸载：`uv tool upgrade codex-516-guard` / `uv tool uninstall codex-516-guard`。
+
+Codex 侧接线——`~/.codex/config.toml` 顶层（必须在第一个 `[table]` 之前）加一行：
+
+```toml
+openai_base_url = "http://127.0.0.1:8787/v1"
+```
+
+这是覆盖内置 openai provider base_url 的**官方 config key**
+（[#16719](https://github.com/openai/codex/issues/16719)；同名 `[model_providers.openai]`
+覆盖被维护者拒绝，`OPENAI_BASE_URL` 环境变量已移除）。provider id 保持 `openai`，
+因此会话历史分组、远程压缩、remote-control 均不受影响。
+
+**关闭**：注释掉 `openai_base_url` 行 + 停掉代理进程。代理停止而 key 在位时，Codex 会因上游不可达报错。
+
+## 开机自启动
+
+代理是**用户会话内**被 Codex 调用的回环服务，所以三平台都选「随用户登录启动、跑在用户上下文」的方式
+（而不是系统级服务——系统服务跑在无用户环境的 session 里，够不到用户 profile 下的 uv 可执行文件与代理设置）。
+先用 `which codex-516-guard`（Unix/macOS）或 `where.exe codex-516-guard`（Windows）拿到绝对路径备用。
+
+### Linux / WSL — systemd user unit
+
+见 `systemd/codex-516-guard.service.example`：
+
+```bash
+cp systemd/codex-516-guard.service.example ~/.config/systemd/user/codex-516-guard.service
+systemctl --user daemon-reload && systemctl --user enable --now codex-516-guard
+```
+
+### macOS — launchd LaunchAgent
+
+macOS 用 launchd 管理后台任务。放在 `~/Library/LaunchAgents/` 的是 **LaunchAgent**，随**用户登录**启动、
+跑在用户 GUI session 里（对回环代理正确的选择）；`/Library/LaunchDaemons/` 里的 LaunchDaemon 开机即起但无用户会话，本场景不适用。
+
+把可执行文件绝对路径填进下面的 plist，存为 `~/Library/LaunchAgents/com.dzshzx.codex-516-guard.plist`：
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>            <string>com.dzshzx.codex-516-guard</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/Users/YOU/.local/bin/codex-516-guard</string>
+    </array>
+    <key>RunAtLoad</key>        <true/>
+    <key>KeepAlive</key>        <true/>
+    <key>StandardOutPath</key>  <string>/tmp/codex-516-guard.log</string>
+    <key>StandardErrorPath</key><string>/tmp/codex-516-guard.log</string>
+</dict>
+</plist>
+```
+
+注意：launchd 不读 shell 配置，`ProgramArguments` 必须是**绝对路径**；崩溃后 `KeepAlive` 会重启（10 秒节流）。
+加载 / 停用（现代 `launchctl`，`load`/`unload` 已是 legacy）：
+
+```bash
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.dzshzx.codex-516-guard.plist
+launchctl enable   gui/$(id -u)/com.dzshzx.codex-516-guard
+launchctl kickstart -k gui/$(id -u)/com.dzshzx.codex-516-guard   # 立即（重）启动
+launchctl bootout  gui/$(id -u)/com.dzshzx.codex-516-guard        # 卸载
+```
+
+### Windows — 用「登录时触发」的计划任务（不是系统服务）
+
+用户常问能否做成 Windows **service**：可以，但原生 service 要求程序实现 SCM 控制协议，
+`sc.exe create` 直接指向普通控制台程序会在启动时被判定超时（错误 1053），必须套 WinSW / NSSM 之类 wrapper。
+即便套上，service 默认跑在 **session 0 + SYSTEM 账户**，没有你的用户环境、代理设置，也不便访问用户 profile 下 uv 装的可执行文件。
+
+因此本场景**推荐计划任务（onlogon）**：随你登录启动、带完整用户环境和 PATH，正好匹配「用户会话内被调用的回环代理」。
+用 `where.exe codex-516-guard` 拿到路径后（PowerShell）：
+
+```powershell
+$exe = (Get-Command codex-516-guard).Source
+schtasks /create /tn "codex-516-guard" /tr "`"$exe`"" /sc onlogon /rl limited /f
+schtasks /run /tn "codex-516-guard"      # 立即启动一次
+# 删除：schtasks /delete /tn "codex-516-guard" /f
+```
+
+如确实要开机即起（未登录也运行）的系统服务形态，用 [WinSW](https://github.com/winswhq/winsw)（MIT）
+把本 exe 包成服务；注意需让服务以你的用户账户运行，否则够不到用户 profile 下的安装。
+
+## 验证
+
+```bash
+curl -sS http://127.0.0.1:8787/healthz            # {"ok":true,...}
+journalctl --user -u codex-516-guard -f | grep -E 'round|done'   # Linux/WSL；mac 看 plist 日志文件
+```
+
+命中折叠时的日志（实测样例，连环双 516 被击破、答案正确）：
+
+```
+round 1: in=21550 out=664 reason=516 total=22214 | n=1 buffered=['function_call'] -> continue
+round 2: in=22078 out=652 reason=516 total=22730 | n=1 buffered=['function_call'] -> continue
+round 3: in=22606 out=566 reason=291 total=23172 | n=None buffered=[...] -> clean
+done: 3 round(s) | ... | status=completed stop=natural
+```
+
+## 开发
+
+```bash
+git clone https://github.com/dzshzx/codex-516-guard && cd codex-516-guard
+uv sync
+uv run python test_fold.py        # 折叠状态机自测，应输出 ALL PASS
+uv run codex-516-guard            # 本地跑
+```
+
+发布走 PyPI Trusted Publishing（`.github/workflows/release.yml`，OIDC，无 token）：推 `v*` tag 即自动构建上传。
+
+## 结构
+
+- `guard/fold.py` — 指纹检测 + 折叠状态机（传输无关；`test_fold.py` 覆盖丢弃/放行、重编号、双口径 usage）
+- `guard/server.py` — starlette 传输层：ws / SSE 下游、SSE 上游、zstd/gzip 请求解压、`/v1/*` 透传
+- `guard/cli.py` — CLI 入口（`codex-516-guard`；仅监听回环；auth passthrough，不存储任何凭据）
+
+## 安全与免责
+
+- 代理只做 auth **passthrough**：转发 Codex 发来的 Authorization 头，不读取、不落盘任何凭据。
+- 仅监听回环地址；不要暴露到非回环接口。
+- 非官方项目，依赖上游未公开的行为（截断指纹、ws 帧格式），OpenAI 侧变更可能使其失效；使用风险自负。
+- 续写会产生额外的真实 token 消耗（见 `metadata.proxy_billed_usage`），guard 以 n 窗口 + 3 轮上限约束。
+
+## License
+
+MIT（见 LICENSE；机制思路 credit neteroster/CodexCont）。

codex_516_guard-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+guard/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+guard/cli.py,sha256=QMc1IOXV44rtoCcqPZ-GbwlGEATdqBNOFkHhU5s3zjI,1517
+guard/fold.py,sha256=tkUn0rwHtzbYT4WmHbrpkotIyFuMWxHQJGPoefVk55E,14471
+guard/server.py,sha256=9QppzZLpoNiAK-sEzwwuUKtAasiwQbp_Qzwxfy4cVP8,9103
+codex_516_guard-0.1.0.dist-info/METADATA,sha256=TBLZ8siLW7vp6P8RbiRdY6QnD5AgkGd9kK3IoEZZSu8,10639
+codex_516_guard-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+codex_516_guard-0.1.0.dist-info/entry_points.txt,sha256=k3OUjGaVDXtw83goZUWH_9PdFS42H9N1y6GCIpbBHf8,51
+codex_516_guard-0.1.0.dist-info/licenses/LICENSE,sha256=xUs31HROJwQ3ywBsM36wSEgCHZbFGQLJXm0iiR06iJY,1258
+codex_516_guard-0.1.0.dist-info/RECORD,,

codex_516_guard-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

codex_516_guard-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+codex-516-guard = guard.cli:main

codex_516_guard-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 dzshzx
+
+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.
+
+---
+
+Mechanism inspiration: the 518n-2 truncation detection + fold-continuation
+approach originates from neteroster/CodexCont (MIT). This project is an
+independent, from-scratch implementation.

guard/cli.py

@@ -0,0 +1,39 @@
+"""codex-516-guard CLI entry point (installed via [project.scripts])."""
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+
+import uvicorn
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="codex-516-guard",
+        description=(
+            "Local Responses proxy for Codex CLI: detects the gpt-5.5 518n-2 "
+            "reasoning-truncation fingerprint, auto-continues thinking, and folds "
+            "all rounds into one response. Wire Codex to it with the top-level "
+            'config key: openai_base_url = "http://127.0.0.1:8787/v1"'
+        ),
+    )
+    parser.add_argument("--host", default="127.0.0.1",
+                        help="bind address (default: 127.0.0.1; keep it loopback)")
+    parser.add_argument("--port", type=int, default=8787, help="bind port (default: 8787)")
+    parser.add_argument("--upstream", default=None,
+                        help="upstream base URL (default: https://chatgpt.com/backend-api/codex)")
+    parser.add_argument("--log-level", default="info",
+                        choices=["critical", "error", "warning", "info", "debug"])
+    args = parser.parse_args()
+
+    if args.upstream:
+        os.environ["GUARD_UPSTREAM_BASE"] = args.upstream
+    logging.basicConfig(level=args.log_level.upper(),
+                        format="%(levelname)s:%(name)s:%(message)s")
+    uvicorn.run("guard.server:app", host=args.host, port=args.port,
+                log_level=args.log_level)
+
+
+if __name__ == "__main__":
+    main()

guard/fold.py

@@ -0,0 +1,361 @@
+"""518n-2 truncation detection + round folding for the Codex Responses event stream.
+
+gpt-5.5 reasoning gets cut at reasoning_tokens == 518*n - 2 (openai/codex#30364).
+When a round ends on that fingerprint we replay the conversation plus the round's
+reasoning items and a phase:"commentary" nudge, then fold every round into ONE
+downstream response: reasoning streams live, each round's tentative final output
+(message / tool calls) is buffered and only the clean round's output is flushed.
+
+Transport-agnostic: `fold()` consumes upstream events as dicts and yields
+downstream events as dicts; serialization (SSE / WebSocket) lives in server.py.
+
+Mechanism credit: neteroster/CodexCont (MIT). Implementation is original.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any, AsyncIterator, Awaitable, Callable
+
+log = logging.getLogger("guard.fold")
+
+STEP = 518
+MIN_N = 1          # continue only when truncation tier n >= MIN_N
+MAX_N = 6          # stop forcing once n > MAX_N (0 = no cap)
+MAX_CONTINUE = 3   # continuation rounds after round 1 (runaway guard)
+MARKER_TEXT = "Continue thinking..."
+ENC_INCLUDE = "reasoning.encrypted_content"
+
+TERMINAL_TYPES = ("response.completed", "response.failed", "response.incomplete")
+
+# An opener returns the upstream event iterator for one round's body.
+RoundOpener = Callable[[dict[str, Any]], Awaitable[AsyncIterator[dict[str, Any]]]]
+
+
+class RoundOpenError(Exception):
+    """Continuation round could not be opened (upstream HTTP >= 400)."""
+
+    def __init__(self, status: int, detail: str):
+        super().__init__(f"upstream {status}: {detail[:200]}")
+        self.status = status
+
+
+DONE = object()  # sentinel an opener may yield to signal upstream sent [DONE]
+
+
+# --- fingerprint -------------------------------------------------------------
+
+
+def reasoning_tokens(usage: dict[str, Any] | None) -> int | None:
+    val = ((usage or {}).get("output_tokens_details") or {}).get("reasoning_tokens")
+    return int(val) if val is not None else None
+
+
+def tier_n(tokens: int | None) -> int | None:
+    """n for reasoning_tokens == STEP*n - 2 (516, 1034, ...), else None."""
+    if tokens is None or tokens < STEP - 2 or (tokens + 2) % STEP != 0:
+        return None
+    return (tokens + 2) // STEP
+
+
+def in_continue_window(n: int | None) -> bool:
+    return n is not None and n >= MIN_N and (MAX_N == 0 or n <= MAX_N)
+
+
+# --- continuation payload ----------------------------------------------------
+
+
+def commentary_nudge() -> dict[str, Any]:
+    """phase:"commentary" assistant message that provokes the model to resume
+    reasoning when replayed together with the encrypted reasoning items."""
+    return {
+        "type": "message",
+        "role": "assistant",
+        "content": [{"type": "output_text", "text": MARKER_TEXT}],
+        "phase": "commentary",
+    }
+
+
+def next_round_body(base_body: dict[str, Any], input_items: list[Any]) -> dict[str, Any]:
+    """The agent's request re-shaped for a continuation round: explicit input,
+    always streamed, encrypted reasoning included, no previous_response_id
+    (state is carried in the replayed items)."""
+    body = dict(base_body)
+    body["stream"] = True
+    body["input"] = input_items
+    include = [str(x) for x in (base_body.get("include") or [])]
+    if ENC_INCLUDE not in include:
+        include.append(ENC_INCLUDE)
+    body["include"] = include
+    body.pop("previous_response_id", None)
+    return body
+
+
+# --- usage accounting --------------------------------------------------------
+
+
+def _sum_usage(acc: dict[str, Any], usage: dict[str, Any] | None) -> None:
+    if not usage:
+        return
+    for key in ("input_tokens", "output_tokens", "total_tokens"):
+        if usage.get(key) is not None:
+            acc[key] = acc.get(key, 0) + int(usage[key])
+    cached = (usage.get("input_tokens_details") or {}).get("cached_tokens")
+    if cached is not None:
+        acc.setdefault("input_tokens_details", {})
+        acc["input_tokens_details"]["cached_tokens"] = (
+            acc["input_tokens_details"].get("cached_tokens", 0) + int(cached)
+        )
+    rt = reasoning_tokens(usage)
+    if rt is not None:
+        acc.setdefault("output_tokens_details", {})
+        acc["output_tokens_details"]["reasoning_tokens"] = (
+            acc["output_tokens_details"].get("reasoning_tokens", 0) + rt
+        )
+
+
+def agent_usage(
+    first: dict[str, Any] | None,
+    summed: dict[str, Any],
+    final_round: dict[str, Any] | None,
+    flushed_final: bool,
+) -> dict[str, Any]:
+    """Usage as if the fold were one response. input/cached come from round 1
+    (summing hidden rounds would fake a blown context window); reasoning is
+    summed because every round's reasoning reached the agent; output adds only
+    the flushed final round's non-reasoning part."""
+    first = first or {}
+    in_tok = first.get("input_tokens") or 0
+    cached = (first.get("input_tokens_details") or {}).get("cached_tokens")
+    reason = (summed.get("output_tokens_details") or {}).get("reasoning_tokens") or 0
+    final_part = 0
+    if flushed_final and final_round:
+        out = final_round.get("output_tokens") or 0
+        final_part = max(0, out - (reasoning_tokens(final_round) or 0))
+    usage: dict[str, Any] = {
+        "input_tokens": in_tok,
+        "output_tokens": reason + final_part,
+        "total_tokens": in_tok + reason + final_part,
+        "output_tokens_details": {"reasoning_tokens": reason},
+    }
+    if cached is not None:
+        usage["input_tokens_details"] = {"cached_tokens": cached}
+    return usage
+
+
+def _fmt(usage: dict[str, Any] | None) -> str:
+    u = usage or {}
+    return (
+        f"in={u.get('input_tokens')} out={u.get('output_tokens')} "
+        f"reason={reasoning_tokens(u)} total={u.get('total_tokens')}"
+    )
+
+
+# --- terminal reconstruction ---------------------------------------------------
+
+
+def _terminal_event(
+    upstream_terminal: dict[str, Any] | None,
+    base_response: dict[str, Any] | None,
+    output: list[dict[str, Any]],
+    usage: dict[str, Any],
+    rounds: list[dict[str, Any]],
+    billed: dict[str, Any],
+    stopped_reason: str | None,
+    *,
+    incomplete_reason: str | None = None,
+) -> dict[str, Any]:
+    """Downstream terminal: round-1 response identity, upstream status (or a
+    synthetic incomplete), our reconstructed output + single-response usage,
+    true billed cost and per-round breakdown in metadata."""
+    tresp = (upstream_terminal or {}).get("response") or {}
+    resp = dict(base_response or tresp)
+    resp["output"] = output
+    resp["usage"] = usage
+    metadata = dict(resp.get("metadata") or {})
+    metadata["proxy_rounds"] = rounds
+    metadata["proxy_billed_usage"] = billed
+    if stopped_reason:
+        metadata["proxy_stopped_reason"] = stopped_reason
+    resp["metadata"] = metadata
+    if incomplete_reason is not None:
+        resp["status"] = "incomplete"
+        resp["incomplete_details"] = {"reason": incomplete_reason}
+        return {"type": "response.incomplete", "response": resp}
+    resp["status"] = tresp.get("status", "completed")
+    if "incomplete_details" in tresp:
+        resp["incomplete_details"] = tresp["incomplete_details"]
+    return {"type": (upstream_terminal or {}).get("type", "response.completed"), "response": resp}
+
+
+# --- the fold ----------------------------------------------------------------
+
+
+async def fold(
+    base_body: dict[str, Any],
+    open_round: RoundOpener,
+) -> AsyncIterator[dict[str, Any] | object]:
+    """Yield downstream events (dicts, plus the DONE sentinel when upstream sent
+    one). Every yielded event gets a proxy-owned sequence_number; output_index
+    is renumbered into one downstream space across rounds."""
+    orig_input = list(base_body.get("input") or [])
+    seq = 0
+    ds_oi = 0
+    base_response: dict[str, Any] | None = None
+    saw_done = False
+    final_output: list[dict[str, Any]] = []
+    replay_tail: list[Any] = []
+    summed_usage: dict[str, Any] = {}
+    first_usage: dict[str, Any] | None = None
+    rounds_info: list[dict[str, Any]] = []
+
+    def stamp(ev: dict[str, Any]) -> dict[str, Any]:
+        nonlocal seq
+        ev["sequence_number"] = seq
+        seq += 1
+        return ev
+
+    round_no = 0
+    events = await open_round(next_round_body(base_body, orig_input))
+
+    while True:
+        round_no += 1
+        oi_to_ds: dict[Any, int] = {}
+        kind: dict[Any, str] = {}
+        buffered: list[dict[str, Any]] = []  # {oi, item, events}
+        round_reasoning: list[dict[str, Any]] = []
+        terminal: dict[str, Any] | None = None
+        usage: dict[str, Any] | None = None
+
+        try:
+            async for ev in events:
+                if ev is DONE:
+                    saw_done = True
+                    continue
+                etype = ev.get("type", "")
+
+                if etype in ("response.created", "response.in_progress"):
+                    if round_no == 1:
+                        if etype == "response.created":
+                            base_response = ev.get("response") or {}
+                        yield stamp(ev)
+                    continue
+                if etype in TERMINAL_TYPES:
+                    terminal = ev
+                    usage = (ev.get("response") or {}).get("usage")
+                    break
+
+                oi = ev.get("output_index")
+                if etype == "response.output_item.added":
+                    item = ev.get("item") or {}
+                    if item.get("type") == "reasoning":
+                        kind[oi] = "reasoning"
+                        oi_to_ds[oi] = ds_oi
+                        ev["output_index"] = ds_oi
+                        ds_oi += 1
+                        yield stamp(ev)
+                    else:
+                        kind[oi] = "buffered"
+                        buffered.append({"oi": oi, "item": item, "events": [ev]})
+                    continue
+
+                k = kind.get(oi)
+                if k == "reasoning":
+                    if oi in oi_to_ds:
+                        ev["output_index"] = oi_to_ds[oi]
+                    if etype == "response.output_item.done":
+                        item = ev.get("item") or {}
+                        round_reasoning.append(item)
+                        final_output.append(item)
+                    yield stamp(ev)
+                elif k == "buffered":
+                    entry = next(e for e in buffered if e["oi"] == oi)
+                    entry["events"].append(ev)
+                    if etype == "response.output_item.done":
+                        entry["item"] = ev.get("item") or entry["item"]
+                else:
+                    yield stamp(ev)  # unknown scope: forward best-effort
+        except RoundOpenError:
+            raise  # only raised before any event; handled by caller for round 1
+        except Exception as exc:  # upstream died mid-stream
+            log.warning("round %d: upstream error mid-stream: %r", round_no, exc)
+            _sum_usage(summed_usage, usage)
+            yield stamp(_terminal_event(
+                None, base_response, final_output,
+                agent_usage(first_usage, summed_usage, usage, flushed_final=False),
+                rounds_info, summed_usage, "upstream_error",
+                incomplete_reason="upstream_error"))
+            return
+
+        # ---- round ended: decide continue / stop ----------------------------
+        _sum_usage(summed_usage, usage)
+        if round_no == 1:
+            first_usage = usage
+        rt = reasoning_tokens(usage)
+        n = tier_n(rt)
+        rounds_info.append({"round": round_no, "reasoning_tokens": rt, "n": n})
+        has_enc = bool(round_reasoning and round_reasoning[-1].get("encrypted_content"))
+
+        do_continue = (
+            terminal is not None
+            and in_continue_window(n)
+            and has_enc
+            and round_no <= MAX_CONTINUE
+        )
+        stopped_reason = None
+        if not do_continue and n is not None:
+            stopped_reason = (
+                "no_encrypted_content" if not has_enc
+                else "max_continue" if round_no > MAX_CONTINUE
+                else "tier_out_of_window"
+            )
+
+        log.info(
+            "round %d: %s | n=%s buffered=%s -> %s",
+            round_no, _fmt(usage), n,
+            [e["item"].get("type") for e in buffered],
+            "continue" if do_continue else
+            "upstream_eof" if terminal is None else stopped_reason or "clean",
+        )
+
+        if do_continue:
+            replay_tail.extend([*round_reasoning, commentary_nudge()])
+            try:
+                events = await open_round(next_round_body(base_body, orig_input + replay_tail))
+            except RoundOpenError as exc:
+                log.warning("continuation round %d failed to open: %s", round_no + 1, exc)
+                yield stamp(_terminal_event(
+                    None, base_response, final_output,
+                    agent_usage(first_usage, summed_usage, usage, flushed_final=False),
+                    rounds_info, summed_usage, "upstream_error",
+                    incomplete_reason="upstream_error"))
+                return
+            continue
+
+        if terminal is None:  # EOF with no terminal: tentative output is NOT an answer
+            log.warning("round %d: upstream EOF with no terminal event", round_no)
+            yield stamp(_terminal_event(
+                None, base_response, final_output,
+                agent_usage(first_usage, summed_usage, usage, flushed_final=False),
+                rounds_info, summed_usage, "upstream_eof",
+                incomplete_reason="upstream_eof"))
+            return
+
+        # Clean stop: flush this round's buffered output as the real answer.
+        for entry in buffered:
+            for ev in entry["events"]:
+                if "output_index" in ev:
+                    ev["output_index"] = ds_oi
+                yield stamp(ev)
+            ds_oi += 1
+            final_output.append(entry["item"])
+
+        status = (terminal.get("response") or {}).get("status", "completed")
+        log.info("done: %d round(s) | %s | status=%s stop=%s",
+                 round_no, _fmt(summed_usage), status, stopped_reason or "natural")
+        yield stamp(_terminal_event(
+            terminal, base_response, final_output,
+            agent_usage(first_usage, summed_usage, usage, flushed_final=True),
+            rounds_info, summed_usage, stopped_reason))
+        if saw_done:
+            yield DONE
+        return

guard/server.py

@@ -0,0 +1,248 @@
+"""codex-516-guard transport layer.
+
+Downstream (Codex, wired via top-level `openai_base_url`):
+  * WebSocket /v1/responses  — Codex's preferred transport (openai-beta
+    responses_websockets): client sends {"type":"response.create", ...body...}
+    frames, we answer with response.* event frames; the connection is reused
+    for sequential requests (prewarm + turns).
+  * POST /v1/responses       — SSE fallback; request body may be zstd/gzip
+    compressed (built-in provider sends zstd when request compression is on).
+  * anything else under /v1/ — transparent passthrough to the upstream base
+    (Codex refreshes its model catalog via GET /v1/models).
+
+Upstream is always the SSE POST endpoint; the fold state machine (fold.py) is
+transport-agnostic.
+"""
+from __future__ import annotations
+
+import gzip
+import json
+import logging
+import os
+import zlib
+from typing import Any, AsyncIterator
+
+import httpx
+import zstandard
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response, StreamingResponse
+from starlette.routing import Route, WebSocketRoute
+from starlette.websockets import WebSocket, WebSocketDisconnect
+
+from .fold import DONE, RoundOpenError, fold
+
+log = logging.getLogger("guard.server")
+
+UPSTREAM_BASE = os.environ.get(
+    "GUARD_UPSTREAM_BASE", "https://chatgpt.com/backend-api/codex"
+).rstrip("/")
+RESPONSES_URL = UPSTREAM_BASE + "/responses"
+
+# hop-by-hop / transport-specific headers never forwarded upstream
+_DROP_HEADERS = {
+    "host", "connection", "upgrade", "keep-alive", "te", "trailer",
+    "transfer-encoding", "proxy-authorization", "proxy-connection",
+    "content-length", "content-encoding", "accept-encoding",
+    "sec-websocket-key", "sec-websocket-version", "sec-websocket-extensions",
+    "sec-websocket-protocol",
+    "openai-beta",  # advertises the ws protocol; upstream round is plain SSE
+}
+
+
+def upstream_headers(raw: Any) -> dict[str, str]:
+    out = {}
+    for key, value in raw:
+        k = key.decode() if isinstance(key, bytes) else key
+        if k.lower() in _DROP_HEADERS:
+            continue
+        out[k] = value.decode() if isinstance(value, bytes) else value
+    out["accept"] = "text/event-stream"
+    return out
+
+
+def decompress_body(data: bytes, encoding: str | None) -> bytes:
+    enc = (encoding or "").lower().strip()
+    if not enc or enc == "identity":
+        return data
+    if enc == "zstd":
+        return zstandard.ZstdDecompressor().decompressobj().decompress(data)
+    if enc == "gzip":
+        return gzip.decompress(data)
+    if enc == "deflate":
+        return zlib.decompress(data)
+    raise ValueError(f"unsupported content-encoding: {enc}")
+
+
+# --- upstream SSE rounds ------------------------------------------------------
+
+
+def parse_sse(text_chunks: AsyncIterator[str]) -> AsyncIterator[dict | object]:
+    """Incremental SSE parser: yields event dicts (from data: lines) and the
+    DONE sentinel for `data: [DONE]`."""
+
+    async def gen():
+        buf = ""
+        async for chunk in text_chunks:
+            buf += chunk
+            while "\n\n" in buf:
+                block, buf = buf.split("\n\n", 1)
+                data_lines = [
+                    line[5:].lstrip()
+                    for line in block.splitlines()
+                    if line.startswith("data:")
+                ]
+                if not data_lines:
+                    continue
+                data = "\n".join(data_lines)
+                if data == "[DONE]":
+                    yield DONE
+                    continue
+                try:
+                    yield json.loads(data)
+                except json.JSONDecodeError:
+                    log.warning("unparseable SSE data (len=%d), dropped", len(data))
+
+    return gen()
+
+
+class UpstreamRounds:
+    """RoundOpener bound to one downstream request's headers; closes the
+    previous round's response before opening the next."""
+
+    def __init__(self, client: httpx.AsyncClient, headers: dict[str, str]):
+        self.client = client
+        self.headers = headers
+        self._resp: httpx.Response | None = None
+
+    async def open(self, body: dict[str, Any]) -> AsyncIterator[dict | object]:
+        await self.aclose()
+        req = self.client.build_request(
+            "POST", RESPONSES_URL,
+            content=json.dumps(body, ensure_ascii=False).encode(),
+            headers={**self.headers, "content-type": "application/json"},
+            timeout=httpx.Timeout(connect=30, read=600, write=60, pool=30),
+        )
+        resp = await self.client.send(req, stream=True)
+        if resp.status_code >= 400:
+            detail = (await resp.aread()).decode(errors="replace")
+            await resp.aclose()
+            raise RoundOpenError(resp.status_code, detail)
+        self._resp = resp
+        return parse_sse(resp.aiter_text())
+
+    async def aclose(self) -> None:
+        if self._resp is not None:
+            try:
+                await self._resp.aclose()
+            except Exception:
+                pass
+            self._resp = None
+
+
+# --- downstream endpoints -----------------------------------------------------
+
+
+def sse_bytes(ev: dict | object) -> bytes:
+    if ev is DONE:
+        return b"data: [DONE]\n\n"
+    etype = ev.get("type", "message")  # type: ignore[union-attr]
+    return f"event: {etype}\ndata: {json.dumps(ev, ensure_ascii=False)}\n\n".encode()
+
+
+async def responses_post(request: Request) -> Response:
+    raw = await request.body()
+    try:
+        raw = decompress_body(raw, request.headers.get("content-encoding"))
+        body = json.loads(raw)
+    except (ValueError, json.JSONDecodeError) as exc:
+        return JSONResponse({"error": f"bad request body: {exc}"}, status_code=400)
+
+    rounds = UpstreamRounds(request.app.state.client, upstream_headers(request.headers.raw))
+
+    async def stream() -> AsyncIterator[bytes]:
+        try:
+            async for ev in fold(body, rounds.open):
+                yield sse_bytes(ev)
+        except RoundOpenError as exc:  # round 1 rejected: surface upstream error
+            yield sse_bytes({
+                "type": "response.failed",
+                "response": {"status": "failed",
+                             "error": {"message": str(exc), "code": exc.status}},
+            })
+        finally:
+            await rounds.aclose()
+
+    return StreamingResponse(stream(), media_type="text/event-stream")
+
+
+async def responses_ws(ws: WebSocket) -> None:
+    await ws.accept()
+    headers = upstream_headers(ws.headers.raw)
+    rounds = UpstreamRounds(ws.app.state.client, headers)
+    try:
+        while True:
+            try:
+                envelope = json.loads(await ws.receive_text())
+            except (WebSocketDisconnect, json.JSONDecodeError):
+                return
+            if envelope.get("type") != "response.create":
+                log.info("ws: ignoring frame type %s", envelope.get("type"))
+                continue
+            body = {k: v for k, v in envelope.items() if k != "type"}
+            try:
+                async for ev in fold(body, rounds.open):
+                    if ev is DONE:
+                        continue
+                    await ws.send_text(json.dumps(ev, ensure_ascii=False))
+            except RoundOpenError as exc:
+                await ws.send_text(json.dumps({
+                    "type": "response.failed",
+                    "response": {"status": "failed",
+                                 "error": {"message": str(exc), "code": exc.status}},
+                }))
+    except WebSocketDisconnect:
+        pass
+    finally:
+        await rounds.aclose()
+
+
+async def passthrough(request: Request) -> Response:
+    """Transparent proxy for every other /v1/* call (e.g. GET /v1/models)."""
+    suffix = request.path_params["path"]
+    url = f"{UPSTREAM_BASE}/{suffix}"
+    if request.url.query:
+        url += "?" + request.url.query
+    content = await request.body()
+    if content:
+        content = decompress_body(content, request.headers.get("content-encoding"))
+    headers = upstream_headers(request.headers.raw)
+    headers.pop("accept", None)
+    upstream = await request.app.state.client.request(
+        request.method, url, content=content or None, headers=headers,
+        timeout=httpx.Timeout(60),
+    )
+    drop = {"content-encoding", "transfer-encoding", "connection", "content-length"}
+    return Response(
+        upstream.content, status_code=upstream.status_code,
+        headers={k: v for k, v in upstream.headers.items() if k.lower() not in drop},
+    )
+
+
+async def health(_: Request) -> JSONResponse:
+    return JSONResponse({"ok": True, "upstream": UPSTREAM_BASE})
+
+
+def build_app() -> Starlette:
+    app = Starlette(routes=[
+        Route("/healthz", health),
+        Route("/v1/responses", responses_post, methods=["POST"]),
+        WebSocketRoute("/v1/responses", responses_ws),
+        Route("/v1/{path:path}", passthrough,
+              methods=["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD"]),
+    ])
+    app.state.client = httpx.AsyncClient(trust_env=True, http2=False)
+    return app
+
+
+app = build_app()