@qwen-code/arena-agent 0.0.9-image-input-fallback.0 → 0.0.10-dev.0

package/.env.example

@@ -7,6 +7,14 @@ OPENAI_MODEL=openai/qwen-latest-series-invite-beta-v92
 OPENAI_BASE_URL=
 OPENAI_API_KEY=
 
+# Auto mode uses Responses for GPT model names and Chat Completions otherwise.
+# Native Responses preserves opaque OpenAI reasoning across tool steps and
+# separate CLI turns by replaying encrypted output items with store=false.
+# Set chat to force Chat Completions.
+# ARENA_OPENAI_API=auto
+# ARENA_OPENAI_API=responses
+# ARENA_OPENAI_API=chat
+
 # Unified runtime mode. Canonical values are shown; full_stack/fullstack and
 # single_html/single-html remain accepted compatibility aliases.
 ARENA_HARNESS_MODE=arena
@@ -72,6 +80,13 @@ ARENA_HARNESS_MODE=arena
 # false, the optional fallback model converts Arena read_file images to text.
 # ARENA_MODEL_SUPPORTS_IMAGE_INPUT=false
 # ARENA_IMAGE_INPUT_FALLBACK_MODEL=qwen3.7-plus
+# Inline image budget before downscaling: max pixels per edge and max 28x28
+# patches. Images within both limits are sent unchanged; larger ones are
+# downscaled to fit and re-encoded as JPEG. Defaults match the captured
+# baseline; raise both for long screenshots (a 1920x5344 full-page capture
+# needs about 8192 edge and 13179 patches to pass through unchanged).
+# ARENA_IMAGE_MAX_EDGE=1568
+# ARENA_IMAGE_MAX_PATCHES=1568
 
 # Optional headless ask_user delegation. When enabled, `arena -p` sends the
 # current questions plus a serialized ATIF trajectory to this JSON endpoint.
@@ -80,10 +95,13 @@ ARENA_HARNESS_MODE=arena
 # ARENA_ASK_USER_HANDLER_URL=http://127.0.0.1:8080/v1/ask-user
 # ARENA_ASK_USER_TIMEOUT_MS=60000
 
-# Dynamic session metrics. High-confidence Bash cases use deterministic rules;
-# ambiguous Bash attribution/termination plus user praise, complaint, correction,
-# repair-attempt, and repair-verdict classification use this tool-free structured
-# side query. Disable it to retain those cases as unclassified/ambiguous.
+# Dynamic session metrics. Disabled by default: with the switch off the daemon
+# performs no metric analysis, persists no metrics, and emits no
+# data-session-metrics events. Enable it to compute a snapshot after every
+# user-facing turn; high-confidence Bash cases use deterministic rules, while
+# ambiguous Bash attribution/termination plus user praise, complaint,
+# correction, repair-attempt, and repair-verdict classification use this
+# tool-free structured side query.
 # ARENA_METRICS_SIDE_QUERY_ENABLED=true
 # ARENA_METRICS_SIDE_QUERY_MODEL=openai/qwen-latest-series-invite-beta-v92
 # ARENA_METRICS_SIDE_QUERY_MAX_TOKENS=800
@@ -101,23 +119,26 @@ ARENA_HARNESS_MODE=arena
 # defaults to ~/.arena so runs never write into the task workspace.
 # ARENA_HOME=~/.arena
 
-# Brave web and image search through the Routify gateway.
+# Search, page reading, image generation, and speech through ModelRouter/Routify.
 ROUTIFY_API_KEY=
 # ROUTIFY_WEB_SEARCH_URL=https://routify-pub.alibaba-inc.com/protocol/compatible-mode/res/v1/llm/context
 # ROUTIFY_IMAGE_SEARCH_URL=https://routify-pub.alibaba-inc.com/protocol/brave/res/v1/images/search
+# ROUTIFY_VERTEX_BASE_URL=https://routify-pub.alibaba-inc.com/protocol/vertex/v1beta
 # ARENA_WEB_SEARCH_MODEL=brave.llm-context
 # CODE_HARNESS_WEB_SEARCH_MODEL=brave.llm-context
 # Optional fetch_page/web_fetch path: Firecrawl first, then Jina Reader.
 # CODE_HARNESS_ROUTIFY_WEB_FETCH_ENABLED=false
+# ARENA_IMAGE_MODEL=gemini-2.5-flash-image
+# ARENA_IMAGE_SIZE=1024*1024
+# CODE_HARNESS_IMAGE_MODEL=gemini-2.5-flash-image
+# CODE_HARNESS_IMAGE_SIZE=1024*1024
+# ARENA_SPEECH_MODEL=doubao-tts
+# ARENA_SPEECH_VOICE=zh_female_vv_uranus_bigtts
 
