From 4e8fd5abbbc9c8f87a63736b89a67f609b1d75fa Mon Sep 17 00:00:00 2001 From: Diao Shengjia <104132148+GoDiao@users.noreply.github.com> Date: Tue, 17 Nov 2026 21:59:26 +0800 Subject: [PATCH 1/4] docs(harness): compare the agent runtime with Codex CLI and ZCode --- docs/README.md | 1 + docs/features/harness/README.md | 129 ++++++ .../harness/comparison/loop-execution.md | 240 +++++++++++ .../harness/comparison/model-adaptation.md | 203 +++++++++ docs/features/harness/comparison/prompt.md | 403 ++++++++++++++++++ .../harness/comparison/request-cache.md | 253 +++++++++++ docs/features/harness/comparison/tools.md | 314 ++++++++++++++ 7 files changed, 1543 insertions(+) create mode 100644 docs/features/harness/README.md create mode 100644 docs/features/harness/comparison/loop-execution.md create mode 100644 docs/features/harness/comparison/model-adaptation.md create mode 100644 docs/features/harness/comparison/prompt.md create mode 100644 docs/features/harness/comparison/request-cache.md create mode 100644 docs/features/harness/comparison/tools.md diff --git a/docs/README.md b/docs/README.md index 7925a999..3ab45922 100644 --- a/docs/README.md +++ b/docs/README.md @@ -12,6 +12,7 @@ - [agent-browser-control](features/agent-browser-control/tech-design.md): the agent controls the built-in browser. - [artifacts](features/artifacts/tech-design.md): Artifacts and Design mode. - [computer-use](features/computer-use/tech-design.md): Computer Use through cua-driver, with its [decision records](features/computer-use/adr.md). + - [harness](features/harness/README.md): comparison of the agent runtime with Codex CLI and ZCode on third-party models, and the tuning plan (research done, plan not decided). - [kanban](features/kanban/README.md): a persistent project board shared by people and agent sessions (first version implemented on `feat/kanban`). - [performance](features/performance/optimization-report.md): performance audit report. - [session-links](features/session-links/tech-design.md): sessions that start other sessions and message each other. diff --git a/docs/features/harness/README.md b/docs/features/harness/README.md new file mode 100644 index 00000000..27ae8a4d --- /dev/null +++ b/docs/features/harness/README.md @@ -0,0 +1,129 @@ +# Harness 调整 + +状态:调研完成,改造方案未定。本文是总览;五个维度的详细对比在 [comparison/](comparison) 下。 + +## 背景 + +DreamCoder 的 CLI 派生自 Claude Code 2.1.92(`src/constants/claudeCodeCompatibility.ts:7`)。用户大多接第三方模型(GLM、DeepSeek、Kimi 等),请求经本地代理(`src/server/proxy`)从 Anthropic Messages 格式转成 OpenAI 格式。 + +[FrontierHarness Eval](https://frontierharness.org/live/)(2026-11)用 62 个终端任务、22 个 harness、5 个开放权重模型(经 Baseten 的 OpenAI 兼容端点)做了对比。结果: + +- 通过率在 50.6% 到 61.9% 之间,两两差距大多在 95% 置信区间内,排名参考价值有限。 +- 成本和耗时差距大。Claude Code(2.1.308)每任务约 421 万输入 token、7.1 万输出 token、41 分钟;Codex CLI 约 296 万、3.6 万、27 分钟。 +- 按通过率和成本,帕累托前沿是 Codex CLI、Pi、ZCode。Codex 和 ZCode 在 5 个模型上都稳定在前 4 名。 + +所以本次对比选了 Codex CLI 和 ZCode,目标是找出 DreamCoder 在非 Claude 模型上多花 token 和轮数的原因。 + +## 对比的场景 + +一次 headless 编码任务,模型是经 OpenAI 兼容端点接入的第三方模型。 + +- Codex CLI:`codex exec`,自定义 `model_providers`,模型不在内置目录里(走回退元数据)。注意这个版本已删除 chat-completions 协议,只能接 `/v1/responses` 端点。 +- ZCode:CLI `--prompt`,`openai-chat-completions` 协议。 +- DreamCoder:服务器以 `--print` 启动 CLI,`ANTHROPIC_BASE_URL` 指向本地代理,上游格式 `openai_chat`;`USER_TYPE` 不是 `ant`,构建期 `feature()` 全部为 false,GrowthBook 关闭。 + +全部是静态读源码,没有运行任何项目。字符数是从源码字符串按场景分支拼出后计数的;标「推断」的是没有直接测到的结论。 + +参考代码是本地浅克隆,放在 `refs/coding-agents/`(不进 git)。报告里的路径前缀: + +| 前缀 | 仓库与版本 | 相对目录 | +|---|---|---| +| `codex:` | [openai/codex](https://github.com/openai/codex) 标签 `rust-v0.164.0`(与 benchmark 同版本) | `codex-rs/` | +| `zcode:` | [zai-org/ZCode](https://github.com/zai-org/ZCode) 提交 `fec97590`,CLI 0.17.1(benchmark 用 0.17.0) | `apps/zcode-cli/packages/` | +| 无前缀 | DreamCoder,`main` 上的 `75d9b3bf` | 仓库根 | + +## 总表 + +| | Codex | ZCode | DreamCoder | +|---|---|---|---| +| 工具数 | 12,另加托管搜索 | 24 | 34 | +| 工具描述 | 约 7.4K 字符 | 21.5K | 63.7K | +| 工具定义(含 schema) | 12–15K | 28–31K | 82–86K | +| 系统提示词(首个请求) | 17.7K | 6.5K 起 | 26.5K,其中记忆说明 12.5K | +| 每个请求的固定部分 | 约 4.6 万字符 | 约 2.7 万 | 约 12 万(约 3 万 token) | +| 前缀缓存 | 前缀逐请求不变,带 `prompt_cache_key` | 前缀不变,带会话 id | system 第 79 个字符起每个请求都变 | +| 推理强度传到上游 | 传 | 按模型映射 | 不传 | +| 输出上限传到上游 | 不发 | 发 | CLI 发,代理丢弃 | +| 编辑匹配不上时 | 4 遍逐级放宽 | 7 种回退 | 只处理弯引号 | +| 读超大文件 | 用 shell 读 | 返回前一部分 | 报错 | +| 读 `AGENTS.md` | 读 | 读 | 不读 | +| 示例任务的模型往返(推断) | 约 4 次 | 5 次 | 5–7 次 | + +示例任务:找到函数 `foo` 的定义,改一行,跑测试文件。 + +## DreamCoder 的主要问题 + +### 1. 提供方的前缀缓存失效 + +- 代理给每个请求的 system 开头补一行计费标识(`src/server/proxy/handler.ts:64`,`src/server/proxy/claudeCodeAttribution.ts:29`),这一步不看模型名。 +- 发出前,这一行里的 `cch=00000` 被替换成整个请求体的哈希(`src/server/upstream/client.ts:211-224`,`src/utils/claudeCodeCch.ts:57-59`)。请求体每轮都不同,所以这一行每轮都变,位置在 system 的第 79–83 个字符。 +- 除这一行外,DreamCoder 的前缀本来是稳定的:system 各段会话内缓存,日期和 git 状态只算一次,工具按名字排序。 +- 代理还丢掉了 `cache_control`,也不发会话亲和信息。 +- 后果(推断,没有实测):固定部分约 3 万 token 加全部历史,每个请求都按全价计。详见 [request-cache.md](comparison/request-cache.md)。 + +### 2. 代理翻译丢信息 + +- 推理强度:CLI 对自定义提供方发 `thinking:{type:'adaptive'}`,代理只在带预算或类型为 `enabled` 时写 `reasoning_effort`(`src/server/proxy/transform/anthropicToOpenaiChat.ts:64-72`),桌面上选的 Effort 不起作用。 +- 输出上限:`max_tokens` 不转发,实际用上游默认值。 +- 错误:上游错误统一包成 `api_error`,`retry-after` 丢失;CLI 针对 Anthropic 的错误识别(上下文过长、过载)对翻译后的错误不命中。 +- 推理内容:只对 DeepSeek 一类上游写回历史里的 `reasoning_content`,Kimi、GLM 的会丢。 +- 图片:工具结果里的图片被换成 `[image omitted]`(`src/server/proxy/transform/toolArguments.ts:38`)。 +- 工具调用:chat 流里没有 id 的工具调用整个被丢掉。 + +详见 [model-adaptation.md](comparison/model-adaptation.md)。 + +### 3. 每个请求的固定部分太大 + +- Bash 描述 10,003 字符,其中 6,253 是 git 提交和 PR 流程。 +- 13 个产品工具(ShowUI、看板、会话、产物、设计)共 21,265 字符,每个请求都带。服务器无条件打开它们(`src/server/services/conversationService.ts:1052-1058`),大多没有标记可延迟。 +- ToolSearch 依赖 Anthropic 的 `defer_loading` 和 `tool_reference`,非 Anthropic 地址下关闭(`src/utils/toolSearch.ts:299-303`)。ZCode 的本地模式(ToolSearch 加固定的 DeferredToolCall)在任何 chat 端点都能用。 +- 记忆说明 12.5K,记忆目录为空时也发。通用行为条文 9.2K,ZCode 同类内容约 1.6K。 +- EnterPlanMode(4,022 字符)和 4 个 Task 工具要求模型主动使用。 + +详见 [tools.md](comparison/tools.md) 和 [prompt.md](comparison/prompt.md)。 + +### 4. 对非 Claude 模型发送 Claude 专属文字 + +- 身份前缀 "You are a Claude agent…";环境段列出 Claude 模型 ID、Claude Code 产品形态和 `/fast`。 +- Read 工具自称能看图和 PDF,但图片会被代理换成文字。 +- 每次 Read 后追加约 340 字符的恶意软件提醒,只有 `claude-opus-4-7` 豁免(`src/tools/FileReadTool/FileReadTool.ts:727-735`)。 +- 确定的 bug:模型名不在公开列表时,提交署名固定为 `Co-Authored-By: Claude Opus 4.7 `(`src/utils/attribution.ts:73-80`),会写进用户仓库。 + +详见 [prompt.md](comparison/prompt.md)。 + +### 5. 执行层 + +- 编辑只处理弯引号,缩进、行尾空白、行号前缀、转义的偏差都会直接失败。ZCode 有 7 种回退,Codex 有 4 遍逐级放宽。 +- Read 超过 25,000 token 直接报错,模型要多一轮按段重读;ZCode 返回前一部分。 +- 不读 `AGENTS.md`,`src` 里只有 `/init` 提到它。DreamCoder 自己的仓库就只有 `AGENTS.md`。 +- 外部构建里没有「完成前先验证」的条文。 +- 没有空响应重试和重复调用提醒(ZCode 有)。 +- 不在内置表里的模型(如 GLM-5.3、Kimi-K3),上下文窗口按 200K 计。 + +详见 [loop-execution.md](comparison/loop-execution.md)。 + +## 建议的顺序 + +1. 代理层:对非 Claude 模型去掉计费行;转发推理强度和输出上限;保留错误类型和 `retry-after`;通用回传推理内容。改之前和改之后各用测试 key 测一次缓存命中,作为基准。 +2. 去掉发给非 Claude 模型的 Claude 专属文字,修署名 bug;读 `AGENTS.md`。 +3. 缩小固定部分:产品工具按需发送(参照 ZCode 的本地延迟加载);git 流程从 Bash 描述移到 skill;缩短记忆说明。 +4. 执行层:编辑容错、Read 超限时返回前一部分、空响应重试。 +5. 建一组固定任务,量每个改动前后的 token、轮数和通过率。 + +## 待定 + +以下是产品决定,需要维护者确定: + +- Task 工具和计划模式对非 Claude 模型是否降级或改为按需。 +- 记忆说明保留多少。 +- 产品工具按什么条件发送(会话是否用到该功能,或一律延迟加载)。 + +## 详细报告 + +| 维度 | 文件 | 内容 | +|---|---|---| +| A | [tools.md](comparison/tools.md) | 工具清单和大小、能力对照、长描述的内容、产品工具、延迟加载机制、工具顺序 | +| B | [prompt.md](comparison/prompt.md) | 系统提示词逐段对比、话题覆盖、ZCode 相对 Claude Code 的删改、Claude 专属文字、记忆、动态上下文、中途提醒、子 agent 和压缩提示词 | +| C | [request-cache.md](comparison/request-cache.md) | 请求布局、逐轮变化、缓存控制、上下文增长、压缩、额外请求、每个请求的固定开销 | +| D | [model-adaptation.md](comparison/model-adaptation.md) | 到提供方的路径、代理逐字段翻译、推理强度、每个模型的参数来源、输出上限、对非原生模型的容错、错误和重试、辅助请求用的模型 | +| E | [loop-execution.md](comparison/loop-execution.md) | 循环结束条件、工具执行、文件编辑、读取和搜索、shell、子 agent、规划工具、示例任务推演 | diff --git a/docs/features/harness/comparison/loop-execution.md b/docs/features/harness/comparison/loop-execution.md new file mode 100644 index 00000000..dd229a2e --- /dev/null +++ b/docs/features/harness/comparison/loop-execution.md @@ -0,0 +1,240 @@ +# E 维度:Agent 循环与核心动作执行 + +场景:headless 运行,第三方模型经 OpenAI 兼容 chat-completions 接入(Codex:`codex exec` + 自定义 provider + 未知 slug;ZCode:`--prompt` + `openai-chat-completions`;DreamCoder:服务器启动的 `--print` CLI + 本地代理 `openai_chat`,`feature()` 全 false,GrowthBook 关闭)。 + +路径约定:`codex:` 相对 `refs/coding-agents/codex/codex-rs`;`zcode:` 相对 `refs/coding-agents/zcode/apps/zcode-cli/packages`;DreamCoder 相对仓库根。 + +关键结论做过二次核对(DreamCoder 截断续写文案 `src/query.ts:1211-1215`;ZCode 重复调用阈值 `zcode:core/src/runtime/helpers/model-anomaly.ts:23-60`;Codex 未知模型不声明 apply_patch `codex:core/src/tools/spec_plan.rs:1409` + `codex:models-manager/src/model_info.rs:124`),均与源码一致。 + +--- + +## 1. 结论 + +1. **编辑的容错差距最大。** 同样是字符串替换,ZCode 在精确匹配失败后依次尝试 7 种回退(引号、行号前缀、转义、`\u` 转义、逐行 trim、公共缩进、首尾锚定+相似度 0.8);DreamCoder 只有弯引号归一和一张「反净化」替换表,不处理空白、缩进、行号前缀、转义。Codex 用补丁格式,四遍逐行匹配(精确 → 忽略行尾空白 → 忽略两端空白 → Unicode 标点归一)。 +2. **DreamCoder 与 ZCode 都强制 read-before-edit 和过期检查,文案逐字相同;Codex 没有这两项前置条件。** 在「找到函数、改一行」这类任务里,DreamCoder/ZCode 至少多一次 Read 往返;Codex 可以用 `rg -n -C` 一次拿到上下文后直接打补丁。 +3. **Codex 在本场景的编辑入口很脆弱。** apply_patch 不作为工具声明,模型必须在 `exec_command` 里写恰好一条 `apply_patch <<'EOF' … EOF` 才会被拦截;回退 prompt 只有一行格式说明,而且示例是 exec_command 无法表达的 argv 数组形式;只给补丁正文时的报错又让模型「Rerun as ["apply_patch", ""]」。补丁语法本身没有在 prompt 中说明(推断:对非 OpenAI 模型是格式错误的主要来源)。另外,v0.164.0 已不支持 `wire_api = "chat"`,纯 chat-completions 端点无法直接接入(`codex:model-provider-info/src/lib.rs:102-135`)。 +4. **循环结束条件三家相同:响应里没有工具调用就结束。** 都没有默认的步数/轮数上限;都没有对「只有推理、没有文本」的专门处理。ZCode 额外有可疑空响应判定(无文本、无工具、零 usage → 可重试错误),DreamCoder 与 Codex 把空响应当作正常结束。 +5. **只有 ZCode 有重复调用防护**:同名同参连续 3 次插入提醒(只提醒不拦截,每回合最多 3 次)。DreamCoder 与 Codex 未找到任何重复调用检测。ZCode 还有「静默 5 次响应提醒向用户汇报」。 +6. **工具并行:Codex 和 ZCode 在流式过程中就开始执行,DreamCoder 在本场景下要等整个响应结束。** DreamCoder 的流式工具执行受 GrowthBook 门控,GrowthBook 关闭时为 false。Codex 对可并行工具不设数量上限;ZCode 与 DreamCoder 上限 10。 +7. **读取上限:DreamCoder 与 ZCode 常量相同(256KB、25,000 token、描述写 2000 行但代码不按行截断),但超 token 时行为不同**:ZCode 首次整文件读取返回部分视图,DreamCoder 直接报错,模型要再发一次带 offset/limit 的请求。DreamCoder 每次 Read 结果末尾还附约 330 字符的恶意软件提醒,另两家没有。 +8. **Shell 超时语义:Codex 不杀进程,10 秒后交回 session ID 由模型轮询;ZCode 与 DreamCoder 默认 120 秒,到时自动转后台并承诺完成后通知。** 输出上限:Codex 约 10,000 token/字节,ZCode 30KB 尾部预览,DreamCoder 30,000 字符。 +9. **规划工具:Codex 不注册 `update_plan` 但 prompt 仍描述它;ZCode 的 TodoWrite 描述只有 3 行、不鼓励主动使用;DreamCoder 在应用里启用 4 个 Task 工具(约 8K 字符描述),描述要求「3 步以上主动使用」、开始前标 in_progress、完成后立即标 completed。** 这是 DreamCoder 在普通小任务上额外工具调用和往返的主要来源(推断)。 +10. **子 agent:Codex 明文禁止未经要求就委派;ZCode 鼓励「需要跨多个文件阅读」时委派;DreamCoder 鼓励「超过 3 次查询」时用 Explore(模型为 provider 的 fastModel)。** DreamCoder 与 Codex 子 agent 都不能再嵌套(深度 1)。 + +--- + +## 2. 逐项对比 + +### 2.1 循环 + +| | Codex | ZCode | DreamCoder | +|---|---|---|---| +| 结束条件 | 无工具调用且无待处理输入 | 无可执行工具调用 | 流中未出现 tool_use | +| 步数/轮数上限 | 无(未找到) | 主循环无(未找到) | 无(`--max-turns` 服务器不传) | +| 输出截断(length) | 走流错误重试(未逐条核实) | 续写提示,最多 3 次 | 续写提示,最多 3 次 | +| 空响应 | 正常结束 | 零 usage 时报可重试错误 | 正常结束 | +| 只有推理 | 正常结束 | 正常结束(推断) | 正常结束 | +| 重复调用防护 | 无 | 连续 3 次同参提醒 | 无 | +| Stop hook / 完成校验 | Stop hook 可续跑;goal 需显式要求 | Stop hook 续跑 ≤3 次;target 模式需显式入口 | Stop hook 可续跑;无完成校验 | + +- Codex:`run_turn` 循环(`codex:core/src/session/turn.rs:460`),`needs_follow_up` 来自工具调用、`end_turn == Some(false)` 或待处理用户输入(`turn.rs:609, 3028-3030`);为 false 时跑 Stop hook(`turn.rs:725`),hook 要求续跑则追加 prompt 并继续(`turn.rs:742-759`),否则 break(`turn.rs:830`)。上下文超限时自动压缩后继续(`turn.rs:664-705`)。`ResponseIncomplete` 走 `handle_response_stream_error` 重试,次数 `stream_max_retries`(`turn.rs:1743, 1810-1835, 2850-2870`);各 incomplete 原因的处理未核实。goal 工具描述要求「do not infer goals from ordinary tasks」(`codex:ext/goal/src/spec.rs:~33`)。 +- ZCode:`runRegularTurnLoop`(`zcode:core/src/runtime/methods/turn-loop.ts:56-57`),无工具调用时 `finishModelStepWithoutToolCalls`(`turn-stop.ts:167`)先处理中途追加的用户消息,再跑 Stop hook,续跑上限 3(`runtime/methods/hooks.ts:14, 232-241`)。截断续写文案与 DreamCoder 逐字相同,3 次后抛 `The model's response exceeded the output token maximum.`(`runtime/methods/turn-output-token-continuation.ts:20-41, 175-178`)。可疑空响应:`Model returned no text, no tool calls, and no usage before completing the turn.`,标 retryable(`runtime/helpers/model-errors.ts:114-131`;`turn-model-step.ts:690-713`)。重复调用提醒:`You have called X with the same input 3 times in a row. Do not repeat the exact same tool call again ...`,只在连续次数恰好等于阈值时触发(`runtime/helpers/model-anomaly.ts:23-60, 98-105`;注入点 `turn-tool-warnings.ts:52-70`)。静默提醒:连续 5 次模型响应没有可见文本时插入「The user hasn't heard from you in a while ...」,每段最多 3 次(`runtime/helpers/runtime-reminders.ts:105-160`)。每次收集输入附件时追加 runtime context、ToolSearch、agent 清单、skills、runtime_mode、todo 提醒、token 预算、output_style 等(`turn-loop.ts:240-343`),字节数未测。 +- DreamCoder:`src/query.ts` 的 `while (true)`,退出信号是流中是否出现 tool_use(`src/query.ts:555-559, 835, 1050`)。默认无轮数上限:`maxTurns` 只来自隐藏选项 `--max-turns`(`src/main.tsx:969`),服务器不传(`src/server/services/conversationService.ts:142-156`;`src/query.ts:1680`)。截断:代理把 `finish_reason: length` 映射为 `max_tokens`(`src/server/proxy/transform/openaiChatToAnthropic.ts:74`)→ 合成 `max_output_tokens` 错误(`src/services/api/claude.ts:2316-2327`)→ 提升输出上限的分支依赖 GrowthBook,本场景不走(`src/query.ts:1183-1209`)→ 追加 meta 用户消息续写,最多 3 次(`src/query.ts:1165, 1211-1240`)。空响应:代理对空 choice 造一个空文本 end_turn(`openaiChatToAnthropic.ts:93-104`),视为正常结束(`claude.ts:2390-2404`)。Stop hook:blockingError 时把 hook 输出作为 meta 消息追加并继续,`preventContinuation` 则结束(`src/query.ts:1266-1294`;`src/query/stopHooks.ts`)。 + +### 2.2 工具执行 + +| | Codex | ZCode | DreamCoder | +|---|---|---|---| +| 何时开始执行 | 每个调用在流中完成即派发 | 流中执行只读、并发安全、无需审批的工具;其余流结束后 | 流结束后(流式执行被 GrowthBook 门关闭) | +| 并发上限 | 可并行工具无上限(读写锁) | 10 | 10 | +| 可并行的工具 | exec_command、view_image;apply_patch 独占 | Read/Glob/Grep/TodoRead/Agent;Edit/Write/Bash 串行 | 相邻的「并发安全」调用成批;其余串行 | +| 结果顺序 | 流结束后按序收集 | 按 blockIndex 排序 | 按调用顺序 | +| 错误形态 | 纯文本,`success:false` | `…` | `…` + `is_error` | +| 未知工具 | `unsupported call: ` | 未细查 | `Error: No such tool available: X` | +| 需审批的调用(headless) | 策略 Never,直接拒绝 | deny broker 直接拒绝 | 应用里转发给桌面端等待 | +| 向用户提问 | 拒绝:`request_user_input is not supported in exec mode` | 拒绝:`No permission client configured for ` | 转发给桌面端等待 | + +- Codex:`handle_output_item_done` 构造 future,`tokio::spawn` 执行(`codex:core/src/stream_events_utils.rs:~345-372`;`codex:core/src/tools/parallel.rs:201`);读写锁分配(`parallel.rs:213-217`);`exec_command` 声明可并行(`codex:core/src/tools/handlers/unified_exec/exec_command.rs:135`),apply_patch handler 默认不可并行(`codex:tools/src/tool_executor.rs:122`)。错误输出(`parallel.rs:338-384`;`codex:core/src/tools/registry.rs:963-966`)。exec 审批策略固定 Never(`codex:exec/src/lib.rs:591`),`request_user_input` 与文件变更审批被拒(`exec/src/lib.rs:2122-2143`);需要提权时返回「approval policy is Never; reject command — you cannot ask for escalated permissions ...」(`exec_command.rs:~330`)。 +- ZCode:`ToolScheduler` 并发 10,判定规则(`zcode:core/src/tool/scheduler.ts:45, 90-185`);流中执行条件 `modelStreaming === "on"`(headless 为 on,`zcode:cli/src/prompt-command.ts:270`)且 `streamingToolExecution` 默认 `readOnly`(`runtime/methods/streaming-tool-coordinator.ts:383-406`);排序(`runtime/methods/turn-tools.ts:47-57`)。错误措辞与 DreamCoder 同一套(`tool/input-validation-model-content.ts:12-68`;`tool/executor/errors.ts:44-58`)。`zcode -p` 默认 yolo(`zcode:cli/src/run.ts:52`),但判为 ask 的调用经 deny broker 拒绝(`permission/broker.ts:22-37`;`permission/service.ts:121-150`;`prompt-command.ts:250-253`;`tool/executor/errors.ts:136-160`)。 +- DreamCoder:流式执行门 `tengu_streaming_tool_execution2`(`src/query/config.ts:33`),GrowthBook 无 clientKey 时关闭(`src/services/analytics/growthbook.ts:173, 422-427, 819-821`),所以由 `runTools` 在响应结束后执行(`src/query.ts:1368-1370`)。并发上限 `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` 默认 10(`src/services/tools/toolOrchestration.ts:8-112`)。错误类型(`src/services/tools/toolExecution.ts:402, 474-482, 671, 724`)。权限拒绝返回 is_error 的 tool_result(`toolExecution.ts:1030-1040`),文案见 `src/utils/messages.ts:217-241`。应用用 `--sdk-url` 强制 stdio 权限提示并转发服务器(`src/cli/print.ts:851-853, 4315-4317`);无人响应时是等待而不是自动拒绝(推断)。 + +### 2.3 编辑文件 + +| | Codex | ZCode | DreamCoder | +|---|---|---|---| +| 接口 | exec_command 里写 `apply_patch <<'EOF'` | Edit(file_path, old_string, new_string, replace_all) + Write | 同 ZCode | +| 描述长度 | prompt 一行 | Edit 约 380 字符 | Edit 约 1.2K 字符 | +| read-before-edit | 无 | 有 | 有 | +| 过期检查 | 无 | mtime 前进或大小变化 | mtime 前进且内容不同 | +| 匹配遍数 | 4 遍逐行 + 末尾空行回退 | 精确 + 7 回退 | 精确 + 弯引号;接收时反净化 | +| 歧义处理 | 不拒绝,取游标后第一个 | 拒绝 | 拒绝 | +| 失败提示是否带文件实际内容 | 否 | 否 | 否 | +| 成功返回 | 文件列表 A/M/D,约 100–200 字符 | 一句话 + 「不要读回」 | 一句话,约 60–100 字符 | +| 行尾 | 逐行保留 | 保留 | Edit 保留;Write 固定 LF | +| 格式化器 | 无 | 无 | 无 | + +**Codex** +- 入口:未知模型 `apply_patch_tool_type: None`,不注册 apply_patch(`codex:models-manager/src/model_info.rs:124`;`codex:core/src/tools/spec_plan.rs:1409`)。`exec_command` 执行前调用 `intercept_apply_patch`(`codex:core/src/tools/handlers/unified_exec/exec_command.rs:358-372`;`codex:core/src/tools/handlers/apply_patch.rs:435-475`)。识别只接受脚本中唯一顶层语句 `apply_patch <<'EOF' … EOF`,可带 `cd &&` 前缀(`codex:apply-patch/src/invocation.rs:274-300`)。exec_command 只有字符串参数 `cmd`(`codex:core/src/tools/handlers/shell_spec.rs:33-36`)。 +- prompt:回退 prompt 只有一行,示例为 argv 数组 `{"command":["apply_patch","*** Begin Patch..."]}`(`codex:models-manager/prompt.md:132`),全文只出现一次 `Begin Patch`,没有补丁语法说明。 +- 只给补丁正文时:`patch detected without explicit call to apply_patch. Rerun as ["apply_patch", ""]`(`codex:apply-patch/src/lib.rs:86-90`;`invocation.rs:146-157`)。写成 `apply_patch ''`(带引号参数)不会被拦截,会作为普通命令执行 PATH 中的 apply_patch 别名(`codex:arg0/src/lib.rs:138-145, 300-310`)(推断:能改文件,但绕过补丁事件与审批路径)。 +- 解析宽松,接受外层 heredoc 包裹(`codex:apply-patch/src/parser.rs:47-53, 225-290`)。 +- 匹配:每个 hunk 从上一个 hunk 结束处向后找(`codex:apply-patch/src/file_update.rs:95-150`)。`seek_sequence` 四遍:精确;`trim_end`;`trim`;trim 后把 Unicode 连字符、弯引号、各种空格归一为 ASCII(`codex:apply-patch/src/seek_sequence.rs:12-110`)。模式末尾空行找不到时去掉再找(`file_update.rs:107-123`)。`@@ ` 行先单独定位(`file_update.rs:69-82`)。 +- 失败:`apply_patch verification failed: Failed to find expected lines in :\n` 或 `Failed to find context '' in `(`apply_patch.rs:463-467`;`file_update.rs:80-82, 154-158`)。整份补丁先校验,失败不写任何文件。 +- 成功:`Success. Updated the following files:` + `A/M/D `(`codex:apply-patch/src/lib.rs:826-840`),外层套 exec 输出头(`codex:core/src/tools/context.rs:524-548`)。prompt 要求不要重读已改文件(`prompt.md:143`)。 +- 行尾按行保留(`codex:apply-patch/src/text_file.rs:14-46`;`file_update.rs:125-140`)。 + +**ZCode**(`zcode:core/src/tool/`) +- 校验顺序(`handlers/edit.ts:105-245`):old==new → 空路径 → 文件不存在(old_string 为空则创建;否则提示 cwd 并给同名不同扩展名或编辑距离 ≤3 的建议,`edit.ts:354-389`)→ >1GB → 统一行尾为 LF → old_string 空但文件非空 → .ipynb → 未读过/部分视图:`File has not been read yet. Read it first before writing to it.`;过期:`File has been modified since read, either by the user or by a linter. Read it again before attempting to write it.`(整毫秒 mtime 前进或大小变化;完整读过且内容相同则放行,`edit.ts:425-470`)→ 匹配。 +- 匹配(`tool/edit-matchers.ts:41-68`),精确后依次:quote_normalized;line_number_prefix_stripped(每行都带 `N: ` 或 `N\t` 才剥,`:253-263`);escape_normalized(`\n \t \r \" \' \` \\ \$`,new_string 同样反转义,`:75-80, 265-284`);unicode_escape_normalized;line_trimmed;indentation_flexible(≥2 行);block_anchor(≥3 行,首尾行 trim 相等、中间行平均相似度 ≥0.8,`:204-220, 323-340`)。replace_all 时跳过后三种宽松匹配(`:25-29, 62`)。第一个有候选的策略即被采用。 +- 歧义:同一策略的候选实际文本不唯一,或实际文本出现多次且未 replace_all,报 `Found N matches of the string to replace, but replace_all is false ...`(`edit.ts:216-231, 641-646`)。 +- 找不到:`String to replace not found in file.\nString: `(`edit.ts:210-214`),与 DreamCoder 逐字相同。 +- 宽松匹配命中后 new_string 原样写入,不按文件实际缩进调整(推断:模型 new_string 缩进错时写入的也是错的)。 +- 成功:`The file X has been updated successfully. (file state is current in your context — no need to Read it back)`(`edit.ts:53-77`);结果给模型的上限 100KB(`edit.ts:281-289`)。保留编码与行尾(`edit.ts:509-515`)。Write 描述约 230 字符,同样的未读/过期检查,保留原行尾(`handlers/write.ts:37-64, 109, 131`)。 + +**DreamCoder**(`src/tools/FileEditTool/`) +- 接收时(解析模型输出阶段,`src/utils/messages.ts:2798` → `src/utils/api.ts:622-645` → `utils.ts:581-662`):new_string 每行去尾部空白(.md/.mdx 除外);old_string 精确找不到时套用 18 项反净化表(``、``、`\n\nH:` 等,`utils.ts:531-550`),同样替换应用到 new_string。 +- validateInput 顺序(`FileEditTool.ts:138-345`):old==new → deny 规则 → >1GiB(`:85`)→ 读入并 CRLF→LF → 文件不存在(附 Did you mean)/ old_string 空但文件非空 → .ipynb → 未读过或部分视图(code 6)→ 过期(code 7,文案同 ZCode)→ 精确匹配,失败再弯引号归一(`utils.ts:73-96`)→ 找不到(code 8:`String to replace not found in file.\nString: `)→ 多处匹配(code 9)。 +- call 阶段再查一次过期,失败抛 `File has been unexpectedly modified. Read it again before attempting to write it.`(`FileEditTool.ts:445-470`;`constants.ts:10-11`)。new_string 为空且后接换行时连换行一起删(`utils.ts:218-229`)。保留编码(utf8/utf16le)与行尾(`src/utils/fileRead.ts:87-96`;`src/utils/file.ts:84-98`)。 +- 成功:`The file has been updated successfully.`(`FileEditTool.ts:555-575`)。没有「不要读回」提示。 +- Write:已存在文件要求读过且未改(`src/tools/FileWriteTool/FileWriteTool.ts:199-219`);content 每行去尾空白(非 md,`src/utils/api.ts:646-660`);固定写 LF(`FileWriteTool.ts:307`);返回 `File created successfully at: ` 或 `The file has been updated successfully.`(`:426, 432`)。 +- 读过的文件被外部修改后,下一次请求附 `edited_text_file` 附件(`src/utils/attachments.ts:862, 2047-2102`)。 + +**每种失败的额外模型往返(推断,按典型行为计)** + +| 失败 | Codex | ZCode | DreamCoder | +|---|---|---|---| +| 未读就编辑 | 不适用 | +2(Read,再 Edit) | +2 | +| 读后文件被改(过期) | 不适用 | +2 | +2 | +| old_string / 上下文不匹配(空白、缩进、行号前缀、转义造成) | 多数被 4 遍匹配吸收;否则 +1~2 | 多数被 7 回退吸收;否则 +1~2 | +1(凭记忆改)或 +2(重读再改) | +| 多处匹配 | 不报错(可能改错位置) | +1 | +1 | +| 调用形式错误(apply_patch 没写成 heredoc) | +1~2 | 不适用 | 不适用 | + +### 2.4 读取与搜索 + +| | Codex | ZCode | DreamCoder | +|---|---|---|---| +| 专用工具 | 无,用 shell | Read/Grep/Glob | Read/Grep/Glob | +| 行号格式 | 无 | `N\t内容` | `N\t内容` | +| 默认读取范围 | 由命令决定 | 整文件(描述写 2000 行) | 整文件(描述写 2000 行) | +| 字节上限 | 输出 10,000 字节/token | 256KB(未给 limit 时) | 256KB(未给 limit 时) | +| token 上限 | — | 25,000,首次整读超限给部分视图 | 25,000,超限报错 | +| 重复读未改文件 | 无去重 | 「Wasted call — file unchanged ...」 | 「File unchanged since last read ...」 | +| 每次结果附加文字 | 输出头 | 无 | 约 330 字符恶意软件提醒 | +| Grep 默认 | — | files_with_matches | files_with_matches,head_limit 250,2 万字符 | + +- Codex:读取靠 `cat`/`sed -n`/`rg`;exec 输出预算默认 10,000 token(`codex:core/src/unified_exec/mod.rs:74`),回退模型截断策略 10,000 字节(`codex:models-manager/src/model_info.rs:126`),截断时加 `Warning: truncated output (original token count: N)`(`codex:core/src/tools/context.rs:519-521`)。 +- ZCode:常量 256KB / 25,000 / 2,000(`zcode:contracts/src/tools/read.ts:15-17`);2,000 只用于描述和附件(`zcode:core/src/runtime/helpers/attachments.ts:307`;`zcode:core/src/tool/handlers/read.ts:72`)。超 token 的首次整读返回前若干行,提示放在批次后附件中(`zcode:core/src/tool/handlers/read-text.ts:150-200`);带 offset/limit 超限才报错。超 256KB 报错,文案与 DreamCoder 相同(`zcode:adapters/src/fs/text-range-reader.ts:41-43`)。去重文案(`read-text.ts:17-18`;`read.ts:207-210`)。描述写明「Do NOT re-read a file you just edited to verify」(`read.ts:78`)。Glob 100 条/100KB(`zcode:core/src/tool/handlers/glob.ts:20-21`);Grep 默认 files_with_matches(`grep.ts:29, 203`)。 +- DreamCoder:确认上限为 256KB(`src/utils/file.ts:48`;`src/utils/readFileInRange.ts:63, 96-101`,仅在未给 limit 时检查,`src/tools/FileReadTool/FileReadTool.ts:1017-1025`)与 25,000 token(`src/tools/FileReadTool/limits.ts` `DEFAULT_MAX_OUTPUT_TOKENS`;`FileReadTool.ts:176-183, 753-770`)。报错文案都要求「Use offset and limit parameters to read specific portions of the file, or search for specific content」,模型下一步是带 offset/limit 重读或改用 Grep,+1 往返。描述默认不提 256KB(`includeMaxSizeInPrompt` 来自 GrowthBook,`FileReadTool.ts:347-349`)。估算超过 6,250 token 时调用 count_tokens API;代理只接 `/proxy/v1/messages`(`src/server/proxy/handler.ts:11-17`),调用失败返回 null 后用估算值(`src/services/tokenEstimation.ts:192-198`)(推断:每次大文件读取多一次失败的本地 HTTP 请求)。2,000 行只用于描述和附件(`src/tools/FileReadTool/prompt.ts:37`;`src/utils/attachments.ts:3137`)。去重仅对同 offset/limit、mtime 未变的 Read 生效(`FileReadTool.ts:530-570`),Edit 后的状态不参与去重。恶意软件提醒对 `claude-opus-4-7` 以外的所有模型都附(`FileReadTool.ts:697-698, 727-736`)。Grep head_limit 250、2 万字符(`src/tools/GrepTool/GrepTool.ts:108, 164`);Glob 100 个(`src/tools/GlobTool/GlobTool.ts:157`)。 + +### 2.5 Shell + +| | Codex | ZCode | DreamCoder | +|---|---|---|---| +| 工具 | exec_command + write_stdin | Bash | Bash | +| 默认等待/超时 | 10 s 后交回 session ID(250–30,000 ms) | 120 s,最大 600 s | 120 s,最大 600 s | +| 到时行为 | 进程继续,模型轮询 | 自动转后台(`sleep` 除外) | 自动转后台(`sleep` 等除外) | +| 完成通知 | 未找到,需轮询(推断) | 通知入队作为新回合;headless 普通后台 Bash 不等待(推断) | task-notification 入队作为下一轮 | +| 交互进程 | `tty=true` + write_stdin | 不支持交互参数 | 不支持 | +| cwd 跨调用 | 不保留,用 `workdir`(推断) | 保留(项目内) | 保留 | +| 子进程环境 | NO_COLOR、TERM=dumb、C.UTF-8、PAGER=cat、CODEX_CI=1 | GIT_EDITOR=true | GIT_EDITOR=true、CLAUDECODE=1 | +| 输出上限 | 10,000 token/字节 | 30KB 尾部预览,全文存 artifact | 30,000 字符;错误时首尾各 5,000 | +| 沙箱(headless) | 由 sandbox_mode/项目信任推导,默认值未核实 | 未核实 | 默认关闭 | + +- Codex:`codex:core/src/tools/handlers/shell_spec.rs:20-84`;`codex:core/src/unified_exec/mod.rs:68-77, 170-180`(最多 64 进程;write_stdin 单次最长等待默认 300,000 ms);`codex:core/src/config/mod.rs:3825-3850, 4067-4070`;环境 `codex:core/src/unified_exec/process_manager.rs:93-104`;输出头 `codex:core/src/tools/context.rs:524-548`。 +- ZCode:`zcode:core/src/tool/bash-timeout-policy.ts:6-7`;`tool/handlers/bash-background-policy.ts:3-9`;`bash-model-content.ts:62-75, 139-151`;`bash.ts:200-270, 600-611`;`bash-prompt.ts:13-18`(描述约 1.6K 字符);`zcode:adapters/src/exec/bash-shell-provider.ts:111`;`zcode:cli/src/headless-workflow.ts:318-331`。 +- DreamCoder:`src/utils/timeouts.ts:2-3`;`src/tools/BashTool/BashTool.tsx:307-315, 424, 596-622, 860-971`;`src/utils/shell/outputLimits.ts:3-4`;`src/utils/toolErrors.ts:5-27`;`src/utils/Shell.ts:321-322`;`src/utils/sandbox/sandbox-adapter.ts:530-544`;`src/cli/print.ts:1988-2119`。Bash 描述源文件 21,130 字节(`src/tools/BashTool/prompt.ts`,含 git/PR 说明),实际字符数未测。 + +### 2.6 子 agent + +| | Codex | ZCode | DreamCoder | +|---|---|---|---| +| 工具 | spawn_agent/send_input/wait_agent/resume_agent/close_agent | Agent(+SendMessage) | Agent | +| prompt 态度 | 未经用户/AGENTS.md 明确要求不得委派 | 跨多文件阅读、并行工作时委派 | 匹配 agent 描述时用;超过 3 次查询用 Explore | +| 默认模型 | 继承 | profile 的 modelSelection(默认未核实) | Explore 用 provider fastModel;Plan/general 继承 | +| 默认同步/异步 | 异步线程,wait_agent 取结果 | 前台(同步) | 同步 | +| 结果返回 | wait_agent 返回 | 加框缩进的报告 | 最终文本 + agentId/usage 尾注 | +| 深度/数量 | 深度 1,并发 6 | 未核实(子 agent maxTurns 默认 4,但未找到执行处) | 深度 1(非 ant 禁 Agent),数量未找到上限 | +| 普通编码任务默认委派 | 否 | 可能(「跨多个文件」即鼓励) | 可能(搜索超过 3 次) | + +- Codex:Collab 默认开(`codex:features/src/lib.rs:1508-1511`),V1 工具(`codex:core/src/config/mod.rs:1668-1676`);spawn_agent 描述禁止未经要求的委派(`codex:core/src/tools/handlers/multi_agents_spec.rs:735-737`);继承模型(`:17`);深度 1、并发 6(`codex:core/src/config/mod.rs:256, 266`)。 +- ZCode:Agent 描述「When to use」段(`zcode:core/src/tool/handlers/agent.ts:92-120`);报告加 `[Subagent hand-back]` 框并逐行缩进(`agent.ts:122-135`);子 agent `maxTurns` 默认 4(`zcode:core/src/runtime/methods/subagent.ts:340`),主循环未找到消费 `config.maxTurns` 的代码,是否生效未核实;Explore/general-purpose 提示词(`zcode:core/src/subagent/explore.ts`、`general-purpose.ts`)。 +- DreamCoder:非 ant 启用 Explore、Plan(`src/tools/AgentTool/builtInAgents.ts:13-22, 58-65`),Verification agent 也注册(`builtInAgents.ts:24-32, 76-78`),但系统提示里的强制验证段落受 `feature('VERIFICATION_AGENT')` 门控为 false(`src/constants/prompts.ts:~392-394`)。Explore 模型 `haiku`(`src/tools/AgentTool/built-in/exploreAgent.ts:78`),在应用里映射为 provider 的 fastModel(`src/server/services/providerRuntimeEnv.ts:247-248`)。委派指引(`src/constants/prompts.ts:315-320, 375-380`;`EXPLORE_AGENT_MIN_QUERIES = 3`,`exploreAgent.ts:59`)。fork 子 agent 在非交互会话关闭(`src/tools/AgentTool/forkSubagent.ts:32-39`)。子 agent 禁用 Agent(`src/constants/tools.ts:41-55`)。默认同步(`src/tools/AgentTool/AgentTool.tsx:568`)。Agent 工具 prompt 源文件 16,671 字节,内置 agent 定义合计约 40KB(`wc -c`),实际发送字符数未测。 + +### 2.7 规划与任务跟踪 + +| | Codex | ZCode | DreamCoder(应用内) | +|---|---|---|---| +| 工具 | 不注册 update_plan | TodoWrite / TodoRead | TaskCreate / TaskGet / TaskUpdate / TaskList | +| 描述大小 | prompt 中有两节描述该工具 | 约 350 字符 | 4 个 prompt 源文件合计 8,024 字节 | +| 使用指引 | prompt 描述何时用 plan,但工具不存在 | 只说明格式,不要求主动使用 | 「3 步以上主动使用」、开始前标 in_progress、完成立即标 completed | +| 提醒 | 无 | 10 回合未用时提醒 | 10 回合未用时提醒 | +| 每次使用开销 | 调用失败一轮(推断) | 全量列表一次调用 | 每个任务至少 create + 2 次 update(推断) | + +- Codex:`resolve_update_plan_enabled` 只在配置启用时为 true(`codex:core/src/config/mod.rs:2791-2796`;`spec_plan.rs:1292`);prompt 仍有 Planning 与 `update_plan` 两节(`codex:models-manager/prompt.md:52-70, 267-275`)。 +- ZCode:`zcode:core/src/tool/handlers/todo.ts:137-141`;提醒(`zcode:core/src/runtime/helpers/runtime-reminders.ts:100-103, 252-270`)。 +- DreamCoder:服务器给 CLI 设置 `CLAUDE_CODE_ENABLE_TASKS=1`(`src/server/services/conversationService.ts:1052`),于是 Task V2 工具启用、TodoWrite 关闭(`src/utils/tasks.ts:133-139`;`src/tools.ts:218-229`;`src/tools/TodoWriteTool/TodoWriteTool.ts:52-54`)。TaskCreate 描述(`src/tools/TaskCreateTool/prompt.ts`);系统提示要求「Mark each task as completed as soon as you are done ... Do not batch up」(`src/constants/prompts.ts:270-282`);提醒间隔(`src/utils/attachments.ts:251-254, 884`)。这些工具 `shouldDefer: true`,但本场景 ToolSearch 关闭,所以描述每次请求都发送(ToolSearch 关闭的依据见 [tools.md](tools.md))。 + +### 2.8 推演示例(推断) + +任务:「找到函数 `foo` 的定义,改其中一行,运行该测试文件」。假设:仓库不大,`foo` 只定义一次,模型行为符合各自 prompt,编辑一次成功,测试一次通过。 + +**Codex(4 次往返)** +1. exec_command `rg -n -C3 "foo" ...`(拿到位置和上下文;prompt 鼓励用 rg) +2. exec_command `apply_patch <<'EOF' … EOF`(上下文行来自第 1 步,无需 Read) +3. exec_command 运行测试 +4. 最终回复 +若模型先 `sed -n` 看更多上下文:+1;若补丁调用形式错(argv 或无 apply_patch):+1~2。无计划工具。 + +**ZCode(5 次往返)** +1. Grep(content 模式)定位 +2. Read 该文件(Edit 的强制前置;依赖第 1 步的路径,不能合并) +3. Edit +4. Bash 运行测试 +5. 最终回复 +TodoWrite 描述不要求主动使用,通常不调用。若 old_string 带行号前缀或缩进偏差,回退匹配可吸收,不增加往返。 + +**DreamCoder(5~7 次往返)** +1. Grep 定位(可能同时 TaskCreate ×3:查找/修改/测试,描述要求 3 步以上主动使用) +2. Read(强制前置;可能同时 TaskUpdate in_progress) +3. Edit(可能同时 TaskUpdate) +4. Bash 运行测试 +5. TaskUpdate completed(若未与第 4 步合并则单独一轮) +6. 最终回复 +不用任务工具时与 ZCode 同为 5 次;用任务工具且模型按「开始前标 in_progress、完成立即标 completed」逐步执行时为 6~7 次。每次请求都携带全部工具描述(约 64K 字符,见 [tools.md](tools.md)),Read 结果额外附 330 字符提醒。old_string 若带行号前缀或缩进偏差,DreamCoder 不能吸收,+1~2。 + +--- + +## 3. 对 DreamCoder 的含义 + +### DreamCoder 有而另两家都没有 + +| 差异 | 事实 | 后果(推断) | +|---|---|---| +| 每次 Read 附恶意软件提醒 | 约 330 字符,除 `claude-opus-4-7` 外都附(`src/tools/FileReadTool/FileReadTool.ts:697-736`) | 每次读取多约 80–100 token,并累积进历史;对非 Claude 模型没有对应训练,可能使其对正常代码修改更犹豫 | +| 应用内启用 4 个 Task 工具且描述要求主动、逐项更新 | `src/server/services/conversationService.ts:1052`;`src/constants/prompts.ts:270-282` | 小任务也可能多 1~2 次往返和多次工具调用;4 份描述每次请求都发送 | +| Read 超 25,000 token 直接报错 | `FileReadTool.ts:176-183, 753-770` | 大文件首读必定 +1 往返;ZCode 同常量但返回部分视图 | +| 大文件读取触发 count_tokens 请求 | 代理不接该路径(`src/server/proxy/handler.ts:11-17`) | 一次失败的本地 HTTP 请求,增加延迟,不增加 token | +| 接收时的反净化替换表 | `src/tools/FileEditTool/utils.ts:531-550` | 针对 Claude 输出特性的修正,对第三方模型基本无作用 | + +### 另两家都有而 DreamCoder 没有 + +| 差异 | 事实 | 后果(推断) | +|---|---|---| +| 流式过程中开始执行工具 | Codex 全部、ZCode 只读类(`codex:core/src/stream_events_utils.rs:~345-372`;`zcode:core/src/runtime/methods/streaming-tool-coordinator.ts:383-406`);DreamCoder 被 GrowthBook 门关闭(`src/query/config.ts:33`) | 不影响 token 和轮数,只影响墙钟时间;与 benchmark 中 Claude Code「运行时间最长」方向一致,但贡献大小未测 | +| 编辑匹配对空白/缩进的容忍 | Codex trim_end/trim/Unicode 归一;ZCode 7 种回退;DreamCoder 只有弯引号 | 第三方模型常见的缩进、行尾空白、带行号前缀、转义错误在 DreamCoder 上都变成失败,每次 +1~2 往返,且需重发整段 old_string | +| 编辑成功后明确告诉模型「不要读回」 | ZCode 成功文案(`zcode:core/src/tool/handlers/edit.ts:59`)、Read 描述(`read.ts:78`);Codex prompt(`codex:models-manager/prompt.md:143`);DreamCoder 两处都没有 | 模型可能在编辑后再 Read 验证,+1 往返和一份全文输出 | +| 循环异常保护(在两家中至少一家有) | ZCode 有重复调用提醒、可疑空响应重试、静默提醒;Codex 没有。严格说这不是「两家都有」,单列在此 | DreamCoder 遇到第三方模型重复同一调用时没有任何干预;空响应直接结束回合,headless 运行会以空结果收尾 | + +### 三家共同点(不构成差异,但影响判断) + +- 都没有默认步数上限;都没有对 reasoning-only 响应的处理;截断续写文案 ZCode 与 DreamCoder 逐字相同。 +- 编辑失败文案都不包含文件实际内容或最近似片段,模型要么凭记忆重试,要么重读。 + +--- + +## 4. 没有核实的地方 + +- Codex:`ResponseIncomplete` 各原因(max_output_tokens 等)的具体处理;`codex exec` 无参数时的默认沙箱档;后台进程完成是否有主动通知(只找到轮询路径);apply_patch 通过 PATH 别名直接执行时是否仍有事件记录;读取文件的编码处理。前提问题:v0.164.0 不支持 chat wire API,本场景是否需要上游提供 Responses 接口。 +- ZCode:子 agent `maxTurns`(默认 4)是否在任何地方生效;子 agent 默认模型与嵌套深度;headless 沙箱;`targetCompletionVerification` 默认开关;系统提示中是否另有 TodoWrite 使用指引;每回合输入附件的字节数。 +- DreamCoder:工具描述、Agent/Task 描述实际发送的字符数(只测了源文件字节数);LSP 诊断在 headless 应用模式是否启用;权限请求在桌面端无人响应时的最终行为。 +- 所有「额外往返」数字和第 2.8 节的推演都是按 prompt 和代码路径推断,没有运行验证。 diff --git a/docs/features/harness/comparison/model-adaptation.md b/docs/features/harness/comparison/model-adaptation.md new file mode 100644 index 00000000..3a2e7f10 --- /dev/null +++ b/docs/features/harness/comparison/model-adaptation.md @@ -0,0 +1,203 @@ +# D 维度:适配模型与提供方(传输层) + +路径约定:DreamCoder 相对仓库根(`src/...`);`codex:` 相对 `refs/coding-agents/codex/codex-rs`;`zcode:` 相对 `refs/coding-agents/zcode/apps/zcode-cli/packages`;`zcode-rules:` 指 `refs/coding-agents/zcode/config/provider/zcode-builtin.json`(解析该 JSON 得到的规则序号写作 `modelApiRules[n]` 等);`zcode-repo:` 指 zcode 仓库根下的 `packages/provider`、`packages/model-option-map`(规则引擎所在)。场景见 [README](../README.md#对比的场景):第三方非原生模型,经 OpenAI 兼容 chat-completions 端点。全部为静态阅读,未运行任何代码。 + +## 1. 结论 + +1. **线协议**:Codex 只说 Responses API,配置 `wire_api = "chat"` 在反序列化时直接报错(codex:model-provider-info/src/lib.rs:108-135);chat-only 的提供方在 Codex 里无法直接接入,只能在外部加 Responses→chat 网关(推断)。ZCode 用 Vercel AI SDK 原生支持 chat completions(zcode:adapters/src/model/model-execution.ts:301-312, 401-423)。DreamCoder 的 CLI 只说 Anthropic Messages,靠服务端本地代理逐字段翻译(src/server/upstream/client.ts:202-235)。 +2. **每模型知识**:ZCode 有一份 83 条模型规则、73 条模型×协议规则、58 条站点规则的声明式表,按模型名正则和 baseUrl 叠加,决定上下文窗口、输出上限、推理档位及其写到哪个请求字段(zcode-repo:packages/provider/src/config/model-config.ts:398-436)。Codex 只有 11 条 OpenAI 自家模型,未知模型走固定回退值(codex:models-manager/src/model_info.rs:90-146)。DreamCoder 只有上下文窗口表(src/utils/model/modelContextWindows.ts:5-48)和以 Claude 名字为依据的输出上限/能力判断,第三方模型的推理参数没有按模型的映射。 +3. **推理/effort 在 DreamCoder 的 chat 路径上到不了上游**:自定义 provider 下 CLI 总是发 `thinking:{type:'adaptive'}`(src/services/api/claude.ts:1649-1659),代理只在有 `budget_tokens` 或 `type:'enabled'` 时写 `reasoning_effort`(src/server/proxy/transform/anthropicToOpenaiChat.ts:64-72),`output_config.effort` 被丢弃。结果:桌面的 Effort 设置在 openai_chat 上游上不产生任何请求字段(DeepSeek/opencode.ai 域名只多透传一个 `thinking.type`)。ZCode 对每个模型/站点写对应字段(`reasoning_effort`、`thinking.type`、`enable_thinking` 等),默认取最高档。Codex 未知模型不发 effort,只发 `summary:"auto"`。 +4. **输出上限**:ZCode 每步发 `max_completion_tokens = min(模型上限, 窗口−估算输入−1000)`(zcode:core/src/runtime/methods/model-token-limits.ts:6-45);Codex 不发;DreamCoder 的 CLI 发 32000,但代理不转发(`OpenAIChatRequest.max_tokens` 无代码赋值),上游用自身默认值。截断后 ZCode 与 DreamCoder 都有同文的“继续”提示(最多 3 次),Codex 把 `response.incomplete` 当错误结束回合。 +5. **DreamCoder 代理在每个请求的 system 首行插入随请求体变化的 billing 行**(src/server/proxy/handler.ts:64;src/server/proxy/claudeCodeAttribution.ts:28-46;src/utils/claudeCodeCch.ts:46-59 用整个请求体算哈希替换 `cch=00000`)。system 是请求的第一条消息,提供方的前缀缓存因此在第一行就失配(推断:缓存按前缀匹配)。另两家没有这类逐请求变化的前缀内容。 +6. **推理内容跨轮回传**:DreamCoder 只对 baseUrl 含 deepseek 或 opencode.ai 的上游写回 `reasoning_content`(client.ts:251-256),其余(含 Kimi、GLM 的 chat 端点)历史 thinking 全部丢弃。ZCode 把 reasoning 作为 AI SDK 的 reasoning part 交给 SDK,是否序列化为 `reasoning_content` 取决于 `@ai-sdk/openai-compatible`(未核实)。Codex 的 Responses 路径保存并回传 reasoning item(含 `encrypted_content`)。 +7. **非原生模型的容错**:ZCode 有空回复重试、重复调用提醒、参数规范化、媒体降级、`$ref` 修整、上下文溢出文本识别;Codex 有 schema 清理、调用/输出配对修补、参数错误回给模型;DreamCoder 有参数解析失败→`{}`、字符串布尔/数字容忍、zod 错误回给模型,但没有 schema 清理、空回复重试、重复调用检测,且 chat 流里不带 id 的 tool_call 会被丢弃(src/server/proxy/streaming/openaiChatStreamToAnthropic.ts:405)。 +8. **错误与重试**:三家都有指数退避。DreamCoder 的代理把上游错误统一包成 `api_error` 并丢掉上游响应头(`retry-after` 失效,handler.ts:66-71);CLI 的 Anthropic 专用识别(`prompt is too long`、`overloaded_error`、`input length and max_tokens exceed`)对 OpenAI 风格错误文本不命中,且被动压缩模块在本构建里是 stub,上下文溢出后没有自动恢复。ZCode 用文本和错误码识别上下文溢出并触发压缩。 +9. **辅助请求的模型**:DreamCoder 在本场景用 `haiku` 别名(= provider.fastModel,未设则主模型)跑 Explore 子代理和 WebFetch 页面处理;ZCode 所有辅助请求都用会话主模型;Codex 压缩用主模型,review/memories 等有独立配置项。 + +## 2. 逐项对比 + +### Q1 到提供方的路径与支持的线协议 + +| | Codex | ZCode | DreamCoder | +|---|---|---|---| +| 支持的协议 | 仅 Responses | anthropic-messages / openai-responses / openai-chat-completions | CLI 仅 Anthropic Messages;代理上游 anthropic / openai_chat / openai_responses | +| chat-only 提供方 | 不能直连(`chat` 报错) | 原生(@ai-sdk/openai-compatible) | 经本地代理翻译 | +| URL | base_url + `/responses` | SDK 按协议拼接 | base(去掉尾部 `/v1`)+ `/v1/chat/completions` | +| 中间层 | 无 | option-map fetch 改写请求体 JSON | Bun 服务端代理 | + +- Codex:`WireApi` 只有 `Responses`(codex:model-provider-info/src/lib.rs:108-113),`"chat"` 反序列化报 `CHAT_WIRE_API_REMOVED_ERROR`(:124-135)。仓库内 `responses-api-proxy` 只把 `POST /v1/responses` 转发给 OpenAI(codex:responses-api-proxy/README.md:26-30),不做协议转换。调用链:turn 循环(codex:core/src/session/turn.rs:1678-1690)→ `stream_responses_http`(codex:core/src/client.rs:1797-1996,另有 WebSocket 路径)→ `build_responses_request`(:979-1130)。 +- ZCode:`api.type` 选择 SDK 工厂(zcode:adapters/src/model/model-execution.ts:401-423);chat 用 openai-compatible,`includeUsage:true`(:301-312);fetch 链为 option-map → business-error → request-security → endpoint-routing → 代理(:333-394);SDK 的 `maxRetries:0`,重试自己做(zcode:adapters/src/model/runner-options.ts:101-167)。 +- DreamCoder:CLI 的 `ANTHROPIC_BASE_URL` 指向 `http://127.0.0.1:/proxy`(src/server/services/providerRuntimeEnv.ts:210-216),代理只接 `POST /proxy/v1/messages` 与 `/proxy/providers/:id/v1/messages`,`apiFormat==='anthropic'` 时 400 拒绝(src/server/proxy/handler.ts:9-52);`normalizeUpstreamBaseUrl` 去掉尾部 `/v1`(src/server/upstream/baseUrl.ts:1-3),再拼 `/v1/chat/completions`(client.ts:205-215)。预设中只有 qwen 是 openai_chat;DeepSeek/Kimi/智谱预设是 anthropic 格式,CLI 直连上游的 Anthropic 兼容端点、不经代理(src/server/config/providerPresets.json;providerRuntimeEnv.ts:211-216)。 + +### Q2 DreamCoder 逐字段翻译 + +请求方向(chat,src/server/proxy/transform/anthropicToOpenaiChat.ts): + +| Anthropic 字段 | 发往 chat 上游 | 位置 | +|---|---|---| +| system(块数组) | 用 `\n` 拼成一条 role=system;代理先在最前插 billing 块 | :19-26;handler.ts:64 | +| cache_control | 丢弃 | — | +| user 的 tool_result | role=tool,排在同一条 user 的文本/图片之前 | :105-131 | +| tool_result 里的图片 | 文字 `[image omitted: ]` | toolArguments.ts:37-38 | +| tool_result.is_error | 丢弃 | types.ts:153 有字段,转换未用 | +| user 图片 | `image_url` data URL | :111-113 | +| assistant text / tool_use | 拼接文本;`tool_calls` | :143-167 | +| assistant thinking | 仅 deepseek/opencode.ai 域名写 `reasoning_content`,否则丢弃 | :146-147, 168-170;client.ts:206-210, 251-256 | +| tools | `input_schema` 原样作 `parameters`;去掉 `BatchTool`;无 schema 清理 | :47-58 | +| tool_choice | auto→auto,any→required,none→none,tool→function | :175-187 | +| thinking | 见 Q3 | :64-76 | +| output_config(effort/format) | 丢弃(类型里无此字段) | types.ts:161-181 | +| max_tokens | 不转发 | types.ts:35-36 有字段,无赋值 | +| temperature / top_p / stop_sequences | 转发 | :40-45 | +| metadata、betas(在 HTTP 头里)、context_management | 丢弃 | — | +| stream_options.include_usage | 流式时总设 true | :38 | +| parallel_tool_calls | 不发送(全仓无此字段) | grep | + +请求方向(Responses,src/server/proxy/transform/anthropicToOpenaiResponses.ts):system → `instructions`(:24-30);`store:false`(:21);消息内块按原顺序展开,tool_use → `function_call`,tool_result → `function_call_output`(:90-105);助手文本 `output_text`、用户文本 `input_text`(:80);图片 `input_image`(:85-89);thinking 块总是丢弃,不生成 reasoning item,也不请求 `encrypted_content`;tools 带 `strict:false`(:36-44);`reasoning.effort` 规则与 chat 相同(:51-60);stop_sequences、max_tokens、parallel_tool_calls 不发送。 + +响应方向(chat 流,src/server/proxy/streaming/openaiChatStreamToAnthropic.ts): + +| 上游 | 转成 | 位置 | +|---|---|---| +| `delta.content` | text 块 | :358-368 | +| `reasoning_content` / `reasoning` / `thinking_blocks` | thinking 块,signature 为空串(thinking_blocks 时取原值) | :246-268, 338-356 | +| `tool_calls[].index` | 每个 index 一个 tool_use 块;参数以 `input_json_delta` 增量转发 | :387-431 | +| 无 index 的并行调用 | 按 id 变化或 name 再次出现判定新调用 | :370-385 | +| 无 id 的 tool_call | 不开块,整个调用被丢弃 | :405 | +| finish_reason | stop→end_turn,tool_calls→tool_use,length→max_tokens,content_filter/其他→end_turn;出现过工具而 stop→tool_use | :433-445, 530-538 | +| usage | `prompt_tokens − cached_tokens`→input,`prompt_tokens_details.cached_tokens`→cache_read;无 cache_creation;usage 晚到时暂存 message_delta 等合并 | openaiChatToAnthropic.ts:81-91;:457-476 | +| 无 usage 块 | `output_tokens:0` | :518-525 | +| 流中 `error` 对象 / 无有效 chunk | SSE `error` 事件,type api_error,无 HTTP 状态 | :113-120, 497-505 | +| 流截断(无 finish_reason) | 补 end_turn 的 message_delta + message_stop | :508-527 | + +- 非流式 chat(openaiChatToAnthropic.ts):参数 JSON 失败 → `{raw: 原文}`(toolArguments.ts:7-22),与流式路径(CLI 侧解析失败得到 `{}`,src/utils/messages.ts:2770-2789)不一致;无 choices → 空文本。 +- Responses 流(openaiResponsesStreamToAnthropic.ts):`function_call` item → tool_use(:156-172),参数按 `item_id`(:227-239);`reasoning_summary_text`/`reasoning_text` → thinking(:268-290);`incomplete`→max_tokens,`completed` 且有工具→tool_use(:318-327);`response.failed`/`error` → SSE error(:307-315);usage 用 `input_tokens_details.cached_tokens`(openaiResponsesToAnthropic.ts:36-44)。 +- 缓存用量字段:只读 `prompt_tokens_details.cached_tokens`。DeepSeek 原生端点用 `prompt_cache_hit_tokens` 报告缓存(推断,依据外部文档,代码中未处理),这种情况下缓存命中会记为 0。 + +### Q3 推理与 effort + +| | Codex | ZCode | DreamCoder(openai_chat 上游) | +|---|---|---|---| +| 档位来源 | 配置 `model_reasoning_effort` 或目录默认 | 模型规则 `reasoningLevel.values`;选模型时取最高档 | 桌面 Effort → `--effort` | +| 未知模型默认 | 不发 effort,只发 `summary:"auto"` | `enabled` → 通用映射写 4 个字段 | 不发任何推理字段 | +| 写到哪里 | `reasoning.{effort,summary}` | option-map 按模型/站点写 `reasoning_effort` / `thinking.type` / `enable_thinking` / `reasoning.effort` | 仅在 thinking 有 budget 或 enabled 时写 `reasoning_effort` | +| 跨轮推理内容 | reasoning item + `encrypted_content` 回传 | reasoning part 交给 SDK(序列化未核实) | 仅 deepseek/opencode.ai 域名写回 `reasoning_content` | + +- Codex:`build_reasoning`(codex:core/src/client.rs:957-976);include 至少含 `reasoning.encrypted_content`(:1075);reasoning item 属于发给 API 的历史项(codex:core/src/context_manager/history.rs:1048)。回退元数据 `default_reasoning_level: None`、`supported_reasoning_levels` 为空(codex:models-manager/src/model_info.rs:90-146)。DeepSeek/Kimi 式 `reasoning_content`:Codex 不说 chat,不适用。 +- ZCode:通用 chat 映射(zcode-rules: modelApiRules[2])同时写 `thinking.type`、`enable_thinking`、`reasoning_effort`(disabled→"none",enabled→"high")、`reasoning.effort`;kimi-k3 → 仅 `reasoning_effort`(modelApiRules[24],[26]);`deepseek-v4[.-]1-flash` → `thinking.type` + `reasoning_effort`(modelApiRules[67]);glm-5.3 走 chat 时落到通用映射;`deepseek-v4.1-pro` 无专门规则,落到基线(推断:正则整串匹配不命中)。默认档取 `values.at(-1)`(zcode-repo:packages/provider/src/model-selection-config.ts:57-72)。推理历史经 `normalizeReasoningHistory` 去掉跨模型 reasoning 等(zcode:adapters/src/model/reasoning-history-normalization.ts:44-52),以 reasoning part 交给 `@ai-sdk/openai-compatible` ^2.0.58(zcode:adapters/package.json:110);空 reasoning 不写 `reasoning_content` 有测试(zcode:adapters/tests/openai-compatible-extra-body-wire.test.ts:106-133),非空时是否写出未核实。 +- DreamCoder 链路(静态追踪,未运行): + 1. 桌面 Effort 选项 low/medium/high/max;会话内经 WS `set_runtime_config`,全局经 PUT `/api/effort`;未设置时服务器不加参数(src/server/ws/handler.ts:1174-1180, 1202-1207)。启动参数 `--effort `(src/server/services/conversationService.ts:976-978);改 effort 会重启会话。 + 2. CLI:`resolveAppliedEffort`(src/utils/effort.ts:152-167);`configureEffortParams` 只在 `modelSupportsEffort` 为真时写 `output_config.effort`(claude.ts:439-465)。 + 3. thinking:默认 `{type:'adaptive'}`(src/main.tsx:2422-2426);`hasThinking && modelCanThink` 且支持 adaptive → `thinking:{type:'adaptive'}`,否则 `{type:'enabled', budget_tokens}`(claude.ts:1649-1673);不能 think 时只有 `sendsExplicitDisabledThinking` 才发 disabled(:1674-1678)。 + 4. **自定义 provider**:`presetId==='custom'` 时三档 `*_SUPPORTED_CAPABILITIES` 都是 `thinking,effort,adaptive_thinking,max_effort`,主模型同时是 SONNET/OPUS 默认模型(providerRuntimeEnv.ts:38, 229-250),因此走 adaptive 分支,`set_max_thinking_tokens` 的预算也不会被采用。代理收到 `thinking:{type:'adaptive'}` + `output_config.effort` → chat 请求里没有 `reasoning_effort`(adaptive 无 budget,type 不是 enabled),effort 丢弃。上游收到:非 deepseek/opencode.ai 域名无任何推理字段;这两个域名多一个 `thinking:{type:"adaptive"}`(client.ts:206-210;上游是否接受该值未核实)。关闭思考时同理,上游按模型自身默认决定是否思考。 + 5. **预设 provider(qwen,openai_chat)**:无能力声明,模型名不含 sonnet-4/opus-4 → `modelSupportsThinking` 为假(src/utils/thinking.ts:91-117),不发 thinking;`modelSupportsEffort` 对未知名字在 firstParty 下为真(effort.ts:23-49),写入 `output_config.effort` 后被代理丢弃。上游收到:无推理字段。 + 6. Kimi/智谱/DeepSeek 预设走 anthropic 格式直连,thinking 与 output_config 原样到上游;Kimi/智谱额外设 `DREAMCODER_SEND_DISABLED_THINKING=1`,关闭时显式发 disabled(providerPresets.json)。 + +### Q4 每模型知识及来源 + +| | Codex | ZCode | DreamCoder | +|---|---|---|---| +| 来源 | 内置 models.json 11 条(OpenAI)+可选 `model_catalog_url` | zcode-builtin.json 规则叠加+个人手动规则 | 上下文窗口表+env 覆盖;其余按 Claude 名字判断 | +| 匹配方式 | slug 最长前缀,再去一段命名空间 | 模型 id 整串正则(忽略大小写)+协议+baseUrl | 窗口:精确/后缀匹配;能力:名字含 sonnet/opus/haiku | +| 未知模型窗口 | 272000,有效 95% | 1000000(基线) | 200000 | +| 未知模型输出上限 | 不发送 | 128000(基线) | 32000(CLI 内部;不转发) | +| 推理档位 | 空 | [disabled, enabled] | 无映射 | +| 图像 | 文本+图像 | 仅文本,媒体降级 | 无判断,照发 | +| 并行工具调用 | 请求固定 true | 未见设置 | 不发送 | +| 中途系统消息 | developer 角色项 | 由 `supportsMidConversationSystem` 决定 | 不用 system 角色(user 内 system-reminder) | +| 工具格式特例 | 回退时不声明 apply_patch | `requiresMfjsToolSchema`;strict 仅一方模型 | 仅过滤 BatchTool | + +- Codex:目录匹配 codex:models-manager/src/manager.rs:888-931;回退 codex:models-manager/src/model_info.rs:90-146(截断 10000 字节、窗口 272000、`input_modalities` 默认文本+图像 codex:protocol/src/openai_models.rs:193-195、`used_fallback_model_metadata=true`);`parallel_tool_calls: true` 固定(codex:core/src/session/turn.rs:1686),单个工具能否并行由注册表决定(codex:core/src/tools/registry.rs:606);基础指令作为 developer 角色的首个 input 项(codex:core/src/client.rs:1031-1041;codex:core/src/context/base_instructions.rs:46-47)。 +- ZCode:基线规则 `.*`:窗口 1000000、仅文本、`supportsToolCall` true、`supportsMidConversationSystem` false、输出上限 128000、档位 [disabled, enabled](zcode-rules: modelRules[0]);手动模型可覆盖的字段见 zcode-repo:packages/provider/src/config/manual-model-config.ts:7-28;媒体降级 zcode:adapters/src/model/media-transform-policy.ts、tool-result-media-projection.ts;中途 system 由 zcode:core/src/runtime/helpers/runtime-provider-request-messages.ts:13-20 控制;工具检索只在 anthropic-messages 可用(zcode:adapters/src/model/tool-search.ts:5-17)。 +- DreamCoder:窗口优先级为 env `CLAUDE_CODE_MODEL_CONTEXT_WINDOWS`(预设表 + provider 配置;列模型时由 src/server/upstream/contextWindows 从 `/v1/models` 列表、ollama、lmstudio、deepseek、qwen 来源补全,index.ts:11-17)> 内置表(src/utils/model/modelContextWindows.ts:5-48,有 deepseek-v4、kimi-k2.x、glm-5.1 等,无 glm-5.3/deepseek-v4.1/kimi-k3)> 200000(src/utils/context.ts:11, 53-115)。输出上限按 Claude 名字(context.ts:203-260),未知模型 32000、上限 64000;`getModelCapability` 仅 ant(src/utils/model/modelCapabilities.ts:46-51)。thinking/effort 能力:3P 能力 env 覆盖 → 名字判断(effort.ts:23-49;thinking.ts:91-163)。 + +### Q5 输出上限与截断 + +| | Codex | ZCode | DreamCoder | +|---|---|---|---| +| 请求里的上限 | 不发 | `max_completion_tokens = min(模型上限, 窗口−输入估算−1000)` | CLI 32000,代理不转发 → 上游默认 | +| 截断判定 | `response.incomplete`(非 interrupted/content_filter) | finishReason length 或原始 max_tokens 等 | finish_reason length → max_tokens | +| 截断后 | `ResponseIncomplete` 错误,不重试,回合结束 | 无工具调用时注入继续提示,最多 3 次,第 4 次报错 | 无 tool_use 时注入继续提示,最多 3 次;有 tool_use 时照常执行工具 | + +- Codex:codex:codex-api/src/sse/responses.rs:419-448;不重试 codex:protocol/src/error.rs:424。 +- ZCode:zcode:core/src/runtime/methods/model-token-limits.ts:6-45;zcode:core/src/runtime/methods/turn-output-token-continuation.ts:17-66。 +- DreamCoder:`getMaxOutputTokensForModel`(claude.ts:3454-3474;`tengu_otk_slot_v1` 默认 false,8K 封顶不生效);截断时生成 “exceeded the 32000 output token maximum” 的 API 错误消息(claude.ts:2316-2326,数字是 CLI 的值,与上游实际上限无关);续写提示 query.ts:1212-1242,次数上限 :165;有 tool_use 时 `needsFollowUp` 为真,不进入恢复(query.ts:830-835, 1050),被截断的参数解析为 `{}` 后由 zod 校验报错回给模型。 + +### Q6 对非原生模型的容错 + +| | Codex | ZCode | DreamCoder | +|---|---|---|---| +| 工具参数解析失败 | 错误文本回给模型 | 规范化为 `{}`(去 BOM) | 流式 `{}`、非流式 `{raw}`;zod 错误回给模型 | +| 参数类型容忍 | 未找到 | 未找到 | 字符串 "true"/"5" 接受为布尔/数字 | +| schema 清理 | MCP/动态工具 `sanitize_json_schema` | `$ref` 提升(仅 kimi-k3 某站点);strict 仅一方 | 无 | +| 文本内嵌工具调用 | 未找到 | 未找到 | 未找到 | +| 无 id / 空名的调用 | 未找到 | 空名保留并让工具报错 | 无 id 的调用被丢弃 | +| 空回复 | 未找到专门处理 | 重试 1 次 | 无事件时改非流式重试;有效但空的回复直接结束 | +| 重复调用 | 未找到 | 同名同参连续 3 次注入提醒 | 未找到 | +| 角色顺序 | 补缺失 call output、删孤立 output | reasoning 历史规范化、补 “(no content)” | tool 消息放在同条 user 文本前;CLI 侧配对修补 | +| system 合并 | 基础指令为 developer 项 | 开头连续 system 合并为一条 | 所有 system 块合成一条 | + +- Codex:codex:core/src/context_manager/normalize.rs:21, 171, 346, 394;codex:tools/src/json_schema.rs:47-116;参数错误 `RespondToModel("failed to parse function arguments: …")`(如 codex:core/src/tools/code_mode/wait_handler.rs:44-49)。 +- ZCode:zcode:adapters/src/model/tool-input-normalization.ts:9-47;tool-call-validation.ts:5-27;empty-completion-retry.ts:6-27;zcode:core/src/runtime/helpers/model-anomaly.ts:21-113;zcode:adapters/src/model/system-message-compat.ts:6-36。 +- DreamCoder:src/utils/messages.ts:2770-2789;src/utils/semanticBoolean.ts:22-28(另有 semanticNumber.ts:26,12 个工具文件使用);src/services/tools/toolExecution.ts:616-671;空流分支 claude.ts:2400-2413(代理在流结束时总会补 end_turn,所以上游返回合法但空的回复不会触发该分支,推断);无 id 丢弃 openaiChatStreamToAnthropic.ts:405。 + +### Q7 错误与重试 + +| | Codex | ZCode | DreamCoder | +|---|---|---|---| +| 次数 | HTTP 层 4,流/回合层 5;连接失败无限(5s 起,上限 60s) | 10 次重试 | CLI 10 次;代理 0 次 | +| 退避 | 200ms 起指数,或 retry-after | 2s×2,上限 60s,抖动,遵守 retry-after(≤5 分钟) | 500ms×2,上限 32s,+25% 抖动;retry-after 被代理丢掉 | +| 429 | HTTP 层不重试,回合层按类别重试 | 重试 | 重试 | +| 400/422 | 不重试 | 不重试 | 不重试 | +| 上下文溢出 | `context_length_exceeded` 码 → 标满;纯文本 400 → InvalidRequest | 码或文本(含 “maximum context length”)→ 被动压缩 | 仅认 “prompt is too long”;被动压缩是 stub,不恢复 | +| 流中断 | 回合层重试 | streamRecovery 重发 | 默认改走非流式请求 | + +- Codex:codex:model-provider-info/src/lib.rs:68-70, 471-477;codex:core/src/responses_retry.rs:22-23, 56-173;codex:protocol/src/error.rs:415-460;codex:codex-api/src/sse/responses_error.rs:48。 +- ZCode:zcode:adapters/src/model/retry-policy.ts:12-31;runner-retry.ts:15-60;failure-classifier.ts:194-300;failure-inspection.ts:185-243;zcode:core/src/runtime/internal-turn-methods.ts:191。 +- DreamCoder 代理:上游非 2xx → `{type:'error',error:{type:'api_error',message:'Upstream returned HTTP : '}}`,状态码沿用,上游响应头不传(handler.ts:66-71;client.ts:83-89);网络错误/超时 → 502;代理超时默认 120s(src/server/services/networkSettings.ts:13),流式只覆盖到收到响应头(client.ts:258-277)。SDK 把 body 序列化进消息 `" {json}"`(node_modules/@anthropic-ai/sdk/core/error.js:18-26);SSE `error` 事件生成无状态码的 APIError(node_modules/@anthropic-ai/sdk/core/streaming.js:99-103)。 +- DreamCoder CLI:`withRetry` 默认 10 次(src/services/api/withRetry.ts:52, 789-794),退避(:530-548),可重试 408/409/429/401/5xx/连接错误(:696-786)。流中错误默认改非流式请求再走 withRetry(claude.ts:2512-2601)。流空闲看门狗默认关闭(claude.ts:1924-1928,需 `CLAUDE_ENABLE_STREAM_WATCHDOG`)。 +- Anthropic 专用处理在翻译后的错误上是否触发:529 判定为 `status===529` 或消息含 `"type":"overloaded_error"`(withRetry.ts:610-621)——代理把上游 body 放进 JSON 字符串字段,引号被转义,该子串不会出现(推断);OpenAI 兼容上游通常不返回 529。“prompt is too long”(src/services/api/errors.ts:560-573)与 “input length and `max_tokens` exceed context limit”(withRetry.ts:550-575)都是 Anthropic 文本,OpenAI 风格的 `context_length_exceeded` / “maximum context length” 不匹配;即使匹配,`REACTIVE_COMPACT` 为 false 且模块是生成的 stub(src/query.ts:15-17;src/services/compact/reactiveCompact.ts),不会被动压缩。429 的提示文案指向 status.anthropic.com(errors.ts:555)。 + +### Q8 辅助请求的模型 + +| | Codex | ZCode | DreamCoder | +|---|---|---|---| +| 机制 | 各功能独立配置项 | 无小模型,一律用会话模型 | `haiku` 别名与 `ANTHROPIC_SMALL_FAST_MODEL` | +| 本场景用到小模型的 | 无(压缩用主模型) | 无 | Explore 子代理、WebFetch 页面处理、claude-code-guide 子代理、prompt/agent 类 hook | +| 本场景不触发的 | memories 默认关;`codex exec` 无标题请求 | — | bash 前缀、工具摘要、WebSearch 小模型、away summary、CLI 内标题 | + +- Codex:压缩用当前模型,非 OpenAI 提供方无远程压缩(codex:model-provider/src/capabilities.rs:33-40);memories 默认关(codex:features/src/lib.rs:1317-1322),开启后用 `memories.extract_model/consolidation_model`(codex:config/src/types.rs:352-354);`review_model`(codex:config/src/config_toml.rs:172)。 +- ZCode:压缩、标题、web_fetch、web_search、project_memory_recall、子代理都用会话模型(zcode:core/src/runtime/methods/compact-active.ts:206-210;zcode:bootstrap/src/app/workflow-actor-model.ts:5-8)。 +- DreamCoder:别名解析 `getSmallFastModel` → `ANTHROPIC_SMALL_FAST_MODEL` → `ANTHROPIC_DEFAULT_HAIKU_MODEL`(src/utils/model/model.ts:41-43, 142-148),两者都是 provider.fastModel,未设则主模型(providerRuntimeEnv.ts:220-222, 247-248)。Explore 子代理非 ant 时 `model:'haiku'`(src/tools/AgentTool/built-in/exploreAgent.ts:78),非 ant 默认启用(src/tools/AgentTool/builtInAgents.ts:13-16);WebFetch `applyPromptToMarkdown` 调 `queryHaiku`(src/tools/WebFetchTool/utils.ts:516),预批准域名的短 markdown 例外(WebFetchTool.ts:261-276);claude-code-guide `model:'haiku'`(claudeCodeGuideAgent.ts:119);hook 默认 small-fast(src/utils/hooks/execPromptHook.ts:79;execAgentHook.ts:118)。不触发:bash 前缀生产路径不调用(src/tools/BashTool/bashPermissions.ts:2386-2393);工具摘要需 `CLAUDE_CODE_EMIT_TOOL_USE_SUMMARIES`(src/query/config.ts:36);WebSearch 小模型需 `tengu_plum_vx3`(src/tools/WebSearchTool/WebSearchTool.ts:395-398);会话标题由服务端 titleService 用 `fastModel || 选中模型` 直连上游(src/server/services/titleService.ts:78-85,不经代理 handler,没有 billing 行)。`queryHaiku` 发出的请求 thinking 为 disabled、不带工具(claude.ts:3325-3340)。 + +## 3. 对 DreamCoder 的含义 + +### DreamCoder 有而另两家都没有 + +| 差异 | 事实 | 后果(推断) | +|---|---|---| +| 请求要经过 Anthropic→OpenAI 的有损翻译层 | effort、max_tokens、is_error、cache_control、tool_result 内图片、非白名单域名的历史 reasoning 被丢弃(Q2 表) | 非原生模型拿不到推理强度和输出上限;工具失败只能靠文本区分;推理模型跨轮丢失自己的推理,可能重复推理、输出变长 | +| system 首行逐请求变化的 billing 行 | handler.ts:64;claudeCodeCch.ts:46-59 | 提供方前缀缓存从第一行起失配,每轮按全量输入计费,输入成本和首 token 延迟都上升;与 benchmark 中 Claude Code 系输入 token 多、耗时长的方向一致,但未测量 | +| 以 Claude 名字为依据的能力推断 | thinking/effort/输出上限按 sonnet/opus/haiku 判断;自定义 provider 统一声明全部能力 | 同一个第三方模型,选“自定义”和选“预设”时请求字段不同;Effort 设置在 chat 上游没有效果 | +| `haiku` 别名驱动的子代理与 WebFetch | Q8 | 未设 fastModel 时等于主模型,无节省;设了 fastModel 时 Explore 子代理的质量取决于该小模型 | +| CLI 看不到上游的错误语义 | 代理统一包成 api_error,丢 retry-after | 限流时按固定退避重试,可能过早重试再被限流;上下文溢出直接失败,不自动压缩 | +| 截断提示中的上限数字来自 CLI | claude.ts:2316-2326 | 显示的 32000 与上游实际上限不符,只影响提示文本 | + +### 另两家都有而 DreamCoder 没有 + +| 差异 | 事实 | 后果(推断) | +|---|---|---| +| 输出上限的请求语义一致(ZCode 明确发送;Codex 走 Responses 默认、不声称发送) | DreamCoder 的 CLI 以为发了 32000,实际被代理丢弃 | 输出上限由上游默认值决定,有的提供方默认较小,长文件写入更易被截断,进而触发续写或 `{}` 参数错误,增加轮数 | +| 按模型的推理参数映射 | ZCode option-map;Codex `reasoning.effort` | DreamCoder 无法让 GLM/Kimi/DeepSeek 在 chat 端点上开关或调节推理 | +| 跨轮推理内容的通用处理 | Codex 回传 reasoning item;ZCode 交给 SDK 并做历史规范化 | DreamCoder 只对两个域名回传;对要求回传的模型(如 Kimi 思考模式)可能出现质量下降或 400(未核实) | +| 上下文溢出的识别 | ZCode 文本+码识别并压缩;Codex 识别码 | DreamCoder 只靠按 200K(或配置值)提前自动压缩;窗口配置偏大时,溢出即失败 | +| 对未知模型给出集中的回退元数据 | Codex 回退 ModelInfo;ZCode 基线规则 | DreamCoder 的回退分散在多个按 Claude 名字判断的函数里,结果随 provider 类型变化 | + +另外:ZCode 独有的容错(空回复重试、重复调用提醒、媒体按模型降级)DreamCoder 也没有;Codex 独有的工具 schema 清理 DreamCoder 也没有(MCP 工具 schema 原样发给上游;哪些提供方会拒绝含 `$ref`/`oneOf` 的 schema 未核实)。 + +## 4. 没有核实的地方 + +- ZCode:`@ai-sdk/openai-compatible` ^2.0.58 是否把非空 reasoning part 序列化为 `reasoning_content`(refs 中无 node_modules);流空闲超时默认值 `DEFAULT_MODEL_STREAM_IDLE_TIMEOUT_MS` 的数值;chat 路径下是否发送 `parallel_tool_calls`。 +- DreamCoder:DeepSeek/opencode.ai 端点是否接受 `thinking:{type:"adaptive"}`;DeepSeek 原生端点的缓存命中字段名是否导致 cache_read 为 0;各提供方在未设置 max_tokens 时的默认上限;billing 行导致缓存失配的实际 token 影响(未测量);WebSearch 在代理场景下的后端选择(`resolveWebSearchProvider`)属于工具维度,未追。 +- Codex:回退元数据下用户显式设置 `model_reasoning_effort` 时是否原样发送(`resolve_reasoning_effort` 未逐行核对);外部网关后接 chat-only 提供方的实际行为(仓库外)。 +- 所有数字(重试次数、上限、窗口)来自源码常量,未运行验证。 diff --git a/docs/features/harness/comparison/prompt.md b/docs/features/harness/comparison/prompt.md new file mode 100644 index 00000000..c34d62dd --- /dev/null +++ b/docs/features/harness/comparison/prompt.md @@ -0,0 +1,403 @@ +# 维度 B:system prompt 及其他以文字告知模型的内容 + +场景:第三方模型(GLM-5.3、DeepSeek-V4.1、Kimi-K3 一类)经 OpenAI 兼容端点,headless 运行一个编码任务。字符数为字符(非字节)。路径约定(见 [README](../README.md#对比的场景)):`codex:` 相对 `refs/coding-agents/codex/codex-rs`,`zcode:` 相对 `refs/coding-agents/zcode/apps/zcode-cli/packages`,`zcode-cfg:` 相对 `refs/coding-agents/zcode/config/provider`,DreamCoder 相对仓库根。 + +测量方法:DreamCoder 的各段按本场景分支把 `src/constants/prompts.ts`、`src/memdir/*` 的字符串重建后计数,其中 intro / System / Doing tasks / Actions / Tools / Tone / Output efficiency / Session guidance 八段做过独立复算,相差不超过 1。Codex 的 `prompt.md` 全文 20 751 字符、剔除 Planning 与 update_plan 两节后 16 979 字符,复算一致。ZCode 各段从源码字面量重建复算,Identity 1 171、Dynamic Behavior 975、Context management 559、Memory 约 2 066(路径按 46 字符计)。三家代码均未执行。 + +## 1. 结论 + +1. 首个请求里 system 及注入文字的体量:DreamCoder 约 26.5K(不含 git 状态、CLAUDE.md、工具描述),Codex 约 17.7K,ZCode 约 6.5K 起。三家的差异主要来自 DreamCoder 的 memory 段(约 12.5K,占 47%)和「Doing tasks / Executing actions with care / Using your tools / Tone / Output efficiency」五段(约 9.2K);ZCode 把这些压到约 1.6K。 +2. DreamCoder 向非 Claude 模型发送大量 Claude 专属文字:身份前缀「You are a Claude agent, built on Anthropic's Claude Agent SDK.」、Environment 段里 549 字符的 Claude 模型家族 / Claude Code 产品 / `/fast` 说明、`/help` 指向 Claude Code、Read 工具称「Claude Code is a multimodal LLM」(而代理会把工具结果里的图片换成文字)、子 agent 自称「agent for Claude Code」,以及 Bash 工具要求在提交信息末尾写 `Co-Authored-By: Claude Opus 4.7 `。Codex 和 ZCode 没有向第三方模型发送其他厂商的模型名。 +3. DreamCoder 的 CLI 不读 `AGENTS.md`(只有 `/init` 命令提到它),只读 `CLAUDE.md` 系列;Codex 与 ZCode 都读 `AGENTS.md`。这一条已确认。 +4. Codex 的 fallback prompt 把篇幅放在「最终消息格式」(约 6.0K)、「前言与进度更新」(约 2.7K)、「验证」(约 2.0K)上;DreamCoder 外部构建里没有任何验证或「何时算完成」的条文(相关条目只在 `USER_TYPE=ant` 时加入);ZCode 只有一句「如实汇报:测试失败要附输出」。 +5. 动态上下文的送达方式不同:Codex 和 ZCode 把环境、日期、指令文件、skills、agent 清单作为对话历史里的独立消息发送,按与历史的差异只追加变化;DreamCoder 把环境放在 system 内、git 状态放在 system 末尾、CLAUDE.md 与日期放在第一条 user 消息,会话内各算一次,之后只有日期跨天、子目录 CLAUDE.md 等少数附件会追加。 +6. 中途提醒:DreamCoder 在每次 Read 文本结果后追加 340 字符的「考虑是否为恶意软件」提醒(模型不是 claude-opus-4-7 时都加),另有每 10 轮的 task 提醒(480 字符起);ZCode 每个工具批次后追加约 45 字符的 `` 倒数,另有静默 5 轮提醒、重复调用提醒、todo 提醒;Codex 在本场景基本没有中途提醒。 +7. 压缩提示:Codex 426 字符;DreamCoder 约 5.6K;ZCode 约 6.4K(与 DreamCoder 同源,增加了「安全相关约束逐字保留」和「不要把 assistant 文本当成用户消息」两条)。 +8. 子 agent:Codex 子 agent 复用父会话的整份 base instructions(约 17K);DreamCoder 与 ZCode 子 agent 用 1–2.5K 的专用 prompt 加约 0.6–1.1K 的 Notes,二者文字几乎相同,但 DreamCoder 版本自称 Claude Code、ZCode 版本自称 ZCode。 +9. ZCode 的 prompt 明显以 Claude Code 为蓝本删减而成:保留了安全声明、git 状态块、指令文件前言、skills 清单格式、memory 类型、压缩提示、子 agent prompt、todo 提醒的原文或近似原文;删除了语气、输出效率、工具对照表、Agent 用法等大段;并加入了 DreamCoder 2.1.92 里没有的几段(代词、如实汇报、下载文件不可信、token 预算、「够了就动手」)。 + +## 2. 逐项对比 + +### Q1 逐节清单 + +#### DreamCoder(场景:server 以 `--print` stream-json 启动 CLI,`USER_TYPE` 非 `ant`,`feature()` 全为 false,GrowthBook 关闭) + +启动参数:`src/server/services/conversationService.ts:141-157` 只传 `--print --verbose --sdk-url ... --input-format/--output-format stream-json --include-partial-messages --session-id|--resume --replay-user-messages` 加 `--model/--effort/--thinking` 和权限参数(`src/server/services/conversationService.ts:969-985`);没有 `--system-prompt`、`--append-system-prompt`。所以走 `getSystemPrompt` 默认路径(`src/utils/queryContext.ts:56-66`)。 + +子进程环境(`src/server/services/conversationService.ts:1048-1061`):`CLAUDE_CODE_ENABLE_TASKS=1`(`src/utils/tasks.ts:133-139`,用 TaskCreate 系而非 TodoWrite)、`CLAUDE_COWORK_MEMORY_PATH_OVERRIDE`(auto memory 目录定到 `/projects/<项目>/memory/`,`:1060`)、`DREAMCODER_SHOW_UI`、`DREAMCODER_SESSION_LINKS`;`CLAUDE_CODE_ATTRIBUTION_HEADER` 对非 `claude*` 模型置 `0`(`src/server/services/attributionHeaderPolicy.ts:11-20`)。`CLAUDE_CODE_ENTRYPOINT` 非交互时为 `sdk-cli`(`src/main.tsx:532`)。`MACRO.ISSUES_EXPLAINER` 在 `preload.ts:19` 是空串。 + +发给模型的 system 内容,按顺序(`src/services/api/claude.ts:1394-1403`,`src/query.ts:451`): + +| # | 段 | 字符 | 内容 | +|---|---|---|---| +| 0 | 计费头 `x-anthropic-billing-header: ...; cch=00000;` | 约 90 | CLI 不加;代理在 `src/server/proxy/handler.ts:64` → `src/server/proxy/claudeCodeAttribution.ts:29-47` 补为 system 第一块;`cch` 由 `src/server/upstream/client.ts:211-224` 换成请求体哈希(详见维度 C) | +| 1 | 身份前缀 `src/constants/system.ts:12,29-43` | 63 | 非交互且无 append →「You are a Claude agent, built on Anthropic's Claude Agent SDK.」 | +| 2 | intro `src/constants/prompts.ts:175-184` | 834 | 角色一句;`CYBER_RISK_INSTRUCTION`(459);禁止猜 URL | +| 3 | `# System` `:186-197` | 1 625 | 输出显示给用户;权限模式;system-reminder 标签;提示注入要告知用户;hooks;自动压缩 | +| 4 | `# Doing tasks` `:199-253` | 3 267 | 任务范围;不加范围外功能/多余错误处理/一次性抽象;先读后改;不给时间估计;失败先诊断;OWASP;`/help` 与反馈 | +| 5 | `# Executing actions with care` `:255-267` | 2 832 | 可逆性与影响范围;需确认的动作清单;遇障碍不走破坏性捷径 | +| 6 | `# Using your tools` `:269-314` | 1 622 | 专用工具代替 Bash 的对照;TaskCreate 用法;并行调用 | +| 7 | `# Tone and style` `:430-442` | 706 | 不用 emoji;简短;`file_path:line_number`;`owner/repo#123` | +| 8 | `# Output efficiency` `:403-428` | 730 | 直奔主题、少说 | +| — | `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` | 0 | 插入数组但拼块时跳过(`src/utils/api.ts:338,374`) | +| 9 | `# Session-specific guidance` `:352-400` | 1 286 | AskUserQuestion、Agent、Explore、`/` 四条 | +| 10 | memory `src/memdir/memdir.ts:199-266, 419-490` | 约 12 550 | 见 Q5 | +| 11 | `# Environment` `src/constants/prompts.ts:651-710` | 约 810 | cwd、git、平台、shell、OS、模型名,加 549 字符 Claude 专属三行(见 Q4) | +| 12 | `summarize_tool_results` `:841` | 130 | 工具结果可能被清除,重要信息要记下 | +| 13 | git 状态 `src/context.ts:72-103`,`src/utils/api.ts:437-447` | 数百至约 3 000 | status 截断 2 000 字符 + 5 条 log | + +本场景不进入:`language`、`output_style`、`mcp_instructions`(有带 instructions 的 MCP server 时才有)、`scratchpad`、`frc`、token_budget / brief / proactive。 + +合计(不含 git 状态、MCP instructions)约 **26 450 字符**,memory 一段占约 47%。另有: + +- 第一条 user 消息是 `` 包着的 userContext:CLAUDE.md 系列、MEMORY.md、`Today's date is ...`(`src/utils/api.ts:449-472`),固定包装约 250 字符。 +- 代理把所有 system 块用 `\n` 拼成一条 role=system 消息(`src/server/proxy/transform/anthropicToOpenaiChat.ts:19-25`)。 +- 工具描述约 80K(维度 A),ToolSearch 在非 Anthropic base URL 下关闭(`src/utils/toolSearch.ts:270-312`),每次请求全量发送。 + +#### Codex(场景:`codex exec`,自定义 provider,slug 不在内置目录) + +- 内置目录 `models-manager/models.json` 11 个 OpenAI slug;最长前缀匹配与「一级命名空间/后缀」匹配(codex:models-manager/src/manager.rs:888-930),GLM/DeepSeek/Kimi 不会命中,走 `model_info_from_slug`,`instructions_template` 为 `prompt.md` 全文(codex:models-manager/src/model_info.rs:16,98-156)。 +- 前提:rust-v0.164.0 的 `WireApi` 只剩 `Responses`(codex:model-provider-info/src/lib.rs:102,109-113),chat-completions 端点需要外部转换层;prompt 分析与 wire 格式无关。 +- `update_plan` 默认关闭(codex:core/src/config/mod.rs:2791-2796),请求前剔除 `## Planning`(含示例)与 `## update_plan` 两节(codex:core/src/session/mod.rs:1608-1627 → codex:prompts/src/update_plan_instructions.rs:4-30):20 751 → 16 979 字符。 + +| # | 段 | 字符 | 内容 | +|---|---|---|---| +| 1 | 开头身份与能力 `prompt.md:1-9` | 797 | 「Codex CLI 里的 coding agent」;能力三条 | +| 2 | `## Personality` | 404 | 简洁、直接、友好 | +| 3 | `# AGENTS.md spec` | 1 288 | 作用域与优先级;根到 cwd 的内容已随消息给出 | +| 4 | `### Preamble messages` | 1 593 | 工具调用前发 1–2 句前言,8 条示例 | +| 5 | `## Task execution` | 2 414 | 做到解决为止;`apply_patch` 编辑;根因修复;不加行内注释;不 `git commit` | +| 6 | `## Validating your work` | 2 020 | 先窄后宽地跑测试;格式化最多 3 次;按审批模式决定是否主动跑测试 | +| 7 | `## Ambition vs. precision` | 936 | 新项目可发挥,既有代码要精确 | +| 8 | `## Sharing progress updates` | 1 128 | 长任务定期发 8–10 词进度 | +| 9 | `## Presenting your work...` + `### Final answer structure...` | 5 973 | 最终消息长度、标题、列表、等宽、文件引用、语气 | +| 10 | `## Shell commands` | 363 | 优先 `rg`;不用 python 输出大段文件 | +| 11 | 小计:base instructions | **16 979** | 作为 input 首项发送(维度 D:codex:core/src/client.rs:1017-1030) | +| 12 | permissions(developer) | 约 300–500 | `never.md` 120(codex:prompts/templates/permissions/approval_policy/never.md)+ sandbox 模板 177–281 | +| 13 | ``(user) | 约 300 起 | ``、``、``、``,可含 network/filesystem/subagents(codex:core/src/context/world_state/environment.rs:263-330) | +| 14 | AGENTS.md(user) | 视文件,合计上限 32 KiB | 见 Q6 | +| 15 | skills 清单(developer) | 视已装 skill | 回退元数据不带「How to use skills」(codex:ext/skills/src/fragments.rs:20-32) | + +本场景不发:collaboration mode 默认文本(推断,codex:core/src/context/world_state/collaboration_mode.rs:34-66)、multi-agent V2 用法提示(V1 下 `usage_hint_text` 为 None,codex:core/src/session/multi_agents.rs:14-18)、persistent mode(3 376)、memories(6 593,`MemoryTool` 缺省关,codex:features/src/lib.rs:1317-1322)、token budget / context-window guidance(`TokenBudget` 缺省关,codex:core/src/session/world_state.rs:177-201)、model catalog(`ModelCatalogInContext` 缺省关,codex:features/src/lib.rs:1520-1524)。 + +合计约 **17.7K 字符**,加 AGENTS.md 与 skills 条目。 + +#### ZCode(场景:CLI `--prompt`,`openai-chat-completions`,非 GLM 模型) + +`ContextBuilder.build()`(zcode:core/src/context/builder.ts:83-231)产生三类内容:三条 system 消息(CLI 前缀 / 稳定段带缓存标记 / 动态段带缓存标记,`:238-284`)、meta_user 附件(skills、指令文件、git,`:295-321`)、运行时公告(环境、模型、日期,`:287-293` 列为「由运行时宣告」,实际在 zcode:core/src/runtime/methods/context-refresh.ts 里作为 `` 附件写入历史)。只有一套 prompt,不按模型分支;`zcode-cfg:zcode-builtin.json` 的模型规则里没有任何 prompt 文字字段(我遍历了所有含 prompt/instruction/system 的键,只有 `supportsMidConversationSystem`)。 + +`midConversationSystem` 由 `shouldUseMidConversationSystem` 决定(zcode:core/src/runtime/helpers/runtime-provider-request-messages.ts:13-20);缺省模型规则为 false(`zcode-cfg:zcode-builtin.json` 的 `modelRules[0]`),本场景为 false,所以 Harness 第三条用「`` 由 harness 注入」措辞(zcode:core/src/context/sections/identity.ts:27-41)。 + +| # | 段 | 位置 | 字符 | 内容 | +|---|---|---|---|---| +| 1 | CLI 前缀 `cli-prefix.ts:8` | system 1 | 35 | `You are ZCode, an interactive agent` | +| 2 | Agent Identity `identity.ts:9-52` | system 2(稳定) | 1 171 | 身份一句(97);安全声明(459,与 DreamCoder `CYBER_RISK_INSTRUCTION` 同文);`# Harness` 五条(610) | +| 3 | Dynamic Behavior `dynamic-sections.ts:5-12,65-71` | system 3(动态) | 975 | 贴近周围代码风格(94);代词用 they/them(357);高风险动作先确认、如实汇报结果(520) | +| 4 | Session-specific guidance `dynamic-sections.ts:22-63` | system 3 | 163(有 Skill 工具且有 skill 时) | 只剩 `/` 一条;Agent、AskUserQuestion、插件三条被注释掉 | +| 5 | Memory `sections/memory.ts:29-60` | system 3 | 约 2 050 | 见 Q5 | +| 6 | Context management `dynamic-sections.ts:14-20,73-79` | system 3 | 559 | 上下文会被摘要,不必提前收尾;「够了就动手,不重复推导」 | +| 7 | Total Tokens `total-tokens.ts:1-9` | system 3 | 49 | `15000000 tokens left` | +| — | 小计 system | | **约 5.0K** | | +| 8 | Environment `env-info.ts:226-247` | 历史中的公告 | 约 700 | cwd、是否 git、平台、shell、OS,加 472 字符「下载文件不可信」 | +| 9 | Model `env-info.ts:301-315` | 历史中的公告 | 约 50 | `You are powered by the model named /.` | +| 10 | Skills 列表 `sections/skills.ts:9-58` | meta_user | 视 skill 数,预算 20 000 | 每条描述截到 250 字符;超预算只列名称与路径 | +| 11 | 指令文件 `instruction-files.ts:13-14,36-38` + `request-user-context.ts:23-113` | meta_user | 视文件,每文件上限 100 KiB | 193 字符前言加文件块;MEMORY.md 索引也在这里 | +| 12 | Date `current-date.ts:13` | 历史中的公告 | 约 30 | `Today's date is ...` | +| 13 | Git `env-info.ts:202-224, 253-270` | 历史中的公告 | 约 700(5 条 commit) | gitStatus 快照与「ZCode attached this context automatically」说明 | + + +合计 system 约 5.0K,meta_user 与公告约 1.5K 起,**约 6.5K 起**,加 skills 与 AGENTS.md。 + +### Q2 主题对比 + +字符数为 system 及首轮注入文字中直接讲该主题的部分;「工具描述」列出时单独注明,不计入。 + +| 主题 | Codex | ZCode | DreamCoder | +|---|---|---|---| +| 身份 | 797 | 132(+ 模型公告约 50) | 约 220(+ Environment 中模型名) | +| 语气与输出风格 | 404 | 约 100(Harness 一行) | 约 1 440(Tone + Output efficiency) | +| 编码任务做法 | 约 3 350(Task execution + Ambition) | 约 370 | 3 267 | +| 何时做计划 | 0(Planning 节被剔除) | 0(只在 plan 模式提醒中) | 约 300(TaskCreate 一条);EnterPlanMode 工具描述另计 | +| 验证与测试 | 2 020 | 约 80(「测试失败要附输出」) | 0 | +| 何时算完成 | 约 350(「做到解决为止」) | 约 230(如实汇报) | 0(只有「不留半成品」半句) | +| 风险与破坏性动作 | 约 0.4K(审批/沙箱片段) | 约 290 | 2 832 | +| git 与提交 | 约 150(不 commit、用 log/blame) | 0 | system 中 0;Bash 工具描述约 6.2K(提交/PR 流程) | +| 工具使用与并行 | 363(无并行说明) | 约 140 | 1 622 | +| 子 agent 使用 | 0;spawn_agent 描述含角色说明约 1.9K | 约 130(清单后并发说明)+ 清单 | 约 900(Session guidance 中两条)+ Agent 工具描述 | +| 安全政策 | 0 | 459 + 472(下载不可信) | 约 1 100(安全声明、URL、提示注入、OWASP) | +| memory | 0(功能缺省关) | 约 2 050 + MEMORY.md | 约 12 550 + MEMORY.md | +| 环境信息 | 约 300 | 约 750 | 约 810(含 549 Claude 文字)+ git 状态 | +| 最终消息格式 | 5 973 | 0 | 0(只有 Tone/Output efficiency 的一般要求) | +| 进度更新 | 约 2 720(前言 + 进度) | 0(中途静默提醒 139) | 约 100(Output efficiency 一句) | + +各家重点: + +- Codex 独有的大段:最终消息格式(约 6.0K)、前言与进度(约 2.7K)、验证(约 2.0K)、AGENTS.md 规范(1.3K)。另两家在这些主题上为 0 或一两句。 +- DreamCoder 独有的大段:memory(12.5K)、风险动作(2.8K)、工具对照(1.6K)、语气与输出效率(1.4K)、安全政策(1.1K)、Bash 工具里的 git 流程(6.2K)。 +- ZCode 在所有主题上都很短;它独有的是 token 预算行与倒数、代词规则、「不必提前收尾 / 够了就动手」。 +- 三家都很少写「何时做计划」:Codex 在 `update_plan` 关闭时整节删除,ZCode 只在 plan 模式里有,DreamCoder 只有一条 TaskCreate 指引。 + +### Q3 ZCode 相对 DreamCoder:保留、缩短、删除 + +ZCode 的结构与措辞来自 Claude Code 系的 prompt。以下比较以 DreamCoder 2.1.92 为参照。 + +保留(原文或几乎原文): + +| 内容 | ZCode | DreamCoder | +|---|---|---| +| 安全声明 459 字符 | zcode:core/src/context/sections/identity.ts:15-16 | `src/constants/cyberRiskInstruction.ts` | +| 指令文件前言「Codebase and user instructions are shown below...」 | zcode:core/src/context/sections/instruction-files.ts:13-14 | `src/utils/claudemd.ts:93-94` | +| git 状态块(「This is the git status at the start of the conversation...」、`Main branch (you will usually use this for PRs)`) | zcode:core/src/context/sections/env-info.ts:27-30 | `src/context.ts:72-103` | +| Environment 标签(`You have been invoked in the following environment`、`Primary working directory` 等) | env-info.ts:10-20,226-247 | `src/constants/prompts.ts:651-710` | +| skills 清单头与每条 250 字符截断 | zcode:core/src/context/sections/skills.ts:10,41 | `src/tools/SkillTool/prompt.ts:29`,`src/utils/messages.ts:3822-3831` | +| MEMORY.md 200 行 / 25 000 字符截断 | zcode:core/src/memory/index-content.ts:6-7 | `src/memdir/memdir.ts:35,38` | +| memory 四种类型 user/feedback/project/reference | zcode:core/src/context/sections/memory.ts:51 | `src/memdir/memoryTypes.ts` | +| 压缩提示(`NO_TOOLS_PREAMBLE` 379 字符同文、九节摘要结构) | zcode:core/src/compact/prompt.ts:1-110 | `src/services/compact/prompt.ts:19-272` | +| 子 agent general-purpose 正文与 Notes | zcode:core/src/subagent/general-purpose.ts:7-23,system-prompt.ts:6-14 | `src/tools/AgentTool/built-in/generalPurposeAgent.ts:3-24`,`src/constants/prompts.ts:766-770` | +| Explore 子 agent 正文 | zcode:core/src/subagent/explore.ts:20-68 | `src/tools/AgentTool/built-in/exploreAgent.ts:24-` | +| todo 提醒(10 轮/10 轮阈值与措辞) | zcode:core/src/runtime/helpers/runtime-reminders.ts:100-103,260-270 | `src/utils/attachments.ts:251-254`,`src/utils/messages.ts:3774-3793` | +| plan 模式五阶段流程 | runtime-reminders.ts:27-79 | DreamCoder plan_mode 附件(未逐字核对) | + +缩短: + +| DreamCoder 段 | 字符 | ZCode 对应 | 字符 | +|---|---|---|---| +| `# System` | 1 625 | `# Harness` 五条(markdown 输出、权限拒绝、system-reminder 与 hooks、专用工具与并行、`file_path:line_number`) | 610 | +| `# Executing actions with care` | 2 832 | `ACTION_CAUTION_PROMPT` 的前半(先确认、外发即发布、删除前先看) | 约 290 | +| `# Doing tasks` | 3 267 | 「贴近周围代码」94 + 「够了就动手」277 | 约 370 | +| `# Session-specific guidance` | 1 286 | 只剩 `/` | 163 | +| memory 段 | 约 12 550 | memory 段 | 约 2 050 | +| Environment | 约 810 | Environment(去掉 Claude 三行,加下载不可信说明) | 约 700 | + +删除:`# Tone and style`、`# Output efficiency`、`# Using your tools` 的工具对照、Agent / Explore / AskUserQuestion 用法(在 zcode:core/src/context/dynamic-sections.ts:28-55 中被注释掉)、OWASP 条、「不加范围外功能 / 不做一次性抽象」等编码风格条、时间估计、`/help` 与反馈、禁止猜 URL、`summarize_tool_results`、知识截止日期、Claude 模型家族与产品三行、「You are a Claude agent」前缀、Read 工具的恶意软件提醒(zcode 中该字符串只出现在 `core/tests/read-file-state-hydrator.test.ts`)、Bash 工具里的 git 提交 / PR 流程(ZCode 的 core 里只有 Explore 的「不要 git commit」)。 + +ZCode 新增(DreamCoder 的 prompt 文本里没有,`grep` `src/constants`、`src/utils` 无结果):代词 they/them(357);「Report outcomes faithfully」(DreamCoder 中同类条目只在 `USER_TYPE=ant` 时加入,`src/constants/prompts.ts:239-243`);下载文件不可信说明(472);`` 预算行与倒数;「不必提前收尾」「不重复推导、不重议已定决定」;静默轮次提醒;重复调用提醒;`provider/model` 形式的模型公告;指令文件增量公告;memory 文件之间的 `[[name]]` 链接。推断:这些新增段落与较新版本的 Claude Code 文字相近,ZCode 跟随的蓝本比 2.1.92 新;未逐字核对来源。 + +### Q4 发给「错误模型 / 错误产品」的文字 + +#### DreamCoder → 非 Claude 模型 + +system prompt: + +| 位置 | 引文 | 问题 | +|---|---|---| +| `src/constants/system.ts:12` | 「You are a Claude agent, built on Anthropic's Claude Agent SDK.」 | 身份是 Claude | +| `src/constants/prompts.ts:217-218` | 「/help: Get help with using Claude Code」「To give feedback, users should 」 | 指向 Claude Code;`ISSUES_EXPLAINER` 为空串(`preload.ts:19`),句子不完整 | +| `src/constants/prompts.ts:437` | 「use the owner/repo#123 format (e.g. anthropics/claude-code#100)」 | 示例仓库是 Anthropic 的(影响小) | +| `src/constants/prompts.ts:696` | 「The most recent Claude model family is Claude 4.5/4.6. Model IDs — Opus 4.7: 'claude-opus-4-7'...」 | 244 字符,告诉 GLM 等模型 Claude 的模型 ID,并要求构建 AI 应用时默认用 Claude | +| `src/constants/prompts.ts:699` | 「Claude Code is available as a CLI in the terminal, desktop app (Mac/Windows), web app (claude.ai/code)...」 | 144 字符,描述的是 Claude Code 的产品形态 | +| `src/constants/prompts.ts:702` | 「Fast mode for Claude Code uses the same Claude Opus 4.7 model... toggled with /fast.」 | 152 字符,DreamCoder 没有 `/fast`(推断:server 未暴露此命令,未逐一核对) | + +工具描述(本场景发送的工具): + +| 位置 | 引文 | 问题 | +|---|---|---| +| `src/tools/BashTool/prompt.ts:79,107,122,150` + `src/utils/attribution.ts:73-80` | 提交信息末尾写「Co-Authored-By: Claude Opus 4.7 」,PR 末尾写「🤖 Generated with [Claude Code](https://claude.com/claude-code)」 | 非 Claude 模型名查不到时固定回退为「Claude Opus 4.7」(`getPublicModelDisplayName` 只认 Claude 与少数 GPT 名,`src/utils/model/model.ts:377-402`,`src/services/openaiAuth/models.ts:93-108`);server 没有设置 `attribution`/`includeCoAuthoredBy`(`grep src/server` 无结果)。模型会把错误的署名写进用户仓库 | +| `src/tools/FileReadTool/prompt.ts:40` | 「This tool allows Claude Code to read images... as Claude Code is a multimodal LLM.」 | 自称 Claude Code;且代理把工具结果里的图片替换成 `[image omitted: ]`(`src/server/proxy/transform/toolArguments.ts:37-42`),模型实际看不到图 | +| `src/tools/EnterWorktreeTool/prompt.ts:21` | 「creates a new git worktree inside `.claude/worktrees/`」 | 目录名带 Claude(该工具是否在本场景工具集中 未核实) | +| `src/tools/AgentTool/built-in/statuslineSetup.ts:136-137`(经 Agent 工具描述的清单发出,`src/tools/AgentTool/prompt.ts:196-199`) | 「Use this agent to configure the user's Claude Code status line setting.」 | DreamCoder 没有 status line(`src/server/services/claudeCodeImportService.ts:49` 明确不导入 `statusLine`);清单默认在工具描述中,因为 `tengu_agent_list_attach` 默认 false(`src/tools/AgentTool/prompt.ts:59-64`) | + +子 agent prompt(本场景可用的内置 agent:general-purpose、statusline-setup、Explore、Plan、verification;`sdk-cli` 入口下不含 claude-code-guide,`src/tools/AgentTool/builtInAgents.ts:58-79`): + +| 位置 | 引文 | +|---|---| +| `src/tools/AgentTool/built-in/generalPurposeAgent.ts:3` | 「You are an agent for Claude Code, Anthropic's official CLI for Claude.」 | +| `src/tools/AgentTool/built-in/exploreAgent.ts:24` | 「You are a file search specialist for Claude Code, Anthropic's official CLI for Claude.」 | +| `src/tools/AgentTool/built-in/planAgent.ts:21` | 「You are a software architect and planning specialist for Claude Code.」 | +| `src/tools/AgentTool/built-in/statuslineSetup.ts:3` | 「You are a status line setup agent for Claude Code... the user's Claude Code settings.」 | + +中途注入:Read 结果后的恶意软件提醒对所有非 `claude-opus-4-7` 模型都追加(`src/tools/FileReadTool/FileReadTool.ts:697-699,727-736`)。它本身不提 Claude,但豁免名单只按 Claude 模型名设计。 + +其他:`CLAUDE.md` 名称在 memory 段与 userContext 中出现,这是 DreamCoder 实际读取的文件,不算错误产品。 + +#### Codex → 非 OpenAI 模型 + +| 位置 | 引文 | 问题 | +|---|---|---| +| codex:models-manager/prompt.md:1 | 「Codex CLI is an open source project led by OpenAI.」 | 产品身份,不涉及模型身份;影响小 | +| codex:models-manager/prompt.md:9 | 「not the old Codex language model built by OpenAI」 | 同上 | +| codex:models-manager/prompt.md:132,143(剔除后仍在) | 「Use the `apply_patch` tool to edit files... {"command":["apply_patch",...]}」 | 回退元数据 `apply_patch_tool_type=None`,不声明 apply_patch 工具;文中给的是 shell 命令形式,靠对 shell 调用的拦截生效(见 [loop-execution.md](loop-execution.md)) | +| codex:models-manager/prompt.md:7 | 「More on this in the "Sandbox and approvals" section.」 | `prompt.md` 中没有这一节(`grep -c` 只有这一处引用);审批与沙箱信息由 permissions 片段提供(推断) | +| codex:core/src/tools/handlers/multi_agents_spec.rs:71-75,822-870 | spawn_agent 描述列出「picker 可见」的模型及其 reasoning effort | 自定义 provider 下 `available_models` 来自哪份目录 未核实;若用内置目录(codex:models-manager/src/manager.rs:864-866),会向 GLM 列出 6 个 `visibility: list` 的 gpt-* 名称 | + +没有找到向非 OpenAI 模型声称「你是 GPT」或列出 OpenAI 模型 ID 的 system 文字。 + +#### ZCode → 非 GLM 模型 + +- 没有 GLM、智谱、Z.ai 字样;模型公告用真实的 `provider/model`(zcode:core/src/context/sections/env-info.ts:301-315)。 +- zcode:core/src/context/sections/memory.ts:59:「Don't save what the repo already records (code structure, past fixes, git history, CLAUDE.md)」。ZCode 读的是 `AGENTS.md`(zcode:adapters/src/context/index.ts:26),这里写错了文件名。 +- `Task` 别名工具描述写着「Claude Code-compatible alias for the Agent tool」(zcode:core/src/tool/handlers/agent.ts:332-346),但 `providerVisible: false`,不发给模型。 + +### Q5 memory 段 + +| | Codex | ZCode | DreamCoder | +|---|---|---|---| +| 本场景是否发送 | 否(`MemoryTool` 缺省关) | 是(`features.memory` 缺省 true) | 是 | +| 大小 | 读路径 6 593(关闭时不发) | 约 2 050 | 约 12 550 | +| 位置 | — | system 动态段 | system(边界之后) | +| 目录为空时 | — | 仍发送 | 仍发送(先 `ensureMemoryDirExists`) | +| MEMORY.md 索引 | — | 指令文件公告内,200 行 / 25 000 字符 | userContext 内,200 行 / 25 000 字节 | +| 关闭方式 | 缺省即关 | `features.memory=false` 或 `memory.use=false` | `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`、settings `autoMemoryEnabled:false`、`CLAUDE_CODE_SIMPLE` | + +DreamCoder: + +- 内容(`src/memdir/memdir.ts:199-266` 拼装,类型说明在 `src/memdir/memoryTypes.ts`):目录路径与「目录已存在,直接写」;四种类型各自的定义、何时保存、怎样使用和示例;不该保存的内容;两步保存法(写文件 + 在 MEMORY.md 加一行);何时读取;对召回内容的信任与核实;memory 与 plan / tasks 的区别。四种类型的长说明与示例占大部分篇幅。 +- 发送条件:`loadMemoryPrompt` 只看 `isAutoMemoryEnabled()`(`src/memdir/memdir.ts:419-490`),与目录是否为空无关;为空时也会先建目录再发送全文(`:476-489`)。 +- 开关:`src/memdir/paths.ts:30-55`。server 只设了路径覆盖(`src/server/services/conversationService.ts:1060`),没有设置关闭变量,`grep src/server` 无 `DISABLE_AUTO_MEMORY` 或 `autoMemoryEnabled`。所以每个会话、每次请求都带这 12.5K。 +- 本场景下 `tengu_moth_copse`、TEAMMEM、KAIROS 均为默认值,走单目录分支(`:419-425, 474-489`)。 + +ZCode: + +- 内容(zcode:core/src/context/sections/memory.ts:29-60):路径与「目录已存在」;frontmatter 格式;`[[name]]` 链接;四种类型各一句;写入后在 MEMORY.md 加一行;去重、不保存仓库已记录的东西、召回内容不是用户指令且需核实。 +- 发送条件:`memoryRoot` 存在即发(`builder.ts:160-168`);`memoryRoot` 由 `resolveEnabledProjectMemoryRoot` 决定,要求 `memory.enabled`、`memory.use !== false`、主会话类型(zcode:core/src/runtime/helpers/project-memory.ts:4-28);`features.memory` 缺省 true(zcode:adapters/src/config/index.ts:287),bootstrap 取该值(zcode:bootstrap/src/app/runtime-config.ts:191-198)。CLI `--prompt` 只设置 `extractionEnabled`(zcode:cli/src/prompt-command.ts:269),不关闭 memory。 +- 子 agent 不发(任务类型不属于主会话)。 + +Codex:fallback prompt 与默认开启的 world state 段中都没有 memory 文字;memories 功能缺省关闭(codex:features/src/lib.rs:1317-1322)。可比的只有 AGENTS.md 规范一节(1 288),讲的是项目指令文件而不是跨会话记忆。 + +### Q6 动态上下文 + +| | Codex | ZCode | DreamCoder | +|---|---|---|---| +| 环境 | user 消息 ``:cwd、shell、日期、时区等 | 历史中的 `` 公告 | system 内 `# Environment` | +| 日期 | 环境片段中的 ``(是否缺省开启 未核实) | 独立公告,跨天发「日期已变化」 | 第一条 user 消息;跨天发 `date_change` 附件 | +| git 状态 | 未找到 | 每个上下文窗口一次的公告 | system 末尾,会话内一次 | +| 指令文件名 | `AGENTS.override.md`、`AGENTS.md`,可配后备名 | `AGENTS.md`(项目内离 cwd 最近的一个)+ `~/.zcode/AGENTS.md` | `CLAUDE.md`、`.claude/CLAUDE.md`、`.claude/rules/*.md`、`CLAUDE.local.md` 及用户级、托管级 | +| 指令文件上限 | 合计 32 KiB | 每个文件 100 KiB | 不截断;40 000 字符只是告警阈值 | +| skills 清单 | developer 片段 | meta_user,预算 20 000 字符 | 第一轮 `skill_listing` 附件,预算为窗口的 1%×4 字符(200K 窗口时 8 000) | +| 子 agent 清单 | spawn_agent 工具描述 | 历史中的增量公告 | Agent 工具描述 | +| MCP instructions | 未核实 | 未核实 | system 内,每轮重算 | +| 送达方式 | 每步按 world state 与上次快照的差异追加 | 写入历史,只追加变化 | 会话内各算一次 | + +DreamCoder: + +- 指令文件:`src/utils/claudemd.ts:6-16, 835-990` 列出读取的文件,全部是 `CLAUDE.md` 系列。整个 `src` 下只有 `src/commands/init.ts` 提到 `AGENTS.md`。**确认 CLI 不读 `AGENTS.md`。** `MAX_MEMORY_CHARACTER_COUNT = 40000`(`src/utils/claudemd.ts:96`)只用于 doctor 与状态提示(`src/utils/doctorContextWarnings.ts:57-66`),不截断内容。 +- 送达:gitStatus 与 userContext 都 `memoize`,会话内只算一次(`src/context.ts:116,155`)。gitStatus 拼在 system 末尾(`src/utils/api.ts:437-447`),userContext 作为第一条 user 消息(`src/utils/api.ts:449-472`)。system 动态段按名字缓存,`/compact` 时清除(维度 C,`src/constants/systemPromptSections.ts:20-62`)。会话中途修改根目录 CLAUDE.md 不会送达,直到压缩;读取子目录文件时可能通过 `nested_memory` 附件补发该目录的 CLAUDE.md(`src/utils/attachments.ts` 中的 `nested_memory`)。 +- skills 清单:`src/tools/SkillTool/prompt.ts:21-40`;渲染见 `src/utils/messages.ts:3822-3831`。 + +Codex: + +- `AGENTS.md`:从项目根(向上找 `.git`)到 cwd 逐层收集并拼接,每层优先 `AGENTS.override.md`(codex:core/src/agents_md.rs:1-18, 43-45, 272-290);合计上限 `project_doc_max_bytes`,缺省 32 KiB(codex:core/src/config/mod.rs:255,4528);以 user 消息 `# AGENTS.md instructions for ` + `` 发送(codex:core/src/context/user_instructions.rs:31-41)。 +- 送达:每个采样步骤重建 world state,各段与历史中的上一份快照比较,只把差异作为新片段追加(codex:core/src/session/world_state.rs:163-400;差异接口 codex:core/src/context/world_state/mod.rs 中的 `render_diff`)。AGENTS.md 也是一个 world state 段(world_state.rs:218)。 + +ZCode: + +- 指令文件:在 cwd 到项目根之间找离 cwd 最近的 `AGENTS.md`,加用户级 `~/.zcode/AGENTS.md`;每个文件上限 100 KiB(zcode:adapters/src/context/index.ts:26-27, 123-157, 236-271)。完整公告只发一次;启动时或压缩后重读,内容变化时追加增量公告「Instruction files were re-read...」(zcode:core/src/runtime/methods/context-refresh.ts:362-474,zcode:core/src/context/sections/instruction-files.ts:44-55)。 +- 环境、模型、output style:每次输入附件收集时与历史中最近一次公告比较,只发变化的行(context-refresh.ts:96-158;env-info.ts:125-175)。 +- git:每个窗口(会话开始或压缩后)决定一次(context-refresh.ts:570-634)。 +- skills:只发一次;冷恢复时原位更新(context-refresh.ts:296-336)。 + +### Q7 中途提醒 + +DreamCoder(附件列表 `src/utils/attachments.ts:740-985`;渲染在 `src/utils/messages.ts`): + +| 种类 | 触发 | 大小 | 本场景 | +|---|---|---|---| +| Read 恶意软件提醒 | 每次 Read 返回文本内容,模型不是 `claude-opus-4-7`(`src/tools/FileReadTool/FileReadTool.ts:697-699,727-736`) | 340 | 是,每次 Read | +| `task_reminder` | 距上次 TaskCreate/TaskUpdate ≥10 个 assistant 轮,且距上次提醒 ≥10 轮(`src/utils/attachments.ts:251-254, 3359-3412`) | 480 + 任务列表 | 是 | +| `edited_text_file`(changed_files) | 读过的文件被 Edit/Write 以外的方式改动(如 Bash、格式化器) | 302 + diff 片段 | 是,视任务 | +| `nested_memory` | 读到含 CLAUDE.md 的子目录中的文件 | 视文件 | 视仓库 | +| `skill_listing` | 第一轮,及新增 skill 时 | 视 skill 数,预算约 8 000 | 第一轮 | +| `queued_command` / 任务通知 | 后台 agent 或后台命令结束 | 视内容 | 用后台任务时 | +| `date_change` | 跨天 | 约 100 | 很少 | +| 空文件 / offset 越界提示 | Read 结果为空或越界(FileReadTool.ts:700-705) | 约 100 | 偶发 | +| 不触发 | `token_usage`(需环境变量,:3791-3796)、`output_token_usage`(需 `feature('TOKEN_BUDGET')`)、`verify_plan_reminder`(仅 ant)、`deferred_tools_delta`(ToolSearch 关)、`agent_listing_delta`(GrowthBook 默认 false)、`compaction_reminder` / `context_efficiency` / `auto_mode`(feature)、`budget_usd`(未设置预算)、teammate 系列(需 agent teams 开关,`src/utils/agentSwarmsEnabled.ts:24-36`) | — | 否 | + +ZCode(输入附件收集:回合首个请求、每个完整工具批之后、文本回复后续的 guide;zcode:core/src/runtime/methods/turn-loop.ts:284-411): + +| 种类 | 触发 | 大小 | 本场景 | +|---|---|---|---| +| `total_tokens_reminder` | 每个工具批之后;用户输入时重新起算(zcode:core/src/runtime/helpers/total-tokens-budget.ts:53-67;turn-loop.ts:416-447) | 约 45 | 是,每批 | +| 静默轮次提醒 | 连续 ≥5 次模型回应没有可见文字,每段最多 3 次(runtime-reminders.ts:105-161;turn-loop.ts:363-375) | 139 | 是 | +| 重复调用提醒 | 连续 3 次相同工具名与输入,每回合最多 3 次(zcode:core/src/runtime/helpers/model-anomaly.ts:28-29;维度 E) | 约 150 | 是,异常时 | +| todo 提醒 | 有 TodoWrite,距上次 TodoWrite 与上次提醒各 ≥10 轮(runtime-reminders.ts:100-103, 252-270) | 384 + 列表 | 是 | +| 环境 / 模型 / output style / 日期公告 | 内容变化时 | 每条数十至数百 | 首轮各一次,之后很少 | +| 指令文件增量 | 压缩后重读且有变化 | 视文件 | 压缩后 | +| skills / agent 清单 | 首轮一次,之后只发增量 | 视数量 | 首轮 | +| output style 提醒 | 每次收集都发(turn-loop.ts:379-397) | 约 80 | 仅设置了 output style 时 | +| plan 模式提醒 | plan 模式,每 5 个用户轮一次,每第 5 次为完整版 | 完整约 4 000,简版约 300 | 否 | +| Dream memory 更新、UserPromptSubmit hook 上下文、上次运行中断的后台 agent 通知 | 各自事件 | 视内容 | 一般否 | +| 不触发 | ToolSearch 公告(`--toolsearch-mode` 缺省 `off`,zcode:cli/src/run.ts:446;zcode:core/src/tool/search/exposure.ts:18-35) | — | 否 | + +Codex: + +| 种类 | 触发 | 本场景 | +|---|---|---| +| world state 差异(环境、AGENTS.md、权限等) | 每步比较,变化时追加 | 一般只有首轮 | +| `` | V1 子 agent 状态变为最终状态(codex:core/src/context/subagent_notification.rs) | 用子 agent 时 | +| ``、`` | 中断、换模型 | 否 | +| token budget、context-window guidance、current time | 需 `TokenBudget` 等开发中特性(codex:core/src/session/world_state.rs:177-201) | 否 | + +未找到 Codex 在本场景对重复调用、静默、todo 一类的提醒。各片段字符数 未核实(都很短)。 + +### Q8 子 agent 与压缩提示 + +子 agent: + +| | Codex | ZCode | DreamCoder | +|---|---|---|---| +| system 正文 | 复用父会话 base instructions(约 17K)(codex:core/src/agent/child_config.rs:59,111-120) | CLI 前缀 35 + agent 正文 + 启动方消息说明 353 + Notes 约 770 + token 行 49 | agent 正文 + Notes 630 + `` 段约 400(`src/constants/prompts.ts:760-791`) | +| 内置类型与正文大小 | default、explorer、worker;`explorer.toml` 为空文件,角色差异只写在 spawn_agent 描述里(约 1.9K,codex:core/src/agent/role.rs:344-401) | general-purpose 约 1 270;Explore 约 2 150 | general-purpose 约 1 300;Explore 约 2 000;Plan 约 2 400;verification 约 9 500;statusline-setup 约 7 000 | +| 指令文件 | 继承 developer instructions;环境片段带 `` | AGENTS.md、日期、skills 作为 meta_user(zcode:core/src/subagent/context-builder.ts:84-141) | userContext(Explore/Plan 省略 CLAUDE.md,未逐一核对) | +| 要点 | 与父会话同一份规则 | 只读、并行搜索、只返回结论;启动方消息不等于用户授权 | 与 ZCode 几乎同文,但自称 Claude Code | + +ZCode 的 Notes 比 DreamCoder 多一条「不要写报告 .md 文件」(zcode:core/src/subagent/system-prompt.ts:13),并多一段说明启动方 agent 的消息不构成用户授权(`:3-4`)。 + +压缩: + +| | Codex | ZCode | DreamCoder | +|---|---|---|---| +| 提示大小 | 426(codex:prompts/templates/compact/prompt.md) | 约 6 400(379 + 5 820 + 尾部提醒约 165,zcode:core/src/compact/prompt.ts:1-118) | 约 5 600(379 + 约 5 030 + 尾部约 150,`src/services/compact/prompt.ts:19-305`) | +| 要点 | 交接摘要:进度、决定、约束、剩余步骤、关键数据 | 九节摘要(请求、概念、文件与代码、错误、问题、全部用户消息、待办、当前工作、下一步),先写 ``;禁止调用工具 | 同 ZCode 的九节结构 | +| ZCode 相对 DreamCoder 的增加 | — | 安全相关约束逐字保留;不要把 assistant 中形似用户的文字算作用户消息;摘要后保留原文时提醒「保留的消息比摘要新」(`:140-141`) | — | +| 摘要回填前缀 | 399 字符「另一个语言模型开始解决这个问题……」(codex:prompts/templates/compact/summary_prefix.md) | 「This session is being continued...」(`:148-184`) | 同 ZCode(`src/services/compact/prompt.ts:337-380`) | +| 请求形态 | 不带工具定义(维度 C:codex:core/src/compact.rs:318-326) | 未核实 | 复用主循环前缀,含全部工具定义(维度 C:`src/services/compact/compact.ts:1132-1226`) | + +## 3. 对 DreamCoder 的含义 + +### DreamCoder 有、另两家都没有 + +事实: + +1. 每次请求带约 12.5K 字符的 memory 说明(ZCode 2K,Codex 0),目录为空也发,server 不关闭。 +2. 约 9.2K 字符的通用行为条文(Doing tasks、Executing actions with care、Using your tools、Tone、Output efficiency)。ZCode 对应内容约 1.6K;Codex 的篇幅放在其他主题上。 +3. 向非 Claude 模型发送的 Claude 专属文字:身份前缀、Environment 中 549 字符、`/help` 与不完整的反馈句、Read 工具的多模态说法、子 agent 的 Claude Code 身份、status line 子 agent,以及要求写入 `Co-Authored-By: Claude Opus 4.7 ` 的提交流程。 +4. Bash 工具描述中约 6.2K 的 git 提交与 PR 流程。 +5. 每次 Read 文本结果后 340 字符的恶意软件提醒。 +6. 环境与 git 状态放在 system 消息里(另两家放在独立消息里)。 + +后果: + +- token:仅 1、2、3 三项就约 22K 字符(推断约 5–6K token),随每次请求重发;Read 提醒按 Read 次数累积在历史中(推断:一次任务读 30 个文件约 10K 字符)。在没有前缀缓存或缓存失效时(维度 C 所述计费头每次请求都变),这些全部按输入计费。 +- 可靠性:第 3 项会让第三方模型在提交信息中写入错误的署名,或在被问到身份、模型、`/fast`、`/help` 时给出错误回答(推断,未做运行验证)。Read 工具声称能看图而代理丢图,模型可能据此对图片内容作出无依据的描述(推断)。 +- 第 6 项:环境和 git 放在 system 里本身不增加轮数;代价在于它们与 memory 等动态段相邻,任何一段变化都会使其后的缓存前缀失效(推断,细节见维度 C)。 + +### 另两家都有、DreamCoder 没有 + +事实: + +1. 读取 `AGENTS.md`(Codex 与 ZCode 都读;DreamCoder 只读 `CLAUDE.md` 系列)。 +2. 动态上下文以独立消息写入历史,变化时只追加差异(Codex world state、ZCode 公告)。DreamCoder 会话内各算一次,只有日期跨天、子目录 CLAUDE.md 等少数附件会补发。 +3. 关于「结果如实 / 验证」的明文:Codex 有 2K 的验证一节和「做到解决为止」;ZCode 有「测试失败要附输出、跳过的步骤要说明」。DreamCoder 外部构建中这类条目只在 `USER_TYPE=ant` 时加入(`src/constants/prompts.ts:205-213, 239-243`)。 +4. 没有向第三方模型发送其他厂商的模型身份或模型 ID。 + +后果: + +- 第 1 项:仓库里只有 `AGENTS.md` 时(benchmark 与很多开源仓库属于这种情况,DreamCoder 自己的仓库也是),DreamCoder 的模型看不到项目指令,可能多走探索轮次或违反项目约定(推断)。 +- 第 2 项:本场景是单次 headless 任务,环境基本不变,对 token 影响小;差异主要在压缩和会话恢复之后(推断)。 +- 第 3 项:在以通过测试为标准的任务上,缺少「完成前先验证」的明文,可能使模型更早结束回合(推断;benchmark 中 DreamCoder 的通过率差距在噪声范围内,无法据此确认)。 + +## 4. 没有核实的地方 + +- DreamCoder 传给 CLI 的 `--model` 值是否就是上游模型 ID(决定 Environment 中「You are powered by the model ...」一行的内容):未核实。 +- DreamCoder 本场景实际发送的工具里是否有 EnterWorktree:未核实(以维度 A 为准)。 +- DreamCoder `/fast` 在 DreamCoder 中不可用:推断,未逐一核对命令表。 +- Codex 自定义 provider 下 `available_models` 来自内置目录还是 provider 的 `/models`,以及 spawn_agent 描述是否因此列出 gpt-* 名称:未核实。 +- Codex `` 是否缺省发送(`include_environment_context_time` 的缺省值):未核实。 +- Codex MCP 服务器 instructions 的送达方式、ZCode MCP instructions 的送达方式:未核实。 +- Codex skills 清单的预算与条目格式:未核实。 +- Codex 各中途片段的字符数:未核实。 +- ZCode 压缩请求是否带工具定义:未核实。 +- ZCode 的 TodoWrite 是否在本场景 24 个默认工具中(决定 todo 提醒是否会触发):未核实(以维度 A 为准)。 +- ZCode 新增段落与较新版本 Claude Code 文字的对应关系:推断,未逐字核对。 +- DreamCoder plan 模式附件与 ZCode 五阶段流程是否逐字相同:未逐字核对。 +- DreamCoder Explore/Plan 子 agent 是否省略 CLAUDE.md:未逐一核对。 diff --git a/docs/features/harness/comparison/request-cache.md b/docs/features/harness/comparison/request-cache.md new file mode 100644 index 00000000..a228440c --- /dev/null +++ b/docs/features/harness/comparison/request-cache.md @@ -0,0 +1,253 @@ +# C 维度:请求形态、前缀稳定性、提示缓存、上下文增长与压缩 + +场景见 [README](../README.md#对比的场景):第三方非原生模型,经 OpenAI 兼容端点。路径前缀:`codex:` 相对 `refs/coding-agents/codex/codex-rs`;`zcode:` 相对 `refs/coding-agents/zcode/apps/zcode-cli/packages`;DreamCoder 相对仓库根。ZCode 的模型规则文件和补丁不在 packages 下,写全路径 `refs/coding-agents/zcode/...`。 + +范围修正(A、D 维度也已记录):Codex rust-v0.164.0 已删除 chat completions,`WireApi` 只剩 `Responses`,`wire_api = "chat"` 直接报错(`codex:model-provider-info/src/lib.rs:102,109-113`)。所以 Codex 在本场景只能对第三方端点发 `/v1/responses` 请求;下文 Codex 一列都按 Responses 格式写。 + +## 1. 结论 + +1. **DreamCoder 在本场景拿不到任何 provider 侧前缀缓存。** 代理给每个请求的 system 开头补一行计费头,其中 `cch=` 后 5 位是对整个请求体(含全部历史)的哈希,位于 system 消息第 79–83 个字符;每个请求都不同,其后的 system、工具定义、历史全部无法命中。`openai_chat` 和 `openai_responses` 两种上游格式都这样;只有 `anthropic` 格式的第三方端点不经代理、对非 Claude 模型名不加这行。另外两家第一字节起逐请求相同。 +2. **除这一行外,DreamCoder 的前缀本身相当稳定**:system 各段会话内缓存、日期和 git 状态会话内只算一次、工具按名字排序且 schema 按会话缓存、提醒类内容作为新消息追加。这些继承自 Claude Code 的稳定性设计被计费头一行全部抵消。 +3. **缓存控制字段**:Codex 发 `prompt_cache_key`(线程 id)、`session-id` 等头,并有测试断言第 N 次请求是第 N+1 次的严格前缀;ZCode 在消息上标 Anthropic 式 ephemeral 断点并发 `x-session-id`,但 chat-completions 路径上这些断点按 SDK 行为不会进入请求体(推断);DreamCoder 的 CLI 发 `cache_control` 和 `prompt-caching-scope`,代理全部丢弃,上游请求只有 `Content-Type` 和 `Authorization` 两个头。 +4. **每请求固定开销**(system + 工具定义 + 固定上下文):DreamCoder 约 12 万字符,Codex 约 4.6 万,ZCode 约 2.7 万(ZCode 工具部分为推断)。DreamCoder 的大头是工具描述(约 9–10 万字符,推断)和 memory 段(约 1.25 万)。没有缓存时这部分每个请求按全价计费。 +5. **上下文窗口**:DreamCoder 对内置表以外的模型(GLM-5.3、Kimi-K3、DeepSeek-V4.1 都不在表里)回落到 200,000,除非服务端从 `/v1/models` 回填到环境变量;ZCode 内置规则对任何模型默认 1,000,000,并对 glm-5.3、kimi-k3 有专门条目;Codex 回退元数据 272,000。 +6. **旧工具结果的清理**:三家在本场景下都没有生效的「清除旧工具结果」机制(DreamCoder 各 microcompact 变体都被 GrowthBook 默认值或 `feature()` 关掉;ZCode 的 microcompact 默认 `enabled` 不为 true;Codex 未找到)。差别在单条结果的上限:Codex 写入历史时统一中间截断到约 12,000 字节;ZCode 默认 100KB、Bash 30KB 并落盘;DreamCoder 默认 50,000 字符、Bash 30,000、Read 25,000 token,超限落盘只留 2KB 预览。 +7. **压缩请求本身的代价**:DreamCoder 用 fork 把主循环的 system、全部工具和完整历史原样重发再加一条压缩提示,本意是复用缓存,但在本场景因计费头无法命中,整份按全价;ZCode 同样带主循环工具(为了命中缓存),但只发需要摘要的部分,最近一轮保留不发,输出上限 20K;Codex 不带工具,只发历史和 426 字符的压缩提示。 +8. **主循环以外的模型请求**:DreamCoder 有服务端标题生成(第 1、3 条用户消息各一次)、WebFetch 每次一次二次处理请求、子代理;ZCode 无头模式下没有标题生成,WebFetch 二次处理和子代理与 DreamCoder 同类;Codex 默认没有这类请求。 + +## 2. 逐项对比 + +### Q1 第 N 轮的请求布局 + +| | Codex | ZCode | DreamCoder(CLI → 代理 → 上游) | +|---|---|---|---| +| 接口 | `/v1/responses` | `/chat/completions`(`@ai-sdk/openai-compatible`) | CLI 发 `/v1/messages` 到本地代理;代理发 `/v1/chat/completions` | +| 系统提示位置 | `input[0]`,developer 角色;无 `instructions` 字段 | 开头 1 条 system(3 段合并) | 1 条 system(所有块用 `\n` 拼接) | +| system 首行 | `prompt.md` 正文 | `You are ZCode, an interactive agent` | 计费头 `x-anthropic-billing-header: …cch=xxxxx;` | +| 固定上下文 | developer 消息(权限等)+ user 消息(环境、AGENTS.md) | meta user 消息:skills 列表、指令文件、环境、模型、日期、git | 第一条 user 消息 ``:CLAUDE.md、MEMORY.md、日期;git 状态在 system 末尾 | +| 工具 | 请求体 `tools` 字段,在 `input` 之后 | `tools` 字段 | `tools` 字段,在 `messages` 之后 | +| 历史之后 | 世界状态变化项追加在末尾 | 公告与提醒追加在末尾 | 附件(提醒、skill_listing 等)作为 user 消息追加 | + +**DreamCoder CLI 侧**(`/v1/messages` 请求体): +- system 数组顺序:[计费头(环境变量允许时)][身份前缀句][`getSystemPrompt()` 各段][git 状态],`src/services/api/claude.ts:1394-1404`,git 状态由 `appendSystemContext` 追加(`src/utils/api.ts:437-447`,`src/query.ts:451`)。`--print` 下前缀句为 `You are a Claude agent, built on Anthropic's Claude Agent SDK.`(`src/constants/system.ts:30-46`)。 +- 本场景模型名不以 `claude` 开头,服务端给 CLI 设 `CLAUDE_CODE_ATTRIBUTION_HEADER=0`(`src/server/services/attributionHeaderPolicy.ts:3-15`,注入 `src/server/services/providerRuntimeEnv.ts:251`),CLI 不加计费头(`src/constants/system.ts:52-57`)。 +- 自定义 `ANTHROPIC_BASE_URL` 仍被判为 `firstParty`(`src/utils/model/providers.ts:12-23`),所以 `shouldUseGlobalCacheScope()` 为真(`src/utils/betas.ts:228-233`):静态段标 `cache_control: {type:'ephemeral', scope:'global'}`,请求带 `prompt-caching-scope` beta(`src/services/api/claude.ts:1264-1268`,分块 `src/utils/api.ts:331-376`)。 +- 静态段:intro、System、Doing tasks、Actions、Using your tools、Tone、Output efficiency(`src/constants/prompts.ts:560-572`)。动态段:session_guidance、memory、env_info_simple、language、output_style、mcp_instructions、scratchpad、frc、summarize_tool_results(`src/constants/prompts.ts:491-558`)。 +- 第一条 user 消息是 `prependUserContext` 插入的 ``,内容为 claudeMd(含 MEMORY.md)和 `Today's date is …`(`src/utils/api.ts:449-472`,`src/query.ts:661`)。 + +**代理改写后(openai_chat)**: +- 代理先 `ensureClaudeCodeAttribution`:system 里没有计费头就在最前插入一块(`src/server/proxy/handler.ts:64`,`src/server/proxy/claudeCodeAttribution.ts:29-47`)。 +- 转换:system 块 `map(b => b.text).join('\n')` 成一条 system 消息,`cache_control` 丢弃(`src/server/proxy/transform/anthropicToOpenaiChat.ts:19-26`);工具转 `{type:'function', function:{name, description, parameters}}`,过滤 `BatchTool`(`:47-58`);顶层只拷 `model, messages, stream, stream_options, temperature, top_p, stop, tools, tool_choice, reasoning_effort`(DeepSeek 兼容时加 `thinking`)(`:32-76`)。 +- `JSON.stringify` 后对 system 消息签 `cch`(`src/server/upstream/client.ts:205-216`)。请求头只有 `Content-Type`、`Authorization`(`:213`)。 +- 工具结果:`tool_result` 转 `role:'tool'` 消息(`anthropicToOpenaiChat.ts:114-120`);工具结果里的图片被替换成文字 `[image omitted: ]`(`src/server/proxy/transform/toolArguments.ts:40-42`)。 + +**Codex**: +- 请求体字段顺序 `model, stream, service_tier, input, tools, tool_choice, parallel_tool_calls, reasoning, store, stream_options, include, prompt_cache_key, text, client_metadata`(`codex:codex-api/src/common.rs:279-304`)。 +- `base_instructions` 作为 developer 角色消息插在 `input` 最前,消息 id 由线程 id 与文本做 UUIDv5(`codex:core/src/client.rs:1031-1041`,`codex:core/src/context/base_instructions.rs:31`)。非 OpenAI provider 清掉 `encrypted_content` 与元数据,`store:false`(`codex:core/src/client.rs:1048-1075`)。 +- 之后是初始上下文(`codex:core/src/session/mod.rs:4552-4780`):developer 消息(权限、沙箱、审批说明等),user 消息(``:cwd、shell、`current_date`、`timezone`;AGENTS.md,总量上限 32 KiB,`codex:config/src/config_toml.rs:75`),然后是历史。 + +**ZCode**: +- `ContextBuilder` 产出三条 system:CLI 前缀;稳定段(Agent Identity,带 ephemeral 标记);动态段(Dynamic Behavior、session guidance、Memory、Context management、`` 固定行,带 ephemeral 标记)(`zcode:core/src/context/builder.ts:103-176,238-285`)。 +- chat-completions 适配层把开头连续的 system 合并为一条(`zcode:adapters/src/model/system-message-compat.ts:6-36`,调用 `zcode:adapters/src/model/transform.ts:54`)。 +- 环境、模型、日期、git、skills 列表、指令文件(AGENTS.md 等与 MEMORY.md 索引)作为 meta user 附件或「请求前公告」写入历史(`zcode:core/src/context/builder.ts:288-321`,`zcode:core/src/runtime/methods/context-refresh.ts:348-410`)。 +- 本场景 `midConversationSystem` 为假,提醒都作为 user 消息里的 `` 发送(`zcode:core/src/runtime/helpers/runtime-provider-request-messages.ts:13-20`;默认规则 `supportsMidConversationSystem:false`,`refs/coding-agents/zcode/config/provider/zcode-builtin.json` 的 `modelRules[0]`)。 +- 请求头加 `x-request-id`、`x-session-id`、`x-zcode-trace-id`、`x-query-id`、`x-zcode-session-type` 等(`zcode:adapters/src/model/runner-attribution.ts:20-66`,用于所有 provider:`zcode:adapters/src/model/runner-options.ts:150-154`)。 + +### Q2 第 N 轮与第 N+1 轮开头可能不同的地方 + +| 项 | Codex | ZCode | DreamCoder | +|---|---|---|---| +| system 第一行 | 不变 | 不变 | **每请求变**(`cch`) | +| system 正文 | 不变(UUIDv5 id 固定) | 会话内快照,不变 | 不变(段缓存),MCP 说明段每轮重算 | +| 日期 | 变化时末尾追加 | 变化时末尾追加 | 会话内 memoize;跨天追加 `date_change` 附件 | +| git 状态 | 未找到注入(未核实) | 公告,按来源去重追加 | 会话开始快照,不变 | +| 指令文件 / 记忆 | 初始上下文固定 | 发出后不改写,变化追加增量 | memory 段会话内缓存;CLAUDE.md 在首条 user 消息,memoize | +| skills 列表 | developer 片段 | 写一次;冷恢复时原位改写一次 | 附件,写一次,新增按增量追加 | +| 工具顺序 | 固定(有测试) | 名单内按名字排序(固定 en-US),MCP 排最后 | 内置按名字排序,MCP 排最后 | +| 中途出现的工具 | 未核实 | MCP 工具按当前注册表发送,会变 | MCP 工具连上后追加在工具列表末尾 | + +**DreamCoder 的 `cch` 行**。依据下面四个文件(两次独立阅读,结论一致): +- 代理补头不看模型名也不看环境变量,只检查 system 里是否已有以 `x-anthropic-billing-header:` 开头的块(`src/server/proxy/claudeCodeAttribution.ts:29-30,49-57`);入口取代理进程的 `CLAUDE_CODE_ENTRYPOINT`,未设时为 `unknown`(`:37`)。B 维度记录的 `sdk-cli` 是 CLI 进程里的值(`src/main.tsx:532`),代理在服务端进程里读,取不到(推断:服务端进程未设该变量)。 +- 指纹 = `SHA-256(盐 + 首条 user 文本的第 4、7、20 个字符 + 版本)` 前 3 位(`src/utils/fingerprint.ts:56-69`)。首条 user 消息总是 `\nAs you answer…`,这三个字符固定为 `t`、`-`、空格,所以指纹会话内不变(按此算出 `d27`,推断)。 +- `cch` = 对**整个请求体字符串**做带种子的 xxHash64,取低 20 位,5 位十六进制(`src/utils/claudeCodeCch.ts:135-139`);签名前要求请求体中 `cch=00000;` 恰好出现一次、该字段 JSON 字面量恰好出现一次(`:35,44,48,54`)。 +- 三种上游格式: + - `openai_chat`:签 `messages` 里 role=system 的内容(`src/server/upstream/client.ts:205-216`,选择器 `src/utils/claudeCodeCch.ts:89-107`)。 + - `openai_responses`:签 `instructions`(`src/server/upstream/client.ts:218-224`)。 + - `anthropic`:代理直接返回 400「proxy not needed」(`src/server/proxy/handler.ts:39-52`),CLI 直连上游(`src/server/services/providerRuntimeEnv.ts:211-214`)。非 Claude 模型名时 CLI 不加头,请求体里没有这行;Claude 模型名时 CLI 加头并在 `src/services/api/client.ts:461` 的 fetch 包装里签,仍每请求变。 +- 两个连续请求的 system 开头: + - 第 N 轮:`x-anthropic-billing-header: cc_version=2.1.92.d27; cc_entrypoint=unknown; cch=3fa1c;` + `\n` + `You are a Claude agent, …` + - 第 N+1 轮:同上,只有 `cch=a07e2;` 不同(两个值仅示意)。 + - 前 78 个字符相同,第 79–83 个字符不同,整行 84 个字符。 +- 偶发不签(头部保持 `cch=00000;`,反而稳定):对话中别处也出现 `cch=00000;` 字面量(例如工具读到含该串的文件)。不是可依赖的行为。 +- 波及范围:所有经代理的请求都带这一行,包括 WebFetch 的二次处理请求、子代理请求、压缩请求;服务端标题请求直接调 `sendToUpstream`,不经 `ensureClaudeCodeAttribution`,没有这行。 + +**DreamCoder 其余项**: +- 日期与 git:`getSystemContext`、`getUserContext` 都 `memoize`(`src/context.ts:116,155`);跨午夜由 `date_change` 附件追加(`src/utils/attachments.ts:827-829`)。 +- MCP 说明:`isMcpInstructionsDeltaEnabled` 非 ant 默认 false(`src/utils/mcpInstructionsDelta.ts:26-33`),说明段用 `DANGEROUS_uncachedSystemPromptSection` 每轮重算(`src/constants/prompts.ts:513-518`);MCP 服务器中途连上或断开时 system 中部会变。 +- memory 段:`systemPromptSection('memory', …)` 会话内缓存,`/clear`、`/compact` 清除(`src/constants/prompts.ts:495`,`src/constants/systemPromptSections.ts:20-62`)。 +- skills 列表:`skill_listing` 附件(`src/utils/attachments.ts:866`)。 +- 工具:`assembleToolPool` 内置与 MCP 分别按 `localeCompare` 排序(未指定 locale)(`src/tools.ts:366-388`);schema 会话内按名字缓存(`src/utils/api.ts:119-175`);ToolSearch 在非 Anthropic base URL 下关闭,全部工具每次全量发送(`src/utils/toolSearch.ts:270-312`,A 维度已核)。 +- ZCode 专门修过不带 locale 的 `localeCompare` 会随进程语言改变顺序的问题(`zcode:core/src/tool/provider-visible-order.ts:60-66`)。DreamCoder 同样写法,换 locale 恢复会话时工具顺序可能变(推断)。 +- 中途新增的 MCP 工具在请求体 `tools` 末尾,但很多 chat 模板把工具渲染进 system 区,此时会改变前缀中部(推断,依 provider 模板)。 + +**Codex**: +- 世界状态按段快照,每轮与上次比较,只在变化时追加更新项,不改写前缀(`codex:core/src/context/world_state/mod.rs`,日期和 shell 见 `codex:core/src/context/world_state/environment.rs:148-151`)。 +- 测试断言第一次请求的整个 input 是第二次请求的前缀、`prompt_cache_key` 不变、工具一致(`codex:core/tests/suite/prompt_caching.rs:133,473,550-557,746,820-827`)。 + +**ZCode**: +- 主会话 system 第一次请求时写快照,之后按快照发送,冷恢复和升级后字节不变;压缩时清除快照(`zcode:core/src/runtime/helpers/prompt-snapshot.ts:1-8,70`,`zcode:core/src/runtime/methods/compact-active.ts:764-766`)。 +- 请求前公告(指令文件、git 会话上下文、日期)发出后不改写,变化追加增量(`zcode:core/src/runtime/methods/context-refresh.ts:348-410,454`),注释写明原地改写曾导致缓存失效。 +- skills 列表冷恢复或 rewind 时原位更新,会让缓存失效一次(`zcode:core/src/runtime/methods/context-refresh.ts:307-328`)。 +- 工具不进快照,MCP 工具中途变化时按当前注册表发送(`zcode:core/src/runtime/helpers/prompt-snapshot.ts:5`)。 + +### Q3 缓存控制 + +| | Codex | ZCode | DreamCoder | +|---|---|---|---| +| 请求体缓存键 | `prompt_cache_key` = 线程 id;子代理 `:<父线程 id>` | 无 | 无(CLI 的 `metadata.user_id` 不转发) | +| 断点标记 | 无(Responses 无此概念) | 2 个 system 段 + 最新非 system 消息,ephemeral | CLI 有,代理丢弃 | +| 断点能否到达上游 | 不适用 | chat 路径:否(推断) | 否 | +| 会话亲和头 | `session-id`、`x-client-request-id`、`x-codex-turn-state`、`x-codex-window-id` | `x-session-id`、`x-request-id`、`x-zcode-trace-id` 等 | 无 | +| 缓存命中数回到客户端 | 是:`cached_input_tokens` | 是(用于压缩判断) | 代理映射到 `cache_read_input_tokens`;回合结束消息不带,会话检查面板可见 | + +- Codex:`codex:core/src/client.rs:658-677`(缓存键),`codex:core/src/thread_manager.rs:273-281`(策略),`codex:codex-api/src/requests/headers.rs:8`,`codex:core/src/client.rs:1430,2509`;用量 `codex:codex-api/src/sse/responses.rs:134`,`codex exec` 汇总时扣除缓存部分 `codex:exec/src/event_processor_with_human_output.rs:519-521`。 +- ZCode 断点: + - 两个 system 段带 `EPHEMERAL_CACHE_CONTROL`(`zcode:core/src/context/builder.ts:36,265,279`)。 + - 每次请求把最新非 system 消息设为断点;压缩请求前移一条(`zcode:core/src/runtime/helpers/provider-request-messages.ts:139-143,551-571`)。 + - 适配层只把它转成 `providerOptions.anthropic.cacheControl`(`zcode:adapters/src/model/transform.ts:575-589`),chat 路径由 `createOpenAICompatible` 发送(`zcode:adapters/src/model/model-execution.ts:353-366`)。 + - 推断:该 SDK 不读 `anthropic` 键,断点不进请求体。SDK 源码不在本地,未核实;ZCode 对该 SDK 的补丁只有 44 行,未涉及缓存(`refs/coding-agents/zcode/patches/@ai-sdk__openai-compatible@2.0.60.patch`)。 + - 所以 ZCode 在 chat 路径上依赖 provider 的自动前缀缓存,和 Codex 一样;它的前缀逐请求不变(Q2)。 +- DreamCoder: + - `cache_control`、`anthropic-beta: prompt-caching-scope`、`metadata`、`context_management`、`output_config`、`max_tokens` 都不转发(`src/server/proxy/transform/anthropicToOpenaiChat.ts:32-76`,请求头 `src/server/upstream/client.ts:213`)。 + - 用量:`cache_read_input_tokens = prompt_tokens_details.cached_tokens`,`input_tokens = prompt_tokens − cached`(`src/server/proxy/transform/openaiChatToAnthropic.ts:81-91`);流式在 `message_delta` 里带,`message_start` 为 0(`src/server/proxy/transform/openaiChatStreamToAnthropic.ts:178,446-475`);responses 路径同(`src/server/proxy/transform/openaiResponsesToAnthropic.ts:36-45`)。 + - 到达 CLI:是,写入 transcript。到达 UI:回合结束的 `message_complete` 只带 input/output(`src/server/session/translate.ts:427-431`);会话检查接口从 transcript 读缓存读写数(`src/server/services/sessionService.ts:870-905`,`src/server/api/sessions.ts:513-517`),桌面端「缓存读 / 写」卡片显示它(`desktop/src/components/chat/LocalSlashCommandPanel.tsx:295`)。 + - DeepSeek 官方的 `prompt_cache_hit_tokens` 字段,仓库内 grep 无匹配,未处理。在本场景这个数应当一直接近 0(推断,因 Q2)。 + +### Q4 对话增长 + +| | Codex | ZCode | DreamCoder | +|---|---|---|---| +| 通用上限 | 写入历史时每个函数输出中间截断,约 12,000 字节 | 默认 100KB,从头保留 | 默认 50,000 字符,超限落盘 | +| Shell | `exec_command` `max_output_tokens` 默认 10,000 token,再按上一行截断 | Bash 30KB,落盘,保留尾部 | Bash 30,000 字符,保留头部,落盘 | +| Read | 无 Read 工具 | 25,000 token / 256KB;同文件同范围未改动时返回短提示 | 同左(25,000 token / 256KB;未改动去重默认开) | +| Grep / Glob | — | 20KB / 100 条、100KB | 20,000 / 100,000 字符 | +| 旧结果清理(压缩之外) | 未找到 | microcompact 存在,默认不启用 | 各变体全部不生效 | +| 工具结果图片 | 按模型输入模态保留或剥离 | 移到后续 user 消息;默认规则不支持图片则换成文字 | 代理替换成 `[image omitted]` | + +- Codex:截断预算 `truncation_policy × 1.2`(回退 10,000 字节 → 12,000),中间截断,只截内存中的历史、rollout 保留完整(`codex:utils/output-truncation/src/lib.rs:19-37`,`codex:core/src/context_manager/history.rs:518,565-577`);`max_output_tokens` 参数 `codex:core/src/tools/handlers/shell_spec.rs:56-60`;图片单边 2048 像素(`codex:utils/image/src/lib.rs:26,163`),不支持图片模态时在 `for_prompt` 剥离(`codex:core/src/context_manager/history.rs:603-617`)。 +- ZCode: + - 默认预算 `zcode:core/src/tool/executor/result-serialization.ts:25-31`;Bash `zcode:core/src/tool/handlers/bash.ts:600-612`;Grep `zcode:core/src/tool/handlers/grep.ts:23`;Glob `zcode:core/src/tool/handlers/glob.ts:20-21`;WebFetch 100KB `zcode:core/src/tool/handlers/webfetch-constants.ts:6`;Read `zcode:contracts/src/tools/read.ts:15-17`。 + - Read 去重:同一路径、同范围、文件未变时返回「Wasted call — file unchanged…」(`zcode:core/src/tool/handlers/read.ts:204-210`,`zcode:core/src/tool/handlers/read-text.ts:17-18`)。 + - microcompact:保留最近 5 个可清理结果,其余替换为 `[Old tool result content cleared]`,触发条件为空闲 60 分钟或接近压缩阈值(`zcode:core/src/compact/microcompact.ts:12-29`)。但运行时只在 `config.compact.microcompact.enabled === true` 时启用(`zcode:core/src/runtime/methods/microcompact.ts:104-115`),cli 与 bootstrap 里未找到设置 `compact` 的代码,所以默认不启用(推断,依据 grep 无结果)。 + - 图片:chat 路径把工具结果图片文字化,图片移到后续 user 消息(`zcode:adapters/src/model/tool-result-media-projection.ts:23-39`);每请求媒体预算 40MB(`zcode:core/src/runtime/helpers/media-budget.ts:28`);`.*` 默认规则 `supportsImage:false`。 +- DreamCoder: + - 上限 `src/constants/toolLimits.ts:13`;Bash `src/tools/BashTool/BashTool.tsx:424`;Grep `src/tools/GrepTool/GrepTool.ts:164`;Glob `src/tools/GlobTool/GlobTool.ts:60`;WebFetch `src/tools/WebFetchTool/WebFetchTool.ts:70`;Read `Infinity` 但自限(`src/tools/FileReadTool/FileReadTool.ts:340`,`src/tools/FileReadTool/limits.ts:1-18`)。 + - 超限时整段写入会话目录,对话里留提示和前 2000 字节预览(`src/utils/toolResultStorage.ts:109,137-197,272-330`)。Bash 另有头部保留截断(`src/tools/BashTool/utils.ts:133-165`)。 + - Read 去重:GrowthBook `tengu_read_dedup_killswitch` 默认 false,即去重开启(`src/tools/FileReadTool/FileReadTool.ts:534-565`)。 + - 单条消息 200,000 字符聚合预算由 `tengu_hawthorn_steeple` 控制,默认关(`src/utils/toolResultStorage.ts:451-455`)。 + - microcompact 各变体:时间触发版 `tengu_slate_heron` 默认关(`src/services/compact/timeBasedMCConfig.ts:30-36`);cached 版需 `feature('CACHED_MICROCOMPACT')` 且模块是空桩(`src/services/compact/microCompact.ts:276`);API 侧 `clear_tool_uses` 仅 ant(`src/services/compact/apiMicrocompact.ts:84-87`),且 `context_management` 不被代理转发。 + - 图片:用户图片转 `data:` URL(`src/server/proxy/transform/anthropicToOpenaiChat.ts:111-113`),工具结果里的图片被代理替换成文字(`src/server/proxy/transform/toolArguments.ts:40-42`),模型看不到 Read 读到的图片,但 CLI 侧仍按图片计入上下文估算(推断)。 + +### Q5 压缩 + +| | Codex | ZCode | DreamCoder | +|---|---|---|---| +| 触发 | 窗口 × 90% | 窗口 − min(最大输出, 21K) − 13K | (窗口 − min(最大输出, 20K)) × 90% | +| 第三方模型窗口 | 回退 272,000;可配 `model_context_window` | 规则表 `.*` 默认 1,000,000;glm-5.3 1M、kimi-k3 1,048,576 | 内置表 → 服务端回填的环境变量 → 200,000 | +| 计数来源 | provider 用量 | provider 用量,没有时估算 | provider 用量 + 估算 | +| 方法 | 本地摘要(远程压缩只给 OpenAI) | 摘要,保留最近一轮不进摘要 | fork 摘要整段历史 | +| 摘要请求带工具 | 否 | 是,与主循环同一份 | 是,与主循环同一份 | +| 摘要请求能否命中缓存 | 部分(工具段不同,推断) | 能,前缀相同(推断) | 否(计费头) | +| 摘要输出上限 | 未设置(未核实) | min(模型上限, 20K) | 不设;代理也不转发 `max_tokens` | +| 恢复内容 | 最近用户消息 ≤20,000 token + 摘要 + 重建初始上下文 | 最近一轮原样 + 摘要 + 最多 5 个文件(≤5K/个,≤50K 合计)+ 指令、skills、计划模式 | 最多 5 个文件(≤5K/个,≤50K)+ 用过的 skill + 计划、agent 状态、MCP 说明 | +| 失败处理 | 超窗口删最旧项重试;其他错误按流重试 | 自动压缩最多 3 次;超长时多保留几轮再试 | 超长按轮次删头重试 ≤3 次;fork 失败退回流式;连续失败 3 次停用 | + +- Codex:阈值 `codex:protocol/src/openai_models.rs:529-541`;窗口 `codex:models-manager/src/model_info.rs:19-29,98-156`;远程压缩条件 `codex:model-provider/src/capabilities.rs:33`;本地压缩不带工具 `codex:core/src/compact.rs:318-326`;重试 `:345-360`;保留 `:63,83-111,697-710`;提示 426 字符 `codex:prompts/templates/compact/prompt.md`。 +- ZCode: + - 阈值 `zcode:core/src/compact/policy.ts:6-14,67-88`;provider 用量覆盖估算 `:30-39,104-106`。 + - 窗口来自模型规则,按顺序叠加(`refs/coding-agents/zcode/config/provider/zcode-builtin.json` 的 `modelConfigRules.modelRules[0]`、`[4]`、`[39]`;叠加规则见 `refs/coding-agents/zcode/docs/builtin-provider-maintenance/configuration.md:14`)。deepseek-v4 系条目未设窗口,继承 1M。未配置窗口的模型若实际窗口更小,自动压缩不会在超窗口前触发,只能靠超窗口错误后的被动压缩(D 维度:`zcode:adapters/src/model/failure-inspection.ts:185-243`)。 + - 摘要请求与主循环同一份工具,注释写明原因是命中主循环前缀缓存(`zcode:core/src/runtime/methods/compact-active.ts:282-286,335-347`)。 + - 保留最近一组(`zcode:core/src/runtime/helpers/compact-selection.ts:31-57`);输出上限 `zcode:core/src/runtime/methods/compact-active.ts:864-873`;最多 3 次 `:101,783-813`;恢复文件 `zcode:core/src/runtime/helpers/compact-post-reminders.ts:27-30`。 +- DreamCoder: + - 阈值 `src/services/compact/autoCompact.ts:32-90`;窗口 `src/utils/context.ts:53-116`;内置表 `src/utils/model/modelContextWindows.ts:5-47`(有 glm-5.1、kimi-k2.6、deepseek-v4-*,没有 GLM-5.3、Kimi-K3、DeepSeek-V4.1);服务端回填 `src/server/upstream/contextWindows/`,写入 `src/server/services/providerRuntimeEnv.ts:238-243`。 + - **fork 重发前缀:确认。** `tengu_compact_cache_prefix` 默认 true(`src/services/compact/compact.ts:1150-1153`),`runForkedAgent` 带主循环的 `cacheSafeParams`(system、工具、历史),加一条压缩提示,`maxTurns:1`、`skipCacheWrite:true`,有意不设 `maxOutputTokens`(`:1177-1191`)。这个请求同样经代理、带新的 `cch`,所以「复用缓存」在本场景不成立,整份历史 + 约 12 万字符的固定部分按全价计一次。 + - 失败回退到流式摘要(`src/services/compact/compact.ts:1246-1291`);超长重试(`:227,440-489`);连续失败停用(`src/services/compact/autoCompact.ts:60-65,215-224`);恢复(`src/services/compact/compact.ts:122-131,520-600,1437-1515`)。session memory 压缩需两个 GrowthBook 开关,默认关(`src/services/compact/sessionMemoryCompact.ts:403-432`)。 + +### Q6 主循环以外的模型请求 + +| 请求 | Codex | ZCode | DreamCoder | +|---|---|---|---| +| 标题 | 无 | 无头模式无 | 服务端,第 1、3 条用户消息各一次,`fastModel` 或主模型 | +| WebFetch 二次处理 | 无 WebFetch | 每次一次,会话模型 | 每次一次,`ANTHROPIC_SMALL_FAST_MODEL`(未配则主模型) | +| WebSearch | 托管搜索(不是额外请求) | 一次模型请求(需模型支持原生搜索) | 默认不启用 | +| 压缩 | 当前模型 | 当前模型 | 当前模型 | +| 子代理 | 独立线程,`prompt_cache_key` 关联父线程 | 独立会话,会话模型 | 独立会话,各自 system,每轮一次 | +| 记忆提取 / 召回 | 默认关 | 召回关,整理未接线 | 默认关 | +| 预热 | 自定义 provider 不发 | 无 | 无 | + +- Codex:`supports_websockets` 默认 false(`codex:model-provider-info/src/lib.rs:199-201`),没有 websocket 时预热只做鉴权、不发模型请求(`codex:core/src/session/startup_prewarm.rs:244-253`,`codex:core/src/client.rs:1146-1151`);记忆默认关(`codex:features/src/lib.rs:1319-1321`);自动审批子代理默认 `User`(`codex:protocol/src/config_types.rs:183-186`);`current_time_reminder`、`token_budget` 默认关(`codex:features/src/lib.rs:1964-1991`)。 +- ZCode: + - 标题需 `config.titleGeneration` 存在且 taskType 为 interactive(`zcode:core/src/runtime/methods/session-title.ts:148-170`);`titleGeneration` 只在调用方传入时设置(`zcode:bootstrap/src/app/runtime-config.ts:72-90`),`cli/src` 里没有传入(grep 无结果,推断无头模式不生成标题)。 + - 语义记忆召回常量关(`zcode:core/src/memory/project-memory-retrieval-branch.ts:4`);`runProjectMemoryDream` 定义了但未找到调用方(`zcode:core/src/runtime/helpers/project-memory-dream.ts:56`)。 + - WebSearch 请求 `zcode:core/src/tool/handlers/websearch.ts:105-118`;WebFetch 处理 `zcode:core/src/tool/handlers/webfetch-processing.ts`。模型选择见 D 维度(都用会话模型)。 +- DreamCoder: + - 标题:`src/server/ws/handler.ts:897-939`(只在第 1、3 条用户消息触发),`src/server/services/titleService.ts:79,87`(模型 `provider.fastModel || selectedModel || models[0]`,system 约 800 字符 + 用户文本前 2000 字符)。直接调 `sendToUpstream`,没有计费头;`max_tokens:100` 被 chat 转换丢弃。 + - WebFetch:内容上限 100,000 字符,再发一次 `queryHaiku`(`src/tools/WebFetchTool/utils.ts:141,505-516`),模型 `ANTHROPIC_SMALL_FAST_MODEL`,服务端设为 `fastModel`,回退 `selectedModel`(`src/server/services/providerRuntimeEnv.ts:207-209,247-249`)。这个请求经代理,带计费头。 + - 默认不发的请求:记忆提取 `feature('EXTRACT_MEMORIES')`(`src/query/stopHooks.ts:158`);相关记忆预取 `tengu_moth_copse`(`src/utils/attachments.ts:2349-2354`);autoDream(`src/services/autoDream/config.ts:13-20`);工具摘要需 `CLAUDE_CODE_EMIT_TOOL_USE_SUMMARIES`(`src/query/config.ts:36`);Bash 前缀检测在生产路径跳过(`src/tools/BashTool/bashPermissions.ts:1937-1940`)。 + +### Q7 每请求固定开销(字符) + +| | Codex | ZCode | DreamCoder | +|---|---|---|---| +| system | 16,979(剔除 Planning 后的 `prompt.md`) | 约 5,000 | 约 26,500(含 memory 约 12,550) | +| 其他固定上下文 | 权限约 400 + 环境约 300 | meta 约 1,500 | 计费头 84 + git 状态至多约 3,000 | +| 工具定义 | 约 28,000(12 个) | 约 20,000(推断) | 约 90,000–100,000(34 个,推断) | +| 合计 | **约 46,000** | **约 27,000** | **约 120,000** | +| 折合 token(按 4 字符/token) | 约 1.15 万 | 约 0.7 万 | 约 3 万 | + +均不含 AGENTS.md / CLAUDE.md、skills 列表、MEMORY.md 正文(三家都视项目而定)。 + +- system:采用 B 维度按本场景分支求值的结果(Codex 16,979 + 片段,ZCode 约 5.0K + meta 约 1.5K,DreamCoder 约 26,450),我未重算。 +- DreamCoder 工具: + - 测量方法:对 34 个工具目录的 `prompt*.ts` 提取 ≥20 字符的字符串字面量,得 80,102 字符。这是上限估计;按本场景分支实际拼出的描述是 63,692 字符,见 [tools.md](tools.md)。 + - 这个数把条件分支两侧都算进去了。Bash 和 Agent 按 A 维度的精确值(10,003、6,992)替换后约 73,100。 + - 加上参数 `.describe()` 文本 14,083,再加 JSON schema 结构(估 8–12K),约 9–10 万字符(推断)。 +- ZCode 工具:这里只测到部分描述常量(完整数字见 [tools.md](tools.md)):Read 750、Edit 358、Grep 495、Glob 140、Write 240、AskUserQuestion 1,771、SendMessage 503、Bash 约 1,219、计划模式两工具约 6,000。同名工具的描述约为 DreamCoder 的 1/3 到 1/8;24 个工具合计约 2 万字符是推断。 +- Codex 工具:按源码字面量粗估(shell_spec 约 7.1K、request_user_input 约 3.2K、view_image 约 1.3K、goal 约 1.8K、多代理一套约 11K),加 JSON 结构约 2.8 万(推断)。 +- 折算:英文散文与 JSON 混合按约 4 字符/token;中文或密集 JSON 偏差较大,只用于比较量级。 +- 本场景 DreamCoder 前缀不命中缓存,这约 3 万 token 每个请求都按全价计;另两家在 provider 支持自动前缀缓存时,第二个请求起这部分主要按缓存价计(推断,取决于 provider)。 + +## 3. 对 DreamCoder 的含义 + +### DreamCoder 有而另两家都没有 + +| 差异 | 事实 | 后果 | +|---|---|---| +| 每请求变化的计费头 `cch` | system 第 79–83 字符逐请求不同(Q2) | 推断:provider 前缀缓存命中率接近 0;固定部分约 3 万 token 加全部历史每个请求按全价计;缓存价通常是原价的 10%–50%,长会话里输入成本差距按历史长度放大。延迟上也拿不到缓存命中带来的首 token 提速。 | +| 代理丢弃全部缓存控制字段 | `cache_control`、beta 头、`metadata` 不转发;无会话亲和头(Q3) | 推断:即使去掉 `cch`,对需要显式标记或靠会话粘性路由的 provider 也拿不到缓存;靠自动前缀缓存的 provider 会恢复。 | +| 每请求约 9–10 万字符工具定义、memory 段约 1.25 万字符 | Q7 | 推断:固定开销是 Codex 的约 2.6 倍、ZCode 的约 4.5 倍;在 200K 窗口下约占 15%,压缩更早触发。 | +| 压缩用 fork 重发整份前缀,不设输出上限 | Q5 | 事实:这次请求的输入约等于当时整个上下文。推断:因计费头它不命中缓存,一次压缩的输入接近窗口阈值。输出无上限,非原生模型可能写出很长的摘要。 | +| 代理把工具结果图片换成文字 | `toolArguments.ts:40-42` | 推断:Read 读图、截图类工具对模型无效,模型可能重试,增加轮数。 | +| 服务端标题请求两次 | 第 1、3 条用户消息 | 事实:每会话多两次小请求,`fastModel` 未配置时用主模型。 | + +### 另两家都有而 DreamCoder 没有 + +| 差异 | 事实 | 后果 | +|---|---|---| +| 逐请求严格不变的前缀 | Codex 有测试保证;ZCode 有 system 快照、公告只追加 | 推断:这是另两家在 benchmark 上输入成本低的直接原因之一,在 provider 自动缓存下效果最大。DreamCoder 除计费头外的设计也能做到,差的是那一行。 | +| 会话级缓存路由信息 | Codex `prompt_cache_key` + `session-id`;ZCode `x-session-id` | 推断:多副本部署的 provider 可据此把同一会话路由到同一缓存节点;DreamCoder 每请求可能落到不同节点。 | +| 第三方模型的上下文窗口来源更全 | ZCode 规则表覆盖 glm-5.3、kimi-k3,默认 1M;Codex 可配置 | 事实:DreamCoder 对表外且服务端未回填的模型按 200,000 计。推断:对 1M 窗口的模型过早压缩、多付压缩费用;对小窗口模型则可能来不及压缩就超窗口。ZCode 默认 1M 是另一方向的风险。 | +| 压缩摘要输出上限 | ZCode 20K;Codex 未核实 | 推断:DreamCoder 依赖 provider 默认 `max_tokens`,摘要长度和耗时不可控。 | +| 写入历史时统一截断 | Codex 每项约 12KB 中间截断 | 推断:DreamCoder 单项可达 50,000 字符(Bash 30,000),历史增长更快;ZCode 介于两者之间。 | + +旧工具结果清理:三家在本场景都没有生效的机制,不构成差异;DreamCoder 与 ZCode 都有实现但默认关闭。 + +## 4. 没有核实的地方 + +- `@ai-sdk/openai-compatible` 是否忽略 `providerOptions.anthropic.cacheControl`:SDK 源码不在本地,按该 SDK 的已知行为推断为忽略。 +- 各 provider 的 chat 模板是否把 `tools` 渲染到 system 附近(影响「中途新增工具」对前缀的破坏位置):未核实。 +- DeepSeek 官方端点是否同时返回 `prompt_tokens_details.cached_tokens`:未核实;DreamCoder 不读 `prompt_cache_hit_tokens`。 +- Codex:git 状态是否进入初始上下文、本地压缩请求是否设置输出上限、中途出现的 MCP 工具对 `tools` 顺序的影响:未核实。 +- ZCode:24 个工具的完整描述总长(只测了部分);`cli/src` 未设 `compact` 与 `titleGeneration` 的结论依据 grep 无结果。 +- DreamCoder:工具定义总长为静态提取的估计,未在运行时序列化核对;代理进程 `CLAUDE_CODE_ENTRYPOINT` 未设(推断为 `unknown`)。指纹值 `d27` 是按算法手算,未在运行中抓包。 +- 各家实际缓存命中率与成本:没有运行,没有数据。 diff --git a/docs/features/harness/comparison/tools.md b/docs/features/harness/comparison/tools.md new file mode 100644 index 00000000..9cbafd4e --- /dev/null +++ b/docs/features/harness/comparison/tools.md @@ -0,0 +1,314 @@ +# A 维度:工具面(Codex CLI / ZCode / DreamCoder) + +测量方法:三家的描述文本都从源码字符串字面量静态拼出(不运行任何项目代码),按本场景解析每个插值和条件分支后数字符。schema 大小只统计了 describe 文本并据此估算 JSON 总量,标为推断。 + +范围说明:Codex rust-v0.164.0 已删除 `wire_api = "chat"`(`codex:model-provider-info/src/lib.rs:102` 的报错文案;`codex:model-provider-info/src/lib.rs:109-113` 的 `WireApi` 只剩 `Responses`)。所以 Codex 在本场景只能接「OpenAI 兼容的 `/v1/responses` 端点」,不能接 chat-completions。下文 Codex 一列按「自定义 provider + Responses 端点 + 目录外模型(fallback 元数据)」描述。 + +--- + +## 1. 结论 + +1. **工具数量和描述体量差一个数量级。** DreamCoder 发 34 个工具,描述 63,692 字符,加 schema 约 82–86K 字符;ZCode 24 个,描述 21,544 字符,总量约 28–31K;Codex 12 个 function 工具加 1 个托管 `web_search`,描述约 7.4K 字符(另加 `spawn_agent` 里的模型列表),总量约 12–15K(推断)。 +2. **DreamCoder 的长描述大部分是行为规程,不是参数说明。** 最大的 Bash(10,003)里 6,253 字符是 git 提交和 PR 的完整流程;Agent(6,992)里 1,815 是内联的 agent 列表;EnterPlanMode(4,022)是「主动进入计划模式」的规则和例子。ZCode 的 Bash 只有 1,121,Codex 的 `exec_command` 只有 82,shell 规则放在系统提示词里(`codex:models-manager/prompt.md:258-265`)。 +3. **DreamCoder 有 13 个产品功能类工具(ShowUI、Kanban×4、会话×3、SendMessage、Artifact×2、Design×2),合计 21,265 字符(占描述的 33%),每个请求都发。** 它们由服务器对每个会话无条件打开的环境变量控制(`src/server/services/conversationService.ts:1052-1058`),4 个 artifact/design 工具根本没有开关。除 SendMessage 外都没有 `shouldDefer`,即使打开 ToolSearch 也不会被延迟。 +4. **ZCode 的产品工具(8 个会话控制 + ListModels,6,434 字符)全部标了 `shouldDefer`,但 CLI 默认 `--toolsearch-mode off`,所以本场景照样全量发送。** Codex 的同类工具(goal、多 agent、图片生成、历史笔记、插件推荐)按 feature、模型目录、provider 能力和登录方式逐项决定是否注册。 +5. **三家都有延迟加载机制,但只有 ZCode 的 local 模式能在普通 chat-completions 端点上用。** ZCode local 模式用 `LocalToolSearch` 返回 schema 文本,再经固定的 `DeferredToolCall` 调用,工具数组不变。DreamCoder 的 ToolSearch 依赖 Anthropic 的 `defer_loading` 和 `tool_reference`,非 Anthropic base URL 时直接关闭。Codex 的 `tool_search` 是 Responses API 的原生工具类型,并且只在模型目录标了 `supports_search_tool` 时启用,fallback 模型为 false。 +6. **搜索:两家并入 shell,DreamCoder 单列工具。** Codex 没有读、搜索、写文件的工具,靠 `exec_command`,提示词要求用 `rg`;ZCode 默认走 embedded search 分支,不注册 Glob/Grep,搜索用 Bash 里的 `find`/`grep`;DreamCoder 有 Glob、Grep、Read、Write、Edit、NotebookEdit,Bash 描述再用 990 字符要求模型不要在 shell 里用这些命令。 +7. **DreamCoder 把 Claude 专属文本发给非 Claude 模型。** 例如 Read 说「Claude Code is a multimodal LLM」;Bash 要求提交署名 `Co-Authored-By: Claude Opus 4.7`(非公开模型名回落值,`src/utils/attribution.ts:73-80`);Agent 的 `model` 参数是 `sonnet/opus/haiku` 枚举;agent 列表里有「configure the user's Claude Code status line」。ZCode 的描述按模型能力改写(Read 只在模型支持 PDF 时加 PDF 句);Codex 的工具集按模型目录字段决定。 +8. **排序:三家的工具顺序都是确定的。** DreamCoder 按名字排序,并按会话缓存 schema;ZCode 对名单内工具按 en-US 排序,名单外按注册顺序,MCP 排最后;Codex 按代码里的注册顺序(`IndexMap`),托管工具排最后,再合并成 namespace。会话内会变的是 MCP 连接带来的增减;ZCode 的 native 模式和 DreamCoder 的 ToolSearch 在发现新工具后也会往数组里加工具。 + +--- + +## 2. 逐项对比 + +### Q1 完整清单 + +#### 1a 汇总 + +| | Codex | ZCode | DreamCoder | +|---|---|---|---| +| 发送的工具数 | 12 function + 1 托管 `web_search` | 24 | 34 | +| 描述字符合计 | 约 7.4K + 模型列表 | 21,544 | 63,692 | +| schema 估计(推断) | 5–7K | 6–9K | 18–22K | +| 工具块总量(推断) | 12–15K | 28–31K | 82–86K | +| 最长描述 | `spawn_agent` 约 4.2K | EnterPlanMode 4,011 | Bash 10,003 | +| 产品功能类工具 | 无(goal 工具 1.9K 算通用) | 9 个,6,434 | 13 个,21,265 | + +按约 4 字符/token 粗算(推断),每个请求的工具块:DreamCoder 约 21K token,ZCode 约 7K,Codex 约 3–4K。 + +#### 1b DreamCoder(`--print`,服务器启动,本场景) + +门控(逐项核对 `getAllBaseTools` 的候选和各工具的 `isEnabled`): +- 流程:`src/tools.ts:203-272` `getAllBaseTools()` 产出候选 → `getTools()`(`src/tools.ts:292-348`)去掉 ListMcpResources/ReadMcpResource/SyntheticOutput,过滤 deny 规则和 `isEnabled()` → print 模式在 `src/cli/print.ts:1521-1549` 调 `assembleToolPool`(`src/tools.ts:366-388`)和 `mergeAndFilterTools`(`src/utils/toolPool.ts:55-79`)。 +- 描述就是 `tool.prompt()`(`src/utils/api.ts:169-177`),代理原样转成 `function.description`/`parameters`(`src/server/proxy/transform/anthropicToOpenaiChat.ts:47-58`),不截断。 +- 服务器给子进程设 `CLAUDE_CODE_ENABLE_TASKS=1`、ShowUI、SessionLinks、ArtifactEditLocks 开关(`src/server/services/conversationService.ts:1052-1058`)→ TodoWrite 关,TaskCreate/Get/Update/List 开(`src/utils/tasks.ts:133-139`);ShowUI、StartSession、ListSessions、RenameSession、Kanban×4 开;SendMessage 开(`src/tools/SendMessageTool/SendMessageTool.ts:594-596`)。 +- Glob/Grep:`hasEmbeddedSearchTools()` 要求 `EMBEDDED_SEARCH_TOOLS` 且入口不是 sdk-*(`src/utils/embeddedTools.ts:15-21`);本场景入口被设成 `sdk-cli`(`src/main.tsx:510-533`),为假 → 两者都发。 +- EnterWorktree/ExitWorktree:`isWorktreeModeEnabled()` 恒真(`src/utils/worktreeModeEnabled.ts:9-11`)。 +- ArtifactCheck/ArtifactCopy/ChooseDesignTemplate/UseDesignSystem:没有自定义 `isEnabled`,用 `buildTool` 默认 true(`src/Tool.ts:758`)。 +- 不发:TeamCreate/TeamDelete(只在设置里开 Agent teams 时注入环境变量,`src/server/services/agentTeamsEnv.ts:9-15`);Brief(`feature('KAIROS')` 假,`src/tools/BriefTool/BriefTool.ts:126-131`);WebSearch(非 Claude 模型名只有配 Tavily/Brave key 才开,`src/tools/WebSearchTool/backend.ts:65-110`);ToolSearch(见 Q5);所有 `USER_TYPE==='ant'` 和 `feature()` 工具。 +- 条件附加:桌面端浏览器宿主已连接时,CLI 多一个 MCP 服务器 `dreamcoder-browser`(`src/server/browserHost/childEnv.ts:29-37`、`src/utils/browserControl/setup.ts:14-33`、`src/main.tsx:1598-1605`),15 个工具(`src/server/browserHost/names.ts:9-25`),描述未测;用户 MCP 和自定义 agent 也会增加。 + +| 工具 | 定义 | 描述字符 | 参数 | schema | +|---|---|---|---|---| +| Agent | `src/tools/AgentTool/prompt.ts:66-300` | 6,992 | 6 | 中(describe 约 550) | +| ArtifactCheck | `src/tools/ArtifactCheckTool/prompt.ts:3` | 871 | 1 | 小 | +| ArtifactCopy | `src/tools/ArtifactCopyTool/prompt.ts:3` | 608 | 1 | 小 | +| AskUserQuestion | `src/tools/AskUserQuestionTool/prompt.ts`(`ASK_USER_QUESTION_TOOL_PROMPT`) | 1,074 | 4 | 大(嵌套,describe 1,860) | +| Bash | `src/tools/BashTool/prompt.ts:275-369`,git 段 `:42-165` | 10,003 | 5 | 中(describe 1,012) | +| ChooseDesignTemplate | `src/tools/ChooseDesignTemplateTool/prompt.ts:5` | 914 | 4 | 中 | +| Edit | `src/tools/FileEditTool/prompt.ts` | 1,095 | 4 | 小 | +| EnterPlanMode | `src/tools/EnterPlanModeTool/prompt.ts:16-99` | 4,022 | 0 | 空 | +| EnterWorktree | `src/tools/EnterWorktreeTool/prompt.ts:1` | 1,335 | 1 | 小 | +| ExitPlanMode | `src/tools/ExitPlanModeTool/prompt.ts:6` | 1,849 | 1 | 小 | +| ExitWorktree | `src/tools/ExitWorktreeTool/prompt.ts:31` | 1,923 | 2 | 小 | +| Glob | `src/tools/GlobTool/prompt.ts:3` | 371 | 2 | 小 | +| Grep | `src/tools/GrepTool/prompt.ts:6` | 866 | 9 | 大(describe 1,622) | +| KanbanCreate | `src/tools/KanbanCreateTool/prompt.ts:6` | 1,334 | 7 | 中 | +| KanbanGet | `src/tools/KanbanGetTool/prompt.ts:5` | 685 | 2 | 小 | +| KanbanList | `src/tools/KanbanListTool/prompt.ts:5` | 592 | 2 | 小 | +| KanbanUpdate | `src/tools/KanbanUpdateTool/prompt.ts:8` | 4,774 | 1 | 大(`command` 是 15 个分支的 discriminated union,`src/entrypoints/sdk/controlSchemas.ts:768-846`;推断 JSON 4–5K) | +| ListSessions | `src/tools/ListSessionsTool/prompt.ts:6` | 471 | 1 | 小 | +| NotebookEdit | `src/tools/NotebookEditTool/prompt.ts:3` | 513 | 5 | 小 | +| Read | `src/tools/FileReadTool/prompt.ts:28-50` | 1,680 | 4 | 小 | +| RenameSession | `src/tools/RenameSessionTool/prompt.ts:3` | 259 | 1 | 小 | +| SendMessage | `src/tools/SendMessageTool/prompt.ts`(`getPrompt`) | 1,551 | 4 | 小 | +| ShowUI | `src/tools/ShowUITool/prompt.ts:6` | 6,505 | 7 | 中 | +| Skill | `src/tools/SkillTool/prompt.ts:173-196` | 1,272 | 2 | 小 | +| StartSession | `src/tools/StartSessionTool/prompt.ts:6` | 1,880 | 6 | 中 | +| TaskCreate | `src/tools/TaskCreateTool/prompt.ts`(`getPrompt`) | 2,146 | 4 | 小 | +| TaskGet | `src/tools/TaskGetTool/prompt.ts:3` | 732 | 1 | 小 | +| TaskList | `src/tools/TaskListTool/prompt.ts`(`getPrompt`) | 998 | 0 | 空 | +| TaskOutput | `src/tools/TaskOutputTool/TaskOutputTool.tsx:172-182` | 701 | 3 | 小 | +| TaskStop | `src/tools/TaskStopTool/prompt.ts:3` | 511 | 2 | 小 | +| TaskUpdate | `src/tools/TaskUpdateTool/prompt.ts:3` | 2,243 | 9 | 中 | +| UseDesignSystem | `src/tools/UseDesignSystemTool/prompt.ts:3` | 821 | 2 | 小 | +| WebFetch | `src/tools/WebFetchTool/WebFetchTool.ts:181-190` + `prompt.ts:3` | 1,479 | 2 | 小 | +| Write | `src/tools/FileWriteTool/prompt.ts:10` | 622 | 2 | 小 | + +解析时用到的本场景取值: +- Bash:超时默认 120000、上限 600000(`src/utils/timeouts.ts:2-3`);沙箱未启用,沙箱段为空(`src/tools/BashTool/prompt.ts:172-175`);git 段默认包含(`src/utils/gitSettings.ts:13-18`)。 +- Agent:fork 关(`src/tools/AgentTool/forkSubagent.ts:32-39`);入口 sdk-cli 时内置 agent 是 general-purpose、statusline-setup、Explore、Plan、verification(`src/tools/AgentTool/builtInAgents.ts`);列表内联(`tengu_agent_list_attach` 默认 false,`src/tools/AgentTool/prompt.ts:59-64`);订阅类型不是 pro,所以带并发提示(`src/tools/AgentTool/prompt.ts:254-258`)。 +- AskUserQuestion:入口 sdk-cli 时不设预览格式(`src/main.tsx:828-836`),不带 preview 段。 +- EnterPlanMode:interview phase 关(`src/utils/planModeV2.ts:50-62`),带「What Happens in Plan Mode」段。 +- Read:`includeMaxSizeInPrompt`/`targetedRangeNudge` 默认 undefined(`src/tools/FileReadTool/limits.ts:76-84`);PDF 句只对 `claude-3-haiku` 关闭(`src/utils/pdfUtils.ts:59-61`),所以对 GLM 等模型也写着能读 PDF。 +- Edit:compact 行号前缀开(`src/utils/file.ts:278-285`)。 +- TaskCreate/TaskList:swarm 关,不带 teammate 段。 +- Agent schema:`name/team_name/mode` 在 swarm 关时被删(`src/utils/api.ts:87-90`、`:163-167`),剩 6 个参数。 + +#### 1c ZCode(headless `--prompt`,`openai-chat-completions`,默认 `--toolsearch-mode off`) + +门控: +- 注册入口 `zcode:core/src/tool/handlers/index.ts:232-345`(`registerBuiltInTools`),选项来自 `zcode:core/src/runtime/helpers/runtime-tools.ts:47-101`;`--prompt` 的 app 选项在 `zcode:cli/src/prompt-command.ts:243-275`:`standaloneSessionControl: true`,不传 automation、offPeak、pluginDiscovery、topicResource 端口,ToolSearch 模式默认 `"off"`(`zcode:cli/src/prompt-command.ts:82`)。 +- 会话控制:独立 CLI 只注册共有的 8 个(`zcode:core/src/tool/handlers/index.ts:247-258`,定义 `zcode:core/src/tool/session-control/index.ts:80-170`)。 +- Glob/Grep:embedded search 分支默认开(`zcode:core/src/embedded-search/capability.ts:4`),Bash 可用时不注册 Glob/Grep(`zcode:core/src/tool/handlers/index.ts:259-264`)。 +- 动态工作流:独立 CLI 默认 `disabled`(`zcode:cli/src/workflow-mode.ts:10`),10 个工作流工具不注册;ListModels 因会话控制在场仍注册(`zcode:core/src/tool/handlers/index.ts:318-329`)。Agent 描述里的「必须用 CreateWorkflow」一行也随之删掉(`zcode:core/src/tool/handlers/index.ts:362-373`)。 +- Task 是 Agent 的别名,`providerVisible: false`(`zcode:core/src/tool/handlers/agent.ts:331-345`),不发。 +- SendMessage:默认 subagent 端口带 `sendMessage`(`zcode:core/src/subagent/runner.ts:718-746`),发。 +- WebSearch:只在 `model.properties.supportsNativeWebSearch` 为真时发(`zcode:core/src/runtime/methods/config.ts:293-298`),而且只能编码成 Anthropic 原生工具,其他 provider 直接报错(`zcode:adapters/src/model/tool-transform.ts:250-280`)。本场景不发(推断:自定义模型该属性为 false;即使为 true 也无法编码)。 +- 描述 = `metadata.description`,有 `modelInstructions` 时追加 `Usage:` 列表(`zcode:core/src/tool/registry.ts:104-142`);个别工具按模型改写(`resolveModelContract`,`zcode:core/src/tool/model-contract.ts:20-33`)。 + +| 工具 | 定义 | 描述字符 | 参数 | schema | shouldDefer | +|---|---|---|---|---|---| +| Agent | `zcode:core/src/tool/handlers/agent.ts:92-122` | 1,371 | 约 5 | 小 | 否 | +| AskUserQuestion | `zcode:core/src/tool/handlers/ask-user-question.ts:20-45` | 1,785 | 1 | 中 | 否 | +| Bash | `zcode:core/src/tool/handlers/bash-prompt.ts:1-25` | 1,121 | 4 | 小 | 否 | +| Edit | `zcode:core/src/tool/handlers/edit.ts:53-59` | 360 | 4 | 小 | 否 | +| EnterPlanMode | `zcode:core/src/tool/handlers/plan-mode-prompts.ts:5-98` | 4,011 | 0 | 空 | 是 | +| ExitPlanMode | `zcode:core/src/tool/handlers/plan-mode-prompts.ts:102-` | 1,917 | 1 | 小 | 是 | +| Read | `zcode:core/src/tool/handlers/read.ts:68-79` | 736 | 3–4 | 小 | 否 | +| SendMessage | `zcode:core/src/tool/handlers/send-message.ts:17-28` | 509 | 3 | 小 | 是 | +| Skill | `zcode:core/src/tool/handlers/skill.ts:103-116` | 935 | 2 | 小 | 否 | +| TaskOutput | `zcode:contracts/src/tools/task-output.ts:12-24` | 1,049 | 3 | 小 | 是 | +| TaskStop | `zcode:core/src/tool/handlers/task-stop.ts:20-27` | 203 | 2 | 小 | 是 | +| TodoRead | `zcode:core/src/tool/handlers/todo.ts:74-79` | 34 | 0 | 空 | 是 | +| TodoWrite | `zcode:core/src/tool/handlers/todo.ts:130-141` | 370 | 1 | 小 | 否 | +| WebFetch | `zcode:core/src/tool/handlers/webfetch.ts:39-47` | 469 | 2 | 小 | 否 | +| Write | `zcode:core/src/tool/handlers/write.ts:37-41` | 240 | 2 | 小 | 否 | +| CreateSession / ForkSession / SendToSession / InterruptSession / RenameSession | `zcode:core/src/tool/session-control/index.ts:80-170`,Usage 指令 `:58-77` | 799 / 835 / 786 / 770 / 729 | 2–4 | 小 | 是 | +| ListSessions / ReadSession / WaitSessions | 同上 | 481 / 569 / 659 | 1–4 | 小 | 是 | +| ListModels | `zcode:core/src/tool/handlers/list-models.ts:38-45` | 806 | 0 | 空 | 是 | + +合计 24 个、21,544 字符(确认早前「24 个」)。contracts 里 describe 文本合计约 2K(`zcode:contracts/src/tools/*.ts`),推断 JSON 6–9K。ListModels 描述提到 CreateWorkflow/AmendWorkflow,而这两个工具本场景不存在(`zcode:core/src/tool/handlers/list-models.ts:42`)。 + +#### 1d Codex(`codex exec`,自定义 provider,Responses 端点,fallback 元数据) + +门控: +- fallback 元数据:`shell_type: UnifiedExec`、`apply_patch_tool_type: None`、`supports_search_tool: false`、`experimental_supported_tools` 为空、`multi_agent_version: None`、`tool_mode: None`(`codex:models-manager/src/model_info.rs:98-150`)。 +- feature 默认值(`codex:features/src/lib.rs`):ShellTool、UnifiedExec、ViewImage、Collab、Goals 开;MultiAgentV2、CodeMode、RequestPermissionsTool、DeferredExecutor、TokenBudget 关。 +- 注册流程:`codex:core/src/tools/spec_plan.rs:121-188`(`build_tool_router`)→ `add_shell_tools`(`:1235-1266`)、`add_mcp_resource_tools`(`:1269-1284`,无 MCP 服务器时不加)、`add_core_utility_tools`(`:1287-1436`)、`add_collaboration_tools`(`:1439-1572`),再加扩展工具和托管工具。 +- `update_plan`:要配置 `tools.update_plan.enabled` 才注册(`codex:core/src/config/mod.rs:2791-2797`),默认不发。但 fallback 提示词有整节说明这个工具(`codex:models-manager/prompt.md:52-121`、`:267-273`)。 +- `apply_patch`:fallback 模型不声明(`codex:core/src/tools/spec_plan.rs:1409-1412`),但 `exec_command` 会拦截 shell 里的 `apply_patch` 调用(`codex:core/src/tools/handlers/unified_exec/exec_command.rs:358`、`codex:core/src/tools/handlers/apply_patch.rs:435-448`);提示词要求用 `apply_patch` 改文件(`codex:models-manager/prompt.md:132`)。 +- 多 agent:Collab 开、V2 关 → V1(`codex:core/src/config/mod.rs:1668-1676`),5 个工具放在 namespace `multi_agent_v1` 里(`codex:core/src/tools/handlers/multi_agents_spec.rs:14-15`)。fallback 模型 `supports_search_tool` 为 false,所以是 Direct 暴露(`codex:core/src/tools/spec_plan.rs:1538-1542`)。 +- `request_user_input`:配置默认开(`codex:core/src/config/mod.rs:2783-2789`),但描述写明只在 Plan 模式可用(`codex:tools/src/tool_config.rs:6-15`、`codex:core/src/tools/handlers/request_user_input_spec.rs:123-128`)。 +- goal:Goals 开,app-server 有 state_db 时安装扩展(`codex:app-server/src/extensions.rs:87-99`)。 +- 托管 `web_search`:provider 能力默认 `web_search: true`(`codex:model-provider/src/capabilities.rs:19-27`),模式默认 Cached(`codex:core/src/config/mod.rs:3928-3929`),追加到列表末尾(`codex:core/src/tools/spec_plan.rs:687-716`)。 +- 不发:图片生成(要 OpenAI 鉴权,`codex:core/src/tools/spec_plan.rs:783-818`);history/notes 工具(要 Codex 后端登录,`codex:ext/history-notes/src/extension.rs:52`);skills 扩展工具(要云端 skill 或选定能力根,`codex:ext/skills/src/preparation.rs:48-57`,推断默认不发)。 +- `output_schema` 不序列化(`codex:tools/src/responses_api.rs:43-44`),只发 parameters。 + +| 工具 | 定义 | 描述字符 | 参数 | schema | +|---|---|---|---|---| +| exec_command | `codex:core/src/tools/handlers/shell_spec.rs:22-107` | 82 | 10 | 中(每个参数一句 describe) | +| write_stdin | `codex:core/src/tools/handlers/shell_spec.rs:110-150` | 80 | 4 | 小 | +| view_image | `codex:core/src/tools/handlers/view_image_spec.rs:16-50` | 124 | 1 | 小 | +| multi_agent_v1(namespace 描述) | `codex:core/src/tools/handlers/multi_agents_spec.rs:15` | 43 | — | — | +| spawn_agent | `codex:core/src/tools/handlers/multi_agents_spec.rs:70-106`、`:686-770` | 约 4,200 + 模型列表 | 约 5 | 中 | +| send_input / resume_agent / wait_agent / close_agent | `codex:core/src/tools/handlers/multi_agents_spec.rs:166-360` | 215 / 89 / 252 / 298 | 1–3 | 小 | +| request_user_input | `codex:core/src/tools/handlers/request_user_input_spec.rs:16-128` | 120 | 1 | 中(嵌套) | +| get_goal / create_goal / update_goal | `codex:ext/goal/src/spec.rs:15-100` | 122 / 265 / 1,541 | 0 / 2 / 1 | 小 | +| web_search(托管) | `codex:tools/src/tool_spec.rs:37-52` | 无描述 | — | — | + +合计 12 个 function 工具 + 托管 `web_search`,描述约 7.4K 字符加 `spawn_agent` 的模型列表(列表长度取决于目录里 picker 可见的模型,未核实)。 + +### Q2 能力与工具对照 + +| 能力 | Codex | ZCode | DreamCoder | +|---|---|---|---| +| 执行命令 | `exec_command` + `write_stdin`(PTY 会话) | Bash | Bash | +| 读文件 | 并入 shell | Read | Read | +| 搜索 | 并入 shell,提示词要求 `rg`(`codex:models-manager/prompt.md:264`) | 并入 Bash 的 `find`/`grep`(Glob/Grep 不注册) | Glob、Grep | +| 编辑 | shell 里的 `apply_patch`,被拦截执行 | Edit(ApplyPatch 注释掉了,`zcode:core/src/tool/handlers/index.ts:96`) | Edit | +| 写文件 | 同上 | Write | Write | +| Notebook | 并入 shell | 无 | NotebookEdit | +| 网页抓取 | 无工具,靠 shell | WebFetch | WebFetch | +| 网页搜索 | 托管 `web_search`(provider 能力) | 只有 Anthropic 原生,本场景无 | 只有配 Tavily/Brave key 才有,本场景无 | +| 问用户 | `request_user_input`(仅 Plan 模式) | AskUserQuestion | AskUserQuestion | +| 计划模式 | 协作模式,由用户切换,无工具 | EnterPlanMode/ExitPlanMode(deferred) | EnterPlanMode/ExitPlanMode | +| 任务清单 | `update_plan`(默认不注册) | TodoWrite、TodoRead | TaskCreate/Get/Update/List | +| 目标 | get/create/update_goal | 无 | 无 | +| 子代理 | `multi_agent_v1` 下 5 个工具 | Agent + SendMessage | Agent + SendMessage | +| 后台进程 | `exec_command` 返回 session_id,`write_stdin` 轮询 | Bash `run_in_background` + TaskOutput/TaskStop | Bash `run_in_background` + TaskOutput/TaskStop | +| Skills | 无工具;列表在提示词里,用 shell 读(推断) | Skill | Skill | +| 会话控制 | 无 | 8 个会话工具 + ListModels | StartSession、ListSessions、RenameSession、SendMessage | +| Worktree | 无 | 无 | EnterWorktree、ExitWorktree | +| MCP | 有服务器时加资源工具和 MCP 工具;模型支持时可 deferred | MCP 工具,ToolSearch 开时 deferred | MCP 工具,ToolSearch 开时 deferred(本场景关) | +| 图片 | `view_image` | Read(也读视频) | Read | +| 产品专属 | 无 | 会话控制、ListModels | ShowUI、Kanban×4、Artifact×2、Design×2、会话×3 | + +### Q3 DreamCoder 的长描述拆解,以及另两家对应写在哪 + +**Bash(10,003)** + +| 内容 | DreamCoder | ZCode Bash(1,121) | Codex | +|---|---|---|---| +| 开头 + 「别在 shell 里用 find/grep/cat…,用专用工具」列表 | 990 | 一句「Avoid using this tool to run …」(不含 find/grep) | 无;提示词反过来要求用 `rg`(`prompt.md:264`) | +| 指令(mkdir 前 ls、引号、cwd、超时、后台、多命令、git 三条、sleep 七条) | 2,756 | 五条短句(cwd、超时、后台、输出不一定给用户看) | `exec_command` 参数 describe;提示词 Shell 节 | +| git 提交完整流程(安全协议、四步并行、HEREDOC 示例、署名) | 4,216 | 「# Git」三行:交互 flag 不支持、用 gh、用户要求才提交 | 提示词两行:用 git log/blame、不提交不建分支(`prompt.md:141-144`) | +| PR 完整流程 | 2,037 | 无 | 无 | + +**Agent(6,992)** + +| 内容 | DreamCoder | ZCode Agent(1,371) | Codex `spawn_agent`(约 4.2K) | +|---|---|---|---| +| 介绍 | 约 380 | 约 260 | 一行 | +| agent 列表 | 1,815(内联) | 不在描述里,放 system-reminder 消息(`agent.ts:99`) | 放 `agent_type` 参数 describe | +| 何时不用 | 520 | 一段「何时用」约 400 | 「没有明确要求不要派生」两段 | +| 使用说明(并发、后台、SendMessage 续接、worktree 隔离…) | 约 2,250 | 4 条约 600 | 「委派 vs 自己做」「设计子任务」「委派后」「并行模式」四节约 3.4K | +| 怎么写 prompt | 1,028 | 无 | 并入上面 | +| 示例 | 1,002 | 无 | 无 | + +**EnterPlanMode(4,022)**:开头 326(要求「proactively」使用)、何时用 1,750、何时不用 343、计划模式里做什么 369、例子 927、注意事项 302。ZCode 是几乎相同的 4,011 字符(`plan-mode-prompts.ts:5-98`),区别是标了 `shouldDefer`。Codex 没有这个工具:计划模式是用户切换的协作模式,模型侧只有 `request_user_input` 写着「只在 Plan 模式可用」。 + +**ExitPlanMode(1,849)**:工作方式 401、何时用 308、使用前 443、例子 567。ZCode 1,917,内容相近。Codex 无。 + +**ShowUI(6,505)**:何时用 708、调用协议(同一个工具的不同输入)886、强制步骤 609、组件清单和选择规则 1,431、operations 775、revision 规则 447、布局尺寸 348、中文目录说明 241、其他约 1,060。另两家没有对应工具(ZCode 有 visualize 插件,headless 默认未加载,未核实)。 + +**Kanban(合计 7,385)**:KanbanUpdate 4,774 里,按角色(owner / owner 或 creator / reviewer / creator)写的权限和流程约 3,200,其余是通用规则和文本长度约束;Create 1,334、Get 685、List 592。另两家没有。 + +**Task×4(合计 6,119)**:TaskCreate 2,146(何时用 807、何时不用 430、字段 401、技巧 228);TaskUpdate 2,243(何时用 961、字段 583、例子 431);TaskList 998;TaskGet 732。ZCode 是 TodoWrite 370 + TodoRead 34。Codex 的 `update_plan` 默认不注册,计划规则写在提示词 Planning 节(`prompt.md:52-121`,3,061 字符)。 + +**AskUserQuestion(1,074 描述 + 1,860 schema describe)**:用途 282、使用说明 292、计划模式说明 496。ZCode 1,785,多了「只在被一个必须由用户决定的问题卡住时才用」一段和 preview 说明。Codex `request_user_input` 描述 120,选项规则写在 schema describe 里(2–3 个选项、推荐项放第一个)。 + +**Read(1,680)**:开头 290;用法 1,388,其中有图片(「Claude Code is a multimodal LLM」)、PDF、notebook、截图、目录、空文件各一条。ZCode 736,PDF 句只在模型支持 PDF 时加(`read-pdf.ts:69-80`)。Codex 没有读文件工具,图片用 `view_image`(124)。 + +### Q4 产品功能类工具 + +DreamCoder: + +| 工具 | 字符 | 开关 | 不用该功能的会话里会不会用到 | +|---|---|---|---| +| ShowUI | 6,505 | `DREAMCODER_SHOW_UI`,服务器总设 | 用户随口要求「画个图」时会用 | +| KanbanUpdate / Create / Get / List | 4,774 / 1,334 / 685 / 592 | `isSessionLinksEnabled()`,服务器总设 | 只在会话关联了卡片或用户问看板时 | +| StartSession | 1,880 | 同上 | 用户要求另开会话时 | +| SendMessage | 1,551 | 同上(或 agent teams) | 回复其他会话发来的 ``、续接子 agent 时要用 | +| ListSessions / RenameSession | 471 / 259 | 同上 | 用户要求改名时 | +| ArtifactCheck / ArtifactCopy | 871 / 608 | 无开关 | 只在 artifact 流程里 | +| ChooseDesignTemplate / UseDesignSystem | 914 / 821 | 无开关 | 只在 design/slides skill 里(描述自己写着「Use this in the design or slides skill」) | + +合计 21,265 字符,每个请求都发。开关位置:`src/server/services/conversationService.ts:1052-1058` 对每个会话无条件设置;ArtifactCheck 等 4 个工具用 `buildTool` 默认 `isEnabled: true`。除 SendMessage 外,这些工具都没有 `shouldDefer`(全仓 `shouldDefer: true` 只出现在 Ask/Plan/Worktree/Notebook/Task*/SendMessage/WebFetch/WebSearch/Team*/MCP 资源等工具上),所以即使 ToolSearch 打开也照样全量发送。 + +ZCode 的决定方式: +- 会话控制:只有可信启动绑定给了 `sessionControlKind` 才注册,并按 cli/app 选不同变体(`zcode:core/src/tool/handlers/index.ts:240-258`)。 +- Cron、OffPeak、插件发现、话题资源:以宿主注入的端口是否存在为门(`zcode:core/src/tool/handlers/index.ts:288-317`、`zcode:core/src/runtime/helpers/runtime-tools.ts:73-90`)。 +- 动态工作流:灰度门或 `--workflow-mode`,同时管工具和描述里的引用(`zcode:core/src/tool/handlers/index.ts:308-329`、`:362-373`)。 +- node_repl:由 browser-use 插件推导的 runtime feature 决定(`zcode:core/src/tool/handlers/index.ts:330-332`)。 +- 这些工具都标 `shouldDefer`;ToolSearch 打开时只留名字。 + +Codex 的决定方式:feature 开关(Goals、Collab、ToolSuggest+Apps+Plugins)、模型目录字段(`experimental_supported_tools`、`supports_search_tool`、`apply_patch_tool_type`)、provider 能力(`web_search`、`image_generation`)、登录方式(图片生成、history/notes 要 OpenAI/Codex 后端鉴权)、配置(`tools.update_plan`)。见 `codex:core/src/tools/spec_plan.rs:718-818`、`:1287-1436`。 + +### Q5 延迟加载机制 + +| | Codex | ZCode | DreamCoder | +|---|---|---|---| +| 机制 | `tool_search`(Responses 原生工具类型)+ `defer_loading` + `tool_search_output` 条目带回工具定义 | native:`ToolSearch` + `defer_loading`;local:`LocalToolSearch` 返回 schema 文本 + `DeferredToolCall({name,input})` | `ToolSearch` + `defer_loading` + `tool_result` 里的 `tool_reference` 块 | +| 启用条件 | 模型目录 `supports_search_tool` 且有 deferred 工具(`spec_plan.rs:393-417`) | `--toolsearch-mode auto/native/local`,默认 off(`zcode:core/src/tool/search/exposure.ts:18-35`) | `ENABLE_TOOL_SEARCH` 未设时默认 tst,但 base URL 不是 Anthropic 就关(`src/utils/toolSearch.ts:270-312`) | +| 本场景 | 关(fallback `supports_search_tool: false`) | 关(默认 off) | 关 | +| 需要 provider 支持吗 | 需要 Responses API 支持 `tool_search` 类型和 `tool_search_output` 条目(`codex:tools/src/tool_spec.rs:27-32`) | native 需要 Anthropic Messages(`exposure.ts:24-27`);local 只要求模型支持 tool call(`exposure.ts:31-33`) | 需要 Anthropic 的 tool search beta:接受 `defer_loading` 字段,并在服务端展开 `tool_reference` | +| 任意 chat-completions 端点能否用 | 不能(整个 Codex 都不能接 chat) | local 能 | 不能 | +| 发现后工具数组 | 不变(定义通过对话条目送入) | local 不变(`exposure.ts:107-116`,deferred 工具始终不进数组,压缩后才提升);native 会加 | 会加:已发现的工具下一请求加入数组(`src/services/api/claude.ts:1196-1212`) | + +DreamCoder 关闭的确切原因:`isToolSearchEnabledOptimistic()` 在 `ENABLE_TOOL_SEARCH` 未设、`getAPIProvider()==='firstParty'`、`!isFirstPartyAnthropicBaseUrl()` 时返回 false(`src/utils/toolSearch.ts:297-310`),注释说明第三方网关通常不接受 `tool_reference` 块会 400。本场景 base URL 是本地代理,服务器不设 `ENABLE_TOOL_SEARCH`。 + +如果强行设 `ENABLE_TOOL_SEARCH=true` 走代理(推断,基于代码路径):CLI 端会只发未延迟的工具和已发现的工具(`src/services/api/claude.ts:1174-1212`),这部分逻辑在客户端;但代理把 `tool_result` 里的 `tool_reference` 块转成 `[omitted content: tool_reference]`(`src/server/proxy/transform/toolArguments.ts:29-48`),`defer_loading` 字段被丢掉(`anthropicToOpenaiChat.ts:47-58` 只取 name/description/input_schema)。模型看不到搜索结果里的 schema,只能等下一请求工具出现在数组里;每次发现都改变工具数组,影响前缀缓存。另外 DreamCoder 的 deferred 集合在本场景里约 21.1K 字符(Ask、Plan×2、Worktree×2、Notebook、SendMessage、Task×6、WebFetch),12 个产品工具(约 19.7K)不在其中。 + +Codex 的 namespace(`multi_agent_v1`)和 code mode:namespace 是 Responses API 的 `type: "namespace"` 工具(`codex:tools/src/tool_spec.rs:25-26`),由 `merge_into_namespaces` 合并(`spec_plan.rs:1104-1130`),第三方 Responses 端点是否接受未核实。code mode(把工具包进一个 JS 执行工具)由 `Feature::CodeMode`(默认关)或模型目录 `tool_mode` 打开,fallback 为 None,本场景关。 + +### Q6 工具顺序和会话内稳定性 + +| | Codex | ZCode | DreamCoder | +|---|---|---|---| +| 排序规则 | 注册顺序(`IndexMap`,`codex:core/src/tools/registry.rs:330-331`),托管工具追加在后,再合并 namespace(`spec_plan.rs:628-656`) | 固定名单内按名字排(固定 en-US locale),名单外按注册顺序,MCP 按名字排在最后(`zcode:core/src/tool/provider-visible-order.ts:41-66`) | 内置按名字 `localeCompare`,MCP 按名字排在后(`src/tools.ts:383-387`、`src/utils/toolPool.ts:65-70`) | +| 重建频率 | 每轮重建 router(`codex:core/src/session/turn.rs:1977`),输入相同则结果相同 | 缓存到工具集变化(`config.ts:140-163`) | 每请求组装;描述和 schema 按会话缓存(`src/utils/api.ts:136-152`) | +| 会话内会变的情况 | MCP 增减 | MCP 增减;native 模式发现工具 | MCP 增减;ToolSearch 发现工具(本场景关);Agent 描述依赖 agent 列表,但被会话缓存固定 | +| 描述是否随会话状态变化 | 否(推断) | 否;按模型能力投影一次 | 否(会话缓存);DreamCoder 的 locale 未固定(`localeCompare` 不带 locale),ZCode 修过这个问题(`provider-visible-order.ts:60-62`) | + +--- + +## 3. 对 DreamCoder 的含义 + +### DreamCoder 有、另两家都没有的 + +事实: +- **工具描述里的 git 提交和 PR 流程**,6,253 字符,每个请求都发。ZCode 的 Bash 只写三行 git 规则;Codex 在提示词里写两行。 +- **13 个产品功能类工具**,21,265 字符,由服务器无条件打开,4 个无开关;除 SendMessage 外都不在 deferred 集合里。 +- **agent 列表内联在 Agent 描述里**,1,815 字符;ZCode 放 system-reminder 消息,Codex 放参数 describe。 +- **Glob、Grep、NotebookEdit、Task×4、Worktree×2 这些细分工具**,加上 Bash 里约 1K 字符告诉模型别用 shell 做这些事。两家都把搜索并入 shell。 +- **发给非 Claude 模型的 Claude 专属文本**:Read 的「Claude Code is a multimodal LLM」和 PDF 说明、Bash 的 `Co-Authored-By: Claude Opus 4.7`、Agent 的 `sonnet/opus/haiku` 枚举、statusline-setup agent。 +- **KanbanUpdate 的 15 分支 union schema**(约 4–5K 字符)。 + +后果: +- token(事实 + 推断):工具块约 82–86K 字符,约 21K token(4 字符/token 推断),是 ZCode 的 3 倍左右、Codex 的 6 倍左右。按每个任务几十个请求算,仅工具定义就是几十万到上百万 input token(推断)。缓存命中时按缓存价计;C 维度报告的计费头问题如果让前缀缓存失效,这部分每次按全价计。 +- 轮数(推断):EnterPlanMode 和 TaskCreate 的描述都要求「proactively」使用,headless 编码任务里可能多出进入/退出计划模式和逐步更新任务的调用;Codex 默认不给计划工具,ZCode 在 ToolSearch 开时把计划工具延迟。 +- 可靠性(推断):工具多、名字相近(TaskCreate/TaskUpdate 与 TaskOutput/TaskStop,SendMessage 与 StartSession)、union schema 大,非原生模型选错工具或构造错参数的机会更多;Claude 专属文本可能让模型写出错误的署名或误判自己能读图和 PDF。 + +### 另两家都有、DreamCoder 没有的 + +事实: +- **按运行时能力决定工具集。** Codex 按模型目录字段、provider 能力、鉴权;ZCode 按宿主注入的端口、可信绑定和模型属性。DreamCoder 的开关是服务器对每个会话都打开的环境变量,与本会话是否用到这些功能无关;模型相关的判断只有 WebSearch(看模型名像不像 Claude)和 PDF(只排除 `claude-3-haiku`)。 +- **搜索并入 shell。** Codex 用 `rg`,ZCode 用 embedded `find`/`grep`。 +- **短的 shell 工具描述**:82 和 1,121 字符,对比 10,003。 +- **长的行为规程不放在工具描述里,或放在可以延迟的工具上。** Codex 放在系统提示词;ZCode 把计划模式、会话控制、TaskOutput/TaskStop 等标为 `shouldDefer`。 + +后果: +- token(事实):同类能力,DreamCoder 在工具定义上花的字符明显更多,而且没有一种在本场景下可用的手段把不用的工具移出请求。 +- 在非原生模型上(推断):只有 ZCode 的 local 模式证明了延迟加载可以在普通 chat-completions 端点上工作,并保持工具数组不变(对前缀缓存友好)。DreamCoder 已有客户端侧的过滤逻辑,缺的是代理对 `tool_reference` 的转换,以及把产品工具纳入 deferred 集合。这里只陈述差异,不提方案。 + +--- + +## 4. 没有核实的地方 + +- DreamCoder 浏览器 MCP(`dreamcoder-browser`,15 个工具)的描述长度未测;它只在桌面端浏览器宿主已连接时出现(`src/server/browserHost/childEnv.ts:14-27`)。 +- DreamCoder 自定义 agent、插件 agent 会让 Agent 描述变长,未计入。 +- 三家的 schema JSON 大小都是根据 describe 文本和字段数推断的,没有生成真实 JSON。 +- ZCode:自定义模型的 `supportsNativeWebSearch` 默认值未核实(只确认了就算为真也无法在 chat-completions 上编码);headless 下随 CLI 加载的内置插件是否带工具或 MCP 未核实;Agent 参数个数是估计。 +- Codex:`spawn_agent` 描述里的模型列表长度未核实(取决于目录中 picker 可见的模型);goal 工具依赖 app-server 有 state_db,`codex exec` 路径下是否总有 state_db 未逐行核实;skills 扩展工具默认不发是推断;第三方 Responses 端点是否接受 `namespace` 类型工具和托管 `web_search` 未核实。 +- 「每个任务几十个请求」与 token 换算(4 字符/token)是推断,没有实测。 From e68ade0a5e81cab73187695b6f3ed7c9cd05f963 Mon Sep 17 00:00:00 2001 From: Diao Shengjia <104132148+GoDiao@users.noreply.github.com> Date: Tue, 17 Nov 2026 22:38:29 +0800 Subject: [PATCH 2/4] docs(harness): add the proxy layer review against Codex CLI and ZCode --- docs/features/harness/README.md | 18 +- docs/features/harness/proxy/request.md | 275 +++++++++++++++++++++++ docs/features/harness/proxy/response.md | 252 +++++++++++++++++++++ docs/features/harness/proxy/transport.md | 262 +++++++++++++++++++++ 4 files changed, 806 insertions(+), 1 deletion(-) create mode 100644 docs/features/harness/proxy/request.md create mode 100644 docs/features/harness/proxy/response.md create mode 100644 docs/features/harness/proxy/transport.md diff --git a/docs/features/harness/README.md b/docs/features/harness/README.md index 27ae8a4d..d9c5a11b 100644 --- a/docs/features/harness/README.md +++ b/docs/features/harness/README.md @@ -1,6 +1,6 @@ # Harness 调整 -状态:调研完成,改造方案未定。本文是总览;五个维度的详细对比在 [comparison/](comparison) 下。 +状态:长期进行,跟踪见 [RFC: Harness evolution](https://github.com/GoDiao/dreamcoder/issues/261)。本文是总览;五个维度的详细对比在 [comparison/](comparison) 下,代理层的专项评审在 [proxy/](proxy) 下。 ## 背景 @@ -118,6 +118,22 @@ DreamCoder 的 CLI 派生自 Claude Code 2.1.92(`src/constants/claudeCodeCompa - 记忆说明保留多少。 - 产品工具按什么条件发送(会话是否用到该功能,或一律延迟加载)。 +## 代理层专项评审 + +第一个落地的区域是 CLI 和第三方提供方之间的代理层(`src/server/proxy`、`src/server/upstream`,以及相关的提供方配置)。三份评审逐项对照了 Codex 和 ZCode,共 45 条发现,每条写了现状、场景、两家做法、改法方向和确定程度: + +| 文件 | 范围 | 编号 | +|---|---|---| +| [proxy/request.md](proxy/request.md) | 请求方向:从 CLI 的请求到发往上游的字节 | P-REQ-01 到 16 | +| [proxy/response.md](proxy/response.md) | 响应方向:从上游的流到 CLI 收到的 Anthropic 格式 | P-RES-01 到 15 | +| [proxy/transport.md](proxy/transport.md) | 传输、容错和提供方配置 | P-NET-01 到 14 | + +按三批处理,每批一个 issue,挂在 RFC 下面: + +1. 请求通路的基础问题:计费行、60 秒空闲断开和流空闲超时、base URL、取消传到上游、`NO_PROXY`、缓存键和缓存命中统计,以及请求头配置、日志、`count_tokens` 等小项。 +2. 上下文、错误和流的健壮性:上下文溢出识别、用量为 0、错误结构化和 `retry-after`、重试分类、结束原因映射、流提前结束和流中错误。 +3. 按模型的能力:先设计一张按模型的规则表,再接上推理强度和思考开关、能力声明、推理数据回传、图片和 PDF、上下文窗口和输出上限。 + ## 详细报告 | 维度 | 文件 | 内容 | diff --git a/docs/features/harness/proxy/request.md b/docs/features/harness/proxy/request.md new file mode 100644 index 00000000..553f4aad --- /dev/null +++ b/docs/features/harness/proxy/request.md @@ -0,0 +1,275 @@ +# 代理层评审:请求方向(P-REQ) + +范围:CLI 发出的 Anthropic Messages 请求,经本地代理变成发往上游的 HTTP 请求(URL、头、body),覆盖 `openai_chat` 与 `openai_responses` 两种上游格式,以及经代理的辅助请求和服务端标题请求的请求侧。 + +路径约定:DreamCoder 相对仓库根;`codex:` 相对 `refs/coding-agents/codex/codex-rs`;`zcode:` 相对 ZCode 仓库根(`refs/coding-agents/zcode`)。ZCode 规则文件 `zcode:config/provider/zcode-builtin.json` 里的规则按解析后的数组下标写,例如 `modelApiRules[37]`、`providerSiteRules[49]`(均在 `.config.modelConfigRules` 下)。 + +静态阅读为主;另运行了 DreamCoder 现有测试 `src/server/__tests__/proxy-transform.test.ts`、`src/server/__tests__/upstream-client.test.ts`、`src/utils/claudeCodeCch.test.ts`(66 个通过),并用仓库自带的 zod 打印了一个 schema 样例,确认 `toJSONSchema` 的输出形状。没有对任何模型提供方发请求;凡是依赖提供方文档的结论都标「未核实」。 + +## 1. 发现清单 + +### P-REQ-01 代理给每个请求的 system 首行加计费行,`cch` 随整个请求体变化,提供方前缀缓存从第一行起失配 + +- 类型:问题 +- 严重程度:高 +- 现状(按执行顺序): + 1. 服务端按模型名给 CLI 设 `CLAUDE_CODE_ATTRIBUTION_HEADER`:模型名不以 `claude` 开头时为 `0`(`src/server/services/attributionHeaderPolicy.ts:3-15`,注入点 `src/server/services/providerRuntimeEnv.ts:251`),CLI 因此不加计费行(`src/constants/system.ts:52-57`)。 + 2. 代理收到请求后无条件调用 `ensureClaudeCodeAttribution`(`src/server/proxy/handler.ts:64`):只要 system 里没有以 `x-anthropic-billing-header:` 开头的块,就在最前面插一块 `x-anthropic-billing-header: cc_version=2.1.92.<指纹>; cc_entrypoint=unknown; cch=00000;`(`src/server/proxy/claudeCodeAttribution.ts:29-46`,格式 `src/constants/claudeCodeCompatibility.ts:10-17`)。它不看模型名,也不看第 1 步的环境变量,所以第 1 步对经代理的请求不起作用。 + 3. 转换时 system 各块用 `\n` 拼成一条 role=system 消息(`src/server/proxy/transform/anthropicToOpenaiChat.ts:19-26`)或 Responses 的 `instructions`(`src/server/proxy/transform/anthropicToOpenaiResponses.ts:24-30`),计费行在最前。 + 4. `JSON.stringify` 后再签名:`cch` = 对**整个转换后请求体字符串**做带种子的 xxHash64 取低 20 位(`src/server/upstream/client.ts:214,222`;`src/utils/claudeCodeCch.ts:27-58,135-139`)。请求体含全部历史,所以每个请求的 `cch` 都不同。 + 5. 模型名以 `claude` 开头时(例如中转站用 OpenAI 格式卖 `claude-sonnet-4-5`),CLI 自己加计费行并在 fetch 包装里按 Anthropic 请求体签名(`src/services/api/client.ts:461`),代理看到已有计费行就不再加(`claudeCodeAttribution.ts:30,49-57`),转换后不再含 `cch=00000`,不会重签;`cch` 仍逐请求变化。 +- 用途与依赖:文件头注释说明这段逻辑取自 sub2api(`claudeCodeAttribution.ts:1-4`;常量注释「accepted by upstream billing validation」`claudeCodeCompatibility.ts:6`),用途是让 Anthropic 订阅类中转站把请求认作 Claude Code。代理只服务 `openai_chat` / `openai_responses`(`handler.ts:39-52` 拒绝 anthropic 格式),在仓库内 grep 不到任何读取或校验这行的下游代码(只有 `handler.ts`、`upstream/client.ts`、CLI 的 `client.ts` 三处写入)。OpenAI 格式的上游没有已知的校验方(推断)。服务端标题请求直接调 `sendToUpstream`,不经过 `ensureClaudeCodeAttribution`,是唯一不带这行的请求(`src/server/services/titleService.ts:83-89`)。 +- 场景:Qwen 预设(`openai_chat`,`src/server/config/providerPresets.json:28-42`)或任何自定义 OpenAI 格式提供方。同一会话第 N 与第 N+1 个请求的 system 只有第 79–83 个字符不同(`cch` 的 5 位)。DashScope、DeepSeek、OpenAI、Kimi 等按前缀自动缓存的提供方在第一行就失配,system、工具定义(约 3 万 token 量级,见 request-cache.md Q7)和全部历史每个请求都按未命中计费。子代理、WebFetch 二次处理、压缩请求同样带这行。这行 84 个字符本身也作为普通文本进入模型上下文。 +- 参考:Codex 的前缀逐请求不变,并有测试断言第 N 个请求的 input 是第 N+1 个的前缀(`codex:core/tests/suite/prompt_caching.rs`,见 request-cache.md Q2);指令项的 id 由线程 id 和文本做 UUIDv5,重试与恢复后不变(`codex:core/src/client.rs:1010-1041`)。ZCode 的 system 首行固定(`You are ZCode…`),无此类内容。两者都没有计费行。 +- 改法方向:代理对 `openai_*` 目标不再插入计费行、不再签名(删除 `handler.ts:64` 的调用和 `client.ts:214,222` 的签名),与 `attributionHeaderPolicy` 的意图一致;如果确有「OpenAI 格式中转 Claude」的需求,按模型名沿用 CLI 自带的那一行,作为单独的产品决定处理。 +- 确定程度:代码确认(缓存失配的计费影响为推断,未测量) + +### P-REQ-02 Effort 与思考开关在两种 OpenAI 格式上都到不了上游 + +- 类型:问题 +- 严重程度:高 +- 现状: + 1. 自定义提供方三档模型都声明 `thinking,effort,adaptive_thinking,max_effort`(`src/server/services/providerRuntimeEnv.ts:38,229-236`),CLI 因此发 `thinking:{type:'adaptive'}`(`src/services/api/claude.ts:1649-1659`),并在用户设置了 Effort 时写 `output_config.effort`(`claude.ts:439-455,1603-1614`;`src/utils/effort.ts:23-49`)。关闭思考时 CLI 发 `thinking:{type:'disabled'}` 并删掉 effort(`claude.ts:1600-1607,1674-1678`)。 + 2. Qwen 预设没有能力声明,模型名不含 sonnet/opus,`modelSupportsThinking` 为假,CLI 不发 thinking;`modelSupportsEffort` 对未知模型名在 firstParty 下为真(`effort.ts:47-49`),会写 `output_config.effort`。 + 3. 代理的 `AnthropicRequest` 类型里没有 `output_config`(`src/server/proxy/transform/types.ts:161-181`),effort 被丢弃。chat 只在 `budget_tokens` 存在或 `type==='enabled'` 时写 `reasoning_effort`(`anthropicToOpenaiChat.ts:64-72`),Responses 同理写 `reasoning.effort`(`anthropicToOpenaiResponses.ts:51-60`)。`adaptive` 和 `disabled` 都不产生任何字段。 + 4. 唯一例外:baseUrl 含 `deepseek` 或 `opencode.ai` 时,chat 原样透传 `thinking:{type: body.thinking.type}`(`anthropicToOpenaiChat.ts:73-75`;`src/server/upstream/client.ts:206-210,251-256`),自定义提供方下传的是 `adaptive`。 + 5. 带 budget 的分支只有在关闭 adaptive(`CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`)或能力声明不含 adaptive 时才走到,桌面现有配置下等于没有用到。 +- 场景: + - 自定义 `openai_chat` 接 Kimi(`https://api.moonshot.cn/v1`,`kimi-k2.6`),桌面把 Effort 设为 low 或关闭思考:上游请求里没有 `thinking`、`reasoning_effort`,模型按默认(思考开)运行,设置无效。 + - Qwen 预设 `qwen-plus`:无法打开思考(DashScope 用 `enable_thinking`,未核实其默认值),Effort 选择器无效果。 + - 自定义 `openai_chat` 接 `https://api.deepseek.com`:每个请求带 `thinking:{type:"adaptive"}`。ZCode 对 DeepSeek chat 只发 `enabled`/`disabled`;DeepSeek 是否接受 `adaptive` 未核实(若拒绝则每个请求 400,若忽略则用户的开关不生效)。 + - 自定义 `openai_responses` 接 OpenAI `gpt-5.x`:Effort 不进入 `reasoning.effort`。 +- 参考: + - ZCode:每个模型/协议有字段映射。通用 chat 映射同时写 `thinking.type`、`enable_thinking`、`reasoning_effort`(disabled→`none`)、`reasoning.effort`(`modelApiRules[2]`);Responses 通用映射写 `reasoning.effort`(`modelApiRules[3]`);DeepSeek v4 chat 写 `thinking.type` + `reasoning_effort`(`modelApiRules[37],[39],[63],[67]`),DeepSeek 官方 Responses 写 `reasoning.effort`(`providerSiteRules[42]-[44]`);Kimi k2.5/k2.6 chat 写 `thinking.type`(`modelApiRules[33],[35]`),k3 写 `reasoning_effort`(`[24],[26]`);Qwen plus/flash/3.x 写 `enable_thinking`(`[44],[46],[48],[50],[69]`),qwen3.8 写 `reasoning_effort`(`[41]`);OpenRouter 上部分模型写 `reasoning:{effort}` 或 `reasoning:{enabled:false}`(`providerSiteRules[49],[50]`)。默认档取最高(见 model-adaptation.md Q3)。 + - Codex:`reasoning.effort` 与 `reasoning.summary`(`codex:core/src/client.rs:957-976`)。 +- 改法方向:在代理请求类型中加入 `output_config`,把「effort 档位 + thinking 开/关」按上游格式写到对应字段:Responses 写 `reasoning.effort`(关闭时 `none`);chat 先按 ZCode 通用映射的做法写一组通用字段,再按模型/站点覆盖(DeepSeek、Kimi、Qwen、OpenRouter);不再透传 `adaptive` 这个 Anthropic 专有值。 +- 确定程度:代码确认(各提供方对字段的接受情况未核实) + +### P-REQ-03 PDF(document 块)在两种格式上被静默丢弃,模型只看到「已读取」 + +- 类型:问题 +- 严重程度:高 +- 现状: + 1. Read 工具读整份 PDF 时,tool_result 只写 `PDF file read: <路径> (<大小>)`(`src/tools/FileReadTool/FileReadTool.ts:670-676`),PDF 内容放在随后一条 meta user 消息的 `document` 块里(`FileReadTool.ts:997-1011`)。是否走这条路只看 `isPDFSupported()`,它只排除 `claude-3-haiku`(`src/utils/pdfUtils.ts:59-61`),对第三方模型都为真。 + 2. chat 转换 `convertUserMessage` 只处理 text、image、tool_result(`anthropicToOpenaiChat.ts:108-121`),`document` 块没有分支,被直接跳过;Responses 转换同样只处理 text、image、tool_use、tool_result(`anthropicToOpenaiResponses.ts:82-105`)。只有出现在 tool_result 内部时才会留下 `[omitted content: document]`(`src/server/proxy/transform/toolArguments.ts:43-44`)。 +- 场景:Qwen 预设或任何自定义 OpenAI 格式提供方,用户让模型「读一下 spec.pdf 并总结」。模型调用 Read,收到「PDF file read: spec.pdf (120KB)」,后面没有任何内容,也没有提示内容缺失;模型据此编造总结,或认为已读而不再尝试 `pages` 参数(该参数会把页面转成图片,见 `FileReadTool.ts:886-944`)。 +- 参考:ZCode 对 file 块:模型声明支持 PDF 时作为 SDK file part 发送,不支持时换成明确的「不支持该媒体」文本(`zcode:apps/zcode-cli/packages/adapters/src/model/transform.ts:540-563`;`zcode:apps/zcode-cli/packages/adapters/src/model/media-transform-policy.ts:8-15`;基线规则 `supportsPdf:false`,`modelRules[0]`)。Codex:无 PDF 读取。 +- 改法方向:代理对 `document` 块不再静默跳过:模型支持 PDF 输入时转成 chat 的 file 内容块 / Responses 的 `input_file`,否则换成一段明确文本(说明 PDF 未送达、可用 `pages` 参数按页读取);或由服务端告知 CLI 当前提供方不支持 PDF,让 `isPDFSupported` 为假。 +- 确定程度:代码确认 + +### P-REQ-04 工具结果里的图片被换成文字占位,视觉模型看不到截图 + +- 类型:问题 +- 严重程度:高 +- 现状:tool_result 的内容块经 `extractToolResultContent` 拍平成字符串,图片变成 `[image omitted: ]`(`toolArguments.ts:29-38`),chat(`anthropicToOpenaiChat.ts:114-120`)和 Responses(`anthropicToOpenaiResponses.ts:98-104`)都这样。产生图片结果的工具:Read 读图片(`FileReadTool.ts:650-666`)、Bash 输出 data URI(`src/tools/BashTool/utils.ts:71-90`)、内置浏览器截图(MCP 内容 `{type:'image'}`,`src/server/browserHost/service.ts:826`)以及其他返回图片的 MCP 工具。 +- 场景:自定义 `openai_chat` 接一个视觉模型(例如 `qwen3-vl-plus` 或 OpenRouter 上的 Claude/GPT),用户让 agent 在内置浏览器里检查页面布局。截图工具返回 JPEG,上游只收到 `[image omitted: image/jpeg]`,模型无法完成任务,通常会反复截图,多花轮数。 +- 参考: + - ZCode(chat):tool 消息里保留文本,图片移到紧随其后的一条 user 消息,并按模型输入能力决定保留还是换成说明文字(`zcode:apps/zcode-cli/packages/adapters/src/model/transform.ts:59-66,120-151`;`tool-result-media-projection.ts:26-39`)。 + - Codex(Responses):`function_call_output` 的内容项支持 `input_image`(`codex:protocol/src/models.rs:2249-2261`)。DreamCoder 的 Responses 路径本可直接带图,却同样拍平。 +- 改法方向:chat 路径把同一条 user 消息里所有 tool_result 的图片收集起来,在这些 tool 消息之后追加一条 user 消息放图片(文字留在 tool 消息里,并注明图片在下一条);Responses 路径把图片作为 `function_call_output.output` 数组里的 `input_image`。是否发送图片取决于 P-REQ-11 的模型图像能力。 +- 确定程度:代码确认 + +### P-REQ-05 `max_tokens` 不转发;上游按自身默认值截断,CLI 的截断提示与实际不符 + +- 类型:问题 +- 严重程度:中 +- 现状:CLI 对第三方模型默认 `max_tokens: 32000`(`src/utils/context.ts:203-262`;`src/services/api/claude.ts:3454-3474`,放进请求 `claude.ts:1765`)。`OpenAIChatRequest` 有 `max_tokens`、`max_completion_tokens` 字段但没有任何赋值(`types.ts:35-36`;`anthropicToOpenaiChat.ts:32-76`),`OpenAIResponsesRequest.max_output_tokens` 同样无赋值(`types.ts:112`;`anthropicToOpenaiResponses.ts:17-62`)。直接照抄 32000 也不行:它不是按模型给出的值。 +- 场景: + - 自定义 `openai_chat` 接 `https://api.deepseek.com`、模型 `deepseek-chat`:上游默认输出上限较小(外部文档记忆为 4K,未核实),Write 一个较大的文件时参数被截断,`finish_reason: length` → `max_tokens`,CLI 提示「exceeded the 32000 output token maximum」(`claude.ts:2316-2326`),被截断的工具参数解析失败后由 zod 报错回给模型,多出重试轮次。 + - 反方向:如果简单转发 32000,`qwen-max` 这类输出上限为 8192 的模型会直接 400(未核实具体上限)。 + - 压缩请求不设输出上限(`src/services/compact/compact.ts:1177-1191`),标题请求的 `max_tokens: 100`(`titleService.ts:8,85`)也被丢弃。 +- 参考:ZCode 每步发 `min(模型输出上限, 窗口 − 估算输入 − 1000)`,模型未声明时 32K(`zcode:apps/zcode-cli/packages/core/src/runtime/methods/model-token-limits.ts:5-41`),chat 写 `max_completion_tokens`、Responses 写 `max_output_tokens`(`modelApiRules[2],[3]`),部分站点改写 `max_tokens` 并给出模型上限(`providerSiteRules[0]-[14]`);适配层校验不超过模型上限(`zcode:apps/zcode-cli/packages/adapters/src/model/model.ts:112-121`)。Codex 不发送输出上限。 +- 改法方向:代理把 `max_tokens` 写到上游字段(chat 默认 `max_tokens`,可按站点换 `max_completion_tokens`;Responses 写 `max_output_tokens`),并按模型上限截取;模型上限来自 provider 配置或模型列表,没有时不发送而不是发 32000。 +- 确定程度:代码确认(各提供方默认值未核实) + +### P-REQ-06 OpenAI 格式的 baseUrl 被强制改成 `<去掉 /v1 的 base>/v1/...`,路径里版本段不是 `/v1` 的端点无法接入 + +- 类型:问题 +- 严重程度:中 +- 现状:`normalizeUpstreamBaseUrl` 去掉结尾的 `/v1`(`src/server/upstream/baseUrl.ts:1-3`),然后固定拼 `/v1/chat/completions`、`/v1/responses`、`/v1/models`(`src/server/upstream/client.ts:136,212,220`)。测试也按这个行为写(`src/server/__tests__/upstream-client.test.ts:79-84`)。界面上 Base URL 的占位示例是 Anthropic 风格(`desktop/src/i18n/locales/en.ts:500`),没有说明 OpenAI 格式的写法。 +- 场景: + - 智谱 GLM 的 OpenAI 兼容端点 `https://open.bigmodel.cn/api/paas/v4`(以及 `https://api.z.ai/api/paas/v4`)→ 实际请求 `.../api/paas/v4/v1/chat/completions`,404。无论用户怎么填都拼不出正确路径。 + - 火山方舟 `.../api/v3`、Gemini 的 OpenAI 兼容端点 `.../v1beta/openai` 同理。Gemini 没有 Anthropic 兼容端点,因此在 DreamCoder 里完全无法接入(推断)。 + - 模型列表拉取(`client.ts:136`)也走同一个错误路径,连接测试就会失败。 +- 参考:Codex 把配置的 base_url(默认 `https://api.openai.com/v1`)当作完整前缀,只拼 `/responses`(`codex:codex-client/src/provider.rs:55-62`;`codex:model-provider-info/src/lib.rs:430-446`)。ZCode 把 baseURL 原样交给 AI SDK,SDK 拼 `/chat/completions` 或 `/responses`(`zcode:apps/zcode-cli/packages/adapters/src/model/model-execution.ts:333-365`)。 +- 改法方向:对 `openai_*` 把用户填写的 base 当作完整前缀,只追加 `/chat/completions`、`/responses`、`/models`;对已保存的、路径为空的 OpenAI 格式提供方(例如 `https://api.openai.com`)在读取时补 `/v1`,保证磁盘上已有配置继续可用;界面按格式给出示例。 +- 确定程度:代码确认(各端点路径来自外部文档记忆,未核实) + +### P-REQ-07 历史推理内容只对 deepseek / opencode.ai 域名回传,判断依据是域名而不是模型或上游实际返回的字段 + +- 类型:问题 +- 严重程度:中 +- 现状:`shouldUseDeepSeekReasoningCompat` 只看 baseUrl 是否含 `deepseek` 或 `opencode.ai`(`src/server/upstream/client.ts:251-256`),命中时同时打开两件事:把历史 thinking 写回 `reasoning_content`、透传 `thinking.type`(`client.ts:206-210`;`anthropicToOpenaiChat.ts:73-75,146-147,168-170`)。其他上游的历史 thinking 全部丢弃。Responses 路径从不回传推理(见 P-REQ-08)。响应侧把 `reasoning_content` / `reasoning` / `thinking_blocks` 都转成 thinking 块,signature 为空(见 model-adaptation.md Q2),请求侧因此不知道这段推理原来来自哪个字段。 +- 场景: + - 自定义 `openai_chat` 接 Kimi(`api.moonshot.cn`)的思考模型,多步工具调用:上一步的 `reasoning_content` 不回传。Moonshot 对思考模型在工具调用循环中要求保留 `reasoning_content`(外部文档,未核实是报错还是质量下降)。 + - DeepSeek 模型经 SiliconFlow、OpenRouter 等其他域名提供:不命中域名,推理丢失,思考开关也不透传。 + - opencode.ai 上的 GLM、Kimi 等非 DeepSeek 模型:也会被透传 `thinking:{type:"adaptive"}`;ZCode 对 opencode go 的这些模型只写 `reasoning_effort` 或什么都不写(`providerSiteRules[0]-[14]`)。 +- 参考:ZCode 按模型把推理作为 reasoning part 交给 SDK,并在请求前规范化推理历史(跨模型的推理会去掉),空推理不写(`zcode:apps/zcode-cli/packages/adapters/src/model/transform.ts:371-394`;`zcode:apps/zcode-cli/packages/adapters/tests/openai-compatible-extra-body-wire.test.ts:106-133`);SDK 是否把非空推理写成 `reasoning_content` 未核实。Codex(Responses)回传 reasoning item 和 `encrypted_content`,对非 OpenAI 提供方也保留(`codex:core/src/client.rs:1048-1059,1075`)。 +- 改法方向:响应侧把推理来源字段记在 thinking 块上(例如写进现在为空的 signature),请求侧按这个记录写回同名字段;思考开关的写法并入 P-REQ-02 的按模型映射,不再与推理回传绑在同一个域名判断上。 +- 确定程度:代码确认(各提供方是否要求回传未核实) + +### P-REQ-08 Responses 路径不回传 reasoning item、不请求 `encrypted_content`、不请求推理摘要 + +- 类型:问题 +- 严重程度:中 +- 现状:Responses 请求固定 `store:false`(`anthropicToOpenaiResponses.ts:17-22`),没有 `include`、没有 `reasoning.summary`(`types.ts:107-125`);历史中的 thinking 块在 `convertMessageToInputItems` 里没有分支,被丢弃(`anthropicToOpenaiResponses.ts:82-105`)。 +- 场景:自定义 `openai_responses` 接 OpenAI `gpt-5.x`,一个回合内连续多次工具调用。`store:false` 下没有 `encrypted_content`,前一步的推理无法带入下一步,模型每步重新推理,输出 token 和延迟增加(OpenAI 文档建议在函数调用中回传推理项,外部文档,未核实具体影响)。未请求摘要,桌面上也看不到这类模型的思考内容(推断,取决于提供方默认)。 +- 参考:Codex 总是带 `include: ["reasoning.encrypted_content"]`,回传 reasoning item,并在模型支持时发 `reasoning.summary`(`codex:core/src/client.rs:957-976,1075,1112-1128`)。ZCode 用 AI SDK 的 Responses 实现,并在无状态回放时只去掉 `store=true` 的 item 引用(`zcode:apps/zcode-cli/packages/adapters/src/model/transform.ts:371-385,406-416`)。 +- 改法方向:Responses 请求带 `include: ["reasoning.encrypted_content"]` 和 `reasoning.summary: "auto"`;响应侧把 reasoning item 的 id 与 `encrypted_content` 存进 thinking 块;请求侧把这类 thinking 块还原成 `{type:"reasoning", encrypted_content, summary}` 输入项。 +- 确定程度:代码确认(对模型表现的影响为推断) + +### P-REQ-09 原生 web_search 服务端工具被翻译成一个没有参数的普通函数,搜索「成功」但没有结果,也不会回退到 Tavily/Brave + +- 类型:问题 +- 严重程度:中 +- 现状: + 1. WebSearch 在模型名「像 Claude」时选原生 Anthropic 搜索(`src/tools/WebSearchTool/backend.ts:40-46,90-92,178-181`),正则对 `anthropic/claude-sonnet-4.5` 这类网关名也成立。 + 2. 原生搜索把 `{type:'web_search_20250305', name:'web_search', …}` 作为 `extraToolSchemas` 发出(`src/tools/WebSearchTool/WebSearchTool.ts:90-98,383-424`)。 + 3. 代理把每个工具都当作客户端函数:`{type:'function', function:{name, description, parameters: t.input_schema}}`(`anthropicToOpenaiChat.ts:47-58`;Responses 同样 `anthropicToOpenaiResponses.ts:35-45`)。服务端工具没有 `input_schema`,于是上游收到一个名为 `web_search`、没有参数定义的函数,`type`、`max_uses`、域名限制都丢失。 + 4. 回退到外部搜索只在出错时发生,判断依据是错误文本含 400/422 或 web_search 等字样(`backend.ts:112-120`;`WebSearchTool.ts:298-345`)。上游接受了这个函数,不报错,所以不会回退。 +- 场景:自定义 `openai_chat` 接 OpenRouter,模型 `anthropic/claude-sonnet-4.5`,并在设置里配了 Tavily key。模型调用 WebSearch → 二次请求里模型要么调用这个空参数函数(返回普通 tool_use,而不是 `server_tool_use` / `web_search_tool_result`),要么直接用文字作答;WebSearch 拿不到任何结果块,返回空结果或模型编造的文本(推断),Tavily 从未被使用。 +- 参考:ZCode 只在 anthropic-messages 且模型声明支持时编码原生搜索,其他协议直接报错(`zcode:apps/zcode-cli/packages/adapters/src/model/tool-transform.ts:250-283`)。Codex:无对应。 +- 改法方向:代理遇到带 `type` 字段的服务端工具时返回 400(错误文本含 `web_search`),让现有回退逻辑生效;更直接的做法是服务端在提供方为 `openai_*` 时告知 CLI 不使用原生搜索。 +- 确定程度:代码确认(上游与模型的具体反应为推断) + +### P-REQ-10 没有任何缓存键或会话亲和信息,CLI 已经提供的会话 id 被丢弃 + +- 类型:优化 +- 严重程度:中 +- 现状:CLI 给每个请求带 `X-Claude-Code-Session-Id` 头(`src/services/api/client.ts:155-158`)和 `metadata.user_id`(内含 `session_id`、`device_id`,`src/services/api/claude.ts:502-527,1764`),还在 system、工具和最后一条消息上标 `cache_control`。代理只读 body(`handler.ts:54-64`),类型里没有 `metadata`(`types.ts:161-181`),发往上游的头只有 `Content-Type` 和 `Authorization`(`client.ts:213,221`)。 +- 场景: + - 自定义 `openai_responses` 接 OpenAI:没有 `prompt_cache_key`,同一会话的请求可能落到不同缓存节点(OpenAI 文档说明该字段影响缓存路由,未核实命中率差异)。 + - 自定义 `openai_chat` 接 opencode.ai:ZCode 会带 `x-opencode-session`,DreamCoder 不带。 + - OpenRouter 上的 Claude / Gemini 模型、DashScope 的显式缓存,都接受 OpenAI 格式内容块上的 `cache_control`(外部文档,未核实);代理丢弃,这些模型在 OpenAI 格式下拿不到缓存。 + - 此项要在 P-REQ-01 修掉之后才有收益。 +- 参考:Codex 发 `prompt_cache_key`(默认取会话 id,子线程用 `<来源>:<父线程 id>`)和 `session-id` 头(`codex:core/src/client.rs:657-689,1124`;`codex:core/src/thread_manager.rs:271-281`;`codex:codex-api/src/requests/headers.rs:8`)。ZCode 对所有提供方发 `x-session-id`、`x-request-id` 等,对 opencode go 另发 `x-opencode-session`(`zcode:apps/zcode-cli/packages/adapters/src/model/runner-attribution.ts:35-66`);它在 chat 路径上同样不发 `cache_control`(推断,见 request-cache.md Q3)。 +- 改法方向:代理读取 `X-Claude-Code-Session-Id`,Responses 写 `prompt_cache_key`,chat 对已知支持的站点写 `prompt_cache_key` 或会话头;对已知接受 `cache_control` 的上游(OpenRouter 的 Claude/Gemini、DashScope)把断点挪到对应 OpenAI 内容块上。 +- 确定程度:代码确认(提供方支持情况未核实) + +### P-REQ-11 用户图片无条件以 `image_url` 发给上游,不看模型是否支持图像 + +- 类型:问题 +- 严重程度:中 +- 现状:user 消息里的 image 块直接转成 `image_url` data URL(`anthropicToOpenaiChat.ts:111-113`)或 `input_image`(`anthropicToOpenaiResponses.ts:85-89`)。DreamCoder 没有模型图像能力的配置(`src/server/types/provider.ts:47-60` 无此字段),代理拿到的 `UpstreamTarget` 也只有 baseUrl、key、格式和鉴权(`client.ts:26-31`)。 +- 场景:Qwen 预设 `qwen-max`(纯文本模型)或自定义 `deepseek-chat`,用户在对话里贴一张截图。上游以「不支持图片输入」拒绝(未核实具体错误);图片留在历史里,之后同一会话的每个请求都带着它,会话无法继续,只能新开。 +- 参考:ZCode 每个模型有 `inputFormat`,基线规则为不支持图片(`modelRules[0]`),不支持时把图片换成说明文字(`zcode:apps/zcode-cli/packages/adapters/src/model/transform.ts:484-497`;`media-transform-policy.ts:8-15`)。Codex 回退元数据默认支持文本+图像,不支持时在构造请求时剥离(见 request-cache.md Q4)。 +- 改法方向:provider 配置里按模型记录是否支持图像(模型列表能提供时自动填),代理在不支持时把图片换成一段说明文字;与 P-REQ-04 共用同一个能力判断。 +- 确定程度:代码确认(提供方报错行为未核实) + +### P-REQ-12 不发送 `parallel_tool_calls` + +- 类型:优化 +- 严重程度:低 +- 现状:chat 与 Responses 请求都没有 `parallel_tool_calls`(`types.ts:32-46,107-125`);CLI 侧也不使用 `disable_parallel_tool_use`(grep 无结果)。 +- 场景:Qwen 预设走 DashScope,`parallel_tool_calls` 默认为 false(外部文档记忆,未核实),模型每轮只发一个工具调用;agent 并行读多个文件时变成多轮,延迟和输入 token 都增加。 +- 参考:Codex 请求固定带 `parallel_tool_calls`(`codex:core/src/client.rs:1117`)。ZCode 未找到设置。 +- 改法方向:chat 与 Responses 请求在有工具时发 `parallel_tool_calls: true`;个别不接受该字段的站点再单独关闭。 +- 确定程度:代码确认(DashScope 默认值未核实) + +### P-REQ-13 工具 schema 原样转发,带 `$schema`、超大 `maximum` 等提供方用不上的关键字 + +- 类型:优化 +- 严重程度:低 +- 现状:内置工具的 schema 由 zod v4 `toJSONSchema` 生成(`src/utils/zodToJsonSchema.ts:5,17-23`),形状如 `{"$schema":"https://json-schema.org/draft/2020-12/schema", …, "additionalProperties":false}`,整数字段带 `"maximum":9007199254740991`,URL 字段带 `"format":"uri"`(本地用仓库 zod 打印确认)。代理把 `input_schema` 原样作为 `parameters`(`anthropicToOpenaiChat.ts:47-58`;`anthropicToOpenaiResponses.ts:35-45`)。MCP 工具的 schema 也原样转发。 +- 场景:每个请求的约 30 个内置工具都带一个 `$schema` URL(约 55 个字符),总计约 1.6K 字符;对校验较严格的 OpenAI 兼容后端(例如基于 OpenAPI 子集的函数声明),`$schema` 或 `format` 可能导致 400(哪些提供方会拒绝未核实)。 +- 参考:Codex 把工具 schema 规范化成一个受限子集,只保留 type、description、properties、required、items、enum、anyOf/oneOf/allOf、`$ref`/`$defs`、additionalProperties 等(`codex:tools/src/json_schema.rs:47-116`;`codex:tools/src/json_schema/types.rs:40-77`)。ZCode 原样发送,只对 Kimi K3 把 `$ref` 提升到 `$defs`(`zcode:apps/zcode-cli/packages/adapters/src/model/tool-transform.ts:96-153`;`providerSiteRules[34]`)。 +- 改法方向:代理在转换工具时去掉顶层 `$schema` 和等于 `Number.MAX_SAFE_INTEGER` 的 `maximum`;更多关键字的清理等出现具体提供方报错时再按站点加。 +- 确定程度:代码确认(提供方拒绝情况未核实) + +### P-REQ-14 服务端标题请求在 OpenAI 格式上既不限输出也关不掉思考 + +- 类型:问题 +- 严重程度:低 +- 现状:标题请求是非流式、15 秒超时、`max_tokens: 100`,只有用户设置 `alwaysThinkingEnabled === false` 时才带 `thinking:{type:'disabled'}`(`src/server/services/titleService.ts:82-89,177-180`)。经 `sendToUpstream` 转换后:`max_tokens` 丢弃(P-REQ-05),`disabled` 只在 deepseek/opencode.ai 域名透传,其余上游没有关闭思考的字段(P-REQ-02)。 +- 场景:自定义 `openai_chat` 接一个默认开思考的模型(例如 Kimi 思考模型),第一条用户消息后生成标题:上游完整推理、没有输出上限,非流式等待超过 15 秒即 `Request timed out`,会话没有 AI 标题(推断)。DashScope 的部分开源 Qwen3 模型对非流式请求要求关闭思考(外部文档记忆,未核实),这类模型的标题请求会直接 400。 +- 参考:ZCode 无头模式不生成标题;ZCode 与 Codex 都没有对应的服务端标题请求(见 request-cache.md Q6)。 +- 改法方向:标题请求总是声明「关闭思考」,并依赖 P-REQ-02、P-REQ-05 的映射把它和 `max_tokens` 写到上游字段。 +- 确定程度:代码确认(超时与 400 为推断/未核实) + +### P-REQ-15 结构化输出(`output_config.format`)被丢弃 + +- 类型:优化 +- 严重程度:低 +- 现状:prompt 类 hook 用 `outputFormat` 要求 JSON schema 输出(`src/utils/hooks/execPromptHook.ts:61-98`),CLI 放进 `output_config.format`(`claude.ts:1626-1636`);代理类型里没有 `output_config`(`types.ts:161-181`),不转成 `response_format` / `text.format`。hook 只靠 system 里的文字要求返回 JSON,解析失败时报 `JSON validation failed`(`execPromptHook.ts:110-127`)。 +- 场景:用户配置了 `type: "prompt"` 的 hook,提供方为 Qwen 预设。小模型偶尔在 JSON 外加说明文字或代码围栏,hook 判为非阻塞错误,条件检查失效。 +- 参考:ZCode 按模型 `supportsJsonSchemaOutput` 决定是否让 SDK 发原生 JSON schema 输出(`zcode:apps/zcode-cli/packages/adapters/src/model/model-execution.ts:356-365`;`runner-options.ts` 中 `withNativeGenerateOutputFormat`)。Codex 把输出 schema 写进 `text`(`codex:core/src/client.rs:1090-1094`)。 +- 改法方向:`output_config.format` 为 json_schema 时,chat 写 `response_format: {type:"json_schema", …}`,Responses 写 `text.format`;模型不支持时退回 `json_object` 或不写。 +- 确定程度:代码确认 + +### P-REQ-16 提供方缺少自定义请求头、查询参数和请求体补丁的配置项 + +- 类型:优化 +- 严重程度:低 +- 现状:`SavedProvider` 只有 baseUrl、key、鉴权方式、格式、模型、上下文窗口(`src/server/types/provider.ts:47-60`);`UpstreamTarget` 不带 presetId 和模型信息(`client.ts:26-31`),代理里唯一的提供方分支是 P-REQ-07 的域名判断。上游请求头固定为 `Content-Type` + `Authorization: Bearer`(`client.ts:213,221`)。 +- 场景:Azure OpenAI 需要 `api-key` 头和 `api-version` 查询参数,无法配置;OpenRouter 的应用标识头、DashScope 的 `enable_thinking` 这类按模型的 body 字段,只能等代码内置规则。 +- 参考:Codex provider 配置有 `http_headers`、`env_http_headers`、`query_params`(`codex:model-provider-info/src/lib.rs:172-181,400-420`)。ZCode provider 有 `api.headers`(`zcode:apps/zcode-cli/packages/adapters/src/model/model-execution.ts:401-411`),并有手动模型规则覆盖内置规则(见 model-adaptation.md Q4)。 +- 改法方向:provider 配置增加可选的额外请求头和额外 body 字段(按模型匹配),代理在构造上游请求时合并;P-REQ-02、P-REQ-05、P-REQ-11 的内置规则也通过同一结构表达。 +- 确定程度:代码确认 + +### 按提供方的对照(第 6 项) + +DreamCoder 代理里唯一的提供方分支是 `shouldUseDeepSeekReasoningCompat`(`client.ts:251-256`);其余提供方的请求完全相同。预设里只有 Qwen 是 `openai_chat`,DeepSeek、Kimi、智谱、LM Studio、Ollama 预设都是 `anthropic` 格式,不经代理(`src/server/config/providerPresets.json`)。下表是用户以自定义提供方接 OpenAI 格式端点时的情况。 + +| 提供方 | DreamCoder 代理 | ZCode 规则 | +|---|---|---| +| DeepSeek(`api.deepseek.com`) | 回传 `reasoning_content`;透传 `thinking.type`(可能是 `adaptive`) | chat:`thinking.type` enabled/disabled + `reasoning_effort`(`modelApiRules[37],[39],[63],[67]`);Responses:`reasoning.effort`(`providerSiteRules[42]-[44]`);v4-flash 支持图片(`providerSiteRules[45]`) | +| Kimi(`api.moonshot.cn/v1`) | 无 | k2.5/k2.6:`thinking.type`(`modelApiRules[33],[35]`);k3:`reasoning_effort`(`[24],[26]`);k2.7-code 三种协议各自映射(`[29]-[31]`) | +| 智谱 GLM(`/api/paas/v4`) | 无法接入(P-REQ-06) | chat 落到通用映射(`modelApiRules[2]`);opencode go 上按模型给 `reasoning_effort` 档位和 `max_tokens` 上限(`providerSiteRules[0]-[3]`) | +| Qwen(DashScope,预设) | 无(思考与 effort 都不发) | plus/flash/3.5–3.7:`enable_thinking`(`modelApiRules[44],[46],[48],[50],[69]`);3.8:`reasoning_effort`(`[41]`) | +| MiniMax | 无 | 只有 opencode go 上 anthropic 协议的条目(`providerSiteRules[15]-[17]`) | +| OpenRouter | 无 | chat 上部分模型写 `reasoning:{effort}` / `reasoning:{enabled}`(`providerSiteRules[49],[50]`),并给出窗口、输出上限(`[48],[51]`) | +| opencode.ai | 与 DeepSeek 同一兼容分支(对所有模型) | 每个模型给 `reasoning_effort` 档位、`max_tokens` 上限、图像能力(`providerSiteRules[0]-[14]`);请求带 `x-opencode-session`(`runner-attribution.ts:47-64`) | +| 未知模型 | 无 | 通用映射写 `thinking.type`、`enable_thinking`、`reasoning_effort`、`reasoning.effort`、`max_completion_tokens`(`modelApiRules[2]`),基线不支持图片/PDF(`modelRules[0]`) | + +DreamCoder 缺少的配置维度:推理字段的写法与档位、输出上限字段名与上限、图像/PDF 输入能力、推理回传字段、JSON schema 输出支持、`parallel_tool_calls`、会话头与缓存键、自定义头与 body 字段、base 路径。 + +### 其余检查过、未列为发现的项 + +- system 块顺序:CLI 为 [计费行(仅 Claude 名)][CLI 前缀句][各段][advisor](`claude.ts:1394-1404`),代理再在最前插计费行,用 `\n` 拼接(`anthropicToOpenaiChat.ts:23`;`anthropicToOpenaiResponses.ts:28`)。ZCode 合并开头连续 system 时用空串拼接,靠各段自带边界(`zcode:apps/zcode-cli/packages/adapters/src/model/system-message-compat.ts:6-35`)。除 P-REQ-01 外,代理侧的转换是确定性的,同一份历史两次转换得到相同字节;会话内其他可能变化的前缀内容(MCP 说明、中途新增工具、locale 相关排序)在 CLI 侧,见 request-cache.md Q2。 +- 消息顺序:同一条 user 消息里的 tool_result 先输出为 tool 消息,文本和图片放在其后的 user 消息(`anthropicToOpenaiChat.ts:105-131`),满足「tool 结果紧跟 tool_calls」。CLI 在 `normalizeMessagesForAPI` 中已合并相邻 user 消息、去掉只有 thinking 的孤立 assistant 消息、给空 assistant 补占位(`src/utils/messages.ts:2316-2345,5027-5060,5085-5150`),代理没有再遇到连续同角色或空 assistant 的输入路径。 +- `is_error`:转换时丢弃,但 CLI 的错误结果文本已带 `` 包裹(`src/services/tools/toolExecution.ts:402,481,671`),模型能区分。chat 与 Responses 都没有对应字段。 +- `tool_choice`:auto→auto、any→required、none→none、tool→指定函数(`anthropicToOpenaiChat.ts:175-187`;Responses 为扁平形状 `anthropicToOpenaiResponses.ts:125-137`)。CLI 唯一发 `type:'tool'` 的地方是 WebSearch 的小模型分支,受 `tengu_plum_vx3` 控制、默认关(`WebSearchTool.ts:395-414`)。 +- `stop_sequences`:chat 转为 `stop`,Responses 丢弃(`anthropicToOpenaiChat.ts:43-45`)。CLI 只在 yolo 分类器和 sideQuery 中使用(`src/utils/permissions/yoloClassifier.ts:792`;`src/utils/sideQuery.ts:187`),本场景默认不触发。 +- `temperature`:只在思考关闭时发 1(`claude.ts:1741-1745`),即 WebFetch 二次处理、hook 等辅助请求和用户关闭思考时;未找到会因此报错的具体模型。 +- `defer_loading` 与 `tool_reference`:代理场景下 ToolSearch 默认关闭(ANTHROPIC_BASE_URL 非 Anthropic 官方,`src/utils/toolSearch.ts:296-309`),服务端不设 `ENABLE_TOOL_SEARCH`;用户手动开启时 `tool_reference` 会变成 `[omitted content: tool_reference]`(`toolArguments.ts:43-44`),所有工具仍全量发送。 +- 工具名长度:MCP 工具名只做字符替换、不截断(`src/services/mcp/normalization.ts:17-23`;`mcpStringUtils.ts:50-52`),超过 64 字符时 Anthropic 与 OpenAI 端点都会拒绝,不是代理特有的问题。 +- 空内容:空数组 content 转成 `content: ''`(`anthropicToOpenaiChat.ts:93-96`);ZCode 用 `(no content)` 防止提供方把空串当缺失(`zcode:apps/zcode-cli/packages/adapters/src/model/transform.ts:457-469`)。没找到 CLI 发出空 user content 的具体路径,未列为发现。 +- 多个 assistant 文本块用 `+=` 直接相连、没有分隔(`anthropicToOpenaiChat.ts:144-145`);CLI 把 tool_use 重排为连续段(`messages.ts:2318-2330`),两段文本会被粘在一起。影响很小,未列为发现。 + +### 辅助请求的请求侧(第 7 项) + +| 请求 | 是否经代理 | 请求侧特点 | +|---|---|---| +| 子代理 | 是 | 各自的 system,带计费行(指纹按子代理首条 user 文本算);与主会话同一进程、同一 `X-Claude-Code-Session-Id`,可共用缓存键(P-REQ-10) | +| WebFetch 二次处理(`queryHaiku`) | 是 | fastModel、思考关闭、`temperature: 1`、无工具;计费行照加;关闭思考的字段到不了上游(P-REQ-02) | +| 压缩 | 是 | 与主循环相同的 system、工具和历史,加一条压缩提示,不设输出上限(`compact.ts:1150-1191`);本意复用主循环缓存,因 P-REQ-01 不成立;输出无上限(P-REQ-05) | +| prompt hook | 是 | 结构化输出要求被丢弃(P-REQ-15) | +| 服务端标题 | 否(直接 `sendToUpstream`) | 无计费行;`max_tokens` 与关闭思考都到不了 OpenAI 格式上游(P-REQ-14) | + +## 2. 已知结论的核实 + +| 已知结论 | 核实结果 | 位置与补充 | +|---|---|---| +| 代理在开头加计费行,`cch` 是整个请求体的哈希,请求开头每次都变 | 确认,并补充 | `handler.ts:64`;`claudeCodeAttribution.ts:29-46`;`client.ts:214,222`;`claudeCodeCch.ts:56,135-139`。补充:代理加这行无视服务端按模型名关闭计费行的策略(`attributionHeaderPolicy.ts:3-15`);Claude 名模型由 CLI 预先签名,代理不重签,结果同样逐请求变化;标题请求是唯一不带这行的请求;仓库内没有读取它的下游。 | +| `max_tokens` 和 effort 不转发 | 确认,并补充 | `types.ts:35-36,112` 有字段无赋值;`types.ts:161-181` 无 `output_config`。补充:`thinking: adaptive/disabled` 也不产生任何字段,带 budget 的映射在现有配置下走不到;直接转发 32000 会超出部分模型上限(P-REQ-02、P-REQ-05)。 | +| 上游错误统一包成 `api_error`,响应头(含 `retry-after`)丢失 | 不在本部分范围 | 代码位置与描述一致(`handler.ts:66-71`;`client.ts:83-89`),留给错误方向的评审。 | +| `reasoning_content` 只对 deepseek 与 opencode.ai 域名写回 | 确认,并补充 | `client.ts:206-210,251-256`;`anthropicToOpenaiChat.ts:146-147,168-170`。补充:同一判断还打开 `thinking.type` 透传,对 opencode.ai 上的所有模型生效;Responses 路径完全不回传(P-REQ-07、P-REQ-08)。 | +| 工具结果里的图片变成 `[image omitted]` | 确认,并补充 | `toolArguments.ts:37-38`,chat 与 Responses 两条路径都是。补充:PDF 的 `document` 块不在 tool_result 里,被完全静默丢弃(P-REQ-03);Responses 本可在 `function_call_output` 里带图片(P-REQ-04)。 | +| 流式工具调用没有 id 时被丢弃 | 不在本部分范围 | 响应方向。 | +| `cache_control` 被丢弃,不发缓存键或会话头 | 确认,并补充 | `types.ts:149-181` 只声明不使用;`client.ts:213,221` 只有两个头。补充:CLI 已经给代理带了 `X-Claude-Code-Session-Id` 和 `metadata.user_id`,代理没读(P-REQ-10)。 | + +## 3. 覆盖范围 + +完整阅读: +- DreamCoder:`src/server/proxy/handler.ts`、`src/server/proxy/claudeCodeAttribution.ts`、`src/server/upstream/client.ts`、`src/server/upstream/baseUrl.ts`、`src/server/proxy/transform/anthropicToOpenaiChat.ts`、`anthropicToOpenaiResponses.ts`、`types.ts`、`toolArguments.ts`、`src/utils/claudeCodeCch.ts`、`src/constants/claudeCodeCompatibility.ts`、`src/server/services/attributionHeaderPolicy.ts`、`src/server/services/titleService.ts`、`src/server/config/providerPresets.json`、`src/server/types/provider.ts`。 +- ZCode:`apps/zcode-cli/packages/adapters/src/model/transform.ts`、`tool-transform.ts`、`strict-tool-schema.ts`、`system-message-compat.ts`、`runner-attribution.ts`、`model-request-headers.ts`、`opencode-session.ts`、`media-transform-policy.ts`;`config/provider/zcode-builtin.json` 的 `modelApiRules` 全部、`providerSiteRules` 全部、`modelRules[0]`;`patches/@ai-sdk__openai-compatible@2.0.60.patch`;`core/src/runtime/methods/model-token-limits.ts`。 +- Codex:`core/src/client.rs` 640–690、950–1135 行;`tools/src/json_schema.rs` 前 130 行与 `json_schema/types.rs`;`core/src/thread_manager.rs` 的 `PromptCacheKey`;`codex-client/src/provider.rs` 的 URL 拼接;`model-provider-info/src/lib.rs` 的 provider 字段。 + +部分阅读:`src/services/api/claude.ts`(metadata、system 组装、参数构造 1380–1420、1560–1790、3450–3475 行)、`src/services/api/client.ts`(默认头与 fetch 包装)、`src/utils/messages.ts`(normalize 末段与 thinking 过滤)、`src/tools/FileReadTool/FileReadTool.ts`(图片/PDF 结果)、`src/tools/WebSearchTool/backend.ts` 与 `WebSearchTool.ts`、`src/utils/toolSearch.ts`、`src/utils/api.ts`(`toolToAPISchema`)、`src/utils/effort.ts`、`src/utils/context.ts`(输出上限)、`src/server/services/providerRuntimeEnv.ts`、`src/utils/hooks/execPromptHook.ts`;ZCode 的 `model-execution.ts`、`runner-options.ts`、`tool-result-media-projection.ts`(前 60 行)与相关测试。 + +未覆盖: +- 响应方向(流转换、usage、无 id 工具调用)见 [response.md](response.md),错误和重试见 [transport.md](transport.md)。 +- CLI 内的 `azureOpenAI` 直连路径(`claude.ts:1027-1050`)不经代理,未看。 +- `src/utils/fingerprint.ts` 的算法细节未重读,沿用 request-cache.md 的结论。 +- ZCode 的 `reasoning-history-normalization.ts` 只看了调用点;`@ai-sdk/openai-compatible` 是否把推理写成 `reasoning_content` 仍未核实(refs 中无该依赖源码)。 +- 所有提供方行为(默认输出上限、是否接受 `adaptive`、是否要求回传推理、`parallel_tool_calls` 默认值、`cache_control` 支持、端点路径)均来自外部文档记忆,没有联网核实,已逐条标注。 diff --git a/docs/features/harness/proxy/response.md b/docs/features/harness/proxy/response.md new file mode 100644 index 00000000..b4da211d --- /dev/null +++ b/docs/features/harness/proxy/response.md @@ -0,0 +1,252 @@ +# 代理层评审:响应方向(P-RES) + +范围:从提供方返回的字节,到 CLI 收到的 Anthropic 格式响应(流式与非流式),以及 CLI、服务端、桌面端对它的后续处理。上游格式 `openai_chat` 与 `openai_responses`。 + +路径约定:DreamCoder 路径相对仓库根;`codex:` 相对 `refs/coding-agents/codex/codex-rs`;`zcode:` 相对 ZCode 仓库根。全部为静态阅读;唯一运行的是现有测试 `bun test src/server/__tests__/proxy-streaming.test.ts`(31 通过)。ZCode 依赖的 Vercel AI SDK 源码不在本地,凡是 AI SDK 内部行为一律标「未核实」。 + +## 1. 发现清单 + +### P-RES-01 上游没给 usage 时代理写 0,CLI 的上下文估算以 0 为基准,自动压缩不会触发 + +- 类型:问题 +- 严重程度:高 +- 现状: + 1. chat 流:`message_start` 的 usage 固定为 0(src/server/proxy/streaming/openaiChatStreamToAnthropic.ts:178)。收到 `finish_reason` 时,只认 chunk 顶层的 `usage`,没有就把 `message_delta` 暂存(:446-462);之后只有 `choices` 为空的 chunk 能补 usage(:297-301)。流结束仍没有 usage,就发出暂存的 `message_delta`,其 usage 为 `mapUsage(undefined)` = `{input_tokens:0, output_tokens:0}`(:512-516;src/server/proxy/transform/openaiChatToAnthropic.ts:82-84)。 + 2. Responses 流:usage 只来自 `response.completed`/`response.incomplete`(src/server/proxy/streaming/openaiResponsesStreamToAnthropic.ts:318-341);没收到这两个事件时根本没有 `message_delta`,消息的 usage 保持 `message_start` 的 0(:131)。 + 3. CLI:每个内容块在 `content_block_stop` 时生成一条消息,usage 来自 `message_start`(src/services/api/claude.ts:2221-2262);`message_delta` 只把 usage 写到最后一条(:2294-2297)。 + 4. `getTokenUsage` 只要消息有 `usage` 字段就返回它,不管是不是全 0(src/utils/tokens.ts:7-20);`tokenCountWithEstimation` 取最近一条带 usage 的助手消息作基准,再加其后消息的粗估(:244-285)。基准为 0 时,结果只等于最后几条消息的粗估。 + 5. 自动压缩用这个数判断阈值(src/services/compact/autoCompact.ts:210)。 +- 场景:自定义 provider,`openai_chat`,Moonshot(Kimi)OpenAI 兼容端点。按 Moonshot 公开文档,流式 usage 放在最后一个 chunk 的 `choices[0].usage` 里,而不是 chunk 顶层(推断,依据外部文档,未在运行时核实)。代理读不到 → 每个回复 usage 全 0 → `tokenCountWithEstimation` 每轮都只算最后几条消息 → 对话长到超过窗口也不压缩 → 上游返回超长 400;CLI 不认 OpenAI 风格的超长错误(已有报告 Q7),会话卡死。同样的结果也出现在:中转站去掉 `stream_options` 不回 usage;Responses 流在 `response.completed` 前被关闭(见 P-RES-04)。桌面端的用量面板和上下文估算会跳过全 0 记录(src/server/services/sessionService.ts:883, 985-993),只是显示偏旧,不会报错。 +- 参考: + - ZCode:usage 的 input 不大于 0 时不作为基准(zcode:apps/zcode-cli/packages/core/src/agent/message-history-usage.ts:14-16),继续往前找有效 usage(zcode:apps/zcode-cli/packages/core/src/runtime/methods/turn-model-step-usage.ts:62-72),找不到就整段本地估算(zcode:apps/zcode-cli/packages/core/src/compact/policy.ts:104-106)。是否读取 `choices[0].usage` 取决于 AI SDK(未核实)。 + - Codex:usage 只来自 `response.completed`(codex:codex-api/src/sse/responses.rs:134-137);流在 completed 之前结束按错误处理并重试(:574-579),不会留下 0 用量的回复。 +- 改法方向:代理在 chunk 顶层没有 usage 时也读 `choices[0].usage`;没有任何 usage 时不要写 0,而是不带 input/output 字段或带一个能被识别为“未知”的值;CLI 的 `getTokenUsage`/`tokenCountWithEstimation` 把全 0 的 usage 当作没有,退回整段估算。 +- 确定程度:CLI 链路代码确认;Kimi 的 usage 位置推断。 + +### P-RES-02 提供方要求回传的推理数据在响应方向就被丢弃(Gemini 的 thought_signature、OpenRouter 的 reasoning_details、Responses 的 encrypted_content) + +- 类型:问题 +- 严重程度:高(Gemini 3 场景成立时功能失效;其余为推理质量和 token 损失) +- 现状: + 1. chat 流:推理只取 `reasoning_content`、`reasoning`、`thinking_blocks[0]`(openaiChatStreamToAnthropic.ts:246-268),签名只来自 `thinking_blocks`,其余情况签名为空串(:248, 252)。工具调用只读 `index`、`id`、`function.name`、`function.arguments`(:387-431),`tool_calls[].extra_content` 不读。`reasoning_details` 不读(全仓 grep 无匹配)。 + 2. chat 非流式同样只读这三个字段,工具调用只取 id/name/arguments(openaiChatToAnthropic.ts:18-45)。 + 3. Responses 流不处理 `response.output_item.done`,reasoning item 只把 summary 文本变成 thinking 块(openaiResponsesStreamToAnthropic.ts:268-305);非流式也只取 `summary[].text`(openaiResponsesToAnthropic.ts:67-79)。请求里 `store:false`(src/server/proxy/transform/anthropicToOpenaiResponses.ts:21),全仓没有 `include: ["reasoning.encrypted_content"]`。 +- 场景: + - 自定义 provider,`openai_chat`,Gemini 的 OpenAI 兼容端点,模型 Gemini 3 Pro。按 Google 文档,函数调用的思考签名放在 `tool_calls[].extra_content.google.thought_signature`,当前回合的函数调用缺签名时请求返回 400(推断,依据外部文档)。第一步模型调用 Read → 代理丢掉签名 → 第二步带着工具结果的请求缺签名 → 400,工具循环无法继续。 + - OpenRouter(`openai_chat`)上的 Gemini 3、Claude、OpenAI 推理模型:OpenRouter 要求在工具调用循环中回传 `reasoning_details` 才能保留推理(推断,依据外部文档);DreamCoder 只保留 `reasoning` 文本,签名和加密推理丢失。 + - OpenAI GPT-5 系列经 `openai_responses`(以及 ChatGPT 登录路径,它复用同一个流转换器:src/services/openaiAuth/fetch.ts:101):`store:false` 又不请求 `encrypted_content`,工具调用之间推理全部丢失,模型每步重新推理,输出 token 和延迟上升(推断)。 +- 参考: + - Codex:请求总带 `include: ["reasoning.encrypted_content"]`(codex:core/src/client.rs:1075),从 `response.output_item.done` 取完整 item(codex:codex-api/src/sse/responses.rs:354-361)并在下一轮回传。 + - ZCode:adapters 里没有处理 `thought_signature`、`reasoning_details`、`encrypted_content` 的代码(grep 无匹配),依赖 AI SDK(未核实)。 +- 改法方向:响应方向把这些不透明数据保存在 thinking 块的 `signature` 或 tool_use 块的附加字段里(Anthropic 格式能原样存进转录);请求方向(P-REQ 评审范围)再按上游格式写回。Responses 路径同时在请求里加 `include` 并读取 `output_item.done` 的 reasoning item。 +- 确定程度:DreamCoder 不读这些字段为代码确认;各提供方的强制要求为推断。 + +### P-RES-03 上游流停滞时没有任何超时,回合一直挂着 + +- 类型:问题 +- 严重程度:中 +- 现状: + 1. 代理的流式请求只在收到响应头之前计时,拿到响应头就清掉定时器(src/server/upstream/client.ts:268-276)。 + 2. 两个流转换器都在 `start()` 里循环 `reader.read()`,没有读超时(openaiChatStreamToAnthropic.ts:80-82;openaiResponsesStreamToAnthropic.ts:53-55)。 + 3. 上游的 SSE 注释(keep-alive)被直接跳过,不向 CLI 转发任何事件(openaiChatStreamToAnthropic.ts:90)。 + 4. CLI 的流空闲看门狗默认关闭,需 `CLAUDE_ENABLE_STREAM_WATCHDOG`(src/services/api/claude.ts:1924-1928);SDK 的请求超时同样只覆盖到响应头(同处注释 :1918-1923)。服务端没有给 CLI 设置这个变量(`buildNetworkEnvironment` 只设 `API_TIMEOUT_MS` 和代理,src/server/services/networkSettings.ts:76-88)。 +- 场景:中转站或提供方在输出到一半时卡住但不断开连接(TCP 仍在)。代理一直等 `reader.read()`,CLI 一直等事件,桌面端一直显示生成中,直到用户手动停止。 +- 参考: + - Codex:每次读 SSE 都套 `idle_timeout`(codex:codex-api/src/sse/responses.rs:557),默认 300 秒(codex:model-provider-info/src/lib.rs:68, 515-519),超时作为可重试的流错误(:582-586;codex:protocol/src/error.rs:445-460)。 + - ZCode:默认 600 秒(zcode:apps/zcode-cli/packages/contracts/src/config/index.ts:284),每次重试加 30 秒(zcode:apps/zcode-cli/packages/adapters/src/model/stream-idle-timeout.ts:5-24),在 runner-stream.ts:164 应用并归类为可重试(failure-classifier.ts:137)。 +- 改法方向:在代理的两个流转换器里加读空闲超时,超时后发 SSE `error` 并取消上游;同时把上游的 keep-alive 注释转成 Anthropic 的 `ping` 事件,这样以后若开启 CLI 看门狗,也不会误杀只发 keep-alive 的长推理。 +- 确定程度:代码确认。 + +### P-RES-04 上游在结束标记之前正常关闭连接,被当成正常结束,回答被截断且不重试 + +- 类型:问题 +- 严重程度:中 +- 现状: + 1. chat 流:`reader.read()` 返回 done 后进入 `finalizeStream`(openaiChatStreamToAnthropic.ts:81-82, 135-140)。只要之前有过合法 chunk,就关闭所有块并补一个 `stop_reason: end_turn`、`output_tokens: 0` 的 `message_delta` 和 `message_stop`(:508-527)。没有收到 `finish_reason` 与收到 `stop` 无法区分。 + 2. Responses 流:读完后直接 `controller.close()`(openaiResponsesStreamToAnthropic.ts:105),没有 `message_delta`、没有 `message_stop`,未收到 `.done` 的文本块和工具块也不关闭。 + 3. CLI:只有“没有 message_start”或“没有完成任何块且没有 stop_reason”才判为异常并回退(src/services/api/claude.ts:2400-2413)。chat 路径补了 end_turn,Responses 路径已关闭的块已经产出消息,两种情况都通过检查,回合按正常结束处理。 +- 场景:经中转站(反向代理有读超时)调用 DeepSeek 推理模型,长回答输出到一半时中转站正常关闭分块响应。用户看到半截回答、没有任何提示;如果截在工具参数中间,工具块被关闭,参数 JSON 不完整,CLI 解析成 `{}` 后执行(见 P-RES-07)。用量为 0(见 P-RES-01)。 +- 参考: + - Codex:`Ok(None)`(流结束)而没有 `response.completed` 时报 “stream closed before response.completed”(codex:codex-api/src/sse/responses.rs:574-579),属可重试错误(codex:protocol/src/error.rs:445)。 + - ZCode:没有 finish 事件时的处理在 AI SDK 内(未核实);流中断后由 streamRecovery 重发(zcode:apps/zcode-cli/packages/core/src/runtime/methods/streaming-recovery.ts:24-40)。 +- 改法方向:chat 流在没有收到 `finish_reason`(也没有 `[DONE]`)就结束时、Responses 流在没有 `response.completed/incomplete` 就结束时,发 SSE `error`(“上游流提前结束”),让 CLI 走现有的重试路径。 +- 确定程度:代码确认。 + +### P-RES-05 finish_reason 映射过粗:内容过滤、资源不足、上下文用满都变成 end_turn;Responses 的内容过滤变成 max_tokens + +- 类型:问题 +- 严重程度:中 +- 现状: + 1. chat(流式与非流式相同):`stop`→end_turn,`tool_calls`→tool_use,`length`→max_tokens,`content_filter` 与其他任何值→end_turn;出现过工具调用时 end_turn 改为 tool_use(openaiChatStreamToAnthropic.ts:442-445, 530-538;openaiChatToAnthropic.ts:65-78)。缺失 `finish_reason` 时见 P-RES-04。 + 2. Responses:`completed`→end_turn/tool_use,`incomplete`→max_tokens(不看 `incomplete_details.reason`),`failed`/`cancelled`→end_turn(openaiResponsesStreamToAnthropic.ts:325-327;openaiResponsesToAnthropic.ts:83-91)。 + 3. CLI 对 `max_tokens` 生成“超过 32000 输出上限”的错误消息并进入最多 3 次的续写恢复(claude.ts:2316-2327;src/query.ts:1173-1234);对 `model_context_window_exceeded` 有专门提示并复用续写恢复(claude.ts:2329-2341);对 `refusal` 给出拒答提示(:2308-2314,文案指向 Anthropic 使用政策,src/services/api/errors.ts:1194-1196);对 end_turn 不做任何提示。 +- 场景: + - Azure OpenAI 或 Qwen(DashScope,预设)在输出中途触发内容审核,`finish_reason: "content_filter"` → end_turn,用户只看到半截回答,没有任何提示。 + - 自定义 provider 直连智谱 `/api/paas/v4`(`openai_chat`):`sensitive`(审核)、`network_error`(推理错误)、`model_context_window_exceeded` 都成了 end_turn;最后一种本应触发 CLI 已有的上下文用满处理。 + - DeepSeek 的 OpenAI 端点(`openai_chat`,代码专门支持该域名:src/server/upstream/client.ts:251-256)返回 `insufficient_system_resource`(服务端资源不足中断)→ end_turn,截断且不重试。 + - OpenAI 经 `openai_responses`,`response.incomplete` 且 `reason: "content_filter"` → max_tokens → CLI 显示“超过输出上限”并发送续写提示,重复撞同一个过滤。 + 以上 provider 特有取值来自各家公开文档(推断)。 +- 参考: + - Codex:`incomplete` 时读 `incomplete_details.reason`,`content_filter` 报 ContentFilter,非 `interrupted` 报 ResponseIncomplete(codex:codex-api/src/sse/responses.rs:419-448)。 + - ZCode:保留原始 finish reason;把 `content_filter`/`sensitive` 识别为内容过滤并报不可重试的错误(zcode:apps/zcode-cli/packages/core/src/runtime/helpers/model-errors.ts:27-72),把 `model_context_window_exceeded` 等识别为上下文超限(:252-260)或输出截断(zcode:apps/zcode-cli/packages/core/src/runtime/methods/turn-output-token-continuation.ts:29-33),`network_error` 归为可恢复的网络错误(zcode:apps/zcode-cli/packages/core/src/runtime/methods/streaming-recovery.ts:34-40)。 +- 改法方向:映射表补上这些取值:上下文用满类映射到 `model_context_window_exceeded`;内容过滤类映射成一个 CLI 能显示中性提示的结果(不要复用指向 Anthropic 政策的 refusal 文案);资源不足、`network_error` 类转成 SSE `error` 以便重试;Responses 的 `incomplete` 按 `incomplete_details.reason` 区分。 +- 确定程度:映射为代码确认;各 provider 取值为推断。 + +### P-RES-06 流中途的上游错误丢掉错误码和状态,CLI 一律改走非流式请求,长回答在 120 秒总时长内完不成 + +- 类型:问题 +- 严重程度:中 +- 现状: + 1. chat 流里的 `error` 对象只取 `message`(openaiChatStreamToAnthropic.ts:486-491),之后只发一个 SSE `error`,类型固定 `api_error`(:497-505);Responses 的 `response.failed`/`error` 同样只取 message(openaiResponsesStreamToAnthropic.ts:15-21, 307-316)。上游的 `code`(如 `context_length_exceeded`、`rate_limit_exceeded`)丢失。 + 2. SDK 遇到 SSE `error` 抛出没有状态码的 `APIError`(主检出 node_modules/@anthropic-ai/sdk/core/streaming.js:99-103)。 + 3. CLI 的流错误处理:不是用户取消就改走非流式请求(claude.ts:2519-2601),已产出的部分消息被替换(src/query.ts:713-726)。 + 4. 非流式请求的总时长:CLI 用 `API_TIMEOUT_MS`(claude.ts:806-810),服务端把它设为网络设置里的值,默认 120 秒(networkSettings.ts:13, 77);代理的非流式 fetch 也用同一个值,并且覆盖读取整个响应体(client.ts:63, 264-265)。超时后代理返回 502(handler.ts:66-71),CLI 按 5xx 重试(src/services/api/withRetry.ts:784)。 +- 场景: + - 经 OpenRouter(`openai_chat`)用推理模型写长回答,第 90 秒时下游提供方出错,OpenRouter 在流里发 `{"error":{...}}`。CLI 丢掉已输出内容,改发非流式请求;推理加输出要 3 分钟,每次在 120 秒时被代理和 CLI 同时掐断,返回 502,CLI 再重试,最多 10 次,每次都是一次完整的上游计费请求(推断:上游被中断后是否计费因提供方而异)。 + - OpenAI 经 `openai_responses`,`response.failed` 带 `code: "context_length_exceeded"`(Codex 测试里的真实负载:codex:codex-api/src/sse/responses.rs:1159):CLI 不知道是超长,先改发一次非流式请求,再收到 400 文本错误,也不会触发压缩。 +- 参考: + - Codex:按 `code` 分类为上下文超限、额度不足、限流(带从文本解析的重试等待)等(codex:codex-api/src/sse/responses_error.rs:26-80);流错误按回合层重试仍用流式(codex:core/src/responses_retry.rs)。 + - ZCode:识别业务错误码和 finish 中的错误(zcode:apps/zcode-cli/packages/adapters/src/model/provider-finish-business-error.ts:15-62),流中断后用流式重发(streaming-recovery.ts)。 +- 改法方向:代理把上游错误的 `code`/`type` 映射为对应的 Anthropic 错误类型(如上下文超限映射为 `invalid_request_error` 并使用 CLI 认得的超长文本,限流映射为 `rate_limit_error`);在服务端启动 CLI 时设置 `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK`(claude.ts:2519-2523 已支持),让流错误直接交给 withRetry 用流式重试。 +- 确定程度:代码确认;计费影响推断。 + +### P-RES-07 被截断或损坏的工具参数在 CLI 里变成 `{}`,模型看到“缺参数”而不是“参数被截断” + +- 类型:问题 +- 严重程度:中 +- 现状: + 1. 流式路径把参数片段原样作为 `input_json_delta` 转发(openaiChatStreamToAnthropic.ts:420-428;openaiResponsesStreamToAnthropic.ts:227-239),不在代理侧校验。 + 2. CLI 在 `content_block_stop` 解析;JSON 无效时记一条分析事件,参数变成 `{}`(src/utils/messages.ts:2770-2789)。 + 3. 工具执行前 zod 校验失败,回给模型 `InputValidationError: ... required`(src/services/tools/toolExecution.ts:616-671)。转录和下一轮请求里,这次调用的参数是 `{}`。 + 4. 非流式路径则是 `{raw: 原文}`(src/server/proxy/transform/toolArguments.ts:10-16),与流式不一致。 + 5. `length` 时,即使有工具调用也只映射为 max_tokens(openaiChatStreamToAnthropic.ts:534);CLI 有 tool_use 时照常执行工具(已有报告 Q5)。 +- 场景:DeepSeek OpenAI 端点(`openai_chat`),代理不转发 `max_tokens`(已有结论),上游用自身默认输出上限。模型用 Write 写一个大文件,参数在 `content` 中间被 `length` 截断 → CLI 得到 `{}` → 返回 “file_path is required” 一类错误 → 模型以为自己漏了参数,再次用同样长的内容重试,再次截断,循环。 +- 参考: + - Codex:参数解析失败时把 `failed to parse function arguments: <错误>` 回给模型(codex:core/src/tools/handlers/mcp_resource.rs:378)。 + - ZCode:同样降级为 `{}` 并记录警告(zcode:apps/zcode-cli/packages/adapters/src/model/tool-input-normalization.ts:31-47),但请求里明确发送输出上限(已有报告 Q5),且有工具调用时不做续写(turn-output-token-continuation.ts:44)。 +- 改法方向:CLI 在参数 JSON 解析失败时不再执行工具,而是回给模型一个说明“参数 JSON 不完整(可能因输出上限被截断),请分小块重试”的错误结果;非流式路径与流式统一。 +- 确定程度:代码确认;DeepSeek 默认上限导致截断为推断。 + +### P-RES-08 同一个 delta 同时带正文、推理或工具调用时,只处理其中一种,其余被丢弃 + +- 类型:问题 +- 严重程度:中 +- 现状:`detectBlockTransition` 按 tool_calls → content → reasoning 的顺序只返回一种类型(openaiChatStreamToAnthropic.ts:270-292),`processChunk` 只调用对应的一个处理函数(:320-330)。同一 delta 里的其余字段直接丢弃。 +- 场景: + - 自部署 vLLM 开启 `--reasoning-parser` 运行 Qwen3 或 DeepSeek-R1(`openai_chat`):推理结束的那个 chunk 同时带 `reasoning_content` 的结尾和 `content` 的开头时,推理结尾被丢掉(推断,依据 vLLM 推理解析器按 delta 同时返回两段的实现)。 + - 网关的伪流式模式把整个回复放进一个 chunk(`content` + `tool_calls`):正文全部丢失,只剩工具调用(推断)。 +- 参考: + - Codex:只支持 Responses,事件本身按类型分开,不适用。 + - ZCode:AI SDK 的 openai-compatible 对同一 delta 依次处理推理、正文、工具调用(未核实)。 +- 改法方向:`processChunk` 对同一 delta 依次处理 reasoning、content、tool_calls 三类字段,每类按现有的块切换规则开关块。 +- 确定程度:丢弃行为代码确认;触发它的上游为推断。 + +### P-RES-09 Responses 流转换只依赖增量事件,不读完整 item,也不在结束时关闭文本和工具块 + +- 类型:问题 +- 严重程度:低 +- 现状: + 1. 文本增量必须先有 `response.content_part.added` 建立索引,否则丢弃(openaiResponsesStreamToAnthropic.ts:176-209)。 + 2. 工具块只在 `response.function_call_arguments.done` 关闭,文本块只在 `output_text.done` 关闭(:241-266);`response.completed` 只关闭推理块(:329-335)。 + 3. `output_item.added` 里已有的 `arguments`、`.done` 事件里的完整 `arguments`/`text`、`response.output_item.done` 都不读(:151-174, 256-266)。 + 4. `response.created` 读 `data.model`,而事件里模型在 `data.response.model`(:145-146),所以总是沿用请求的模型名。 +- 场景:第三方 Responses 兼容服务若不发 `content_part.added` 或只在 `.done` 里给完整参数,正文丢失或工具参数为 `{}`;若漏发 `.done`,块从不关闭,CLI 不会为它产出消息(claude.ts:2221-2262 只在 stop 时产出)。目前能确认的上游只有 OpenAI 官方,它会发全部事件;第三方的行为未核实,因此定为低。 +- 参考:Codex 以 `response.output_item.done` 的完整 item 为准(codex:codex-api/src/sse/responses.rs:354-361),文本增量不依赖 content_part 事件(:362-366)。ZCode 由 AI SDK 处理(未核实)。 +- 改法方向:文本增量在没有索引时自动开块;`response.completed` 时关闭所有仍开着的块;用 `output_item.done` 的完整 item 补齐缺失的参数(也为 P-RES-02 取 reasoning item 提供入口)。 +- 确定程度:代码确认;第三方触发推断。 + +### P-RES-10 正文里的 `` 标签原样当作回答 + +- 类型:优化 +- 严重程度:低 +- 现状:chat 流与非流式只从专用字段取推理(openaiChatStreamToAnthropic.ts:246-268;openaiChatToAnthropic.ts:18-30),`content` 原样成为 text 块(:358-368;:32-34)。服务端标题生成也直接用 text(src/server/services/titleService.ts:95-100)。 +- 场景:MiniMax M2 的 OpenAI 兼容端点(自定义 provider,`openai_chat`)默认把推理以 `…` 放进 `content`(推断,依据 MiniMax 文档)。桌面端把推理当回答显示;子代理最终报告带着推理文本交给主代理;标题可能取到推理内容。回传给上游时推理保留在正文里,这一点符合 MiniMax 的建议,不需要改变回传。 +- 参考:Codex 无。ZCode 主路径无;仅在标题和输入预测里去掉 `` 段(zcode:apps/zcode-cli/packages/core/src/runtime/methods/title-generation-sidecar.ts:267)。 +- 改法方向:至少在标题生成里去掉 `` 段;是否在显示层折叠该段由产品决定。 +- 确定程度:代码确认;MiniMax 默认格式推断。 + +### P-RES-11 缓存命中只读 `prompt_tokens_details.cached_tokens` + +- 类型:优化 +- 严重程度:低 +- 现状:`mapUsage` 只读 `prompt_tokens_details.cached_tokens`(openaiChatToAnthropic.ts:85);Responses 只读 `input_tokens_details.cached_tokens`(openaiResponsesToAnthropic.ts:38)。CLI 把 `cache_read_input_tokens` 计入上下文和费用(src/utils/tokens.ts:46-53),桌面端单列“缓存读/写”(desktop/src/components/chat/LocalSlashCommandPanel.tsx:291)。 +- 场景:DeepSeek OpenAI 端点用 `prompt_cache_hit_tokens` 报告命中;若它不同时返回 `prompt_tokens_details.cached_tokens`,缓存读恒为 0,全部算作普通输入(是否同时返回未核实)。Moonshot 用顶层 `usage.cached_tokens`(推断)。只影响显示和估算费用,上下文总量不变(input 未扣除缓存,总和相同)。 +- 参考:ZCode 由 AI SDK 归一化(未核实)。Codex 只读 Responses 的 `cached_tokens`(codex:codex-api/src/sse/responses.rs:134)。 +- 改法方向:`mapUsage` 依次读 `prompt_tokens_details.cached_tokens`、`prompt_cache_hit_tokens`、`cached_tokens`。 +- 确定程度:代码确认;提供方字段推断。 + +### P-RES-12 有合法 chunk 但没有任何内容的回复,CLI 静默结束 + +- 类型:优化 +- 严重程度:低 +- 现状:chat 流里只要出现过带 `choices` 的 chunk 就算合法(openaiChatStreamToAnthropic.ts:121),结束时发 end_turn(:518-527)。CLI 的空流检查要求“没有块且没有 stop_reason”(claude.ts:2400),此时 stop_reason 已是 end_turn,检查不触发,本次请求不产出任何助手消息。 +- 场景:中转站或高负载的提供方返回只有 `role` 的 chunk 加 `finish_reason: stop`,没有正文也没有工具调用。回合结束,用户看不到任何回复,也没有错误(推断:query.ts 对零条助手消息的后续处理未逐行核实)。 +- 参考:ZCode 在“无正文、无工具调用、无 usage”时重试 1 次(zcode:apps/zcode-cli/packages/adapters/src/model/empty-completion-retry.ts:8-31),排除内容过滤与上下文超限(runner-diagnostics.ts:438-450)。Codex 未找到对应处理。 +- 改法方向:代理在“有 chunk 但无任何内容块且无 usage”时发 SSE `error`,交给 CLI 的回退或重试。 +- 确定程度:代理与 CLI 检查为代码确认;CLI 最终表现推断。 + +### P-RES-13 用户取消在非流式请求和流式响应头到达之前传不到上游 + +- 类型:问题 +- 严重程度:低 +- 现状:`handleProxyRequest` 调 `sendToUpstream` 时不传 `req.signal`(src/server/proxy/handler.ts:64);`sendToUpstream` 只用超时信号(src/server/upstream/client.ts:70-75, 264-276)。流开始之后的取消可以传到上游(流转换器的 `cancel` 取消上游 body,openaiChatStreamToAnthropic.ts:143-146,有测试 src/server/__tests__/proxy-streaming.test.ts:613-637)。 +- 场景:P-RES-06 的非流式回退进行中,用户点停止。CLI 断开与代理的连接,代理对上游的请求继续,直到上游生成完或 120 秒超时,这段生成照常计费。 +- 参考:Codex 在接收方关闭时停止读取(codex:codex-api/src/sse/responses.rs:555-556)。ZCode 把父级 abort 信号连到模型请求(zcode:apps/zcode-cli/packages/adapters/src/model/stream-idle-timeout.ts:63-80)。 +- 改法方向:把 `req.signal` 与超时信号合并后传给上游 fetch。 +- 确定程度:代码确认;Bun 在客户端断开时触发 `req.signal` 为推断。 + +### P-RES-14 SSE 解析不完全按规范 + +- 类型:优化 +- 严重程度:低 +- 现状: + 1. 两个转换器都要求 `data: ` 带空格(openaiChatStreamToAnthropic.ts:98;openaiResponsesStreamToAnthropic.ts:69),`event:` 同样要求空格(:64)。SSE 规范允许冒号后无空格。 + 2. 一个事件多行 `data:` 不拼接,每行单独解析。 + 3. chat 能识别 200 状态下的非 SSE JSON 错误体,但只限单行 JSON(:98-101, 128-131);多行格式化的错误体识别不到,最终报“没有合法 chunk”,原错误信息丢失。Responses 转换器没有这项识别。 +- 场景:本次没能确认哪个提供方发 `data:` 无空格或格式化的错误体(未核实),所以只作为健壮性改进。 +- 参考:Codex 用 eventsource 解析器(codex:codex-api/src/sse/responses.rs:548);ZCode 用 AI SDK 的 SSE 解析(未核实)。 +- 改法方向:两个转换器共用一个按规范实现的 SSE 分帧函数(处理可选空格、多行 data、空行分隔),并在非 SSE 响应时整体解析响应体以取错误信息。 +- 确定程度:代码确认。 + +### P-RES-15 响应里的模型名来源不一致 + +- 类型:优化 +- 严重程度:低 +- 现状:chat 流用上游 chunk 的 `model` 覆盖(openaiChatStreamToAnthropic.ts:304),非流式用 `response.model`(openaiChatToAnthropic.ts:56;openaiResponsesToAnthropic.ts:28),Responses 流实际总用请求的模型名(见 P-RES-09 第 4 点)。这个名字写进转录的 `message.model`,桌面端按它分模型统计并查上下文窗口(src/server/services/sessionService.ts:897, 1000-1015)。 +- 场景:OpenAI 经 `openai_chat` 请求 `gpt-4.1`,响应里返回带日期的快照名(推断),桌面用量面板按另一个名字分组,上下文窗口查表可能落到默认值。 +- 参考:Anthropic 原生 API 在 message_start 里返回请求的模型 id;Codex 把服务端模型名作为单独事件上报(codex:codex-api/src/sse/responses.rs:609-619),不替换会话模型。 +- 改法方向:Anthropic 消息里的 `model` 统一用请求的模型名。 +- 确定程度:代码确认;OpenAI 返回快照名推断。 + +## 2. 已知结论的核实 + +- 「流式里不带 id 的 tool_call 被丢弃」:确认(openaiChatStreamToAnthropic.ts:405,`block.id && block.name` 才开块)。补充:被丢弃的调用不设 `sawToolUse`,参数缓冲随之丢失;若上游 `finish_reason` 为 `tool_calls`,CLI 收到 `stop_reason: tool_use` 却没有 tool_use 块,回合直接结束(CLI 以块是否存在决定是否继续)。非流式路径不丢弃,而是生成 `id: undefined` 的 tool_use(openaiChatToAnthropic.ts:38-43),两条路径不一致。本次未能确认哪个提供方不发 id,故未列为发现。 +- 「上游错误统一包成 `api_error`,响应头被丢弃」:HTTP 非 2xx 部分确认(handler.ts:66-71;client.ts:83-89)。流内错误同样确认,且错误码也被丢弃(见 P-RES-06)。 +- 「`reasoning_content` 只对 deepseek 和 opencode.ai 写回」:属于请求方向。响应方向核实:所有域名的 `reasoning_content`/`reasoning`/`thinking_blocks` 都会转成 thinking 块并进入转录(openaiChatStreamToAnthropic.ts:246-268),丢失发生在下一轮请求转换时;另外签名、`reasoning_details`、`extra_content` 在响应方向就没有保存(见 P-RES-02)。 +- 已有报告「流截断(无 finish_reason)补 end_turn」:确认,并补充其后果,列为 P-RES-04。 +- 已有报告「代理在流结束时总会补 end_turn,所以合法但空的回复不会触发 CLI 空流分支」:需要修正。chat 流若一个合法 chunk 都没有,代理发的是 SSE `error`(openaiChatStreamToAnthropic.ts:497-505),CLI 走非流式回退;只有出现过合法 chunk 时才补 end_turn,此时空回复确实不触发空流分支(P-RES-12)。Responses 流不补 end_turn,没有 completed 且没有完成的块时会触发空流分支,有完成的块时不触发(P-RES-04)。 +- 已有报告「DeepSeek 的 `prompt_cache_hit_tokens` 未处理」:确认代码不读(P-RES-11);DeepSeek 是否同时返回 `prompt_tokens_details.cached_tokens` 未核实,影响可能比已有报告估计的小。 +- 已有报告「非流式参数解析失败得 `{raw}`,流式得 `{}`」:确认(toolArguments.ts:10-16;src/utils/messages.ts:2770-2789),并扩展为 P-RES-07。 +- 已有报告「流空闲看门狗默认关闭」:确认(claude.ts:1924-1928),服务端也没有开启它(networkSettings.ts:76-88),扩展为 P-RES-03。 +- 「`stream_options.include_usage` 是否请求」:流式 chat 总是请求(src/server/proxy/transform/anthropicToOpenaiChat.ts:38)。 + +## 3. 覆盖范围 + +完整阅读: +- src/server/proxy/streaming/openaiChatStreamToAnthropic.ts +- src/server/proxy/streaming/openaiResponsesStreamToAnthropic.ts +- src/server/proxy/streaming/openaiResponsesStreamToAnthropicResponse.ts +- src/server/proxy/transform/openaiChatToAnthropic.ts +- src/server/proxy/transform/openaiResponsesToAnthropic.ts +- src/server/proxy/transform/toolArguments.ts +- src/server/proxy/handler.ts +- src/server/upstream/client.ts + +部分阅读:src/services/api/claude.ts(流事件处理 1900-2420、错误与回退 2470-2720、非流式请求 800-900、updateUsage 2977-3080);src/utils/tokens.ts;src/utils/messages.ts(工具参数解析);src/services/tools/toolExecution.ts(输入校验);src/services/api/withRetry.ts(shouldRetry);src/services/api/errors.ts(refusal);src/server/services/sessionService.ts(用量与上下文估算);src/server/api/sessions.ts;src/server/services/networkSettings.ts;src/server/services/titleService.ts;src/services/openaiAuth/fetch.ts;desktop/src/components/chat/LocalSlashCommandPanel.tsx;src/server/__tests__/proxy-streaming.test.ts(并运行,31 通过)。参考实现:codex:codex-api/src/sse/responses.rs、responses_error.rs、protocol/src/error.rs 相关段;ZCode adapters 的 stream-idle-timeout、stream-retry-boundary、streaming-tool-call-assembler、provider-finish-business-error、empty-completion-retry、tool-input-normalization,以及 core 里 finish reason、压缩基准相关文件。 + +未覆盖: +- 任何提供方的真实响应(不做网络请求);文中各提供方的字段和取值来自公开文档,均标推断。 +- AI SDK(`@ai-sdk/openai-compatible`、`@ai-sdk/openai`)源码不在本地,ZCode 在 SDK 层的 SSE 解析、tool call id 缺失处理、usage 归一化未核实。 +- 桌面端和 H5 页对 thinking 块、空签名、`` 文本的渲染细节;会话中途从 openai 格式 provider 切到 Anthropic provider 时空签名 thinking 块的处理。 +- ChatGPT 登录路径(src/services/openaiAuth)只看了它复用流转换器这一点,请求构造与非流式聚合未评审。 +- 请求方向见 [request.md](request.md),非 2xx 错误映射见 [transport.md](transport.md)。 diff --git a/docs/features/harness/proxy/transport.md b/docs/features/harness/proxy/transport.md new file mode 100644 index 00000000..ab94ac4c --- /dev/null +++ b/docs/features/harness/proxy/transport.md @@ -0,0 +1,262 @@ +# 代理层评审:传输、容错与提供方配置(P-NET) + +范围:请求怎样到达提供方再回来、失败时发生什么、DreamCoder 对每个提供方和模型知道什么。DreamCoder 路径相对仓库根;`codex:` 相对 `refs/coding-agents/codex/codex-rs`;`zcode:` 相对 `refs/coding-agents/zcode`。 + +运行验证说明:没有向任何模型提供方发请求。为确认 Bun 运行时行为,在本地用 Bun 1.4.2(项目使用的版本)跑了几个只连 127.0.0.1 的小实验(脚本未收入仓库): +- `idle.ts`:`Bun.serve` 的 `idleTimeout` 会切断「处理函数还没返回响应」的请求,也会切断「已发出部分数据后停顿」的流式响应,并调用流的 `cancel()`。 +- `timeout0.ts`:在处理函数里调用 `server.timeout(req, 0)` 后,同样的慢请求正常完成。 +- `cancel.ts`:仿照代理的结构(`start()` 循环读上游、`cancel()` 里 `reader.cancel()`)。客户端在流开始后中止,上游连接立即被中止;客户端在上游返回响应头之前中止,上游请求继续跑到响应头到达后才被中止。 +- `proxyopt.ts`:Bun `fetch` 的 `proxy` 选项对 `http://127.0.0.1:` 也会走代理;设置 `NO_PROXY=127.0.0.1` 后直连。 +- `msg.ts`:按 SDK 的拼接规则模拟代理返回的 429,确认 CLI 显示的内容(见 P-NET-03)。 + +## 1. 发现清单 + +### P-NET-01 本地 Bun 服务的 60 秒空闲超时会切断走代理的请求,导致重试和重复计费 + +- 类型:问题 +- 严重程度:高 +- 现状: + 1. 服务端用 `Bun.serve({ idleTimeout: 60 })` 启动(src/server/index.ts:152-155),`/proxy/` 路由和其他路由共用这个设置(src/server/index.ts:349-366)。 + 2. 代理处理函数先 `await sendToUpstream(...)`,拿到上游响应头之后才返回 `Response`(src/server/proxy/handler.ts:64-85)。非流式请求要等上游完整返回(src/server/upstream/client.ts:103-116)。 + 3. 流式转换器只在上游有可转换的数据时才向 CLI 写字节:chat 流跳过空行和 `:` 开头的注释行(src/server/proxy/streaming/openaiChatStreamToAnthropic.ts:88-90),Responses 流只处理 `event:`/`data:` 行(src/server/proxy/streaming/openaiResponsesStreamToAnthropic.ts:61-99)。代理自己不发心跳或 `ping` 事件。 + 4. Responses 请求不设 `reasoning.summary`(src/server/proxy/transform/anthropicToOpenaiResponses.ts:17-60),所以 OpenAI 推理模型思考期间不会有 `reasoning_summary_text.delta` 事件(推断:依据 OpenAI 的事件语义)。 + 5. 实验 `idle.ts` 证实:只要连续约 60 秒没有字节写给 CLI,不论处理函数是否已返回,Bun 都会关闭这条连接。 + 6. CLI 收到连接关闭:响应头之前的失败按连接错误重试(src/services/api/withRetry.ts:753-755),最多 10 次;流中途断开则改发非流式请求(src/services/api/claude.ts:2552-2601),非流式请求也走代理、也受 60 秒限制。 + 7. 设置里的「AI 请求超时」(5–600 秒,src/server/services/networkSettings.ts:13-15)同时传给代理和 CLI(`API_TIMEOUT_MS`,src/server/services/networkSettings.ts:76-78;src/services/api/client.ts:214)。在代理路径上,超过 60 秒的设置值不起作用。 +- 场景:自定义提供方,`openai_responses`,OpenAI 官方 `gpt-5` 系列,任务较难,模型静默推理超过 60 秒。第 60 秒左右 Bun 关闭 CLI 的连接,转换器 `cancel()` 中止上游(推断:已产生的输入和推理 token 照常计费)。CLI 改发非流式请求,这次代理要等完整结果,60 秒时再被切断;而非流式的上游请求不会被中止(见 P-NET-02),会在提供方那边跑完并计费,代理拿到结果后无人接收。CLI 再按连接错误重试最多 10 次,每次都重复上述过程。另一个场景:OpenRouter 在排队或推理时发 `: OPENROUTER PROCESSING` 注释保活(推断:依据 OpenRouter 文档),代理把注释丢掉,CLI 一侧仍然 60 秒没有字节。流中途断开后改发非流式请求时,如果流式部分已经开始执行工具,可能重复执行同一工具(推断:claude.ts:2512-2518 的注释说明了这个风险)。 +- 参考:Codex 的流空闲超时按提供方配置,默认 300 秒(codex:model-provider-info/src/lib.rs:68, 515-519),超时报 `idle timeout waiting for SSE`(codex:codex-api/src/sse/responses.rs:584),没有中间进程。ZCode 流空闲超时默认 600 秒(zcode:apps/zcode-cli/packages/contracts/src/config/index.ts:284),每次重试再加 30 秒(zcode:apps/zcode-cli/packages/adapters/src/model/stream-idle-timeout.ts:5-24),也没有中间进程。 +- 改法方向:代理路由对每个请求调用 `server.timeout(req, 0)`(实验 `timeout0.ts` 证实可用),不再依赖全局 60 秒;上游静默时,代理按固定间隔向 CLI 写 Anthropic 的 `ping` 事件,并把上游的注释行当作活动信号;真正的空闲判定放在代理读上游的地方,用一个明确的、可配置的空闲超时(参考 Codex 300 秒)。 +- 确定程度:代码确认;Bun 行为经本地实验确认;具体模型的静默时长为推断。 + +### P-NET-02 提供方的上下文溢出错误认不出来,会话卡死,手动 /compact 也救不回来 + +- 类型:问题 +- 严重程度:高 +- 现状: + 1. 上游返回 400,代理原样保留状态码,把上游响应体包进 `api_error` 的字符串字段(src/server/upstream/client.ts:83-90;src/server/proxy/handler.ts:66-71)。 + 2. CLI 只用 `prompt is too long` 识别上下文溢出(src/services/api/errors.ts:560-573);`parseMaxTokensContextOverflowError` 只认 Anthropic 文案(src/services/api/withRetry.ts:550-575)。400 不重试(withRetry.ts:696-786)。 + 3. 没认出来时,用户看到通用的 `API Error: 400 {...}`(errors.ts 末尾的通用分支)。被动压缩在本构建里是 stub(前一份报告已确认,src/query.ts:15-17)。 + 4. 手动 `/compact` 也要把整段历史发给模型,同样溢出。compact 有一条「截掉最早的消息再试」的路径,但它只在摘要结果以 `Prompt is too long` 开头时才触发(src/services/compact/compact.ts:449-480;src/services/api/errors.ts:62-64),所以也不触发。 + 5. 自动压缩只按配置的上下文窗口提前触发;窗口配大了(见 P-NET-10),或一次工具输出很大,就会越过真实上限。 +- 场景:Qwen 预设(`openai_chat`),模型的真实窗口比 DreamCoder 认定的 200,000 小。某次请求超过真实上限,DashScope 返回 400(文案含 `Range of input length should be`,见下面 ZCode 的匹配规则)。这一轮失败,下一轮带着更长的历史再次失败;用户执行 `/compact` 也失败,只能 `/clear` 或回退。各家的文案:OpenAI `context_length_exceeded`(Codex 测试数据,codex:codex-api/src/sse/responses.rs:1159);DeepSeek 的 OpenAI 格式端点用 `maximum context length ... tokens`(推断);智谱 BigModel 业务码 1261(zcode:apps/zcode-cli/packages/adapters/src/model/failure-provider-business-codes.ts:166-173);Moonshot 是 `total message token length ... exceed ... model limit` 一类文案(推断:依据 ZCode 的匹配规则 zcode:apps/zcode-cli/packages/adapters/src/model/failure-inspection.ts:239-241)。直连路径(Kimi、智谱、DeepSeek 的 Anthropic 端点)的溢出文案是否为 `prompt is too long`,未核实。 +- 参考:Codex 把 `context_length_exceeded` 映射为 `ContextWindowExceeded`,不重试(codex:codex-api/src/sse/responses_error.rs:48;codex:protocol/src/error.rs:434)。ZCode 按错误码和文案识别(`context_length_exceeded` 等 4 个码;`maximum context length`、`prompt is too long`、`range of input length should be`、`input token count ... maximum number of tokens allowed` 等短语,zcode:apps/zcode-cli/packages/adapters/src/model/failure-inspection.ts:212-245),400/422 时归为上下文超限(zcode:apps/zcode-cli/packages/adapters/src/model/failure-classifier.ts:229-244),由上层触发压缩(前一份报告:zcode:apps/zcode-cli/packages/core/src/runtime/internal-turn-methods.ts:191)。 +- 改法方向:在代理里识别各家的溢出错误码和文案(可照 ZCode 的匹配表),改写成 Anthropic 形态:400、`invalid_request_error`、消息以 `prompt is too long` 开头,能解析出数字时带上 `N tokens > M maximum`,这样 CLI 现有的识别和 compact 的截头重试会生效;直连路径的识别放在 CLI 的 errors.ts,两处共用同一张匹配表。 +- 确定程度:代码确认(DreamCoder 一侧);各提供方文案部分为推断。 + +### P-NET-03 代理转发错误时把原因转义进字符串、丢掉响应头,429 时用户看不到原因 + +- 类型:问题 +- 严重程度:中 +- 现状: + 1. 上游非 2xx:代理读出响应体前 500 字,拼成 `Upstream returned HTTP : `,作为 `{type:'error', error:{type:'api_error', message}}` 返回,状态码沿用,上游响应头全部丢弃(src/server/upstream/client.ts:83-90;src/server/proxy/handler.ts:66-71)。网络错误和超时得到 502,消息为 `Request timed out (120s)` 或底层错误文本(client.ts:76-81;handler.ts:70)。 + 2. SDK 生成错误消息时,响应体没有顶层 `message`,于是把整个 JSON 序列化为 `" {json}"`(node_modules/@anthropic-ai/sdk/core/error.js,SDK 0.98.0,`makeMessage`)。上游原文在里面是转义过的字符串。 + 3. CLI 的 429 分支用正则 `"message"\s*:\s*"([^"]*)"` 取内层消息(src/services/api/errors.ts:551-556)。第一处匹配是代理那层的 message,`[^"]*` 碰到转义引号就停。实验 `msg.ts` 的结果:用户看到 `API Error: Request rejected (429) · Upstream returned HTTP 429: {\`,原因丢失。 + 4. 丢掉 `retry-after` 后,CLI 用自己的退避:0.5 秒起,翻倍,封顶 32 秒(src/services/api/withRetry.ts:530-548),不知道提供方要等多久。丢掉 `x-request-id` 后,无法拿请求号找提供方查问题。 + 5. `is529Error` 和 `shouldRetry` 里的 `"type":"overloaded_error"` 子串检查(withRetry.ts:610-621, 733-735)对转义后的文本也匹配不上(实验确认)。 +- 场景:OpenAI 兼容端点返回 429,正文写着「请 20 秒后重试」,响应头 `retry-after: 20`。CLI 在 0.5、1、2、4、8 秒后连续重试(前 5 次都早于 20 秒),每次都被拒;10 次用完后,用户看到上面那条被截断的消息。 +- 参考:Codex 保留状态码、响应头和正文,从 `retry-after` 或正文的「try again in Ns」取等待时间(codex:codex-api/src/sse/responses_error.rs:90-96, 104-110;codex:codex-client/src/retry.rs:103-110),并从响应头取 request id 用于诊断(codex:response-debug-context/src/lib.rs:19-35)。ZCode 解析 `retry-after` 和 `retry-after-ms`,在其上加不超过 20% 且不超过 5 秒的抖动(zcode:apps/zcode-cli/packages/adapters/src/model/runner-retry.ts:40-60, 97-110)。 +- 改法方向:代理解析上游错误体,取出 message、code、type,作为 Anthropic 错误体的 `error.message`(不再整体塞进字符串),`error.type` 按状态码映射(`rate_limit_error`、`authentication_error`、`invalid_request_error`、`overloaded_error` 等);透传 `retry-after`、`retry-after-ms` 和上游 request id 响应头。 +- 确定程度:代码确认,CLI 显示经本地模拟确认。 + +### P-NET-04 重试分类按 Anthropic 设计,对第三方提供方会重试不该重试的错误、等待过久 + +- 类型:问题 +- 严重程度:中 +- 现状(主循环请求 `maxRetries` 默认 10,即最多 11 次,src/services/api/withRetry.ts:52, 789-794;SDK 自身重试关闭,claude.ts:1831): + 1. 401 总是重试(withRetry.ts:773-776)。这是为 OAuth 令牌刷新设计的;对固定 API key,重试 10 次后结果不变。 + 2. 429 总是重试(withRetry.ts:767-770),不区分限流和余额或配额耗尽。 + 3. 5xx 和连接错误重试(withRetry.ts:753-755, 784)。代理在上游超时或网络失败时返回 502(handler.ts:70),每次要等满 `aiRequestTimeoutMs`(默认 120 秒)才失败,再按 5xx 重试。 + 4. 非流式请求收到 2xx 但正文是 `{"error":...}` 时,代理返回 502(src/server/upstream/client.ts:103-107, 299-303),CLI 按 5xx 重试,不管这个错误本身是什么。 + 5. 流式请求中途出错(代理发 SSE `error` 事件,src/server/proxy/streaming/openaiChatStreamToAnthropic.ts:497-505;openaiResponsesStreamToAnthropic.ts:307-315)时,CLI 改发非流式请求,并开始一轮新的 `withRetry`(claude.ts:2552-2601;executeNonStreamingRequest,claude.ts:817-900)。两轮叠加,一次调用最多 22 次请求。代理本身不重试,三层不会再叠加。 +- 场景: + - 填错 key:上游 401,CLI 等约 160 秒(0.5+1+2+4+8+16+32×4,另加最多 25% 抖动)后才显示 `Failed to authenticate`(errors.ts:864-880)。 + - 余额或配额耗尽:OpenAI `insufficient_quota`、Moonshot `exceeded_current_quota_error`、智谱 1113 都以 429 返回(推断:依据 ZCode 的注释和映射,zcode:apps/zcode-cli/packages/adapters/src/model/failure-provider-business-codes.ts:174-181, 294-313),CLI 照样等约 160 秒,最后显示的还是 P-NET-03 那条截断消息。Kimi 和智谱预设走直连,同样受影响。 + - 上游挂起不回响应头:11 次 × 120 秒超时,加上约 160 秒退避,用户大约 25 分钟后才看到错误。 +- 参考:Codex 的 HTTP 层只重试 5xx 和传输错误,不重试 429,最多 4 次,基础间隔 200 毫秒(codex:model-provider-info/src/lib.rs:70, 455-461;codex:codex-client/src/retry.rs:23-41);配额类错误码直接终止(codex:codex-api/src/api_bridge.rs:223-233;codex:codex-api/src/sse/responses_error.rs:49-54)。ZCode 401/403 不重试(zcode:apps/zcode-cli/packages/adapters/src/model/failure-classifier.ts:218-226);配额类码和 BigModel 的 1113、1304、1308 等终止,1302、1303 等限流可重试(failure-provider-business-codes.ts:174-327);默认 10 次重试,2 秒起,封顶 60 秒(zcode:apps/zcode-cli/packages/adapters/src/model/retry-policy.ts:13-30)。 +- 改法方向:对 API key 类提供方(所有 DreamCoder 预设和自定义提供方)不重试 401/403;代理按错误码和文案把配额、余额类错误标为终止(比如改成 400 或 403,并给出可读消息),或由 CLI 依据代理传回的 `error.type` 判断;2xx 正文里的错误按其内容映射状态码,不统一用 502;网络超时类失败减少重试次数。 +- 确定程度:代码确认;各提供方错误码对应的 HTTP 状态为推断。 + +### P-NET-05 代理不随 CLI 中止上游请求:非流式请求和等待响应头期间的请求会跑完并计费 + +- 类型:问题 +- 严重程度:中 +- 现状: + 1. `handleProxyRequest` 不读 `req.signal`(src/server/proxy/handler.ts:8-85);`sendToUpstream` 的 `fetch` 只挂超时信号(非流式用 `AbortSignal.timeout`,流式用一个只在等响应头期间生效的定时器,src/server/upstream/client.ts:258-277)。 + 2. 流式响应开始后,CLI 断开会触发转换器的 `cancel()`,进而 `reader.cancel()` 中止上游(openaiChatStreamToAnthropic.ts:143-146;openaiResponsesStreamToAnthropic.ts:107-110)。实验 `cancel.ts` 证实这一段能立即传到上游。 + 3. 在上游返回响应头之前 CLI 断开:上游请求继续,直到响应头到达后流才被取消(实验确认)。非流式请求:上游一直跑到完成或 120 秒超时。 +- 场景:用户点「停止」或删除会话,而此时 CLI 正在走非流式回退请求(例如 P-NET-01 之后)。提供方继续生成完整回复并计费,代理拿到结果后丢弃。CLI 因 P-NET-01 重试时,前一次的非流式上游请求也没有被中止,多次重试的生成同时进行。 +- 参考:ZCode 每次尝试都用与调用方中止信号联动的 AbortController(zcode:apps/zcode-cli/packages/adapters/src/model/runner-stream.ts:175-178;stream-idle-timeout.ts:63-80)。Codex 中止回合时丢弃请求 future,底层连接随之关闭(推断:Rust async 的取消语义,未逐行核对)。 +- 改法方向:`sendToUpstream` 接收调用方的 `AbortSignal`,与超时信号合并(`AbortSignal.any`),代理把 `req.signal` 传进去。 +- 确定程度:代码确认,传播行为经本地实验确认。 + +### P-NET-06 OpenAI 格式的 base URL 被强制改成 `.../v1/...`,版本号不是 v1 的提供方都会 404 + +- 类型:问题 +- 严重程度:中 +- 现状:`normalizeUpstreamBaseUrl` 只去掉末尾的 `/v1`(src/server/upstream/baseUrl.ts:1-3),然后固定拼上 `/v1/chat/completions` 或 `/v1/responses`(src/server/upstream/client.ts:211-222);拉取模型列表固定拼 `/v1/models`(client.ts:121, 136)。界面上 base URL 的占位符只举了 Anthropic 的例子(desktop/src/i18n/locales/en.ts:500)。 +- 场景:自定义提供方,`openai_chat`,填智谱 OpenAI 兼容地址 `https://open.bigmodel.cn/api/paas/v4`。请求实际发到 `.../api/paas/v4/v1/chat/completions`,404,连「测试连接」和「拉取模型」都失败。同样受影响的还有 Z.ai `https://api.z.ai/api/paas/v4`(这两个地址取自 zcode:config/provider/zcode-builtin.json:42, 112)、火山方舟 `.../api/v3`、Gemini 的 OpenAI 兼容地址 `.../v1beta/openai`(这两个为推断,依据公开文档)。 +- 参考:Codex 把 base_url 当作已经含版本号的完整前缀,只追加 `/responses`,另可附加 query 参数(codex:codex-client/src/provider.rs:55-77;默认值 `https://api.openai.com/v1`,codex:model-provider-info/src/lib.rs:441-446)。ZCode 的 openai-compatible 直接把 baseURL 交给 SDK,由 SDK 追加 `/chat/completions`,只对 Anthropic 格式补 `/v1`(zcode:apps/zcode-cli/packages/adapters/src/model/model-execution.ts:333-360, 466-480)。 +- 改法方向:OpenAI 格式下,base URL 末段已经是版本号(`/v\d+…`)或含 `/openai` 时直接追加 `/chat/completions`、`/responses`、`/models`,否则仍补 `/v1`,这样已保存的 `https://api.openai.com` 一类地址继续可用;表单给出 OpenAI 格式的占位示例。 +- 确定程度:代码确认;ZCode 配置里的智谱地址为仓库内证据,其余提供方地址为推断。 + +### P-NET-07 手动代理模式下,CLI 访问本地代理的请求也被送进外部 HTTP 代理 + +- 类型:问题 +- 严重程度:中 +- 现状: + 1. 网络设置为手动代理时,服务端给 CLI 进程设置 `HTTP_PROXY`、`HTTPS_PROXY` 及小写版本,但不设置 `NO_PROXY`(src/server/services/networkSettings.ts:75-89;conversationService.ts:1036)。 + 2. CLI 创建 SDK 客户端时用 `getProxyFetchOptions({ forAnthropicAPI: true })`(src/services/api/client.ts:216-218);在 Bun 下,只要有代理地址就返回 `{ proxy }`,不检查 `NO_PROXY`(src/utils/proxy.ts:307-315)。 + 3. 走代理的提供方,CLI 的 `ANTHROPIC_BASE_URL` 是 `http://127.0.0.1:/proxy...`(src/server/services/providerRuntimeEnv.ts:214-216)。实验 `proxyopt.ts` 证实:Bun 的 `proxy` 选项对 127.0.0.1 照样生效,只有设置了 `NO_PROXY` 才直连。 +- 场景:公司网络,用户在设置里填 `http://proxy.corp:8080`,使用 `openai_chat` 提供方。CLI 把发往 `127.0.0.1:` 的请求交给 proxy.corp,proxy.corp 连的是它自己的 127.0.0.1,连接失败或返回 502,CLI 按 5xx 或连接错误重试 10 次后报错,所有走代理的提供方都不可用。用本机 Clash(`127.0.0.1:7890`)时能否通,取决于 Clash 规则是否让回环地址直连。系统代理模式下,如果应用继承的环境里有 `HTTPS_PROXY` 而没有 `NO_PROXY`,情况相同。 +- 参考:ZCode 给子进程环境显式处理 `NO_PROXY`/`no_proxy`(zcode:apps/zcode-cli/packages/adapters/src/network/subprocess-env.ts:30-40, 104-110),自己的 fetch 按 `NO_PROXY` 判断是否绕过代理(zcode:apps/zcode-cli/packages/adapters/src/network/http-config.ts:190-200)。Codex:无对应(不经本地中转)。 +- 改法方向:`buildNetworkEnvironment` 同时写入 `NO_PROXY`/`no_proxy`,至少包含 `127.0.0.1,localhost,::1`,并与已有值合并;`getProxyFetchOptions` 的 Bun 分支用已有的 `shouldBypassProxy` 判断。 +- 确定程度:代码确认,Bun 行为经本地实验确认。 + +### P-NET-08 直连路径没有流空闲超时,连接半开时会话无限等待;两条路径的超时语义不一致 + +- 类型:问题 +- 严重程度:中 +- 现状:CLI 的流空闲看门狗默认关闭,要设 `CLAUDE_ENABLE_STREAM_WATCHDOG` 才开(src/services/api/claude.ts:1924-1928)。SDK 的 `timeout`(= `API_TIMEOUT_MS`)只管到响应头(推断:SDK 行为,claude.ts:1916-1923 的注释也这样说明)。代理路径的上游 fetch 在拿到响应头后清掉定时器(src/server/upstream/client.ts:268-276),此后唯一的空闲限制是 P-NET-01 的 Bun 60 秒。结果:代理路径 60 秒(对静默推理太短),直连路径没有上限。 +- 场景:Kimi 预设(直连),笔记本合盖或切换 Wi‑Fi 后 TCP 连接半开,流不再有数据,也没有收到断开通知。会话一直显示在生成,直到用户手动停止。 +- 参考:Codex 每个提供方默认 300 秒(codex:model-provider-info/src/lib.rs:68, 515-519);ZCode 默认 600 秒,每次重试加 30 秒(zcode:apps/zcode-cli/packages/contracts/src/config/index.ts:284;zcode:apps/zcode-cli/packages/adapters/src/model/stream-idle-timeout.ts:5-24)。 +- 改法方向:DreamCoder 启动 CLI 时默认打开流空闲看门狗,超时取一个与 P-NET-01 的代理空闲超时一致的值;代理的 `ping` 心跳会重置看门狗,二者不冲突。 +- 确定程度:代码确认(默认关闭);半开连接场景为推断。 + +### P-NET-09 自定义提供方对所有模型一律声明全部思考能力,没有按模型的能力配置 + +- 类型:问题 +- 严重程度:中 +- 现状:`presetId === 'custom'` 时,三档模型的 `*_SUPPORTED_CAPABILITIES` 都设为 `thinking,effort,adaptive_thinking,max_effort`,主模型同时作为 SONNET 和 OPUS 默认模型(src/server/services/providerRuntimeEnv.ts:38, 229-250),与 `apiFormat` 和模型无关。CLI 按这些覆盖值决定发 `thinking:{type:'adaptive'}`,允许 `max` 档 effort(src/utils/model/modelSupportOverrides.ts:30-48;thinking.ts:91-95, 125-129;effort.ts:28-31, 53-56;claude.ts:1649-1659)。`SavedProvider` 没有能力字段,界面上无法修改(src/server/types/provider.ts:46-59)。 +- 场景:自定义 Anthropic 格式提供方,是一个转发 `claude-sonnet-4-5` 的中转站。CLI 发 `thinking:{type:'adaptive'}`;按 CLI 自己的判断,adaptive 只有 opus-4-6、sonnet-4-6 及更新的模型支持(thinking.ts:139-150),上游返回 400(推断:依据 Anthropic API 对旧模型的行为)。用户把 Effort 设为 max 时,代码注释说其他模型会报错(effort.ts:50-51)。走代理的自定义提供方上,adaptive 不产生任何推理字段(前一份报告已述)。 +- 参考:ZCode 有按模型正则、协议、站点叠加的规则(zcode:config/provider/zcode-builtin.json 中 `modelRules` 83 条、`modelApiRules` 73 条、`providerSiteRules` 58 条),用户手动模型可覆盖窗口、输出上限、推理档位等字段(前一份报告:zcode:packages/provider/src/config/manual-model-config.ts:7-28)。Codex 有内置目录和可选的 `model_catalog_url`,未知模型用回退元数据:不发 effort,窗口 272,000(codex:models-manager/src/model_info.rs:98-146)。 +- 改法方向:提供方的每个模型保存能力声明(thinking、adaptive、effort、max effort、窗口、输出上限),自定义提供方的默认值按 `apiFormat` 和模型名给出(Claude 名字按 CLI 已有判断,其他名字取保守值),界面允许修改;服务端按所选模型生成环境变量,不再整档写死。 +- 确定程度:代码确认;中转站返回 400 为推断。 + +### P-NET-10 Qwen 预设没有声明上下文窗口;窗口只在用户手动「拉取模型」时获取,未知模型一律当 200,000 + +- 类型:问题 +- 严重程度:中 +- 现状: + 1. DeepSeek、Kimi、智谱预设带 `modelContextWindows`;Qwen 预设没有,也没有能力声明(src/server/config/providerPresets.json;Qwen 默认模型 `qwen-max`、`qwen-plus`、`qwen-turbo`)。 + 2. CLI 的窗口查找顺序:环境变量 `CLAUDE_CODE_MODEL_CONTEXT_WINDOWS`,然后内置表,最后 200,000(src/utils/context.ts:11, 53-115)。内置表有 `qwen3-max`、`qwen3.5-*`、`qwen-long`,没有上面三个名字(src/utils/model/modelContextWindows.ts:5-48)。 + 3. 窗口发现(`/v1/models` 列表字段、DashScope 和 DeepSeek 的专用接口等)只在拉取模型时运行(src/server/upstream/client.ts:187-189;src/server/upstream/contextWindows/index.ts:11-66),结果作为表单建议值(desktop/src/components/settings/ProviderFormModal.tsx:592-616),之后不会刷新。会话启动和运行时都不查询提供方。 + 4. 输出上限:非 Claude 名字的模型 CLI 用 32,000(前一份报告:context.ts:203-260),代理路径上不转发。 +- 场景:用户选 Qwen 预设,保留默认模型 `qwen-max`,不点拉取模型。DreamCoder 按 200,000 计算自动压缩;若 `qwen-max` 的真实窗口是约 32K(未核实,依据对阿里云文档的记忆),固定开销(前一份报告估算约 12 万字符的 system 和工具描述)已经接近或超过上限,第一轮或前几轮就会溢出,然后进入 P-NET-02 的卡死状态。 +- 参考:ZCode 内置规则给每个已知模型写窗口和输出上限,未知模型用基线 1,000,000 和 128,000(zcode:config/provider/zcode-builtin.json `modelRules[0]`)。Codex 未知模型回退 272,000,并标记 `used_fallback_model_metadata`(codex:models-manager/src/model_info.rs:98-146);对 OpenAI 兼容提供方可从 `/models` 刷新目录,5 秒超时(codex:model-provider/src/models_endpoint.rs:44-45)。 +- 改法方向:Qwen 预设补上默认模型的窗口(可用 DashScope 接口在发布前核对),并更新默认模型列表;创建或编辑预设提供方时,自动对有专用来源的主机运行一次窗口发现,不依赖用户点击。 +- 确定程度:代码确认;Qwen 各模型的真实窗口未核实。 + +### P-NET-11 走代理的提供方不能配置额外请求头和 query 参数 + +- 类型:优化 +- 严重程度:低 +- 现状:代理发往上游的请求头只有 `Content-Type` 和 `Authorization: Bearer`(src/server/upstream/client.ts:213, 221),URL 不带 query 参数;OpenAI 格式下 `authStrategy` 不起作用。`SavedProvider` 没有请求头字段(src/server/types/provider.ts:46-59)。直连路径的 CLI 支持 `ANTHROPIC_CUSTOM_HEADERS`(src/services/api/client.ts:404-428),但提供方表单不会写入它。 +- 场景:Azure OpenAI 需要 `api-key` 请求头和 `api-version` query 参数(推断:依据 Azure 文档),在 DreamCoder 里无法接入;OpenRouter 建议的 `HTTP-Referer`/`X-Title` 归因头也无法设置。 +- 参考:Codex 的提供方有 `http_headers`、`env_http_headers`、`query_params`(codex:model-provider-info/src/lib.rs:173-181, 399-426;codex:codex-client/src/provider.rs:64-74)。ZCode 的提供方 `api.headers`(zcode:packages/provider/src/config/provider-data-schema.ts:70;zcode:packages/provider/src/resolver.ts:63),并对 OpenRouter 自动加归因头(zcode:apps/zcode-cli/packages/adapters/src/model/model-execution.ts:231)。 +- 改法方向:`SavedProvider` 增加可选的请求头和 query 参数,代理和直连两条路径都使用;鉴权头仍由 `authStrategy` 决定,不允许被覆盖。 +- 确定程度:代码确认。 + +### P-NET-12 代理日志不足以诊断失败的上游请求,也没有逐请求的统计 + +- 类型:优化 +- 严重程度:低 +- 现状:代理只在上游返回非 2xx 或网络失败时打一行 `console.error('[Proxy] Upstream request failed:', result.error)`(src/server/proxy/handler.ts:67),被诊断服务捕获并脱敏写入 diagnostics 文件(src/server/services/diagnosticsService.ts:70-112)。这一行没有提供方 id、模型、上游主机和路径、apiFormat、耗时、上游 request id。流中途的上游错误(SSE `error`)、上游连接中断、Bun 空闲断开都不记录。成功请求不记录。token 用量只来自 CLI 写入转录的 usage,由会话服务汇总(src/server/services/sessionService.ts:868-890);代理侧没有按提供方和模型的请求数、失败数、延迟统计。key 不会出现在这行日志里(只含上游响应体前 500 字),诊断文件按键名再做一次脱敏(diagnosticsService.ts:42, 258-270)。 +- 场景:用户报告「OpenRouter 上某模型经常卡住然后报错」,日志里要么什么都没有(P-NET-01 的断开不记录),要么只有一行不带模型和提供方的 `Upstream returned HTTP 502: ...`,无法区分是哪个会话、哪个提供方、在第几秒失败。 +- 参考:Codex 每次请求和重试都有遥测(尝试次数、状态、耗时,codex:codex-client/src/telemetry.rs:5-14;codex:codex-client/src/retry.rs:62-81),并从响应头提取 request id(codex:response-debug-context/src/lib.rs:19-35)。ZCode 按 `x-request-id` 记录请求观测(zcode:apps/zcode-cli/packages/adapters/src/model/request-observations.ts:1-40),调试输出有专门的脱敏(zcode:apps/zcode-cli/packages/adapters/src/model/runner-debug-redaction.ts)。 +- 改法方向:代理对每个请求记一条结构化事件(提供方 id、模型、上游主机、格式、状态、耗时、首字节时间、结束原因、上游 request id,不含 key 和正文),失败和流中途错误记为 warn/error,写入现有 diagnostics。 +- 确定程度:代码确认。 + +### P-NET-13 代理不支持 count_tokens;终端里的 `/context` 会把每个统计项变成一次完整生成 + +- 类型:问题 +- 严重程度:低 +- 现状: + 1. 代理只接 `POST .../v1/messages`,其他路径返回 404,正文不是 Anthropic 错误格式(src/server/proxy/handler.ts:9-21)。 + 2. `countMessagesTokensWithAPI` 调 `/v1/messages/count_tokens`,失败返回 null(src/services/tokenEstimation.ts:141-196)。读大文件时(FileReadTool.ts:764)只是多一次本地往返,然后用估算值。 + 3. `/context` 在非估算模式下,API 计数失败后调用 `countTokensViaHaikuFallback`,发一次 `max_tokens: 1` 的 `/v1/messages`(tokenEstimation.ts:233-302);代理不转发 `max_tokens`(src/server/proxy/transform/types.ts:35-36 有字段,转换代码不赋值),上游按默认上限完整生成。system 的每一段、每个记忆文件、每个自定义 agent 等各发一次,并发执行(src/utils/analyzeContext.ts:327-331, 368-376, 786-795)。 + 4. 桌面端拦截 `/context`,用 `estimateOnly: true` 只做估算(desktop/src/components/chat/LocalSlashCommandPanel.tsx:1104;src/server/api/sessions.ts:535-548),不受影响。 +- 场景:用户在终端运行 dreamcoder CLI,提供方由桌面端的 active provider 注入(src/utils/managedEnv.ts:109-111,基础地址指向本地代理),提供方是 `openai_chat`。输入 `/context` 后,CLI 并发发出几十个请求,每个都让模型完整回答一段 system 文本,按全价计费,并可能触发 429。 +- 参考:Codex、ZCode:无对应(没有 count_tokens 调用)。 +- 改法方向:代理对 `/v1/messages/count_tokens` 返回本地估算值(Anthropic 响应格式),或返回 Anthropic 格式的 404,并让 CLI 在代理提供方上跳过 Haiku 回退;`max_tokens` 的转发由请求形态评审处理。 +- 确定程度:代码确认。 + +### P-NET-14 各预设的能力声明不一致,同一个 Effort/思考开关在不同预设上产生不同的请求字段 + +- 类型:优化 +- 严重程度:低 +- 现状:DeepSeek 预设声明三档 `thinking,effort,adaptive_thinking,max_effort`;Kimi、智谱预设不声明能力,只设 `DREAMCODER_SEND_DISABLED_THINKING=1`;Qwen 什么都不设(src/server/config/providerPresets.json)。不声明能力时,CLI 对 `kimi-k2.6`、`glm-5.1` 判定不支持 thinking(非一方地址时只认 sonnet-4/opus-4,src/utils/thinking.ts:91-117),但判定支持 effort(未知名字在 firstParty 下返回 true,src/utils/effort.ts:23-49)。于是 Kimi、智谱直连时:思考开启,不发 `thinking`,由提供方默认决定;思考关闭,发 `thinking:{type:'disabled'}`(claude.ts:1596-1600, 1674-1678);两种情况下都可能发 `output_config.effort`(claude.ts:1607-1616, 439-465)。 +- 场景:用户在 Kimi 预设上把 Effort 从 high 调到 low,请求里的 `output_config.effort` 变了;Kimi 的 Anthropic 端点是否理会这个字段,未核实。用户以为调节有效,实际可能不起作用。 +- 参考:ZCode 每个模型和站点写明推理档位以及映射到哪个请求字段(zcode:config/provider/zcode-builtin.json `providerSiteRules`,例如 glm-5.3-flash 映射到 `reasoning_effort`)。Codex:无对应(只有 OpenAI 模型)。 +- 改法方向:与 P-NET-09 合并处理:每个预设的每个默认模型显式声明能力,界面只在声明支持时显示 Effort 档位。 +- 确定程度:代码确认;提供方是否理会这些字段未核实。 + +## 2. 已知结论的核实 + +| 已知结论 | 结论 | 说明与位置 | +|---|---|---| +| 上游错误统一包成 `api_error`,响应头(含 `retry-after`)丢失 | 确认并补充 | src/server/upstream/client.ts:83-90;src/server/proxy/handler.ts:66-71。补充:状态码保留;上游原文被转义进字符串,导致 429 分支只显示到 `{\`,`overloaded_error` 子串也匹配不上(P-NET-03,本地模拟确认);`x-request-id` 一并丢失;网络失败和超时统一为 502,按 5xx 重试,每次等满超时(P-NET-04)。 | +| `max_tokens` 和 effort 不转发 | 确认(属请求形态,未深入) | `max_tokens` 有类型字段无赋值(src/server/proxy/transform/types.ts:35-36, 112);Responses 转换也不设 `max_output_tokens`(anthropicToOpenaiResponses.ts:17-60)。补充一个由此引发的计费后果:P-NET-13。 | +| `reasoning_content` 只对 deepseek 和 opencode.ai 主机回写 | 确认 | `shouldUseDeepSeekReasoningCompat` 用主机名正则判断(src/server/upstream/client.ts:206-210, 251-256);同一判断还控制是否透传 `thinking` 开关。 | +| 计费头 `cch` 每请求变化 | 不在本部分,未复核哈希;补充一处不一致 | 代理对所有请求无条件加计费头(handler.ts:64;claudeCodeAttribution.ts:29-46),不看 `CLAUDE_CODE_ATTRIBUTION_HEADER`。服务端对非 Claude 模型名把这个变量设为 0(attributionHeaderPolicy.ts;providerRuntimeEnv.ts:251),直连路径因此不加;代理路径对同一模型名照加。 | +| 图片、无 id 的工具调用、`cache_control` | 不在本部分,未复核 | — | + +前一份报告中属于本部分、本次另行核对的几点: +- 代理超时只覆盖到响应头:确认(client.ts:258-277)。补充:此后的实际空闲上限是 Bun 的 60 秒(P-NET-01)。 +- CLI 重试 10 次,0.5 秒起翻倍,封顶 32 秒,加不超过 25% 的抖动:确认(withRetry.ts:52-55, 530-548)。补充:`retry-after` 没有上限,直连路径上提供方给多大就等多久(withRetry.ts:535-539)。 +- 流中途出错改走非流式:确认(claude.ts:2512-2601),默认开启(GrowthBook 默认 false,claude.ts:2520-2524)。补充:与第一轮 `withRetry` 叠加(P-NET-04),并受 P-NET-01 影响。 + +### 第 3 项要求的错误逐项表(代理路径,OpenAI 兼容上游) + +| 上游错误 | CLI 收到 | CLI 行为 | 用户看到 | 评价 | +|---|---|---|---|---| +| 400 参数错误 | 400,`api_error` 包装 | 不重试 | `API Error: 400 {"type":"error",...转义的上游原文...}` | 不重试正确;文本难读 | +| 401 | 401 | 重试 10 次,约 160 秒 | `Failed to authenticate. API Error: 401 {...}`(errors.ts:864-880) | 不应重试(P-NET-04) | +| 403 | 403 | 不重试 | 同 401 的认证提示 | 地区或权限类 403 也被说成认证失败 | +| 404 模型不存在 | 404 | 不重试 | 「所选模型 X 可能不存在或无权访问」(errors.ts:905-917) | 合理;部分提供方对未知模型返回 400,只能显示通用文本 | +| 413 | 413 | 不重试 | 请求过大提示(errors.ts:659-664) | 合理 | +| 429 带 `retry-after` | 429,响应头被丢 | 按自身退避重试 10 次 | `Request rejected (429) · Upstream returned HTTP 429: {\` | 早于提供方要求重试;原因丢失(P-NET-03) | +| 429 不带 `retry-after` | 同上 | 同上 | 同上 | 退避本身合理;原因丢失 | +| 429 配额或余额耗尽 | 同上 | 同上,约 160 秒 | 同上 | 应立即终止(P-NET-04) | +| 402 余额不足(DeepSeek 一类) | 402 | 不重试 | 通用 `API Error: 402 {...}` | 可接受 | +| 500/502/503/504 | 原状态码 | 重试 10 次 | 最后显示 `API Error: 5xx {...}` | 次数偏多但可接受(Codex 4 次,ZCode 10 次) | +| 代理到上游超时或网络失败 | 502 | 按 5xx 重试,每次等满超时 | 约 25 分钟后看到错误 | 等待过长(P-NET-04) | +| 上下文溢出(OpenAI、DashScope、Moonshot、BigModel 各自的文案或码) | 400 | 不重试,不压缩 | 通用 400 文本;之后每轮失败,`/compact` 也失败 | 会话卡死(P-NET-02) | +| 内容过滤:chat 流 `finish_reason: content_filter` | 映射为 `end_turn`(openaiChatStreamToAnthropic.ts:535) | 当作正常结束 | 回复中途结束,没有说明 | Codex 把 ContentFilter 作为可重试错误并在历史中记录提示(codex:core/src/responses_retry.rs:63-80) | +| 内容过滤:Responses `incomplete` | 不看 `incomplete_details.reason`,一律映射为 `max_tokens`(openaiResponsesStreamToAnthropic.ts:325-327) | 触发「输出超限」续写,最多 3 次 | 「超过 32000 输出上限」类提示 | 判断错误(属响应转换,此处只记录) | +| 2xx 但正文是错误(非流式) | 502 | 按 5xx 重试 10 次 | 上游 message 文本 | 应按错误内容分类(P-NET-04) | +| 2xx 流中出现 error 对象 | SSE `error`,无状态码 | 改发非流式请求,再走一轮重试 | 依第二次的结果而定 | 多一次完整请求 | + +直连路径(Kimi、智谱、DeepSeek 的 Anthropic 端点):状态码和响应头原样到达 CLI,`retry-after` 生效(没有上限);401 同样重试 10 次;429 配额类同样重试;上下文溢出是否被识别,取决于提供方文案是否含 `prompt is too long`(未核实)。 + +### 第 6 项:直连 Anthropic 格式路径发出的 Anthropic 专有内容 + +- `anthropic-beta`:不发。`getMergedBetas` 对非一方地址返回空数组(src/utils/betas.ts:398-404),`useBetas` 为假(claude.ts:1415, 1763),因此 `context_management` 也不发(claude.ts:1767-1770)。 +- `output_config.effort`:DeepSeek 预设声明了 effort,会发;Kimi、智谱因 `modelSupportsEffort` 对未知名字为真,也会发(P-NET-14)。 +- `thinking`:DeepSeek 发 `adaptive`;Kimi、智谱只在关闭时发 `disabled`(P-NET-14)。 +- `metadata.user_id`:总是发,内容是含 `device_id`、`session_id` 的 JSON 字符串(claude.ts:502-527, 1764),会送到第三方提供方。没有已知的失败,属隐私层面的考虑。 +- `cache_control`:照发在消息块上(claude.ts:3131-3290);`ttl: '1h'` 只对符合条件的一方用户生效(claude.ts:357-372)。各端点是否理会未核实。 +- 计费头:非 Claude 模型名不加(attributionHeaderPolicy.ts;providerRuntimeEnv.ts:251)。 +- 代理侧的修复是否也需要用在直连路径:P-NET-02(溢出识别)、P-NET-04(401 和配额类重试)、P-NET-08(空闲超时)需要在 CLI 一侧处理,直连路径才能受益;P-NET-01、P-NET-03、P-NET-05、P-NET-06、P-NET-07 只涉及代理路径。 + +## 3. 覆盖范围 + +完整阅读: +- src/server/proxy/handler.ts、claudeCodeAttribution.ts +- src/server/upstream/client.ts、baseUrl.ts、contextWindows/(index、source、listed、qwen、deepseek) +- src/server/services/providerRuntimeEnv.ts、networkSettings.ts(前 90 行)、attributionHeaderPolicy.ts +- src/server/config/providerPresets.json +- src/services/api/withRetry.ts +- src/utils/model/modelSupportOverrides.ts + +部分阅读(与本部分相关的段落):src/server/index.ts(服务启动与路由)、h5AccessPolicy.ts、middleware/cors.ts、proxy/streaming 两个流转换器(开头、结尾、取消、错误、结束原因)、anthropicToOpenaiResponses.ts、providerService.ts(测试连接、拉取模型)、titleService.ts、conversationService.ts(CLI 环境)、diagnosticsService.ts、src/services/api/client.ts、errors.ts、claude.ts(参数构建、流式与非流式回退、用量合并)、src/utils/proxy.ts、betas.ts、thinking.ts、effort.ts、modelContextWindows.ts、tokenEstimation.ts、analyzeContext.ts、compact.ts(PTL 重试)、Anthropic SDK 0.98.0 的 core/error.js 与 core/streaming.js。 + +参考实现:Codex 的 model-provider-info/src/lib.rs、codex-client/src/provider.rs 与 retry.rs、core/src/responses_retry.rs、protocol/src/error.rs(retry_delay)、codex-api/src/api_bridge.rs 与 sse/responses_error.rs(部分)、model-provider/src/models_endpoint.rs(开头);ZCode 的 adapters/src/model 下 retry-policy、runner-retry、failure-classifier、failure-inspection、failure-provider-business-codes、stream-idle-timeout、model-execution(provider 创建与 base URL)、model-request-headers、request-observations,adapters/src/network(NO_PROXY),config/provider/zcode-builtin.json 的结构与相关条目。 + +没有覆盖: +- 请求和响应字段的逐项翻译(另一位评审负责),只在影响传输或计费时引用。 +- 请求体大小和压缩:Bun.serve 默认请求体上限、上游请求是否压缩,没有逐项核对;没有找到会撞上限的具体场景。 +- TLS:代理和 CLI 都经 `getProxyFetchOptions` 使用同一套 CA/mTLS 设置(src/utils/proxy.ts:288-321),没有进一步核对。 +- 「系统代理」模式只读取进程继承的环境变量(界面文案也这样写,desktop/src/i18n/locales/en.ts:1045),不读 macOS 系统代理设置;从 Dock 启动的应用是否因此连不上被墙的提供方,未核实。 +- 会话未指定 providerId、走 `/proxy/v1/messages`(按请求时的 active provider 转发)时,用户中途切换 active provider 的后果,未追踪。 +- 标题生成(非流式,15 秒超时,`max_tokens` 不转发)在推理模型上可能超时,未展开。 +- 所有提供方的错误码、HTTP 状态和真实上下文窗口都没有联网核实,文中已逐条标注。 From 0936fc4b7b1f957e710fbf9f76952d70b053ca74 Mon Sep 17 00:00:00 2001 From: Diao Shengjia <104132148+GoDiao@users.noreply.github.com> Date: Wed, 18 Nov 2026 10:24:58 +0800 Subject: [PATCH 3/4] fix(proxy): fix the basics of the OpenAI-format request path Part of #262. Each item below came with a test that failed before the change. Cache and request shape: - The proxy adds and signs the Claude Code billing line only for models whose name starts with `claude` (reusing attributionHeaderPolicy). The line changed on every request, so OpenAI and GLM could only reuse the cached tool definitions. Measured on OpenRouter, later turns now hit the cache for about 99% of the input. - Responses requests carry the CLI session id as `prompt_cache_key`; requests with tools send `parallel_tool_calls: true`; tool schemas drop the `$schema` URL and zod's safe-integer bounds. - Cache hits are also read from `prompt_cache_hit_tokens` and a top-level `cached_tokens`. Responses report the requested model name. Transport: - The proxy route turns off Bun's 60-second idle timeout per request. - A base URL that already ends in a version (`/v4`, `/v1beta/openai`) is used as the full prefix for requests, model lists and connection tests; others still get `/v1`. - The caller's abort signal reaches the upstream fetch, also before the upstream answers and for non-streaming requests. - With a manual HTTP proxy, the CLI env gets NO_PROXY for loopback, merged with the inherited value (an inherited `*` is kept as is). Scheduled tasks now get the network env too. - One stream supervisor times idle gaps (aiRequestTimeoutMs; only events sent to the CLI count, keep-alive comments become `ping`) and records how the stream ended. The CLI direct path gets the same limit through CLAUDE_ENABLE_STREAM_WATCHDOG and CLAUDE_STREAM_IDLE_TIMEOUT_MS. - Every upstream request is recorded as an `upstream_request` diagnostics event (provider, model, host, status, timings, request id, outcome); never the key or the body. diagnosticsService resolves its paths before awaiting, so a pending write cannot land in another config dir. - All three SSE readers share one spec framing function; a formatted JSON error body is surfaced instead of an empty reply. - OpenAI-format providers can carry extraHeaders and queryParams; configured headers go first, auth and Content-Type override them. They are rejected for anthropic-format providers. No desktop form yet. - The proxy answers count_tokens and other unknown paths with an Anthropic not_found_error. The server marks proxied providers with DREAMCODER_PROVIDER_PROXIED, and /context uses the local estimate for them instead of a Haiku request. Docs: CHANGELOG entries, status lines on the fixed items in docs/features/harness/proxy, measured cache results in the harness README. --- CHANGELOG.md | 10 + desktop/src/types/provider.ts | 6 + docs/features/harness/README.md | 5 +- docs/features/harness/proxy/request.md | 5 + docs/features/harness/proxy/response.md | 5 + docs/features/harness/proxy/transport.md | 8 + .../__tests__/conversation-service.test.ts | 39 ++- .../__tests__/cron-scheduler-launcher.test.ts | 28 ++ .../__tests__/diagnostics-service.test.ts | 20 ++ src/server/__tests__/network-settings.test.ts | 47 ++- .../__tests__/provider-runtime-env.test.ts | 20 ++ src/server/__tests__/providers.test.ts | 129 ++++++- .../__tests__/proxy-network-settings.test.ts | 114 ++++++- src/server/__tests__/proxy-streaming.test.ts | 113 +++++++ src/server/__tests__/proxy-transform.test.ts | 75 +++++ src/server/__tests__/upstream-client.test.ts | 315 +++++++++++++++++- src/server/index.ts | 2 +- src/server/proxy/handler.ts | 22 +- .../streaming/openaiChatStreamToAnthropic.ts | 97 +++--- .../openaiResponsesStreamToAnthropic.ts | 110 +++--- ...penaiResponsesStreamToAnthropicResponse.ts | 73 ++-- src/server/proxy/streaming/sse.ts | 82 +++++ .../proxy/transform/anthropicToOpenaiChat.ts | 4 +- .../transform/anthropicToOpenaiResponses.ts | 11 +- .../proxy/transform/openaiChatToAnthropic.ts | 9 +- .../transform/openaiResponsesToAnthropic.ts | 2 +- src/server/proxy/transform/toolSchema.ts | 22 ++ src/server/proxy/transform/types.ts | 5 + src/server/services/conversationService.ts | 4 +- src/server/services/cronScheduler.ts | 5 +- src/server/services/cuaDriverService.ts | 7 +- src/server/services/diagnosticsService.ts | 12 +- src/server/services/networkSettings.ts | 42 ++- src/server/services/providerRuntimeEnv.ts | 3 + src/server/services/providerService.ts | 16 + src/server/types/provider.ts | 8 + src/server/upstream/anthropicStream.ts | 84 +++++ src/server/upstream/baseUrl.ts | 11 + src/server/upstream/client.ts | 134 ++++++-- src/server/upstream/requestLog.ts | 56 ++++ src/utils/__tests__/analyzeContext.test.ts | 39 ++- .../providerManagedEnvCompat.test.ts | 4 + src/utils/analyzeContext.ts | 4 + src/utils/managedEnvConstants.ts | 3 + src/utils/providerProxy.ts | 7 + 45 files changed, 1581 insertions(+), 236 deletions(-) create mode 100644 src/server/proxy/streaming/sse.ts create mode 100644 src/server/proxy/transform/toolSchema.ts create mode 100644 src/server/upstream/anthropicStream.ts create mode 100644 src/server/upstream/requestLog.ts create mode 100644 src/utils/providerProxy.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 0f42154f..0e477b5f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,9 +25,19 @@ All notable changes to DreamCoder will be documented in this file. - The "open project" button in the session header is a split button: the icon opens the project in the editor you used last, the arrow lists the other editors and file managers. - **A message you send while the agent is working waits for the next turn.** It used to be slipped into the running turn. Queued messages are listed above the message box, where you can withdraw one or send the queue now, which stops the current turn and starts the next one; Stop does the same while messages are queued. Queued messages survive a model or permission change that restarts the agent at the end of the turn (#239). - The skill page and the Files tab read file previews through one shared reader, so both classify text, images, binary and oversized files the same way (#255). Thanks @iruzen-dono. +- **Providers in OpenAI format reuse their prompt cache.** Later turns of a session now hit the cache for about 99% of the input (measured on OpenRouter with GPT-4.1 mini and GLM-4.6), and cache hits that DeepSeek and Moonshot report are counted as cache reads (#262). +- Providers in OpenAI format can run several tool calls in one step and get tool definitions without schema fields they do not use, and replies show the model you chose instead of the dated version the provider reports (#262). +- Every request the app itself sends to a provider (through the local proxy, for session titles and for connection tests) is recorded in the diagnostics log with the provider, model, status, timings, the provider's request id and how it ended, including errors in the middle of a stream and clients that disconnect; never the key or the request body (#262). +- **A stalled reply ends after the AI request timeout.** When a provider stops sending anything for longer than the timeout in the network settings, the agent gives up on that reply and asks again without streaming, instead of waiting until you stop it. This now applies to every provider, whether it is reached directly or through the local proxy; keep-alive signals alone do not count as progress (#262). +- Providers in OpenAI format can carry extra request headers and query parameters, such as Azure's `api-version`. The settings form does not offer them yet; for now they are set by editing the provider in `providers.json`. Authentication and the content type still come from the provider settings and override a header of the same name (#262). ### Fixed +- A provider in OpenAI format whose base URL already ends in a version, such as `https://open.bigmodel.cn/api/paas/v4` or Gemini's `.../v1beta/openai`, works: requests, model lists and the connection test no longer add another `/v1`. Base URLs without a version still get `/v1` (#262). +- A streamed reply through the local proxy is no longer cut off when the provider pauses for more than 60 seconds, and stopping a reply or deleting a session now also stops the request to the provider before it starts answering (#262). +- With a manual HTTP proxy set in the network settings, the agent reaches the app's local proxy directly instead of sending those requests to the HTTP proxy (#262). +- Replies from some providers no longer come back empty; the provider's error message is shown instead (#262). +- `/context` in the terminal no longer sends a request to the model for each part of the context when the provider is reached through the local proxy; it uses the local estimate (#262). - The slash menu on the new task page lists the built-in commands such as `/design`; it used to list only skills on disk. - A deleted session no longer comes back as an empty session in the sidebar. It happened to sessions with a title you had set that were deleted while their agent was still running. - Exporting an artifact as a PNG image shows the whole page. On a page taller than the side panel, everything below the visible part used to repeat the visible part. The image now shows the page as it loads, without what you clicked or typed in the tab. diff --git a/desktop/src/types/provider.ts b/desktop/src/types/provider.ts index 2e4b40f7..caf625e1 100644 --- a/desktop/src/types/provider.ts +++ b/desktop/src/types/provider.ts @@ -30,6 +30,8 @@ export type SavedProvider = { models: ProviderModel[] fastModel?: string modelContextWindows?: ModelContextWindows + extraHeaders?: Record + queryParams?: Record notes?: string } @@ -44,6 +46,8 @@ export type CreateProviderInput = { models: ProviderModel[] fastModel?: string modelContextWindows?: ModelContextWindows + extraHeaders?: Record + queryParams?: Record notes?: string } @@ -57,6 +61,8 @@ export type UpdateProviderInput = { models?: ProviderModel[] fastModel?: string | null modelContextWindows?: ModelContextWindows | null + extraHeaders?: Record | null + queryParams?: Record | null notes?: string } diff --git a/docs/features/harness/README.md b/docs/features/harness/README.md index d9c5a11b..73a64039 100644 --- a/docs/features/harness/README.md +++ b/docs/features/harness/README.md @@ -55,11 +55,12 @@ DreamCoder 的 CLI 派生自 Claude Code 2.1.92(`src/constants/claudeCodeCompa ### 1. 提供方的前缀缓存失效 -- 代理给每个请求的 system 开头补一行计费标识(`src/server/proxy/handler.ts:64`,`src/server/proxy/claudeCodeAttribution.ts:29`),这一步不看模型名。 +- 代理给每个请求的 system 开头补一行计费标识(`src/server/proxy/handler.ts:64`,`src/server/proxy/claudeCodeAttribution.ts:29`),修复前这一步不看模型名。 - 发出前,这一行里的 `cch=00000` 被替换成整个请求体的哈希(`src/server/upstream/client.ts:211-224`,`src/utils/claudeCodeCch.ts:57-59`)。请求体每轮都不同,所以这一行每轮都变,位置在 system 的第 79–83 个字符。 - 除这一行外,DreamCoder 的前缀本来是稳定的:system 各段会话内缓存,日期和 git 状态只算一次,工具按名字排序。 - 代理还丢掉了 `cache_control`,也不发会话亲和信息。 -- 后果(推断,没有实测):固定部分约 3 万 token 加全部历史,每个请求都按全价计。详见 [request-cache.md](comparison/request-cache.md)。 +- 后果:固定部分约 3 万 token 加全部历史,每个请求都按全价计。详见 [request-cache.md](comparison/request-cache.md)。 +- 实测(#262,OpenRouter 测试 key):OpenAI 和 GLM 把工具定义排在 system 之前,带计费行时每轮只命中工具定义那一段,system 和历史全部未命中;去掉计费行后同一会话后续轮次命中约 99%。DeepSeek 经 DeepInfra 这条路上,这一行在到达模型前被去掉了,不受影响。已在 #262 修复:代理只对 Claude 模型加这一行。 ### 2. 代理翻译丢信息 diff --git a/docs/features/harness/proxy/request.md b/docs/features/harness/proxy/request.md index 553f4aad..23525553 100644 --- a/docs/features/harness/proxy/request.md +++ b/docs/features/harness/proxy/request.md @@ -10,6 +10,7 @@ ### P-REQ-01 代理给每个请求的 system 首行加计费行,`cch` 随整个请求体变化,提供方前缀缓存从第一行起失配 +- 状态:已在 #262 修复:代理只对模型名以 `claude` 开头的请求加计费行并签名,判断复用 `attributionHeaderPolicy`。实测(OpenRouter,`openai/gpt-4.1-mini`、`z-ai/glm-4.6`):带计费行时每轮只命中排在 system 之前的工具定义,去掉后同一会话后续轮次命中约 99%。 - 类型:问题 - 严重程度:高 - 现状(按执行顺序): @@ -84,6 +85,7 @@ ### P-REQ-06 OpenAI 格式的 baseUrl 被强制改成 `<去掉 /v1 的 base>/v1/...`,路径里版本段不是 `/v1` 的端点无法接入 +- 状态:已在 #262 修复,见 P-NET-06。 - 类型:问题 - 严重程度:中 - 现状:`normalizeUpstreamBaseUrl` 去掉结尾的 `/v1`(`src/server/upstream/baseUrl.ts:1-3`),然后固定拼 `/v1/chat/completions`、`/v1/responses`、`/v1/models`(`src/server/upstream/client.ts:136,212,220`)。测试也按这个行为写(`src/server/__tests__/upstream-client.test.ts:79-84`)。界面上 Base URL 的占位示例是 Anthropic 风格(`desktop/src/i18n/locales/en.ts:500`),没有说明 OpenAI 格式的写法。 @@ -134,6 +136,7 @@ ### P-REQ-10 没有任何缓存键或会话亲和信息,CLI 已经提供的会话 id 被丢弃 +- 状态:部分在 #262 修复:`openai_responses` 发 `prompt_cache_key`(取 `X-Claude-Code-Session-Id`)。`openai_chat` 是否发、`cache_control` 是否转发,归 #264 按模型处理。 - 类型:优化 - 严重程度:中 - 现状:CLI 给每个请求带 `X-Claude-Code-Session-Id` 头(`src/services/api/client.ts:155-158`)和 `metadata.user_id`(内含 `session_id`、`device_id`,`src/services/api/claude.ts:502-527,1764`),还在 system、工具和最后一条消息上标 `cache_control`。代理只读 body(`handler.ts:54-64`),类型里没有 `metadata`(`types.ts:161-181`),发往上游的头只有 `Content-Type` 和 `Authorization`(`client.ts:213,221`)。 @@ -158,6 +161,7 @@ ### P-REQ-12 不发送 `parallel_tool_calls` +- 状态:已在 #262 修复:两种格式在有工具时发 `parallel_tool_calls: true`。 - 类型:优化 - 严重程度:低 - 现状:chat 与 Responses 请求都没有 `parallel_tool_calls`(`types.ts:32-46,107-125`);CLI 侧也不使用 `disable_parallel_tool_use`(grep 无结果)。 @@ -168,6 +172,7 @@ ### P-REQ-13 工具 schema 原样转发,带 `$schema`、超大 `maximum` 等提供方用不上的关键字 +- 状态:已在 #262 修复:工具 schema 去掉字符串值的 `$schema` 和等于安全整数边界的 `maximum`/`minimum`,其他关键字不动。 - 类型:优化 - 严重程度:低 - 现状:内置工具的 schema 由 zod v4 `toJSONSchema` 生成(`src/utils/zodToJsonSchema.ts:5,17-23`),形状如 `{"$schema":"https://json-schema.org/draft/2020-12/schema", …, "additionalProperties":false}`,整数字段带 `"maximum":9007199254740991`,URL 字段带 `"format":"uri"`(本地用仓库 zod 打印确认)。代理把 `input_schema` 原样作为 `parameters`(`anthropicToOpenaiChat.ts:47-58`;`anthropicToOpenaiResponses.ts:35-45`)。MCP 工具的 schema 也原样转发。 diff --git a/docs/features/harness/proxy/response.md b/docs/features/harness/proxy/response.md index b4da211d..08153e6e 100644 --- a/docs/features/harness/proxy/response.md +++ b/docs/features/harness/proxy/response.md @@ -43,6 +43,7 @@ ### P-RES-03 上游流停滞时没有任何超时,回合一直挂着 +- 状态:已在 #262 修复:代理在转换后的流上计空闲时间,时长取「AI 请求超时」,只有发给 CLI 的非 `ping` 事件才重置计时;超时后发 SSE `error` 并取消上游。上游的 `:` 注释转成 `ping` 事件,但不算活动。更正:「以后开启 CLI 看门狗也不会误杀只发 keep-alive 的长推理」不成立,Anthropic SDK 收到 `ping` 直接跳过(`@anthropic-ai/sdk/core/streaming.js:96-98`),看门狗看不到它。 - 类型:问题 - 严重程度:中 - 现状: @@ -167,6 +168,7 @@ ### P-RES-11 缓存命中只读 `prompt_tokens_details.cached_tokens` +- 状态:已在 #262 修复:依次读 `prompt_tokens_details.cached_tokens`、`prompt_cache_hit_tokens`、`cached_tokens`。 - 类型:优化 - 严重程度:低 - 现状:`mapUsage` 只读 `prompt_tokens_details.cached_tokens`(openaiChatToAnthropic.ts:85);Responses 只读 `input_tokens_details.cached_tokens`(openaiResponsesToAnthropic.ts:38)。CLI 把 `cache_read_input_tokens` 计入上下文和费用(src/utils/tokens.ts:46-53),桌面端单列“缓存读/写”(desktop/src/components/chat/LocalSlashCommandPanel.tsx:291)。 @@ -187,6 +189,7 @@ ### P-RES-13 用户取消在非流式请求和流式响应头到达之前传不到上游 +- 状态:已在 #262 修复,见 P-NET-05。 - 类型:问题 - 严重程度:低 - 现状:`handleProxyRequest` 调 `sendToUpstream` 时不传 `req.signal`(src/server/proxy/handler.ts:64);`sendToUpstream` 只用超时信号(src/server/upstream/client.ts:70-75, 264-276)。流开始之后的取消可以传到上游(流转换器的 `cancel` 取消上游 body,openaiChatStreamToAnthropic.ts:143-146,有测试 src/server/__tests__/proxy-streaming.test.ts:613-637)。 @@ -197,6 +200,7 @@ ### P-RES-14 SSE 解析不完全按规范 +- 状态:已在 #262 修复:三处解析(两个流转换器和 Responses 的非流式回退)共用 `src/server/proxy/streaming/sse.ts` 的分帧;没有任何 SSE 事件的响应体整体按 JSON 解析取错误信息,两个流转换器都识别。 - 类型:优化 - 严重程度:低 - 现状: @@ -210,6 +214,7 @@ ### P-RES-15 响应里的模型名来源不一致 +- 状态:已在 #262 修复:流式和非流式响应的 `model` 都用请求的模型名。 - 类型:优化 - 严重程度:低 - 现状:chat 流用上游 chunk 的 `model` 覆盖(openaiChatStreamToAnthropic.ts:304),非流式用 `response.model`(openaiChatToAnthropic.ts:56;openaiResponsesToAnthropic.ts:28),Responses 流实际总用请求的模型名(见 P-RES-09 第 4 点)。这个名字写进转录的 `message.model`,桌面端按它分模型统计并查上下文窗口(src/server/services/sessionService.ts:897, 1000-1015)。 diff --git a/docs/features/harness/proxy/transport.md b/docs/features/harness/proxy/transport.md index ab94ac4c..99733036 100644 --- a/docs/features/harness/proxy/transport.md +++ b/docs/features/harness/proxy/transport.md @@ -13,6 +13,7 @@ ### P-NET-01 本地 Bun 服务的 60 秒空闲超时会切断走代理的请求,导致重试和重复计费 +- 状态:已在 #262 修复:代理处理函数对每个请求调用 `server.timeout(req, 0)`。更正:#262 实测 Bun 1.4.2 下,POST 请求在处理函数返回响应之前,即使沉默 70 秒也不会被 60 秒的 `idleTimeout` 切断(GET 会);会被切断的是流式响应发出后中途停顿的情况。所以第 2、6 步里「非流式请求也受 60 秒限制」不成立。另外 `idleTimeout` 的计时粒度约 4 秒。 - 类型:问题 - 严重程度:高 - 现状: @@ -78,6 +79,7 @@ ### P-NET-05 代理不随 CLI 中止上游请求:非流式请求和等待响应头期间的请求会跑完并计费 +- 状态:已在 #262 修复:`sendToUpstream` 接收调用方的取消信号,与超时信号合并;代理传入 `req.signal`。 - 类型:问题 - 严重程度:中 - 现状: @@ -91,6 +93,7 @@ ### P-NET-06 OpenAI 格式的 base URL 被强制改成 `.../v1/...`,版本号不是 v1 的提供方都会 404 +- 状态:已在 #262 修复:OpenAI 格式下,base URL 末段是版本号(`/v4`、`/v1beta` 等)或 `<版本>/openai` 时当完整前缀;否则仍补 `/v1`,已保存的配置行为不变。请求、拉取模型和测试连接共用这一个函数。表单占位示例未改。 - 类型:问题 - 严重程度:中 - 现状:`normalizeUpstreamBaseUrl` 只去掉末尾的 `/v1`(src/server/upstream/baseUrl.ts:1-3),然后固定拼上 `/v1/chat/completions` 或 `/v1/responses`(src/server/upstream/client.ts:211-222);拉取模型列表固定拼 `/v1/models`(client.ts:121, 136)。界面上 base URL 的占位符只举了 Anthropic 的例子(desktop/src/i18n/locales/en.ts:500)。 @@ -101,6 +104,7 @@ ### P-NET-07 手动代理模式下,CLI 访问本地代理的请求也被送进外部 HTTP 代理 +- 状态:已在 #262 修复:手动代理模式下 CLI 环境写入 `NO_PROXY`/`no_proxy`(与继承值合并,加上 `127.0.0.1,localhost,::1`;继承值为 `*` 时原样保留)。实测 Bun 的 fetch 在设置了 `NO_PROXY` 时,即使显式传了 `proxy` 选项也会直连,所以 `getProxyFetchOptions` 未改。系统代理模式未处理。 - 类型:问题 - 严重程度:中 - 现状: @@ -114,6 +118,7 @@ ### P-NET-08 直连路径没有流空闲超时,连接半开时会话无限等待;两条路径的超时语义不一致 +- 状态:已在 #262 修复:服务端给 CLI 设 `CLAUDE_ENABLE_STREAM_WATCHDOG=1`,`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 与 `API_TIMEOUT_MS` 相同(「AI 请求超时」),代理侧用同一个时长,两条路径都按「多久没有内容事件」计。`ping` 不重置 CLI 看门狗(SDK 跳过 ping),所以代理也不让 ping 重置自己的计时。两条路径超时后,CLI 都走同一个 catch,退回非流式把请求重发一次(`claude.ts:2519-2558`),除非设了 `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK`。 - 类型:问题 - 严重程度:中 - 现状:CLI 的流空闲看门狗默认关闭,要设 `CLAUDE_ENABLE_STREAM_WATCHDOG` 才开(src/services/api/claude.ts:1924-1928)。SDK 的 `timeout`(= `API_TIMEOUT_MS`)只管到响应头(推断:SDK 行为,claude.ts:1916-1923 的注释也这样说明)。代理路径的上游 fetch 在拿到响应头后清掉定时器(src/server/upstream/client.ts:268-276),此后唯一的空闲限制是 P-NET-01 的 Bun 60 秒。结果:代理路径 60 秒(对静默推理太短),直连路径没有上限。 @@ -148,6 +153,7 @@ ### P-NET-11 走代理的提供方不能配置额外请求头和 query 参数 +- 状态:部分在 #262 修复:提供方配置加了可选的 `extraHeaders` 和 `queryParams`,只对 `openai_chat`/`openai_responses` 生效,anthropic 格式保存时拒绝。请求头按固定顺序合并:先放配置的头,再放鉴权头和 `Content-Type`,后者覆盖前者(不区分大小写)。请求都会带上;测试连接和拉取模型只对已保存的提供方带上,未保存配置的这两个输入等做表单时补字段。桌面端表单和直连路径未做:直连路径的头要走 `ANTHROPIC_CUSTOM_HEADERS`,它不在受管 key(`providerRuntimeEnv.ts:19`)里,纳入后会清掉用户手写的同名设置;query 参数在直连路径上需要改 CLI。 - 类型:优化 - 严重程度:低 - 现状:代理发往上游的请求头只有 `Content-Type` 和 `Authorization: Bearer`(src/server/upstream/client.ts:213, 221),URL 不带 query 参数;OpenAI 格式下 `authStrategy` 不起作用。`SavedProvider` 没有请求头字段(src/server/types/provider.ts:46-59)。直连路径的 CLI 支持 `ANTHROPIC_CUSTOM_HEADERS`(src/services/api/client.ts:404-428),但提供方表单不会写入它。 @@ -158,6 +164,7 @@ ### P-NET-12 代理日志不足以诊断失败的上游请求,也没有逐请求的统计 +- 状态:已在 #262 修复:`sendToUpstream` 对每个上游请求记一条 `upstream_request` 诊断事件(提供方、模型、主机、格式、状态、响应头耗时、总耗时、上游 request id、结果),流式请求在流结束时记,结果分为正常结束、流中错误、未正常结束、空闲超时、客户端中止和客户端断开(调用方已中止后出现的错误按客户端断开记);不含 key 和正文。 - 类型:优化 - 严重程度:低 - 现状:代理只在上游返回非 2xx 或网络失败时打一行 `console.error('[Proxy] Upstream request failed:', result.error)`(src/server/proxy/handler.ts:67),被诊断服务捕获并脱敏写入 diagnostics 文件(src/server/services/diagnosticsService.ts:70-112)。这一行没有提供方 id、模型、上游主机和路径、apiFormat、耗时、上游 request id。流中途的上游错误(SSE `error`)、上游连接中断、Bun 空闲断开都不记录。成功请求不记录。token 用量只来自 CLI 写入转录的 usage,由会话服务汇总(src/server/services/sessionService.ts:868-890);代理侧没有按提供方和模型的请求数、失败数、延迟统计。key 不会出现在这行日志里(只含上游响应体前 500 字),诊断文件按键名再做一次脱敏(diagnosticsService.ts:42, 258-270)。 @@ -168,6 +175,7 @@ ### P-NET-13 代理不支持 count_tokens;终端里的 `/context` 会把每个统计项变成一次完整生成 +- 状态:已在 #262 修复,用的是第二种做法:代理对 `count_tokens` 和其他未知路径都返回 Anthropic 格式的 `not_found_error`。服务端给经代理的提供方设 `DREAMCODER_PROVIDER_PROXIED=1`,CLI 的 `/context` 计数在 API 计数返回 null 时直接用本地粗估,不再发 Haiku 请求。FileRead 的大小检查不变(仍是 404 → null → 按文件类型粗估)。没有采用本地估算,因为代理拿不到文件类型,会让 FileRead 对 JSON 文件少算约一半。 - 类型:问题 - 严重程度:低 - 现状: diff --git a/src/server/__tests__/conversation-service.test.ts b/src/server/__tests__/conversation-service.test.ts index 0d190060..5f7d12f7 100644 --- a/src/server/__tests__/conversation-service.test.ts +++ b/src/server/__tests__/conversation-service.test.ts @@ -9,6 +9,7 @@ import { FakeDesktop } from '../browserHost/testSupport.js' import { ConversationService } from '../services/conversationService.js' import { ProviderService } from '../services/providerService.js' import { resetTerminalShellEnvironmentCacheForTests } from '../../utils/terminalShellEnvironment.js' +import { PROVIDER_PROXIED_ENV_KEY } from '../../utils/providerProxy.js' describe('ConversationService', () => { let tmpDir: string @@ -234,12 +235,40 @@ describe('ConversationService', () => { 'utf-8', ) - const service = new ConversationService() as any - const env = (await service.buildChildEnv('/tmp')) as Record + const originalNoProxy = process.env.NO_PROXY + const originalLowerNoProxy = process.env.no_proxy + process.env.NO_PROXY = 'corp.internal' + delete process.env.no_proxy + try { + const service = new ConversationService() as any + const env = (await service.buildChildEnv('/tmp')) as Record + + expect(env.API_TIMEOUT_MS).toBe('180000') + expect(env.CLAUDE_ENABLE_STREAM_WATCHDOG).toBe('1') + expect(env.CLAUDE_STREAM_IDLE_TIMEOUT_MS).toBe('180000') + expect(env.HTTP_PROXY).toBe('http://127.0.0.1:7890') + expect(env.HTTPS_PROXY).toBe('http://127.0.0.1:7890') + expect(env.NO_PROXY).toBe('corp.internal,127.0.0.1,localhost,::1') + } finally { + if (originalNoProxy === undefined) delete process.env.NO_PROXY + else process.env.NO_PROXY = originalNoProxy + if (originalLowerNoProxy === undefined) delete process.env.no_proxy + else process.env.no_proxy = originalLowerNoProxy + } + }) + + test('buildChildEnv drops an inherited local proxy marker when the host chooses the provider', async () => { + const originalProxied = process.env[PROVIDER_PROXIED_ENV_KEY] + process.env[PROVIDER_PROXIED_ENV_KEY] = '1' + try { + const service = new ConversationService() as any + const env = (await service.buildChildEnv('/tmp', undefined, { providerId: null })) as Record - expect(env.API_TIMEOUT_MS).toBe('180000') - expect(env.HTTP_PROXY).toBe('http://127.0.0.1:7890') - expect(env.HTTPS_PROXY).toBe('http://127.0.0.1:7890') + expect(env[PROVIDER_PROXIED_ENV_KEY]).toBeUndefined() + } finally { + if (originalProxied === undefined) delete process.env[PROVIDER_PROXIED_ENV_KEY] + else process.env[PROVIDER_PROXIED_ENV_KEY] = originalProxied + } }) test('buildChildEnv gives a session of a connected desktop a browser endpoint and its own token', async () => { diff --git a/src/server/__tests__/cron-scheduler-launcher.test.ts b/src/server/__tests__/cron-scheduler-launcher.test.ts index 1b24fadc..11b224b8 100644 --- a/src/server/__tests__/cron-scheduler-launcher.test.ts +++ b/src/server/__tests__/cron-scheduler-launcher.test.ts @@ -11,6 +11,7 @@ import { import { CronService } from '../services/cronService.js' import { ProviderService } from '../services/providerService.js' import { resetTerminalShellEnvironmentCacheForTests } from '../../utils/terminalShellEnvironment.js' +import { resetSettingsCache } from '../../utils/settings/settingsCache.js' const originalConfigDir = process.env.DREAMCODER_CONFIG_DIR const originalPath = process.env.PATH @@ -289,6 +290,33 @@ describe('cron scheduler launcher resolution', () => { expect(run.error).toContain('No provider configured') }) + it('gives a scheduled task the network timeout and stream watchdog settings', async () => { + await fs.mkdir(path.join(tmpDir, 'config'), { recursive: true }) + await fs.writeFile( + path.join(tmpDir, 'config', 'settings.json'), + JSON.stringify({ network: { aiRequestTimeoutMs: 180_000 } }), + 'utf-8', + ) + resetSettingsCache() + const scheduler = new CronScheduler(new CronService()) as any + + try { + const env = await scheduler.buildTaskChildEnv(tmpDir, { id: 't', cron: '* * * * *', prompt: 'p', createdAt: 0 }) + + expect({ + API_TIMEOUT_MS: env.API_TIMEOUT_MS, + CLAUDE_ENABLE_STREAM_WATCHDOG: env.CLAUDE_ENABLE_STREAM_WATCHDOG, + CLAUDE_STREAM_IDLE_TIMEOUT_MS: env.CLAUDE_STREAM_IDLE_TIMEOUT_MS, + }).toEqual({ + API_TIMEOUT_MS: '180000', + CLAUDE_ENABLE_STREAM_WATCHDOG: '1', + CLAUDE_STREAM_IDLE_TIMEOUT_MS: '180000', + }) + } finally { + resetSettingsCache() + } + }) + it('starts a task in its own permission mode', () => { const scheduler = new CronScheduler(new CronService()) as any const task = { id: 't', cron: '* * * * *', prompt: 'p', createdAt: 0 } diff --git a/src/server/__tests__/diagnostics-service.test.ts b/src/server/__tests__/diagnostics-service.test.ts index 6b9881ea..94620813 100644 --- a/src/server/__tests__/diagnostics-service.test.ts +++ b/src/server/__tests__/diagnostics-service.test.ts @@ -89,6 +89,26 @@ describe('DiagnosticsService', () => { expect(runtime).not.toContain('sk-secret-token') }) + test('writes an event to the config dir that was current when it was recorded', async () => { + const laterDir = await fs.mkdtemp(path.join(os.tmpdir(), 'dreamcoder-diagnostics-later-')) + const service = new DiagnosticsService() + + try { + const pending = service.recordEvent({ type: 'upstream_request', severity: 'warn', summary: 'recorded first' }) + process.env.DREAMCODER_CONFIG_DIR = laterDir + await pending + + const firstLog = await fs.readFile(path.join(tmpDir, 'dreamcoder', 'diagnostics', 'diagnostics.jsonl'), 'utf-8') + const firstRuntimeLog = await fs.readFile(path.join(tmpDir, 'dreamcoder', 'diagnostics', 'runtime-errors.log'), 'utf-8') + expect(firstLog).toContain('recorded first') + expect(firstRuntimeLog).toContain('recorded first') + expect(await fs.readdir(laterDir)).toEqual([]) + } finally { + process.env.DREAMCODER_CONFIG_DIR = tmpDir + await fs.rm(laterDir, { recursive: true, force: true }) + } + }) + test('exports a single diagnostics tarball without provider secrets', async () => { const service = new DiagnosticsService() await fs.mkdir(path.join(tmpDir, 'dreamcoder'), { recursive: true }) diff --git a/src/server/__tests__/network-settings.test.ts b/src/server/__tests__/network-settings.test.ts index 10b8a21f..11da5e51 100644 --- a/src/server/__tests__/network-settings.test.ts +++ b/src/server/__tests__/network-settings.test.ts @@ -90,12 +90,57 @@ describe('network settings', () => { expect(settings.aiRequestTimeoutMs).toBe(180_000) expect(getManualNetworkProxyUrl(settings)).toBe('http://127.0.0.1:7890') - expect(buildNetworkEnvironment(settings)).toEqual({ + expect(buildNetworkEnvironment(settings, { NO_PROXY: 'corp.internal' })).toEqual({ API_TIMEOUT_MS: '180000', + CLAUDE_ENABLE_STREAM_WATCHDOG: '1', + CLAUDE_STREAM_IDLE_TIMEOUT_MS: '180000', HTTP_PROXY: 'http://127.0.0.1:7890', HTTPS_PROXY: 'http://127.0.0.1:7890', http_proxy: 'http://127.0.0.1:7890', https_proxy: 'http://127.0.0.1:7890', + NO_PROXY: 'corp.internal,127.0.0.1,localhost,::1', + no_proxy: 'corp.internal,127.0.0.1,localhost,::1', }) }) + + it('keeps an inherited NO_PROXY wildcard as it is', () => { + const settings = normalizeNetworkSettings({ + network: { proxy: { mode: 'manual', url: 'http://proxy.corp:8080' } }, + }) + + expect(buildNetworkEnvironment(settings, { NO_PROXY: '*' })).toMatchObject({ NO_PROXY: '*', no_proxy: '*' }) + }) + + it('lets a CLI with a manual proxy reach the local server directly', async () => { + let proxyHits = 0 + const externalProxy = Bun.serve({ + hostname: '127.0.0.1', + port: 0, + fetch() { + proxyHits += 1 + return new Response('through the external proxy', { status: 502 }) + }, + }) + const localServer = Bun.serve({ hostname: '127.0.0.1', port: 0, fetch: () => new Response('direct') }) + const settings = normalizeNetworkSettings({ + network: { proxy: { mode: 'manual', url: `http://127.0.0.1:${externalProxy.port}` } }, + }) + const { HTTP_PROXY: _a, HTTPS_PROXY: _b, http_proxy: _c, https_proxy: _d, NO_PROXY: _e, no_proxy: _f, ...baseEnv } = process.env + + try { + const child = Bun.spawn([ + process.execPath, + '-e', + `const res = await fetch('http://127.0.0.1:${localServer.port}/', { proxy: process.env.HTTPS_PROXY }); console.log(await res.text())`, + ], { env: { ...baseEnv, ...buildNetworkEnvironment(settings, baseEnv) }, stdout: 'pipe' }) + const output = (await new Response(child.stdout).text()).trim() + await child.exited + + expect(output).toBe('direct') + expect(proxyHits).toBe(0) + } finally { + externalProxy.stop(true) + localServer.stop(true) + } + }) }) diff --git a/src/server/__tests__/provider-runtime-env.test.ts b/src/server/__tests__/provider-runtime-env.test.ts index f82d61fa..0f68bbfa 100644 --- a/src/server/__tests__/provider-runtime-env.test.ts +++ b/src/server/__tests__/provider-runtime-env.test.ts @@ -4,6 +4,7 @@ import * as os from 'os' import * as path from 'path' import { + buildProviderManagedEnv, mergeActiveProviderManagedEnv, readActiveProviderManagedEnv, resolveProviderDefaultModel, @@ -137,4 +138,23 @@ describe('providerRuntimeEnv', () => { DISABLE_AUTOUPDATER: '1', }) }) + + test.each([ + ['openai_chat', '1'], + ['openai_responses', '1'], + ['anthropic', undefined], + ] as const)('marks providers reached through the local proxy (%s)', (apiFormat, expected) => { + const env = buildProviderManagedEnv({ + id: 'p1', + presetId: 'custom', + name: 'Provider', + apiKey: 'sk-test', + baseUrl: 'https://api.example.com', + apiFormat, + runtimeKind: 'anthropic_compatible', + models: [{ id: 'model-main' }], + }) + + expect(env.DREAMCODER_PROVIDER_PROXIED).toBe(expected) + }) }) diff --git a/src/server/__tests__/providers.test.ts b/src/server/__tests__/providers.test.ts index 44d3ca21..8dfba48b 100644 --- a/src/server/__tests__/providers.test.ts +++ b/src/server/__tests__/providers.test.ts @@ -5,6 +5,7 @@ import * as os from 'os' import { ProviderService } from '../services/providerService.js' import { handleProvidersApi } from '../api/providers.js' import { handleProxyRequest } from '../proxy/handler.js' +import { resolveUpstreamTarget } from '../upstream/client.js' import type { CreateProviderInput } from '../types/provider.js' let tmpDir: string @@ -773,8 +774,41 @@ describe('ProviderService', () => { }) }) + describe('extra headers and query parameters', () => { + test('saves them for OpenAI-format providers and hands them to the upstream client', async () => { + const svc = new ProviderService() + const provider = await svc.addProvider(sampleInput({ + apiFormat: 'openai_chat', + extraHeaders: { 'HTTP-Referer': 'https://dreamcoder.dev' }, + queryParams: { 'api-version': '2024-10-21' }, + })) + + expect(resolveUpstreamTarget(await svc.getProvider(provider.id))).toMatchObject({ + extraHeaders: { 'HTTP-Referer': 'https://dreamcoder.dev' }, + queryParams: { 'api-version': '2024-10-21' }, + }) + }) + + test('rejects them for Anthropic-format providers', async () => { + const svc = new ProviderService() + + await expect(svc.addProvider(sampleInput({ apiFormat: 'anthropic', queryParams: { a: 'b' } }))).rejects.toThrow() + const provider = await svc.addProvider(sampleInput({ apiFormat: 'openai_chat', extraHeaders: { 'X-Title': 'DreamCoder' } })) + await expect(svc.updateProvider(provider.id, { apiFormat: 'anthropic' })).rejects.toThrow() + }) + + test('clears them with null', async () => { + const svc = new ProviderService() + const provider = await svc.addProvider(sampleInput({ apiFormat: 'openai_chat', extraHeaders: { 'X-Title': 'DreamCoder' } })) + + const updated = await svc.updateProvider(provider.id, { extraHeaders: null, apiFormat: 'anthropic' }) + + expect(updated.extraHeaders).toBeUndefined() + }) + }) + describe('handleProxyRequest', () => { - test('injects Claude Code billing attribution with compat version and signed CCH', async () => { + test('injects Claude Code billing attribution with compat version and signed CCH for Claude models', async () => { const originalFetch = globalThis.fetch const originalEntrypoint = process.env.CLAUDE_CODE_ENTRYPOINT delete process.env.CLAUDE_CODE_ENTRYPOINT @@ -803,13 +837,13 @@ describe('ProviderService', () => { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ - model: 'gpt-4', + model: 'claude-sonnet-4-5', max_tokens: 64, messages: [{ role: 'user', content: 'hello from proxy' }], }), }) - const res = await handleProxyRequest(req, new URL(req.url)) + const res = await handleProxyRequest(req, new URL(req.url), { timeout: () => {} }) expect(res.status).toBe(200) const system = calls[0].body.messages as Array> @@ -823,6 +857,95 @@ describe('ProviderService', () => { else process.env.CLAUDE_CODE_ENTRYPOINT = originalEntrypoint } }) + + test('leaves the system prompt without billing attribution for non-Claude models', async () => { + const originalFetch = globalThis.fetch + const originalEntrypoint = process.env.CLAUDE_CODE_ENTRYPOINT + delete process.env.CLAUDE_CODE_ENTRYPOINT + const calls: Array<{ body: Record }> = [] + globalThis.fetch = mock(async (_url: string | URL | Request, init?: RequestInit) => { + calls.push({ body: JSON.parse(String(init?.body)) as Record }) + return new Response(JSON.stringify({ + id: 'chatcmpl-1', + object: 'chat.completion', + created: 0, + model: 'gpt-4', + choices: [{ index: 0, message: { role: 'assistant', content: 'ok' }, finish_reason: 'stop' }], + usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 }, + }), { + status: 200, + headers: { 'Content-Type': 'application/json' }, + }) + }) as typeof fetch + + try { + const svc = new ProviderService() + const provider = await svc.addProvider(sampleInput({ apiFormat: 'openai_chat' })) + await svc.activateProvider(provider.id) + + const req = new Request('http://localhost:3456/proxy/v1/messages', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ + model: 'gpt-4', + max_tokens: 64, + messages: [{ role: 'user', content: 'hello from proxy' }], + }), + }) + + const res = await handleProxyRequest(req, new URL(req.url), { timeout: () => {} }) + expect(res.status).toBe(200) + + expect(calls[0].body.messages).toEqual([{ role: 'user', content: 'hello from proxy' }]) + } finally { + globalThis.fetch = originalFetch + if (originalEntrypoint === undefined) delete process.env.CLAUDE_CODE_ENTRYPOINT + else process.env.CLAUDE_CODE_ENTRYPOINT = originalEntrypoint + } + }) + + test.each([ + ['openai_responses', 'session-abc'], + ['openai_chat', undefined], + ] as const)('sends the CLI session id as prompt_cache_key for %s: %p', async (apiFormat, expected) => { + const originalFetch = globalThis.fetch + const bodies: Array> = [] + globalThis.fetch = mock(async (_url: string | URL | Request, init?: RequestInit) => { + bodies.push(JSON.parse(String(init?.body)) as Record) + return Response.json(apiFormat === 'openai_chat' + ? { id: 'c', object: 'chat.completion', created: 0, model: 'gpt-4', choices: [{ index: 0, message: { role: 'assistant', content: 'ok' }, finish_reason: 'stop' }] } + : { id: 'r', object: 'response', model: 'gpt-4', status: 'completed', output: [] }) + }) as typeof fetch + + try { + const provider = await new ProviderService().addProvider(sampleInput({ apiFormat })) + const req = new Request(`http://localhost:3456/proxy/providers/${provider.id}/v1/messages`, { + method: 'POST', + headers: { 'Content-Type': 'application/json', 'X-Claude-Code-Session-Id': 'session-abc' }, + body: JSON.stringify({ model: 'gpt-4', max_tokens: 64, messages: [{ role: 'user', content: 'hi' }] }), + }) + + const res = await handleProxyRequest(req, new URL(req.url), { timeout: () => {} }) + + expect(res.status).toBe(200) + expect(bodies[0]!.prompt_cache_key).toBe(expected) + } finally { + globalThis.fetch = originalFetch + } + }) + + test.each([ + '/proxy/v1/messages/count_tokens', + '/proxy/providers/p1/v1/messages/count_tokens', + '/proxy/v1/models', + ])('answers %s with an Anthropic not_found_error', async (pathname) => { + const req = new Request(`http://localhost:3456${pathname}`, { method: 'POST', body: '{}' }) + + const res = await handleProxyRequest(req, new URL(req.url), { timeout: () => {} }) + + expect(res.status).toBe(404) + expect(await res.json()).toMatchObject({ type: 'error', error: { type: 'not_found_error' } }) + }) }) describe('discoverModels', () => { diff --git a/src/server/__tests__/proxy-network-settings.test.ts b/src/server/__tests__/proxy-network-settings.test.ts index 1ba01130..75c0d40e 100644 --- a/src/server/__tests__/proxy-network-settings.test.ts +++ b/src/server/__tests__/proxy-network-settings.test.ts @@ -91,7 +91,7 @@ describe('proxy network settings', () => { body: JSON.stringify(body), }, ) - const res = await handleProxyRequest(req, new URL(req.url)) + const res = await handleProxyRequest(req, new URL(req.url), { timeout: () => {} }) expect(res.status).toBe(200) expect(timeoutCalls).toEqual([45_000]) @@ -160,7 +160,7 @@ describe('proxy network settings', () => { body: JSON.stringify(body), }, ) - const res = await handleProxyRequest(req, new URL(req.url)) + const res = await handleProxyRequest(req, new URL(req.url), { timeout: () => {} }) expect(res.status).toBe(200) expect(timeoutCalls).toEqual([45_000]) @@ -170,7 +170,7 @@ describe('proxy network settings', () => { } }) - test('uses configured AI request timeout only while opening streaming upstream requests', async () => { + test('uses the configured AI request timeout for opening a stream and for idle gaps, and clears it when the stream ends', async () => { await fs.writeFile( path.join(tmpDir, 'settings.json'), JSON.stringify({ @@ -242,12 +242,13 @@ describe('proxy network settings', () => { body: JSON.stringify(body), }, ) - const res = await handleProxyRequest(req, new URL(req.url)) + const res = await handleProxyRequest(req, new URL(req.url), { timeout: () => {} }) await res.text() expect(res.status).toBe(200) expect(timeoutCalls).toEqual([]) - expect(timers).toEqual([{ ms: 180_000, cleared: true }]) + expect(timers.length).toBeGreaterThanOrEqual(2) + expect(timers.every((timer) => timer.ms === 180_000 && timer.cleared)).toBe(true) } finally { globalThis.clearTimeout = originalClearTimeout globalThis.setTimeout = originalSetTimeout @@ -255,4 +256,107 @@ describe('proxy network settings', () => { globalThis.fetch = originalFetch } }) + + test('keeps a proxied stream open while the upstream pauses longer than the server idle timeout', async () => { + const encoder = new TextEncoder() + const chunk = (delta: Record, finishReason: string | null = null) => + encoder.encode(`data: ${JSON.stringify({ + id: 'chatcmpl-slow', + object: 'chat.completion.chunk', + created: 0, + model: 'model-main', + choices: [{ index: 0, delta, finish_reason: finishReason }], + })}\n\n`) + const upstream = Bun.serve({ + hostname: '127.0.0.1', + port: 0, + fetch: () => new Response(new ReadableStream({ + async start(controller) { + controller.enqueue(chunk({ role: 'assistant', content: 'before ' })) + await Bun.sleep(5_000) + controller.enqueue(chunk({ content: 'after' }, 'stop')) + controller.enqueue(encoder.encode('data: [DONE]\n\n')) + controller.close() + }, + }), { headers: { 'Content-Type': 'text/event-stream' } }), + }) + const provider = await new ProviderService().addProvider({ + presetId: 'custom', + name: 'Slow Upstream', + baseUrl: `http://127.0.0.1:${upstream.port}`, + apiKey: 'sk-test', + apiFormat: 'openai_chat', + models: [{ id: 'model-main' }], + }) + const proxy = Bun.serve({ + hostname: '127.0.0.1', + port: 0, + idleTimeout: 1, + fetch: (req, server) => handleProxyRequest(req, new URL(req.url), server), + }) + + try { + const res = await fetch(`http://127.0.0.1:${proxy.port}/proxy/providers/${provider.id}/v1/messages`, { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ model: 'model-main', max_tokens: 64, stream: true, messages: [{ role: 'user', content: 'hello' }] }), + }) + const text = await res.text() + + expect(text).toContain('"text":"after"') + expect(text).toContain('message_stop') + } finally { + proxy.stop(true) + upstream.stop(true) + } + }, 15_000) + + test.each([false, true])('aborts the upstream request when the client disconnects before upstream headers (stream: %p)', async (stream) => { + const upstreamReceived = Promise.withResolvers() + const upstreamAborted = Promise.withResolvers() + const upstream = Bun.serve({ + hostname: '127.0.0.1', + port: 0, + fetch(req) { + req.signal.addEventListener('abort', () => upstreamAborted.resolve('aborted')) + upstreamReceived.resolve() + return new Promise(() => {}) + }, + }) + const provider = await new ProviderService().addProvider({ + presetId: 'custom', + name: 'Hanging Upstream', + baseUrl: `http://127.0.0.1:${upstream.port}`, + apiKey: 'sk-test', + apiFormat: 'openai_chat', + models: [{ id: 'model-main' }], + }) + const proxy = Bun.serve({ + hostname: '127.0.0.1', + port: 0, + fetch: (req, server) => handleProxyRequest(req, new URL(req.url), server), + }) + const client = new AbortController() + + try { + const pending = fetch(`http://127.0.0.1:${proxy.port}/proxy/providers/${provider.id}/v1/messages`, { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ model: 'model-main', max_tokens: 64, stream, messages: [{ role: 'user', content: 'hello' }] }), + signal: client.signal, + }).catch(() => null) + await upstreamReceived.promise + client.abort() + await pending + + const outcome = await Promise.race([ + upstreamAborted.promise, + Bun.sleep(3_000).then(() => 'still running'), + ]) + expect(outcome).toBe('aborted') + } finally { + proxy.stop(true) + upstream.stop(true) + } + }, 10_000) }) diff --git a/src/server/__tests__/proxy-streaming.test.ts b/src/server/__tests__/proxy-streaming.test.ts index cf74b0a4..6ebcc156 100644 --- a/src/server/__tests__/proxy-streaming.test.ts +++ b/src/server/__tests__/proxy-streaming.test.ts @@ -5,6 +5,7 @@ import { OpenAIResponsesStreamError, openaiResponsesStreamToAnthropicResponse, } from '../proxy/streaming/openaiResponsesStreamToAnthropicResponse.js' +import { SseDecoder } from '../proxy/streaming/sse.js' function makeStream(chunks: string[]): ReadableStream { const encoder = new TextEncoder() @@ -610,6 +611,118 @@ describe('openaiResponsesStreamToAnthropicResponse upstream errors', () => { }) }) +describe('SSE framing', () => { + const chatChunk = (delta: Record, finishReason: string | null = null) => JSON.stringify({ + id: 'c1', object: 'chat.completion.chunk', created: 0, model: 'gpt-4', choices: [{ index: 0, delta, finish_reason: finishReason }], + }) + + test('a CRLF split across chunks ends one line, not two', () => { + const decoder = new SseDecoder() + const encoder = new TextEncoder() + const messages = [ + ...decoder.push(encoder.encode('data: a\r')), + ...decoder.push(encoder.encode('\ndata: b\r')), + ...decoder.push(encoder.encode('\n\r\n')), + ...decoder.flush(), + ] + + expect(messages).toEqual([{ type: 'event', event: '', data: 'a\nb' }]) + }) + + test('the last event is dispatched at the end of the stream without a closing blank line', () => { + const decoder = new SseDecoder() + + expect(decoder.push(new TextEncoder().encode('event: x\ndata: y\n'))).toEqual([]) + expect(decoder.flush()).toEqual([{ type: 'event', event: 'x', data: 'y' }]) + }) + + test('chat stream accepts field lines without a space after the colon and CRLF line endings', async () => { + const events = await collectSse(openaiChatStreamToAnthropic(makeStream([ + `data:${chatChunk({ role: 'assistant', content: 'Hi' })}\r\n\r\n`, + `data:${chatChunk({}, 'stop')}\r\n\r\n`, + 'data:[DONE]\r\n\r\n', + ]), 'gpt-4')) + + expect(events.map(e => e.event)).toEqual([ + 'message_start', 'content_block_start', 'content_block_delta', 'content_block_stop', 'message_delta', 'message_stop', + ]) + }) + + test('chat stream joins an event split over several data lines', async () => { + const [head, tail] = [chatChunk({ role: 'assistant', content: 'Hi' }).slice(0, 20), chatChunk({ role: 'assistant', content: 'Hi' }).slice(20)] + const events = await collectSse(openaiChatStreamToAnthropic(makeStream([ + `data: ${head}\ndata: ${tail}\n\n`, + `data: ${chatChunk({}, 'stop')}\n\n`, + 'data: [DONE]\n\n', + ]), 'gpt-4')) + + expect(events.find(e => e.event === 'content_block_delta')?.data.delta).toEqual({ type: 'text_delta', text: 'Hi' }) + }) + + test.each([ + ['openaiChatStreamToAnthropic', openaiChatStreamToAnthropic], + ['openaiResponsesStreamToAnthropic', openaiResponsesStreamToAnthropic], + ] as const)('%s surfaces a formatted JSON error body sent with status 200', async (_name, convert) => { + const body = JSON.stringify({ error: { message: 'invalid model', code: 'model_not_found' } }, null, 2) + const events = await collectSse(convert(makeStream([body]), 'gpt-4')) + + expect(events.map(e => e.event)).toEqual(['error']) + expect((events[0]!.data as { error: { message: string } }).error.message).toBe('invalid model') + }) + + test('responses stream accepts event and data lines without a space after the colon', async () => { + const events = await collectSse(openaiResponsesStreamToAnthropic(makeStream([ + 'event:response.content_part.added\ndata:{"output_index":0,"content_index":0,"part":{"type":"output_text","text":""}}\n\n', + 'event:response.output_text.delta\ndata:{"output_index":0,"content_index":0,"delta":"Hello"}\n\n', + 'event:response.completed\ndata:{"response":{"status":"completed","usage":{"input_tokens":1,"output_tokens":1}}}\n\n', + ]), 'gpt-4o')) + + expect(events.find(e => e.event === 'content_block_delta')?.data.delta).toEqual({ type: 'text_delta', text: 'Hello' }) + expect(events.at(-1)?.event).toBe('message_stop') + }) + + test('responses fallback reader accepts data lines without a space after the colon', async () => { + const response = { + id: 'resp_1', model: 'm', status: 'completed', + output: [{ type: 'message', role: 'assistant', content: [{ type: 'output_text', text: 'ok' }] }], + } + const result = await openaiResponsesStreamToAnthropicResponse( + makeStream([`event:response.completed\ndata:${JSON.stringify({ type: 'response.completed', response })}\n\n`]), + 'm', + ) + + expect(result.content).toEqual([{ type: 'text', text: 'ok' }]) + }) +}) + +describe('response model name', () => { + test('chat stream reports the requested model, not the snapshot the upstream returns', async () => { + const events = await collectSse(openaiChatStreamToAnthropic(makeStream([ + 'data: {"id":"c1","object":"chat.completion.chunk","created":0,"model":"gpt-4.1-2025-04-14","choices":[{"index":0,"delta":{"role":"assistant","content":"Hi"},"finish_reason":"stop"}]}\n\n', + 'data: [DONE]\n\n', + ]), 'gpt-4.1')) + + expect((events.find(e => e.event === 'message_start')!.data.message as { model: string }).model).toBe('gpt-4.1') + }) + + test('responses stream reports the requested model, not the snapshot the upstream returns', async () => { + const events = await collectSse(openaiResponsesStreamToAnthropic(makeStream([ + 'event: response.created\ndata: {"id":"r1","model":"gpt-4.1-2025-04-14","status":"in_progress"}\n\n', + 'event: response.completed\ndata: {"response":{"status":"completed"}}\n\n', + ]), 'gpt-4.1')) + + expect((events.find(e => e.event === 'message_start')!.data.message as { model: string }).model).toBe('gpt-4.1') + }) + + test('responses fallback reader reports the requested model', async () => { + const result = await openaiResponsesStreamToAnthropicResponse(makeStream([ + `event: response.completed\ndata: ${JSON.stringify({ response: { id: 'r1', model: 'gpt-4.1-2025-04-14', status: 'completed', output: [] } })}\n\n`, + ]), 'gpt-4.1') + + expect(result.model).toBe('gpt-4.1') + }) +}) + describe('stream cancellation', () => { test.each([ ['openaiChatStreamToAnthropic', openaiChatStreamToAnthropic, 'data: {"id":"c","object":"chat.completion.chunk","created":0,"model":"m","choices":[{"index":0,"delta":{"content":"x"},"finish_reason":null}]}\n\n'], diff --git a/src/server/__tests__/proxy-transform.test.ts b/src/server/__tests__/proxy-transform.test.ts index 41ab1350..9ab5bfcf 100644 --- a/src/server/__tests__/proxy-transform.test.ts +++ b/src/server/__tests__/proxy-transform.test.ts @@ -402,6 +402,19 @@ describe('openaiChatToAnthropic', () => { const result = openaiChatToAnthropic(res, 'gpt-4') expect(result.usage).toEqual({ input_tokens: 20, output_tokens: 50, cache_read_input_tokens: 80 }) }) + + test.each([ + ['DeepSeek prompt_cache_hit_tokens', { prompt_cache_hit_tokens: 80 }], + ['Moonshot top-level cached_tokens', { cached_tokens: 80 }], + ])('cached tokens mapping from %s', (_name, cacheFields) => { + const res: OpenAIChatResponse = { + id: 'x', object: 'chat.completion', created: 0, model: 'gpt-4', + choices: [{ index: 0, message: { role: 'assistant', content: 'hi' }, finish_reason: 'stop' }], + usage: { prompt_tokens: 100, completion_tokens: 50, total_tokens: 150, ...cacheFields }, + } + const result = openaiChatToAnthropic(res, 'gpt-4') + expect(result.usage).toEqual({ input_tokens: 20, output_tokens: 50, cache_read_input_tokens: 80 }) + }) }) describe('anthropicToOpenaiResponses', () => { @@ -785,3 +798,65 @@ describe('openaiResponsesToAnthropic', () => { expect(result.content).toEqual([{ type: 'text', text: '' }]) }) }) + +describe('response model name', () => { + test('chat responses report the requested model, not the snapshot the upstream returns', () => { + const res: OpenAIChatResponse = { + id: 'x', object: 'chat.completion', created: 0, model: 'gpt-4.1-2025-04-14', + choices: [{ index: 0, message: { role: 'assistant', content: 'hi' }, finish_reason: 'stop' }], + } + expect(openaiChatToAnthropic(res, 'gpt-4.1').model).toBe('gpt-4.1') + expect(openaiChatToAnthropic({ ...res, choices: [] }, 'gpt-4.1').model).toBe('gpt-4.1') + }) + + test('Responses API results report the requested model, not the snapshot the upstream returns', () => { + const res: OpenAIResponsesResponse = { + id: 'r', object: 'response', created_at: 0, model: 'gpt-4.1-2025-04-14', status: 'completed', output: [], + } + expect(openaiResponsesToAnthropic(res, 'gpt-4.1').model).toBe('gpt-4.1') + }) +}) + +describe('tool request options', () => { + const tool = { name: 'Read', description: 'Read a file', input_schema: { type: 'object', properties: { path: { type: 'string' } } } } + const base: AnthropicRequest = { model: 'gpt-4', max_tokens: 100, messages: [{ role: 'user', content: 'Hi' }] } + + test.each([ + ['anthropicToOpenaiChat', (req: AnthropicRequest) => anthropicToOpenaiChat(req) as { parallel_tool_calls?: boolean }], + ['anthropicToOpenaiResponses', (req: AnthropicRequest) => anthropicToOpenaiResponses(req) as { parallel_tool_calls?: boolean }], + ] as const)('%s allows parallel tool calls only when tools are sent', (_name, convert) => { + expect(convert({ ...base, tools: [tool] }).parallel_tool_calls).toBe(true) + expect(convert(base).parallel_tool_calls).toBeUndefined() + }) + test.each([ + ['anthropicToOpenaiChat', (req: AnthropicRequest) => anthropicToOpenaiChat(req).tools![0]!.function.parameters], + ['anthropicToOpenaiResponses', (req: AnthropicRequest) => anthropicToOpenaiResponses(req).tools![0]!.parameters], + ] as const)('%s drops the schema URL and the safe-integer bounds zod adds', (_name, parametersOf) => { + const inputSchema = { + $schema: 'https://json-schema.org/draft/2020-12/schema', + type: 'object', + properties: { + limit: { type: 'integer', minimum: -9007199254740991, maximum: 9007199254740991 }, + offset: { type: 'integer', minimum: 0, maximum: 9007199254740991 }, + items: { type: 'array', items: { type: 'object', properties: { n: { type: 'integer', exclusiveMinimum: 0, maximum: 9007199254740991 } } } }, + url: { type: 'string', format: 'uri' }, + $schema: { type: 'string', description: 'a parameter that happens to be named $schema' }, + }, + required: ['limit'], + additionalProperties: false, + } + + expect(parametersOf({ ...base, tools: [{ name: 'T', input_schema: inputSchema }] })).toEqual({ + type: 'object', + properties: { + limit: { type: 'integer' }, + offset: { type: 'integer', minimum: 0 }, + items: { type: 'array', items: { type: 'object', properties: { n: { type: 'integer', exclusiveMinimum: 0 } } } }, + url: { type: 'string', format: 'uri' }, + $schema: { type: 'string', description: 'a parameter that happens to be named $schema' }, + }, + required: ['limit'], + additionalProperties: false, + }) + }) +}) diff --git a/src/server/__tests__/upstream-client.test.ts b/src/server/__tests__/upstream-client.test.ts index 805f553c..b8024e46 100644 --- a/src/server/__tests__/upstream-client.test.ts +++ b/src/server/__tests__/upstream-client.test.ts @@ -1,9 +1,10 @@ -import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test' +import { afterEach, beforeEach, describe, expect, mock, spyOn, test } from 'bun:test' import * as fs from 'fs/promises' import * as os from 'os' import * as path from 'path' +import { diagnosticsService, type DiagnosticEventInput } from '../services/diagnosticsService.js' import { normalizeUpstreamBaseUrl } from '../upstream/baseUrl.js' -import { resolveUpstreamTarget, sendToUpstream, type UpstreamTarget } from '../upstream/client.js' +import { fetchUpstreamModels, resolveUpstreamTarget, sendToUpstream, type UpstreamTarget } from '../upstream/client.js' import type { AnthropicRequest } from '../proxy/transform/types.js' import type { SavedProvider } from '../types/provider.js' @@ -105,6 +106,51 @@ describe('upstream client', () => { expect(result.ok && 'message' in result && result.message.content[0]).toMatchObject({ type: 'text', text: 'ok' }) }) + test.each([ + ['openai_chat', 'https://open.bigmodel.cn/api/paas/v4', 'https://open.bigmodel.cn/api/paas/v4/chat/completions'], + ['openai_chat', 'https://ark.cn-beijing.volces.com/api/v3/', 'https://ark.cn-beijing.volces.com/api/v3/chat/completions'], + ['openai_chat', 'https://generativelanguage.googleapis.com/v1beta/openai', 'https://generativelanguage.googleapis.com/v1beta/openai/chat/completions'], + ['openai_responses', 'https://api.openai.com/v1', 'https://api.openai.com/v1/responses'], + ['openai_responses', 'https://api.openai.com', 'https://api.openai.com/v1/responses'], + ['openai_chat', 'https://relay.example.com/openai-compatible', 'https://relay.example.com/openai-compatible/v1/chat/completions'], + ] as const)('%s base URL %s is used as %s', async (apiFormat, baseUrl, expected) => { + mockFetch(() => Response.json(apiFormat === 'openai_chat' ? openaiChatMessage : { + id: 'resp_1', + object: 'response', + model: 'model-main', + status: 'completed', + output: [], + })) + + await sendToUpstream(target({ apiFormat, baseUrl }), request) + + expect(calls[0].url).toBe(expected) + }) + + test('lists OpenAI-format models under a base URL that already ends in a version', async () => { + let requestPath = '' + const server = Bun.serve({ + hostname: '127.0.0.1', + port: 0, + fetch(req) { + requestPath = new URL(req.url).pathname + return Response.json({ data: [{ id: 'glm-4.6' }] }) + }, + }) + + try { + const result = await fetchUpstreamModels(target({ + apiFormat: 'openai_chat', + baseUrl: `http://127.0.0.1:${server.port}/api/paas/v4`, + })) + + expect(requestPath).toBe('/api/paas/v4/models') + expect(result.ok && result.models).toEqual([{ id: 'glm-4.6' }]) + } finally { + server.stop(true) + } + }) + test.each([ ['api_key', { 'x-api-key': 'sk-test' }, ['authorization']], ['auth_token', { Authorization: 'Bearer sk-test' }, ['x-api-key']], @@ -200,10 +246,275 @@ describe('upstream client', () => { } expect(resolveUpstreamTarget(provider)).toEqual({ + providerId: 'p1', baseUrl: 'http://localhost:1234', apiKey: 'lmstudio', apiFormat: 'anthropic', authStrategy: 'auth_token_empty_api_key', }) }) + + describe('extra headers and query parameters', () => { + test('adds configured headers first and lets auth and content type from the provider settings win', async () => { + mockFetch(() => Response.json(openaiChatMessage)) + + await sendToUpstream(target({ + apiFormat: 'openai_chat', + baseUrl: 'https://example.openai.azure.com/openai/v1', + extraHeaders: { 'HTTP-Referer': 'https://dreamcoder.dev', authorization: 'Bearer from-config', 'content-type': 'text/plain' }, + queryParams: { 'api-version': '2024-10-21' }, + }), request) + + expect(calls[0].url).toBe('https://example.openai.azure.com/openai/v1/chat/completions?api-version=2024-10-21') + expect(calls[0].headers).toEqual({ + 'HTTP-Referer': 'https://dreamcoder.dev', + 'Content-Type': 'application/json', + Authorization: 'Bearer sk-test', + }) + }) + + test('lists models with the configured headers and query parameters', async () => { + let seen = { search: '', referer: '' } + const server = Bun.serve({ + hostname: '127.0.0.1', + port: 0, + fetch(req) { + seen = { search: new URL(req.url).search, referer: req.headers.get('http-referer') ?? '' } + return Response.json({ data: [{ id: 'm' }] }) + }, + }) + + try { + await fetchUpstreamModels(target({ + apiFormat: 'openai_chat', + baseUrl: `http://127.0.0.1:${server.port}/v1`, + extraHeaders: { 'HTTP-Referer': 'https://dreamcoder.dev' }, + queryParams: { 'api-version': '2024-10-21' }, + })) + + expect(seen).toEqual({ search: '?api-version=2024-10-21', referer: 'https://dreamcoder.dev' }) + } finally { + server.stop(true) + } + }) + + test('reports an invalid configured header instead of throwing', async () => { + const server = Bun.serve({ hostname: '127.0.0.1', port: 0, fetch: () => Response.json(openaiChatMessage) }) + + try { + const result = await sendToUpstream(target({ + apiFormat: 'openai_chat', + baseUrl: `http://127.0.0.1:${server.port}`, + extraHeaders: { 'Bad Header': 'x' }, + }), request) + + expect(result.ok).toBe(false) + expect(result.ok === false && result.error).toContain('Bad Header') + } finally { + server.stop(true) + } + }) + }) + + describe('stream idle timeout', () => { + const encoder = new TextEncoder() + + async function readWithGuard(stream: ReadableStream): Promise { + return Promise.race([ + new Response(stream).text(), + Bun.sleep(3_000).then(() => 'still waiting'), + ]) + } + + function hangingUpstream(start: (controller: ReadableStreamDefaultController) => void, onCancel: () => void) { + return new Response(new ReadableStream({ start, cancel: onCancel }), { + headers: { 'Content-Type': 'text/event-stream' }, + }) + } + + test('ends a stream with an error and cancels the upstream when no event reaches the client in time', async () => { + let upstreamCancelled = false + mockFetch(() => hangingUpstream((controller) => { + controller.enqueue(encoder.encode(`data: ${JSON.stringify({ id: 'c1', object: 'chat.completion.chunk', created: 0, model: 'm', choices: [{ index: 0, delta: { role: 'assistant', content: 'Hi' }, finish_reason: null }] })}\n\n`)) + }, () => { upstreamCancelled = true })) + + const result = await sendToUpstream(target({ apiFormat: 'openai_chat' }), { ...request, stream: true }, { timeoutMs: 300 }) + const text = await readWithGuard((result as { stream: ReadableStream }).stream) + + expect(text).toContain('"text":"Hi"') + expect(text).toMatch(/event: error\ndata: .*No response from the provider/) + expect(upstreamCancelled).toBe(true) + }) + + test('keep-alive comments become ping events but do not count as activity', async () => { + let timer: ReturnType | undefined + mockFetch(() => hangingUpstream((controller) => { + timer = setInterval(() => controller.enqueue(encoder.encode(': OPENROUTER PROCESSING\n\n')), 50) + }, () => clearInterval(timer))) + + try { + const result = await sendToUpstream(target({ apiFormat: 'openai_chat' }), { ...request, stream: true }, { timeoutMs: 300 }) + const text = await readWithGuard((result as { stream: ReadableStream }).stream) + + expect(text).toContain('event: ping\ndata: {"type":"ping"}') + expect(text).toContain('event: error') + } finally { + clearInterval(timer) + } + }) + + test('upstream events that produce nothing for the client do not count as activity', async () => { + let timer: ReturnType | undefined + mockFetch(() => hangingUpstream((controller) => { + controller.enqueue(encoder.encode('event: response.created\ndata: {"type":"response.created","response":{"id":"r1"}}\n\n')) + timer = setInterval(() => controller.enqueue(encoder.encode('event: response.in_progress\ndata: {"type":"response.in_progress"}\n\n')), 50) + }, () => clearInterval(timer))) + + try { + const result = await sendToUpstream(target({ apiFormat: 'openai_responses' }), { ...request, stream: true }, { timeoutMs: 300 }) + const text = await readWithGuard((result as { stream: ReadableStream }).stream) + + expect(text).toContain('event: message_start') + expect(text).toContain('event: error') + } finally { + clearInterval(timer) + } + }) + }) + + describe('diagnostics', () => { + let events: DiagnosticEventInput[] + let recordSpy: ReturnType + + beforeEach(() => { + events = [] + recordSpy = spyOn(diagnosticsService, 'recordEvent').mockImplementation(async (event) => { + events.push(event) + }) + }) + + afterEach(() => { + recordSpy.mockRestore() + }) + + const upstreamEvents = () => events.filter((event) => event.type === 'upstream_request') + const chatChunk = (delta: Record, finishReason: string | null = null) => + `data: ${JSON.stringify({ id: 'c1', object: 'chat.completion.chunk', created: 0, model: 'model-main', choices: [{ index: 0, delta, finish_reason: finishReason }] })}\n\n` + + test('records a successful request without the key or the request body', async () => { + mockFetch(() => Response.json(openaiChatMessage, { headers: { 'x-request-id': 'req_123' } })) + + await sendToUpstream(target({ apiFormat: 'openai_chat', providerId: 'p1' }), request) + + expect(upstreamEvents()).toHaveLength(1) + const [event] = upstreamEvents() + expect(event!.severity).toBe('info') + expect(event!.details).toMatchObject({ + providerId: 'p1', + model: 'model-main', + host: 'api.example.com', + apiFormat: 'openai_chat', + stream: false, + status: 200, + requestId: 'req_123', + outcome: 'completed', + }) + expect(typeof (event!.details as { durationMs: unknown }).durationMs).toBe('number') + expect(JSON.stringify(event)).not.toContain('sk-test') + expect(JSON.stringify(event)).not.toContain('hello') + }) + + test('records an upstream HTTP error as a warning', async () => { + mockFetch(() => new Response('slow down', { status: 429 })) + + await sendToUpstream(target({ apiFormat: 'openai_chat' }), request) + + expect(upstreamEvents()).toHaveLength(1) + expect(upstreamEvents()[0]!.severity).toBe('warn') + expect(upstreamEvents()[0]!.details).toMatchObject({ status: 429, outcome: 'error', error: 'Upstream returned HTTP 429: slow down' }) + }) + + test('records an error reported in the middle of a stream when the stream ends', async () => { + mockFetch(() => new Response( + chatChunk({ role: 'assistant', content: 'Hi' }) + 'data: {"error":{"message":"overloaded"}}\n\n', + { headers: { 'Content-Type': 'text/event-stream' } }, + )) + + const result = await sendToUpstream(target({ apiFormat: 'openai_chat' }), { ...request, stream: true }) + expect(upstreamEvents()).toHaveLength(0) + await new Response((result as { stream: ReadableStream }).stream).text() + + expect(upstreamEvents()).toHaveLength(1) + expect(upstreamEvents()[0]!.severity).toBe('warn') + expect(upstreamEvents()[0]!.details).toMatchObject({ stream: true, status: 200, outcome: 'error', error: 'overloaded' }) + }) + + test('records a request the client aborted before the upstream answered', async () => { + globalThis.fetch = mock((_url: string | URL | Request, init?: RequestInit) => new Promise((_resolve, reject) => { + const abort = () => reject(new DOMException('The operation was aborted.', 'AbortError')) + if (init?.signal?.aborted) abort() + init?.signal?.addEventListener('abort', abort) + })) as unknown as typeof fetch + const client = new AbortController() + + const pending = sendToUpstream(target({ apiFormat: 'openai_chat' }), request, { signal: client.signal }) + client.abort() + const result = await pending + + expect(result.ok).toBe(false) + expect(upstreamEvents()).toHaveLength(1) + expect(upstreamEvents()[0]!.severity).toBe('info') + expect(upstreamEvents()[0]!.details).toMatchObject({ outcome: 'client_aborted' }) + }) + + test('records a client that disconnects as a disconnect when the upstream read fails first', async () => { + globalThis.fetch = mock(async (_url: string | URL | Request, init?: RequestInit) => new Response(new ReadableStream({ + start(controller) { + controller.enqueue(new TextEncoder().encode(chatChunk({ role: 'assistant', content: 'Hi' }))) + init?.signal?.addEventListener('abort', () => controller.error(new DOMException('The operation was aborted.', 'AbortError'))) + }, + }), { headers: { 'Content-Type': 'text/event-stream' } })) as unknown as typeof fetch + const client = new AbortController() + + const result = await sendToUpstream(target({ apiFormat: 'openai_chat' }), { ...request, stream: true }, { signal: client.signal }) + const reader = (result as { stream: ReadableStream }).stream.getReader() + await reader.read() + client.abort() + await reader.read().catch(() => null) + + expect(upstreamEvents()).toHaveLength(1) + expect(upstreamEvents()[0]!.details).toMatchObject({ stream: true, outcome: 'client_disconnected' }) + }) + + test('records an idle timeout as its own outcome', async () => { + mockFetch(() => new Response(new ReadableStream({ + start(controller) { + controller.enqueue(new TextEncoder().encode(chatChunk({ role: 'assistant', content: 'Hi' }))) + }, + }), { headers: { 'Content-Type': 'text/event-stream' } })) + + const result = await sendToUpstream(target({ apiFormat: 'openai_chat' }), { ...request, stream: true }, { timeoutMs: 200 }) + await new Response((result as { stream: ReadableStream }).stream).text() + + expect(upstreamEvents()).toHaveLength(1) + expect(upstreamEvents()[0]!.severity).toBe('warn') + expect(upstreamEvents()[0]!.details).toMatchObject({ stream: true, outcome: 'idle_timeout' }) + }) + + test('records a client that disconnects in the middle of a stream', async () => { + mockFetch(() => new Response(new ReadableStream({ + start(controller) { + controller.enqueue(new TextEncoder().encode(chatChunk({ role: 'assistant', content: 'Hi' }))) + }, + }), { headers: { 'Content-Type': 'text/event-stream' } })) + + const result = await sendToUpstream(target({ apiFormat: 'openai_chat' }), { ...request, stream: true }) + const reader = (result as { stream: ReadableStream }).stream.getReader() + await reader.read() + await reader.cancel('client gone') + + expect(upstreamEvents()).toHaveLength(1) + expect(upstreamEvents()[0]!.details).toMatchObject({ stream: true, outcome: 'client_disconnected' }) + }) + }) }) diff --git a/src/server/index.ts b/src/server/index.ts index 735def55..a0ed3af4 100644 --- a/src/server/index.ts +++ b/src/server/index.ts @@ -363,7 +363,7 @@ export function startServer(port = PORT, host = HOST) { } } try { - const response = await handleProxyRequest(req, url) + const response = await handleProxyRequest(req, url, server) return withCors(response, cors) } catch (error) { void diagnosticsService.recordEvent({ diff --git a/src/server/proxy/handler.ts b/src/server/proxy/handler.ts index ab2392f3..381c25b0 100644 --- a/src/server/proxy/handler.ts +++ b/src/server/proxy/handler.ts @@ -1,3 +1,4 @@ +import { isClaudeModelName } from '../services/attributionHeaderPolicy.js' import { ProviderService } from '../services/providerService.js' import { sendToUpstream } from '../upstream/client.js' import { ensureClaudeCodeAttribution } from './claudeCodeAttribution.js' @@ -5,7 +6,12 @@ import type { AnthropicRequest } from './transform/types.js' const providerService = new ProviderService() -export async function handleProxyRequest(req: Request, url: URL): Promise { +export type ProxyServer = { + timeout(request: Request, seconds: number): void +} + +export async function handleProxyRequest(req: Request, url: URL, server: ProxyServer): Promise { + server.timeout(req, 0) const providerMatch = url.pathname.match(/^\/proxy\/providers\/([^/]+)\/v1\/messages$/) const providerId = providerMatch ? decodeURIComponent(providerMatch[1]!) : undefined const isActiveProxyPath = url.pathname === '/proxy/v1/messages' @@ -13,8 +19,11 @@ export async function handleProxyRequest(req: Request, url: URL): Promise { const encoder = new TextEncoder() - const decoder = new TextDecoder() - let buffer = '' + const sse = new SseDecoder() const state = createState(model) const reader = upstream.getReader() let cancelled = false @@ -75,59 +75,24 @@ export function openaiChatStreamToAnthropic( return new ReadableStream({ async start(controller) { let errored = false + const handle = (messages: SseMessage[]) => { + for (const message of messages) { + if (message.type === 'event') handleData(message.data.trim(), state, controller, encoder) + else if (!state.messageStopSent) controller.enqueue(encoder.encode(formatSse('ping', { type: 'ping' }))) + } + } try { while (true) { const { done, value } = await reader.read() if (done) break - - buffer += decoder.decode(value, { stream: true }) - const lines = buffer.split('\n') - buffer = lines.pop() || '' - - for (const line of lines) { - const trimmed = line.trim() - if (!trimmed || trimmed.startsWith(':')) continue - - if (trimmed === 'data: [DONE]') { - finalizeStream(state) - flushQueue(state, controller, encoder) - continue - } - - if (!trimmed.startsWith('data: ')) { - if (!state.upstreamError && trimmed.startsWith('{')) { - state.upstreamError = readUpstreamError(parseJson(trimmed)) - } - continue - } - const jsonStr = trimmed.slice(6) - - let chunk: OpenAIChatStreamChunk - try { - chunk = JSON.parse(jsonStr) - } catch { - continue - } - - if (state.upstreamError) continue - const upstreamError = readUpstreamError(chunk) - if (upstreamError) { - state.upstreamError = upstreamError - finalizeStream(state) - flushQueue(state, controller, encoder) - continue - } - if (Array.isArray(chunk.choices)) state.sawValidChunk = true - - processChunk(chunk, state) - flushQueue(state, controller, encoder) - } + handle(sse.push(value)) } + handle(sse.flush()) - const rest = buffer.trim() - if (!state.upstreamError && rest.startsWith('{')) { - state.upstreamError = readUpstreamError(parseJson(rest)) + const body = sse.unframedBody() + if (!state.upstreamError && body) { + state.upstreamError = readUpstreamError(parseSseJson(body)) } } catch (err) { errored = true @@ -147,6 +112,33 @@ export function openaiChatStreamToAnthropic( }) } +function handleData( + data: string, + state: StreamState, + controller: ReadableStreamDefaultController, + encoder: TextEncoder, +): void { + if (data === '[DONE]') { + finalizeStream(state) + flushQueue(state, controller, encoder) + return + } + + const chunk = parseSseJson(data) as OpenAIChatStreamChunk | undefined + if (!chunk || state.upstreamError) return + const upstreamError = readUpstreamError(chunk) + if (upstreamError) { + state.upstreamError = upstreamError + finalizeStream(state) + flushQueue(state, controller, encoder) + return + } + if (Array.isArray(chunk.choices)) state.sawValidChunk = true + + processChunk(chunk, state) + flushQueue(state, controller, encoder) +} + function enqueue(state: StreamState, event: string, data: unknown): void { state.queue.push({ event, data }) } @@ -301,7 +293,6 @@ function processChunk(chunk: OpenAIChatStreamChunk, state: StreamState): void { return } - state.model = chunk.model || state.model ensureMessageStart(state, chunk.id) const delta = choice.delta as DeltaEx @@ -475,14 +466,6 @@ function mergeUsageIntoHeldDelta( state.heldMessageDelta = null } -function parseJson(text: string): unknown { - try { - return JSON.parse(text) - } catch { - return null - } -} - function readUpstreamError(chunk: unknown): string | null { const error = (chunk as { error?: unknown } | null)?.error if (!error || typeof error !== 'object') return null diff --git a/src/server/proxy/streaming/openaiResponsesStreamToAnthropic.ts b/src/server/proxy/streaming/openaiResponsesStreamToAnthropic.ts index f869f7c8..947a8852 100644 --- a/src/server/proxy/streaming/openaiResponsesStreamToAnthropic.ts +++ b/src/server/proxy/streaming/openaiResponsesStreamToAnthropic.ts @@ -1,6 +1,7 @@ import { stringifyOpenAIToolArguments } from '../transform/toolArguments.js' import { mapResponsesUsage } from '../transform/openaiResponsesToAnthropic.js' import type { OpenAIResponsesUsage } from '../transform/types.js' +import { parseSseJson, SseDecoder, type SseMessage } from './sse.js' type StreamState = { nextContentIndex: number @@ -29,8 +30,7 @@ export function openaiResponsesStreamToAnthropic( model: string, ): ReadableStream { const encoder = new TextEncoder() - const decoder = new TextDecoder() - let buffer = '' + const sse = new SseDecoder() const state: StreamState = { nextContentIndex: 0, @@ -47,57 +47,23 @@ export function openaiResponsesStreamToAnthropic( return new ReadableStream({ async start(controller) { - let currentEvent = '' + const handle = (messages: SseMessage[]) => { + for (const message of messages) { + if (message.type === 'event') handleEvent(message.event, message.data.trim(), state, controller, encoder) + else if (!state.messageStopped) controller.enqueue(encoder.encode(formatSse('ping', { type: 'ping' }))) + } + } try { while (true) { const { done, value } = await reader.read() if (done) break - - buffer += decoder.decode(value, { stream: true }) - const lines = buffer.split('\n') - buffer = lines.pop() || '' - - for (const line of lines) { - const trimmed = line.trim() - - if (trimmed.startsWith('event: ')) { - currentEvent = trimmed.slice(7).trim() - continue - } - - if (trimmed.startsWith('data: ')) { - const jsonStr = trimmed.slice(6) - if (jsonStr === '[DONE]') { - if (!state.messageStopped) { - state.messageStopped = true - if (!state.messageStarted) { - emitMessageStart(state, controller, encoder, model) - } - controller.enqueue(encoder.encode(formatSse('message_stop', { type: 'message_stop' }))) - } - continue - } - - let data: Record - try { - data = JSON.parse(jsonStr) - } catch { - continue - } - - if (!state.messageStopped) { - processEvent(currentEvent || String(data.type ?? ''), data, state, controller, encoder) - } - currentEvent = '' - continue - } - - if (trimmed === '') { - currentEvent = '' - } - } + handle(sse.push(value)) } + handle(sse.flush()) + + const body = sse.unframedBody() + if (body) emitUnframedError(body, controller, encoder) } catch (err) { if (!cancelled) controller.error(err) return @@ -111,11 +77,47 @@ export function openaiResponsesStreamToAnthropic( }) } +function handleEvent( + event: string, + data: string, + state: StreamState, + controller: ReadableStreamDefaultController, + encoder: TextEncoder, +): void { + if (data === '[DONE]') { + if (!state.messageStopped) { + state.messageStopped = true + if (!state.messageStarted) { + emitMessageStart(state, controller, encoder) + } + controller.enqueue(encoder.encode(formatSse('message_stop', { type: 'message_stop' }))) + } + return + } + + const parsed = parseSseJson(data) + if (state.messageStopped || !parsed || typeof parsed !== 'object') return + const record = parsed as Record + processEvent(event || String(record.type ?? ''), record, state, controller, encoder) +} + +function emitUnframedError( + body: string, + controller: ReadableStreamDefaultController, + encoder: TextEncoder, +): void { + const parsed = parseSseJson(body) as Record | undefined + if (!parsed || typeof parsed !== 'object' || !parsed.error) return + controller.enqueue(encoder.encode(formatSse('error', { + type: 'error', + error: { type: 'api_error', message: upstreamErrorMessage(parsed) }, + }))) +} + function emitMessageStart( state: StreamState, controller: ReadableStreamDefaultController, encoder: TextEncoder, - model: string, ): void { state.messageStarted = true controller.enqueue(encoder.encode(formatSse('message_start', { @@ -125,7 +127,7 @@ function emitMessageStart( type: 'message', role: 'assistant', content: [], - model, + model: state.model, stop_reason: null, stop_sequence: null, usage: { input_tokens: 0, output_tokens: 0 }, @@ -142,14 +144,12 @@ function processEvent( ): void { switch (event) { case 'response.created': { - const response = data as Record - state.model = (response.model as string) || state.model - emitMessageStart(state, controller, encoder, state.model) + emitMessageStart(state, controller, encoder) break } case 'response.output_item.added': { - if (!state.messageStarted) emitMessageStart(state, controller, encoder, state.model) + if (!state.messageStarted) emitMessageStart(state, controller, encoder) const item = data.item as Record | undefined if (!item) break @@ -174,7 +174,7 @@ function processEvent( } case 'response.content_part.added': { - if (!state.messageStarted) emitMessageStart(state, controller, encoder, state.model) + if (!state.messageStarted) emitMessageStart(state, controller, encoder) const part = data.part as Record | undefined if (part?.type !== 'output_text' && part?.type !== 'refusal') break @@ -272,7 +272,7 @@ function processEvent( if (index === undefined) { index = state.nextContentIndex++ state.reasoningIndexByItemId.set(itemId, index) - if (!state.messageStarted) emitMessageStart(state, controller, encoder, state.model) + if (!state.messageStarted) emitMessageStart(state, controller, encoder) controller.enqueue(encoder.encode(formatSse('content_block_start', { type: 'content_block_start', index, diff --git a/src/server/proxy/streaming/openaiResponsesStreamToAnthropicResponse.ts b/src/server/proxy/streaming/openaiResponsesStreamToAnthropicResponse.ts index 9ecd8b88..bebba1ec 100644 --- a/src/server/proxy/streaming/openaiResponsesStreamToAnthropicResponse.ts +++ b/src/server/proxy/streaming/openaiResponsesStreamToAnthropicResponse.ts @@ -1,5 +1,6 @@ import { openaiResponsesToAnthropic } from '../transform/openaiResponsesToAnthropic.js' import { upstreamErrorMessage } from './openaiResponsesStreamToAnthropic.js' +import { parseSseJson, SseDecoder, type SseMessage } from './sse.js' import type { AnthropicResponse, OpenAIResponsesResponse, @@ -8,7 +9,6 @@ import type { type StreamFallbackState = { id: string createdAt: number - model: string status: string textByKey: Map usage: OpenAIResponsesResponse['usage'] @@ -20,76 +20,49 @@ export async function openaiResponsesStreamToAnthropicResponse( upstream: ReadableStream, model: string, ): Promise { - const decoder = new TextDecoder() + const sse = new SseDecoder() const reader = upstream.getReader() - let buffer = '' - let currentEvent = '' let completedResponse: OpenAIResponsesResponse | null = null let upstreamError: string | null = null const fallback: StreamFallbackState = { id: `resp_${Date.now()}`, createdAt: Math.floor(Date.now() / 1000), - model, status: 'completed', textByKey: new Map(), usage: undefined, } - while (true) { - const { done, value } = await reader.read() - if (done) break - - buffer += decoder.decode(value, { stream: true }) - const lines = buffer.split('\n') - buffer = lines.pop() || '' - - for (const line of lines) { - const trimmed = line.trim() - if (trimmed.startsWith('event: ')) { - currentEvent = trimmed.slice(7).trim() - continue - } - - if (!trimmed.startsWith('data: ')) { - if (trimmed === '') currentEvent = '' - continue - } - - const jsonStr = trimmed.slice(6) - if (jsonStr === '[DONE]') { - currentEvent = '' - continue - } - - let data: Record - try { - data = JSON.parse(jsonStr) as Record - } catch { - currentEvent = '' - continue - } - - if (currentEvent === 'response.completed' || currentEvent === 'response.incomplete') { - const response = data.response - if (isOpenAIResponsesResponse(response)) { - completedResponse = response - } - } else if (currentEvent === 'response.failed' || currentEvent === 'error') { + const handle = (messages: SseMessage[]) => { + for (const message of messages) { + if (message.type !== 'event') continue + const event = message.event + const parsed = parseSseJson(message.data.trim()) + if (!parsed || typeof parsed !== 'object') continue + const data = parsed as Record + if (event === 'response.completed' || event === 'response.incomplete') { + if (isOpenAIResponsesResponse(data.response)) completedResponse = data.response + } else if (event === 'response.failed' || event === 'error') { upstreamError = upstreamErrorMessage(data) } else { - updateFallbackState(currentEvent, data, fallback) + updateFallbackState(event, data, fallback) } - currentEvent = '' } } + while (true) { + const { done, value } = await reader.read() + if (done) break + handle(sse.push(value)) + } + handle(sse.flush()) + if (!completedResponse && upstreamError !== null) { throw new OpenAIResponsesStreamError(upstreamError) } return openaiResponsesToAnthropic( - completedResponse ?? buildFallbackResponse(fallback), + completedResponse ?? buildFallbackResponse(fallback, model), model, ) } @@ -102,7 +75,6 @@ function updateFallbackState( if (event === 'response.created') { if (typeof data.id === 'string') fallback.id = data.id if (typeof data.created_at === 'number') fallback.createdAt = data.created_at - if (typeof data.model === 'string') fallback.model = data.model if (typeof data.status === 'string') fallback.status = data.status return } @@ -129,6 +101,7 @@ function updateFallbackState( function buildFallbackResponse( fallback: StreamFallbackState, + model: string, ): OpenAIResponsesResponse { const text = [...fallback.textByKey.entries()] .sort(([a], [b]) => a.localeCompare(b)) @@ -139,7 +112,7 @@ function buildFallbackResponse( id: fallback.id, object: 'response', created_at: fallback.createdAt, - model: fallback.model, + model, status: fallback.status, output: [{ type: 'message', diff --git a/src/server/proxy/streaming/sse.ts b/src/server/proxy/streaming/sse.ts new file mode 100644 index 00000000..f43ca05e --- /dev/null +++ b/src/server/proxy/streaming/sse.ts @@ -0,0 +1,82 @@ +export type SseMessage = + | { type: 'event'; event: string; data: string } + | { type: 'comment' } + +const MAX_UNFRAMED_BODY = 64 * 1024 + +export class SseDecoder { + private readonly decoder = new TextDecoder() + private buffer = '' + private event = '' + private data: string[] = [] + private sawEvent = false + private unframed = '' + + push(chunk: Uint8Array): SseMessage[] { + return this.consume(this.decoder.decode(chunk, { stream: true }), false) + } + + flush(): SseMessage[] { + const messages = this.consume(this.decoder.decode(), true) + const pending = this.dispatch() + return pending ? [...messages, pending] : messages + } + + unframedBody(): string | null { + return this.sawEvent ? null : this.unframed.trim() || null + } + + private consume(text: string, final: boolean): SseMessage[] { + if (!this.sawEvent && this.unframed.length < MAX_UNFRAMED_BODY) this.unframed += text + let pending = this.buffer + text + const heldCarriageReturn = !final && pending.endsWith('\r') + if (heldCarriageReturn) pending = pending.slice(0, -1) + const lines = pending.split(/\r\n|\r|\n/) + const rest = lines.pop() ?? '' + if (final) { + if (rest) lines.push(rest) + this.buffer = '' + } else { + this.buffer = heldCarriageReturn ? `${rest}\r` : rest + } + + const messages: SseMessage[] = [] + for (const line of lines) { + const message = this.readLine(line) + if (message) messages.push(message) + } + return messages + } + + private readLine(line: string): SseMessage | null { + if (line === '') return this.dispatch() + if (line.startsWith(':')) return { type: 'comment' } + + const colon = line.indexOf(':') + const field = colon === -1 ? line : line.slice(0, colon) + const rawValue = colon === -1 ? '' : line.slice(colon + 1) + const value = rawValue.startsWith(' ') ? rawValue.slice(1) : rawValue + + if (field === 'data') this.data.push(value) + else if (field === 'event') this.event = value + return null + } + + private dispatch(): SseMessage | null { + const event = this.event + const data = this.data + this.event = '' + this.data = [] + if (data.length === 0) return null + this.sawEvent = true + return { type: 'event', event, data: data.join('\n') } + } +} + +export function parseSseJson(data: string): unknown { + try { + return JSON.parse(data) + } catch { + return undefined + } +} diff --git a/src/server/proxy/transform/anthropicToOpenaiChat.ts b/src/server/proxy/transform/anthropicToOpenaiChat.ts index fb224557..9f4f1a41 100644 --- a/src/server/proxy/transform/anthropicToOpenaiChat.ts +++ b/src/server/proxy/transform/anthropicToOpenaiChat.ts @@ -9,6 +9,7 @@ import type { OpenAITool, } from './types.js' import { extractToolResultContent } from './toolArguments.js' +import { cleanToolSchema } from './toolSchema.js' export function anthropicToOpenaiChat( body: AnthropicRequest, @@ -52,9 +53,10 @@ export function anthropicToOpenaiChat( function: { name: t.name, description: t.description, - parameters: t.input_schema, + parameters: cleanToolSchema(t.input_schema), }, })) + if (result.tools.length > 0) result.parallel_tool_calls = true } if (body.tool_choice !== undefined) { diff --git a/src/server/proxy/transform/anthropicToOpenaiResponses.ts b/src/server/proxy/transform/anthropicToOpenaiResponses.ts index c86a6631..64554f11 100644 --- a/src/server/proxy/transform/anthropicToOpenaiResponses.ts +++ b/src/server/proxy/transform/anthropicToOpenaiResponses.ts @@ -6,8 +6,12 @@ import type { OpenAIResponsesContentPart, } from './types.js' import { extractToolResultContent } from './toolArguments.js' +import { cleanToolSchema } from './toolSchema.js' -export function anthropicToOpenaiResponses(body: AnthropicRequest): OpenAIResponsesRequest { +export function anthropicToOpenaiResponses( + body: AnthropicRequest, + options: { promptCacheKey?: string } = {}, +): OpenAIResponsesRequest { const input: OpenAIResponsesInputItem[] = [] for (const msg of body.messages) { @@ -21,6 +25,8 @@ export function anthropicToOpenaiResponses(body: AnthropicRequest): OpenAIRespon store: false, } + if (options.promptCacheKey) result.prompt_cache_key = options.promptCacheKey + if (body.system) { if (typeof body.system === 'string') { result.instructions = body.system @@ -39,9 +45,10 @@ export function anthropicToOpenaiResponses(body: AnthropicRequest): OpenAIRespon type: 'function', name: t.name, description: t.description, - parameters: t.input_schema, + parameters: cleanToolSchema(t.input_schema), strict: false, })) + if (result.tools.length > 0) result.parallel_tool_calls = true } if (body.tool_choice !== undefined) { diff --git a/src/server/proxy/transform/openaiChatToAnthropic.ts b/src/server/proxy/transform/openaiChatToAnthropic.ts index fd032d22..6335c90c 100644 --- a/src/server/proxy/transform/openaiChatToAnthropic.ts +++ b/src/server/proxy/transform/openaiChatToAnthropic.ts @@ -53,7 +53,7 @@ export function openaiChatToAnthropic(response: OpenAIChatResponse, model: strin type: 'message', role: 'assistant', content, - model: response.model || model, + model, stop_reason: mapStopReason(choice.finish_reason, content.some((block) => block.type === 'tool_use')), stop_sequence: null, usage: mapUsage(response.usage), @@ -82,7 +82,10 @@ export function mapUsage(usage?: OpenAIChatResponse['usage']): AnthropicResponse if (!usage) { return { input_tokens: 0, output_tokens: 0 } } - const cached = usage.prompt_tokens_details?.cached_tokens || 0 + const cached = usage.prompt_tokens_details?.cached_tokens + || usage.prompt_cache_hit_tokens + || usage.cached_tokens + || 0 return { input_tokens: Math.max(0, (usage.prompt_tokens || 0) - cached), output_tokens: usage.completion_tokens || 0, @@ -96,7 +99,7 @@ function createEmptyResponse(response: OpenAIChatResponse, model: string): Anthr type: 'message', role: 'assistant', content: [{ type: 'text', text: '' }], - model: response.model || model, + model, stop_reason: 'end_turn', stop_sequence: null, usage: mapUsage(response.usage), diff --git a/src/server/proxy/transform/openaiResponsesToAnthropic.ts b/src/server/proxy/transform/openaiResponsesToAnthropic.ts index 9220be45..a8d1956f 100644 --- a/src/server/proxy/transform/openaiResponsesToAnthropic.ts +++ b/src/server/proxy/transform/openaiResponsesToAnthropic.ts @@ -25,7 +25,7 @@ export function openaiResponsesToAnthropic(response: OpenAIResponsesResponse, mo type: 'message', role: 'assistant', content, - model: response.model || model, + model, stop_reason: mapStatus(response.status, hasToolUse), stop_sequence: null, usage: mapResponsesUsage(response.usage), diff --git a/src/server/proxy/transform/toolSchema.ts b/src/server/proxy/transform/toolSchema.ts new file mode 100644 index 00000000..86ba66a8 --- /dev/null +++ b/src/server/proxy/transform/toolSchema.ts @@ -0,0 +1,22 @@ +export function cleanToolSchema(schema: Record): Record { + return cleanValue(schema) as Record +} + +function cleanValue(value: unknown): unknown { + if (Array.isArray(value)) return value.map(cleanValue) + if (!value || typeof value !== 'object') return value + + const cleaned: Record = {} + for (const [key, child] of Object.entries(value)) { + if (isUnusedKeyword(key, child)) continue + cleaned[key] = cleanValue(child) + } + return cleaned +} + +function isUnusedKeyword(key: string, value: unknown): boolean { + if (key === '$schema') return typeof value === 'string' + if (key === 'maximum') return value === Number.MAX_SAFE_INTEGER + if (key === 'minimum') return value === Number.MIN_SAFE_INTEGER + return false +} diff --git a/src/server/proxy/transform/types.ts b/src/server/proxy/transform/types.ts index 42181480..37558146 100644 --- a/src/server/proxy/transform/types.ts +++ b/src/server/proxy/transform/types.ts @@ -41,6 +41,7 @@ export type OpenAIChatRequest = { stream_options?: { include_usage: boolean } tools?: OpenAITool[] tool_choice?: unknown + parallel_tool_calls?: boolean reasoning_effort?: 'low' | 'medium' | 'high' thinking?: { type: string } } @@ -66,6 +67,8 @@ export type OpenAIChatResponse = { prompt_tokens_details?: { cached_tokens?: number } + prompt_cache_hit_tokens?: number + cached_tokens?: number } } @@ -121,7 +124,9 @@ export type OpenAIResponsesRequest = { strict: false }> tool_choice?: unknown + parallel_tool_calls?: boolean reasoning?: { effort?: 'low' | 'medium' | 'high' } + prompt_cache_key?: string } export type OpenAIResponsesOutputItem = diff --git a/src/server/services/conversationService.ts b/src/server/services/conversationService.ts index e5f7f82e..3b2ac0c7 100644 --- a/src/server/services/conversationService.ts +++ b/src/server/services/conversationService.ts @@ -17,6 +17,7 @@ import { getClaudeConfigHomeDir } from '../../utils/envUtils.js' import { findCanonicalGitRoot } from '../../utils/git.js' import { sanitizePath } from '../../utils/path.js' import { getProcessEnvWithTerminalShellEnvironment } from '../../utils/terminalShellEnvironment.js' +import { PROVIDER_PROXIED_ENV_KEY } from '../../utils/providerProxy.js' import { browserMcpChildEnv, webCloneChildEnv } from '../browserHost/childEnv.js' import { attributionHeaderEnvForModel } from './attributionHeaderPolicy.js' import { buildNetworkEnvironment, normalizeNetworkSettings } from './networkSettings.js' @@ -1008,6 +1009,7 @@ export class ConversationService { 'CLAUDE_CODE_MODEL_CONTEXT_WINDOWS', 'DREAMCODER_OPENAI_OAUTH_PROVIDER', 'OPENAI_CODEX_OAUTH_FILE', + PROVIDER_PROXIED_ENV_KEY, ] as const const cleanEnv = await getProcessEnvWithTerminalShellEnvironment() @@ -1033,7 +1035,7 @@ export class ConversationService { ? await this.providerService.getProviderRuntimeEnv(options.providerId, options.model) : null const userSettings = await new SettingsService().getUserSettings() - const networkEnv = buildNetworkEnvironment(normalizeNetworkSettings(userSettings)) + const networkEnv = buildNetworkEnvironment(normalizeNetworkSettings(userSettings), cleanEnv) applyAgentTeamsSetting(cleanEnv, userSettings) const attributionHeaderEnv = attributionHeaderEnvForModel( options?.model?.trim() || diff --git a/src/server/services/cronScheduler.ts b/src/server/services/cronScheduler.ts index 6d695d8d..efab1098 100644 --- a/src/server/services/cronScheduler.ts +++ b/src/server/services/cronScheduler.ts @@ -15,6 +15,7 @@ import { getProcessEnvWithTerminalShellEnvironment } from '../../utils/terminalS import { attributionHeaderEnvForModel } from './attributionHeaderPolicy.js' import { applyAgentTeamsSetting } from './agentTeamsEnv.js' import { SettingsService } from './settingsService.js' +import { buildNetworkEnvironment, normalizeNetworkSettings } from './networkSettings.js' import { isPermissionMode, permissionModeCliArgs } from './permissionModes.js' import { getClaudeConfigHomeDir } from '../../utils/envUtils.js' @@ -577,7 +578,8 @@ export class CronScheduler { ): Promise> { const cleanEnv = await getProcessEnvWithTerminalShellEnvironment() delete cleanEnv.CLAUDE_CODE_OAUTH_TOKEN - applyAgentTeamsSetting(cleanEnv, await new SettingsService().getUserSettings()) + const userSettings = await new SettingsService().getUserSettings() + applyAgentTeamsSetting(cleanEnv, userSettings) if (this.shouldStripInheritedProviderEnv(task.providerId)) { for (const key of Object.keys(cleanEnv)) { @@ -604,6 +606,7 @@ export class CronScheduler { CALLER_DIR: workDir, PWD: workDir, DREAMCODER_SKIP_DOTENV: '1', + ...buildNetworkEnvironment(normalizeNetworkSettings(userSettings), cleanEnv), ...(explicitProviderEnv ? { CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST: '1', diff --git a/src/server/services/cuaDriverService.ts b/src/server/services/cuaDriverService.ts index beb4d4ae..431ea674 100644 --- a/src/server/services/cuaDriverService.ts +++ b/src/server/services/cuaDriverService.ts @@ -763,13 +763,10 @@ export function defaultDeps(): CuaDriverDeps { await writeFile(path, data, 'utf8') }, networkEnv: async () => { - const { loadNetworkSettings, buildNetworkEnvironment } = await import( + const { loadNetworkSettings, buildProxyEnvironment } = await import( './networkSettings.js' ) - const { API_TIMEOUT_MS: _timeout, ...env } = buildNetworkEnvironment( - await loadNetworkSettings(), - ) - return env + return buildProxyEnvironment(await loadNetworkSettings(), process.env) }, } } diff --git a/src/server/services/diagnosticsService.ts b/src/server/services/diagnosticsService.ts index 0f2e90c8..3153a25e 100644 --- a/src/server/services/diagnosticsService.ts +++ b/src/server/services/diagnosticsService.ts @@ -78,13 +78,16 @@ export class DiagnosticsService { ...(input.details !== undefined ? { details: this.sanitizeValue(input.details) } : {}), } + const logDir = this.getLogDir() + const diagnosticsPath = this.getDiagnosticsPath() + const runtimeErrorsPath = this.getRuntimeErrorsPath() try { await this.ensureLogDir() - await fs.appendFile(this.getDiagnosticsPath(), JSON.stringify(event) + '\n', 'utf-8') + await fs.appendFile(diagnosticsPath, JSON.stringify(event) + '\n', 'utf-8') if (event.severity === 'warn' || event.severity === 'error') { - await fs.appendFile(this.getRuntimeErrorsPath(), this.formatRuntimeLogEntry(event), 'utf-8') + await fs.appendFile(runtimeErrorsPath, this.formatRuntimeLogEntry(event), 'utf-8') } - await this.enforceRetention().catch(() => {}) + await this.enforceRetention(logDir).catch(() => {}) } catch { } } @@ -488,8 +491,7 @@ export class DiagnosticsService { } } - private async enforceRetention(): Promise { - const dir = this.getLogDir() + private async enforceRetention(dir: string): Promise { const cutoff = Date.now() - RETENTION_DAYS * 24 * 60 * 60 * 1000 const files = await this.listFiles(dir) diff --git a/src/server/services/networkSettings.ts b/src/server/services/networkSettings.ts index b97f70c2..4c354c81 100644 --- a/src/server/services/networkSettings.ts +++ b/src/server/services/networkSettings.ts @@ -1,3 +1,4 @@ +import { getNoProxy } from '../../utils/proxy.js' import { SettingsService } from './settingsService.js' export type NetworkProxyMode = 'system' | 'manual' @@ -14,6 +15,8 @@ export const DEFAULT_AI_REQUEST_TIMEOUT_MS = 120_000 export const MIN_AI_REQUEST_TIMEOUT_MS = 5_000 export const MAX_AI_REQUEST_TIMEOUT_MS = 600_000 +const LOOPBACK_HOSTS = ['127.0.0.1', 'localhost', '::1'] + const DEFAULT_NETWORK_SETTINGS: NetworkSettings = { aiRequestTimeoutMs: DEFAULT_AI_REQUEST_TIMEOUT_MS, proxy: { @@ -72,20 +75,41 @@ export function getManualNetworkProxyUrl(settings: NetworkSettings): string | un return url || undefined } -export function buildNetworkEnvironment(settings: NetworkSettings): Record { - const env: Record = { - API_TIMEOUT_MS: String(settings.aiRequestTimeoutMs), +export function buildNetworkEnvironment( + settings: NetworkSettings, + inheritedEnv: Record, +): Record { + const timeout = String(settings.aiRequestTimeoutMs) + return { + API_TIMEOUT_MS: timeout, + CLAUDE_ENABLE_STREAM_WATCHDOG: '1', + CLAUDE_STREAM_IDLE_TIMEOUT_MS: timeout, + ...buildProxyEnvironment(settings, inheritedEnv), } +} + +export function buildProxyEnvironment( + settings: NetworkSettings, + inheritedEnv: Record, +): Record { const proxyUrl = getManualNetworkProxyUrl(settings) + if (!proxyUrl) return {} - if (proxyUrl) { - env.HTTP_PROXY = proxyUrl - env.HTTPS_PROXY = proxyUrl - env.http_proxy = proxyUrl - env.https_proxy = proxyUrl + const noProxy = mergeNoProxy(getNoProxy(inheritedEnv)) + return { + HTTP_PROXY: proxyUrl, + HTTPS_PROXY: proxyUrl, + http_proxy: proxyUrl, + https_proxy: proxyUrl, + NO_PROXY: noProxy, + no_proxy: noProxy, } +} - return env +function mergeNoProxy(inherited: string | undefined): string { + if (inherited?.trim() === '*') return '*' + const entries = (inherited ?? '').split(/[,\s]+/).filter(Boolean) + return [...new Set([...entries, ...LOOPBACK_HOSTS])].join(',') } export async function loadNetworkSettings(): Promise { diff --git a/src/server/services/providerRuntimeEnv.ts b/src/server/services/providerRuntimeEnv.ts index b670c118..42d53725 100644 --- a/src/server/services/providerRuntimeEnv.ts +++ b/src/server/services/providerRuntimeEnv.ts @@ -2,6 +2,7 @@ import * as fs from 'fs' import * as path from 'path' import { MODEL_CONTEXT_WINDOWS_ENV_KEY } from '../../utils/model/modelContextWindows.js' +import { PROVIDER_PROXIED_ENV_KEY } from '../../utils/providerProxy.js' import { PROVIDER_PRESETS } from '../config/providerPresets.js' import type { ApiFormat, @@ -33,6 +34,7 @@ export const MANAGED_PROVIDER_ENV_KEYS = [ MODEL_CONTEXT_WINDOWS_ENV_KEY, 'DREAMCODER_OPENAI_OAUTH_PROVIDER', 'OPENAI_CODEX_OAUTH_FILE', + PROVIDER_PROXIED_ENV_KEY, ] as const const CUSTOM_PROVIDER_MODEL_CAPABILITIES = 'thinking,effort,adaptive_thinking,max_effort' @@ -249,6 +251,7 @@ export function buildProviderManagedEnv( ANTHROPIC_DEFAULT_SONNET_MODEL: stripContextSuffix(selectedModel), ANTHROPIC_DEFAULT_OPUS_MODEL: stripContextSuffix(selectedModel), ...attributionHeaderEnvForModel(selectedModel), + ...(needsProxy && { [PROVIDER_PROXIED_ENV_KEY]: '1' }), } } diff --git a/src/server/services/providerService.ts b/src/server/services/providerService.ts index 9e35917c..37cc329d 100644 --- a/src/server/services/providerService.ts +++ b/src/server/services/providerService.ts @@ -128,9 +128,12 @@ export class ProviderService { models: normalizeProviderModels(input.models), ...(input.fastModel !== undefined && { fastModel: input.fastModel }), ...(input.modelContextWindows !== undefined && { modelContextWindows: input.modelContextWindows }), + ...(input.extraHeaders !== undefined && { extraHeaders: input.extraHeaders }), + ...(input.queryParams !== undefined && { queryParams: input.queryParams }), ...(input.notes !== undefined && { notes: input.notes }), } this.assertFastModel(provider) + this.assertRequestOptions(provider) index.providers.push(provider) await this.writeIndex(index) @@ -154,15 +157,20 @@ export class ProviderService { ...(input.models !== undefined && { models: normalizeProviderModels(input.models) }), ...(typeof input.fastModel === 'string' && { fastModel: input.fastModel }), ...(input.modelContextWindows !== undefined && input.modelContextWindows !== null && { modelContextWindows: input.modelContextWindows }), + ...(input.extraHeaders != null && { extraHeaders: input.extraHeaders }), + ...(input.queryParams != null && { queryParams: input.queryParams }), ...(input.notes !== undefined && { notes: input.notes }), } if (input.modelContextWindows === null) { delete updated.modelContextWindows } + if (input.extraHeaders === null) delete updated.extraHeaders + if (input.queryParams === null) delete updated.queryParams if (input.fastModel === null || (input.fastModel === undefined && input.models !== undefined && !updated.models.some((model) => model.id === updated.fastModel))) { delete updated.fastModel } this.assertFastModel(updated) + this.assertRequestOptions(updated) index.providers[idx] = updated await this.writeIndex(index) @@ -318,6 +326,14 @@ export class ProviderService { return result.models } + private assertRequestOptions(provider: SavedProvider): void { + const hasOptions = Object.keys(provider.extraHeaders ?? {}).length > 0 + || Object.keys(provider.queryParams ?? {}).length > 0 + if (hasOptions && provider.apiFormat === 'anthropic') { + throw ApiError.badRequest('Extra headers and query parameters only apply to OpenAI-format providers') + } + } + private assertFastModel(provider: SavedProvider): void { if (provider.fastModel && !provider.models.some((model) => model.id === provider.fastModel)) { throw ApiError.badRequest('Fast model must be one of the provider models') diff --git a/src/server/types/provider.ts b/src/server/types/provider.ts index 461062a5..18e70e99 100644 --- a/src/server/types/provider.ts +++ b/src/server/types/provider.ts @@ -44,6 +44,8 @@ export const ModelContextWindowsSchema = z.record( ModelContextWindowSchema, ) +export const ProviderStringMapSchema = z.record(z.string(), z.string()) + export const SavedProviderSchema = z.object({ id: z.string(), presetId: z.string(), @@ -56,6 +58,8 @@ export const SavedProviderSchema = z.object({ models: ProviderModelsSchema.min(1), fastModel: z.string().trim().min(1).optional(), modelContextWindows: ModelContextWindowsSchema.optional(), + extraHeaders: ProviderStringMapSchema.optional(), + queryParams: ProviderStringMapSchema.optional(), notes: z.string().optional(), }) @@ -76,6 +80,8 @@ export const CreateProviderSchema = z.object({ models: ProviderModelsSchema.min(1), fastModel: z.string().trim().min(1).optional(), modelContextWindows: ModelContextWindowsSchema.optional(), + extraHeaders: ProviderStringMapSchema.optional(), + queryParams: ProviderStringMapSchema.optional(), notes: z.string().optional(), }) @@ -89,6 +95,8 @@ export const UpdateProviderSchema = z.object({ models: ProviderModelsSchema.min(1).optional(), fastModel: z.string().trim().min(1).nullable().optional(), modelContextWindows: ModelContextWindowsSchema.nullable().optional(), + extraHeaders: ProviderStringMapSchema.nullable().optional(), + queryParams: ProviderStringMapSchema.nullable().optional(), notes: z.string().optional(), }) diff --git a/src/server/upstream/anthropicStream.ts b/src/server/upstream/anthropicStream.ts new file mode 100644 index 00000000..b1fc377a --- /dev/null +++ b/src/server/upstream/anthropicStream.ts @@ -0,0 +1,84 @@ +import { parseSseJson, SseDecoder, type SseMessage } from '../proxy/streaming/sse.js' +import type { UpstreamOutcome } from './requestLog.js' + +export function superviseAnthropicStream( + stream: ReadableStream, + idleTimeoutMs: number, + onEnd: (outcome: UpstreamOutcome) => void, +): ReadableStream { + const reader = stream.getReader() + const sse = new SseDecoder() + const encoder = new TextEncoder() + let timer: ReturnType | undefined + let streamError: string | undefined + let stopped = false + let ended = false + + const finish = (outcome: UpstreamOutcome): boolean => { + if (ended) return false + ended = true + clearTimeout(timer) + onEnd(outcome) + return true + } + const observe = (messages: SseMessage[]): boolean => { + let active = false + for (const message of messages) { + if (message.type !== 'event' || message.event === 'ping') continue + active = true + if (message.event === 'message_stop') stopped = true + if (message.event === 'error') streamError ??= readErrorMessage(message.data) + } + return active + } + + return new ReadableStream({ + async start(controller) { + const arm = () => { + clearTimeout(timer) + timer = setTimeout(() => { + const message = `No response from the provider for ${Math.round(idleTimeoutMs / 1000)}s` + if (!finish({ outcome: 'idle_timeout', error: message })) return + controller.enqueue(encoder.encode(`event: error\ndata: ${JSON.stringify({ + type: 'error', + error: { type: 'api_error', message }, + })}\n\n`)) + controller.close() + reader.cancel(new DOMException('Stream idle timeout', 'TimeoutError')).catch((err: unknown) => { + console.error('[Upstream] Cancelling the provider stream after an idle timeout failed:', err) + }) + }, idleTimeoutMs) + } + + arm() + try { + while (true) { + const { done, value } = await reader.read() + if (ended) return + if (done) break + if (observe(sse.push(value))) arm() + controller.enqueue(value) + } + observe(sse.flush()) + finish(streamError + ? { outcome: 'error', error: streamError } + : { outcome: stopped ? 'completed' : 'incomplete' }) + controller.close() + } catch (err) { + if (finish({ outcome: 'error', error: err instanceof Error ? err.message : String(err) })) { + controller.error(err) + } + } + }, + cancel(reason) { + finish({ outcome: 'client_disconnected' }) + return reader.cancel(reason) + }, + }) +} + +function readErrorMessage(data: string): string { + const parsed = parseSseJson(data) as { error?: { message?: unknown } } | undefined + const message = parsed?.error?.message + return typeof message === 'string' && message ? message : 'Upstream stream error' +} diff --git a/src/server/upstream/baseUrl.ts b/src/server/upstream/baseUrl.ts index b15a3c5a..391cb76a 100644 --- a/src/server/upstream/baseUrl.ts +++ b/src/server/upstream/baseUrl.ts @@ -1,3 +1,14 @@ +const VERSION_SEGMENT = /^v\d+[a-z0-9]*$/i + export function normalizeUpstreamBaseUrl(baseUrl: string): string { return baseUrl.trim().replace(/\/+$/, '').replace(/\/v1$/i, '') } + +export function openaiUpstreamBaseUrl(baseUrl: string): string { + const trimmed = baseUrl.trim().replace(/\/+$/, '') + const segments = trimmed.split('/') + const last = segments.at(-1) ?? '' + const endsInVersion = VERSION_SEGMENT.test(last) + || (last.toLowerCase() === 'openai' && VERSION_SEGMENT.test(segments.at(-2) ?? '')) + return endsInVersion ? trimmed : `${trimmed}/v1` +} diff --git a/src/server/upstream/client.ts b/src/server/upstream/client.ts index 9429f1ff..b138e4f6 100644 --- a/src/server/upstream/client.ts +++ b/src/server/upstream/client.ts @@ -12,7 +12,7 @@ import type { OpenAIChatResponse, OpenAIResponsesResponse, } from '../proxy/transform/types.js' -import { getManualNetworkProxyUrl, loadNetworkSettings } from '../services/networkSettings.js' +import { getManualNetworkProxyUrl, loadNetworkSettings, type NetworkSettings } from '../services/networkSettings.js' import { getPresetAuthStrategy, getPresetDefaultEnv, @@ -20,14 +20,24 @@ import { stripContextSuffix, } from '../services/providerRuntimeEnv.js' import type { ApiFormat, ProviderAuthStrategy, DiscoveredProviderModel, SavedProvider } from '../types/provider.js' -import { normalizeUpstreamBaseUrl } from './baseUrl.js' +import { normalizeUpstreamBaseUrl, openaiUpstreamBaseUrl } from './baseUrl.js' import { fillContextWindows } from './contextWindows/index.js' +import { superviseAnthropicStream } from './anthropicStream.js' +import { + recordUpstreamRequest, + type UpstreamOutcome, + type UpstreamRequestInfo, + type UpstreamResponseInfo, +} from './requestLog.js' export type UpstreamTarget = { + providerId?: string baseUrl: string apiKey: string apiFormat: ApiFormat authStrategy: ProviderAuthStrategy + extraHeaders?: Record + queryParams?: Record } export type UpstreamResult = @@ -47,32 +57,83 @@ type UpstreamRequest = { export function resolveUpstreamTarget(provider: SavedProvider): UpstreamTarget { return { + providerId: provider.id, baseUrl: provider.baseUrl, apiKey: resolveProviderApiKey(provider, getPresetDefaultEnv(provider.presetId)), apiFormat: provider.apiFormat ?? 'anthropic', authStrategy: provider.authStrategy ?? getPresetAuthStrategy(provider.presetId), + ...(provider.extraHeaders && { extraHeaders: provider.extraHeaders }), + ...(provider.queryParams && { queryParams: provider.queryParams }), } } +type SendOptions = { timeoutMs?: number; signal?: AbortSignal; sessionId?: string } +type RequestContext = { + networkSettings: NetworkSettings + timeoutMs: number + startedAt: number + signal?: AbortSignal + sessionId?: string +} + export async function sendToUpstream( target: UpstreamTarget, request: AnthropicRequest, - options?: { timeoutMs?: number }, + options?: SendOptions, ): Promise { + const anthropicRequest = { ...request, model: stripContextSuffix(request.model) } + const info: UpstreamRequestInfo = { + providerId: target.providerId, + model: anthropicRequest.model, + baseUrl: target.baseUrl, + apiFormat: target.apiFormat, + stream: request.stream === true, + startedAt: Date.now(), + } const networkSettings = await loadNetworkSettings() const timeoutMs = options?.timeoutMs ?? networkSettings.aiRequestTimeoutMs - const isStream = request.stream === true - const anthropicRequest = { ...request, model: stripContextSuffix(request.model) } - const upstreamRequest = buildUpstreamRequest(target, anthropicRequest) + const response: UpstreamResponseInfo = {} + const result = await requestUpstream(target, anthropicRequest, response, { + networkSettings, + timeoutMs, + startedAt: info.startedAt, + signal: options?.signal, + sessionId: options?.sessionId, + }) + const record = (outcome: UpstreamOutcome) => recordUpstreamRequest( + info, + response, + outcome.outcome === 'error' && options?.signal?.aborted ? { outcome: 'client_disconnected' } : outcome, + ) + + if (!result.ok) { + record({ outcome: options?.signal?.aborted ? 'client_aborted' : 'error', error: result.error }) + return result + } + if ('stream' in result) { + return { ...result, stream: superviseAnthropicStream(result.stream, timeoutMs, record) } + } + record({ outcome: 'completed' }) + return result +} + +async function requestUpstream( + target: UpstreamTarget, + anthropicRequest: AnthropicRequest, + responseInfo: UpstreamResponseInfo, + { networkSettings, timeoutMs, startedAt, signal, sessionId }: RequestContext, +): Promise { + const isStream = anthropicRequest.stream === true let response: Response try { + const upstreamRequest = buildUpstreamRequest(target, anthropicRequest, sessionId) response = await fetchWithTimeout(upstreamRequest.url, { method: 'POST', headers: upstreamRequest.headers, body: upstreamRequest.body, ...getProxyFetchOptions({ proxyUrl: getManualNetworkProxyUrl(networkSettings) }), - }, timeoutMs, isStream) + }, timeoutMs, isStream, signal) } catch (err) { if (err instanceof DOMException && err.name === 'TimeoutError') { return { ok: false, error: `Request timed out (${Math.round(timeoutMs / 1000)}s)` } @@ -80,6 +141,10 @@ export async function sendToUpstream( return { ok: false, error: err instanceof Error ? err.message : String(err) } } + responseInfo.status = response.status + responseInfo.requestId = response.headers.get('x-request-id') ?? response.headers.get('request-id') ?? undefined + responseInfo.headersMs = Date.now() - startedAt + if (!response.ok) { const errText = await response.text().catch(() => '') return { @@ -118,13 +183,15 @@ export async function sendToUpstream( export async function fetchUpstreamModels(target: UpstreamTarget, presetId?: string): Promise { const networkSettings = await loadNetworkSettings() - const base = normalizeUpstreamBaseUrl(target.baseUrl) + const modelsUrl = target.apiFormat === 'anthropic' + ? `${normalizeUpstreamBaseUrl(target.baseUrl)}/v1/models` + : withQueryParams(`${openaiUpstreamBaseUrl(target.baseUrl)}/models`, target.queryParams) const headers = target.apiFormat === 'anthropic' ? { 'anthropic-version': '2023-06-01', ...buildAnthropicAuthHeaders(target.apiKey, target.authStrategy), } - : { Authorization: `Bearer ${target.apiKey}` } + : mergeHeaders(target.extraHeaders, { Authorization: `Bearer ${target.apiKey}` }) const seen = new Set() const models: DiscoveredProviderModel[] = [] @@ -133,7 +200,7 @@ export async function fetchUpstreamModels(target: UpstreamTarget, presetId?: str let afterId = '' for (let page = 0; page < maxPages; page += 1) { - const url = new URL(`${base}/v1/models`) + const url = new URL(modelsUrl) if (target.apiFormat === 'anthropic') { url.searchParams.set('limit', '1000') if (afterId) url.searchParams.set('after_id', afterId) @@ -199,32 +266,31 @@ export async function fetchUpstreamModels(target: UpstreamTarget, presetId?: str return { ok: false, httpStatus: 502, error: `Upstream model pagination exceeded ${maxPages} pages` } } -function buildUpstreamRequest(target: UpstreamTarget, request: AnthropicRequest): UpstreamRequest { - const base = normalizeUpstreamBaseUrl(target.baseUrl) - +function buildUpstreamRequest(target: UpstreamTarget, request: AnthropicRequest, sessionId?: string): UpstreamRequest { if (target.apiFormat === 'openai_chat') { + const base = openaiUpstreamBaseUrl(target.baseUrl) const compat = shouldUseDeepSeekReasoningCompat(base) const transformed = anthropicToOpenaiChat(request, { roundTripReasoningContent: compat, passThinkingToggle: compat, }) return { - url: `${base}/v1/chat/completions`, - headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${target.apiKey}` }, + url: withQueryParams(`${base}/chat/completions`, target.queryParams), + headers: openaiHeaders(target), body: signClaudeCodeCCHInTransformedString(JSON.stringify(transformed)), } } if (target.apiFormat === 'openai_responses') { return { - url: `${base}/v1/responses`, - headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${target.apiKey}` }, - body: signClaudeCodeCCHInTransformedString(JSON.stringify(anthropicToOpenaiResponses(request))), + url: withQueryParams(`${openaiUpstreamBaseUrl(target.baseUrl)}/responses`, target.queryParams), + headers: openaiHeaders(target), + body: signClaudeCodeCCHInTransformedString(JSON.stringify(anthropicToOpenaiResponses(request, { promptCacheKey: sessionId }))), } } return { - url: `${base}/v1/messages`, + url: `${normalizeUpstreamBaseUrl(target.baseUrl)}/v1/messages`, headers: { 'Content-Type': 'application/json', 'anthropic-version': '2023-06-01', @@ -234,6 +300,29 @@ function buildUpstreamRequest(target: UpstreamTarget, request: AnthropicRequest) } } +function openaiHeaders(target: UpstreamTarget): Record { + return mergeHeaders(target.extraHeaders, { + 'Content-Type': 'application/json', + Authorization: `Bearer ${target.apiKey}`, + }) +} + +function mergeHeaders( + configured: Record | undefined, + own: Record, +): Record { + const ownNames = new Set(Object.keys(own).map((name) => name.toLowerCase())) + const kept = Object.entries(configured ?? {}).filter(([name]) => !ownNames.has(name.toLowerCase())) + return { ...Object.fromEntries(kept), ...own } +} + +function withQueryParams(url: string, queryParams: Record | undefined): string { + if (!queryParams || Object.keys(queryParams).length === 0) return url + const parsed = new URL(url) + for (const [name, value] of Object.entries(queryParams)) parsed.searchParams.set(name, value) + return parsed.toString() +} + function buildAnthropicAuthHeaders(apiKey: string, authStrategy: ProviderAuthStrategy): Record { switch (authStrategy) { case 'api_key': @@ -260,9 +349,12 @@ async function fetchWithTimeout( init: RequestInit, timeoutMs: number, isStream: boolean, + callerSignal?: AbortSignal, ): Promise { + const withCaller = (signal: AbortSignal) => callerSignal ? AbortSignal.any([callerSignal, signal]) : signal + if (!isStream) { - return fetch(url, { ...init, signal: AbortSignal.timeout(timeoutMs) }) + return fetch(url, { ...init, signal: withCaller(AbortSignal.timeout(timeoutMs)) }) } const controller = new AbortController() @@ -270,7 +362,7 @@ async function fetchWithTimeout( controller.abort(new DOMException('The operation timed out.', 'TimeoutError')) }, timeoutMs) try { - return await fetch(url, { ...init, signal: controller.signal }) + return await fetch(url, { ...init, signal: withCaller(controller.signal) }) } finally { clearTimeout(timer) } diff --git a/src/server/upstream/requestLog.ts b/src/server/upstream/requestLog.ts new file mode 100644 index 00000000..769bd40d --- /dev/null +++ b/src/server/upstream/requestLog.ts @@ -0,0 +1,56 @@ +import { diagnosticsService } from '../services/diagnosticsService.js' +import type { ApiFormat } from '../types/provider.js' + +export type UpstreamRequestInfo = { + providerId?: string + model: string + baseUrl: string + apiFormat: ApiFormat + stream: boolean + startedAt: number +} + +export type UpstreamOutcome = { + outcome: 'completed' | 'incomplete' | 'error' | 'idle_timeout' | 'client_aborted' | 'client_disconnected' + error?: string +} + +export type UpstreamResponseInfo = { + status?: number + requestId?: string + headersMs?: number +} + +export function recordUpstreamRequest( + info: UpstreamRequestInfo, + response: UpstreamResponseInfo, + { outcome, error }: UpstreamOutcome, +): void { + const failed = outcome === 'error' || outcome === 'incomplete' || outcome === 'idle_timeout' + void diagnosticsService.recordEvent({ + type: 'upstream_request', + severity: failed ? 'warn' : 'info', + summary: `${info.apiFormat} ${info.model}: ${outcome}${response.status ? ` (HTTP ${response.status})` : ''}`, + details: { + providerId: info.providerId, + model: info.model, + host: hostOf(info.baseUrl), + apiFormat: info.apiFormat, + stream: info.stream, + status: response.status, + requestId: response.requestId, + headersMs: response.headersMs, + durationMs: Date.now() - info.startedAt, + outcome, + error, + }, + }) +} + +function hostOf(baseUrl: string): string | undefined { + try { + return new URL(baseUrl).host + } catch { + return undefined + } +} diff --git a/src/utils/__tests__/analyzeContext.test.ts b/src/utils/__tests__/analyzeContext.test.ts index 8f6b0b0a..6dc6848f 100644 --- a/src/utils/__tests__/analyzeContext.test.ts +++ b/src/utils/__tests__/analyzeContext.test.ts @@ -1,12 +1,14 @@ -import { describe, expect, test } from 'bun:test' +import { afterEach, describe, expect, spyOn, test } from 'bun:test' import type { AssistantMessage, AttachmentMessage, UserMessage, } from '../../types/message.js' +import * as tokenEstimation from '../../services/tokenEstimation.js' import { roughTokenCountEstimation } from '../../services/tokenEstimation.js' import { jsonStringify } from '../slowOperations.js' import { + countToolDefinitionTokens, estimateTokensForContextMessages, processAssistantMessage, processAttachment, @@ -245,3 +247,38 @@ describe('processAttachment', () => { ) }) }) + +describe('counting context through the local proxy', () => { + const originalProxied = process.env.DREAMCODER_PROVIDER_PROXIED + const spies: Array<{ mockRestore: () => void }> = [] + + afterEach(() => { + for (const spy of spies.splice(0)) spy.mockRestore() + if (originalProxied === undefined) delete process.env.DREAMCODER_PROVIDER_PROXIED + else process.env.DREAMCODER_PROVIDER_PROXIED = originalProxied + }) + + test('uses the local estimate instead of a Haiku request when the provider goes through the proxy', async () => { + process.env.DREAMCODER_PROVIDER_PROXIED = '1' + const apiCount = spyOn(tokenEstimation, 'countMessagesTokensWithAPI').mockResolvedValue(null) + const haiku = spyOn(tokenEstimation, 'countTokensViaHaikuFallback').mockResolvedValue(42) + spies.push(apiCount, haiku) + + const tokens = await countToolDefinitionTokens([], async () => { throw new Error('unused') }, null) + + expect(haiku).not.toHaveBeenCalled() + expect(tokens).toBe(estimateTokensForContextMessages([], [])) + }) + + test('still falls back to Haiku for providers reached directly', async () => { + delete process.env.DREAMCODER_PROVIDER_PROXIED + const apiCount = spyOn(tokenEstimation, 'countMessagesTokensWithAPI').mockResolvedValue(null) + const haiku = spyOn(tokenEstimation, 'countTokensViaHaikuFallback').mockResolvedValue(42) + spies.push(apiCount, haiku) + + const tokens = await countToolDefinitionTokens([], async () => { throw new Error('unused') }, null) + + expect(haiku).toHaveBeenCalledTimes(1) + expect(tokens).toBe(42) + }) +}) diff --git a/src/utils/__tests__/providerManagedEnvCompat.test.ts b/src/utils/__tests__/providerManagedEnvCompat.test.ts index 673d3a7b..a4686dfd 100644 --- a/src/utils/__tests__/providerManagedEnvCompat.test.ts +++ b/src/utils/__tests__/providerManagedEnvCompat.test.ts @@ -41,4 +41,8 @@ describe('provider managed env compatibility', () => { test('treats attribution header routing as provider-managed env', () => { expect(isProviderManagedEnvVar('CLAUDE_CODE_ATTRIBUTION_HEADER')).toBe(true) }) + + test('treats the local proxy marker as provider-managed env', () => { + expect(isProviderManagedEnvVar('DREAMCODER_PROVIDER_PROXIED')).toBe(true) + }) }) diff --git a/src/utils/analyzeContext.ts b/src/utils/analyzeContext.ts index b8637a3c..11fad64c 100644 --- a/src/utils/analyzeContext.ts +++ b/src/utils/analyzeContext.ts @@ -61,6 +61,7 @@ import { errorMessage, toError } from './errors.js' import { logError } from './log.js' import { normalizeMessagesForAPI } from './messages.js' import { getRuntimeMainLoopModel } from './model/model.js' +import { isProviderProxied } from './providerProxy.js' import type { SettingSource } from './settings/constants.js' import { jsonStringify } from './slowOperations.js' import { buildEffectiveSystemPrompt } from './systemPrompt.js' @@ -109,6 +110,9 @@ async function countTokensWithFallback( if (result !== null) { return result } + if (isProviderProxied()) { + return estimateTokensForContextMessages(messages, tools) + } logForDebugging( `countTokensWithFallback: API returned null, trying haiku fallback (${tools.length} tools)`, ) diff --git a/src/utils/managedEnvConstants.ts b/src/utils/managedEnvConstants.ts index 622b36e1..c2e014a0 100644 --- a/src/utils/managedEnvConstants.ts +++ b/src/utils/managedEnvConstants.ts @@ -1,3 +1,5 @@ +import { PROVIDER_PROXIED_ENV_KEY } from './providerProxy.js' + /** * Environment variables that control inference routing: which provider to use, * which endpoint to hit, and which model IDs to send. @@ -43,6 +45,7 @@ const PROVIDER_MANAGED_ENV_VARS = new Set([ 'CLAUDE_CODE_SKIP_AZURE_OPENAI_AUTH', 'DREAMCODER_OPENAI_OAUTH_PROVIDER', 'OPENAI_CODEX_OAUTH_FILE', + PROVIDER_PROXIED_ENV_KEY, // Model defaults — often set to provider-specific ID formats 'ANTHROPIC_MODEL', 'ANTHROPIC_DEFAULT_HAIKU_MODEL', diff --git a/src/utils/providerProxy.ts b/src/utils/providerProxy.ts new file mode 100644 index 00000000..3a4c2b43 --- /dev/null +++ b/src/utils/providerProxy.ts @@ -0,0 +1,7 @@ +import { isEnvTruthy } from './envUtils.js' + +export const PROVIDER_PROXIED_ENV_KEY = 'DREAMCODER_PROVIDER_PROXIED' + +export function isProviderProxied(): boolean { + return isEnvTruthy(process.env[PROVIDER_PROXIED_ENV_KEY]) +} From cee1b1e54449dac8a31df420d383c75e76081c5c Mon Sep 17 00:00:00 2001 From: Diao Shengjia <104132148+GoDiao@users.noreply.github.com> Date: Wed, 18 Nov 2026 18:28:38 +0800 Subject: [PATCH 4/4] fix(harness): recover from provider errors, broken streams and context overflow - Retry a stream that breaks mid-reply by opening a new stream, sharing one budget with request retries; no non-streaming fallback. The partial reply is retracted from history, the transcript and connected clients. - The proxy parses provider errors into Anthropic error types, passes retry-after and request ids through, and marks quota and auth failures as not retryable; the CLI classifies them with the same table. - Context overflow from OpenAI-format providers is recognised as prompt-too-long so reactive compaction runs. - Truncated tool arguments are refused with an explanation to the model instead of running the tool with an empty input. Part of #263 --- CHANGELOG.md | 10 +- desktop/src/stores/chatStore.test.ts | 56 + desktop/src/stores/chatStore.ts | 27 + docs/features/harness/README.md | 5 +- .../harness/comparison/loop-execution.md | 2 +- docs/features/harness/proxy/request.md | 8 +- docs/features/harness/proxy/response.md | 8 + docs/features/harness/proxy/transport.md | 3 + docs/features/session-state/tech-design.md | 13 +- src/QueryEngine.ts | 29 +- src/__tests__/queryEngineRetraction.test.ts | 93 + src/entrypoints/sdk/coreSchemas.ts | 14 + src/query.ts | 1 + .../__tests__/conversation-service.test.ts | 1 + .../__tests__/cron-scheduler-launcher.test.ts | 2 + src/server/__tests__/network-settings.test.ts | 1 + src/server/__tests__/providers.test.ts | 70 +- src/server/__tests__/proxy-streaming.test.ts | 285 ++- src/server/__tests__/proxy-transform.test.ts | 37 +- .../__tests__/stream-retraction.test.ts | 34 + src/server/__tests__/upstream-client.test.ts | 108 +- src/server/proxy/handler.ts | 7 +- .../streaming/openaiChatStreamToAnthropic.ts | 162 +- .../openaiResponsesStreamToAnthropic.ts | 394 ++--- ...penaiResponsesStreamToAnthropicResponse.ts | 11 +- .../proxy/transform/openaiChatToAnthropic.ts | 55 +- .../transform/openaiResponsesToAnthropic.ts | 26 +- src/server/proxy/transform/toolArguments.ts | 21 +- src/server/proxy/transform/types.ts | 25 +- src/server/services/networkSettings.ts | 1 + src/server/services/providerService.ts | 5 +- src/server/services/titleService.ts | 3 +- src/server/session/translate.ts | 9 + src/server/upstream/anthropicStream.ts | 6 +- src/server/upstream/client.ts | 30 +- src/server/upstream/upstreamError.ts | 150 ++ src/server/ws/protocol.ts | 1 + .../api/__tests__/contextOverflow.test.ts | 70 + .../api/__tests__/providerRetry.test.ts | 95 + .../api/__tests__/streamRetry.test.ts | 218 +++ src/services/api/claude.ts | 1544 +++++++++-------- src/services/api/errors.ts | 22 +- src/services/api/withRetry.ts | 41 +- src/services/compact/autoCompact.test.ts | 40 +- src/services/openaiAuth/fetch.test.ts | 33 + src/services/openaiAuth/fetch.ts | 36 +- .../__tests__/truncatedToolArguments.test.ts | 101 ++ src/services/tools/toolExecution.ts | 24 + src/utils/invalidToolArguments.ts | 32 + src/utils/messages.ts | 19 +- src/utils/providerErrors.ts | 88 + src/utils/tokens.ts | 3 +- 52 files changed, 2868 insertions(+), 1211 deletions(-) create mode 100644 src/__tests__/queryEngineRetraction.test.ts create mode 100644 src/server/__tests__/stream-retraction.test.ts create mode 100644 src/server/upstream/upstreamError.ts create mode 100644 src/services/api/__tests__/contextOverflow.test.ts create mode 100644 src/services/api/__tests__/providerRetry.test.ts create mode 100644 src/services/api/__tests__/streamRetry.test.ts create mode 100644 src/services/tools/__tests__/truncatedToolArguments.test.ts create mode 100644 src/utils/invalidToolArguments.ts create mode 100644 src/utils/providerErrors.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 752a924a..3d527c1e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,7 +14,7 @@ All notable changes to DreamCoder will be documented in this file. - **Providers in OpenAI format reuse their prompt cache.** Later turns of a session now hit the cache for about 99% of the input (measured on OpenRouter with GPT-4.1 mini and GLM-4.6), and cache hits that DeepSeek and Moonshot report are counted as cache reads (#262). - Providers in OpenAI format can run several tool calls in one step and get tool definitions without schema fields they do not use, and replies show the model you chose instead of the dated version the provider reports (#262). - Every request the app itself sends to a provider (through the local proxy, for session titles and for connection tests) is recorded in the diagnostics log with the provider, model, status, timings, the provider's request id and how it ended, including errors in the middle of a stream and clients that disconnect; never the key or the request body (#262). -- **A stalled reply ends after the AI request timeout.** When a provider stops sending anything for longer than the timeout in the network settings, the agent gives up on that reply and asks again without streaming, instead of waiting until you stop it. This now applies to every provider, whether it is reached directly or through the local proxy; keep-alive signals alone do not count as progress (#262). +- **A stalled reply ends after the AI request timeout.** When a provider stops sending anything for longer than the timeout in the network settings, the agent gives up on that reply and starts it again, instead of waiting until you stop it. This now applies to every provider, whether it is reached directly or through the local proxy; keep-alive signals alone do not count as progress (#262). - Providers in OpenAI format can carry extra request headers and query parameters, such as Azure's `api-version`. The settings form does not offer them yet; for now they are set by editing the provider in `providers.json`. Authentication and the content type still come from the provider settings and override a header of the same name (#262). ### Fixed @@ -24,6 +24,14 @@ All notable changes to DreamCoder will be documented in this file. - With a manual HTTP proxy set in the network settings, the agent reaches the app's local proxy directly instead of sending those requests to the HTTP proxy (#262). - Replies from some providers no longer come back empty; the provider's error message is shown instead (#262). - `/context` in the terminal no longer sends a request to the model for each part of the context when the provider is reached through the local proxy; it uses the local estimate (#262). +- **A session that outgrows a third-party model's context can be compacted again.** Context overflow errors from OpenAI, OpenRouter, DashScope, Moonshot, Zhipu and Gemini are recognized as "Prompt is too long", so `/compact` drops the oldest turns and succeeds instead of failing the same way (#263). +- Auto-compaction also triggers for providers that do not report token usage; the agent estimates the context itself instead of counting it as empty (#263). +- Errors from providers in OpenAI format show the provider's own message, such as the reason for a 429, instead of a cut-off JSON fragment, and the agent waits as long as the provider's `retry-after` asks before trying again (#263). +- A reply that the provider stops with its content filter or because of an error on its side, a stream that closes before the reply is complete, and a reply with no content now show an error instead of looking finished (#263). +- Replies from providers in OpenAI format no longer lose text when one chunk carries reasoning, text and a tool call together, and Responses-format replies keep text and tool arguments that only arrive in completed events (#263). +- **A wrong API key or an empty balance is reported at once.** For providers that use an API key, the agent no longer retries authentication failures and quota or balance errors for minutes before showing them; it shows the provider's message right away (#263). +- When the output limit cuts off a tool call in the middle of its arguments, the agent no longer runs the tool with missing arguments; the model is told the call was cut off and retries with smaller pieces (#263). +- **A reply that breaks off in the middle is retried as a stream.** When a provider's stream fails partway, the agent removes the half-finished reply from the conversation, the app and the session history, and asks again with streaming, instead of switching to a slower request without streaming that long answers could not finish within the timeout. Retries before and during a stream share one limit (#263). ## [0.9.0] — 2026-11-17 diff --git a/desktop/src/stores/chatStore.test.ts b/desktop/src/stores/chatStore.test.ts index 598a163f..54dab760 100644 --- a/desktop/src/stores/chatStore.test.ts +++ b/desktop/src/stores/chatStore.test.ts @@ -526,6 +526,62 @@ describe('chatStore history mapping', () => { vi.useRealTimers() }) + it('drops what a retried reply already streamed and keeps the earlier turn', () => { + vi.useFakeTimers() + const earlier: UIMessage[] = [ + { id: 'u1', type: 'user_text', content: 'do it', timestamp: 1 }, + { id: 'a1', type: 'assistant_text', content: 'Reading the file.', transcriptMessageId: 'cli-a1', timestamp: 2 }, + { id: 't1', type: 'tool_use', toolName: 'Read', toolUseId: 'toolu_read', input: {}, timestamp: 3 }, + { id: 'r1', type: 'tool_result', toolUseId: 'toolu_read', content: 'file', isError: false, timestamp: 4 }, + ] + useChatStore.setState({ sessions: { [TEST_SESSION_ID]: makeSession({ messages: earlier, chatState: 'streaming' }) } }) + const send = (msg: Parameters['handleServerMessage']>[1]) => + useChatStore.getState().handleServerMessage(TEST_SESSION_ID, msg) + + send({ type: 'thinking', text: 'planning' }) + send({ type: 'content_start', blockType: 'text' }) + send({ type: 'content_delta', text: 'Now I write' }) + send({ type: 'message_id', id: 'cli-a2' }) + send({ type: 'content_start', blockType: 'tool_use', toolName: 'Write', toolUseId: 'toolu_write' }) + send({ type: 'content_delta', toolInput: '{"file_pa' }) + send({ type: 'content_start', blockType: 'tool_use', toolName: 'Grep', toolUseId: 'toolu_sub', parentToolUseId: 'toolu_agent' }) + send({ type: 'tool_use_complete', toolName: 'Grep', toolUseId: 'toolu_sub', input: { pattern: 'x' }, parentToolUseId: 'toolu_agent' }) + send({ type: 'content_start', blockType: 'text' }) + send({ type: 'content_delta', text: 'half a sen' }) + send({ type: 'content_start', blockType: 'tool_use', toolName: 'Edit', toolUseId: 'toolu_edit' }) + send({ type: 'content_delta', toolInput: '{"old_str' }) + vi.runOnlyPendingTimers() + send({ type: 'thinking', text: 'checking again' }) + vi.runOnlyPendingTimers() + send({ type: 'content_delta', text: 'and then' }) + vi.runOnlyPendingTimers() + expect(useChatStore.getState().sessions[TEST_SESSION_ID]).toMatchObject({ + activeToolUseId: 'toolu_edit', + activeToolName: 'Edit', + activeThinkingId: expect.any(String), + streamingText: 'and then', + streamingToolInput: '{"old_str', + }) + + send({ type: 'reply_retracted' }) + vi.runOnlyPendingTimers() + + const session = useChatStore.getState().sessions[TEST_SESSION_ID]! + expect(session.messages).toEqual([ + ...earlier, + expect.objectContaining({ type: 'tool_use', toolUseId: 'toolu_sub', parentToolUseId: 'toolu_agent' }), + ]) + expect(session).toMatchObject({ + chatState: 'thinking', + streamingText: '', + streamingToolInput: '', + activeToolUseId: null, + activeToolName: null, + activeThinkingId: null, + }) + vi.useRealTimers() + }) + it('builds on history and keeps only live messages history does not have yet', async () => { vi.mocked(sessionsApi.getTranscript).mockResolvedValueOnce(transcriptOf([ { id: 'u1', type: 'user_text', content: 'prompt', transcriptMessageId: 'u1', timestamp: 1 }, diff --git a/desktop/src/stores/chatStore.ts b/desktop/src/stores/chatStore.ts index 53a102ba..e9ae5c22 100644 --- a/desktop/src/stores/chatStore.ts +++ b/desktop/src/stores/chatStore.ts @@ -583,6 +583,18 @@ function mergeHistoryWithLiveMessages(history: UIMessage[], live: UIMessage[]): const liveStartBySession = new Map() +const STREAMED_REPLY_TYPES = new Set(['assistant_text', 'thinking', 'tool_use']) + +function dropRetractedReply(messages: UIMessage[]): UIMessage[] { + const replyStart = messages.findLastIndex((message) => message.type === 'user_text' || message.type === 'tool_result') + 1 + const kept = messages.filter((message, index) => + index < replyStart || + !STREAMED_REPLY_TYPES.has(message.type) || + (message.type === 'tool_use' && !!message.parentToolUseId), + ) + return kept.length === messages.length ? messages : kept +} + function tagLatestAssistantText(messages: UIMessage[], pendingText: string, id: string, timestamp: number): UIMessage[] { for (let index = messages.length - 1; index >= 0; index--) { const message = messages[index]! @@ -1347,6 +1359,21 @@ export const useChatStore = create((set, get) => ({ break } + case 'reply_retracted': + textDeltaBuffer.clear(sessionId) + thinkingDeltaBuffer.clear(sessionId) + toolInputDeltaBuffer.clear(sessionId) + update((s) => ({ + messages: dropRetractedReply(s.messages), + streamingText: '', + streamingToolInput: '', + activeThinkingId: null, + activeToolUseId: null, + activeToolName: null, + chatState: 'thinking', + })) + break + case 'api_retry': { const attempt = Math.max(1, Math.trunc(msg.attempt)) const maxRetries = Math.max(attempt, Math.trunc(msg.maxRetries)) diff --git a/docs/features/harness/README.md b/docs/features/harness/README.md index 73a64039..1dd39f9c 100644 --- a/docs/features/harness/README.md +++ b/docs/features/harness/README.md @@ -66,9 +66,9 @@ DreamCoder 的 CLI 派生自 Claude Code 2.1.92(`src/constants/claudeCodeCompa - 推理强度:CLI 对自定义提供方发 `thinking:{type:'adaptive'}`,代理只在带预算或类型为 `enabled` 时写 `reasoning_effort`(`src/server/proxy/transform/anthropicToOpenaiChat.ts:64-72`),桌面上选的 Effort 不起作用。 - 输出上限:`max_tokens` 不转发,实际用上游默认值。 -- 错误:上游错误统一包成 `api_error`,`retry-after` 丢失;CLI 针对 Anthropic 的错误识别(上下文过长、过载)对翻译后的错误不命中。 +- 错误:上游错误统一包成 `api_error`,`retry-after` 丢失;CLI 针对 Anthropic 的错误识别(上下文过长、过载)对翻译后的错误不命中。已在 #263 修复:代理解析上游错误并透传 `retry-after`,代理和 CLI 按同一张表分类(见 proxy/transport.md 的 P-NET-03、P-NET-04)。 - 推理内容:只对 DeepSeek 一类上游写回历史里的 `reasoning_content`,Kimi、GLM 的会丢。 -- 图片:工具结果里的图片被换成 `[image omitted]`(`src/server/proxy/transform/toolArguments.ts:38`)。 +- 图片:工具结果里的图片被换成 `[image omitted]`(`src/server/proxy/transform/toolArguments.ts:31`)。 - 工具调用:chat 流里没有 id 的工具调用整个被丢掉。 详见 [model-adaptation.md](comparison/model-adaptation.md)。 @@ -100,6 +100,7 @@ DreamCoder 的 CLI 派生自 Claude Code 2.1.92(`src/constants/claudeCodeCompa - 外部构建里没有「完成前先验证」的条文。 - 没有空响应重试和重复调用提醒(ZCode 有)。 - 不在内置表里的模型(如 GLM-5.3、Kimi-K3),上下文窗口按 200K 计。 +- 工具在一次模型回复读完之后才执行:`tengu_streaming_tool_execution2` 在 DreamCoder 里打不开(见 loop-execution.md)。 详见 [loop-execution.md](comparison/loop-execution.md)。 diff --git a/docs/features/harness/comparison/loop-execution.md b/docs/features/harness/comparison/loop-execution.md index dd229a2e..7a488b13 100644 --- a/docs/features/harness/comparison/loop-execution.md +++ b/docs/features/harness/comparison/loop-execution.md @@ -56,7 +56,7 @@ - Codex:`handle_output_item_done` 构造 future,`tokio::spawn` 执行(`codex:core/src/stream_events_utils.rs:~345-372`;`codex:core/src/tools/parallel.rs:201`);读写锁分配(`parallel.rs:213-217`);`exec_command` 声明可并行(`codex:core/src/tools/handlers/unified_exec/exec_command.rs:135`),apply_patch handler 默认不可并行(`codex:tools/src/tool_executor.rs:122`)。错误输出(`parallel.rs:338-384`;`codex:core/src/tools/registry.rs:963-966`)。exec 审批策略固定 Never(`codex:exec/src/lib.rs:591`),`request_user_input` 与文件变更审批被拒(`exec/src/lib.rs:2122-2143`);需要提权时返回「approval policy is Never; reject command — you cannot ask for escalated permissions ...」(`exec_command.rs:~330`)。 - ZCode:`ToolScheduler` 并发 10,判定规则(`zcode:core/src/tool/scheduler.ts:45, 90-185`);流中执行条件 `modelStreaming === "on"`(headless 为 on,`zcode:cli/src/prompt-command.ts:270`)且 `streamingToolExecution` 默认 `readOnly`(`runtime/methods/streaming-tool-coordinator.ts:383-406`);排序(`runtime/methods/turn-tools.ts:47-57`)。错误措辞与 DreamCoder 同一套(`tool/input-validation-model-content.ts:12-68`;`tool/executor/errors.ts:44-58`)。`zcode -p` 默认 yolo(`zcode:cli/src/run.ts:52`),但判为 ask 的调用经 deny broker 拒绝(`permission/broker.ts:22-37`;`permission/service.ts:121-150`;`prompt-command.ts:250-253`;`tool/executor/errors.ts:136-160`)。 -- DreamCoder:流式执行门 `tengu_streaming_tool_execution2`(`src/query/config.ts:33`),GrowthBook 无 clientKey 时关闭(`src/services/analytics/growthbook.ts:173, 422-427, 819-821`),所以由 `runTools` 在响应结束后执行(`src/query.ts:1368-1370`)。并发上限 `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` 默认 10(`src/services/tools/toolOrchestration.ts:8-112`)。错误类型(`src/services/tools/toolExecution.ts:402, 474-482, 671, 724`)。权限拒绝返回 is_error 的 tool_result(`toolExecution.ts:1030-1040`),文案见 `src/utils/messages.ts:217-241`。应用用 `--sdk-url` 强制 stdio 权限提示并转发服务器(`src/cli/print.ts:851-853, 4315-4317`);无人响应时是等待而不是自动拒绝(推断)。 +- DreamCoder:流式执行门 `tengu_streaming_tool_execution2`(`src/query/config.ts:33`),GrowthBook 无 clientKey 时关闭(`src/services/analytics/growthbook.ts:173, 422-427, 819-821`),所以由 `runTools` 在响应结束后执行(`src/query.ts:1369-1371`)。#263 的流式重试依赖这一点:读流中途出错时,失败那次的工具调用还没有执行,撤回后重来不会重复执行;以后要打开这个开关,必须先补上保护,已有工具开始执行时不再重试这次流。并发上限 `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` 默认 10(`src/services/tools/toolOrchestration.ts:8-112`)。错误类型(`src/services/tools/toolExecution.ts:402, 474-482, 671, 724`)。权限拒绝返回 is_error 的 tool_result(`toolExecution.ts:1030-1040`),文案见 `src/utils/messages.ts:217-241`。应用用 `--sdk-url` 强制 stdio 权限提示并转发服务器(`src/cli/print.ts:851-853, 4315-4317`);无人响应时是等待而不是自动拒绝(推断)。 ### 2.3 编辑文件 diff --git a/docs/features/harness/proxy/request.md b/docs/features/harness/proxy/request.md index 23525553..ed02df5d 100644 --- a/docs/features/harness/proxy/request.md +++ b/docs/features/harness/proxy/request.md @@ -52,7 +52,7 @@ - 严重程度:高 - 现状: 1. Read 工具读整份 PDF 时,tool_result 只写 `PDF file read: <路径> (<大小>)`(`src/tools/FileReadTool/FileReadTool.ts:670-676`),PDF 内容放在随后一条 meta user 消息的 `document` 块里(`FileReadTool.ts:997-1011`)。是否走这条路只看 `isPDFSupported()`,它只排除 `claude-3-haiku`(`src/utils/pdfUtils.ts:59-61`),对第三方模型都为真。 - 2. chat 转换 `convertUserMessage` 只处理 text、image、tool_result(`anthropicToOpenaiChat.ts:108-121`),`document` 块没有分支,被直接跳过;Responses 转换同样只处理 text、image、tool_use、tool_result(`anthropicToOpenaiResponses.ts:82-105`)。只有出现在 tool_result 内部时才会留下 `[omitted content: document]`(`src/server/proxy/transform/toolArguments.ts:43-44`)。 + 2. chat 转换 `convertUserMessage` 只处理 text、image、tool_result(`anthropicToOpenaiChat.ts:108-121`),`document` 块没有分支,被直接跳过;Responses 转换同样只处理 text、image、tool_use、tool_result(`anthropicToOpenaiResponses.ts:82-105`)。只有出现在 tool_result 内部时才会留下 `[omitted content: document]`(`src/server/proxy/transform/toolArguments.ts:36-37`)。 - 场景:Qwen 预设或任何自定义 OpenAI 格式提供方,用户让模型「读一下 spec.pdf 并总结」。模型调用 Read,收到「PDF file read: spec.pdf (120KB)」,后面没有任何内容,也没有提示内容缺失;模型据此编造总结,或认为已读而不再尝试 `pages` 参数(该参数会把页面转成图片,见 `FileReadTool.ts:886-944`)。 - 参考:ZCode 对 file 块:模型声明支持 PDF 时作为 SDK file part 发送,不支持时换成明确的「不支持该媒体」文本(`zcode:apps/zcode-cli/packages/adapters/src/model/transform.ts:540-563`;`zcode:apps/zcode-cli/packages/adapters/src/model/media-transform-policy.ts:8-15`;基线规则 `supportsPdf:false`,`modelRules[0]`)。Codex:无 PDF 读取。 - 改法方向:代理对 `document` 块不再静默跳过:模型支持 PDF 输入时转成 chat 的 file 内容块 / Responses 的 `input_file`,否则换成一段明确文本(说明 PDF 未送达、可用 `pages` 参数按页读取);或由服务端告知 CLI 当前提供方不支持 PDF,让 `isPDFSupported` 为假。 @@ -62,7 +62,7 @@ - 类型:问题 - 严重程度:高 -- 现状:tool_result 的内容块经 `extractToolResultContent` 拍平成字符串,图片变成 `[image omitted: ]`(`toolArguments.ts:29-38`),chat(`anthropicToOpenaiChat.ts:114-120`)和 Responses(`anthropicToOpenaiResponses.ts:98-104`)都这样。产生图片结果的工具:Read 读图片(`FileReadTool.ts:650-666`)、Bash 输出 data URI(`src/tools/BashTool/utils.ts:71-90`)、内置浏览器截图(MCP 内容 `{type:'image'}`,`src/server/browserHost/service.ts:826`)以及其他返回图片的 MCP 工具。 +- 现状:tool_result 的内容块经 `extractToolResultContent` 拍平成字符串,图片变成 `[image omitted: ]`(`toolArguments.ts:22-31`),chat(`anthropicToOpenaiChat.ts:114-120`)和 Responses(`anthropicToOpenaiResponses.ts:98-104`)都这样。产生图片结果的工具:Read 读图片(`FileReadTool.ts:650-666`)、Bash 输出 data URI(`src/tools/BashTool/utils.ts:71-90`)、内置浏览器截图(MCP 内容 `{type:'image'}`,`src/server/browserHost/service.ts:826`)以及其他返回图片的 MCP 工具。 - 场景:自定义 `openai_chat` 接一个视觉模型(例如 `qwen3-vl-plus` 或 OpenRouter 上的 Claude/GPT),用户让 agent 在内置浏览器里检查页面布局。截图工具返回 JPEG,上游只收到 `[image omitted: image/jpeg]`,模型无法完成任务,通常会反复截图,多花轮数。 - 参考: - ZCode(chat):tool 消息里保留文本,图片移到紧随其后的一条 user 消息,并按模型输入能力决定保留还是换成说明文字(`zcode:apps/zcode-cli/packages/adapters/src/model/transform.ts:59-66,120-151`;`tool-result-media-projection.ts:26-39`)。 @@ -236,7 +236,7 @@ DreamCoder 缺少的配置维度:推理字段的写法与档位、输出上限 - `tool_choice`:auto→auto、any→required、none→none、tool→指定函数(`anthropicToOpenaiChat.ts:175-187`;Responses 为扁平形状 `anthropicToOpenaiResponses.ts:125-137`)。CLI 唯一发 `type:'tool'` 的地方是 WebSearch 的小模型分支,受 `tengu_plum_vx3` 控制、默认关(`WebSearchTool.ts:395-414`)。 - `stop_sequences`:chat 转为 `stop`,Responses 丢弃(`anthropicToOpenaiChat.ts:43-45`)。CLI 只在 yolo 分类器和 sideQuery 中使用(`src/utils/permissions/yoloClassifier.ts:792`;`src/utils/sideQuery.ts:187`),本场景默认不触发。 - `temperature`:只在思考关闭时发 1(`claude.ts:1741-1745`),即 WebFetch 二次处理、hook 等辅助请求和用户关闭思考时;未找到会因此报错的具体模型。 -- `defer_loading` 与 `tool_reference`:代理场景下 ToolSearch 默认关闭(ANTHROPIC_BASE_URL 非 Anthropic 官方,`src/utils/toolSearch.ts:296-309`),服务端不设 `ENABLE_TOOL_SEARCH`;用户手动开启时 `tool_reference` 会变成 `[omitted content: tool_reference]`(`toolArguments.ts:43-44`),所有工具仍全量发送。 +- `defer_loading` 与 `tool_reference`:代理场景下 ToolSearch 默认关闭(ANTHROPIC_BASE_URL 非 Anthropic 官方,`src/utils/toolSearch.ts:296-309`),服务端不设 `ENABLE_TOOL_SEARCH`;用户手动开启时 `tool_reference` 会变成 `[omitted content: tool_reference]`(`toolArguments.ts:36-37`),所有工具仍全量发送。 - 工具名长度:MCP 工具名只做字符替换、不截断(`src/services/mcp/normalization.ts:17-23`;`mcpStringUtils.ts:50-52`),超过 64 字符时 Anthropic 与 OpenAI 端点都会拒绝,不是代理特有的问题。 - 空内容:空数组 content 转成 `content: ''`(`anthropicToOpenaiChat.ts:93-96`);ZCode 用 `(no content)` 防止提供方把空串当缺失(`zcode:apps/zcode-cli/packages/adapters/src/model/transform.ts:457-469`)。没找到 CLI 发出空 user content 的具体路径,未列为发现。 - 多个 assistant 文本块用 `+=` 直接相连、没有分隔(`anthropicToOpenaiChat.ts:144-145`);CLI 把 tool_use 重排为连续段(`messages.ts:2318-2330`),两段文本会被粘在一起。影响很小,未列为发现。 @@ -259,7 +259,7 @@ DreamCoder 缺少的配置维度:推理字段的写法与档位、输出上限 | `max_tokens` 和 effort 不转发 | 确认,并补充 | `types.ts:35-36,112` 有字段无赋值;`types.ts:161-181` 无 `output_config`。补充:`thinking: adaptive/disabled` 也不产生任何字段,带 budget 的映射在现有配置下走不到;直接转发 32000 会超出部分模型上限(P-REQ-02、P-REQ-05)。 | | 上游错误统一包成 `api_error`,响应头(含 `retry-after`)丢失 | 不在本部分范围 | 代码位置与描述一致(`handler.ts:66-71`;`client.ts:83-89`),留给错误方向的评审。 | | `reasoning_content` 只对 deepseek 与 opencode.ai 域名写回 | 确认,并补充 | `client.ts:206-210,251-256`;`anthropicToOpenaiChat.ts:146-147,168-170`。补充:同一判断还打开 `thinking.type` 透传,对 opencode.ai 上的所有模型生效;Responses 路径完全不回传(P-REQ-07、P-REQ-08)。 | -| 工具结果里的图片变成 `[image omitted]` | 确认,并补充 | `toolArguments.ts:37-38`,chat 与 Responses 两条路径都是。补充:PDF 的 `document` 块不在 tool_result 里,被完全静默丢弃(P-REQ-03);Responses 本可在 `function_call_output` 里带图片(P-REQ-04)。 | +| 工具结果里的图片变成 `[image omitted]` | 确认,并补充 | `toolArguments.ts:30-31`,chat 与 Responses 两条路径都是。补充:PDF 的 `document` 块不在 tool_result 里,被完全静默丢弃(P-REQ-03);Responses 本可在 `function_call_output` 里带图片(P-REQ-04)。 | | 流式工具调用没有 id 时被丢弃 | 不在本部分范围 | 响应方向。 | | `cache_control` 被丢弃,不发缓存键或会话头 | 确认,并补充 | `types.ts:149-181` 只声明不使用;`client.ts:213,221` 只有两个头。补充:CLI 已经给代理带了 `X-Claude-Code-Session-Id` 和 `metadata.user_id`,代理没读(P-REQ-10)。 | diff --git a/docs/features/harness/proxy/response.md b/docs/features/harness/proxy/response.md index 08153e6e..008daece 100644 --- a/docs/features/harness/proxy/response.md +++ b/docs/features/harness/proxy/response.md @@ -8,6 +8,7 @@ ### P-RES-01 上游没给 usage 时代理写 0,CLI 的上下文估算以 0 为基准,自动压缩不会触发 +- 状态:已在 #263 修复:代理在 chunk 顶层没有 usage 时读 `choices[0].usage`(流式和非流式);上游没给 usage 时 `message_delta` 不带 usage,不再写 0。CLI 的 `getTokenUsage` 把全 0 的 usage 当作没有,`tokenCountWithEstimation` 继续往前找有效 usage,找不到就整段本地估算,自动压缩照常按估算触发。 - 类型:问题 - 严重程度:高 - 现状: @@ -60,6 +61,7 @@ ### P-RES-04 上游在结束标记之前正常关闭连接,被当成正常结束,回答被截断且不重试 +- 状态:已在 #263 修复:chat 流既没有 `finish_reason` 也没有 `[DONE]` 就结束时、Responses 流没有 `response.completed`/`incomplete`/`failed` 就结束时,代理发 SSE `error`(「The provider closed the stream before the reply finished.」)。只有 `[DONE]` 没有 `finish_reason` 仍按正常结束。CLI 收到后撤回部分回复并重新建立流,见 P-RES-06。直连路径(anthropic 格式)上,已有块完成、但没有 message_delta 就正常关闭的流仍按正常结束处理,列为后续。 - 类型:问题 - 严重程度:中 - 现状: @@ -75,6 +77,7 @@ ### P-RES-05 finish_reason 映射过粗:内容过滤、资源不足、上下文用满都变成 end_turn;Responses 的内容过滤变成 max_tokens +- 状态:已在 #263 修复:chat 流和非流式共用一个映射:`model_context_window_exceeded` 原样传给 CLI;`content_filter`、`sensitive` 转成 `invalid_request_error`(「The provider's content filter stopped the reply ...」);`network_error`、`insufficient_system_resource` 转成 `api_error`;其余未知取值仍按 end_turn。Responses 的 `incomplete` 按 `incomplete_details.reason` 区分:`max_output_tokens` 或没有原因时为 max_tokens,`content_filter` 同上,其他原因转成 `api_error`。流式时以 SSE `error` 发出,非流式时为对应状态码的错误响应。CLI 专门处理的 stop_reason 只有 max_tokens、model_context_window_exceeded 和 refusal(src/services/api/claude.ts:2321-2355),其余都按正常结束;refusal 的文案指向 Anthropic 使用政策,所以内容过滤不映射到它。 - 类型:问题 - 严重程度:中 - 现状: @@ -95,6 +98,7 @@ ### P-RES-06 流中途的上游错误丢掉错误码和状态,CLI 一律改走非流式请求,长回答在 120 秒总时长内完不成 +- 状态:已在 #263 修复:流中途的错误用 P-NET-04 的同一张分类表映射:上下文溢出转成 `prompt is too long`,额度或余额不足为 `billing_error`,鉴权失败为 `authentication_error`,限流为 `rate_limit_error`,其余为 `api_error`。服务端给 CLI 设 `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1`,流出错后不再改走非流式请求。报告里「设了这个变量就交给 withRetry 用流式重试」不成立:withRetry 只包住建立流这一步(src/services/api/claude.ts 的 withRetry 调用),读流在它外面,单设变量时流中途的错误直接成为错误消息。所以 #263 在 `queryModel` 里把「建立流加读流」放进一个外层循环:读流出错且 `isRetryableStreamError` 判为可重试(不是用户中止,不是 invalid_request、鉴权、权限、额度一类)时,撤回已产出的部分消息,按 withRetry 的退避重新建立流。外层重来和 withRetry 内部的重试共用一个次数:整个调用的请求总数不超过 `getDefaultMaxRetries() + 1`。撤回的去向见 docs/features/session-state/tech-design.md 的 `reply_retracted`。 - 类型:问题 - 严重程度:中 - 现状: @@ -113,6 +117,7 @@ ### P-RES-07 被截断或损坏的工具参数在 CLI 里变成 `{}`,模型看到“缺参数”而不是“参数被截断” +- 状态:已在 #263 修复:参数解析统一在 CLI 的 `normalizeContentFromAPI`(src/utils/messages.ts)。参数为空串或 JSON `null` 时视为没有参数(`{}`)。其余情况下,非流式代理在参数不是合法 JSON 对象时把原始字符串交给 CLI,不再生成 `{raw}`;CLI 解析失败或得到的不是对象时,input 写成保留键 `__dreamcoder_invalid_arguments: { receivedChars, parseError }`(只记长度和错误,不记原文)。`runToolUse` 见到保留键就不执行工具,回给模型一条 is_error 的说明:参数不完整,很可能被输出上限截断,请缩短参数重试。保留键的写入和判断都在 `src/utils/invalidToolArguments.ts`。Anthropic 官方路径上因 max_tokens 截断的工具调用走同一条路。桌面端把这种调用显示为没有摘要的工具卡片,输入区以 JSON 显示保留键,结果区显示错误说明。 - 类型:问题 - 严重程度:中 - 现状: @@ -130,6 +135,7 @@ ### P-RES-08 同一个 delta 同时带正文、推理或工具调用时,只处理其中一种,其余被丢弃 +- 状态:已在 #263 修复:同一个 delta 依次处理推理、正文和工具调用,每类按原有规则开关块。 - 类型:问题 - 严重程度:中 - 现状:`detectBlockTransition` 按 tool_calls → content → reasoning 的顺序只返回一种类型(openaiChatStreamToAnthropic.ts:270-292),`processChunk` 只调用对应的一个处理函数(:320-330)。同一 delta 里的其余字段直接丢弃。 @@ -144,6 +150,7 @@ ### P-RES-09 Responses 流转换只依赖增量事件,不读完整 item,也不在结束时关闭文本和工具块 +- 状态:已在 #263 修复:文本增量没有 `content_part.added` 时自动开块;`output_item.added`、`function_call_arguments.done`、`output_text.done` 和 `output_item.done` 里的完整参数或文本在没有收到增量时补发;`response.completed` 和 `incomplete` 时关闭所有还开着的块。模型名一项 #262 已改为使用请求的模型名。 - 类型:问题 - 严重程度:低 - 现状: @@ -179,6 +186,7 @@ ### P-RES-12 有合法 chunk 但没有任何内容的回复,CLI 静默结束 +- 状态:已在 #263 修复:chat 流正常结束(end_turn)时,如果没有任何内容块也没有 usage,代理发 SSE `error`(「The provider returned an empty reply.」)。因输出上限结束(max_tokens)的不算空回复。 - 类型:优化 - 严重程度:低 - 现状:chat 流里只要出现过带 `choices` 的 chunk 就算合法(openaiChatStreamToAnthropic.ts:121),结束时发 end_turn(:518-527)。CLI 的空流检查要求“没有块且没有 stop_reason”(claude.ts:2400),此时 stop_reason 已是 end_turn,检查不触发,本次请求不产出任何助手消息。 diff --git a/docs/features/harness/proxy/transport.md b/docs/features/harness/proxy/transport.md index 99733036..26c489fe 100644 --- a/docs/features/harness/proxy/transport.md +++ b/docs/features/harness/proxy/transport.md @@ -31,6 +31,7 @@ ### P-NET-02 提供方的上下文溢出错误认不出来,会话卡死,手动 /compact 也救不回来 +- 状态:已在 #263 修复:溢出错误的识别表放在 `src/utils/providerErrors.ts`,代理和 CLI 共用。代理把识别出的溢出错误改写成 400 `invalid_request_error`,消息以 `prompt is too long` 开头,能解析出数字时带上 `N tokens > M maximum`;CLI 的 `errors.ts` 对直连路径用同一张表识别,并能从 OpenAI、OpenRouter、Gemini、Moonshot 的文案里解析出 token 数。`/compact` 的截头重试因此能按超出的 token 数删掉最早的几轮。OpenRouter 实测文案:`This endpoint's maximum context length is 128000 tokens. However, you requested about 270016 tokens ...`,它在转发前就拒绝,流式、非流式和 Responses 端点相同。本构建里被动压缩是空实现,溢出后需要用户手动 `/compact`。 - 类型:问题 - 严重程度:高 - 现状: @@ -46,6 +47,7 @@ ### P-NET-03 代理转发错误时把原因转义进字符串、丢掉响应头,429 时用户看不到原因 +- 状态:已在 #263 修复:代理解析上游错误正文,取出 message 和 code,`error.type` 按状态码映射,原文作为 `error.message`;透传 `retry-after`、`retry-after-ms` 和 `x-request-id`,并把 request id 也写进 `request-id`(SDK 读这个头)。按错误内容决定是否重试见 P-NET-04。 - 类型:问题 - 严重程度:中 - 现状: @@ -61,6 +63,7 @@ ### P-NET-04 重试分类按 Anthropic 设计,对第三方提供方会重试不该重试的错误、等待过久 +- 状态:已在 #263 修复:分类表在 `src/utils/providerErrors.ts`,代理和 CLI 直连路径共用。代理:额度或余额不足(HTTP 402,`insufficient_quota`、`exceeded_current_quota_error`、`billing_hard_limit_reached`、智谱 1113 等,原来是 429 的也算)改成 402 `billing_error`;401、403 保留状态码;这两类都加 `x-should-retry: false`,CLI 不再重试。限流保留 429 和 `retry-after`;5xx 照常重试,503 不改成 `overloaded_error`;2xx 正文里的错误按内容分类,分不出的为 502。CLI 直连路径:非 Anthropic 官方地址上的额度类错误不重试;401 只在能刷新凭据时重试(Anthropic 官方地址、配置了 apiKeyHelper、Claude 登录或 OpenAI 登录)。已知限制:代理自己的超时和网络错误仍按 5xx 重试,上游完全不回响应头时,非流式请求和等待响应头的阶段最坏要等「重试次数 × AI 请求超时」。 - 类型:问题 - 严重程度:中 - 现状(主循环请求 `maxRetries` 默认 10,即最多 11 次,src/services/api/withRetry.ts:52, 789-794;SDK 自身重试关闭,claude.ts:1831): diff --git a/docs/features/session-state/tech-design.md b/docs/features/session-state/tech-design.md index 8e829f84..5cdb5a50 100644 --- a/docs/features/session-state/tech-design.md +++ b/docs/features/session-state/tech-design.md @@ -44,7 +44,7 @@ DreamCoder 的每个会话由服务端拉起一个 CLI 进程执行,桌面端 客户端发:`prewarm_session`、`user_message`、`permission_response`、`set_permission_mode`、`set_runtime_config`、`stop_generation`、`ping`。 -服务端发:流式内容(`content_start`、`content_delta`、`tool_use_complete`、`tool_result`、`thinking`、`message_complete`),状态类(`status`、`permission_mode`、`permission_request`、`session_title_updated`、`team_*`、`task_update`、`background_task`),以及 `error`、`system_notification`、`transcript_item`、`api_retry`。定义在 `src/server/ws/protocol.ts`。 +服务端发:流式内容(`content_start`、`content_delta`、`tool_use_complete`、`tool_result`、`thinking`、`message_complete`、`reply_retracted`),状态类(`status`、`permission_mode`、`permission_request`、`session_title_updated`、`team_*`、`task_update`、`background_task`),以及 `error`、`system_notification`、`transcript_item`、`api_retry`。定义在 `src/server/ws/protocol.ts`。 ### 已核实的主要问题 @@ -300,6 +300,16 @@ CLI 源码注释提到,末尾的 `idle` 事件曾让一些客户端卡在「 - `session_patch`:`version` 是应用这次变化之后的版本号。客户端收到的 `version` 不等于本地版本加一时,丢弃这个 patch 并发 `request_snapshot`。 - `changes` 只包含变化的顶层字段,每个顶层字段整体替换,不做深层合并 `[assumption]`。这样客户端的应用逻辑最简单,代价是 `pendingPermissions` 这类数组每次整体下发,数据量很小,可以接受。 +流式内容另有一条撤回消息(#263): + +```ts +| { type: 'reply_retracted' } +``` + +- 来源:CLI 读流时出错并重新建立流之前,输出 stream-json 系统消息 `{ type: 'system', subtype: 'stream_retracted' }`(`src/QueryEngine.ts`)。 +- 服务端 `translate` 收到后清空这次回复的流式翻译状态(进行中的块、待补全的工具块、已流式发出的工具 id),广播 `reply_retracted`,并用现有的 `turn_activity_reported` 事件经 reducer 把 `turn.activity` 改回 `thinking`。消息内容不在 `SessionState` 里,所以撤回不需要新的状态事件。 +- 客户端(桌面与 H5 同一份 `chatStore`)收到后丢掉流式缓冲,并删掉最后一条用户消息或工具结果之后、属于主线程的 `assistant_text`、`thinking` 和 `tool_use`。 + ### WebSocket:客户端 → 服务端 - 新增 `{ type: 'request_snapshot' }`。 @@ -425,6 +435,7 @@ Store --> C : patch(effective=bypass, pendingRestart=无) - **重启期间的请求**:带着旧代号的强杀、删除操作被忽略;新请求排在 `runtimeTransition` 之后执行(沿用现有的串行队列思路)。 - **持久化写入失败**:内存状态照常生效并广播,记一条诊断事件(`diagnosticsService`),下一次写入重试整条记录。不会因为写盘失败回滚界面。 - **恢复时 transcript 损坏或缺字段**:按恢复顺序退回全局默认,记诊断事件。 +- **读流中途出错后重新建立流**:CLI 在 `mutableMessages` 和 transcript 里删掉失败那次已经完整产出的部分消息(`QueryEngine` 处理 `tombstone`),服务端和客户端按上面的 `reply_retracted` 丢掉已显示的流式内容。重试成功后,客户端只看到重试得到的完整回复,下一轮历史里也没有失败那次的部分消息。 ## 横切关注点 diff --git a/src/QueryEngine.ts b/src/QueryEngine.ts index 9dcb1861..aa2485a8 100644 --- a/src/QueryEngine.ts +++ b/src/QueryEngine.ts @@ -86,6 +86,7 @@ import { setCwd } from './utils/Shell.js' import { flushSessionStorage, recordTranscript, + removeTranscriptMessage, } from './utils/sessionStorage.js' import { asSystemPrompt } from './utils/systemPromptType.js' import { resolveThemeSetting } from './utils/systemTheme.js' @@ -710,6 +711,7 @@ export class QueryEngine { let structuredOutputFromTool: unknown // Track the last stop_reason from assistant messages let lastStopReason: string | null = null + let pendingAssistantRecord: Promise = Promise.resolve() // Reference-based watermark so error_during_execution's errors[] is // turn-scoped. A length-based index breaks when the 100-entry ring buffer // shift()s during the turn — the index slides. If this entry is rotated @@ -773,7 +775,7 @@ export class QueryEngine { // useLogMessages.ts fire-and-forgets. enqueueWrite is // order-preserving so fire-and-forget here is safe. if (message.type === 'assistant') { - void recordTranscript(messages) + pendingAssistantRecord = recordTranscript(messages) } else { await recordTranscript(messages) } @@ -803,9 +805,17 @@ export class QueryEngine { } switch (message.type) { - case 'tombstone': - // Tombstone messages are control signals for removing messages, skip them + case 'tombstone': { + const retractedUuid = message.message.uuid + removeMessageByUuid(this.mutableMessages, retractedUuid) + removeMessageByUuid(messages, retractedUuid) + if (persistSession) { + await pendingAssistantRecord + await flushSessionStorage() + await removeTranscriptMessage(retractedUuid) + } break + } case 'assistant': // Capture stop_reason if already set (synthetic messages). For // streamed responses, this is null at content_block_stop time; @@ -998,6 +1008,14 @@ export class QueryEngine { compact_metadata: toSDKCompactMetadata(message.compactMetadata), } } + if (message.subtype === 'api_error' && message.streamRestart) { + yield { + type: 'system', + subtype: 'stream_retracted' as const, + session_id: getSessionId(), + uuid: message.uuid, + } + } if (message.subtype === 'api_error') { yield { type: 'system', @@ -1397,3 +1415,8 @@ export async function* ask({ setReadFileCache(engine.getReadFileState()) } } + +function removeMessageByUuid(messages: Message[], uuid: string): void { + const index = messages.findIndex(message => message.uuid === uuid) + if (index !== -1) messages.splice(index, 1) +} diff --git a/src/__tests__/queryEngineRetraction.test.ts b/src/__tests__/queryEngineRetraction.test.ts new file mode 100644 index 00000000..38d936e4 --- /dev/null +++ b/src/__tests__/queryEngineRetraction.test.ts @@ -0,0 +1,93 @@ +import { afterEach, beforeEach, describe, expect, spyOn, test } from 'bun:test' +import { readFile } from 'node:fs/promises' +import { APIError } from '@anthropic-ai/sdk' +import { QueryEngine } from '../QueryEngine.js' +import * as claudeApi from '../services/api/claude.js' +import { getDefaultAppState } from '../state/AppStateStore.js' +import { createFileStateCacheWithSizeLimit } from '../utils/fileStateCache.js' +import { createAssistantMessage, createSystemAPIErrorMessage } from '../utils/messages.js' +import { flushSessionStorage, getTranscriptPath } from '../utils/sessionStorage.js' + +function reply(content: Parameters[0]['content']) { + const message = createAssistantMessage({ content }) + message.message.model = 'claude-sonnet-4-5' + return message +} + +describe('QueryEngine when a stream is retried', () => { + let modelSpy: ReturnType | undefined + const envKeys = ['ANTHROPIC_API_KEY', 'TEST_ENABLE_SESSION_PERSISTENCE'] as const + let savedEnv: Partial> + + beforeEach(() => { + savedEnv = Object.fromEntries(envKeys.map((key) => [key, process.env[key]])) + process.env.ANTHROPIC_API_KEY = 'sk-test' + process.env.TEST_ENABLE_SESSION_PERSISTENCE = '1' + }) + + afterEach(() => { + modelSpy?.mockRestore() + for (const key of envKeys) { + if (savedEnv[key] === undefined) delete process.env[key] + else process.env[key] = savedEnv[key] + } + }) + + test('keeps the whole retried reply, drops the partial one and tells the client', async () => { + const partial = reply('Half an ans') + const text = reply('Let me check.') + const toolUse = reply([{ type: 'tool_use', id: 'toolu_1', name: 'Missing', input: {} }] as never) + const final = reply('Done.') + let calls = 0 + modelSpy = spyOn(claudeApi, 'queryModelWithStreaming').mockImplementation(async function* ({ options }) { + calls += 1 + if (calls > 1) { + yield final + return + } + yield partial + options.onStreamingFallback?.() + yield { + ...createSystemAPIErrorMessage(APIError.generate(undefined, undefined, 'the stream broke', undefined), 500, 1, 10), + streamRestart: true, + } + yield { type: 'stream_event', event: { type: 'message_start', message: { usage: { input_tokens: 10, output_tokens: 0 } } } } + yield text + yield toolUse + yield { type: 'stream_event', event: { type: 'message_delta', delta: { stop_reason: 'tool_use' }, usage: { output_tokens: 5 } } } + } as never) + + let appState = getDefaultAppState() + const engine = new QueryEngine({ + cwd: process.cwd(), + tools: [], + commands: [], + mcpClients: [], + agents: [], + canUseTool: async () => ({ behavior: 'allow' }) as never, + getAppState: () => appState, + setAppState: (update) => { + appState = update(appState) + }, + readFileCache: createFileStateCacheWithSizeLimit(10), + userSpecifiedModel: 'claude-sonnet-4-5', + }) + + const output: Array> = [] + for await (const message of engine.submitMessage('hello')) output.push(message as Record) + await flushSessionStorage() + + const retracted = output.findIndex((m) => m.type === 'system' && m.subtype === 'stream_retracted') + const retry = output.findIndex((m) => m.type === 'system' && m.subtype === 'api_retry') + expect(retracted).toBeGreaterThan(-1) + expect(retracted).toBeLessThan(retry) + const history = engine.getMessages().map((m) => m.uuid) + expect(history).not.toContain(partial.uuid) + expect(history).toEqual(expect.arrayContaining([text.uuid, toolUse.uuid, final.uuid])) + expect(calls).toBe(2) + const transcript = await readFile(getTranscriptPath(), 'utf8') + expect(transcript).not.toContain(partial.uuid) + expect(transcript).toContain(toolUse.uuid) + expect(transcript).toContain(final.uuid) + }) +}) diff --git a/src/entrypoints/sdk/coreSchemas.ts b/src/entrypoints/sdk/coreSchemas.ts index 9204796d..9ade409f 100644 --- a/src/entrypoints/sdk/coreSchemas.ts +++ b/src/entrypoints/sdk/coreSchemas.ts @@ -1646,6 +1646,19 @@ export const SDKAPIRetryMessageSchema = lazySchema(() => ), ) +export const SDKStreamRetractedMessageSchema = lazySchema(() => + z + .object({ + type: z.literal('system'), + subtype: z.literal('stream_retracted'), + uuid: UUIDPlaceholder(), + session_id: z.string(), + }) + .describe( + 'Emitted when a stream broke in the middle and will be opened again. Everything streamed since the last user message or tool result belongs to the failed attempt and is replaced by the retried reply.', + ), +) + export const SDKLocalCommandOutputMessageSchema = lazySchema(() => z .object({ @@ -1922,6 +1935,7 @@ export const SDKMessageSchema = lazySchema(() => SDKCompactBoundaryMessageSchema(), SDKStatusMessageSchema(), SDKAPIRetryMessageSchema(), + SDKStreamRetractedMessageSchema(), SDKLocalCommandOutputMessageSchema(), SDKHookStartedMessageSchema(), SDKHookProgressMessageSchema(), diff --git a/src/query.ts b/src/query.ts index ca2ec844..2a4685da 100644 --- a/src/query.ts +++ b/src/query.ts @@ -739,6 +739,7 @@ async function* queryLoop( toolUseContext, ) } + streamingFallbackOccured = false } // Backfill tool_use inputs on a cloned message before yield so // SDK stream output and transcript serialization see legacy/derived diff --git a/src/server/__tests__/conversation-service.test.ts b/src/server/__tests__/conversation-service.test.ts index 5f7d12f7..ccfd18f0 100644 --- a/src/server/__tests__/conversation-service.test.ts +++ b/src/server/__tests__/conversation-service.test.ts @@ -245,6 +245,7 @@ describe('ConversationService', () => { expect(env.API_TIMEOUT_MS).toBe('180000') expect(env.CLAUDE_ENABLE_STREAM_WATCHDOG).toBe('1') + expect(env.CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK).toBe('1') expect(env.CLAUDE_STREAM_IDLE_TIMEOUT_MS).toBe('180000') expect(env.HTTP_PROXY).toBe('http://127.0.0.1:7890') expect(env.HTTPS_PROXY).toBe('http://127.0.0.1:7890') diff --git a/src/server/__tests__/cron-scheduler-launcher.test.ts b/src/server/__tests__/cron-scheduler-launcher.test.ts index 11b224b8..c328d736 100644 --- a/src/server/__tests__/cron-scheduler-launcher.test.ts +++ b/src/server/__tests__/cron-scheduler-launcher.test.ts @@ -306,10 +306,12 @@ describe('cron scheduler launcher resolution', () => { expect({ API_TIMEOUT_MS: env.API_TIMEOUT_MS, CLAUDE_ENABLE_STREAM_WATCHDOG: env.CLAUDE_ENABLE_STREAM_WATCHDOG, + CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK: env.CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK, CLAUDE_STREAM_IDLE_TIMEOUT_MS: env.CLAUDE_STREAM_IDLE_TIMEOUT_MS, }).toEqual({ API_TIMEOUT_MS: '180000', CLAUDE_ENABLE_STREAM_WATCHDOG: '1', + CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK: '1', CLAUDE_STREAM_IDLE_TIMEOUT_MS: '180000', }) } finally { diff --git a/src/server/__tests__/network-settings.test.ts b/src/server/__tests__/network-settings.test.ts index 11da5e51..f74a69e1 100644 --- a/src/server/__tests__/network-settings.test.ts +++ b/src/server/__tests__/network-settings.test.ts @@ -92,6 +92,7 @@ describe('network settings', () => { expect(getManualNetworkProxyUrl(settings)).toBe('http://127.0.0.1:7890') expect(buildNetworkEnvironment(settings, { NO_PROXY: 'corp.internal' })).toEqual({ API_TIMEOUT_MS: '180000', + CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK: '1', CLAUDE_ENABLE_STREAM_WATCHDOG: '1', CLAUDE_STREAM_IDLE_TIMEOUT_MS: '180000', HTTP_PROXY: 'http://127.0.0.1:7890', diff --git a/src/server/__tests__/providers.test.ts b/src/server/__tests__/providers.test.ts index 8dfba48b..59103aaa 100644 --- a/src/server/__tests__/providers.test.ts +++ b/src/server/__tests__/providers.test.ts @@ -946,6 +946,35 @@ describe('ProviderService', () => { expect(res.status).toBe(404) expect(await res.json()).toMatchObject({ type: 'error', error: { type: 'not_found_error' } }) }) + + test('answers an upstream error in Anthropic form with the retry and request id headers', async () => { + const originalFetch = globalThis.fetch + globalThis.fetch = mock(async () => Response.json( + { error: { message: 'Rate limit reached, please try again in 20s.', code: 'rate_limit_exceeded' } }, + { status: 429, headers: { 'retry-after': '20', 'x-request-id': 'req_abc' } }, + )) as unknown as typeof fetch + + try { + const svc = new ProviderService() + const provider = await svc.addProvider(sampleInput({ apiFormat: 'openai_chat' })) + const req = new Request(`http://localhost:3456/proxy/providers/${provider.id}/v1/messages`, { + method: 'POST', + body: JSON.stringify({ model: 'model-main', max_tokens: 16, messages: [{ role: 'user', content: 'hi' }] }), + }) + + const res = await handleProxyRequest(req, new URL(req.url), { timeout: () => {} }) + + expect(res.status).toBe(429) + expect(res.headers.get('retry-after')).toBe('20') + expect(res.headers.get('request-id')).toBe('req_abc') + expect(await res.json()).toEqual({ + type: 'error', + error: { type: 'rate_limit_error', message: 'Rate limit reached, please try again in 20s.' }, + }) + } finally { + globalThis.fetch = originalFetch + } + }) }) describe('discoverModels', () => { @@ -1173,6 +1202,44 @@ describe('ProviderService', () => { } }) + test('shows only the HTTP status when a rejected connection test has an empty body', async () => { + const originalFetch = globalThis.fetch + globalThis.fetch = mock(async () => new Response('', { status: 502 })) as unknown as typeof fetch + + try { + const svc = new ProviderService() + const result = await svc.testProviderConfig({ + baseUrl: 'https://api.example.com', + apiKey: 'sk-test', + modelId: 'gpt-main', + apiFormat: 'openai_chat', + }) + + expect(result.connectivity).toMatchObject({ success: false, error: 'HTTP 502', httpStatus: 502 }) + } finally { + globalThis.fetch = originalFetch + } + }) + + test('shows the HTTP status with the provider message when the connection test is rejected', async () => { + const originalFetch = globalThis.fetch + globalThis.fetch = mock(async () => Response.json({ error: { message: 'Incorrect API key provided' } }, { status: 401 })) as unknown as typeof fetch + + try { + const svc = new ProviderService() + const result = await svc.testProviderConfig({ + baseUrl: 'https://api.example.com', + apiKey: 'sk-test', + modelId: 'gpt-main', + apiFormat: 'openai_chat', + }) + + expect(result.connectivity).toMatchObject({ success: false, error: 'HTTP 401: Incorrect API key provided', httpStatus: 401 }) + } finally { + globalThis.fetch = originalFetch + } + }) + test.each([ ['a JSON error body', '{"error":{"message":"invalid api key"}}', 'invalid api key'], ['an HTML page', 'hi', 'no valid Chat Completions chunks'], @@ -1387,10 +1454,11 @@ describe('Providers API', () => { apiFormat: 'openai_chat', }) const res = await handleProvidersApi(req, url, segments) - const body = (await res.json()) as { error: string } + const body = (await res.json()) as { error: string; message: string } expect(res.status).toBe(400) expect(body.error).toBe('MODEL_DISCOVERY_FAILED') + expect(body.message).toBe('HTTP 401: unauthorized') } finally { server.stop(true) } diff --git a/src/server/__tests__/proxy-streaming.test.ts b/src/server/__tests__/proxy-streaming.test.ts index 6ebcc156..74116358 100644 --- a/src/server/__tests__/proxy-streaming.test.ts +++ b/src/server/__tests__/proxy-streaming.test.ts @@ -1,10 +1,8 @@ import { describe, test, expect } from 'bun:test' import { openaiChatStreamToAnthropic } from '../proxy/streaming/openaiChatStreamToAnthropic.js' import { openaiResponsesStreamToAnthropic } from '../proxy/streaming/openaiResponsesStreamToAnthropic.js' -import { - OpenAIResponsesStreamError, - openaiResponsesStreamToAnthropicResponse, -} from '../proxy/streaming/openaiResponsesStreamToAnthropicResponse.js' +import { openaiResponsesStreamToAnthropicResponse } from '../proxy/streaming/openaiResponsesStreamToAnthropicResponse.js' +import { UpstreamReplyError } from '../upstream/upstreamError.js' import { SseDecoder } from '../proxy/streaming/sse.js' function makeStream(chunks: string[]): ReadableStream { @@ -588,7 +586,7 @@ describe('openaiResponsesStreamToAnthropicResponse upstream errors', () => { 'm', ) - await expect(result).rejects.toBeInstanceOf(OpenAIResponsesStreamError) + await expect(result).rejects.toBeInstanceOf(UpstreamReplyError) await expect(result).rejects.toThrow(message) }) @@ -745,3 +743,280 @@ describe('stream cancellation', () => { expect(upstreamCancelReason).toBe('client gone') }) }) + +function chatChunk(choice: Record, extra?: Record): string { + return `data: ${JSON.stringify({ id: 'c1', object: 'chat.completion.chunk', created: 0, model: 'm', choices: [{ index: 0, ...choice }], ...extra })}\n\n` +} + +describe('chat stream usage', () => { + test('reads usage that the provider puts inside the choice (Moonshot)', async () => { + const events = await collectSse(openaiChatStreamToAnthropic(makeStream([ + chatChunk({ delta: { content: 'Hi' }, finish_reason: null }), + chatChunk({ delta: {}, finish_reason: 'stop', usage: { prompt_tokens: 1000, completion_tokens: 20, total_tokens: 1020 } }), + 'data: [DONE]\n\n', + ]), 'kimi-k2.6')) + + expect(events.find((e) => e.event === 'message_delta')!.data.usage).toEqual({ input_tokens: 1000, output_tokens: 20, cache_read_input_tokens: 0 }) + }) + + test('leaves usage out instead of reporting zero when the provider sends none', async () => { + const events = await collectSse(openaiChatStreamToAnthropic(makeStream([ + chatChunk({ delta: { content: 'Hi' }, finish_reason: null }), + chatChunk({ delta: {}, finish_reason: 'stop' }), + 'data: [DONE]\n\n', + ]), 'm')) + + expect(events.find((e) => e.event === 'message_delta')!.data).not.toHaveProperty('usage') + }) +}) + +function eventNames(events: Array<{ event: string }>): string[] { + return events.map((e) => e.event) +} + +function lastError(events: Array<{ event: string; data: Record }>): { type: string; message: string } { + const last = events.at(-1)! + expect(last.event).toBe('error') + return (last.data as { error: { type: string; message: string } }).error +} + +describe('chat stream finish reasons', () => { + test('passes a full context window through so the CLI can tell the user', async () => { + const events = await collectSse(openaiChatStreamToAnthropic(makeStream([ + chatChunk({ delta: { content: 'Hi' }, finish_reason: null }), + chatChunk({ delta: {}, finish_reason: 'model_context_window_exceeded' }), + 'data: [DONE]\n\n', + ]), 'glm-4.6')) + + expect((events.find((e) => e.event === 'message_delta')!.data.delta as { stop_reason: string }).stop_reason) + .toBe('model_context_window_exceeded') + }) + + test.each(['content_filter', 'sensitive'])('reports %s as an error instead of a normal end', async (reason) => { + const events = await collectSse(openaiChatStreamToAnthropic(makeStream([ + chatChunk({ delta: { content: 'Hi' }, finish_reason: null }), + chatChunk({ delta: {}, finish_reason: reason }), + 'data: [DONE]\n\n', + ]), 'm')) + + expect(eventNames(events)).not.toContain('message_stop') + expect(lastError(events)).toEqual({ + type: 'invalid_request_error', + message: `The provider's content filter stopped the reply (finish_reason: ${reason}).`, + }) + }) + + test.each(['network_error', 'insufficient_system_resource'])('reports %s as a server error', async (reason) => { + const events = await collectSse(openaiChatStreamToAnthropic(makeStream([ + chatChunk({ delta: { content: 'Hi' }, finish_reason: null }), + chatChunk({ delta: {}, finish_reason: reason }), + 'data: [DONE]\n\n', + ]), 'm')) + + expect(eventNames(events)).not.toContain('message_stop') + expect(lastError(events)).toEqual({ + type: 'api_error', + message: `The provider stopped the reply because of an error on its side (finish_reason: ${reason}).`, + }) + }) +}) + +describe('chat stream errors and early ends', () => { + test('keeps a context overflow code from an error in the middle of the stream', async () => { + const events = await collectSse(openaiChatStreamToAnthropic(makeStream([ + chatChunk({ delta: { content: 'Hi' }, finish_reason: null }), + 'data: {"error":{"message":"Your input exceeds the context window of this model.","code":"context_length_exceeded"}}\n\n', + ]), 'm')) + + expect(lastError(events)).toEqual({ + type: 'invalid_request_error', + message: 'prompt is too long · Your input exceeds the context window of this model.', + }) + }) + + test('reports a stream that closes before any end marker', async () => { + const events = await collectSse(openaiChatStreamToAnthropic(makeStream([ + chatChunk({ delta: { content: 'Half an ans' }, finish_reason: null }), + ]), 'm')) + + expect(eventNames(events)).not.toContain('message_stop') + expect(lastError(events)).toEqual({ + type: 'api_error', + message: 'The provider closed the stream before the reply finished.', + }) + }) + + test('accepts [DONE] without a finish reason as a normal end', async () => { + const events = await collectSse(openaiChatStreamToAnthropic(makeStream([ + chatChunk({ delta: { content: 'Hi' }, finish_reason: null }), + 'data: [DONE]\n\n', + ]), 'm')) + + expect(eventNames(events).at(-1)).toBe('message_stop') + }) + + test('reports a reply with chunks but no content and no usage', async () => { + const events = await collectSse(openaiChatStreamToAnthropic(makeStream([ + chatChunk({ delta: { role: 'assistant' }, finish_reason: null }), + chatChunk({ delta: {}, finish_reason: 'stop' }), + 'data: [DONE]\n\n', + ]), 'm')) + + expect(lastError(events)).toEqual({ type: 'api_error', message: 'The provider returned an empty reply.' }) + }) +}) + +describe('chat stream deltas with several kinds of content', () => { + test('keeps reasoning, text and a tool call that arrive in one delta', async () => { + const events = await collectSse(openaiChatStreamToAnthropic(makeStream([ + chatChunk({ + delta: { + reasoning_content: 'think', + content: 'Let me look.', + tool_calls: [{ index: 0, id: 'call_1', type: 'function', function: { name: 'Read', arguments: '{"file_path":"a.ts"}' } }], + }, + finish_reason: 'tool_calls', + }), + 'data: [DONE]\n\n', + ]), 'm')) + + const starts = events.filter((e) => e.event === 'content_block_start').map((e) => (e.data.content_block as { type: string }).type) + const deltas = events.filter((e) => e.event === 'content_block_delta').map((e) => e.data.delta) + expect(starts).toEqual(['thinking', 'text', 'tool_use']) + expect(deltas).toEqual([ + { type: 'thinking_delta', thinking: 'think' }, + { type: 'text_delta', text: 'Let me look.' }, + { type: 'input_json_delta', partial_json: '{"file_path":"a.ts"}' }, + ]) + expect(eventNames(events).at(-1)).toBe('message_stop') + }) +}) + +function responsesEvent(type: string, data: Record): string { + return `event: ${type}\ndata: ${JSON.stringify({ type, ...data })}\n\n` +} + +const responseCreated = responsesEvent('response.created', { response: { id: 'r1', model: 'gpt-4.1' } }) + +function completed(usage?: Record): string { + return responsesEvent('response.completed', { response: { id: 'r1', status: 'completed', ...(usage && { usage }) } }) +} + +describe('responses stream ends', () => { + test('reports an incomplete reply stopped by the content filter as an error', async () => { + const events = await collectSse(openaiResponsesStreamToAnthropic(makeStream([ + responseCreated, + responsesEvent('response.incomplete', { response: { status: 'incomplete', incomplete_details: { reason: 'content_filter' } } }), + ]), 'gpt-4.1')) + + expect(eventNames(events)).not.toContain('message_stop') + expect(lastError(events)).toEqual({ + type: 'invalid_request_error', + message: "The provider's content filter stopped the reply (incomplete: content_filter).", + }) + }) + + test('keeps a context overflow code from response.failed', async () => { + const events = await collectSse(openaiResponsesStreamToAnthropic(makeStream([ + responseCreated, + responsesEvent('response.failed', { response: { status: 'failed', error: { code: 'context_length_exceeded', message: 'Your input exceeds the context window of this model.' } } }), + ]), 'gpt-4.1')) + + expect(lastError(events)).toEqual({ + type: 'invalid_request_error', + message: 'prompt is too long · Your input exceeds the context window of this model.', + }) + }) + + test('reports a stream that closes before response.completed', async () => { + const events = await collectSse(openaiResponsesStreamToAnthropic(makeStream([ + responseCreated, + responsesEvent('response.content_part.added', { output_index: 0, content_index: 0, part: { type: 'output_text', text: '' } }), + responsesEvent('response.output_text.delta', { output_index: 0, content_index: 0, delta: 'Half an ans' }), + ]), 'gpt-4.1')) + + expect(eventNames(events)).not.toContain('message_stop') + expect(lastError(events)).toEqual({ type: 'api_error', message: 'The provider closed the stream before the reply finished.' }) + }) + + test('leaves usage out when response.completed has none', async () => { + const events = await collectSse(openaiResponsesStreamToAnthropic(makeStream([responseCreated, completed()]), 'gpt-4.1')) + + expect(events.find((e) => e.event === 'message_delta')!.data).not.toHaveProperty('usage') + }) +}) + +describe('responses stream without every delta event', () => { + function blocksAndDeltas(events: Array<{ event: string; data: Record }>) { + return events + .filter((e) => e.event.startsWith('content_block')) + .map((e) => e.event === 'content_block_delta' ? e.data.delta : e.event === 'content_block_start' ? e.data.content_block : 'stop') + } + + test('opens a text block for a text delta without content_part.added and closes it on completion', async () => { + const events = await collectSse(openaiResponsesStreamToAnthropic(makeStream([ + responseCreated, + responsesEvent('response.output_text.delta', { output_index: 0, content_index: 0, delta: 'Hello' }), + completed({ input_tokens: 5, output_tokens: 1 }), + ]), 'gpt-4.1')) + + expect(blocksAndDeltas(events)).toEqual([{ type: 'text', text: '' }, { type: 'text_delta', text: 'Hello' }, 'stop']) + expect(eventNames(events).slice(-2)).toEqual(['message_delta', 'message_stop']) + }) + + test('takes the arguments from function_call_arguments.done when no deltas came', async () => { + const events = await collectSse(openaiResponsesStreamToAnthropic(makeStream([ + responseCreated, + responsesEvent('response.output_item.added', { output_index: 0, item: { type: 'function_call', id: 'fc_1', call_id: 'call_1', name: 'Read' } }), + responsesEvent('response.function_call_arguments.done', { item_id: 'fc_1', output_index: 0, arguments: '{"file_path":"a.ts"}' }), + completed({ input_tokens: 5, output_tokens: 1 }), + ]), 'gpt-4.1')) + + expect(blocksAndDeltas(events)).toEqual([ + { type: 'tool_use', id: 'call_1', name: 'Read', input: {} }, + { type: 'input_json_delta', partial_json: '{"file_path":"a.ts"}' }, + 'stop', + ]) + }) + + test('reads a message that only arrives as a completed output item', async () => { + const events = await collectSse(openaiResponsesStreamToAnthropic(makeStream([ + responseCreated, + responsesEvent('response.output_item.done', { + output_index: 0, + item: { type: 'message', id: 'msg_1', role: 'assistant', content: [{ type: 'output_text', text: 'Hello there' }] }, + }), + completed({ input_tokens: 5, output_tokens: 2 }), + ]), 'gpt-4.1')) + + expect(blocksAndDeltas(events)).toEqual([{ type: 'text', text: '' }, { type: 'text_delta', text: 'Hello there' }, 'stop']) + }) + + test('closes a tool block on completion when function_call_arguments.done never came', async () => { + const events = await collectSse(openaiResponsesStreamToAnthropic(makeStream([ + responseCreated, + responsesEvent('response.output_item.added', { output_index: 0, item: { type: 'function_call', id: 'fc_1', call_id: 'call_1', name: 'Read' } }), + responsesEvent('response.function_call_arguments.delta', { item_id: 'fc_1', output_index: 0, delta: '{"file_path":"a.ts"}' }), + completed({ input_tokens: 5, output_tokens: 1 }), + ]), 'gpt-4.1')) + + expect(blocksAndDeltas(events).at(-1)).toBe('stop') + expect((events.find((e) => e.event === 'message_delta')!.data.delta as { stop_reason: string }).stop_reason).toBe('tool_use') + }) +}) + +describe('stream error classification', () => { + test.each([ + ['insufficient_quota', 'You exceeded your current quota.', 'billing_error'], + ['rate_limit_exceeded', 'Rate limit reached.', 'rate_limit_error'], + ['invalid_api_key', 'Incorrect API key provided', 'authentication_error'], + ['server_error', 'The server had an error.', 'api_error'], + ])('maps a %s error in the middle of a chat stream', async (code, message, type) => { + const events = await collectSse(openaiChatStreamToAnthropic(makeStream([ + chatChunk({ delta: { content: 'Hi' }, finish_reason: null }), + `data: ${JSON.stringify({ error: { message, code } })}\n\n`, + ]), 'm')) + + expect(lastError(events)).toEqual({ type, message }) + }) +}) diff --git a/src/server/__tests__/proxy-transform.test.ts b/src/server/__tests__/proxy-transform.test.ts index 9ab5bfcf..cd6e3e11 100644 --- a/src/server/__tests__/proxy-transform.test.ts +++ b/src/server/__tests__/proxy-transform.test.ts @@ -261,6 +261,23 @@ describe('anthropicToOpenaiChat', () => { }) describe('openaiChatToAnthropic', () => { + test('reads usage that the provider puts inside the choice (Moonshot)', () => { + const res = { + id: 'chatcmpl-1', + object: 'chat.completion', + created: 0, + model: 'kimi-k2.6', + choices: [{ + index: 0, + message: { role: 'assistant', content: 'ok' }, + finish_reason: 'stop', + usage: { prompt_tokens: 1000, completion_tokens: 20, total_tokens: 1020 }, + }], + } as unknown as OpenAIChatResponse + + expect(openaiChatToAnthropic(res, 'kimi-k2.6').usage).toEqual({ input_tokens: 1000, output_tokens: 20, cache_read_input_tokens: 0 }) + }) + test('basic text response', () => { const res: OpenAIChatResponse = { id: 'chatcmpl-1', @@ -375,7 +392,9 @@ describe('openaiChatToAnthropic', () => { expect(openaiChatToAnthropic(make('stop'), 'gpt-4').stop_reason).toBe('end_turn') expect(openaiChatToAnthropic(make('length'), 'gpt-4').stop_reason).toBe('max_tokens') expect(openaiChatToAnthropic(make('tool_calls'), 'gpt-4').stop_reason).toBe('tool_use') - expect(openaiChatToAnthropic(make('content_filter'), 'gpt-4').stop_reason).toBe('end_turn') + expect(openaiChatToAnthropic(make('model_context_window_exceeded'), 'gpt-4').stop_reason).toBe('model_context_window_exceeded') + expect(() => openaiChatToAnthropic(make('content_filter'), 'gpt-4')) + .toThrow("The provider's content filter stopped the reply (finish_reason: content_filter).") }) test('empty choices', () => { @@ -667,6 +686,22 @@ describe('anthropicToOpenaiResponses', () => { }) describe('openaiResponsesToAnthropic', () => { + test.each([ + [{ reason: 'max_output_tokens' }, 'max_tokens'], + [undefined, 'max_tokens'], + ])('maps an incomplete reply with %o to %s', (details, stopReason) => { + const res = { id: 'r1', object: 'response', created_at: 0, model: 'gpt-4.1', status: 'incomplete', incomplete_details: details, output: [] } as OpenAIResponsesResponse + + expect(openaiResponsesToAnthropic(res, 'gpt-4.1').stop_reason).toBe(stopReason) + }) + + test('reports an incomplete reply stopped by the content filter as an error', () => { + const res = { id: 'r1', object: 'response', created_at: 0, model: 'gpt-4.1', status: 'incomplete', incomplete_details: { reason: 'content_filter' }, output: [] } as OpenAIResponsesResponse + + expect(() => openaiResponsesToAnthropic(res, 'gpt-4.1')) + .toThrow("The provider's content filter stopped the reply (incomplete: content_filter).") + }) + test('basic text response', () => { const res: OpenAIResponsesResponse = { id: 'resp_1', diff --git a/src/server/__tests__/stream-retraction.test.ts b/src/server/__tests__/stream-retraction.test.ts new file mode 100644 index 00000000..0f602cb0 --- /dev/null +++ b/src/server/__tests__/stream-retraction.test.ts @@ -0,0 +1,34 @@ +import { describe, expect, test } from 'bun:test' +import { createStreamState, translateCliOutput } from '../session/translate.js' +import { createSessionState, reduceSessionState } from '../session/state/reducer.js' + +function streamEvent(event: Record) { + return { type: 'stream_event', event } +} + +describe('a stream the CLI retries', () => { + test('drops what the failed attempt streamed and tells the clients', () => { + const stream = createStreamState() + translateCliOutput(streamEvent({ type: 'message_start' }), stream) + translateCliOutput(streamEvent({ type: 'content_block_start', index: 0, content_block: { type: 'tool_use', id: 'toolu_1', name: 'Write' } }), stream) + translateCliOutput(streamEvent({ type: 'content_block_delta', index: 0, delta: { type: 'input_json_delta', partial_json: '{"file_pa' } }), stream) + + const retracted = translateCliOutput({ type: 'system', subtype: 'stream_retracted', uuid: 'u1' }, stream) + + expect(retracted.messages).toEqual([{ type: 'reply_retracted' }]) + expect(retracted.events).toEqual([{ type: 'turn_activity_reported', activity: 'thinking' }]) + expect(stream.activeBlockTypes.size).toBe(0) + expect(stream.activeToolBlocks.size).toBe(0) + expect(stream.streamedToolUseIds.size).toBe(0) + expect(stream.hasReceivedStreamEvents).toBe(false) + }) + + test('the turn goes back to thinking', () => { + const running = reduceSessionState(createSessionState('s1'), { type: 'turn_started', at: 1 }).state + const streaming = reduceSessionState(running, { type: 'turn_activity_reported', activity: 'streaming' }).state + + const event = translateCliOutput({ type: 'system', subtype: 'stream_retracted', uuid: 'u1' }, createStreamState()).events[0]! + + expect(reduceSessionState(streaming, event).state.turn.activity).toBe('thinking') + }) +}) diff --git a/src/server/__tests__/upstream-client.test.ts b/src/server/__tests__/upstream-client.test.ts index b8024e46..a62ac28e 100644 --- a/src/server/__tests__/upstream-client.test.ts +++ b/src/server/__tests__/upstream-client.test.ts @@ -194,12 +194,103 @@ describe('upstream client', () => { expect(text).toContain('message_stop') }) - test('reports upstream HTTP errors with status and body', async () => { + test('reports an upstream HTTP error with its status, an Anthropic error type and the plain body', async () => { mockFetch(() => new Response('model not found', { status: 404 })) const result = await sendToUpstream(target({ apiFormat: 'openai_chat' }), request) - expect(result).toEqual({ ok: false, httpStatus: 404, error: 'Upstream returned HTTP 404: model not found' }) + expect(result).toEqual({ ok: false, httpStatus: 404, errorType: 'not_found_error', error: 'model not found', headers: {} }) + }) + + test('reads the message out of a JSON error body and keeps the retry and request id headers', async () => { + mockFetch(() => Response.json( + { error: { message: 'Rate limit reached for gpt-4.1, please try again in 20s.', type: 'requests', code: 'rate_limit_exceeded' } }, + { status: 429, headers: { 'retry-after': '20', 'retry-after-ms': '20000', 'x-request-id': 'req_abc', 'set-cookie': 'a=b' } }, + )) + + const result = await sendToUpstream(target({ apiFormat: 'openai_chat' }), request) + + expect(result).toEqual({ + ok: false, + httpStatus: 429, + errorType: 'rate_limit_error', + error: 'Rate limit reached for gpt-4.1, please try again in 20s.', + headers: { 'retry-after': '20', 'retry-after-ms': '20000', 'x-request-id': 'req_abc', 'request-id': 'req_abc' }, + }) + }) + + test('keeps at most 500 characters of a long provider message', async () => { + mockFetch(() => Response.json({ error: { message: 'x'.repeat(5000) } }, { status: 500 })) + + const result = await sendToUpstream(target({ apiFormat: 'openai_chat' }), request) + + expect(result.ok === false && result.error).toBe('x'.repeat(500)) + }) + + test.each([ + ['OpenAI insufficient_quota', 429, { error: { message: 'You exceeded your current quota, please check your plan and billing details.', type: 'insufficient_quota', code: 'insufficient_quota' } }], + ['Moonshot exceeded_current_quota_error', 429, { error: { message: 'Your account has exceeded the current quota.', type: 'exceeded_current_quota_error' } }], + ['Zhipu 1113', 429, { error: { code: '1113', message: '余额不足或无可用资源包,请充值。' } }], + ['DeepSeek 402', 402, { error: { message: 'Insufficient Balance', type: 'unknown_error' } }], + ['OpenRouter 402', 402, { error: { message: 'Insufficient credits. Add more using https://openrouter.ai/settings/credits', code: 402 } }], + ])('reports %s as a billing error the CLI does not retry', async (_kind, status, body) => { + mockFetch(() => Response.json(body, { status })) + + const result = await sendToUpstream(target({ apiFormat: 'openai_chat' }), request) + + expect(result).toMatchObject({ ok: false, httpStatus: 402, errorType: 'billing_error', headers: { 'x-should-retry': 'false' } }) + }) + + test.each([ + [401, 'authentication_error'], + [403, 'permission_error'], + ] as const)('tells the CLI not to retry a %i from the provider', async (status, type) => { + mockFetch(() => Response.json({ error: { message: 'Incorrect API key provided', code: 'invalid_api_key' } }, { status })) + + const result = await sendToUpstream(target({ apiFormat: 'openai_chat' }), request) + + expect(result).toEqual({ + ok: false, + httpStatus: status, + errorType: type, + error: 'Incorrect API key provided', + headers: { 'x-should-retry': 'false' }, + }) + }) + + test.each([ + ['a quota error', { error: { message: 'You exceeded your current quota.', code: 'insufficient_quota' } }, 402, 'billing_error'], + ['an unknown error', { error: { message: 'something broke' } }, 502, 'api_error'], + ] as const)('maps %s inside a 2xx body by its content', async (_kind, body, status, type) => { + mockFetch(() => Response.json(body)) + + const result = await sendToUpstream(target({ apiFormat: 'openai_chat' }), request) + + expect(result).toMatchObject({ ok: false, httpStatus: status, errorType: type }) + }) + + test.each([ + [ + 'an OpenRouter message with token counts', + { error: { message: "This endpoint's maximum context length is 128000 tokens. However, you requested about 270016 tokens (270000 of text input, 16 in the output).", code: 400 } }, + "prompt is too long: 270016 tokens > 128000 maximum · This endpoint's maximum context length is 128000 tokens. However, you requested about 270016 tokens (270000 of text input, 16 in the output).", + ], + [ + 'an OpenAI error code', + { error: { message: 'Your input exceeds the context window of this model.', type: 'invalid_request_error', code: 'context_length_exceeded' } }, + 'prompt is too long · Your input exceeds the context window of this model.', + ], + [ + 'a Zhipu business code', + { error: { code: '1261', message: 'Prompt exceeds max length' } }, + 'prompt is too long · Prompt exceeds max length', + ], + ])('turns a context overflow reported as %s into the Anthropic prompt-too-long error', async (_kind, body, message) => { + mockFetch(() => Response.json(body, { status: 400 })) + + const result = await sendToUpstream(target({ apiFormat: 'openai_chat' }), request) + + expect(result).toEqual({ ok: false, httpStatus: 400, errorType: 'invalid_request_error', error: message, headers: {} }) }) test('rejects responses that do not match the declared format', async () => { @@ -214,6 +305,17 @@ describe('upstream client', () => { }) }) + test.each([ + ['content_filter', 400, 'invalid_request_error', "The provider's content filter stopped the reply (finish_reason: content_filter)."], + ['insufficient_system_resource', 502, 'api_error', 'The provider stopped the reply because of an error on its side (finish_reason: insufficient_system_resource).'], + ] as const)('reports a non-streaming reply that ended with %s as an error', async (reason, status, type, message) => { + mockFetch(() => Response.json({ ...openaiChatMessage, choices: [{ index: 0, message: { role: 'assistant', content: 'Hi' }, finish_reason: reason }] })) + + const result = await sendToUpstream(target({ apiFormat: 'openai_chat' }), request) + + expect(result).toEqual({ ok: false, httpStatus: status, errorType: type, error: message, headers: {} }) + }) + test('reports conversion failures as 502 instead of throwing', async () => { mockFetch(() => Response.json({ choices: [{}] })) @@ -431,7 +533,7 @@ describe('upstream client', () => { expect(upstreamEvents()).toHaveLength(1) expect(upstreamEvents()[0]!.severity).toBe('warn') - expect(upstreamEvents()[0]!.details).toMatchObject({ status: 429, outcome: 'error', error: 'Upstream returned HTTP 429: slow down' }) + expect(upstreamEvents()[0]!.details).toMatchObject({ status: 429, outcome: 'error', error: 'slow down' }) }) test('records an error reported in the middle of a stream when the stream ends', async () => { diff --git a/src/server/proxy/handler.ts b/src/server/proxy/handler.ts index 381c25b0..da4decc3 100644 --- a/src/server/proxy/handler.ts +++ b/src/server/proxy/handler.ts @@ -1,6 +1,7 @@ import { isClaudeModelName } from '../services/attributionHeaderPolicy.js' import { ProviderService } from '../services/providerService.js' import { sendToUpstream } from '../upstream/client.js' +import { anthropicErrorResponse } from '../upstream/upstreamError.js' import { ensureClaudeCodeAttribution } from './claudeCodeAttribution.js' import type { AnthropicRequest } from './transform/types.js' @@ -77,9 +78,9 @@ export async function handleProxyRequest(req: Request, url: URL, server: ProxySe }) if (!result.ok) { - return Response.json( - { type: 'error', error: { type: 'api_error', message: result.error } }, - { status: result.httpStatus ?? 502 }, + return anthropicErrorResponse( + { status: result.httpStatus ?? 502, type: result.errorType ?? 'api_error', message: result.error }, + result.headers, ) } diff --git a/src/server/proxy/streaming/openaiChatStreamToAnthropic.ts b/src/server/proxy/streaming/openaiChatStreamToAnthropic.ts index ed798203..e3fe4be3 100644 --- a/src/server/proxy/streaming/openaiChatStreamToAnthropic.ts +++ b/src/server/proxy/streaming/openaiChatStreamToAnthropic.ts @@ -1,6 +1,14 @@ -import type { OpenAIChatStreamChunk } from '../transform/types.js' +import type { OpenAIChatStreamChunk, OpenAIChatUsage } from '../transform/types.js' import { stringifyOpenAIToolArguments } from '../transform/toolArguments.js' -import { mapUsage } from '../transform/openaiChatToAnthropic.js' +import { chatUsage, mapChatFinishReason, mapUsage } from '../transform/openaiChatToAnthropic.js' +import { + anthropicErrorBody, + apiError, + readProviderError, + streamClosedEarlyError, + toAnthropicError, + type AnthropicError, +} from '../../upstream/upstreamError.js' import { parseSseJson, SseDecoder, type SseMessage } from './sse.js' type ContentBlockType = 'text' | 'thinking' | 'tool_use' @@ -35,7 +43,10 @@ type StreamState = { heldMessageDelta: SseEvent | null sawValidChunk: boolean - upstreamError: string | null + sawDone: boolean + sawUsage: boolean + stopReason: string | null + upstreamError: AnthropicError | null } function formatSse(event: string, data: unknown): string { @@ -58,6 +69,9 @@ function createState(model: string): StreamState { messageStopSent: false, heldMessageDelta: null, sawValidChunk: false, + sawDone: false, + sawUsage: false, + stopReason: null, upstreamError: null, } } @@ -119,6 +133,7 @@ function handleData( encoder: TextEncoder, ): void { if (data === '[DONE]') { + state.sawDone = true finalizeStream(state) flushQueue(state, controller, encoder) return @@ -136,6 +151,7 @@ function handleData( if (Array.isArray(chunk.choices)) state.sawValidChunk = true processChunk(chunk, state) + if (state.upstreamError) finalizeStream(state) flushQueue(state, controller, encoder) } @@ -259,70 +275,37 @@ function extractReasoning(delta: DeltaEx): { thinking: string; signature: string return null } -function detectBlockTransition( - delta: DeltaEx, - state: StreamState, -): { type: ContentBlockType; isNew: boolean } | null { - if (delta.tool_calls && delta.tool_calls.length > 0) { - const tc = delta.tool_calls[0] - const isNew = state.currentBlockType !== 'tool_use' || !!(tc.function?.name) - return { type: 'tool_use', isNew } - } - - if (delta.content != null && delta.content !== '') { - const isNew = state.currentBlockType !== 'text' || !state.blockStartSent - return { type: 'text', isNew } - } - - const reasoning = extractReasoning(delta) - if (reasoning) { - const isNew = state.currentBlockType !== 'thinking' || !state.blockStartSent - return { type: 'thinking', isNew } - } - - return null +function leaveBlockFor(type: ContentBlockType, state: StreamState): void { + if (!state.blockStartSent || state.blockStopSent || state.currentBlockType === type) return + if (state.currentBlockType === 'tool_use') closeAllToolBlocks(state) + else closeCurrentBlock(state) } function processChunk(chunk: OpenAIChatStreamChunk, state: StreamState): void { const choice = chunk.choices?.[0] - - if (!choice) { - if (chunk.usage && state.heldMessageDelta) { - mergeUsageIntoHeldDelta(state, chunk.usage) - } - return - } + const usage = chatUsage(chunk) + if (usage && state.heldMessageDelta) mergeUsageIntoHeldDelta(state, usage) + if (!choice) return ensureMessageStart(state, chunk.id) const delta = choice.delta as DeltaEx - const transition = detectBlockTransition(delta, state) - - if (transition) { - if (transition.isNew && state.blockStartSent && !state.blockStopSent) { - if (state.currentBlockType === 'tool_use' && transition.type !== 'tool_use') { - closeAllToolBlocks(state) - } else if (state.currentBlockType !== 'tool_use') { - closeCurrentBlock(state) - } - } - - switch (transition.type) { - case 'thinking': - handleThinking(delta, state) - break - case 'text': - handleText(delta, state) - break - case 'tool_use': - handleToolCalls(delta, state) - break - } + if (extractReasoning(delta)) { + leaveBlockFor('thinking', state) + handleThinking(delta, state) + } + if (delta.content != null && delta.content !== '') { + leaveBlockFor('text', state) + handleText(delta, state) + } + if (delta.tool_calls && delta.tool_calls.length > 0) { + leaveBlockFor('tool_use', state) + handleToolCalls(delta, state) } if (choice.finish_reason) { - handleFinishReason(choice.finish_reason, chunk, state) + handleFinishReason(choice.finish_reason, usage, state) } } @@ -423,29 +406,31 @@ function handleToolCalls(delta: DeltaEx, state: StreamState): void { function handleFinishReason( finishReason: string, - chunk: OpenAIChatStreamChunk, + usage: OpenAIChatUsage | undefined, state: StreamState, ): void { if (state.messageDeltaSent) return - closeAllOpenBlocks(state) + const finish = mapChatFinishReason(finishReason, state.sawToolUse) + if ('error' in finish) { + state.upstreamError = finish.error + return + } - let stopReason = mapFinishReason(finishReason) - // Gemini ends a tool-calling turn with finish_reason "stop"; clients that keep going only - // on stop_reason "tool_use" would otherwise not run the tools. - if (state.sawToolUse && stopReason === 'end_turn') stopReason = 'tool_use' - const usage = mapUsage(chunk.usage) + closeAllOpenBlocks(state) + state.stopReason = finish.stopReason const messageDelta: SseEvent = { event: 'message_delta', data: { type: 'message_delta', - delta: { stop_reason: stopReason, stop_sequence: null }, - usage, + delta: { stop_reason: finish.stopReason, stop_sequence: null }, + ...(usage && { usage: mapUsage(usage) }), }, } - if (chunk.usage) { + if (usage) { + state.sawUsage = true state.messageDeltaSent = true state.queue.push(messageDelta) } else { @@ -453,38 +438,42 @@ function handleFinishReason( } } -function mergeUsageIntoHeldDelta( - state: StreamState, - usage: NonNullable, -): void { +function mergeUsageIntoHeldDelta(state: StreamState, usage: OpenAIChatUsage): void { if (!state.heldMessageDelta) return const data = state.heldMessageDelta.data as Record data.usage = mapUsage(usage) + state.sawUsage = true state.messageDeltaSent = true state.queue.push(state.heldMessageDelta) state.heldMessageDelta = null } -function readUpstreamError(chunk: unknown): string | null { +function readUpstreamError(chunk: unknown): AnthropicError | null { const error = (chunk as { error?: unknown } | null)?.error if (!error || typeof error !== 'object') return null - const message = (error as { message?: unknown }).message - return typeof message === 'string' && message ? message : 'Upstream returned an error' + return toAnthropicError(undefined, readProviderError(chunk) ?? { message: 'Upstream returned an error' }) +} + +function endError(state: StreamState): AnthropicError | null { + if (state.upstreamError) return state.upstreamError + if (!state.sawValidChunk) return apiError('Upstream returned no valid Chat Completions chunks') + if (!state.sawDone && !state.messageDeltaSent && !state.heldMessageDelta) { + return streamClosedEarlyError() + } + if (state.nextContentIndex === 0 && !state.sawUsage && (state.stopReason ?? 'end_turn') === 'end_turn') { + return apiError('The provider returned an empty reply.') + } + return null } function finalizeStream(state: StreamState): void { if (state.messageStopSent) return state.messageStopSent = true - if (state.upstreamError || !state.sawValidChunk) { - enqueue(state, 'error', { - type: 'error', - error: { - type: 'api_error', - message: state.upstreamError ?? 'Upstream returned no valid Chat Completions chunks', - }, - }) + const error = endError(state) + if (error) { + enqueue(state, 'error', anthropicErrorBody(error)) return } @@ -502,20 +491,9 @@ function finalizeStream(state: StreamState): void { state.messageDeltaSent = true enqueue(state, 'message_delta', { type: 'message_delta', - delta: { stop_reason: 'end_turn', stop_sequence: null }, - usage: { output_tokens: 0 }, + delta: { stop_reason: state.sawToolUse ? 'tool_use' : 'end_turn', stop_sequence: null }, }) } enqueue(state, 'message_stop', { type: 'message_stop' }) } - -function mapFinishReason(reason: string): string { - switch (reason) { - case 'stop': return 'end_turn' - case 'tool_calls': return 'tool_use' - case 'length': return 'max_tokens' - case 'content_filter': return 'end_turn' - default: return 'end_turn' - } -} diff --git a/src/server/proxy/streaming/openaiResponsesStreamToAnthropic.ts b/src/server/proxy/streaming/openaiResponsesStreamToAnthropic.ts index 947a8852..9993bc5f 100644 --- a/src/server/proxy/streaming/openaiResponsesStreamToAnthropic.ts +++ b/src/server/proxy/streaming/openaiResponsesStreamToAnthropic.ts @@ -1,24 +1,26 @@ import { stringifyOpenAIToolArguments } from '../transform/toolArguments.js' -import { mapResponsesUsage } from '../transform/openaiResponsesToAnthropic.js' +import { mapResponsesStatus, mapResponsesUsage } from '../transform/openaiResponsesToAnthropic.js' import type { OpenAIResponsesUsage } from '../transform/types.js' +import { + anthropicErrorBody, + readProviderError, + streamClosedEarlyError, + toAnthropicError, + type AnthropicError, +} from '../../upstream/upstreamError.js' import { parseSseJson, SseDecoder, type SseMessage } from './sse.js' +type OpenBlock = { index: number; sent: boolean; closed: boolean } + type StreamState = { nextContentIndex: number - indexByKey: Map - toolIndexByItemId: Map - reasoningIndexByItemId: Map + texts: Map + tools: Map + reasoning: Map model: string messageStarted: boolean messageStopped: boolean -} - -export function upstreamErrorMessage(data: Record): string { - const response = data.response as Record | undefined - const error = (response?.error ?? data.error ?? data) as Record | undefined - return typeof error?.message === 'string' && error.message - ? error.message - : 'Upstream Responses stream failed' + emit: (event: string, data: unknown) => void } function formatSse(event: string, data: unknown): string { @@ -31,26 +33,25 @@ export function openaiResponsesStreamToAnthropic( ): ReadableStream { const encoder = new TextEncoder() const sse = new SseDecoder() - - const state: StreamState = { - nextContentIndex: 0, - indexByKey: new Map(), - toolIndexByItemId: new Map(), - reasoningIndexByItemId: new Map(), - model, - messageStarted: false, - messageStopped: false, - } - const reader = upstream.getReader() let cancelled = false return new ReadableStream({ async start(controller) { + const state: StreamState = { + nextContentIndex: 0, + texts: new Map(), + tools: new Map(), + reasoning: new Map(), + model, + messageStarted: false, + messageStopped: false, + emit: (event, data) => controller.enqueue(encoder.encode(formatSse(event, data))), + } const handle = (messages: SseMessage[]) => { for (const message of messages) { - if (message.type === 'event') handleEvent(message.event, message.data.trim(), state, controller, encoder) - else if (!state.messageStopped) controller.enqueue(encoder.encode(formatSse('ping', { type: 'ping' }))) + if (message.type === 'event') handleEvent(message.event, message.data.trim(), state) + else if (!state.messageStopped) state.emit('ping', { type: 'ping' }) } } @@ -62,8 +63,13 @@ export function openaiResponsesStreamToAnthropic( } handle(sse.flush()) - const body = sse.unframedBody() - if (body) emitUnframedError(body, controller, encoder) + if (!state.messageStopped) { + const unframed = sse.unframedBody() + const body = unframed ? parseSseJson(unframed) as Record | undefined : undefined + emitError(state, body?.error + ? errorFromEvent(body) + : streamClosedEarlyError()) + } } catch (err) { if (!cancelled) controller.error(err) return @@ -77,50 +83,34 @@ export function openaiResponsesStreamToAnthropic( }) } -function handleEvent( - event: string, - data: string, - state: StreamState, - controller: ReadableStreamDefaultController, - encoder: TextEncoder, -): void { +function handleEvent(event: string, data: string, state: StreamState): void { + if (state.messageStopped) return if (data === '[DONE]') { - if (!state.messageStopped) { - state.messageStopped = true - if (!state.messageStarted) { - emitMessageStart(state, controller, encoder) - } - controller.enqueue(encoder.encode(formatSse('message_stop', { type: 'message_stop' }))) - } + finishMessage(state, 'completed', undefined, undefined) return } const parsed = parseSseJson(data) - if (state.messageStopped || !parsed || typeof parsed !== 'object') return + if (!parsed || typeof parsed !== 'object') return const record = parsed as Record - processEvent(event || String(record.type ?? ''), record, state, controller, encoder) + processEvent(event || String(record.type ?? ''), record, state) } -function emitUnframedError( - body: string, - controller: ReadableStreamDefaultController, - encoder: TextEncoder, -): void { - const parsed = parseSseJson(body) as Record | undefined - if (!parsed || typeof parsed !== 'object' || !parsed.error) return - controller.enqueue(encoder.encode(formatSse('error', { - type: 'error', - error: { type: 'api_error', message: upstreamErrorMessage(parsed) }, - }))) +export function errorFromEvent(data: Record): AnthropicError { + const response = data.response as Record | undefined + const source = response?.error ? { error: response.error } : data.error || data.message ? data : undefined + return toAnthropicError(undefined, readProviderError(source) ?? { message: 'Upstream Responses stream failed' }) } -function emitMessageStart( - state: StreamState, - controller: ReadableStreamDefaultController, - encoder: TextEncoder, -): void { +function emitError(state: StreamState, error: AnthropicError): void { + state.messageStopped = true + state.emit('error', anthropicErrorBody(error)) +} + +function ensureMessageStart(state: StreamState): void { + if (state.messageStarted) return state.messageStarted = true - controller.enqueue(encoder.encode(formatSse('message_start', { + state.emit('message_start', { type: 'message_start', message: { id: `msg_${Date.now()}`, @@ -132,217 +122,199 @@ function emitMessageStart( stop_sequence: null, usage: { input_tokens: 0, output_tokens: 0 }, }, - }))) + }) +} + +function openBlock(state: StreamState, contentBlock: Record): OpenBlock { + ensureMessageStart(state) + const block = { index: state.nextContentIndex++, sent: false, closed: false } + state.emit('content_block_start', { type: 'content_block_start', index: block.index, content_block: contentBlock }) + return block +} + +function sendDelta(state: StreamState, block: OpenBlock, delta: Record): void { + block.sent = true + state.emit('content_block_delta', { type: 'content_block_delta', index: block.index, delta }) +} + +function closeBlock(state: StreamState, block: OpenBlock | undefined): void { + if (!block || block.closed) return + block.closed = true + state.emit('content_block_stop', { type: 'content_block_stop', index: block.index }) +} + +function textKey(data: Record, contentIndex = data.content_index): string { + return `${(data.output_index as number) ?? 0}:${(contentIndex as number) ?? 0}` +} + +function textBlock(state: StreamState, key: string): OpenBlock { + let block = state.texts.get(key) + if (!block) { + block = openBlock(state, { type: 'text', text: '' }) + state.texts.set(key, block) + } + return block +} + +function toolBlock(state: StreamState, item: Record): OpenBlock { + const itemId = (item.id as string) || (item.call_id as string) || '' + let block = state.tools.get(itemId) + if (!block) { + block = openBlock(state, { + type: 'tool_use', + id: (item.call_id as string) || itemId, + name: (item.name as string) || '', + input: {}, + }) + state.tools.set(itemId, block) + } + return block } -function processEvent( - event: string, - data: Record, +function completeText(state: StreamState, key: string, text: unknown): void { + const existing = state.texts.get(key) + if (!existing && !text) return + const block = existing ?? textBlock(state, key) + if (!block.sent && typeof text === 'string' && text) sendDelta(state, block, { type: 'text_delta', text }) + closeBlock(state, block) +} + +function completeTool(state: StreamState, block: OpenBlock, args: unknown): void { + const json = stringifyOpenAIToolArguments(args) + if (!block.sent && json) sendDelta(state, block, { type: 'input_json_delta', partial_json: json }) + closeBlock(state, block) +} + +function completeOutputItem(state: StreamState, data: Record): void { + const item = data.item as Record | undefined + if (item?.type === 'function_call') { + completeTool(state, toolBlock(state, item), item.arguments) + return + } + if (item?.type !== 'message' || !Array.isArray(item.content)) return + for (const [contentIndex, part] of (item.content as Array>).entries()) { + if (part.type === 'output_text' || part.type === 'refusal') { + completeText(state, textKey(data, contentIndex), part.text ?? part.refusal) + } + } +} + +function finishMessage( state: StreamState, - controller: ReadableStreamDefaultController, - encoder: TextEncoder, + status: string | undefined, + incompleteReason: string | undefined, + usage: OpenAIResponsesUsage | undefined, ): void { + const finish = mapResponsesStatus(status, incompleteReason, state.tools.size > 0) + if ('error' in finish) { + emitError(state, finish.error) + return + } + + ensureMessageStart(state) + const open = [...state.texts.values(), ...state.tools.values(), ...state.reasoning.values()] + .sort((a, b) => a.index - b.index) + for (const block of open) closeBlock(state, block) + + state.emit('message_delta', { + type: 'message_delta', + delta: { stop_reason: finish.stopReason, stop_sequence: null }, + ...(usage && { usage: mapResponsesUsage(usage) }), + }) + state.messageStopped = true + state.emit('message_stop', { type: 'message_stop' }) +} + +function processEvent(event: string, data: Record, state: StreamState): void { switch (event) { case 'response.created': { - emitMessageStart(state, controller, encoder) + ensureMessageStart(state) break } case 'response.output_item.added': { - if (!state.messageStarted) emitMessageStart(state, controller, encoder) + ensureMessageStart(state) const item = data.item as Record | undefined - if (!item) break - - if (item.type === 'function_call') { - const index = state.nextContentIndex++ - const callId = (item.call_id as string) || (item.id as string) || '' - const name = (item.name as string) || '' - state.toolIndexByItemId.set(item.id as string || callId, index) - - controller.enqueue(encoder.encode(formatSse('content_block_start', { - type: 'content_block_start', - index, - content_block: { - type: 'tool_use', - id: callId, - name, - input: {}, - }, - }))) - } + if (item?.type !== 'function_call') break + const block = toolBlock(state, item) + const json = stringifyOpenAIToolArguments(item.arguments) + if (json) sendDelta(state, block, { type: 'input_json_delta', partial_json: json }) break } case 'response.content_part.added': { - if (!state.messageStarted) emitMessageStart(state, controller, encoder) + ensureMessageStart(state) const part = data.part as Record | undefined - if (part?.type !== 'output_text' && part?.type !== 'refusal') break - - const contentIndex = (data.content_index as number) ?? 0 - const outputIndex = (data.output_index as number) ?? 0 - const key = `${outputIndex}:${contentIndex}` - const index = state.nextContentIndex++ - state.indexByKey.set(key, index) - - controller.enqueue(encoder.encode(formatSse('content_block_start', { - type: 'content_block_start', - index, - content_block: { type: 'text', text: '' }, - }))) - break - } - - case 'response.output_text.delta': { - const contentIndex = (data.content_index as number) ?? 0 - const outputIndex = (data.output_index as number) ?? 0 - const key = `${outputIndex}:${contentIndex}` - const index = state.indexByKey.get(key) - if (index === undefined) break - - const delta = (data.delta as string) || '' - controller.enqueue(encoder.encode(formatSse('content_block_delta', { - type: 'content_block_delta', - index, - delta: { type: 'text_delta', text: delta }, - }))) + if (part?.type === 'output_text' || part?.type === 'refusal') textBlock(state, textKey(data)) break } + case 'response.output_text.delta': case 'response.refusal.delta': { - const contentIndex = (data.content_index as number) ?? 0 - const outputIndex = (data.output_index as number) ?? 0 - const key = `${outputIndex}:${contentIndex}` - const index = state.indexByKey.get(key) - if (index === undefined) break - const delta = (data.delta as string) || '' - controller.enqueue(encoder.encode(formatSse('content_block_delta', { - type: 'content_block_delta', - index, - delta: { type: 'text_delta', text: delta }, - }))) + if (delta) sendDelta(state, textBlock(state, textKey(data)), { type: 'text_delta', text: delta }) break } case 'response.function_call_arguments.delta': { - const itemId = (data.item_id as string) || '' - const index = state.toolIndexByItemId.get(itemId) - if (index === undefined) break - + const block = state.tools.get((data.item_id as string) || '') const delta = stringifyOpenAIToolArguments(data.delta) - controller.enqueue(encoder.encode(formatSse('content_block_delta', { - type: 'content_block_delta', - index, - delta: { type: 'input_json_delta', partial_json: delta }, - }))) + if (block && delta) sendDelta(state, block, { type: 'input_json_delta', partial_json: delta }) break } case 'response.output_text.done': case 'response.refusal.done': { - const contentIndex = (data.content_index as number) ?? 0 - const outputIndex = (data.output_index as number) ?? 0 - const key = `${outputIndex}:${contentIndex}` - const index = state.indexByKey.get(key) - if (index === undefined) break - - controller.enqueue(encoder.encode(formatSse('content_block_stop', { - type: 'content_block_stop', - index, - }))) + completeText(state, textKey(data), data.text ?? data.refusal) break } case 'response.function_call_arguments.done': { - const itemId = (data.item_id as string) || '' - const index = state.toolIndexByItemId.get(itemId) - if (index === undefined) break + const block = state.tools.get((data.item_id as string) || '') + if (block) completeTool(state, block, data.arguments) + break + } - controller.enqueue(encoder.encode(formatSse('content_block_stop', { - type: 'content_block_stop', - index, - }))) + case 'response.output_item.done': { + completeOutputItem(state, data) break } case 'response.reasoning_summary_text.delta': case 'response.reasoning_text.delta': { const itemId = (data.item_id as string) || '' - let index = state.reasoningIndexByItemId.get(itemId) - if (index === undefined) { - index = state.nextContentIndex++ - state.reasoningIndexByItemId.set(itemId, index) - if (!state.messageStarted) emitMessageStart(state, controller, encoder) - controller.enqueue(encoder.encode(formatSse('content_block_start', { - type: 'content_block_start', - index, - content_block: { type: 'thinking', thinking: '' }, - }))) + let block = state.reasoning.get(itemId) + if (!block || block.closed) { + block = openBlock(state, { type: 'thinking', thinking: '' }) + state.reasoning.set(itemId, block) } - - const delta = (data.delta as string) || '' - controller.enqueue(encoder.encode(formatSse('content_block_delta', { - type: 'content_block_delta', - index, - delta: { type: 'thinking_delta', thinking: delta }, - }))) + sendDelta(state, block, { type: 'thinking_delta', thinking: (data.delta as string) || '' }) break } case 'response.reasoning_summary_text.done': case 'response.reasoning_text.done': case 'response.reasoning_summary_part.done': { - const itemId = (data.item_id as string) || '' - const index = state.reasoningIndexByItemId.get(itemId) - if (index === undefined) break - state.reasoningIndexByItemId.delete(itemId) - - controller.enqueue(encoder.encode(formatSse('content_block_stop', { - type: 'content_block_stop', - index, - }))) + closeBlock(state, state.reasoning.get((data.item_id as string) || '')) break } case 'response.failed': case 'error': { - const message = upstreamErrorMessage(data) - state.messageStopped = true - controller.enqueue(encoder.encode(formatSse('error', { - type: 'error', - error: { type: 'api_error', message }, - }))) + emitError(state, errorFromEvent(data)) break } case 'response.incomplete': case 'response.completed': { const response = data.response as Record | undefined - const status = (response?.status as string) || 'completed' - const usage = response?.usage as OpenAIResponsesUsage | undefined - const hasToolUse = state.toolIndexByItemId.size > 0 - - const stopReason = status === 'completed' - ? (hasToolUse ? 'tool_use' : 'end_turn') - : status === 'incomplete' ? 'max_tokens' : 'end_turn' - - for (const [, index] of state.reasoningIndexByItemId) { - controller.enqueue(encoder.encode(formatSse('content_block_stop', { - type: 'content_block_stop', - index, - }))) - } - state.reasoningIndexByItemId.clear() - - controller.enqueue(encoder.encode(formatSse('message_delta', { - type: 'message_delta', - delta: { stop_reason: stopReason, stop_sequence: null }, - usage: mapResponsesUsage(usage), - }))) - if (!state.messageStopped) { - state.messageStopped = true - controller.enqueue(encoder.encode(formatSse('message_stop', { type: 'message_stop' }))) - } + const details = response?.incomplete_details as { reason?: string } | undefined + finishMessage( + state, + (response?.status as string) || 'completed', + details?.reason, + response?.usage as OpenAIResponsesUsage | undefined, + ) break } } diff --git a/src/server/proxy/streaming/openaiResponsesStreamToAnthropicResponse.ts b/src/server/proxy/streaming/openaiResponsesStreamToAnthropicResponse.ts index bebba1ec..87df8d5c 100644 --- a/src/server/proxy/streaming/openaiResponsesStreamToAnthropicResponse.ts +++ b/src/server/proxy/streaming/openaiResponsesStreamToAnthropicResponse.ts @@ -1,5 +1,6 @@ import { openaiResponsesToAnthropic } from '../transform/openaiResponsesToAnthropic.js' -import { upstreamErrorMessage } from './openaiResponsesStreamToAnthropic.js' +import { UpstreamReplyError, type AnthropicError } from '../../upstream/upstreamError.js' +import { errorFromEvent } from './openaiResponsesStreamToAnthropic.js' import { parseSseJson, SseDecoder, type SseMessage } from './sse.js' import type { AnthropicResponse, @@ -14,8 +15,6 @@ type StreamFallbackState = { usage: OpenAIResponsesResponse['usage'] } -export class OpenAIResponsesStreamError extends Error {} - export async function openaiResponsesStreamToAnthropicResponse( upstream: ReadableStream, model: string, @@ -23,7 +22,7 @@ export async function openaiResponsesStreamToAnthropicResponse( const sse = new SseDecoder() const reader = upstream.getReader() let completedResponse: OpenAIResponsesResponse | null = null - let upstreamError: string | null = null + let upstreamError: AnthropicError | null = null const fallback: StreamFallbackState = { id: `resp_${Date.now()}`, @@ -43,7 +42,7 @@ export async function openaiResponsesStreamToAnthropicResponse( if (event === 'response.completed' || event === 'response.incomplete') { if (isOpenAIResponsesResponse(data.response)) completedResponse = data.response } else if (event === 'response.failed' || event === 'error') { - upstreamError = upstreamErrorMessage(data) + upstreamError = errorFromEvent(data) } else { updateFallbackState(event, data, fallback) } @@ -58,7 +57,7 @@ export async function openaiResponsesStreamToAnthropicResponse( handle(sse.flush()) if (!completedResponse && upstreamError !== null) { - throw new OpenAIResponsesStreamError(upstreamError) + throw new UpstreamReplyError(upstreamError) } return openaiResponsesToAnthropic( diff --git a/src/server/proxy/transform/openaiChatToAnthropic.ts b/src/server/proxy/transform/openaiChatToAnthropic.ts index 6335c90c..6a7e07f1 100644 --- a/src/server/proxy/transform/openaiChatToAnthropic.ts +++ b/src/server/proxy/transform/openaiChatToAnthropic.ts @@ -1,10 +1,19 @@ import type { OpenAIChatResponse, + OpenAIChatUsage, AnthropicResponse, AnthropicContentBlock, } from './types.js' +import { + contentFilterError, + providerSideError, + UpstreamReplyError, + type AnthropicError, +} from '../../upstream/upstreamError.js' import { parseOpenAIToolArguments } from './toolArguments.js' +export type ChatFinish = { stopReason: string } | { error: AnthropicError } + export function openaiChatToAnthropic(response: OpenAIChatResponse, model: string): AnthropicResponse { const choice = response.choices?.[0] if (!choice) { @@ -48,37 +57,53 @@ export function openaiChatToAnthropic(response: OpenAIChatResponse, model: strin content.push({ type: 'text', text: '' }) } + const finish = mapChatFinishReason(choice.finish_reason, content.some((block) => block.type === 'tool_use')) + if ('error' in finish) { + throw new UpstreamReplyError(finish.error) + } + return { id: response.id || `msg_${Date.now()}`, type: 'message', role: 'assistant', content, model, - stop_reason: mapStopReason(choice.finish_reason, content.some((block) => block.type === 'tool_use')), + stop_reason: finish.stopReason, stop_sequence: null, - usage: mapUsage(response.usage), + usage: mapUsage(chatUsage(response)), } } // Gemini ends a tool-calling turn with finish_reason "stop"; report tool_use whenever the // message carries tool_use blocks. -function mapStopReason(reason: string | null, hasToolUse: boolean): string { - const stopReason = mapFinishReason(reason) - return hasToolUse && stopReason === 'end_turn' ? 'tool_use' : stopReason -} - -function mapFinishReason(reason: string | null): string { +export function mapChatFinishReason(reason: string | null, hasToolUse: boolean): ChatFinish { switch (reason) { - case 'stop': return 'end_turn' - case 'tool_calls': return 'tool_use' - case 'length': return 'max_tokens' - case 'content_filter': return 'end_turn' - default: return 'end_turn' + case 'tool_calls': + case 'function_call': + return { stopReason: 'tool_use' } + case 'length': + return { stopReason: 'max_tokens' } + case 'model_context_window_exceeded': + return { stopReason: 'model_context_window_exceeded' } + case 'content_filter': + case 'sensitive': + return { error: contentFilterError(`finish_reason: ${reason}`) } + case 'network_error': + case 'insufficient_system_resource': + return { error: providerSideError(`finish_reason: ${reason}`) } + default: + return { stopReason: hasToolUse ? 'tool_use' : 'end_turn' } } } +export function chatUsage( + response: { usage?: OpenAIChatUsage; choices?: Array<{ usage?: OpenAIChatUsage }> }, +): OpenAIChatUsage | undefined { + return response.usage ?? response.choices?.[0]?.usage +} + // OpenAI counts cached tokens inside prompt_tokens; Anthropic's input_tokens excludes cache reads. -export function mapUsage(usage?: OpenAIChatResponse['usage']): AnthropicResponse['usage'] { +export function mapUsage(usage?: OpenAIChatUsage): AnthropicResponse['usage'] { if (!usage) { return { input_tokens: 0, output_tokens: 0 } } @@ -102,6 +127,6 @@ function createEmptyResponse(response: OpenAIChatResponse, model: string): Anthr model, stop_reason: 'end_turn', stop_sequence: null, - usage: mapUsage(response.usage), + usage: mapUsage(chatUsage(response)), } } diff --git a/src/server/proxy/transform/openaiResponsesToAnthropic.ts b/src/server/proxy/transform/openaiResponsesToAnthropic.ts index a8d1956f..138ffe74 100644 --- a/src/server/proxy/transform/openaiResponsesToAnthropic.ts +++ b/src/server/proxy/transform/openaiResponsesToAnthropic.ts @@ -5,6 +5,12 @@ import type { AnthropicResponse, AnthropicContentBlock, } from './types.js' +import { + apiError, + contentFilterError, + UpstreamReplyError, +} from '../../upstream/upstreamError.js' +import type { ChatFinish } from './openaiChatToAnthropic.js' import { parseOpenAIToolArguments } from './toolArguments.js' export function openaiResponsesToAnthropic(response: OpenAIResponsesResponse, model: string): AnthropicResponse { @@ -20,13 +26,18 @@ export function openaiResponsesToAnthropic(response: OpenAIResponsesResponse, mo content.push({ type: 'text', text: '' }) } + const finish = mapResponsesStatus(response.status, response.incomplete_details?.reason, hasToolUse) + if ('error' in finish) { + throw new UpstreamReplyError(finish.error) + } + return { id: response.id || `msg_${Date.now()}`, type: 'message', role: 'assistant', content, model, - stop_reason: mapStatus(response.status, hasToolUse), + stop_reason: finish.stopReason, stop_sequence: null, usage: mapResponsesUsage(response.usage), } @@ -80,12 +91,9 @@ function convertOutputItem(item: OpenAIResponsesOutputItem, content: AnthropicCo } } -function mapStatus(status: string, hasToolUse: boolean): string { - switch (status) { - case 'completed': return hasToolUse ? 'tool_use' : 'end_turn' - case 'failed': return 'end_turn' - case 'cancelled': return 'end_turn' - case 'incomplete': return 'max_tokens' - default: return 'end_turn' - } +export function mapResponsesStatus(status: string | undefined, incompleteReason: string | undefined, hasToolUse: boolean): ChatFinish { + if (status !== 'incomplete') return { stopReason: hasToolUse ? 'tool_use' : 'end_turn' } + if (!incompleteReason || incompleteReason === 'max_output_tokens') return { stopReason: 'max_tokens' } + if (incompleteReason === 'content_filter') return { error: contentFilterError(`incomplete: ${incompleteReason}`) } + return { error: apiError(`The provider ended the reply before it finished (incomplete: ${incompleteReason}).`) } } diff --git a/src/server/proxy/transform/toolArguments.ts b/src/server/proxy/transform/toolArguments.ts index 60c7ea8e..5b802eab 100644 --- a/src/server/proxy/transform/toolArguments.ts +++ b/src/server/proxy/transform/toolArguments.ts @@ -1,24 +1,17 @@ +import { parseSseJson } from '../streaming/sse.js' import type { AnthropicContentBlock } from './types.js' function isRecord(value: unknown): value is Record { return typeof value === 'object' && value !== null && !Array.isArray(value) } -export function parseOpenAIToolArguments(value: unknown): Record { - if (value == null || value === '') return {} - - if (typeof value === 'string') { - try { - const parsed = JSON.parse(value) as unknown - return isRecord(parsed) ? parsed : { raw: parsed } - } catch { - return { raw: value } - } - } - +export function parseOpenAIToolArguments(value: unknown): Record | string { + if (value == null || (typeof value === 'string' && value.trim() === '')) return {} if (isRecord(value)) return value - - return { raw: value } + const raw = typeof value === 'string' ? value : JSON.stringify(value) + const parsed = parseSseJson(raw) + if (parsed === null) return {} + return isRecord(parsed) ? parsed : raw } export function stringifyOpenAIToolArguments(value: unknown): string { diff --git a/src/server/proxy/transform/types.ts b/src/server/proxy/transform/types.ts index 37558146..54fdc6c7 100644 --- a/src/server/proxy/transform/types.ts +++ b/src/server/proxy/transform/types.ts @@ -59,17 +59,20 @@ export type OpenAIChatResponse = { tool_calls?: OpenAIToolCall[] } finish_reason: string | null + usage?: OpenAIChatUsage }> - usage?: { - prompt_tokens: number - completion_tokens: number - total_tokens: number - prompt_tokens_details?: { - cached_tokens?: number - } - prompt_cache_hit_tokens?: number + usage?: OpenAIChatUsage +} + +export type OpenAIChatUsage = { + prompt_tokens: number + completion_tokens: number + total_tokens: number + prompt_tokens_details?: { cached_tokens?: number } + prompt_cache_hit_tokens?: number + cached_tokens?: number } export type OpenAIChatStreamChunk = { @@ -93,8 +96,9 @@ export type OpenAIChatStreamChunk = { }> } finish_reason: string | null + usage?: OpenAIChatUsage }> - usage?: OpenAIChatResponse['usage'] + usage?: OpenAIChatUsage } export type OpenAIResponsesContentPart = @@ -140,6 +144,7 @@ export type OpenAIResponsesResponse = { created_at: number model: string status: string + incomplete_details?: { reason?: string } | null output: OpenAIResponsesOutputItem[] usage?: OpenAIResponsesUsage } @@ -154,7 +159,7 @@ export type OpenAIResponsesUsage = { export type AnthropicContentBlock = | { type: 'text'; text: string; cache_control?: unknown } | { type: 'image'; source: { type: 'base64'; media_type: string; data: string }; cache_control?: unknown } - | { type: 'tool_use'; id: string; name: string; input: Record; cache_control?: unknown } + | { type: 'tool_use'; id: string; name: string; input: Record | string; cache_control?: unknown } | { type: 'tool_result'; tool_use_id: string; content: string | AnthropicContentBlock[]; is_error?: boolean; cache_control?: unknown } | { type: 'thinking'; thinking: string; signature?: string } diff --git a/src/server/services/networkSettings.ts b/src/server/services/networkSettings.ts index 4c354c81..ed9bd0a4 100644 --- a/src/server/services/networkSettings.ts +++ b/src/server/services/networkSettings.ts @@ -82,6 +82,7 @@ export function buildNetworkEnvironment( const timeout = String(settings.aiRequestTimeoutMs) return { API_TIMEOUT_MS: timeout, + CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK: '1', CLAUDE_ENABLE_STREAM_WATCHDOG: '1', CLAUDE_STREAM_IDLE_TIMEOUT_MS: timeout, ...buildProxyEnvironment(settings, inheritedEnv), diff --git a/src/server/services/providerService.ts b/src/server/services/providerService.ts index 37cc329d..f095b49f 100644 --- a/src/server/services/providerService.ts +++ b/src/server/services/providerService.ts @@ -18,6 +18,7 @@ import { } from './providerRuntimeEnv.js' import { loadNetworkSettings } from './networkSettings.js' import { fetchUpstreamModels, resolveUpstreamTarget, sendToUpstream, type UpstreamTarget } from '../upstream/client.js' +import { describeFailure } from '../upstream/upstreamError.js' import type { SavedProvider, ProvidersIndex, @@ -321,7 +322,7 @@ export class ProviderService { const result = await fetchUpstreamModels(target, presetId) if (!result.ok) { const upstreamRejected = result.httpStatus !== undefined && result.httpStatus >= 400 && result.httpStatus < 500 - throw new ApiError(upstreamRejected ? 400 : 502, result.error, 'MODEL_DISCOVERY_FAILED') + throw new ApiError(upstreamRejected ? 400 : 502, describeFailure(result), 'MODEL_DISCOVERY_FAILED') } return result.models } @@ -368,7 +369,7 @@ export class ProviderService { connectivity: { success: false, latencyMs: Date.now() - start, - error: result.error, + error: describeFailure(result), modelUsed: modelId, httpStatus: result.httpStatus, }, diff --git a/src/server/services/titleService.ts b/src/server/services/titleService.ts index 1c7cf91e..d3596e63 100644 --- a/src/server/services/titleService.ts +++ b/src/server/services/titleService.ts @@ -3,6 +3,7 @@ import { SettingsService } from './settingsService.js' import { sessionService } from './sessionService.js' import { cleanSessionTitleSource, hasSessionTitleMarkup } from '../../utils/sessionTitleText.js' import { resolveUpstreamTarget, sendToUpstream } from '../upstream/client.js' +import { describeFailure } from '../upstream/upstreamError.js' const TITLE_MAX_LEN = 50 const TITLE_MAX_OUTPUT_TOKENS = 100 @@ -89,7 +90,7 @@ export async function generateTitle( }, { timeoutMs: 15_000 }) if (!result.ok) { - return fail(excerptForLog(result.error)) + return fail(excerptForLog(describeFailure(result))) } if (!('message' in result)) return fail('upstream returned a stream') const block = result.message.content.find((b) => b.type === 'text') diff --git a/src/server/session/translate.ts b/src/server/session/translate.ts index 2ea19d54..97a7af7a 100644 --- a/src/server/session/translate.ts +++ b/src/server/session/translate.ts @@ -463,6 +463,15 @@ function translateMessages( case 'system': { const subtype = cliMsg.subtype + if (subtype === 'stream_retracted') { + streamState.hasReceivedStreamEvents = false + streamState.activeBlockTypes.clear() + streamState.activeToolBlocks.clear() + streamState.pendingToolBlocks.clear() + streamState.streamedToolUseIds.clear() + events.push({ type: 'turn_activity_reported', activity: 'thinking' }) + return [{ type: 'reply_retracted' }] + } if (subtype === 'api_retry') { const apiRetryMessage = toApiRetryServerMessage(cliMsg) return apiRetryMessage ? [apiRetryMessage] : [] diff --git a/src/server/upstream/anthropicStream.ts b/src/server/upstream/anthropicStream.ts index b1fc377a..16cd4364 100644 --- a/src/server/upstream/anthropicStream.ts +++ b/src/server/upstream/anthropicStream.ts @@ -1,5 +1,6 @@ import { parseSseJson, SseDecoder, type SseMessage } from '../proxy/streaming/sse.js' import type { UpstreamOutcome } from './requestLog.js' +import { anthropicErrorBody, apiError } from './upstreamError.js' export function superviseAnthropicStream( stream: ReadableStream, @@ -39,10 +40,7 @@ export function superviseAnthropicStream( timer = setTimeout(() => { const message = `No response from the provider for ${Math.round(idleTimeoutMs / 1000)}s` if (!finish({ outcome: 'idle_timeout', error: message })) return - controller.enqueue(encoder.encode(`event: error\ndata: ${JSON.stringify({ - type: 'error', - error: { type: 'api_error', message }, - })}\n\n`)) + controller.enqueue(encoder.encode(`event: error\ndata: ${JSON.stringify(anthropicErrorBody(apiError(message)))}\n\n`)) controller.close() reader.cancel(new DOMException('Stream idle timeout', 'TimeoutError')).catch((err: unknown) => { console.error('[Upstream] Cancelling the provider stream after an idle timeout failed:', err) diff --git a/src/server/upstream/client.ts b/src/server/upstream/client.ts index b138e4f6..e91178a6 100644 --- a/src/server/upstream/client.ts +++ b/src/server/upstream/client.ts @@ -21,6 +21,13 @@ import { } from '../services/providerRuntimeEnv.js' import type { ApiFormat, ProviderAuthStrategy, DiscoveredProviderModel, SavedProvider } from '../types/provider.js' import { normalizeUpstreamBaseUrl, openaiUpstreamBaseUrl } from './baseUrl.js' +import { + toFailure, + upstreamBodyFailure, + upstreamHttpFailure, + UpstreamReplyError, + type UpstreamFailure, +} from './upstreamError.js' import { fillContextWindows } from './contextWindows/index.js' import { superviseAnthropicStream } from './anthropicStream.js' import { @@ -43,11 +50,11 @@ export type UpstreamTarget = { export type UpstreamResult = | { ok: true; httpStatus: number; message: AnthropicResponse } | { ok: true; httpStatus: number; stream: ReadableStream } - | { ok: false; httpStatus?: number; error: string } + | UpstreamFailure export type UpstreamModelsResult = | { ok: true; httpStatus: number; models: DiscoveredProviderModel[] } - | { ok: false; httpStatus?: number; error: string } + | UpstreamFailure type UpstreamRequest = { url: string @@ -146,12 +153,7 @@ async function requestUpstream( responseInfo.headersMs = Date.now() - startedAt if (!response.ok) { - const errText = await response.text().catch(() => '') - return { - ok: false, - httpStatus: response.status, - error: `Upstream returned HTTP ${response.status}: ${errText.slice(0, 500)}`, - } + return upstreamHttpFailure(response.status, await response.text().catch(() => ''), response.headers) } if (isStream) { @@ -166,6 +168,7 @@ async function requestUpstream( } const body = await response.json().catch(() => null) as Record | null + if (body?.error && typeof body.error === 'object') return upstreamBodyFailure(body) const invalid = validateResponseBody(body, target.apiFormat) if (invalid) { return { ok: false, httpStatus: 502, error: invalid } @@ -177,6 +180,7 @@ async function requestUpstream( message: toAnthropicMessage(target.apiFormat, body!, anthropicRequest.model), } } catch (err) { + if (err instanceof UpstreamReplyError) return toFailure(err.error, {}) return { ok: false, httpStatus: 502, error: err instanceof Error ? err.message : String(err) } } } @@ -221,12 +225,7 @@ export async function fetchUpstreamModels(target: UpstreamTarget, presetId?: str } if (!response.ok) { - const errText = await response.text().catch(() => '') - return { - ok: false, - httpStatus: response.status, - error: `Upstream returned HTTP ${response.status}: ${errText.slice(0, 500)}`, - } + return upstreamHttpFailure(response.status, await response.text().catch(() => ''), response.headers) } const body = await response.json().catch(() => null) as Record | null @@ -390,9 +389,6 @@ function toAnthropicMessage( function validateResponseBody(body: Record | null, format: ApiFormat): string | null { if (!body) return 'Empty response — not a valid API endpoint' - if (body.error && typeof body.error === 'object') { - return ((body.error as Record).message as string) || 'Error in response body' - } if (format === 'openai_chat') { return Array.isArray(body.choices) && body.choices.length > 0 ? null diff --git a/src/server/upstream/upstreamError.ts b/src/server/upstream/upstreamError.ts new file mode 100644 index 00000000..33792c92 --- /dev/null +++ b/src/server/upstream/upstreamError.ts @@ -0,0 +1,150 @@ +import { classifyProviderError, toPromptTooLongMessage } from '../../utils/providerErrors.js' +import { parseSseJson } from '../proxy/streaming/sse.js' + +export type AnthropicErrorType = + | 'invalid_request_error' + | 'authentication_error' + | 'billing_error' + | 'permission_error' + | 'not_found_error' + | 'request_too_large' + | 'rate_limit_error' + | 'api_error' + | 'overloaded_error' + +export type UpstreamFailure = { + ok: false + httpStatus?: number + error: string + errorType?: AnthropicErrorType + headers?: Record +} + +type ProviderError = { message: string; code?: string } + +export type AnthropicError = { status: number; type: AnthropicErrorType; message: string; retryable?: false } + +export class UpstreamReplyError extends Error { + constructor(readonly error: AnthropicError) { + super(error.message) + } +} + +export function anthropicErrorBody(error: { type: AnthropicErrorType; message: string }) { + return { type: 'error', error: { type: error.type, message: error.message } } +} + +export function anthropicErrorResponse(error: AnthropicError, headers?: Record): Response { + return Response.json(anthropicErrorBody(error), { status: error.status, headers }) +} + +const MAX_PROVIDER_MESSAGE_CHARS = 500 + +export function apiError(message: string): AnthropicError { + return { status: 502, type: 'api_error', message } +} + +export function streamClosedEarlyError(): AnthropicError { + return apiError('The provider closed the stream before the reply finished.') +} + +export function contentFilterError(detail: string): AnthropicError { + return { status: 400, type: 'invalid_request_error', message: `The provider's content filter stopped the reply (${detail}).` } +} + +export function providerSideError(detail: string): AnthropicError { + return apiError(`The provider stopped the reply because of an error on its side (${detail}).`) +} + +const PASSED_HEADERS = ['retry-after', 'retry-after-ms', 'x-request-id'] + +export function readProviderError(body: unknown): ProviderError | undefined { + if (!body || typeof body !== 'object') return undefined + const record = body as Record + const nested = record.error + const source = nested && typeof nested === 'object' ? nested as Record : record + const message = [source.message, typeof nested === 'string' ? nested : undefined, record.message, record.msg] + .find((value): value is string => typeof value === 'string' && value.length > 0) + const code = [source.code, source.type, record.code].find( + (value): value is string | number => typeof value === 'string' || typeof value === 'number', + ) + if (!message && code === undefined) return undefined + return { + message: (message ?? String(code)).slice(0, MAX_PROVIDER_MESSAGE_CHARS), + ...(code !== undefined && { code: String(code) }), + } +} + +export function toAnthropicError(status: number | undefined, error: ProviderError): AnthropicError { + const { message } = error + switch (classifyProviderError({ status, ...error })) { + case 'context_overflow': + return { status: 400, type: 'invalid_request_error', message: toPromptTooLongMessage(message) } + case 'quota': + return { status: 402, type: 'billing_error', message, retryable: false } + case 'auth': + return status === 403 + ? { status, type: 'permission_error', message, retryable: false } + : { status: 401, type: 'authentication_error', message, retryable: false } + case 'rate_limit': + return { status: 429, type: 'rate_limit_error', message } + } + return status === undefined + ? apiError(message) + : { status, type: errorTypeForStatus(status), message } +} + +export function upstreamHttpFailure(status: number, text: string, headers: Headers): UpstreamFailure { + const error = readProviderError(parseSseJson(text)) ?? { message: text.trim().slice(0, MAX_PROVIDER_MESSAGE_CHARS) || `HTTP ${status}` } + return toFailure(toAnthropicError(status, error), passedHeaders(headers)) +} + +export function upstreamBodyFailure(body: unknown): UpstreamFailure { + const error = readProviderError(body) ?? { message: 'Error in response body' } + return toFailure(toAnthropicError(undefined, error), {}) +} + +export function describeFailure(failure: UpstreamFailure): string { + const status = failure.httpStatus ? `HTTP ${failure.httpStatus}` : '' + if (!status || failure.error === status) return failure.error || status + return `${status}: ${failure.error}` +} + +export function toFailure(error: AnthropicError, headers: Record): UpstreamFailure { + return { + ok: false, + httpStatus: error.status, + errorType: error.type, + error: error.message, + headers: error.retryable === false ? { ...headers, 'x-should-retry': 'false' } : headers, + } +} + +function errorTypeForStatus(status: number): AnthropicErrorType { + switch (status) { + case 400: + case 422: + return 'invalid_request_error' + case 404: + return 'not_found_error' + case 413: + return 'request_too_large' + case 429: + return 'rate_limit_error' + case 529: + return 'overloaded_error' + default: + return 'api_error' + } +} + +function passedHeaders(headers: Headers): Record { + const passed: Record = {} + for (const name of PASSED_HEADERS) { + const value = headers.get(name) + if (value) passed[name] = value + } + const requestId = passed['x-request-id'] ?? headers.get('request-id') + if (requestId) passed['request-id'] = requestId + return passed +} diff --git a/src/server/ws/protocol.ts b/src/server/ws/protocol.ts index b75755ee..7167395b 100644 --- a/src/server/ws/protocol.ts +++ b/src/server/ws/protocol.ts @@ -108,6 +108,7 @@ export type ServerMessage = | { type: 'tool_result'; toolUseId: string; content: unknown; isError: boolean; parentToolUseId?: string } | { type: 'permission_resolved'; requestId: string; allowed: boolean; by: ClientKind } | { type: 'message_complete'; usage: TokenUsage } + | { type: 'reply_retracted' } | { type: 'thinking'; text: string } | { type: 'api_retry' diff --git a/src/services/api/__tests__/contextOverflow.test.ts b/src/services/api/__tests__/contextOverflow.test.ts new file mode 100644 index 00000000..fa4047de --- /dev/null +++ b/src/services/api/__tests__/contextOverflow.test.ts @@ -0,0 +1,70 @@ +import { afterAll, beforeAll, describe, expect, test } from 'bun:test' +import { APIError } from '@anthropic-ai/sdk' +import { truncateHeadForPTLRetry } from '../../compact/compact.js' +import { createAssistantMessage, createUserMessage } from '../../../utils/messages.js' +import type { Message } from '../../../types/message.js' +import { classifyAPIError, getAssistantMessageFromError, isPromptTooLongMessage } from '../errors.js' + +const openRouterOverflow = + "This endpoint's maximum context length is 128000 tokens. However, you requested about 270016 tokens (270000 of text input, 16 in the output). Please reduce the length of the input, or use the context-compression plugin to compress your prompt automatically." + +function apiError(status: number | undefined, message: string): APIError { + const body = { type: 'error', error: { type: 'invalid_request_error', message } } + return new APIError(status, body, undefined, new Headers()) +} + +function conversation(): Message[] { + const turn = 'x'.repeat(80_000) + const messages: Message[] = [createUserMessage({ content: turn })] + for (let i = 0; i < 10; i += 1) { + messages.push(createAssistantMessage({ content: `step ${i}` })) + messages.push(createUserMessage({ content: turn })) + } + return messages +} + +describe('context overflow from third-party providers', () => { + let originalApiKey: string | undefined + + beforeAll(() => { + originalApiKey = process.env.ANTHROPIC_API_KEY + process.env.ANTHROPIC_API_KEY = 'sk-test' + }) + + afterAll(() => { + if (originalApiKey === undefined) delete process.env.ANTHROPIC_API_KEY + else process.env.ANTHROPIC_API_KEY = originalApiKey + }) + + test.each([ + ['the proxy', 400, 'prompt is too long: 270016 tokens > 128000 maximum · ' + openRouterOverflow], + ['a direct provider', 400, openRouterOverflow], + ['a direct provider stream', undefined, openRouterOverflow], + ])('an overflow reported by %s drops enough old rounds to fit on the compact retry', (_source, status, message) => { + const error = apiError(status, message) + + const reply = getAssistantMessageFromError(error, 'gpt-4o-mini') + const truncated = truncateHeadForPTLRetry(conversation(), reply) + + expect(isPromptTooLongMessage(reply)).toBe(true) + expect(classifyAPIError(error)).toBe('prompt_too_long') + expect(truncated).toHaveLength(7) + }) + + test.each([ + 'Your input exceeds the context window of this model. Please adjust your input and try again.', + 'Range of input length should be [1, 129024]', + 'The input token count (1200000) exceeds the maximum number of tokens allowed (1048576).', + 'Invalid request: Your request exceeded model token limit: 131072', + 'Invalid request: total message token length 140000 exceed model limit 131072', + 'Prompt exceeds max length', + ])('recognizes "%s" as a context overflow', (message) => { + expect(isPromptTooLongMessage(getAssistantMessageFromError(apiError(400, message), 'model'))).toBe(true) + }) + + test('does not treat an unrelated 400 as a context overflow', () => { + const reply = getAssistantMessageFromError(apiError(400, 'max_tokens must be at most 8192'), 'model') + + expect(isPromptTooLongMessage(reply)).toBe(false) + }) +}) diff --git a/src/services/api/__tests__/providerRetry.test.ts b/src/services/api/__tests__/providerRetry.test.ts new file mode 100644 index 00000000..c110538a --- /dev/null +++ b/src/services/api/__tests__/providerRetry.test.ts @@ -0,0 +1,95 @@ +import { afterEach, beforeEach, describe, expect, test } from 'bun:test' +import Anthropic, { APIError } from '@anthropic-ai/sdk' +import { CannotRetryError, withRetry } from '../withRetry.js' + +const ENV_KEYS = ['ANTHROPIC_API_KEY', 'ANTHROPIC_BASE_URL'] as const +let savedEnv: Partial> + +function errorBody(message: string, type = 'api_error', code?: string) { + return { type: 'error', error: { type, message, ...(code && { code }) } } +} + +async function firstOutcome(error: APIError): Promise<{ retried: boolean; retryInMs?: number; attempts: number }> { + let attempts = 0 + const generator = withRetry( + async () => ({}) as Anthropic, + async () => { + attempts += 1 + throw error + }, + { model: 'model-main', thinkingConfig: { type: 'disabled' }, maxRetries: 3 }, + ) + try { + const step = await generator.next() + const message = step.value as { retryInMs?: number } + await generator.return(undefined as never) + return { retried: true, retryInMs: message.retryInMs, attempts } + } catch (err) { + expect(err).toBeInstanceOf(CannotRetryError) + return { retried: false, attempts } + } +} + +describe('retrying provider errors', () => { + beforeEach(() => { + savedEnv = Object.fromEntries(ENV_KEYS.map((key) => [key, process.env[key]])) + process.env.ANTHROPIC_API_KEY = 'sk-test' + delete process.env.ANTHROPIC_BASE_URL + }) + + afterEach(() => { + for (const key of ENV_KEYS) { + if (savedEnv[key] === undefined) delete process.env[key] + else process.env[key] = savedEnv[key] + } + }) + + test('does not retry a quota error the proxy reports as 402', async () => { + process.env.ANTHROPIC_BASE_URL = 'http://127.0.0.1:3456/proxy' + const error = APIError.generate( + 402, + errorBody('You exceeded your current quota, please check your plan and billing details.', 'billing_error'), + undefined, + new Headers({ 'x-should-retry': 'false' }), + ) + + expect(await firstOutcome(error)).toEqual({ retried: false, attempts: 1 }) + }) + + test('does not retry a quota error a direct third-party provider reports as 429', async () => { + process.env.ANTHROPIC_BASE_URL = 'https://api.moonshot.cn/anthropic' + const error = APIError.generate( + 429, + errorBody('Your account has exceeded the current quota.', 'exceeded_current_quota_error'), + undefined, + new Headers(), + ) + + expect(await firstOutcome(error)).toEqual({ retried: false, attempts: 1 }) + }) + + test('does not retry a 401 from a direct third-party provider', async () => { + process.env.ANTHROPIC_BASE_URL = 'https://open.bigmodel.cn/api/anthropic' + const error = APIError.generate(401, errorBody('invalid api key', 'authentication_error'), undefined, new Headers()) + + expect(await firstOutcome(error)).toEqual({ retried: false, attempts: 1 }) + }) + + test('keeps retrying a 401 on the Anthropic API', async () => { + const error = APIError.generate(401, errorBody('invalid x-api-key', 'authentication_error'), undefined, new Headers()) + + expect(await firstOutcome(error)).toMatchObject({ retried: true, attempts: 1 }) + }) + + test('waits as long as the retry-after header the proxy passes on', async () => { + process.env.ANTHROPIC_BASE_URL = 'http://127.0.0.1:3456/proxy' + const error = APIError.generate( + 429, + errorBody('Rate limit reached, please try again in 20s.', 'rate_limit_error'), + undefined, + new Headers({ 'retry-after': '20' }), + ) + + expect(await firstOutcome(error)).toEqual({ retried: true, retryInMs: 20_000, attempts: 1 }) + }) +}) diff --git a/src/services/api/__tests__/streamRetry.test.ts b/src/services/api/__tests__/streamRetry.test.ts new file mode 100644 index 00000000..7128a3ca --- /dev/null +++ b/src/services/api/__tests__/streamRetry.test.ts @@ -0,0 +1,218 @@ +import { afterEach, beforeEach, describe, expect, spyOn, test } from 'bun:test' +import { mkdtemp, rm } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { getEmptyToolPermissionContext } from '../../../Tool.js' +import * as sessionActivity from '../../../utils/sessionActivity.js' +import { createUserMessage } from '../../../utils/messages.js' +import { asSystemPrompt } from '../../../utils/systemPromptType.js' +import { queryModelWithStreaming } from '../claude.js' + +const ENV_KEYS = [ + 'ANTHROPIC_API_KEY', + 'ANTHROPIC_BASE_URL', + 'CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK', + 'CLAUDE_CODE_MAX_RETRIES', + 'CLAUDE_CODE_TEST_FIXTURES_ROOT', + 'VCR_RECORD', +] as const +let savedEnv: Partial> +let fixturesDir: string +let starts: ReturnType +let stops: ReturnType +let server: ReturnType | undefined + +function sse(event: string, data: Record): string { + return `event: ${event}\ndata: ${JSON.stringify({ type: event, ...data })}\n\n` +} + +const messageStart = sse('message_start', { + message: { + id: 'msg_1', type: 'message', role: 'assistant', content: [], model: 'claude-sonnet-4-5', + stop_reason: null, stop_sequence: null, usage: { input_tokens: 10, output_tokens: 0 }, + }, +}) + +function textReply(text: string): string { + return messageStart + + sse('content_block_start', { index: 0, content_block: { type: 'text', text: '' } }) + + sse('content_block_delta', { index: 0, delta: { type: 'text_delta', text } }) + + sse('content_block_stop', { index: 0 }) + + sse('message_delta', { delta: { stop_reason: 'end_turn', stop_sequence: null }, usage: { output_tokens: 5 } }) + + sse('message_stop', {}) +} + +function brokenReply(errorType: string): string { + return messageStart + + sse('content_block_start', { index: 0, content_block: { type: 'text', text: '' } }) + + sse('content_block_delta', { index: 0, delta: { type: 'text_delta', text: 'Half an ans' } }) + + sse('content_block_stop', { index: 0 }) + + `event: error\ndata: ${JSON.stringify({ type: 'error', error: { type: errorType, message: 'the stream broke' } })}\n\n` +} + +const overloaded = { status: 500, body: JSON.stringify({ type: 'error', error: { type: 'api_error', message: 'try again' } }) } + +type Reply = string | { status: number; body: string } | { openEnded: string } + +function reply(body: Reply): Response { + if (typeof body === 'string') return new Response(body, { headers: { 'content-type': 'text/event-stream' } }) + if ('openEnded' in body) { + const stream = new ReadableStream({ + start(controller) { + controller.enqueue(new TextEncoder().encode(body.openEnded)) + }, + }) + return new Response(stream, { headers: { 'content-type': 'text/event-stream' } }) + } + return new Response(body.body, { status: body.status, headers: { 'content-type': 'application/json' } }) +} + +function serve(replies: Reply[]): { requests: () => number } { + let count = 0 + server = Bun.serve({ + port: 0, + fetch() { + const next = replies[Math.min(count, replies.length - 1)]! + count += 1 + return reply(next) + }, + }) + process.env.ANTHROPIC_BASE_URL = `http://127.0.0.1:${server.port}` + return { requests: () => count } +} + +function abortAfterFirstChunk(controller: AbortController): typeof fetch { + return (async (input: RequestInfo | URL, init?: RequestInit) => { + const response = await fetch(input, init) + const reader = response.body!.getReader() + let reads = 0 + const body = new ReadableStream({ + async pull(stream) { + reads += 1 + if (reads > 1) controller.abort() + try { + const { done, value } = await reader.read() + if (done) stream.close() + else stream.enqueue(value) + } catch (error) { + stream.error(error) + } + }, + }, { highWaterMark: 0 }) + return new Response(body, { status: response.status, headers: response.headers }) + }) as typeof fetch +} + +async function ask(controller = new AbortController(), fetchOverride?: typeof fetch) { + let fallbacks = 0 + const yielded = [] + for await (const message of queryModelWithStreaming({ + messages: [createUserMessage({ content: 'hello' })], + systemPrompt: asSystemPrompt(['You are a test.']), + thinkingConfig: { type: 'disabled' }, + tools: [], + signal: controller.signal, + options: { + getToolPermissionContext: async () => getEmptyToolPermissionContext(), + model: 'claude-sonnet-4-5', + isNonInteractiveSession: true, + querySource: 'sdk', + agents: [], + hasAppendSystemPrompt: false, + mcpTools: [], + onStreamingFallback: () => { + fallbacks += 1 + }, + ...(fetchOverride && { fetchOverride }), + }, + })) { + yielded.push(message) + } + const assistants = yielded.filter((m) => m.type === 'assistant') as Array<{ isApiErrorMessage?: boolean; message: { content: Array<{ type: string; text?: string }> } }> + const restarts = yielded.filter((m) => m.type === 'system' && (m as { streamRestart?: boolean }).streamRestart === true) + return { fallbacks, assistants, restarts } +} + +describe('retrying a stream that breaks in the middle', () => { + beforeEach(async () => { + savedEnv = Object.fromEntries(ENV_KEYS.map((key) => [key, process.env[key]])) + fixturesDir = await mkdtemp(join(tmpdir(), 'stream-retry-test-')) + process.env.ANTHROPIC_API_KEY = 'sk-test' + process.env.CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK = '1' + process.env.CLAUDE_CODE_TEST_FIXTURES_ROOT = fixturesDir + process.env.VCR_RECORD = '1' + delete process.env.CLAUDE_CODE_MAX_RETRIES + starts = spyOn(sessionActivity, 'startSessionActivity') + stops = spyOn(sessionActivity, 'stopSessionActivity') + }) + + afterEach(async () => { + starts.mockRestore() + stops.mockRestore() + server?.stop(true) + server = undefined + for (const key of ENV_KEYS) { + if (savedEnv[key] === undefined) delete process.env[key] + else process.env[key] = savedEnv[key] + } + await rm(fixturesDir, { recursive: true, force: true }) + }) + + test('opens a new stream and returns the complete reply', async () => { + const endpoint = serve([brokenReply('api_error'), textReply('The full answer.')]) + + const { fallbacks, assistants, restarts } = await ask() + + expect(endpoint.requests()).toBe(2) + expect(fallbacks).toBe(1) + expect(restarts).toHaveLength(1) + const last = assistants.at(-1)! + expect(last.isApiErrorMessage).toBeFalsy() + expect(last.message.content).toEqual([{ type: 'text', text: 'The full answer.' }]) + expect(starts.mock.calls.length).toBe(stops.mock.calls.length) + }) + + test('treats the user stopping the reply as a stop, not a broken stream to retry', async () => { + const partial = messageStart + + sse('content_block_start', { index: 0, content_block: { type: 'text', text: '' } }) + + sse('content_block_delta', { index: 0, delta: { type: 'text_delta', text: 'Half an ans' } }) + const controller = new AbortController() + const endpoint = serve([{ openEnded: partial }, textReply('never sent')]) + + const { fallbacks, restarts } = await ask(controller, abortAfterFirstChunk(controller)) + + expect(endpoint.requests()).toBe(1) + expect(fallbacks).toBe(0) + expect(restarts).toHaveLength(0) + }) + + test('does not retry an error the provider will repeat', async () => { + const endpoint = serve([brokenReply('invalid_request_error'), textReply('never sent')]) + + const { fallbacks, assistants } = await ask() + + expect(endpoint.requests()).toBe(1) + expect(fallbacks).toBe(0) + expect(assistants.at(-1)!.isApiErrorMessage).toBe(true) + }) + + test('counts stream retries and request retries against one budget', async () => { + process.env.CLAUDE_CODE_MAX_RETRIES = '2' + const endpoint = serve([brokenReply('api_error')]) + + const { assistants } = await ask() + + expect(endpoint.requests()).toBe(3) + expect(assistants.at(-1)!.isApiErrorMessage).toBe(true) + }) + + test('leaves request retries only what the broken streams did not use', async () => { + process.env.CLAUDE_CODE_MAX_RETRIES = '2' + const endpoint = serve([brokenReply('api_error'), brokenReply('api_error'), overloaded]) + + const { assistants } = await ask() + + expect(endpoint.requests()).toBe(3) + expect(assistants.at(-1)!.isApiErrorMessage).toBe(true) + }) +}) diff --git a/src/services/api/claude.ts b/src/services/api/claude.ts index 1b80331a..bd3cca8a 100644 --- a/src/services/api/claude.ts +++ b/src/services/api/claude.ts @@ -72,8 +72,10 @@ import { isEnvTruthy } from "../../utils/envUtils.js"; import { errorMessage } from "../../utils/errors.js"; import { computeFingerprintFromMessages } from "../../utils/fingerprint.js"; import { captureAPIRequest, logError } from "../../utils/log.js"; +import { sleep } from "../../utils/sleep.js"; import { createAssistantAPIErrorMessage, + createSystemAPIErrorMessage, createUserMessage, ensureToolResultPairing, normalizeContentFromAPI, @@ -108,6 +110,7 @@ const autoModeStateModule = feature("TRANSCRIPT_CLASSIFIER") import type { ClientOptions } from "@anthropic-ai/sdk"; import { + APIConnectionError, APIConnectionTimeoutError, APIError, APIUserAbortError, @@ -250,7 +253,11 @@ import { import { CannotRetryError, FallbackTriggeredError, + getDefaultMaxRetries, + getRetryAfter, + getRetryDelay, is529Error, + isRetryableStreamError, type RetryContext, withRetry, } from "./withRetry.js"; @@ -1823,711 +1830,780 @@ async function* queryModel( let isFastModeRequest = isFastMode; // Keep separate state as it may change if falling back let isAdvisorInProgress = false; + const maxStreamRequests = getDefaultMaxRetries() + 1; + let streamRequests = 0; + try { queryCheckpoint("query_client_creation_start"); - const generator = withRetry( - () => - getAnthropicClient({ - maxRetries: 0, // Disabled auto-retry in favor of manual implementation - model: options.model, - fetchOverride: options.fetchOverride, - source: options.querySource, - }), - async (anthropic, attempt, context) => { - attemptNumber = attempt; - isFastModeRequest = context.fastMode ?? false; - start = Date.now(); - attemptStartTimes.push(start); - // Client has been created by withRetry's getClient() call. This fires - // once per attempt; on retries the client is usually cached (withRetry - // only calls getClient() again after auth errors), so the delta from - // client_creation_start is meaningful on attempt 1. - queryCheckpoint("query_client_creation_end"); - - const params = paramsFromContext(context); - captureAPIRequest(params, options.querySource); // Capture for bug reports - - maxOutputTokens = params.max_tokens; - - // Fire immediately before the fetch is dispatched. .withResponse() below - // awaits until response headers arrive, so this MUST be before the await - // or the "Network TTFB" phase measurement is wrong. - queryCheckpoint("query_api_request_sent"); - if (!options.agentId) { - headlessProfilerCheckpoint("api_request_sent"); - } - - // Generate and track client request ID so timeouts (which return no - // server request ID) can still be correlated with server logs. - // First-party only — 3P providers don't log it (inc-4029 class). - clientRequestId = - getAPIProvider() === "firstParty" && isFirstPartyAnthropicBaseUrl() - ? randomUUID() - : undefined; - - // Use raw stream instead of BetaMessageStream to avoid O(n²) partial JSON parsing - // BetaMessageStream calls partialParse() on every input_json_delta, which we don't need - // since we handle tool input accumulation ourselves - // biome-ignore lint/plugin: main conversation loop handles attribution separately - const result = await anthropic.beta.messages - .create( - { ...params, stream: true }, - { - signal, - ...(clientRequestId && { - headers: { [CLIENT_REQUEST_ID_HEADER]: clientRequestId }, - }), - }, - ) - .withResponse(); - queryCheckpoint("query_response_headers_received"); - streamRequestId = result.request_id; - streamResponse = result.response; - return result.data; - }, - { - model: options.model, - fallbackModel: options.fallbackModel, - thinkingConfig, - ...(isFastModeEnabled() ? { fastMode: isFastMode } : false), - signal, - querySource: options.querySource, - }, - ); - - let e; - do { - e = await generator.next(); + startSessionActivity("api_call"); + streamAttempts: for (;;) { + const generator = withRetry( + () => + getAnthropicClient({ + maxRetries: 0, // Disabled auto-retry in favor of manual implementation + model: options.model, + fetchOverride: options.fetchOverride, + source: options.querySource, + }), + async (anthropic, attempt, context) => { + attemptNumber = attempt; + streamRequests += 1; + isFastModeRequest = context.fastMode ?? false; + start = Date.now(); + attemptStartTimes.push(start); + // Client has been created by withRetry's getClient() call. This fires + // once per attempt; on retries the client is usually cached (withRetry + // only calls getClient() again after auth errors), so the delta from + // client_creation_start is meaningful on attempt 1. + queryCheckpoint("query_client_creation_end"); + + const params = paramsFromContext(context); + captureAPIRequest(params, options.querySource); // Capture for bug reports + + maxOutputTokens = params.max_tokens; + + // Fire immediately before the fetch is dispatched. .withResponse() below + // awaits until response headers arrive, so this MUST be before the await + // or the "Network TTFB" phase measurement is wrong. + queryCheckpoint("query_api_request_sent"); + if (!options.agentId) { + headlessProfilerCheckpoint("api_request_sent"); + } - // yield API error messages (the stream has a 'controller' property, error messages don't) - if (!("controller" in e.value)) { - yield e.value; - } - } while (!e.done); - stream = e.value as Stream; - - // reset state - newMessages.length = 0; - ttftMs = 0; - partialMessage = undefined; - contentBlocks.length = 0; - usage = EMPTY_USAGE; - stopReason = null; - isAdvisorInProgress = false; - - // Streaming idle timeout watchdog: abort the stream if no chunks arrive - // for STREAM_IDLE_TIMEOUT_MS. Unlike the stall detection below (which only - // fires when the *next* chunk arrives), this uses setTimeout to actively - // kill hung streams. Without this, a silently dropped connection can hang - // the session indefinitely since the SDK's request timeout only covers the - // initial fetch(), not the streaming body. - const streamWatchdogEnabled = isEnvTruthy( - process.env.CLAUDE_ENABLE_STREAM_WATCHDOG, - ); - const STREAM_IDLE_TIMEOUT_MS = - parseInt(process.env.CLAUDE_STREAM_IDLE_TIMEOUT_MS || "", 10) || 90_000; - const STREAM_IDLE_WARNING_MS = STREAM_IDLE_TIMEOUT_MS / 2; - let streamIdleAborted = false; - // performance.now() snapshot when watchdog fires, for measuring abort propagation delay - let streamWatchdogFiredAt: number | null = null; - let streamIdleWarningTimer: ReturnType | null = null; - let streamIdleTimer: ReturnType | null = null; - function clearStreamIdleTimers(): void { - if (streamIdleWarningTimer !== null) { - clearTimeout(streamIdleWarningTimer); - streamIdleWarningTimer = null; - } - if (streamIdleTimer !== null) { - clearTimeout(streamIdleTimer); - streamIdleTimer = null; - } - } - function resetStreamIdleTimer(): void { - clearStreamIdleTimers(); - if (!streamWatchdogEnabled) { - return; - } - streamIdleWarningTimer = setTimeout( - (warnMs) => { - logForDebugging( - `Streaming idle warning: no chunks received for ${warnMs / 1000}s`, - { level: "warn" }, - ); - logForDiagnosticsNoPII("warn", "cli_streaming_idle_warning"); + // Generate and track client request ID so timeouts (which return no + // server request ID) can still be correlated with server logs. + // First-party only — 3P providers don't log it (inc-4029 class). + clientRequestId = + getAPIProvider() === "firstParty" && isFirstPartyAnthropicBaseUrl() + ? randomUUID() + : undefined; + + // Use raw stream instead of BetaMessageStream to avoid O(n²) partial JSON parsing + // BetaMessageStream calls partialParse() on every input_json_delta, which we don't need + // since we handle tool input accumulation ourselves + // biome-ignore lint/plugin: main conversation loop handles attribution separately + const result = await anthropic.beta.messages + .create( + { ...params, stream: true }, + { + signal, + ...(clientRequestId && { + headers: { [CLIENT_REQUEST_ID_HEADER]: clientRequestId }, + }), + }, + ) + .withResponse(); + queryCheckpoint("query_response_headers_received"); + streamRequestId = result.request_id; + streamResponse = result.response; + return result.data; + }, + { + model: options.model, + fallbackModel: options.fallbackModel, + thinkingConfig, + ...(isFastModeEnabled() ? { fastMode: isFastMode } : false), + signal, + querySource: options.querySource, + maxRetries: maxStreamRequests - streamRequests - 1, }, - STREAM_IDLE_WARNING_MS, - STREAM_IDLE_WARNING_MS, ); - streamIdleTimer = setTimeout(() => { - streamIdleAborted = true; - streamWatchdogFiredAt = performance.now(); - logForDebugging( - `Streaming idle timeout: no chunks received for ${STREAM_IDLE_TIMEOUT_MS / 1000}s, aborting stream`, - { level: "error" }, - ); - logForDiagnosticsNoPII("error", "cli_streaming_idle_timeout"); - logEvent("tengu_streaming_idle_timeout", { - model: - options.model as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - request_id: (streamRequestId ?? - "unknown") as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - timeout_ms: STREAM_IDLE_TIMEOUT_MS, - }); - releaseStreamResources(); - }, STREAM_IDLE_TIMEOUT_MS); - } - resetStreamIdleTimer(); - startSessionActivity("api_call"); - try { - // stream in and accumulate state - let isFirstChunk = true; - let lastEventTime: number | null = null; // Set after first chunk to avoid measuring TTFB as a stall - const STALL_THRESHOLD_MS = 30_000; // 30 seconds - let totalStallTime = 0; - let stallCount = 0; - - for await (const part of stream) { - resetStreamIdleTimer(); - const now = Date.now(); - - // Detect and log streaming stalls (only after first event to avoid counting TTFB) - if (lastEventTime !== null) { - const timeSinceLastEvent = now - lastEventTime; - if (timeSinceLastEvent > STALL_THRESHOLD_MS) { - stallCount++; - totalStallTime += timeSinceLastEvent; + let e; + do { + e = await generator.next(); + + // yield API error messages (the stream has a 'controller' property, error messages don't) + if (!("controller" in e.value)) { + yield e.value; + } + } while (!e.done); + stream = e.value as Stream; + + // reset state + newMessages.length = 0; + ttftMs = 0; + partialMessage = undefined; + contentBlocks.length = 0; + usage = EMPTY_USAGE; + stopReason = null; + isAdvisorInProgress = false; + + // Streaming idle timeout watchdog: abort the stream if no chunks arrive + // for STREAM_IDLE_TIMEOUT_MS. Unlike the stall detection below (which only + // fires when the *next* chunk arrives), this uses setTimeout to actively + // kill hung streams. Without this, a silently dropped connection can hang + // the session indefinitely since the SDK's request timeout only covers the + // initial fetch(), not the streaming body. + const streamWatchdogEnabled = isEnvTruthy( + process.env.CLAUDE_ENABLE_STREAM_WATCHDOG, + ); + const STREAM_IDLE_TIMEOUT_MS = + parseInt(process.env.CLAUDE_STREAM_IDLE_TIMEOUT_MS || "", 10) || 90_000; + const STREAM_IDLE_WARNING_MS = STREAM_IDLE_TIMEOUT_MS / 2; + let streamIdleAborted = false; + // performance.now() snapshot when watchdog fires, for measuring abort propagation delay + let streamWatchdogFiredAt: number | null = null; + let streamIdleWarningTimer: ReturnType | null = null; + let streamIdleTimer: ReturnType | null = null; + function clearStreamIdleTimers(): void { + if (streamIdleWarningTimer !== null) { + clearTimeout(streamIdleWarningTimer); + streamIdleWarningTimer = null; + } + if (streamIdleTimer !== null) { + clearTimeout(streamIdleTimer); + streamIdleTimer = null; + } + } + function resetStreamIdleTimer(): void { + clearStreamIdleTimers(); + if (!streamWatchdogEnabled) { + return; + } + streamIdleWarningTimer = setTimeout( + (warnMs) => { logForDebugging( - `Streaming stall detected: ${(timeSinceLastEvent / 1000).toFixed(1)}s gap between events (stall #${stallCount})`, + `Streaming idle warning: no chunks received for ${warnMs / 1000}s`, { level: "warn" }, ); - logEvent("tengu_streaming_stall", { - stall_duration_ms: timeSinceLastEvent, - stall_count: stallCount, - total_stall_time_ms: totalStallTime, - event_type: - part.type as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - model: - options.model as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - request_id: (streamRequestId ?? - "unknown") as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - }); - } - } - lastEventTime = now; + logForDiagnosticsNoPII("warn", "cli_streaming_idle_warning"); + }, + STREAM_IDLE_WARNING_MS, + STREAM_IDLE_WARNING_MS, + ); + streamIdleTimer = setTimeout(() => { + streamIdleAborted = true; + streamWatchdogFiredAt = performance.now(); + logForDebugging( + `Streaming idle timeout: no chunks received for ${STREAM_IDLE_TIMEOUT_MS / 1000}s, aborting stream`, + { level: "error" }, + ); + logForDiagnosticsNoPII("error", "cli_streaming_idle_timeout"); + logEvent("tengu_streaming_idle_timeout", { + model: + options.model as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + request_id: (streamRequestId ?? + "unknown") as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + timeout_ms: STREAM_IDLE_TIMEOUT_MS, + }); + releaseStreamResources(); + }, STREAM_IDLE_TIMEOUT_MS); + } + resetStreamIdleTimer(); - if (isFirstChunk) { - logForDebugging("Stream started - received first chunk"); - queryCheckpoint("query_first_chunk_received"); - if (!options.agentId) { - headlessProfilerCheckpoint("first_chunk"); + try { + // stream in and accumulate state + let isFirstChunk = true; + let lastEventTime: number | null = null; // Set after first chunk to avoid measuring TTFB as a stall + const STALL_THRESHOLD_MS = 30_000; // 30 seconds + let totalStallTime = 0; + let stallCount = 0; + + for await (const part of stream) { + resetStreamIdleTimer(); + const now = Date.now(); + + // Detect and log streaming stalls (only after first event to avoid counting TTFB) + if (lastEventTime !== null) { + const timeSinceLastEvent = now - lastEventTime; + if (timeSinceLastEvent > STALL_THRESHOLD_MS) { + stallCount++; + totalStallTime += timeSinceLastEvent; + logForDebugging( + `Streaming stall detected: ${(timeSinceLastEvent / 1000).toFixed(1)}s gap between events (stall #${stallCount})`, + { level: "warn" }, + ); + logEvent("tengu_streaming_stall", { + stall_duration_ms: timeSinceLastEvent, + stall_count: stallCount, + total_stall_time_ms: totalStallTime, + event_type: + part.type as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + model: + options.model as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + request_id: (streamRequestId ?? + "unknown") as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + }); + } } - endQueryProfile(); - isFirstChunk = false; - } + lastEventTime = now; - switch (part.type) { - case "message_start": { - partialMessage = part.message; - ttftMs = Date.now() - start; - usage = updateUsage(usage, part.message?.usage); - // Capture research from message_start if available (internal only). - // Always overwrite with the latest value. - if ( - process.env.USER_TYPE === "ant" && - "research" in (part.message as unknown as Record) - ) { - research = (part.message as unknown as Record) - .research; + if (isFirstChunk) { + logForDebugging("Stream started - received first chunk"); + queryCheckpoint("query_first_chunk_received"); + if (!options.agentId) { + headlessProfilerCheckpoint("first_chunk"); } - break; + endQueryProfile(); + isFirstChunk = false; } - case "content_block_start": - switch (part.content_block.type) { - case "tool_use": - contentBlocks[part.index] = { - ...part.content_block, - input: "", - }; - break; - case "server_tool_use": - contentBlocks[part.index] = { - ...part.content_block, - input: "" as unknown as { [key: string]: unknown }, - }; - if ((part.content_block.name as string) === "advisor") { - isAdvisorInProgress = true; - logForDebugging(`[AdvisorTool] Advisor tool called`); - logEvent("tengu_advisor_tool_call", { - model: - options.model as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - advisor_model: (advisorModel ?? - "unknown") as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - }); - } - break; - case "text": - contentBlocks[part.index] = { - ...part.content_block, - // awkwardly, the sdk sometimes returns text as part of a - // content_block_start message, then returns the same text - // again in a content_block_delta message. we ignore it here - // since there doesn't seem to be a way to detect when a - // content_block_delta message duplicates the text. - text: "", - }; - break; - case "thinking": - contentBlocks[part.index] = { - ...part.content_block, - // also awkward - thinking: "", - // initialize signature to ensure field exists even if signature_delta never arrives - signature: "", - }; - break; - default: - // even more awkwardly, the sdk mutates the contents of text blocks - // as it works. we want the blocks to be immutable, so that we can - // accumulate state ourselves. - contentBlocks[part.index] = { ...part.content_block }; - if ( - (part.content_block.type as string) === "advisor_tool_result" - ) { - isAdvisorInProgress = false; - logForDebugging(`[AdvisorTool] Advisor tool result received`); - } - break; - } - break; - case "content_block_delta": { - const contentBlock = contentBlocks[part.index]; - const delta = part.delta as typeof part.delta | ConnectorTextDelta; - if (!contentBlock) { - logEvent("tengu_streaming_error", { - error_type: - "content_block_not_found_delta" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - part_type: - part.type as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - part_index: part.index, - }); - throw new RangeError("Content block not found"); - } - if ( - feature("CONNECTOR_TEXT") && - delta.type === "connector_text_delta" - ) { - if (contentBlock.type !== "connector_text") { - logEvent("tengu_streaming_error", { - error_type: - "content_block_type_mismatch_connector_text" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - expected_type: - "connector_text" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - actual_type: - contentBlock.type as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - }); - throw new Error("Content block is not a connector_text block"); + + switch (part.type) { + case "message_start": { + partialMessage = part.message; + ttftMs = Date.now() - start; + usage = updateUsage(usage, part.message?.usage); + // Capture research from message_start if available (internal only). + // Always overwrite with the latest value. + if ( + process.env.USER_TYPE === "ant" && + "research" in (part.message as unknown as Record) + ) { + research = (part.message as unknown as Record) + .research; } - contentBlock.connector_text += delta.connector_text; - } else { - switch (delta.type) { - case "citations_delta": - // TODO: handle citations + break; + } + case "content_block_start": + switch (part.content_block.type) { + case "tool_use": + contentBlocks[part.index] = { + ...part.content_block, + input: "", + }; break; - case "input_json_delta": - if ( - contentBlock.type !== "tool_use" && - contentBlock.type !== "server_tool_use" - ) { - logEvent("tengu_streaming_error", { - error_type: - "content_block_type_mismatch_input_json" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - expected_type: - "tool_use" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - actual_type: - contentBlock.type as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + case "server_tool_use": + contentBlocks[part.index] = { + ...part.content_block, + input: "" as unknown as { [key: string]: unknown }, + }; + if ((part.content_block.name as string) === "advisor") { + isAdvisorInProgress = true; + logForDebugging(`[AdvisorTool] Advisor tool called`); + logEvent("tengu_advisor_tool_call", { + model: + options.model as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + advisor_model: (advisorModel ?? + "unknown") as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, }); - throw new Error("Content block is not a input_json block"); } - if (typeof contentBlock.input !== "string") { - logEvent("tengu_streaming_error", { - error_type: - "content_block_input_not_string" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - input_type: - typeof contentBlock.input as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - }); - throw new Error("Content block input is not a string"); - } - contentBlock.input += delta.partial_json; break; - case "text_delta": - if (contentBlock.type !== "text") { - logEvent("tengu_streaming_error", { - error_type: - "content_block_type_mismatch_text" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - expected_type: - "text" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - actual_type: - contentBlock.type as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - }); - throw new Error("Content block is not a text block"); - } - contentBlock.text += delta.text; + case "text": + contentBlocks[part.index] = { + ...part.content_block, + // awkwardly, the sdk sometimes returns text as part of a + // content_block_start message, then returns the same text + // again in a content_block_delta message. we ignore it here + // since there doesn't seem to be a way to detect when a + // content_block_delta message duplicates the text. + text: "", + }; break; - case "signature_delta": + case "thinking": + contentBlocks[part.index] = { + ...part.content_block, + // also awkward + thinking: "", + // initialize signature to ensure field exists even if signature_delta never arrives + signature: "", + }; + break; + default: + // even more awkwardly, the sdk mutates the contents of text blocks + // as it works. we want the blocks to be immutable, so that we can + // accumulate state ourselves. + contentBlocks[part.index] = { ...part.content_block }; if ( - feature("CONNECTOR_TEXT") && - contentBlock.type === "connector_text" + (part.content_block.type as string) === "advisor_tool_result" ) { - contentBlock.signature = delta.signature; - break; - } - if (contentBlock.type !== "thinking") { - logEvent("tengu_streaming_error", { - error_type: - "content_block_type_mismatch_thinking_signature" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - expected_type: - "thinking" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - actual_type: - contentBlock.type as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - }); - throw new Error("Content block is not a thinking block"); - } - contentBlock.signature = delta.signature; - break; - case "thinking_delta": - if (contentBlock.type !== "thinking") { - logEvent("tengu_streaming_error", { - error_type: - "content_block_type_mismatch_thinking_delta" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - expected_type: - "thinking" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - actual_type: - contentBlock.type as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - }); - throw new Error("Content block is not a thinking block"); + isAdvisorInProgress = false; + logForDebugging(`[AdvisorTool] Advisor tool result received`); } - contentBlock.thinking += delta.thinking; break; } - } - // Capture research from content_block_delta if available (internal only). - // Always overwrite with the latest value. - if (process.env.USER_TYPE === "ant" && "research" in part) { - research = (part as { research: unknown }).research; - } - break; - } - case "content_block_stop": { - const contentBlock = contentBlocks[part.index]; - if (!contentBlock) { - logEvent("tengu_streaming_error", { - error_type: - "content_block_not_found_stop" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - part_type: - part.type as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - part_index: part.index, - }); - throw new RangeError("Content block not found"); - } - if (!partialMessage) { - logEvent("tengu_streaming_error", { - error_type: - "partial_message_not_found" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - part_type: - part.type as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - }); - throw new Error("Message not found"); - } - const m: AssistantMessage = { - message: { - ...partialMessage, - content: normalizeContentFromAPI( - [contentBlock] as BetaContentBlock[], - tools, - options.agentId, - ), - }, - requestId: streamRequestId ?? undefined, - type: "assistant", - uuid: randomUUID(), - timestamp: new Date().toISOString(), - ...(process.env.USER_TYPE === "ant" && - research !== undefined && { research }), - ...(advisorModel && { advisorModel }), - }; - newMessages.push(m); - yield m; - break; - } - case "message_delta": { - usage = updateUsage(usage, part.usage); - // Capture research from message_delta if available (internal only). - // Always overwrite with the latest value. Also write back to - // already-yielded messages since message_delta arrives after - // content_block_stop. - if ( - process.env.USER_TYPE === "ant" && - "research" in (part as unknown as Record) - ) { - research = (part as unknown as Record).research; - for (const msg of newMessages) { - msg.research = research; + break; + case "content_block_delta": { + const contentBlock = contentBlocks[part.index]; + const delta = part.delta as typeof part.delta | ConnectorTextDelta; + if (!contentBlock) { + logEvent("tengu_streaming_error", { + error_type: + "content_block_not_found_delta" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + part_type: + part.type as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + part_index: part.index, + }); + throw new RangeError("Content block not found"); + } + if ( + feature("CONNECTOR_TEXT") && + delta.type === "connector_text_delta" + ) { + if (contentBlock.type !== "connector_text") { + logEvent("tengu_streaming_error", { + error_type: + "content_block_type_mismatch_connector_text" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + expected_type: + "connector_text" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + actual_type: + contentBlock.type as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + }); + throw new Error("Content block is not a connector_text block"); + } + contentBlock.connector_text += delta.connector_text; + } else { + switch (delta.type) { + case "citations_delta": + // TODO: handle citations + break; + case "input_json_delta": + if ( + contentBlock.type !== "tool_use" && + contentBlock.type !== "server_tool_use" + ) { + logEvent("tengu_streaming_error", { + error_type: + "content_block_type_mismatch_input_json" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + expected_type: + "tool_use" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + actual_type: + contentBlock.type as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + }); + throw new Error("Content block is not a input_json block"); + } + if (typeof contentBlock.input !== "string") { + logEvent("tengu_streaming_error", { + error_type: + "content_block_input_not_string" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + input_type: + typeof contentBlock.input as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + }); + throw new Error("Content block input is not a string"); + } + contentBlock.input += delta.partial_json; + break; + case "text_delta": + if (contentBlock.type !== "text") { + logEvent("tengu_streaming_error", { + error_type: + "content_block_type_mismatch_text" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + expected_type: + "text" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + actual_type: + contentBlock.type as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + }); + throw new Error("Content block is not a text block"); + } + contentBlock.text += delta.text; + break; + case "signature_delta": + if ( + feature("CONNECTOR_TEXT") && + contentBlock.type === "connector_text" + ) { + contentBlock.signature = delta.signature; + break; + } + if (contentBlock.type !== "thinking") { + logEvent("tengu_streaming_error", { + error_type: + "content_block_type_mismatch_thinking_signature" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + expected_type: + "thinking" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + actual_type: + contentBlock.type as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + }); + throw new Error("Content block is not a thinking block"); + } + contentBlock.signature = delta.signature; + break; + case "thinking_delta": + if (contentBlock.type !== "thinking") { + logEvent("tengu_streaming_error", { + error_type: + "content_block_type_mismatch_thinking_delta" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + expected_type: + "thinking" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + actual_type: + contentBlock.type as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + }); + throw new Error("Content block is not a thinking block"); + } + contentBlock.thinking += delta.thinking; + break; + } + } + // Capture research from content_block_delta if available (internal only). + // Always overwrite with the latest value. + if (process.env.USER_TYPE === "ant" && "research" in part) { + research = (part as { research: unknown }).research; } + break; } - - // Write final usage and stop_reason back to the last yielded - // message. Messages are created at content_block_stop from - // partialMessage, which was set at message_start before any tokens - // were generated (output_tokens: 0, stop_reason: null). - // message_delta arrives after content_block_stop with the real - // values. - // - // IMPORTANT: Use direct property mutation, not object replacement. - // The transcript write queue holds a reference to message.message - // and serializes it lazily (100ms flush interval). Object - // replacement ({ ...lastMsg.message, usage }) would disconnect - // the queued reference; direct mutation ensures the transcript - // captures the final values. - stopReason = part.delta.stop_reason; - - const lastMsg = newMessages.at(-1); - if (lastMsg) { - lastMsg.message.usage = usage; - lastMsg.message.stop_reason = stopReason; + case "content_block_stop": { + const contentBlock = contentBlocks[part.index]; + if (!contentBlock) { + logEvent("tengu_streaming_error", { + error_type: + "content_block_not_found_stop" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + part_type: + part.type as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + part_index: part.index, + }); + throw new RangeError("Content block not found"); + } + if (!partialMessage) { + logEvent("tengu_streaming_error", { + error_type: + "partial_message_not_found" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + part_type: + part.type as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + }); + throw new Error("Message not found"); + } + const m: AssistantMessage = { + message: { + ...partialMessage, + content: normalizeContentFromAPI( + [contentBlock] as BetaContentBlock[], + tools, + options.agentId, + ), + }, + requestId: streamRequestId ?? undefined, + type: "assistant", + uuid: randomUUID(), + timestamp: new Date().toISOString(), + ...(process.env.USER_TYPE === "ant" && + research !== undefined && { research }), + ...(advisorModel && { advisorModel }), + }; + newMessages.push(m); + yield m; + break; } + case "message_delta": { + usage = updateUsage(usage, part.usage); + // Capture research from message_delta if available (internal only). + // Always overwrite with the latest value. Also write back to + // already-yielded messages since message_delta arrives after + // content_block_stop. + if ( + process.env.USER_TYPE === "ant" && + "research" in (part as unknown as Record) + ) { + research = (part as unknown as Record).research; + for (const msg of newMessages) { + msg.research = research; + } + } - // Update cost - const costUSDForPart = calculateUSDCost(resolvedModel, usage); - costUSD += addToTotalSessionCost( - costUSDForPart, - usage, - options.model, - ); + // Write final usage and stop_reason back to the last yielded + // message. Messages are created at content_block_stop from + // partialMessage, which was set at message_start before any tokens + // were generated (output_tokens: 0, stop_reason: null). + // message_delta arrives after content_block_stop with the real + // values. + // + // IMPORTANT: Use direct property mutation, not object replacement. + // The transcript write queue holds a reference to message.message + // and serializes it lazily (100ms flush interval). Object + // replacement ({ ...lastMsg.message, usage }) would disconnect + // the queued reference; direct mutation ensures the transcript + // captures the final values. + stopReason = part.delta.stop_reason; + + const lastMsg = newMessages.at(-1); + if (lastMsg) { + lastMsg.message.usage = usage; + lastMsg.message.stop_reason = stopReason; + } - const refusalMessage = getErrorMessageIfRefusal( - part.delta.stop_reason, - options.model, - ); - if (refusalMessage) { - yield refusalMessage; - } + // Update cost + const costUSDForPart = calculateUSDCost(resolvedModel, usage); + costUSD += addToTotalSessionCost( + costUSDForPart, + usage, + options.model, + ); + + const refusalMessage = getErrorMessageIfRefusal( + part.delta.stop_reason, + options.model, + ); + if (refusalMessage) { + yield refusalMessage; + } - if (stopReason === "max_tokens") { - logEvent("tengu_max_tokens_reached", { - max_tokens: maxOutputTokens, - }); - yield createAssistantAPIErrorMessage({ - content: `${API_ERROR_MESSAGE_PREFIX}: Claude's response exceeded the ${ - maxOutputTokens - } output token maximum. To configure this behavior, set the CLAUDE_CODE_MAX_OUTPUT_TOKENS environment variable.`, - apiError: "max_output_tokens", - error: "max_output_tokens", - }); - } + if (stopReason === "max_tokens") { + logEvent("tengu_max_tokens_reached", { + max_tokens: maxOutputTokens, + }); + yield createAssistantAPIErrorMessage({ + content: `${API_ERROR_MESSAGE_PREFIX}: Claude's response exceeded the ${ + maxOutputTokens + } output token maximum. To configure this behavior, set the CLAUDE_CODE_MAX_OUTPUT_TOKENS environment variable.`, + apiError: "max_output_tokens", + error: "max_output_tokens", + }); + } - if (stopReason === "model_context_window_exceeded") { - logEvent("tengu_context_window_exceeded", { - max_tokens: maxOutputTokens, - output_tokens: usage.output_tokens, - }); - // Reuse the max_output_tokens recovery path — from the model's - // perspective, both mean "response was cut off, continue from - // where you left off." - yield createAssistantAPIErrorMessage({ - content: `${API_ERROR_MESSAGE_PREFIX}: The model has reached its context window limit.`, - apiError: "max_output_tokens", - error: "max_output_tokens", - }); + if (stopReason === "model_context_window_exceeded") { + logEvent("tengu_context_window_exceeded", { + max_tokens: maxOutputTokens, + output_tokens: usage.output_tokens, + }); + // Reuse the max_output_tokens recovery path — from the model's + // perspective, both mean "response was cut off, continue from + // where you left off." + yield createAssistantAPIErrorMessage({ + content: `${API_ERROR_MESSAGE_PREFIX}: The model has reached its context window limit.`, + apiError: "max_output_tokens", + error: "max_output_tokens", + }); + } + break; } - break; + case "message_stop": + break; } - case "message_stop": - break; + + yield { + type: "stream_event", + event: part, + ...(part.type === "message_start" ? { ttftMs } : undefined), + }; + } + // Clear the idle timeout watchdog now that the stream loop has exited + clearStreamIdleTimers(); + + // If the stream was aborted by our idle timeout watchdog, fall back to + // non-streaming retry rather than treating it as a completed stream. + if (streamIdleAborted) { + // Instrumentation: proves the for-await exited after the watchdog fired + // (vs. hung forever). exit_delay_ms measures abort propagation latency: + // 0-10ms = abort worked; >>1000ms = something else woke the loop. + const exitDelayMs = + streamWatchdogFiredAt !== null + ? Math.round(performance.now() - streamWatchdogFiredAt) + : -1; + logForDiagnosticsNoPII( + "info", + "cli_stream_loop_exited_after_watchdog_clean", + ); + logEvent("tengu_stream_loop_exited_after_watchdog", { + request_id: (streamRequestId ?? + "unknown") as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + exit_delay_ms: exitDelayMs, + exit_path: + "clean" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + model: + options.model as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + }); + // Prevent double-emit: this throw lands in the catch block below, + // whose exit_path='error' probe guards on streamWatchdogFiredAt. + streamWatchdogFiredAt = null; + throw new Error("Stream idle timeout - no chunks received"); } - yield { - type: "stream_event", - event: part, - ...(part.type === "message_start" ? { ttftMs } : undefined), - }; - } - // Clear the idle timeout watchdog now that the stream loop has exited - clearStreamIdleTimers(); - - // If the stream was aborted by our idle timeout watchdog, fall back to - // non-streaming retry rather than treating it as a completed stream. - if (streamIdleAborted) { - // Instrumentation: proves the for-await exited after the watchdog fired - // (vs. hung forever). exit_delay_ms measures abort propagation latency: - // 0-10ms = abort worked; >>1000ms = something else woke the loop. - const exitDelayMs = - streamWatchdogFiredAt !== null - ? Math.round(performance.now() - streamWatchdogFiredAt) - : -1; - logForDiagnosticsNoPII( - "info", - "cli_stream_loop_exited_after_watchdog_clean", - ); - logEvent("tengu_stream_loop_exited_after_watchdog", { - request_id: (streamRequestId ?? - "unknown") as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - exit_delay_ms: exitDelayMs, - exit_path: - "clean" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - model: - options.model as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - }); - // Prevent double-emit: this throw lands in the catch block below, - // whose exit_path='error' probe guards on streamWatchdogFiredAt. - streamWatchdogFiredAt = null; - throw new Error("Stream idle timeout - no chunks received"); - } + // Detect when the stream completed without producing any assistant messages. + // This covers two proxy failure modes: + // 1. No events at all (!partialMessage): proxy returned 200 with non-SSE body + // 2. Partial events (partialMessage set but no content blocks completed AND + // no stop_reason received): proxy returned message_start but stream ended + // before content_block_stop and before message_delta with stop_reason + // BetaMessageStream had the first check in _endRequest() but the raw Stream + // does not - without it the generator silently returns no assistant messages, + // causing "Execution error" in -p mode. + // Note: We must check stopReason to avoid false positives. For example, with + // structured output (--json-schema), the model calls a StructuredOutput tool + // on turn 1, then on turn 2 responds with end_turn and no content blocks. + // That's a legitimate empty response, not an incomplete stream. + if (!partialMessage || (newMessages.length === 0 && !stopReason)) { + logForDebugging( + !partialMessage + ? "Stream completed without receiving message_start event - triggering non-streaming fallback" + : "Stream completed with message_start but no content blocks completed - triggering non-streaming fallback", + { level: "error" }, + ); + logEvent("tengu_stream_no_events", { + model: + options.model as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + request_id: (streamRequestId ?? + "unknown") as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + }); + throw new Error("Stream ended without receiving any events"); + } - // Detect when the stream completed without producing any assistant messages. - // This covers two proxy failure modes: - // 1. No events at all (!partialMessage): proxy returned 200 with non-SSE body - // 2. Partial events (partialMessage set but no content blocks completed AND - // no stop_reason received): proxy returned message_start but stream ended - // before content_block_stop and before message_delta with stop_reason - // BetaMessageStream had the first check in _endRequest() but the raw Stream - // does not - without it the generator silently returns no assistant messages, - // causing "Execution error" in -p mode. - // Note: We must check stopReason to avoid false positives. For example, with - // structured output (--json-schema), the model calls a StructuredOutput tool - // on turn 1, then on turn 2 responds with end_turn and no content blocks. - // That's a legitimate empty response, not an incomplete stream. - if (!partialMessage || (newMessages.length === 0 && !stopReason)) { - logForDebugging( - !partialMessage - ? "Stream completed without receiving message_start event - triggering non-streaming fallback" - : "Stream completed with message_start but no content blocks completed - triggering non-streaming fallback", - { level: "error" }, - ); - logEvent("tengu_stream_no_events", { - model: - options.model as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - request_id: (streamRequestId ?? - "unknown") as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - }); - throw new Error("Stream ended without receiving any events"); - } + // Log summary if any stalls occurred during streaming + if (stallCount > 0) { + logForDebugging( + `Streaming completed with ${stallCount} stall(s), total stall time: ${(totalStallTime / 1000).toFixed(1)}s`, + { level: "warn" }, + ); + logEvent("tengu_streaming_stall_summary", { + stall_count: stallCount, + total_stall_time_ms: totalStallTime, + model: + options.model as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + request_id: (streamRequestId ?? + "unknown") as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + }); + } - // Log summary if any stalls occurred during streaming - if (stallCount > 0) { - logForDebugging( - `Streaming completed with ${stallCount} stall(s), total stall time: ${(totalStallTime / 1000).toFixed(1)}s`, - { level: "warn" }, - ); - logEvent("tengu_streaming_stall_summary", { - stall_count: stallCount, - total_stall_time_ms: totalStallTime, - model: - options.model as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - request_id: (streamRequestId ?? - "unknown") as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - }); - } + // Check if the cache actually broke based on response tokens + if (feature("PROMPT_CACHE_BREAK_DETECTION")) { + void checkResponseForCacheBreak( + options.querySource, + usage.cache_read_input_tokens, + usage.cache_creation_input_tokens, + messages, + options.agentId, + streamRequestId, + ); + } - // Check if the cache actually broke based on response tokens - if (feature("PROMPT_CACHE_BREAK_DETECTION")) { - void checkResponseForCacheBreak( - options.querySource, - usage.cache_read_input_tokens, - usage.cache_creation_input_tokens, - messages, - options.agentId, - streamRequestId, - ); - } + // Process fallback percentage header and quota status if available + // streamResponse is set when the stream is created in the withRetry callback above + // TypeScript's control flow analysis can't track that streamResponse is set in the callback + // eslint-disable-next-line eslint-plugin-n/no-unsupported-features/node-builtins + const resp = streamResponse as unknown as Response | undefined; + if (resp) { + extractQuotaStatusFromHeaders(resp.headers); + // Store headers for gateway detection + responseHeaders = resp.headers; + } + } catch (streamingError) { + // Clear the idle timeout watchdog on error path too + clearStreamIdleTimers(); + + // Instrumentation: if the watchdog had already fired and the for-await + // threw (rather than exiting cleanly), record that the loop DID exit and + // how long after the watchdog. Distinguishes true hangs from error exits. + if (streamIdleAborted && streamWatchdogFiredAt !== null) { + const exitDelayMs = Math.round( + performance.now() - streamWatchdogFiredAt, + ); + logForDiagnosticsNoPII( + "info", + "cli_stream_loop_exited_after_watchdog_error", + ); + logEvent("tengu_stream_loop_exited_after_watchdog", { + request_id: (streamRequestId ?? + "unknown") as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + exit_delay_ms: exitDelayMs, + exit_path: + "error" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + error_name: + streamingError instanceof Error + ? (streamingError.name as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS) + : ("unknown" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS), + model: + options.model as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + }); + } - // Process fallback percentage header and quota status if available - // streamResponse is set when the stream is created in the withRetry callback above - // TypeScript's control flow analysis can't track that streamResponse is set in the callback - // eslint-disable-next-line eslint-plugin-n/no-unsupported-features/node-builtins - const resp = streamResponse as unknown as Response | undefined; - if (resp) { - extractQuotaStatusFromHeaders(resp.headers); - // Store headers for gateway detection - responseHeaders = resp.headers; - } - } catch (streamingError) { - // Clear the idle timeout watchdog on error path too - clearStreamIdleTimers(); - - // Instrumentation: if the watchdog had already fired and the for-await - // threw (rather than exiting cleanly), record that the loop DID exit and - // how long after the watchdog. Distinguishes true hangs from error exits. - if (streamIdleAborted && streamWatchdogFiredAt !== null) { - const exitDelayMs = Math.round( - performance.now() - streamWatchdogFiredAt, - ); - logForDiagnosticsNoPII( - "info", - "cli_stream_loop_exited_after_watchdog_error", - ); - logEvent("tengu_stream_loop_exited_after_watchdog", { - request_id: (streamRequestId ?? - "unknown") as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - exit_delay_ms: exitDelayMs, - exit_path: - "error" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - error_name: - streamingError instanceof Error - ? (streamingError.name as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS) - : ("unknown" as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS), - model: - options.model as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - }); - } + if (streamingError instanceof APIUserAbortError) { + // Check if the abort signal was triggered by the user (ESC key) + // If the signal is aborted, it's a user-initiated abort + // If not, it's likely a timeout from the SDK + if (signal.aborted) { + // This is a real user abort (ESC key was pressed) + logForDebugging( + `Streaming aborted by user: ${errorMessage(streamingError)}`, + ); + if (isAdvisorInProgress) { + logEvent("tengu_advisor_tool_interrupted", { + model: + options.model as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + advisor_model: (advisorModel ?? + "unknown") as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + }); + } + throw streamingError; + } else { + // The SDK threw APIUserAbortError but our signal wasn't aborted + // This means it's a timeout from the SDK's internal timeout + logForDebugging( + `Streaming timeout (SDK abort): ${streamingError.message}`, + { level: "error" }, + ); + // Throw a more specific error for timeout + throw new APIConnectionTimeoutError({ message: "Request timed out" }); + } + } - if (streamingError instanceof APIUserAbortError) { - // Check if the abort signal was triggered by the user (ESC key) - // If the signal is aborted, it's a user-initiated abort - // If not, it's likely a timeout from the SDK - if (signal.aborted) { - // This is a real user abort (ESC key was pressed) + // When the flag is enabled, skip the non-streaming fallback and let the + // error propagate to withRetry. The mid-stream fallback causes double tool + // execution when streaming tool execution is active: the partial stream + // starts a tool, then the non-streaming retry produces the same tool_use + // and runs it again. See inc-4258. + const disableFallback = + isEnvTruthy(process.env.CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK) || + getFeatureValue_CACHED_MAY_BE_STALE( + "tengu_disable_streaming_to_non_streaming_fallback", + false, + ); + + if (disableFallback) { logForDebugging( - `Streaming aborted by user: ${errorMessage(streamingError)}`, + `Error streaming (non-streaming fallback disabled): ${errorMessage(streamingError)}`, + { level: "error" }, ); - if (isAdvisorInProgress) { - logEvent("tengu_advisor_tool_interrupted", { - model: - options.model as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - advisor_model: (advisorModel ?? - "unknown") as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + logEvent("tengu_streaming_fallback_to_non_streaming", { + model: + options.model as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + error: + streamingError instanceof Error + ? (streamingError.name as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS) + : (String( + streamingError, + ) as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS), + attemptNumber, + maxOutputTokens, + thinkingType: + thinkingConfig.type as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + fallback_disabled: true, + request_id: (streamRequestId ?? + "unknown") as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + fallback_cause: (streamIdleAborted + ? "watchdog" + : "other") as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + }); + if ( + !signal.aborted && + streamRequests < maxStreamRequests && + isRetryableStreamError(streamingError) + ) { + const retryError = + streamingError instanceof APIError + ? streamingError + : new APIConnectionError({ + message: errorMessage(streamingError), + }); + const delayMs = getRetryDelay( + streamRequests, + getRetryAfter(streamingError), + ); + releaseStreamResources(); + options.onStreamingFallback?.(); + yield { + ...createSystemAPIErrorMessage( + retryError, + delayMs, + streamRequests, + maxStreamRequests - 1, + ), + streamRestart: true, + }; + await sleep(delayMs, signal, { + abortError: () => new APIUserAbortError(), }); + continue streamAttempts; } throw streamingError; - } else { - // The SDK threw APIUserAbortError but our signal wasn't aborted - // This means it's a timeout from the SDK's internal timeout - logForDebugging( - `Streaming timeout (SDK abort): ${streamingError.message}`, - { level: "error" }, - ); - // Throw a more specific error for timeout - throw new APIConnectionTimeoutError({ message: "Request timed out" }); } - } - // When the flag is enabled, skip the non-streaming fallback and let the - // error propagate to withRetry. The mid-stream fallback causes double tool - // execution when streaming tool execution is active: the partial stream - // starts a tool, then the non-streaming retry produces the same tool_use - // and runs it again. See inc-4258. - const disableFallback = - isEnvTruthy(process.env.CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK) || - getFeatureValue_CACHED_MAY_BE_STALE( - "tengu_disable_streaming_to_non_streaming_fallback", - false, - ); - - if (disableFallback) { logForDebugging( - `Error streaming (non-streaming fallback disabled): ${errorMessage(streamingError)}`, + `Error streaming, falling back to non-streaming mode: ${errorMessage(streamingError)}`, { level: "error" }, ); + didFallBackToNonStreaming = true; + if (options.onStreamingFallback) { + options.onStreamingFallback(); + } + logEvent("tengu_streaming_fallback_to_non_streaming", { model: options.model as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, @@ -2541,110 +2617,80 @@ async function* queryModel( maxOutputTokens, thinkingType: thinkingConfig.type as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - fallback_disabled: true, + fallback_disabled: false, request_id: (streamRequestId ?? "unknown") as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, fallback_cause: (streamIdleAborted ? "watchdog" : "other") as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, }); - throw streamingError; - } - - logForDebugging( - `Error streaming, falling back to non-streaming mode: ${errorMessage(streamingError)}`, - { level: "error" }, - ); - didFallBackToNonStreaming = true; - if (options.onStreamingFallback) { - options.onStreamingFallback(); - } - logEvent("tengu_streaming_fallback_to_non_streaming", { - model: - options.model as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - error: - streamingError instanceof Error - ? (streamingError.name as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS) - : (String( - streamingError, - ) as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS), - attemptNumber, - maxOutputTokens, - thinkingType: - thinkingConfig.type as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - fallback_disabled: false, - request_id: (streamRequestId ?? - "unknown") as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - fallback_cause: (streamIdleAborted - ? "watchdog" - : "other") as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - }); - - // Fall back to non-streaming mode with retries. - // If the streaming failure was itself a 529, count it toward the - // consecutive-529 budget so total 529s-before-model-fallback is the - // same whether the overload was hit in streaming or non-streaming mode. - // This is a speculative fix for https://github.com/anthropics/claude-code/issues/1513 - // Instrumentation: proves executeNonStreamingRequest was entered (vs. the - // fallback event firing but the call itself hanging at dispatch). - logForDiagnosticsNoPII("info", "cli_nonstreaming_fallback_started"); - logEvent("tengu_nonstreaming_fallback_started", { - request_id: (streamRequestId ?? - "unknown") as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - model: - options.model as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - fallback_cause: (streamIdleAborted - ? "watchdog" - : "other") as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, - }); - const result = yield* executeNonStreamingRequest( - { model: options.model, source: options.querySource }, - { - model: options.model, - fallbackModel: options.fallbackModel, - thinkingConfig, - ...(isFastModeEnabled() && { fastMode: isFastMode }), - signal, - initialConsecutive529Errors: is529Error(streamingError) ? 1 : 0, - querySource: options.querySource, - }, - paramsFromContext, - (attempt, _startTime, tokens) => { - attemptNumber = attempt; - maxOutputTokens = tokens; - }, - (params) => captureAPIRequest(params, options.querySource), - streamRequestId, - ); + // Fall back to non-streaming mode with retries. + // If the streaming failure was itself a 529, count it toward the + // consecutive-529 budget so total 529s-before-model-fallback is the + // same whether the overload was hit in streaming or non-streaming mode. + // This is a speculative fix for https://github.com/anthropics/claude-code/issues/1513 + // Instrumentation: proves executeNonStreamingRequest was entered (vs. the + // fallback event firing but the call itself hanging at dispatch). + logForDiagnosticsNoPII("info", "cli_nonstreaming_fallback_started"); + logEvent("tengu_nonstreaming_fallback_started", { + request_id: (streamRequestId ?? + "unknown") as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + model: + options.model as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + fallback_cause: (streamIdleAborted + ? "watchdog" + : "other") as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, + }); + const result = yield* executeNonStreamingRequest( + { model: options.model, source: options.querySource }, + { + model: options.model, + fallbackModel: options.fallbackModel, + thinkingConfig, + ...(isFastModeEnabled() && { fastMode: isFastMode }), + signal, + initialConsecutive529Errors: is529Error(streamingError) ? 1 : 0, + querySource: options.querySource, + }, + paramsFromContext, + (attempt, _startTime, tokens) => { + attemptNumber = attempt; + maxOutputTokens = tokens; + }, + (params) => captureAPIRequest(params, options.querySource), + streamRequestId, + ); - const m: AssistantMessage = { - message: { - ...result, - usage: normalizeUsage(result.usage), - content: normalizeContentFromAPI( - result.content, - tools, - options.agentId, - ), - }, - requestId: streamRequestId ?? undefined, - type: "assistant", - uuid: randomUUID(), - timestamp: new Date().toISOString(), - ...(process.env.USER_TYPE === "ant" && - research !== undefined && { - research, + const m: AssistantMessage = { + message: { + ...result, + usage: normalizeUsage(result.usage), + content: normalizeContentFromAPI( + result.content, + tools, + options.agentId, + ), + }, + requestId: streamRequestId ?? undefined, + type: "assistant", + uuid: randomUUID(), + timestamp: new Date().toISOString(), + ...(process.env.USER_TYPE === "ant" && + research !== undefined && { + research, + }), + ...(advisorModel && { + advisorModel, }), - ...(advisorModel && { - advisorModel, - }), - }; - newMessages.push(m); - fallbackMessage = m; - yield m; - } finally { - clearStreamIdleTimers(); + }; + newMessages.push(m); + fallbackMessage = m; + yield m; + } finally { + clearStreamIdleTimers(); + } + break; } } catch (errorFromRetry) { // FallbackTriggeredError must propagate to query.ts, which performs the diff --git a/src/services/api/errors.ts b/src/services/api/errors.ts index c9237ca0..08bb50d9 100644 --- a/src/services/api/errors.ts +++ b/src/services/api/errors.ts @@ -50,6 +50,7 @@ import { } from '../claudeAiLimits.js' import { shouldProcessRateLimits } from '../rateLimitMocking.js' // Used for /mock-limits command import { extractConnectionErrorDetails, formatAPIError } from './errorUtils.js' +import { isContextOverflowText, parseContextOverflowTokens } from '../../utils/providerErrors.js' export const API_ERROR_MESSAGE_PREFIX = 'API Error' @@ -86,13 +87,8 @@ export function parsePromptTooLongTokenCounts(rawMessage: string): { actualTokens: number | undefined limitTokens: number | undefined } { - const match = rawMessage.match( - /prompt is too long[^0-9]*(\d+)\s*tokens?\s*>\s*(\d+)/i, - ) - return { - actualTokens: match ? parseInt(match[1]!, 10) : undefined, - limitTokens: match ? parseInt(match[2]!, 10) : undefined, - } + const { actualTokens, limitTokens } = parseContextOverflowTokens(rawMessage) + return { actualTokens, limitTokens } } /** @@ -559,10 +555,7 @@ export function getAssistantMessageFromError( // Handle prompt too long errors (Vertex returns 413, direct API returns 400) // Use case-insensitive check since Vertex returns "Prompt is too long" (capitalized) - if ( - error instanceof Error && - error.message.toLowerCase().includes('prompt is too long') - ) { + if (error instanceof Error && isContextOverflowText(error.message)) { // Content stays generic (UI matches on exact string). The raw error with // token counts goes into errorDetails — reactive compact's retry loop // parses the gap from there via getPromptTooLongTokenGap. @@ -1008,12 +1001,7 @@ export function classifyAPIError(error: unknown): string { } // Prompt/content size errors - if ( - error instanceof Error && - error.message - .toLowerCase() - .includes(PROMPT_TOO_LONG_ERROR_MESSAGE.toLowerCase()) - ) { + if (error instanceof Error && isContextOverflowText(error.message)) { return 'prompt_too_long' } diff --git a/src/services/api/withRetry.ts b/src/services/api/withRetry.ts index 5ec9ad08..6c22517a 100644 --- a/src/services/api/withRetry.ts +++ b/src/services/api/withRetry.ts @@ -11,17 +11,22 @@ import { isAwsCredentialsProviderError } from 'src/utils/aws.js' import { logForDebugging } from 'src/utils/debug.js' import { logError } from 'src/utils/log.js' import { createSystemAPIErrorMessage } from 'src/utils/messages.js' -import { getAPIProviderForStatsig } from 'src/utils/model/providers.js' +import { + getAPIProviderForStatsig, + isFirstPartyAnthropicBaseUrl, +} from 'src/utils/model/providers.js' import { clearApiKeyHelperCache, clearAwsCredentialsCache, clearGcpCredentialsCache, getClaudeAIOAuthTokens, + getConfiguredApiKeyHelper, handleOAuth401Error, isClaudeAISubscriber, isEnterpriseSubscriber, } from '../../utils/auth.js' import { isEnvTruthy } from '../../utils/envUtils.js' +import { isQuotaErrorText } from '../../utils/providerErrors.js' import { errorMessage } from '../../utils/errors.js' import { type CooldownReason, @@ -36,6 +41,7 @@ import { disableKeepAlive } from '../../utils/proxy.js' import { sleep } from '../../utils/sleep.js' import type { ThinkingConfig } from '../../utils/thinking.js' import { getFeatureValue_CACHED_MAY_BE_STALE } from '../analytics/growthbook.js' +import { shouldUseOpenAICodexAuth } from '../openaiAuth/fetch.js' import { type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, logEvent, @@ -516,7 +522,23 @@ export async function* withRetry( throw new CannotRetryError(lastError, retryContext) } -function getRetryAfter(error: unknown): string | null { +const NON_RETRYABLE_STREAM_ERROR_TYPES = new Set([ + 'invalid_request_error', + 'authentication_error', + 'permission_error', + 'billing_error', + 'not_found_error', + 'request_too_large', +]) + +export function isRetryableStreamError(error: unknown): boolean { + if (error instanceof APIUserAbortError) return false + if (!(error instanceof APIError)) return true + if (error.status !== undefined) return shouldRetry(error) + return !NON_RETRYABLE_STREAM_ERROR_TYPES.has(String(error.type)) +} + +export function getRetryAfter(error: unknown): string | null { return ( ((error as { headers?: { 'retry-after'?: string } }).headers?.[ 'retry-after' @@ -699,6 +721,10 @@ function shouldRetry(error: APIError): boolean { return false } + if (!isFirstPartyAnthropicBaseUrl() && isQuotaErrorText(error.message)) { + return false + } + // Persistent mode: 429/529 always retryable, bypass subscriber gates and // x-should-retry header. if (isPersistentRetryEnabled() && isTransientCapacityError(error)) { @@ -772,7 +798,7 @@ function shouldRetry(error: APIError): boolean { // OAuth token handling is done in the main retry loop via handleOAuth401Error. if (error.status === 401) { clearApiKeyHelperCache() - return true + return canRefreshCredentials() } // Retry on 403 "token revoked" (same refresh logic as 401, see above) @@ -786,6 +812,15 @@ function shouldRetry(error: APIError): boolean { return false } +function canRefreshCredentials(): boolean { + return ( + isFirstPartyAnthropicBaseUrl() || + !!getConfiguredApiKeyHelper() || + !!getClaudeAIOAuthTokens()?.accessToken || + shouldUseOpenAICodexAuth() + ) +} + export function getDefaultMaxRetries(): number { if (process.env.CLAUDE_CODE_MAX_RETRIES) { return parseInt(process.env.CLAUDE_CODE_MAX_RETRIES, 10) diff --git a/src/services/compact/autoCompact.test.ts b/src/services/compact/autoCompact.test.ts index 79436480..8a3d834b 100644 --- a/src/services/compact/autoCompact.test.ts +++ b/src/services/compact/autoCompact.test.ts @@ -3,7 +3,8 @@ import { mkdtemp, rm, writeFile } from 'node:fs/promises' import { tmpdir } from 'node:os' import { join } from 'node:path' -import { getAutoCompactThreshold, getEffectiveContextWindowSize } from './autoCompact.js' +import { getAutoCompactThreshold, getEffectiveContextWindowSize, shouldAutoCompact } from './autoCompact.js' +import { createAssistantMessage, createUserMessage } from '../../utils/messages.js' import { getContextWindowForModel } from '../../utils/context.js' import { MODEL_CONTEXT_WINDOWS_ENV_KEY } from '../../utils/model/modelContextWindows.js' import { resetSettingsCache } from '../../utils/settings/settingsCache.js' @@ -94,3 +95,40 @@ describe('auto-compact threshold', () => { expect(getAutoCompactThreshold('deepseek-v4-pro')).toBe(490_000) }) }) + +describe('auto compact without usage from the provider', () => { + const zeroUsage = { + input_tokens: 0, + output_tokens: 0, + cache_creation_input_tokens: 0, + cache_read_input_tokens: 0, + } + + function reply(content: string, usage: typeof zeroUsage) { + const message = createAssistantMessage({ content, usage: usage as never }) + message.message.model = 'kimi-k2.6' + return message + } + + test('falls back to the local estimate when the last reply reports zero usage', async () => { + const messages = [ + createUserMessage({ content: 'x'.repeat(1_200_000) }), + reply('done', zeroUsage), + createUserMessage({ content: 'next' }), + ] + + expect(await shouldAutoCompact(messages, 'kimi-k2.6')).toBe(true) + }) + + test('uses the last reply that does report usage', async () => { + const messages = [ + createUserMessage({ content: 'hello' }), + reply('first', { ...zeroUsage, input_tokens: 250_000 }), + createUserMessage({ content: 'more' }), + reply('second', zeroUsage), + createUserMessage({ content: 'next' }), + ] + + expect(await shouldAutoCompact(messages, 'kimi-k2.6')).toBe(true) + }) +}) diff --git a/src/services/openaiAuth/fetch.test.ts b/src/services/openaiAuth/fetch.test.ts index ff28642e..eea21e4c 100644 --- a/src/services/openaiAuth/fetch.test.ts +++ b/src/services/openaiAuth/fetch.test.ts @@ -157,4 +157,37 @@ describe('buildOpenAICodexFetch', () => { error: { type: 'api_error', message: 'model overloaded' }, }) }) + + test.each([ + ['a JSON reply', () => Response.json({ + id: 'resp_1', + object: 'response', + created_at: 0, + model: 'gpt-5.5', + status: 'incomplete', + incomplete_details: { reason: 'content_filter' }, + output: [], + })], + ['a streamed reply', () => new Response([ + 'event: response.incomplete', + 'data: {"type":"response.incomplete","response":{"id":"resp_1","status":"incomplete","incomplete_details":{"reason":"content_filter"},"output":[]}}', + '', + ].join('\n'), { headers: { 'Content-Type': 'text/event-stream' } })], + ])('answers a content-filtered %s for a non-streaming caller with an Anthropic error', async (_kind, reply) => { + const openAIFetch = buildOpenAICodexFetch(async () => reply(), 'test') + const response = await openAIFetch('https://api.anthropic.com/v1/messages', { + method: 'POST', + body: JSON.stringify({ + model: 'gpt-5.5', + max_tokens: 64, + messages: [{ role: 'user', content: 'Say ok' }], + }), + }) + + expect(response.status).toBe(400) + await expect(response.json()).resolves.toEqual({ + type: 'error', + error: { type: 'invalid_request_error', message: "The provider's content filter stopped the reply (incomplete: content_filter)." }, + }) + }) }) diff --git a/src/services/openaiAuth/fetch.ts b/src/services/openaiAuth/fetch.ts index 81be5320..c1df0e42 100644 --- a/src/services/openaiAuth/fetch.ts +++ b/src/services/openaiAuth/fetch.ts @@ -7,10 +7,8 @@ import { getOpenAIOAuthTokens } from './storage.js' import { anthropicToOpenaiResponses } from '../../server/proxy/transform/anthropicToOpenaiResponses.js' import { openaiResponsesToAnthropic } from '../../server/proxy/transform/openaiResponsesToAnthropic.js' import { openaiResponsesStreamToAnthropic } from '../../server/proxy/streaming/openaiResponsesStreamToAnthropic.js' -import { - OpenAIResponsesStreamError, - openaiResponsesStreamToAnthropicResponse, -} from '../../server/proxy/streaming/openaiResponsesStreamToAnthropicResponse.js' +import { openaiResponsesStreamToAnthropicResponse } from '../../server/proxy/streaming/openaiResponsesStreamToAnthropicResponse.js' +import { anthropicErrorResponse, UpstreamReplyError } from '../../server/upstream/upstreamError.js' import type { AnthropicRequest } from '../../server/proxy/transform/types.js' import { logForDebugging } from '../../utils/debug.js' @@ -111,29 +109,15 @@ export function buildOpenAICodexFetch( ) } - if (upstream.body && isEventStreamResponse(upstream)) { - try { - const responseBody = await openaiResponsesStreamToAnthropicResponse( - upstream.body, - mappedModel, - ) - return Response.json(responseBody) - } catch (error) { - if (!(error instanceof OpenAIResponsesStreamError)) throw error - return Response.json( - { - type: 'error', - error: { type: 'api_error', message: error.message }, - }, - { status: 502 }, - ) - } + try { + const responseBody = upstream.body && isEventStreamResponse(upstream) + ? await openaiResponsesStreamToAnthropicResponse(upstream.body, mappedModel) + : openaiResponsesToAnthropic(await upstream.json(), mappedModel) + return Response.json(responseBody) + } catch (error) { + if (!(error instanceof UpstreamReplyError)) throw error + return anthropicErrorResponse(error.error) } - - const responseBody = await upstream.json() - return Response.json( - openaiResponsesToAnthropic(responseBody, mappedModel), - ) } } diff --git a/src/services/tools/__tests__/truncatedToolArguments.test.ts b/src/services/tools/__tests__/truncatedToolArguments.test.ts new file mode 100644 index 00000000..e9da2a3c --- /dev/null +++ b/src/services/tools/__tests__/truncatedToolArguments.test.ts @@ -0,0 +1,101 @@ +import { describe, expect, test } from 'bun:test' +import { openaiChatToAnthropic } from '../../../server/proxy/transform/openaiChatToAnthropic.js' +import { parseOpenAIToolArguments } from '../../../server/proxy/transform/toolArguments.js' +import type { OpenAIChatResponse } from '../../../server/proxy/transform/types.js' +import type { Tool, ToolUseContext, Tools } from '../../../Tool.js' +import type { AssistantMessage } from '../../../types/message.js' +import { createAssistantMessage, normalizeContentFromAPI } from '../../../utils/messages.js' +import { runToolUse } from '../toolExecution.js' + +const truncated = '{"file_path":"/tmp/a.ts","content":"export const a = 1\\nexport const b' + +function writeTool(calls: unknown[]): Tool { + return { + name: 'Write', + call: async (input: unknown) => { + calls.push(input) + return { data: 'written' } + }, + } as unknown as Tool +} + +function normalizedInput(input: unknown, tools: Tools): unknown { + const [block] = normalizeContentFromAPI( + [{ type: 'tool_use', id: 'toolu_1', name: 'Write', input } as never], + tools, + ) + return (block as { input: unknown }).input +} + +async function run(input: unknown, tools: Tools) { + const assistant = createAssistantMessage({ + content: [{ type: 'tool_use', id: 'toolu_1', name: 'Write', input } as never], + }) as AssistantMessage + const context = { + options: { tools, mcpClients: [] }, + abortController: new AbortController(), + } as unknown as ToolUseContext + const updates = [] + for await (const update of runToolUse( + { type: 'tool_use', id: 'toolu_1', name: 'Write', input } as never, + assistant, + async () => ({ behavior: 'allow' }) as never, + context, + )) { + updates.push(update) + } + return updates +} + +describe('truncated tool arguments', () => { + test('the non-streaming proxy passes unparseable arguments on as the raw string', () => { + const response = { + id: 'c1', + object: 'chat.completion', + created: 0, + model: 'deepseek-chat', + choices: [{ + index: 0, + message: { role: 'assistant', content: null, tool_calls: [{ id: 'call_1', type: 'function', function: { name: 'Write', arguments: truncated } }] }, + finish_reason: 'length', + }], + } as OpenAIChatResponse + + const block = openaiChatToAnthropic(response, 'deepseek-chat').content[0] + + expect(block).toMatchObject({ type: 'tool_use', input: truncated }) + }) + + test.each([ + ['a streamed tool call cut off by the output limit', truncated], + ['arguments that are JSON but not an object', '["a.ts"]'], + ])('marks %s instead of turning it into an empty object', (_kind, input) => { + const marked = normalizedInput(input, [writeTool([])]) + + expect(marked).toEqual({ + __dreamcoder_invalid_arguments: { receivedChars: input.length, parseError: expect.any(String) }, + }) + }) + + test.each(['', ' ', 'null'])('still treats the argument string %p as no arguments', (input) => { + expect(normalizedInput(input, [writeTool([])])).toEqual({}) + }) + + test.each(['null', ' '])('the non-streaming proxy turns the argument string %p into no arguments', (args) => { + expect(parseOpenAIToolArguments(args)).toEqual({}) + }) + + test('does not run the tool and tells the model the arguments were cut off', async () => { + const calls: unknown[] = [] + const tools = [writeTool(calls)] + + const updates = await run(normalizedInput(truncated, tools), tools) + + expect(calls).toHaveLength(0) + expect(updates).toHaveLength(1) + const [result] = (updates[0]!.message as { message: { content: Array> } }).message.content + expect(result).toMatchObject({ type: 'tool_result', tool_use_id: 'toolu_1', is_error: true }) + expect(String(result!.content)).toContain(`received ${truncated.length} characters`) + expect(String(result!.content)).toContain('cut off by the output token limit') + }) +}) diff --git a/src/services/tools/toolExecution.ts b/src/services/tools/toolExecution.ts index 4e024010..22d107a1 100644 --- a/src/services/tools/toolExecution.ts +++ b/src/services/tools/toolExecution.ts @@ -69,6 +69,10 @@ import { TelemetrySafeError_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS, } from '../../utils/errors.js' import { executePermissionDeniedHooks } from '../../utils/hooks.js' +import { + invalidToolArgumentsMessage, + readInvalidToolArguments, +} from '../../utils/invalidToolArguments.js' import { logError } from '../../utils/log.js' import { CANCEL_MESSAGE, @@ -411,6 +415,26 @@ export async function* runToolUse( return } + const invalidArguments = readInvalidToolArguments(toolUse.input) + if (invalidArguments) { + const message = invalidToolArgumentsMessage(invalidArguments) + yield { + message: createUserMessage({ + content: [ + { + type: 'tool_result', + content: `${message}`, + is_error: true, + tool_use_id: toolUse.id, + }, + ], + toolUseResult: message, + sourceToolAssistantUUID: assistantMessage.uuid, + }), + } + return + } + const toolInput = toolUse.input as { [key: string]: string } try { if (toolUseContext.abortController.signal.aborted) { diff --git a/src/utils/invalidToolArguments.ts b/src/utils/invalidToolArguments.ts new file mode 100644 index 00000000..bc00bcd7 --- /dev/null +++ b/src/utils/invalidToolArguments.ts @@ -0,0 +1,32 @@ +const INVALID_TOOL_ARGUMENTS_KEY = '__dreamcoder_invalid_arguments' + +export type InvalidToolArguments = { receivedChars: number; parseError: string } + +function isRecord(value: unknown): value is Record { + return typeof value === 'object' && value !== null && !Array.isArray(value) +} + +export function parseToolArguments(raw: string): Record { + if (raw.trim().length === 0) return {} + let parseError: string + try { + const parsed: unknown = JSON.parse(raw) + if (parsed === null) return {} + if (isRecord(parsed)) return parsed + parseError = 'the arguments are not a JSON object' + } catch (error) { + parseError = error instanceof Error ? error.message : String(error) + } + const invalid: InvalidToolArguments = { receivedChars: raw.length, parseError } + return { [INVALID_TOOL_ARGUMENTS_KEY]: invalid } +} + +export function readInvalidToolArguments(input: unknown): InvalidToolArguments | undefined { + if (!isRecord(input)) return undefined + const invalid = input[INVALID_TOOL_ARGUMENTS_KEY] + return isRecord(invalid) ? invalid as InvalidToolArguments : undefined +} + +export function invalidToolArgumentsMessage({ receivedChars, parseError }: InvalidToolArguments): string { + return `The arguments of this tool call are not a complete JSON object (received ${receivedChars} characters: ${parseError}). They were most likely cut off by the output token limit, so the tool was not run. Call the tool again with shorter arguments, for example by writing a large file in several smaller parts.` +} diff --git a/src/utils/messages.ts b/src/utils/messages.ts index 29e0c35f..647c56e8 100644 --- a/src/utils/messages.ts +++ b/src/utils/messages.ts @@ -156,6 +156,10 @@ import { stripIdeContextTags } from './displayTags.js' import { hasEmbeddedSearchTools } from './embeddedTools.js' import { formatFileSize } from './format.js' import { validateImagesForAPI } from './imageValidation.js' +import { + parseToolArguments, + readInvalidToolArguments, +} from './invalidToolArguments.js' import { safeParseJSON } from './json.js' import { logError, logMCPDebug } from './log.js' import { normalizeLegacyToolName } from './permissions/permissionRuleParser.js' @@ -2768,12 +2772,8 @@ export function normalizeContentFromAPI( // TODO: This needs patching as recursive fields can still be stringified let normalizedInput: unknown if (typeof contentBlock.input === 'string') { - const parsed = safeParseJSON(contentBlock.input) - if (parsed === null && contentBlock.input.length > 0) { - // TET/FC-v3 diagnostic: the streamed tool input JSON failed to - // parse. We fall back to {} which means downstream validation - // sees empty input. The raw prefix goes to debug log only — no - // PII-tagged proto column exists for it yet. + normalizedInput = parseToolArguments(contentBlock.input) + if (readInvalidToolArguments(normalizedInput)) { logEvent('tengu_tool_input_json_parse_fail', { toolName: sanitizeToolNameForAnalytics(contentBlock.name), inputLen: contentBlock.input.length, @@ -2785,13 +2785,16 @@ export function normalizeContentFromAPI( ) } } - normalizedInput = parsed ?? {} } else { normalizedInput = contentBlock.input } // Then apply tool-specific corrections - if (typeof normalizedInput === 'object' && normalizedInput !== null) { + if ( + typeof normalizedInput === 'object' && + normalizedInput !== null && + !readInvalidToolArguments(normalizedInput) + ) { const tool = findToolByName(tools, contentBlock.name) if (tool) { try { diff --git a/src/utils/providerErrors.ts b/src/utils/providerErrors.ts new file mode 100644 index 00000000..b0d74537 --- /dev/null +++ b/src/utils/providerErrors.ts @@ -0,0 +1,88 @@ +export type ProviderErrorKind = 'context_overflow' | 'quota' | 'auth' | 'rate_limit' + +const OVERFLOW_CODES = new Set([ + 'context_length_exceeded', + 'context_window_exceeded', + 'model_context_window_exceeded', + '1261', +]) + +const OVERFLOW_PATTERNS = [ + /prompt is too long/i, + /maximum context length/i, + /context[ _](?:length|window)[ _](?:is )?exceeded/i, + /exceeds? the (?:model's )?context window/i, + /range of input length should be/i, + /input token count.*exceeds? the maximum number of tokens/i, + /exceeded model token limit/i, + /message token length.*exceeds? model limit/i, + /prompt exceeds max length/i, +] + +const QUOTA_CODES = new Set([ + 'insufficient_quota', + 'exceeded_current_quota_error', + 'billing_hard_limit_reached', + 'insufficient_balance', + '1113', +]) + +const QUOTA_PATTERNS = [ + /insufficient[ _](?:quota|balance|credits)/i, + /exceeded (?:your |the )?current quota/i, + /exceeded_current_quota_error/i, + /billing_hard_limit_reached/i, + /"code"\s*:\s*"?1113\b/, + /余额不足/, +] + +const AUTH_CODES = new Set(['invalid_api_key', 'invalid_authentication', 'authentication_error', 'unauthorized']) + +const RATE_LIMIT_CODES = new Set(['rate_limit_exceeded', 'rate_limit_error', '1302', '1303', '1305']) + +const TOKEN_COUNT_PATTERNS: Array<{ pattern: RegExp; actual: number; limit: number }> = [ + { pattern: /prompt is too long[^0-9]*(\d+)\s*tokens?\s*>\s*(\d+)/i, actual: 1, limit: 2 }, + { pattern: /maximum context length is (\d+) tokens.*?(?:resulted in|requested about) (\d+) tokens/is, actual: 2, limit: 1 }, + { pattern: /input token count \((\d+)\) exceeds? the maximum number of tokens allowed \((\d+)\)/i, actual: 1, limit: 2 }, + { pattern: /message token length (\d+) exceeds? model limit (\d+)/i, actual: 1, limit: 2 }, +] + +function hasCode(codes: Set, code: unknown): boolean { + return (typeof code === 'string' || typeof code === 'number') && codes.has(String(code).toLowerCase()) +} + +function isContextOverflowCode(code: unknown): boolean { + return hasCode(OVERFLOW_CODES, code) +} + +export function isQuotaErrorText(text: string): boolean { + return QUOTA_PATTERNS.some((pattern) => pattern.test(text)) +} + +export function classifyProviderError(error: { status?: number; code?: string; message: string }): ProviderErrorKind | undefined { + if (isContextOverflowCode(error.code) || isContextOverflowText(error.message)) return 'context_overflow' + if (error.status === 402 || hasCode(QUOTA_CODES, error.code) || isQuotaErrorText(error.message)) return 'quota' + if (error.status === 401 || error.status === 403 || hasCode(AUTH_CODES, error.code)) return 'auth' + if (error.status === 429 || hasCode(RATE_LIMIT_CODES, error.code)) return 'rate_limit' + return undefined +} + +export function isContextOverflowText(text: string): boolean { + return OVERFLOW_PATTERNS.some((pattern) => pattern.test(text)) +} + +export function parseContextOverflowTokens(text: string): { actualTokens?: number; limitTokens?: number } { + for (const { pattern, actual, limit } of TOKEN_COUNT_PATTERNS) { + const match = text.match(pattern) + if (match) return { actualTokens: Number(match[actual]), limitTokens: Number(match[limit]) } + } + return {} +} + +export function toPromptTooLongMessage(text: string): string { + const { actualTokens, limitTokens } = parseContextOverflowTokens(text) + const counts = actualTokens !== undefined && limitTokens !== undefined + ? `: ${actualTokens} tokens > ${limitTokens} maximum` + : '' + return `prompt is too long${counts} · ${text}` +} diff --git a/src/utils/tokens.ts b/src/utils/tokens.ts index 3c3034bb..54bf4428 100644 --- a/src/utils/tokens.ts +++ b/src/utils/tokens.ts @@ -12,7 +12,8 @@ export function getTokenUsage(message: Message): Usage | undefined { message.message.content[0]?.type === 'text' && SYNTHETIC_MESSAGES.has(message.message.content[0].text) ) && - message.message.model !== SYNTHETIC_MODEL + message.message.model !== SYNTHETIC_MODEL && + getTokenCountFromUsage(message.message.usage) > 0 ) { return message.message.usage }