@qwen-code/arena-agent 0.0.10-dev.1 → 0.0.10-dev.10

package/README.md

@@ -1,9 +1,12 @@
 # Arena CodeAgent Harness
 
+版本变化见 [Changelog](CHANGELOG.md)，发布前请按[发版流程](docs/MODES_AND_RELEASES.md#发布节奏)
+更新变更记录并运行 `npm run check:changelog`。
+
 这是一个基于 `message.json` 与 `tools.json` 所定义消息和工具契约的 TypeScript
 CodeAgent harness。运行时只依赖 Node.js，不再依赖 Python：
 
-- `arena -p ...`：headless 单轮入口，支持文本、完整 JSON 和 NDJSON 流。
+- `arena -p ...` / `arena --file prompt.txt`：headless 单轮入口，支持文本、完整 JSON 和 NDJSON 流。
 - `arena tui`：终端多轮对话，实时输出并自动保存、恢复历史。
 - `arena serve`：HTTP daemon、Web UI 与双通道 SSE 实时接口。
 - Agent loop：流式 assistant → tool call → tool result → assistant。
@@ -72,6 +75,10 @@ Linux libc 分别构建；不能把 macOS 上生成的文件直接用于 Linux
 | HTML | `--mode html` | 空工作区，生成单个 `index.html` |
 | Full Stack | `--mode full-stack` | Next.js + PostgreSQL scaffold |
 
+Code Arena 默认模型步数上限为 React `75`、HTML `25`、Full Stack `75`。
+三个模式的 `read_file` 都能向支持视觉输入的模型提供不超过 10 MB 的 PNG/JPEG 图片；
+其他二进制文件仍会返回错误。
+
 四种模式共用同一套配置、provider、agent loop、上下文压缩、历史记录、服务端、
 TUI 和 SDK，只替换模式对应的 system prompt、tools 与可选 scaffold：
 
@@ -86,10 +93,84 @@ code-harness -p '做一个产品页'
 code-harness -p '做一个单文件网页' --mode html
 ```
 
+当提示词较大时，可以把 UTF-8 文本写入文件，并让 CLI 在进程启动后读取：
+
+```bash
+arena --file prompt.txt --mode arena
+code-harness --file prompt.txt --mode react
+```
+
+`--file` 与 `-p`/`--prompt` 互斥。相对路径以启动命令时的当前目录为基准。与
+`arena -p "$(<prompt.txt)"` 不同，命令行中只传递较短的文件路径，因此不会让
+提示词本身触发 Linux 单个命令行参数的大小上限。
+
 也可以设置 `ARENA_HARNESS_MODE=arena|react|html|full-stack`。迁移期继续接受
 `CODE_HARNESS_MODE`、`ARENA_MODE` 及旧模式别名。详细目录和发包决策见
 [`docs/MODES_AND_RELEASES.md`](docs/MODES_AND_RELEASES.md)。
 
+### 中途快照与单步执行
+
+Headless CLI 可通过 JavaScript Hook 决定何时继续或创建 Harbor 快照。工具校验在
+整批工具执行前触发；输出重复在主模型生成正文或 reasoning 时触发。
+
+| 类型 | 含义 |
+| --- | --- |
+| `valid` | 工具和参数合法 |
+| `unknown_tool` | 工具名称不存在 |
+| `invalid_json` | 工具参数不是合法 JSON |
+| `invalid_arguments` | 参数不符合工具 schema |
+| `repetitive_output` | 模型持续重复同一字符或片段 |
+
+| Hook 返回值 | 后续行为 |
+| --- | --- |
+| `continue` 或 `false` | 正常继续 |
+| `snapshot_continue` 或 `true` | 快照后继续当前生成与工具执行 |
+| `snapshot_exit` | 停止当前生成，保存快照后退出，本批工具不执行 |
+
+例如，将以下内容保存为 `policy.mjs`：
+
+```js
+export default function (event) {
+  const stop = event.type === "repetitive_output"
+    || event.toolCalls.some(call => call.validation !== "valid");
+  return stop ? "snapshot_exit" : "continue";
+}
+```
+
+在启动进程的环境中配置（工作区 `.env` 不用于加载 Hook 或快照配置）：
+
+```bash
+export ARENA_MIDTURN_CHECKPOINT_HOOK=/absolute/path/policy.mjs
+export HARBOR_REMOTE_COMMAND_BASE_URL="http://<harbor-host>:<port>"
+export HARBOR_REMOTE_COMMAND_API_KEY="<api-key>"
+```
+
+配置 Hook 后自动检测输出重复，命中时由 Hook 决定继续、快照或退出；未配置 Hook
+时按默认流程执行。检测连续重复至少 512 个 Unicode 字符、至少 4 次的片段，
+片段最长 1024 字符，忽略纯空白和标点填充。
+正文与 reasoning 分开检测，工具参数和工具结果不参与；每次生成最多触发一次重复事件。
+事件的 `repetition.channel` 和 `repetition.sample` 提供通道与最多 256 字符的诊断片段。
+
+快照保存当前回复生成前的 `history.json`。恢复快照对应环境后，使用原 session ID
+续跑同一个 user turn，不追加用户消息；被中止的那一步会重新生成：
+
+```bash
+arena --continue --session-id demo
+```
+
+`--single-step` 每次只完成一次模型回复及其整批工具调用，保存结果后退出。
+它无需 Hook，也不自行创建快照；下次续跑从已保存的下一步开始。
+
+```bash
+arena -p "完成这个任务" --session-id demo --single-step
+arena --continue --session-id demo --single-step
+```
+
+正常暂停返回 `status: "paused"`、退出码 `0`，`stop_reason` 为 `checkpoint` 或
+`single_step`；Hook 快照退出优先于单步限制。最终回复仍返回 `success`，需要输入
+时返回 `needs_input`，Hook、快照或保存失败时返回 `error` 并以非零退出码结束。
+`--continue` 要求会话尚未完成，不能同时传入新 prompt、文件或附件。
+
 如需完全替换模型收到的 system prompt，可在任一运行入口传入
 `--system-prompt <text>`：
 
@@ -100,9 +181,15 @@ arena serve --system-prompt '只使用中文回复。'
 ```
 
 该参数只在运行时覆盖第一条 system message，不会修改 canonical prompt fixture；
-续跑已有 session 时，当前传入的值会替换历史中的 system message。未传参数时，
+续跑已有 session 时，使用当前参数重新生成运行时 system message。未传参数时，
 日期、workspace 和 mode 对应的现有 prompt 生成逻辑保持不变。
 
+history.json、增量日志和返回的 messages 只保存对话历史（含 compaction），不保存运行时生成的开头 system；中途出现的 system 消息会保留。
+新会话和续跑均在构建模型请求时前置运行时 system；官方以 user 开头的历史可直接续跑。
+旧版带开头 system 的本地历史仍可读取，该旧前缀不作为本次指令，后续写入会移除它。
+每次运行（包括 resume）都会重新探测当前工作区和 Git 状态来填充仓库提示词，
+不从旧 system 或会话 metadata 恢复仓库信息；因此不同轮次的 system 可以变化。
+
 如需保留当前 mode 生成的 system prompt，只在末尾追加任务或部署指令，可传入
 `--append-system-prompt <text>`：
 
@@ -144,19 +231,13 @@ Messages，`gemini/` 使用 Google 的 OpenAI-compatible 接口；`openai/` 或
 无前缀模型使用 OpenAI 传输，其中模型名包含 `gpt`（大小写不敏感）时默认
 使用 Responses，其余使用 Chat Completions。无前缀且名称包含 `claude` 时
 使用 Anthropic Messages。显式 provider 前缀与 `ARENA_OPENAI_API` 始终优先。
-LiteLLM 官方提供 Python SDK 或独立 Proxy，因此
-纯 TypeScript 版本使用
-[LiteLLM Proxy](https://docs.litellm.ai/) 作为多 provider 网关：
+模型出口只有 Chat Completions、Responses API 和 Anthropic Messages 三种协议。
+端点和密钥统一使用 `OPENAI_BASE_URL` / `OPENAI_API_KEY`，兼容旧的
+`ARENA_API_BASE` / `ARENA_API_KEY`。`LITELLM_PROXY_URL` 和 `LITELLM_API_KEY`
+已不再读取，即使仍在环境中也不会影响地址、认证、协议选择或参数格式。
+provider 前缀用于选择协议，发送给服务端时会剥离。
 
-```bash
-export LITELLM_PROXY_URL=http://127.0.0.1:4000/v1
-export LITELLM_API_KEY=sk-litellm
-export OPENAI_MODEL=anthropic/claude-sonnet-4-20250514
-```
-
-设置 `LITELLM_PROXY_URL` 时，模型名会原样发送给 LiteLLM。没有 Proxy 时，
-也支持直连：`openai/` 与 `gemini/` 前缀走各自的 OpenAI-compatibility 接口，
-`anthropic/` 前缀直接使用原生 Anthropic Messages 协议（`/v1/messages`）：
+配置示例：
 
 ```bash
 # OpenAI
@@ -190,8 +271,13 @@ Anthropic Messages payload 并使用 `x-api-key`；OpenAI 路由根据上述规
 回合会把这些 output items 连同 function output 一起完整回放到下一次 `input`，
 从而在不依赖 provider 端存储的情况下保留隐藏 reasoning。请求显式包含
 `reasoning.encrypted_content`；GPT-5.6 还会使用 `reasoning.context=all_turns`。
+设置 `ARENA_RESPONSES_REPLAY_REASONING_STATE=false` 可在发送 Responses 请求时，
+移除 `input` 中所有 `reasoning` item 的 `encrypted_content` 和 `id`；默认值为
+`true`。其他字段（如 `summary`）、工具调用和消息 ID 均保留，本地历史仍保存完整
+output items。该开关只控制下一轮回传，不阻止服务端返回加密内容，也不影响 Chat
+Completions 或 Anthropic Messages；关闭后模型无法通过这两个字段恢复历史隐藏推理。
 设置 `ARENA_OPENAI_API=chat` 或 `responses` 可覆盖 GPT 的自动选择。
-该开关不作用于 LiteLLM、Gemini 或 Anthropic 路由。如未设置统一入口，
+该开关不作用于 Gemini 或 Anthropic 路由。如未设置统一入口，
 Anthropic 可回退到 `ANTHROPIC_BASE_URL` /
 `ANTHROPIC_API_KEY`。
 
@@ -235,12 +321,12 @@ ARENA_ENABLE_THINKING=true
 ARENA_THINKING_BUDGET=81920
 ARENA_PRESERVE_THINKING=true
 ARENA_CONTEXT_WINDOW=1000000
-ARENA_CONTEXT_COMPACTION_RATIO=0.8
-ARENA_COMPACTION_SUMMARY_MAX_TOKENS=8192
+ARENA_CONTEXT_COMPACTION_RATIO=0.25
+ARENA_COMPACTION_SUMMARY_MAX_TOKENS=131072
 ```
 
 可选的 `ARENA_REASONING_EFFORT` 支持 `low`、`medium`、`high`、`xhigh`
-和 `max` 五档；Chat Completions 请求使用 `reasoning_effort`，Responses
+、`max` 和 `ultra` 六档；Chat Completions 请求使用 `reasoning_effort`，Responses
 请求使用 `reasoning.effort`，原生 Anthropic Messages 请求映射为
 `output_config.effort`。不会按模型静默
 降档；目标模型或兼容网关不支持所选档位时，由服务端返回明确错误。
@@ -264,34 +350,108 @@ ARENA_DISALLOWED_TOOLS=["bash","write_file"]
 Jina Reader。
 该密钥不会作为主模型连接的密钥。
 
-Harness 会在每次模型调用前估算消息、reasoning、工具 schema 和图片占用；达到
-`ARENA_CONTEXT_WINDOW × ARENA_CONTEXT_COMPACTION_RATIO`（默认 80%）时，调用
-当前模型把已完成的旧回合生成结构化续作摘要。只有发给模型的内存上下文会把
-旧前缀替换为符合既有会话格式的 leading `<arena-system-message>`；持久化的
-`history.json.messages` 保留原始消息，不会因压缩删除或替换前缀。当前用户回合及
-其后的 tool-call / result 链在模型上下文中保持原样。摘要重点保留目标、硬约束、
-发现、已完成/未完成事项、下一步和相关文件路径；摘要调用默认关闭 thinking，
-输出上限由
-`ARENA_COMPACTION_SUMMARY_MAX_TOKENS` 控制（默认 8192）。
+Agent Arena 通过 `ARENA_COMPACTION_MODE` 选择压缩方式，默认 `rolling`；设置为
+`summary` 可切换回原来的摘要式压缩，适用于 headless CLI、TUI 和服务端：
+
+```bash
+ARENA_COMPACTION_MODE=summary arena -p "继续任务" --session-id demo
+```
+
+`summary` 达到阈值时同步生成完整摘要，保留当前用户回合及其工具调用，不启动或恢复
+后台记忆缓存。它复用 `src/legacy-compaction.ts` 中的原实现：在引入 rolling 的
+提交 `c56456e9` 中，这份代码由旧 `src/compaction.ts` 完整保留；原 Agent Arena
+与当前 Code Arena 使用相同的摘要系统提示词、请求提示词和 continuation preamble。
+摘要按 `Goal`、`Instructions`、`Discoveries`、`Accomplished` 等章节生成，使用
+主模型、temperature=0、关闭 thinking，默认输出上限为 8192。
+`ARENA_COMPACTION_SUMMARY_MAX_TOKENS` 可覆盖上限；`rolling` 的默认上限仍为 131072。
+两种模式默认阈值均为 250k；只有窗口和比例两个环境变量都配置有效时才使用乘积。
+摘要模式沿用旧的
+本地 token 估算。旧实现只归档当前用户回合之前的内容，因此单个长用户回合没有
+可归档前缀时不会强制裁切。Code Arena 保持摘要式压缩，不受此环境变量影响。
+
+Agent Arena 在两种模式下都保存已应用的 `compaction` 历史记录；resume 或切换模式
+后继续使用这些记录，不丢失已压缩内容。历史 metadata 记录本次压缩方式，但下一次
+运行仍以当前环境变量为准，未设置时回到 `rolling`。
+
+以下后台记忆机制适用于 `rolling` 模式。
+
+Agent Arena 在每次模型调用前检查新增对话预算：自上次成功记忆更新以来，
+可归档内容的本地估算达到 `ARENA_MEMORY_UPDATE_TOKENS`（默认 24000）时，
+启动一个后台记忆更新任务。24000 是根据历史日志选择的暂定策略，不是已确认的官方常数。
+已有记忆、系统提示词和工具定义不计入新增预算；最新完整的模型／工具步骤保留原文。
+更新完成只刷新缓存，主模型继续使用原上下文。
+
+整体上下文达到压缩阈值时才回注最新记忆。Agent Arena 默认固定为 250,000 tokens；
+只有 `ARENA_CONTEXT_WINDOW` 与 `ARENA_CONTEXT_COMPACTION_RATIO` 两项都配置了
+有效值，才改用两者的乘积。未配置、只配置一项或任一值无效时，阈值仍为 250,000。
+计数优先采用最近一次主模型请求返回的 `total_tokens`，并只对
+该 assistant 之后追加的 tool 和 user 消息做本地增量估算；缺少 `total_tokens` 时，
+先尝试由 input/output usage 相加得到，若 output usage 也缺失则回退到 input usage
+加 assistant 及后续消息的本地估算。没有可靠 usage 锚点时回退到全量本地估算。
+有正在进行的更新则等待完成，必要时提前发起更新。
+Code Arena 仍使用窗口与比例相乘的阈值，压缩比例默认是 70%。
+每个会话只运行一个更新任务，失败保留原上下文，源内容推进后允许重试。
+Agent Arena 使用捕获的 session-memory 协议：只输出变化章节并合并，保留未输出章节，
+固定维护当前状态、任务、用户约束、工作区、已执行操作、外部来源、失败经验和关键结果。
+章节正文使用 `o200k_base` 计数，不包含标题和开头的斜体章节说明；超过每章节
+1500 tokens 时，下一次更新提示模型精简，不直接截断内容。
+
+主模型上下文通过新的 leading `<arena-system-message>` 回注记忆，最近完整的
+模型／工具步骤保持原样。后台记忆保存在 `history.json.session_memory` 中，包含最新
+成功快照、覆盖边界和前缀校验值，以及最近更新的状态；运行中的变化先写入增量日志，
+结束时合并进 `history.json`。实际触发压缩时，
+在 `history.json.messages` 中插入官方 dump 形式的 `role: "compaction"` 记录：
+正文为 `content: [{type: "text", text: "摘要正文"}]`，`compaction` 包含 `ratio`、
+`tokens_at_compaction` 和 `source`。普通消息格式不变，原始历史不删除。
+压缩记录插在已覆盖前缀与保留步骤之间，其位置就是已应用摘要的恢复边界。
+请求与 resume 使用系统提示词、最后一条未撤销压缩记录的摘要、
+以及其后的消息；`compaction` 角色只用于历史，不发送给模型。后台更新仍不会提前
+改变上下文。`undone: true` 的压缩记录不生效。
+这些字段及 `outer`/`inner` 值来自下载的官方 dump；本地将回合开始／工具循环内的
+压缩分别标为 `outer`／`inner`。token 数和比例使用本地估算，不代表已复刻官方计数。
+
+Agent Arena 的 `--single-step` 默认恢复后台记忆缓存，普通 turn 续跑默认不恢复。
+`--restore-session-memory` 可显式开启，`--no-restore-session-memory` 可显式关闭；
+也可设置 `ARENA_RESTORE_SESSION_MEMORY=true|false`（适用于 CLI、TUI 和服务端，
+命令行标志优先）。恢复前会校验记忆覆盖的历史前缀；不匹配的缓存会被丢弃。
+关闭恢复不会删除仍有效的已存快照。恢复缓存本身不触发压缩，也不影响历史里
+已应用的 `compaction` 记录。
+
+`memory.update` 事件的 `status` 为 `pending`、`success`、`error` 或 `cancelled`；
+JSON 最终结果的 `memory_update` 和历史里的 `session_memory.update` 也保留最近状态。
+失败时 `code` 区分 `MEMORY_REQUEST_FAILED`（请求失败）、`MEMORY_EMPTY_RESPONSE`、
+`MEMORY_INCOMPLETE_RESPONSE`（截断或异常结束）、`MEMORY_INVALID_PATCH`、
+`MEMORY_STALE_HISTORY`（前缀失配）；取消为 `MEMORY_CANCELLED`，恢复上次进程遗留的
+`pending` 状态时记为 `MEMORY_INTERRUPTED`。新更新失败会保留本次运行已有的成功快照。
+没有更新记录表示尚未尝试更新。
+
+单步暂停会等待在途更新完成，再保存历史；主任务完成、失败、取消、返回待输入状态，
+以及外部快照前，会取消未完成的记忆请求并等待退出，再保存最终状态。已成功生成的
+记忆会保留，未完成的输出不会作为有效记忆使用。
+Agent Arena 记忆更新使用主模型、temperature=1、thinking
+开启、thinking budget=81920，输出上限由 `ARENA_COMPACTION_SUMMARY_MAX_TOKENS`
+控制（rolling 默认 131072，summary 默认 8192）。Code Arena 默认上限仍为 8192。
 
 `ARENA_CONTEXT_WINDOW` 应设置为所用模型的真实上下文窗口；默认 `1000000` 是
-当前默认模型的暂定值。token 数目前是本地保守估算，并非 provider tokenizer
-的精确计数。如果摘要请求失败，Harness 会保留原历史并继续正常模型请求，避免
+当前默认模型的暂定值。Agent Arena 的 usage 基线来自 provider；最近 assistant
+之后的新增上下文以及缺少 usage 时的完整上下文仍使用本地保守估算。如果摘要请求失败，Harness 会保留原历史并继续正常模型请求，避免
 摘要服务的瞬时故障直接中断任务。
 
 Responses 与其他协议一样，会在每个工具 step 前检查是否需要压缩。由于所有
 reasoning/function-call 状态都由本地 history 携带，压缩不再需要切断或重建 provider
-端 response 链。压缩会把已完成的旧回合替换成续作摘要，同时保留当前 user turn 里的
+端 response 链。Agent Arena 压缩已归档的前缀，同时保留最新完整步骤里的
 加密 reasoning、function call 和 function output；下一次 Responses 请求直接回放这份
-压缩后的本地上下文。持久化的原始 `history.json` 仍保持 append-only。
+压缩后的本地上下文；完整历史及压缩记录保存在 `history.json.messages`。
 
 每次模型请求都会通过 OpenAI-compatible 的 `stream_options.include_usage`
 请求 token 用量，并把服务端在最终 chunk 上报的 `usage` 对象原样记录到该轮
 assistant 消息的 `usage` 字段（`history.json` 与事件流中均可见），供训练
 和成本统计使用。再次发送历史上下文时，`usage` 会在 wire 边界剥离，不会发回
 服务端。`model.complete` 事件同样携带该轮 `usage`；上下文压缩的摘要调用
-不会在历史中留下消息，其用量通过 `compaction` 事件上报，只在事件流中可
-见。不支持 `stream_options` 的服务可通过 `ARENA_EXTRA_BODY` 覆盖该参数。
+不会在历史中留下普通消息，其用量通过 `compaction` 事件上报。Agent Arena 还通过
+`memory.update` 上报记忆更新用量，并将最近一次更新返回的 usage 保存在
+`session_memory.update.usage` 中。不支持 `stream_options` 的服务可通过
+`ARENA_EXTRA_BODY` 覆盖该参数。
 
 模型请求遇到网络错误、HTTP 408/409/429 或 5xx 时会自动重试，默认最多重试
 10 次。没有 `Retry-After` 时使用带随机抖动的指数退避，单次等待默认最多
@@ -383,6 +543,13 @@ Arena 还维护一份有顺序的模型输入模态表，在第一次 HTTP 调
 当主模型被明确判定为不支持图片时，可设置
 `ARENA_IMAGE_INPUT_FALLBACK_MODEL`，让普通 Arena 的图片 `read_file` 先由该模型
 转换为文字；主模型支持图片、模型未知或 Code Arena 模式均不触发此 fallback。
+可进一步用 `ARENA_IMAGE_INPUT_FALLBACK_BASE_URL`、
+`ARENA_IMAGE_INPUT_FALLBACK_API_KEY` 和 `ARENA_IMAGE_INPUT_FALLBACK_PROTOCOL`
+为 fallback 设置完全独立的连接；协议支持 `openai-chat-completions`、
+`openai-responses` 和 `anthropic-messages`。例如 Anthropic 主模型可以把图片交给
+使用 OpenAI 兼容端点的 Gemini。任一独立连接参数出现后，fallback 不再继承主模型
+的 base URL、认证或协议；未填写的连接项改用所选 provider 的标准
+环境变量与默认端点。仅配置 fallback model 时仍保持原有的主连接继承行为。
 fallback 不继承 `ARENA_EXTRA_BODY` 或主模型生成参数；原生 Anthropic Messages
 因协议要求会单独使用 `max_tokens: 16384`。
 同一条件下，用户直接附加的图片不会发送给主模型；已有附件文件列表会保留，并提示
@@ -429,7 +596,8 @@ arena -p 'redraw this photo with the reference face' \
 每个附件会被保存到工作区 `uploads/`（模型内可通过
 `/home/user/uploads/<name>` 访问；重名自动加 `-2`、`-3` 后缀，URL 无扩展名
 时按图片字节特征补全扩展名）。本轮 user message 与 daemon 附件上传共用同
-一构造逻辑，并使用统一的会话部件格式：图片部件
+一构造逻辑。本地图片只列入附件清单，由模型按需调用 `read_file` 查看；
+网络图片使用统一的会话部件格式：图片部件
 `{"image": ...}` 在前，随后是 prompt 文本 `{"text": ...}`，最后追加一条
 `<arena-system-message>`，列出保存到 `/home/user/uploads/` 的文件名。单条
 消息最多 10 个附件，单个附件上限 20 MB、总量上限 50 MB，与 daemon 一致。
@@ -438,12 +606,19 @@ arena -p 'redraw this photo with the reference face' \
 一律使用 `{"image": ...}` / `{"text": ...}` 原生部件并保持字段格式一致；仅在
 向模型发起 chat-completions 请求的边界处转换为
 OpenAI 风格的 `image_url` 部件。`--attach` 传 URL 时 `image` 直接记录该
-URL（模型服务端会自行下载；恢复历史上下文时要求该 URL 仍可访问）；本地文件
-没有可引用的 URL，`image` 存自包含的 base64
-data-URI。
+URL（模型服务端会自行下载；恢复历史上下文时要求该 URL 仍可访问）；若网络图片
+需要缩放或转码，则记录处理后的 Base64 data-URI。本地图片在 attach 时不生成
+`image` 部件；后续 `read_file` 返回图片时仍可使用 Base64 data-URI。
+
+`stream-json` 每行一个 JSON 对象。四种模式的 headless（Agent Arena、React、HTML、Full Stack）
+的 `message` 事件只带新增的 `message`；`start` 和最终 `result` 保留完整 `messages`，
+避免评测端缓存大量重复历史。需要每个 `message` 事件都带完整 `messages` 的旧消费者，
+可设置 `ARENA_STREAM_HISTORY=full` 恢复旧输出，默认值为 `incremental`。
+旧变量 `ARENA_CODE_STREAM_HISTORY` 作为所有模式的兼容别名保留，`ARENA_STREAM_HISTORY` 优先。
+增量模式使用 JSON Unicode 转义，解析后的文字和图片内容保持原样。
+SDK 和 daemon 的事件保持原有格式。
 
-`stream-json` 每行一个 JSON 对象。`start`、`message`、`result` 事件中的
-`messages` 与输入样例保持相同契约：
+事件中的消息与输入样例保持相同契约：
 
 - system/user：`role` + `content`；支持图片输入的模型在读取图片后会持久化
   一条 multimodal user message
@@ -685,9 +860,9 @@ message。未提供位置时，prompt 会明确标记位置不可用，不会使
 接口，并通过 URI 编码的 `x-file-name` header 传递文件名；再把返回的
 `attachment.path` 作为 `{ "type": "file", "path": "uploads/..." }`
 part 放入实时消息。每个文件最大 20 MB，每条消息最多 10 个文件、合计
-50 MB。服务端会把文件写入该 session 的 `/home/user/uploads/` 映射目录，
-图片作为 multimodal content 注入，并在 user message 最后追加
-`arena-system-message` 附件清单。附件引用只能指向本 session 的
+50 MB。服务端会把文件写入该 session 工作区的 `uploads/` 目录，
+并在 user message 最后追加 `arena-system-message` 附件清单。
+上传的图片由模型按需调用 `read_file` 查看。附件引用只能指向本 session 的
 `uploads/`，不能读取其他 workspace 路径或其他 session 的文件。
 
 SSE 支持 `Last-Event-ID` 断线续传，事件环同时受条数和字节预算约束，不缓存完整
@@ -715,7 +890,7 @@ retry 文件会删除。
 看到 WebUI 的 Retry 按钮：
 
 ```bash
-# 初始模型节点失败：失败后 history 只有 system/user；点一次 Retry 后成功
+# 初始模型节点失败：失败后 history 只有 user；点一次 Retry 后成功
 ARENA_MODEL=mock/manual-retry-initial \
 ARENA_MODEL_RETRY_BASE_MS=0 ARENA_MODEL_RETRY_MAX_MS=0 npm run dev
 
@@ -810,8 +985,8 @@ Arena 的 `fetch_page` 和 Code Arena 的 `web_fetch` 默认仍使用本地抓
 
 `generate_image`、`generate_speech` 使用 ModelRouter/Routify，并从工作区
 `.env` 读取同一个 `ROUTIFY_API_KEY`。图片使用 Google 兼容协议调用；可用
-`ROUTIFY_VERTEX_BASE_URL` 覆盖默认根地址。语音使用 ModelRouter 的火山引擎
-`/protocol/volcengine/api/v1/tts` 路由，不需要新增服务密钥。
+`ROUTIFY_VERTEX_BASE_URL` 覆盖默认根地址。语音默认也通过该 Google 协议
+调用 Gemini TTS，不需要新增服务密钥。
 
 `fetch_page` 使用 Defuddle 将 HTML 正文转换为 Markdown，并使用
 `pdf-parse` 提取 PDF 的前 30 页。响应按 Markdown 边界稳定分块，同一轮内
@@ -826,8 +1001,8 @@ XLSX 仍可提取文字和表格内容，旧版 DOC、PPT、XLS 会先通过 Lib
 内容继续发送给模型。所有工具结果另有 1,000,000 字符的最终兜底。当前不做
 OCR，扫描版 PDF 只会返回无可提取文字的提示。
 
-图片和语音的默认 ModelRouter 路由分别为 `gemini-2.5-flash-image` 和
-`doubao-tts`，可用 `ARENA_IMAGE_MODEL`、`ARENA_SPEECH_MODEL` 覆盖。图片生成结果和
+图片和语音的默认 ModelRouter 路由分别为 `gemini-3.1-flash-image` 和
+`gemini-3.1-flash-tts-preview`，可用 `ARENA_IMAGE_MODEL`、`ARENA_SPEECH_MODEL` 覆盖。图片生成结果和
 搜索到的图片会立即下载到工作区；每次图片搜索的结果按生产命名保存为
 `image-search/<query slug>-<序号>.<扩展名>`，并作为可预览文件显示在 Web UI。
 语音生成先由 `add_voice` 生成两个试听候选并让用户选择，选择结果注册为稳定的
@@ -836,9 +1011,12 @@ OCR，扫描版 PDF 只会返回无可提取文字的提示。
 它会按语言和 `voice_identity` 确定性注册一个默认音色，并在结果中以
 `virtual: true` 标记。返回的 `voice_id` 可直接用于后续 `generate_speech`。
 也可用
-`ARENA_SPEECH_VOICE` 强制覆盖底层音色。豆包响应中的 Base64 数据已经是 MP3、RIFF/WAV
-或 Ogg Opus；`.ogg` 与 `.opus` 都保存 Ogg Opus 数据，所有支持的输出均不依赖
-本地 `ffmpeg` 或 `lame`。
+`ARENA_SPEECH_VOICE` 强制覆盖底层音色（例如 `Kore`）。Gemini 返回的 PCM 在内存中
+封装为 WAV；MP3 和 Ogg Opus 使用随包携带的精简静态 ffmpeg 转换。`.ogg` 与
+`.opus` 都保存 Ogg Opus 数据。单文件发行版内嵌压缩转码器，npm 包携带平台资产；
+转换时释放到操作系统私有临时目录并在结束后清理，不搜索系统 ffmpeg、不运行时下载。
+显式设置 `ARENA_SPEECH_MODEL=doubao-tts` 可继续使用原火山引擎路由及豆包音色。
+从源码运行压缩语音前执行 `npm run prepare:audio`；发布打包会自动准备全部资产。
 
 所有路径工具都限制在 `--workspace` 内并检查符号链接逃逸。`bash` 是本机
 子进程，不是操作系统安全沙箱；多租户或不可信模型部署应使用容器或 VM。

package/dist/agent.d.ts

@@ -1,10 +1,13 @@
 import { type ArenaConfig } from "./config.js";
+import { type StoredSessionMemory, type SessionMemoryCache } from "./compaction.js";
 import { EventSink } from "./protocol.js";
 import { type HarnessMode } from "./mode.js";
 import { ToolExecutor } from "./tools.js";
+import { type CheckpointAction, type MidturnCheckpointHook, type MidturnCheckpointHookEvent } from "./midturn-checkpoint-hook.js";
 import type { AgentResult, AskUserHandler, ClientContext, Message, ModelClient, RepoContext, ToolDefinition, UserTurnMessage, WorkspaceContext } from "./types.js";
 interface AgentOptions {
     client?: ModelClient;
+    imageInputFallbackClient?: ModelClient;
     tools?: ToolExecutor;
     askUserHandler?: AskUserHandler;
     sessionId?: string;
@@ -12,7 +15,18 @@ interface AgentOptions {
     signal?: AbortSignal;
     clientContext?: ClientContext;
     workspaceContext?: WorkspaceContext;
-    onCheckpoint?: (messages: readonly Message[], tools: readonly ToolDefinition[]) => Promise<void>;
+    onCheckpoint?: (messages: readonly Message[], tools: readonly ToolDefinition[], sessionMemory?: StoredSessionMemory | null) => Promise<void>;
+    /** Inspect output repetition and complete tool-call batches before recording them. */
+    midturnCheckpointHook?: MidturnCheckpointHook;
+    /** Materialize the current history and create the external snapshot. */
+    onMidturnCheckpoint?: (messages: readonly Message[], tools: readonly ToolDefinition[], event: MidturnCheckpointHookEvent, action: Exclude<CheckpointAction, "continue">) => Promise<void>;
+    /** Finish durable history before emitting a successful pause result. */
+    onPause?: (messages: readonly Message[], tools: readonly ToolDefinition[]) => Promise<void>;
+    /** Share background updates across invocations. Restoration is a run option. */
+    sessionMemory?: SessionMemoryCache;
+    storedSessionMemory?: StoredSessionMemory;
+    /** Explicit Agent Arena override of the resolved compaction threshold. */
+    compactionThresholdTokens?: number;
     onModelFailure?: (messages: readonly Message[], error: unknown) => void;
     /** Reuse immutable loaded history messages instead of cloning the full prefix. */
     reuseHistoryMessages?: boolean;
@@ -21,12 +35,20 @@ interface AgentRunOptions {
     interrupted?: boolean;
     userMessage?: UserTurnMessage;
     resumeFromHistory?: boolean;
+    singleStep?: boolean;
+    /** Defaults to singleStep. Restores the cache without forcing compaction. */
+    restoreSessionMemory?: boolean;
 }
-export declare function resolveRepoContext(workspace: string, history?: Message[], mode?: HarnessMode): RepoContext | undefined;
+export declare function isContinuableHistory(messages: readonly Message[]): boolean;
+export declare function resolveRepoContext(workspace: string, _history?: Message[], mode?: HarnessMode): RepoContext | undefined;
 export declare class Agent {
     private readonly config;
     private readonly sink;
     private readonly options;
+    private checkpointQueue;
+    private checkpointError?;
+    private persistedMemory?;
+    private readonly memoryCache;
     private readonly client;
     private readonly tools;
     private readonly workspaceContext?;
@@ -34,7 +56,11 @@ export declare class Agent {
     readonly sessionId: string;
     constructor(config: ArenaConfig, sink: EventSink, options?: AgentOptions);
     run(prompt: string, history?: Message[], runOptions?: AgentRunOptions): Promise<AgentResult>;
+    private runTurn;
     private checkpoint;
+    private finish;
+    private makeCheckpoint;
+    private pause;
     private maybeCompact;
     private assistantTurn;
     private retryBackoff;