-# DashScope image generation and speech generation.
-DASHSCOPE_API_KEY=
-# Optional: a workspace-specific host, with or without /api/v1.
-# DASHSCOPE_API_BASE=https://your-workspace.cn-beijing.maas.aliyuncs.com
-# ARENA_IMAGE_MODEL=qwen-image-2.0-pro
-# ARENA_IMAGE_SIZE=2048*2048
-# ARENA_SPEECH_MODEL=qwen-audio-3.0-tts-flash
-# DASHSCOPE_SPEECH_VOICE=longanhuan_v3.6
+# start_process automatically checks E2B preview hosts when E2B_SANDBOX_ID is
+# present. For another preview proxy, use {port} and optionally {sandboxId}:
+# ARENA_PREVIEW_HOST_TEMPLATE={port}-{sandboxId}.e2b.app
+# ROUTIFY_MEDIA_MAX_RETRIES=5
 
 # Code Arena stock photo/video search used by fetch_media.
 # PEXELS_API_KEY=

package/README.md

@@ -1,13 +1,17 @@
 # Arena CodeAgent Harness
 
-这是一个根据 `message.json` 与 `tools.json` 逆向实现的 TypeScript CodeAgent
-harness。运行时只依赖 Node.js，不再依赖 Python：
+这是一个基于 `message.json` 与 `tools.json` 所定义消息和工具契约的 TypeScript
+CodeAgent harness。运行时只依赖 Node.js，不再依赖 Python：
 
 - `arena -p ...`：headless 单轮入口，支持文本、完整 JSON 和 NDJSON 流。
 - `arena tui`：终端多轮对话，实时输出并自动保存、恢复历史。
 - `arena serve`：HTTP daemon、Web UI 与双通道 SSE 实时接口。
 - Agent loop：流式 assistant → tool call → tool result → assistant。
-- 11 个工具逐字使用 `tools.json` 的 Draft-07 schema。
+- 15 个工具按照 `tools.json` 中的 Draft-07 schema 提供参数校验。
+
+本文提及的第三方产品、模型与服务名称仅用于说明兼容性和配置方式，不表示相关
+权利人对本项目的认可或背书；相关商标归各自权利人所有。使用者应自行确认并遵守
+所接入模型、数据源和在线服务的许可、服务条款及适用法律。
 
 ## 源码与 SDK 安装
 
@@ -86,6 +90,39 @@ code-harness -p '做一个单文件网页' --mode html
 `CODE_HARNESS_MODE`、`ARENA_MODE` 及旧模式别名。详细目录和发包决策见
 [`docs/MODES_AND_RELEASES.md`](docs/MODES_AND_RELEASES.md)。
 
+如需完全替换模型收到的 system prompt，可在任一运行入口传入
+`--system-prompt <text>`：
+
+```bash
+arena -p '分析这个目录' --system-prompt '你是一名精简的代码审查助手。'
+arena tui --system-prompt '始终先给结论，再解释原因。'
+arena serve --system-prompt '只使用中文回复。'
+```
+
+该参数只在运行时覆盖第一条 system message，不会修改 canonical prompt fixture；
+续跑已有 session 时，当前传入的值会替换历史中的 system message。未传参数时，
+日期、workspace 和 mode 对应的现有 prompt 生成逻辑保持不变。
+
+如需保留当前 mode 生成的 system prompt，只在末尾追加任务或部署指令，可传入
+`--append-system-prompt <text>`：
+
+```bash
+arena -p '分析这个目录' --append-system-prompt '回答保持精简。'
+arena tui --append-system-prompt '始终先给结论，再解释原因。'
+arena serve --append-system-prompt '只使用中文回复。'
+```
+
+追加内容会作为独立段落放在运行时 system message 末尾，因此原有日期、workspace、
+工具和 mode 指令保持不变，也不会修改 canonical prompt fixture。同一会话内只会追加
+一次，不会随 turn 重复累积。使用 headless CLI 续跑 session 时，需要再次传入相同的
+追加参数。`--system-prompt` 与 `--append-system-prompt` 可以同时使用，此时先完整
+替换，再追加指定文本。
+
+`arena serve` 是一个例外：未显式传入 `--system-prompt` 时，它会保留现有系统
+提示词中的日期、workspace、工具和 mode 指令，但默认将身份声明设为 `Qwen`。
+显式传入 `--system-prompt` 时仍会完整替换系统提示词；仅传
+`--append-system-prompt` 时，则先应用该 Qwen 身份变换，再追加文本。
+
 Arena 模式下，如需从 system prompt 的身份模型列表中移除 `Qwen`，可增加
 `--exclude-qwen-from-system-prompt`，或设置
 `ARENA_EXCLUDE_QWEN_FROM_SYSTEM_PROMPT=true`。CLI 开关优先于环境变量：
@@ -96,15 +133,18 @@ arena tui --exclude-qwen-from-system-prompt
 arena serve --exclude-qwen-from-system-prompt
 ```
 
-三个 Code Arena 模式的 150 个历史 case、工具 replay 和真实模型行为实验入口见
+三个 Code Arena 模式的兼容性测试集、工具回归测试和模型行为评估入口见
 [`tasks/code-harness/README.md`](tasks/code-harness/README.md)；这些开发数据不会
 进入 npm 或 SEA 发布包。
 
 ## 模型
 
-TypeScript 运行时根据模型前缀选择协议：`openai/` 使用 OpenAI Chat
-Completions，`anthropic/` 使用原生 Messages，`gemini/` 使用 Google 的
-OpenAI-compatible 接口。LiteLLM 官方提供 Python SDK 或独立 Proxy，因此
+TypeScript 运行时根据模型前缀与名称选择协议：`anthropic/` 使用原生
+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 网关：
 
@@ -140,10 +180,19 @@ export OPENAI_API_KEY=...
 ```
 
 `OPENAI_BASE_URL` / `OPENAI_API_KEY` 是统一的模型连接入口，变量名不决定
-wire protocol。`OPENAI_MODEL=anthropic/...` 仍会向 `<base>/messages` 发送
-Anthropic Messages payload 并使用 `x-api-key`；`openai/...` 则会向
-`<base>/chat/completions` 发送 OpenAI payload 并使用 Bearer token。未设置
-统一入口时，Anthropic 可回退到 `ANTHROPIC_BASE_URL` /
+wire protocol。`OPENAI_MODEL=anthropic/...` 会向 `<base>/messages` 发送
+Anthropic Messages payload 并使用 `x-api-key`；OpenAI 路由根据上述规则向
+`<base>/chat/completions` 或 `<base>/responses` 发送 Bearer 请求。Responses
+路径固定使用 `store=false`，不会发送 `previous_response_id` 或 conversation。
+每次响应完成时，Harness 会把 `reasoning`、`function_call` 和 assistant message
+等原生 output items 原样保存在 assistant 历史中；其中 reasoning 的
+`encrypted_content` 是 OpenAI 返回的不可读加密载荷。后续工具 step 和跨 CLI
+回合会把这些 output items 连同 function output 一起完整回放到下一次 `input`，
+从而在不依赖 provider 端存储的情况下保留隐藏 reasoning。请求显式包含
+`reasoning.encrypted_content`；GPT-5.6 还会使用 `reasoning.context=all_turns`。
+设置 `ARENA_OPENAI_API=chat` 或 `responses` 可覆盖 GPT 的自动选择。
+该开关不作用于 LiteLLM、Gemini 或 Anthropic 路由。如未设置统一入口，
+Anthropic 可回退到 `ANTHROPIC_BASE_URL` /
 `ANTHROPIC_API_KEY`。
 
 Anthropic 直连默认只用 `x-api-key` 鉴权（同时携带 Authorization 会让部分
@@ -160,11 +209,11 @@ Anthropic 直连在原生协议上完整支持 thinking。旧版 Claude 和非 C
 budget。Anthropic 要求启用 thinking 时不调整 temperature，此时不发送该
 参数。带签名的 thinking/redacted_thinking block 会原样保存在对应 assistant
 消息的 `reasoning_details` 字段——
-Anthropic 要求 tool-use 续跑时回传签名 thinking block，重放历史时会按
+Anthropic 要求 tool-use 续跑时回传签名 thinking block，恢复历史上下文时会按
 原顺序还原；无签名的 thinking block（部分网关返回 `signature: ""`）
-不参与重放，因为协议不需要它们，而且某些网关收到会挂起。
+不会再次发送，因为协议不需要它们，而且某些网关收到会挂起。
 `reasoning_content` 仍是纯文本推理，历史契约不变。向
-OpenAI-compatible 服务重放同一份历史时，`reasoning_details` 与 `usage`
+OpenAI-compatible 服务发送同一份历史时，`reasoning_details` 与 `usage`
 一样在 wire 边界剥离。usage 会映射为 OpenAI 风格字段（`prompt_tokens`
 含 cache 创建/读取部分），同时保留 `input_tokens`、
 `cache_read_input_tokens` 等原生字段。`OPENAI_BASE_URL` 对 anthropic
@@ -191,8 +240,9 @@ ARENA_COMPACTION_SUMMARY_MAX_TOKENS=8192
 ```
 
 可选的 `ARENA_REASONING_EFFORT` 支持 `low`、`medium`、`high`、`xhigh`
-和 `max` 五档；OpenAI-compatible 请求使用 `reasoning_effort`，原生
-Anthropic Messages 请求映射为 `output_config.effort`。不会按模型静默
+和 `max` 五档；Chat Completions 请求使用 `reasoning_effort`，Responses
+请求使用 `reasoning.effort`，原生 Anthropic Messages 请求映射为
+`output_config.effort`。不会按模型静默
 降档；目标模型或兼容网关不支持所选档位时，由服务端返回明确错误。
 `ARENA_DISALLOWED_TOOLS` 是 JSON 字符串数组，工具名精确匹配：
 
@@ -207,17 +257,17 @@ ARENA_DISALLOWED_TOOLS=["bash","write_file"]
 参数覆盖，也会原样写入 `history.json` 的
 `metadata.parameters.extra_body`。
 
-`ROUTIFY_API_KEY` 供 `web_search` 和 `image_search` 使用；开启
+`ROUTIFY_API_KEY` 供 `web_search`、`image_search`、`generate_image` 和
+`generate_speech` 使用；开启
 `CODE_HARNESS_ROUTIFY_WEB_FETCH_ENABLED` 后，Arena 的 `fetch_page` 和 Code Arena 的
 `web_fetch` 也复用该密钥，通过 Routify 先调用 Firecrawl，失败时回退到
 Jina Reader。
-`DASHSCOPE_API_KEY` 供图片生成和语音工具使用。这些工具密钥都不会
-作为主模型连接的密钥。
+该密钥不会作为主模型连接的密钥。
 
 Harness 会在每次模型调用前估算消息、reasoning、工具 schema 和图片占用；达到
 `ARENA_CONTEXT_WINDOW × ARENA_CONTEXT_COMPACTION_RATIO`（默认 80%）时，调用
 当前模型把已完成的旧回合生成结构化续作摘要。只有发给模型的内存上下文会把
-旧前缀替换为与 Arena trace 一致的 leading `<arena-system-message>`；持久化的
+旧前缀替换为符合既有会话格式的 leading `<arena-system-message>`；持久化的
 `history.json.messages` 保留原始消息，不会因压缩删除或替换前缀。当前用户回合及
 其后的 tool-call / result 链在模型上下文中保持原样。摘要重点保留目标、硬约束、
 发现、已完成/未完成事项、下一步和相关文件路径；摘要调用默认关闭 thinking，
@@ -225,14 +275,20 @@ Harness 会在每次模型调用前估算消息、reasoning、工具 schema 和
 `ARENA_COMPACTION_SUMMARY_MAX_TOKENS` 控制（默认 8192）。
 
 `ARENA_CONTEXT_WINDOW` 应设置为所用模型的真实上下文窗口；默认 `1000000` 是
-当前 trace 模型的暂定值。token 数目前是本地保守估算，并非 provider tokenizer
+当前默认模型的暂定值。token 数目前是本地保守估算，并非 provider tokenizer
 的精确计数。如果摘要请求失败，Harness 会保留原历史并继续正常模型请求，避免
 摘要服务的瞬时故障直接中断任务。
 
+Responses 与其他协议一样，会在每个工具 step 前检查是否需要压缩。由于所有
+reasoning/function-call 状态都由本地 history 携带，压缩不再需要切断或重建 provider
+端 response 链。压缩会把已完成的旧回合替换成续作摘要，同时保留当前 user turn 里的
+加密 reasoning、function call 和 function output；下一次 Responses 请求直接回放这份
+压缩后的本地上下文。持久化的原始 `history.json` 仍保持 append-only。
+
 每次模型请求都会通过 OpenAI-compatible 的 `stream_options.include_usage`
 请求 token 用量，并把服务端在最终 chunk 上报的 `usage` 对象原样记录到该轮
 assistant 消息的 `usage` 字段（`history.json` 与事件流中均可见），供训练
-和成本统计使用。向模型重放历史时，`usage` 会在 wire 边界剥离，不会发回
+和成本统计使用。再次发送历史上下文时，`usage` 会在 wire 边界剥离，不会发回
 服务端。`model.complete` 事件同样携带该轮 `usage`；上下文压缩的摘要调用
 不会在历史中留下消息，其用量通过 `compaction` 事件上报，只在事件流中可
 见。不支持 `stream_options` 的服务可通过 `ARENA_EXTRA_BODY` 覆盖该参数。
@@ -250,6 +306,14 @@ assistant 消息的 `usage` 字段（`history.json` 与事件流中均可见）
 `model.retry` 事件（TUI 会显示「reconnecting after a network error」提示）。
 用户主动取消（abort）不会被当作可重试的网络故障。
 
+OpenAI Responses 还会检查 HTTP 200 SSE 中的 `error` / `response.failed`
+事件。带 408/409/429/5xx 或明确瞬时错误类型的事件会整轮重试；上游只给文本时，
+仅明确的 `experiencing high demand`、`maximum usage size allowed during peak
+load`、`Provisioned Throughput` 容量错误会重试。容量错误最多重试 5 次
+（`ARENA_MODEL_MAX_RETRIES` 可进一步降低或关闭），每次均重新发送完全相同的
+模型输入，并沿用 full-jitter 指数退避。上下文超限、参数、鉴权、媒体和安全错误
+等永久错误不会因正文中出现 `error` 一词而重试。
+
 Agent turn 默认没有模型 step 数上限；设置 `ARENA_MAX_TURNS` 后，达到指定上限
 会返回 error，已经完成的 assistant/tool step 仍会保留。整轮没有内建墙钟时长
 上限，会持续到模型正常结束、请求用户输入、发生不可恢复错误、达到显式配置的
@@ -319,12 +383,17 @@ Arena 还维护一份有顺序的模型输入模态表，在第一次 HTTP 调
 转换为文字；主模型支持图片、模型未知或 Code Arena 模式均不触发此 fallback。
 fallback 不继承 `ARENA_EXTRA_BODY` 或主模型生成参数；原生 Anthropic Messages
 因协议要求会单独使用 `max_tokens: 16384`。
+同一条件下，用户直接附加的图片不会发送给主模型；已有附件文件列表会保留，并提示
+模型调用 `read_file` 获取 fallback 生成的文字版本。
 
 输出事件及 JSON 结果中的 `session_id` 就是路径里的 `<sessionId>`。
 `history.json` 的 `messages` 是只追加的原始轨迹；上下文压缩只影响发送给模型的
 临时副本。`metadata` 记录 session、模型以及本次实际生效的 `max_turns`、
-`context_window`、生成和压缩参数。daemon 完成一次 turn 后还会写入
-`version: 3` 和 `metrics`，后者是截至该 turn 的 praise vs. complaint、
+`context_window`、生成和压缩参数。`tools` 记录最近一次保存时实际提供给模型的
+完整工具定义，包括针对 workspace 的描述改写和不可用工具（未接 `ask_user`
+handler、`ARENA_DISALLOWED_TOOLS`）的过滤结果。daemon 完成一次 turn 后还会写入
+`version: 4`；开启动态指标统计（`ARENA_METRICS_SIDE_QUERY_ENABLED`，默认关闭）
+时还会写入 `metrics`，后者是截至该 turn 的 praise vs. complaint、
 steerability、Bash recovery 与 tool hallucination 增量快照。即使结果为
 `needs_input` 或 `error` 也会保存；旧的 `{"messages":[...]}` 历史仍可直接加载。
 需要跨命令续写同一份显式历史时，可另外传入
@@ -358,17 +427,17 @@ arena -p 'redraw this photo with the reference face' \
 每个附件会被保存到工作区 `uploads/`（模型内可通过
 `/home/user/uploads/<name>` 访问；重名自动加 `-2`、`-3` 后缀，URL 无扩展名
 时按图片字节特征补全扩展名）。本轮 user message 与 daemon 附件上传共用同
-一构造逻辑，并使用与 Arena trace 相同的原生部件格式：图片部件
+一构造逻辑，并使用统一的会话部件格式：图片部件
 `{"image": ...}` 在前，随后是 prompt 文本 `{"text": ...}`，最后追加一条
 `<arena-system-message>`，列出保存到 `/home/user/uploads/` 的文件名。单条
 消息最多 10 个附件，单个附件上限 20 MB、总量上限 50 MB，与 daemon 一致。
 
 多模态 user 消息（附件、图片 `read_file` 回灌、中断通知）在历史与事件流中
-一律使用 Arena 原生部件 `{"image": ...}` / `{"text": ...}`，与 baseline
-trace 逐字段同构；仅在向模型发起 chat-completions 请求的边界处转换为
+一律使用 `{"image": ...}` / `{"text": ...}` 原生部件并保持字段格式一致；仅在
+向模型发起 chat-completions 请求的边界处转换为
 OpenAI 风格的 `image_url` 部件。`--attach` 传 URL 时 `image` 直接记录该
-URL（与 baseline 引用附件的方式一致，模型服务端会自行下载；重放历史要求
-该 URL 仍可访问）；本地文件没有可引用的 URL，`image` 存自包含的 base64
+URL（模型服务端会自行下载；恢复历史上下文时要求该 URL 仍可访问）；本地文件
+没有可引用的 URL，`image` 存自包含的 base64
 data-URI。
 
 `stream-json` 每行一个 JSON 对象。`start`、`message`、`result` 事件中的
@@ -382,7 +451,12 @@ data-URI。
 
 `assistant.delta` 实时提供 content、reasoning 与 tool-call 参数碎片；
 `model.start`、`model.complete`、`model.retry`、`tool.start`、`tool.complete`
-标记阶段。最后的 `result` 带完整可重放消息。
+标记阶段。最后的 `result` 带完整消息。
+
+Headless 会向模型提供 `present_file`，以保持生成轨迹与 Arena 工具契约一致。
+该工具在 headless 中只校验目标是 workspace 内已有文件，并返回
+`{"path":"<原始路径>","status":"success"}`；不会连接前端或打开 viewer。
+自动打开 viewer 仅由 daemon/WebUI 消费同一工具结果后触发。
 
 `ask_user` 只有在注入 handler 时才会提供给模型。TUI 和 WebUI 使用真人交互
 handler；headless（`-p`）默认仍不开放该工具，但可配置远程 User Agent handler：
@@ -426,8 +500,9 @@ arena tui --workspace . --model mock/ask-user --session-id my-session
 workspace 默认是启动命令时的当前目录（可用 `--workspace` 覆盖）。TUI 会把
 实际 workspace root 和 cwd 动态注入 system prompt 与工具 schema；因此本机
 运行时使用本机路径，部署进沙箱后会自然使用沙箱内的实际路径，不需要切换模式。
-TUI 没有内置文件 viewer，因此不会向模型提供 `present_file`；模型会直接报告
-生成文件的实际路径。
+TUI 会向模型提供 `present_file`，以保持生成轨迹与 Arena 工具契约一致。由于
+TUI 没有内置文件 viewer，该工具只校验 workspace 内的目标文件并返回 canonical
+成功结果，不会打开文件；模型仍会在正文中报告生成文件的实际路径。
 
 assistant 的 reasoning、正文和工具调用状态会边生成边输出。每轮结束都会把
 完整消息原子写入与 headless、daemon 相同的 `history.json`；再次传入相同的
@@ -673,7 +748,7 @@ curl -N -X POST \
 
 ## 工具
 
-原始规范在源码仓库中逐字保存在：
+消息与工具契约配置保存在：
 
 - `spec/message.json`
 - `spec/tools.json`
@@ -682,40 +757,56 @@ curl -N -X POST \
 `spec/` 目录，运行时也不依赖仓库文件。执行工具前仍使用 AJV 校验原始
 Draft-07 schema。repo mode 的动态提示词模板保存在 `src/prompts.ts`：
 
-`bash`、`ask_user`、`edit_file`、`read_file`、`fetch_page`、`web_search`、
-`write_file`、`image_search`、`present_file`、`generate_image`、
-`generate_speech`。
+`bash`、`ask_user`、`add_voice`、`edit_file`、`read_file`、`fetch_page`、
+`web_search`、`write_file`、`image_search`、`present_file`、`stop_process`、
+`start_process`、`generate_image`、`generate_speech`、`get_process_output`。
+
+新版生产导出的前 50 条脱敏请求单独保存在
+[`tasks/v2`](tasks/v2/README.md)，没有与原有 replay 数据混放。该目录记录了
+2 GB 源文件的 SHA-256、全量解析统计、tool schema 变体和可重复执行的拆分命令；
+`npm run refresh:arena-v2-contract` 用它刷新 canonical prompt/tool fixtures 并重新
+生成 `src/canonical-data.ts`。
+
+`bash` 只用于一次性命令：超时结果为 `status=timeout`，被信号终止为
+`status=killed`，并会清理命令遗留的后台进程。需要跨 tool call 存活的 server、
+watcher 或任务应使用 `start_process`；随后可用 `get_process_output` 按日志、端口
+或退出状态阻塞等待，并用 `stop_process` 停止整个进程组。完整合并日志保存在
+工作区的 `.arena/processes/`，工具返回对应的 `log_tail`；`stop_process` 对齐生产
+只返回最后 100 行。assistant tool call 和这些 JSON tool result 会原样写入
+`history.json`，供后续 turn replay。`start_process` 在 E2B 环境中还会用
+`E2B_SANDBOX_ID` 组成 `{port}-{sandboxId}.e2b.app`，分别探测本地 Host 和用户
+预览 Host；如果新开的公网端口仅拒绝后者，结果会按需增加 `warnings`。其他预览
+代理可用 `ARENA_PREVIEW_HOST_TEMPLATE` 配置 Host 模板。没有告警时不返回该字段，
+保持普通捕获的结果 shape 不变。
 
 `web_search` 使用 Routify 网关提供的 Brave LLM Context，从工作区 `.env`
-读取 `ROUTIFY_API_KEY`，默认调用
-`https://routify-pub.alibaba-inc.com/protocol/compatible-mode/res/v1/llm/context`
-并使用 `brave.llm-context` 路由。实现按 depth 请求最多 3/5/8 条结果，并将
+读取 `ROUTIFY_API_KEY`，默认通过内置的 ModelRouter 兼容接口调用
+`brave.llm-context` 路由。实现按 depth 请求最多 3/5/8 条结果，并将
 `grounding.generic` 的内容片段及 `sources` 的来源信息转换成 Arena 的既有工具
 结果。请求固定考虑最多 20 个搜索候选，再通过 `maximum_number_of_urls` 将
 最终来源数限制为 3/5/8。depth 还分别对应 1024/3072/8192 的总 token 预算和
 512/552/2048 的单 URL token 预算；description 使用预算内的全部 grounding
 snippets，仅在没有 grounding 内容时回退到来源摘要。三个 Code Arena 模式
-使用独立的复刻参数：来源数 3/5/10、总 token 预算 1280/4096/6144、单 URL
+使用独立的模式参数：来源数 3/5/10、总 token 预算 1280/4096/6144、单 URL
 token 预算 512/1280/1536。
 可用 `ROUTIFY_WEB_SEARCH_URL` 和 `ARENA_WEB_SEARCH_MODEL` 覆盖默认值。
 
 `image_search` 使用 Routify 网关提供的 Brave Images Search，同样读取
-`ROUTIFY_API_KEY`，通过 `X-Subscription-Token` 发送 GET 请求。默认接口为
-`https://routify-pub.alibaba-inc.com/protocol/brave/res/v1/images/search`，可用
-`ROUTIFY_IMAGE_SEARCH_URL` 覆盖。实现优先下载 Brave 返回的原图地址，原图不可用
+`ROUTIFY_API_KEY`，通过 `X-Subscription-Token` 发送 GET 请求。默认使用内置的
+ModelRouter 兼容接口，可用 `ROUTIFY_IMAGE_SEARCH_URL` 覆盖。实现优先下载 Brave
+返回的原图地址，原图不可用
 时回退到 Brave 代理缩略图，并保持既有工具结果格式和工作区文件命名不变。
 
 Arena 的 `fetch_page` 和 Code Arena 的 `web_fetch` 默认仍使用本地抓取与正文
-解析。设置 `CODE_HARNESS_ROUTIFY_WEB_FETCH_ENABLED=true` 后，两者改走 Routify 的
-`POST /protocol/search/tools`：先使用 `readpage-firecrawl-inner`，调用失败、HTTP
-非 200 或响应不可用时回退到 `readpage-jina-inner`；两者都失败则返回普通工具
+解析。设置 `CODE_HARNESS_ROUTIFY_WEB_FETCH_ENABLED=true` 后，两者改走 Routify
+页面读取接口，并在首选读取服务不可用时使用备用服务；两者都失败则返回普通工具
 错误。`fetch_page` 仍按 8000 字符分块并缓存同一 URL 的后续 chunk。认证复用
 `ROUTIFY_API_KEY`。
 
-`generate_image`、`generate_speech` 继续使用阿里云百炼 DashScope，并从工作区
-`.env` 读取 `DASHSCOPE_API_KEY`。默认调用公共北京地域
-地址；若使用业务空间专属域名或新加坡地域，可设置 `DASHSCOPE_API_BASE`
-（可带或不带 `/api/v1`）。
+`generate_image`、`generate_speech` 使用 ModelRouter/Routify，并从工作区
+`.env` 读取同一个 `ROUTIFY_API_KEY`。图片使用 Google 兼容协议调用；可用
+`ROUTIFY_VERTEX_BASE_URL` 覆盖默认根地址。语音使用 ModelRouter 的火山引擎
+`/protocol/volcengine/api/v1/tts` 路由，不需要新增服务密钥。
 
 `fetch_page` 使用 Defuddle 将 HTML 正文转换为 Markdown，并使用
 `pdf-parse` 提取 PDF 的前 30 页。响应按 Markdown 边界稳定分块，同一轮内
@@ -730,10 +821,19 @@ Arena 的 `fetch_page` 和 Code Arena 的 `web_fetch` 默认仍使用本地抓
 内容继续发送给模型。所有工具结果另有 1,000,000 字符的最终兜底。当前不做
 OCR，扫描版 PDF 只会返回无可提取文字的提示。
 
-可用 `ARENA_IMAGE_MODEL`、`ARENA_SPEECH_MODEL` 覆盖 DashScope 默认模型。图片生成结果和
+图片和语音的默认 ModelRouter 路由分别为 `gemini-2.5-flash-image` 和
+`doubao-tts`，可用 `ARENA_IMAGE_MODEL`、`ARENA_SPEECH_MODEL` 覆盖。图片生成结果和
 搜索到的图片会立即下载到工作区；每次图片搜索的结果按生产命名保存为
 `image-search/<query slug>-<序号>.<扩展名>`，并作为可预览文件显示在 Web UI。
-语音生成目前按 DashScope HTTP API 支持 `.mp3`、`.wav` 和 `.opus` 输出。
+语音生成先由 `add_voice` 生成两个试听候选并让用户选择，选择结果注册为稳定的
+`voice_id`；后续 `generate_speech` 必须传入该 id。
+无交互 handler 的 headless 模式仍会开放 `add_voice`，但不会生成无法播放的试听；
+它会按语言和 `voice_identity` 确定性注册一个默认音色，并在结果中以
+`virtual: true` 标记。返回的 `voice_id` 可直接用于后续 `generate_speech`。
+也可用
+`ARENA_SPEECH_VOICE` 强制覆盖底层音色。豆包响应中的 Base64 数据已经是 MP3、RIFF/WAV
+或 Ogg Opus；`.ogg` 与 `.opus` 都保存 Ogg Opus 数据，所有支持的输出均不依赖
+本地 `ffmpeg` 或 `lame`。
 
 所有路径工具都限制在 `--workspace` 内并检查符号链接逃逸。`bash` 是本机
 子进程，不是操作系统安全沙箱；多租户或不可信模型部署应使用容器或 VM。
@@ -749,4 +849,7 @@ npm test
 ```
 
 测试覆盖消息契约、工具校验、headless、`/query`、实时双通道、
-`ask_user`、`present_file` 和 daemon 优雅退出。
+`ask_user`、`add_voice`、后台进程工具、`present_file` 和 daemon 优雅退出。
+配置 `.env` 中的 `ROUTIFY_API_KEY` 后，可运行
+`npm run verify:live-speech-voices` 对 headless `add_voice` 到真实
+`generate_speech` 的多音色链路做烟测。

package/dist/agent.d.ts

@@ -2,16 +2,17 @@ import { type ArenaConfig } from "./config.js";
 import { EventSink } from "./protocol.js";
 import { type HarnessMode } from "./mode.js";
 import { ToolExecutor } from "./tools.js";
-import type { AgentResult, AskUserHandler, ClientContext, Message, ModelClient, RepoContext, UserTurnMessage, WorkspaceContext } from "./types.js";
+import type { AgentResult, AskUserHandler, ClientContext, Message, ModelClient, RepoContext, ToolDefinition, UserTurnMessage, WorkspaceContext } from "./types.js";
 interface AgentOptions {
     client?: ModelClient;
     tools?: ToolExecutor;
     askUserHandler?: AskUserHandler;
     sessionId?: string;
+    sessionAffinityId?: string;
     signal?: AbortSignal;
     clientContext?: ClientContext;
     workspaceContext?: WorkspaceContext;
-    onCheckpoint?: (messages: readonly Message[]) => Promise<void>;
+    onCheckpoint?: (messages: readonly Message[], tools: readonly ToolDefinition[]) => Promise<void>;
     onModelFailure?: (messages: readonly Message[], error: unknown) => void;
 }
 interface AgentRunOptions {
@@ -27,6 +28,7 @@ export declare class Agent {
     private readonly client;
     private readonly tools;
     private readonly workspaceContext?;
+    private readonly sessionAffinityId;
     readonly sessionId: string;
     constructor(config: ArenaConfig, sink: EventSink, options?: AgentOptions);
     run(prompt: string, history?: Message[], runOptions?: AgentRunOptions): Promise<AgentResult>;