@qwen-code/arena-agent 0.0.10-dev.15 → 0.0.10-dev.17

package/.env.example

@@ -57,7 +57,8 @@ ARENA_HARNESS_MODE=arena
 # HARBOR_REMOTE_COMMAND_API_KEY=
 
 # Trace-compatible model settings.
-# ARENA_MAX_TURNS=500
+# Agent Arena defaults to 250 model steps per turn; send a follow-up to continue.
+# ARENA_MAX_TURNS=250
 # Code Arena compatibility alias used only when ARENA_MAX_TURNS is unset:
 # CODE_HARNESS_MAX_STEPS=50
 # ARENA_MAX_TOKENS=131072
@@ -68,11 +69,18 @@ ARENA_HARNESS_MODE=arena
 # ARENA_TOOL_CHOICE=auto
 # JSON array of exact tool names hidden from the model and rejected if called.
 # ARENA_DISALLOWED_TOOLS=["bash","write_file"]
-# Agent Arena connectors through Merge MCP (unset, blank or [] disables it).
+# Agent Arena connectors through Merge MCP; opt-in, ignored by Code Arena.
 # Enable the captured catalog in the Tool Pack; connect apps for the Registered
 # User through Merge Link. The key and user must belong to the same environment.
 # One configured Registered User is shared by all sessions of this process.
-# ARENA_CONNECTORS=["notion","google_calendar"]
+# Slugs: notion, google_calendar, google_drive, google_docs, google_sheets,
+# google_slides, gmail, dropbox, supabase, vercel, linear.
+# ARENA_CONNECTORS=["notion","google_drive","google_docs","google_sheets"]
+# Optional host-provided authenticated-app snapshot, separate from conversation
+# enablement. This does not authorize apps or query Merge. Explicit [] enables
+# discovery with the captured no-connected-apps prompt. Omit both arrays to keep
+# the connector-off baseline.
+# ARENA_CONNECTED_CONNECTORS=["notion","google_drive","google_docs","google_sheets","gmail"]
 # ARENA_MERGE_ACCESS_KEY=
 # ARENA_MERGE_TOOL_PACK_ID=
 # ARENA_MERGE_REGISTERED_USER_ID=
@@ -88,12 +96,12 @@ ARENA_HARNESS_MODE=arena
 # Agent Arena compaction: rolling (default) or summary (historical full summary).
 # Code Arena always uses summary and ignores this setting.
 # ARENA_COMPACTION_MODE=rolling
-# Agent Arena: threshold is 250000 unless BOTH variables below have valid
-# values, in which case threshold = context window * ratio.
+# Agent Arena: threshold = min(250000, context window * ratio), default ratio 0.8.
+# Each setting can be configured independently; invalid values use its default.
 # Code Arena keeps independent controls (default window 1000000, ratio 0.7).
 # Compaction counts use completed-request usage plus newer messages.
 # ARENA_CONTEXT_WINDOW=1000000
-# ARENA_CONTEXT_COMPACTION_RATIO=0.25
+# ARENA_CONTEXT_COMPACTION_RATIO=0.8
 # Restore Agent Arena background memory by default; set false to disable.
 # CLI overrides: --restore-session-memory / --no-restore-session-memory.
 # ARENA_RESTORE_SESSION_MEMORY=true
@@ -161,6 +169,12 @@ ARENA_HARNESS_MODE=arena
 
 # Search, page reading, image generation, and speech through ModelRouter/Routify.
 ROUTIFY_API_KEY=
+# Optional per-tool keys override ROUTIFY_API_KEY; unset or blank falls back.
+# ROUTIFY_WEB_SEARCH_API_KEY=
+# ROUTIFY_IMAGE_SEARCH_API_KEY=
+# ROUTIFY_GENERATE_IMAGE_API_KEY=
+# For an image proxy, keep the real MR key in ROUTIFY_API_KEY and set only
+# ROUTIFY_GENERATE_IMAGE_API_KEY to the proxy key, with the base URL below.
 # 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
@@ -172,8 +186,17 @@ ROUTIFY_API_KEY=
 # Code Arena web_fetch content cap (UTF-8 bytes, including truncation notice).
 # Applies to local and Routify readers in all formats; must be a positive integer.
 # CODE_HARNESS_WEB_FETCH_MAX_BYTES=40000
-# ARENA_IMAGE_MODEL=gemini-3.1-flash-image
+# Agent Arena single images randomly use Gemini or gpt-image-2 by default.
+# Set this variable to pin a model (also overrides option one).
+# ARENA_IMAGE_MODEL=gpt-image-2
+# Second model for Agent Arena generate_image with offer_options=true.
+# Defaults to gpt-image-2 (or Gemini when that is the primary).
+# Without a user handler, save option one and continue; otherwise ask the user.
+# ARENA_IMAGE_ALTERNATIVE_MODEL=gpt-image-2
 # ARENA_IMAGE_SIZE=1024*1024
+# Code Arena randomly uses Sunburst or Flare.
+# Set this variable to pin a model; otherwise an explicit ARENA_IMAGE_MODEL
+# also pins Code Arena. Grok and Muse are not enabled.
 # CODE_HARNESS_IMAGE_MODEL=gpt-image-2.5-sunburst
 # CODE_HARNESS_IMAGE_SIZE=1024*1024
 # ARENA_SPEECH_MODEL=gemini-3.1-flash-tts-preview

package/CHANGELOG.md

@@ -12,6 +12,58 @@
 
 ## [Unreleased]
 
+## [0.0.10-dev.17] - 2026-11-09
+
+### Agent Arena
+
+- 压缩阈值对齐为上下文窗口的 80% 与 250,000 tokens 中的较小值，单独设置 `ARENA_CONTEXT_WINDOW` 即可适配小窗口模型；尚无可用记忆时继续运行。
+- 每轮默认最多 250 个模型步骤，`ARENA_MAX_TURNS` 可覆盖；达到上限保存进度，发送消息即可继续。
+- 对齐 `web_search` 各深度的搜索预算，普通附件单文件上限调整为 25 MB，PDF 为 10 MB，每条消息合计仍为 50 MB。
+- 对齐会话记忆更新请求，修复长工具循环中更新被拒绝，并保留恢复记忆和图片上下文。
+
+### 通用
+
+- Responses、Chat Completions 和 Anthropic Messages 的断流、空回复及临时错误按配置重试，不再将不完整回复误报为成功或执行未完成的工具调用。
+- 摘要压缩、图片转文字及指标侧查询拒绝未完成的模型内容，兼容更多网关限流错误，并保留 Chat Completions 的明确拒答。
+
+## [0.0.10-test.0] - 2026-11-09
+
+### Agent Arena
+
+- 压缩阈值对齐为上下文窗口的 80% 与 250,000 tokens 中的较小值，单独设置 `ARENA_CONTEXT_WINDOW` 即可适配小窗口模型。
+- 达到压缩阈值但尚无可用记忆时继续运行，不再强制生成或等待记忆。
+- 每轮默认最多 250 个模型步骤，`ARENA_MAX_TURNS` 可覆盖；达到上限保存进度，发送消息即可继续。
+- `web_search` 各深度的候选数量、正文和片段预算对齐官方文档。
+- 普通附件单文件上限调整为 25 MB，PDF 为 10 MB，每条消息合计仍为 50 MB。
+- 按官方请求补齐会话记忆更新前缀及用户消息合并，修复长工具循环中更新被拒绝，并保留恢复记忆和图片上下文。
+
+### 通用
+
+- Responses、Chat Completions 和 Anthropic Messages 的断流、空回复及临时错误按配置重试，不再将不完整回复误报为成功或执行未完成的工具调用。
+- 摘要压缩、图片转文字及指标侧查询不再接受模型明确标记为未完成的内容。
+- 兼容更多网关限流错误并避免重试明确的鉴权失败，保留 Chat Completions 的明确拒答，拦截 Responses 中前后冲突的工具调用。
+
+## [0.0.10-dev.16] - 2026-11-04
+
+### Agent Arena
+
+- Repo 会话记住目标仓库，新增同级仓库后仍可继续和恢复；目标缺失或 Git 状态异常时明确报错。
+- 对齐近期日志中的工作区、Repo 和记忆提示词，以及已有工具的声明顺序。
+- `read_file` 支持 `offset`、`limit` 分页；`bash` 超时返回已有输出并允许命令继续运行，主动取消仍终止进程树。
+- 对齐工具参数的默认值、实时与恢复历史格式，以及同批工具并发执行和结果顺序。
+- 扩展 MCP 应用至 Google Drive、Docs、Sheets、Slides、Gmail、Dropbox、Supabase、Vercel 和 Linear，并对齐 Notion 工具、工作区文件传输及重复调用保护。
+- 新增 `ARENA_CONNECTED_CONNECTORS`，区分已连接但未开启和未连接的应用。
+- `generate_image` 单图默认随机使用 GPT Image 2 或 Gemini 3.1 Flash，`offer_options` 并行生成双图供选择，保存未选图片并支持中断后重试；第二模型可用 `ARENA_IMAGE_ALTERNATIVE_MODEL` 配置。
+- Headless 未配置用户 handler 时，`generate_image` 的 `offer_options=true` 默认保存第一张候选图并继续执行。
+
+### Code Arena
+
+- `generate_image` 默认随机使用 `gpt-image-2.5-sunburst` 或 `gpt-image-2.5-flare`。
+
+### 通用
+
+- 新增 `ROUTIFY_WEB_SEARCH_API_KEY`、`ROUTIFY_IMAGE_SEARCH_API_KEY`、`ROUTIFY_GENERATE_IMAGE_API_KEY`，支持搜索与生图独立密钥，未设置或留空时继续使用 `ROUTIFY_API_KEY`。
+
 ## [0.0.10-dev.15] - 2026-10-28
 
 ### Agent Arena
@@ -279,7 +331,10 @@
 - `bash` 用于一次性命令，区分超时与信号终止，并清理遗留后台进程；需要持续运行
   的任务改用进程工具。预览端口支持 E2B Host 探测及按需返回告警。
 
-[Unreleased]: https://code.alibaba-inc.com/know-how/arena-harness/compare?from=v0.0.10-dev.15&to=master&mergeBase=true
+[Unreleased]: https://code.alibaba-inc.com/know-how/arena-harness/compare?from=v0.0.10-dev.17&to=master&mergeBase=true
+[0.0.10-dev.17]: https://code.alibaba-inc.com/know-how/arena-harness/compare?from=v0.0.10-test.0&to=v0.0.10-dev.17&mergeBase=true
+[0.0.10-test.0]: https://code.alibaba-inc.com/know-how/arena-harness/compare?from=v0.0.10-dev.16&to=v0.0.10-test.0&mergeBase=true
+[0.0.10-dev.16]: https://code.alibaba-inc.com/know-how/arena-harness/compare?from=v0.0.10-dev.15&to=v0.0.10-dev.16&mergeBase=true
 [0.0.10-dev.15]: https://code.alibaba-inc.com/know-how/arena-harness/compare?from=v0.0.10-dev.14&to=v0.0.10-dev.15&mergeBase=true
 [0.0.10-dev.14]: https://code.alibaba-inc.com/know-how/arena-harness/compare?from=v0.0.10-dev.13&to=v0.0.10-dev.14&mergeBase=true
 [0.0.10-dev.13]: https://code.alibaba-inc.com/know-how/arena-harness/compare?from=v0.0.10-dev.12&to=v0.0.10-dev.13&mergeBase=true

package/README.md

@@ -263,8 +263,11 @@ arena serve --system-prompt '只使用中文回复。'
 history.json、增量日志和返回的 messages 只保存对话历史（含 compaction），不保存运行时生成的开头 system；中途出现的 system 消息会保留。
 新会话和续跑均在构建模型请求时前置运行时 system；官方以 user 开头的历史可直接续跑。
 旧版带开头 system 的本地历史仍可读取，该旧前缀不作为本次指令，后续写入会移除它。
-每次运行（包括 resume）都会重新探测当前工作区和 Git 状态来填充仓库提示词，
-不从旧 system 或会话 metadata 恢复仓库信息；因此不同轮次的 system 可以变化。
+Agent Arena 在尚未选定仓库时，沿用“工作区根不是 Git 仓库，且仅有一个直接子仓库”的自动识别规则。
+成功识别后，会话记住该子仓库的相对路径；新消息、`--continue`、TUI 和服务端恢复均沿用该目标，
+新增同级仓库不会使会话退出 Repo 模式。普通会话后续出现首个可识别仓库时仍可自动进入 Repo 模式。
+每次运行仍从当前 Git 状态刷新分支（包括 `arena/...`）、远端和基准提交，不复用旧 system 中的信息。
+已绑定仓库缺失或 Git 状态无法解析时明确报错，不会静默换仓库或模式。旧历史没有绑定信息时仍按原规则识别。
 
 如需保留当前 mode 生成的 system prompt，只在末尾追加任务或部署指令，可传入
 `--append-system-prompt <text>`：
@@ -389,7 +392,7 @@ OpenAI-compatible 服务发送同一份历史时，`reasoning_details` 与 `usag
 OPENAI_MODEL=qwen3.7-max
 OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
 OPENAI_API_KEY=sk-...
-ARENA_MAX_TURNS=500
+ARENA_MAX_TURNS=250
 ARENA_MAX_TOKENS=131072
 ARENA_TEMPERATURE=1
 ARENA_TOOL_CHOICE=auto
@@ -397,7 +400,7 @@ ARENA_ENABLE_THINKING=true
 ARENA_THINKING_BUDGET=81920
 ARENA_PRESERVE_THINKING=true
 ARENA_CONTEXT_WINDOW=1000000
-ARENA_CONTEXT_COMPACTION_RATIO=0.25
+ARENA_CONTEXT_COMPACTION_RATIO=0.8
 ARENA_COMPACTION_SUMMARY_MAX_TOKENS=131072
 ```
 
@@ -416,29 +419,49 @@ ARENA_DISALLOWED_TOOLS=["bash","write_file"]
 被禁用的工具不会发送给模型；即使模型仍构造了该工具调用，执行层也会
 在产生副作用前拒绝。
 
-Agent Arena 可通过 Merge MCP 调用 Notion 和 Google Calendar，应用范围由
+Agent Arena 可通过 Merge MCP 调用 Notion、Google Calendar、Google Drive、Docs、
+Sheets、Slides、Gmail、Dropbox、Supabase 和 Vercel，应用范围由
 `ARENA_CONNECTORS` JSON 数组控制。先在 Merge 创建 Tool Pack 和 Registered User，
 让该用户通过 Merge Link 连接目标应用，再配置同一环境的 Access Key：
 
 ```sh
 # 写入本地 .env；三个 Merge 值从自己的 Merge 环境取得。
-ARENA_CONNECTORS='["notion","google_calendar"]'
+ARENA_CONNECTORS='["notion","google_drive","google_docs","google_sheets"]'
 ARENA_MERGE_ACCESS_KEY=...
 ARENA_MERGE_TOOL_PACK_ID=...
 ARENA_MERGE_REGISTERED_USER_ID=...
 ```
 
-首次可运行 `arena -p '加载 Google Calendar 工具并读取我的时区，不要修改日历'`。
-Tool Pack 需启用所选应用的完整捕获目录：Notion 22 个、Calendar 42 个，见
+首次可运行 `arena -p '加载 Google Drive 工具并最多列出一个文件，不要创建或修改文件'`。
+Tool Pack 需启用所选应用的完整捕获目录，见
 [目录源文件](spec/connectors/catalog.json)。缺少工具时会明确报错；上游新增的工具不会自动暴露给模型。
 
-未设置、空字符串或 `[]` 时，提示词和工具集合保持原样。非空时在基础工具后注册
+| 应用 slug | 工具数 | 模型参数定义 |
+| --- | ---: | --- |
+| `notion` | 22 | 历史完整捕获 |
+| `google_drive` | 49 | 历史完整捕获 |
+| `google_docs` | 46 | 历史完整捕获 |
+| `google_sheets` | 56 | 历史完整捕获 |
+| `google_slides` | 50 | 历史完整捕获 |
+| `gmail` | 29 | 历史完整捕获 |
+| `dropbox` | 33 | 历史完整捕获 |
+| `supabase` | 42 | 历史完整捕获 |
+| `vercel` | 53 | 历史完整捕获 |
+| `linear` | 41 | 历史完整捕获 |
+| `google_calendar` | 42 | 旧捕获目录与 Merge 实时 schema |
+
+默认不启用应用。非空 `ARENA_CONNECTORS` 在基础工具集合中注册
 `list_connector_tools`，并在普通／Repo 系统提示词末尾加入捕获的 `Connected apps`
-段落，列出数组中的应用。目前只接受 `notion`、`google_calendar`；重复项去重，
+段落，列出数组中的应用。接受上表中的 slug；重复项去重，
 保留输入顺序，未知名称或非法 JSON 会在启动时报错。Code Arena 忽略此配置。
 
-模型调用 `list_connector_tools` 后，harness 才连接 Merge、加载该应用的参数定义，
-并注册业务工具。每条新用户消息都需要重新发现；暂停续跑只恢复目录，不重放已经执行的操作。
+可选 `ARENA_CONNECTED_CONNECTORS` JSON 数组由宿主提供已连接应用的快照，用来区分
+“已连接但未开启”和“未连接”。它不执行 OAuth，也不自动查询账号状态。未设置时按
+`ARENA_CONNECTORS` 提供会话应用；显式 `[]` 可启用“尚无连接应用”的提示和发现入口。
+两项均未设置时，基础提示词和工具集合保持原样。
+
+模型调用 `list_connector_tools` 后，harness 才连接 Merge、校验后端目录并注册业务工具。
+每条新用户消息都需要重新发现；暂停续跑恢复目录及重复调用保护，不重放已执行的操作。
 数组表示本次会话允许哪些应用，加载目录成功也不保证账号具有全部读写权限。
 缺少配置、授权失败或目录不完整时返回明确错误；业务调用按历史日志包装结果。
 `ARENA_DISALLOWED_TOOLS` 禁用发现工具时也会省略应用提示词；显式 `--system-prompt`
@@ -449,18 +472,23 @@ Tool Pack 需启用所选应用的完整捕获目录：Notion 22 个、Calendar
 已经完成写入，需先查询确认。当前一个进程使用一个 Registered User，Web 会话共用该账号；
 尚未提供各 Web 用户独立登录和账号绑定界面。
 
-可选应用提示词的唯一维护源是 `spec/connectors/system-prompt.txt`，由构建脚本嵌入
-生成数据；关闭 connector 时继续使用 `spec/message.json` 的原始提示词。
-工具名称、描述和顺序来自日志；完整参数使用 Merge 实时 schema，发现入口仍是根据
-`service` 参数实现的最小结构。已通过 40 次历史调用的本地回放比对，尚未用真实账号验证。
-配置步骤、已验证范围和剩余差异见 [Connector 接入分析](docs/research/AGENT_ARENA_CONNECTOR_BACKEND.md)。
+Drive、Dropbox 上传及 Gmail 草稿附件使用 `input.file_path` 读取工作区文件；下载／导出
+通过 Merge 文件接口落盘并返回文件路径。单文件上限为 100 MiB。同一回复中已完成或正在
+执行的相同写调用、已失败的相同业务调用会被拦截；上传限流也会阻止该回复继续上传文件。
+
+提示词、发现入口和十家应用的 421 个完整模型工具定义（含 Linear 的 41 个工具）保存在 `spec/connectors/`，
+由构建脚本嵌入；后端要求的 nullable 字段和文件引用只在发送给 Merge 时转换。
+Google Calendar 本批没有完整历史 schema，继续使用实时定义。
+配置步骤及历史与真实后端的验证边界见 [Connector 接入分析](docs/research/AGENT_ARENA_CONNECTOR_BACKEND.md)。
 
 `ARENA_EXTRA_BODY` 会在配置加载时解析为 JSON 对象，既作为最后一层请求
 参数覆盖，也会原样写入 `history.json` 的
 `metadata.parameters.extra_body`。
 
 `ROUTIFY_API_KEY` 供 `web_search`、`image_search`、`generate_image` 和
-`generate_speech` 使用；开启
+`generate_speech` 使用。前三者分别支持 `ROUTIFY_WEB_SEARCH_API_KEY`、
+`ROUTIFY_IMAGE_SEARCH_API_KEY`、`ROUTIFY_GENERATE_IMAGE_API_KEY` 独立覆盖；
+未设置或留空（含纯空白）时回退到 `ROUTIFY_API_KEY`，旧配置无需修改。开启
 `CODE_HARNESS_ROUTIFY_WEB_FETCH_ENABLED` 后，Arena 的 `fetch_page` 和 Code Arena 的
 `web_fetch` 也复用该密钥，通过 Routify 先调用 Firecrawl，失败时回退到
 Jina Reader。
@@ -479,7 +507,7 @@ ARENA_COMPACTION_MODE=summary arena -p "继续任务" --session-id demo
 摘要按 `Goal`、`Instructions`、`Discoveries`、`Accomplished` 等章节生成，使用
 主模型、temperature=0、关闭 thinking，默认输出上限为 8192。
 `ARENA_COMPACTION_SUMMARY_MAX_TOKENS` 可覆盖上限；`rolling` 的默认上限仍为 131072。
-两种模式默认阈值均为 250k；只有窗口和比例两个环境变量都配置有效时才使用乘积。
+两种模式默认阈值均为 `min(250000, 0.8 × context window)`；窗口和比例可独立配置。
 两种模式及 Code Arena 都优先使用最近一次主请求的服务端 usage，仅估算此后新增的内容。
 大段文本取字符估算与带 10% 余量的 `o200k_base` 分词估算的较大值，减少 SVG 等
 密集文本的低估；本地分词不保证与所选模型完全一致。长用户回合没有更早回合可归档，
@@ -509,14 +537,17 @@ total 缺失时尝试 input/output 相加；只有 input 时，连同该 assista
 保留参数、结果正文及图片计数；实际历史与请求中的 ID 和签名保持完整。
 更新完成只刷新缓存，主模型继续使用原上下文。
 
-整体上下文达到压缩阈值时才回注最新记忆。Agent Arena 默认固定为 250,000 tokens；
-只有 `ARENA_CONTEXT_WINDOW` 与 `ARENA_CONTEXT_COMPACTION_RATIO` 两项都配置了
-有效值，才改用两者的乘积。未配置、只配置一项或任一值无效时，阈值仍为 250,000。
+整体上下文达到压缩阈值时才回注最新记忆。Agent Arena 使用
+`min(250000, ARENA_CONTEXT_WINDOW × ARENA_CONTEXT_COMPACTION_RATIO)`，
+默认窗口为 1,000,000、比例为 0.8；两项可独立配置，无效值各自回退默认值。
+例如 200,000 窗口在 160,000 tokens 触发，128,000 窗口在 102,400 tokens 触发；
+大窗口的阈值最高为 250,000。SDK 显式设置 `compactionThresholdTokens` 可覆盖该阈值。
 计数优先采用最近一次主模型请求返回的 `total_tokens`，并只对
 该 assistant 之后追加的 tool 和 user 消息做本地增量估算；缺少 `total_tokens` 时，
 先尝试由 input/output usage 相加得到，若 output usage 也缺失则回退到 input usage
 加 assistant 及后续消息的本地估算。没有可靠 usage 锚点时回退到全量本地估算。
-有正在进行的更新则等待完成，必要时提前发起更新。
+达到阈值时若没有可用记忆，则继续使用原上下文，不因阈值额外发起或等待更新。
+后续检查发现后台记忆已就绪时，再替换已覆盖的历史前缀；生成期间新增的消息保留原样。
 Code Arena 仍使用窗口与比例相乘的阈值，压缩比例默认是 70%。
 每个会话只运行一个更新任务，失败保留原上下文，源内容推进后允许重试。
 Agent Arena 使用捕获的 session-memory 协议：只输出变化章节并合并，保留未输出章节，
@@ -605,9 +636,10 @@ load`、`Provisioned Throughput` 容量错误会重试。容量错误最多重
 模型输入，并沿用 full-jitter 指数退避。上下文超限、参数、鉴权、媒体和安全错误
 等永久错误不会因正文中出现 `error` 一词而重试。
 
-Agent turn 默认没有模型 step 数上限；设置 `ARENA_MAX_TURNS` 后，达到指定上限
-会返回 error，已经完成的 assistant/tool step 仍会保留。整轮没有内建墙钟时长
-上限，会持续到模型正常结束、请求用户输入、发生不可恢复错误、达到显式配置的
+Agent Arena 每轮默认最多 250 个模型 step，`ARENA_MAX_TURNS` 可覆盖上限。
+达到上限返回 `paused` / `step_limit`，保存已完成的 assistant/tool step；用户发送
+下一条消息即可继续，并获得新一轮步数预算。Code Arena 保留各模式原有上限和错误行为。
+整轮没有内建墙钟时长上限，会持续到模型正常结束、请求用户输入、发生不可恢复错误、达到
 step 上限，或用户主动取消。工具自身仍可定义单次调用的超时。headless 与 daemon
 中的每个完整 assistant/tool step 都会同步追加到 `history.json.journal.jsonl`；turn
 正常结束时再原子物化兼容的 `history.json` 并删除 journal。进程被外部终止时，加载器
@@ -731,7 +763,8 @@ arena -p 'redraw this photo with the reference face' \
 网络图片使用统一的会话部件格式：图片部件
 `{"image": ...}` 在前，随后是 prompt 文本 `{"text": ...}`，最后追加一条
 `<arena-system-message>`，列出保存到 `/home/user/uploads/` 的文件名。单条
-消息最多 10 个附件，单个附件上限 20 MB、总量上限 50 MB，与 daemon 一致。
+消息最多 10 个附件；Agent Arena 普通附件上限 25 MB、PDF 上限 10 MB，Code Arena
+单文件上限仍为 20 MB。总量上限为 50 MB，与 daemon 一致（按 1 MB = 1024² bytes 计）。
 
 多模态 user 消息（附件、图片 `read_file` 回灌、中断通知）在历史与事件流中
 一律使用 `{"image": ...}` / `{"text": ...}` 原生部件并保持字段格式一致；仅在
@@ -994,7 +1027,8 @@ message。未提供位置时，prompt 会明确标记位置不可用，不会使
 附件采用两阶段提交。客户端先将每个文件作为原始请求体上传到 `uploads`
 接口，并通过 URI 编码的 `x-file-name` header 传递文件名；再把返回的
 `attachment.path` 作为 `{ "type": "file", "path": "uploads/..." }`
-part 放入实时消息。每个文件最大 20 MB，每条消息最多 10 个文件、合计
+part 放入实时消息。Agent Arena 普通文件最大 25 MB、PDF 最大 10 MB；Code Arena
+每个文件最大 20 MB。每条消息最多 10 个文件、合计
 50 MB。服务端会把文件写入该 session 工作区的 `uploads/` 目录，
 并在 user message 最后追加 `arena-system-message` 附件清单。
 上传的图片由模型按需调用 `read_file` 查看。附件引用只能指向本 session 的
@@ -1100,7 +1134,8 @@ watcher 或任务应使用 `start_process`；随后可用 `get_process_output`
 保持普通捕获的结果 shape 不变。
 
 `web_search` 使用 Routify 网关提供的 Brave LLM Context，从工作区 `.env`
-读取 `ROUTIFY_API_KEY`，默认通过内置的 ModelRouter 兼容接口调用
+优先读取 `ROUTIFY_WEB_SEARCH_API_KEY`，未设置或留空时读取 `ROUTIFY_API_KEY`，
+默认通过内置的 ModelRouter 兼容接口调用
 `brave.llm-context` 路由。实现按 depth 请求最多 3/5/8 条结果，并将
 `grounding.generic` 的内容片段及 `sources` 的来源信息转换成 Arena 的既有工具
 结果。请求固定考虑最多 20 个搜索候选，再通过 `maximum_number_of_urls` 将
@@ -1111,8 +1146,9 @@ snippets，仅在没有 grounding 内容时回退到来源摘要。三个 Code A
 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 请求。默认使用内置的
+`image_search` 使用 Routify 网关提供的 Brave Images Search，优先读取
+`ROUTIFY_IMAGE_SEARCH_API_KEY`，未设置或留空时读取 `ROUTIFY_API_KEY`，
+通过 `X-Subscription-Token` 发送 GET 请求。默认使用内置的
 ModelRouter 兼容接口，可用 `ROUTIFY_IMAGE_SEARCH_URL` 覆盖。实现优先下载 Brave
 返回的原图地址，原图不可用
 时回退到 Brave 代理缩略图，并保持既有工具结果格式和工作区文件命名不变。
@@ -1123,11 +1159,25 @@ Arena 的 `fetch_page` 和 Code Arena 的 `web_fetch` 默认仍使用本地抓
 错误。`fetch_page` 仍按 8000 字符分块并缓存同一 URL 的后续 chunk。认证复用
 `ROUTIFY_API_KEY`。
 
-`generate_image`、`generate_speech` 使用 ModelRouter/Routify，并从工作区
-`.env` 读取同一个 `ROUTIFY_API_KEY`。GPT Image 图片生成与编辑使用 OpenAI 图片
+`generate_image`、`generate_speech` 使用 ModelRouter/Routify。图片生成优先读取
+`ROUTIFY_GENERATE_IMAGE_API_KEY`，未设置或留空时回退到 `ROUTIFY_API_KEY`；
+语音仍使用 `ROUTIFY_API_KEY`。GPT Image 图片生成与编辑使用 OpenAI 图片
 协议，可用 `ROUTIFY_OPENAI_BASE_URL` 覆盖 ModelRouter 根地址。显式选择 Gemini
 图片模型及默认 Gemini TTS 时使用 Google 协议，可用 `ROUTIFY_VERTEX_BASE_URL`
-覆盖对应根地址，不需要新增服务密钥。
+覆盖对应根地址。
+
+例如，搜索直连 MR、GPT Image 生图走 proxy 时，可以在 `.env` 中配置：
+
+```dotenv
+ROUTIFY_API_KEY=your-real-mr-key
+ROUTIFY_GENERATE_IMAGE_API_KEY=your-proxy-key
+ROUTIFY_OPENAI_BASE_URL=https://your-proxy.example/v1
+ARENA_IMAGE_MODEL=gpt-image-2
+```
+
+Gemini 生图使用同一个生图专用 key，但 proxy 地址需配置到
+`ROUTIFY_VERTEX_BASE_URL`（该地址也供 Gemini TTS 使用）。新密钥配置对 Agent Arena
+和提供对应工具的 Code Arena 模式均生效，不改变请求协议、模型默认值或工具契约。
 
 `fetch_page` 使用 Defuddle 将 HTML 正文转换为 Markdown，并使用
 `pdf-parse` 提取 PDF 的前 30 页。响应按 Markdown 边界稳定分块，同一轮内
@@ -1142,10 +1192,20 @@ XLSX 仍可提取文字和表格内容，旧版 DOC、PPT、XLS 会先通过 Lib
 内容继续发送给模型。所有工具结果另有 1,000,000 字符的最终兜底。当前不做
 OCR，扫描版 PDF 只会返回无可提取文字的提示。
 
-Agent Arena 图片和语音的默认 ModelRouter 路由分别为 `gemini-3.1-flash-image` 和
-`gemini-3.1-flash-tts-preview`，可用 `ARENA_IMAGE_MODEL`、`ARENA_SPEECH_MODEL` 覆盖。
-Code Arena 图片默认使用 `gpt-image-2.5-sunburst`；配置时优先使用
-`CODE_HARNESS_IMAGE_MODEL`，其次使用显式设置的 `ARENA_IMAGE_MODEL`。图片生成结果和
+Agent Arena 单图生成默认在 `gemini-3.1-flash-image` 和 `gpt-image-2` 中每次等概率随机选择；
+设置 `ARENA_IMAGE_MODEL` 可固定模型。语音默认使用 `gemini-3.1-flash-tts-preview`，
+可用 `ARENA_SPEECH_MODEL` 覆盖。
+`generate_image` 的 `offer_options=true` 默认并行调用 Gemini 和 GPT Image 2 生成候选图，等用户选择后
+把选中的图保存到 `file_path`，另一张保存到工作区根目录的 `Unselected files`。
+选择“两张都不要”或跳过时保留已有目标文件。省略该参数或传 `false` 仍直接生成一张图。
+第一模型可用 `ARENA_IMAGE_MODEL` 指定，第二模型可用 `ARENA_IMAGE_ALTERNATIVE_MODEL` 指定，
+默认 `gpt-image-2`；第一模型已经使用它时，第二模型默认改为 `gemini-3.1-flash-image`，两者不能相同。
+Web UI 直接展示两张图；TUI 给出候选图片路径供查看。没有交互 handler 的 headless 模式
+仍生成两张候选图，默认保存第一张并继续执行；也可配置支持图片预览的远程用户 handler 供选择。未完成的候选图保存在
+`ARENA_HOME/image-options`，同一会话重试相同请求时可复用；选择完成后清理临时图片。
+Code Arena 单图生成默认在 `gpt-image-2.5-sunburst` 和 `gpt-image-2.5-flare` 中
+每次等概率随机选择，暂不使用 Grok 和 `muse-image`。配置时优先使用 `CODE_HARNESS_IMAGE_MODEL` 固定模型，
+其次使用显式设置的 `ARENA_IMAGE_MODEL`。Code Arena 不提供 `offer_options`。图片生成结果和
 搜索到的图片会立即下载到工作区；每次图片搜索的结果按生产命名保存为
 `image-search/<query slug>-<序号>.<扩展名>`，并作为可预览文件显示在 Web UI。
 语音生成先由 `add_voice` 生成两个试听候选并让用户选择，选择结果注册为稳定的

package/dist/agent.d.ts

@@ -16,6 +16,8 @@ interface AgentOptions {
     signal?: AbortSignal;
     clientContext?: ClientContext;
     workspaceContext?: WorkspaceContext;
+    /** Restore the session's selected direct workspace child. */
+    repoDirectory?: string;
     onCheckpoint?: (messages: readonly Message[], tools: readonly ToolDefinition[], sessionMemory?: StoredSessionMemory | null) => Promise<void>;
     /** Inspect repetition, tool-call batches and pending Agent Arena compactions. */
     midturnCheckpointHook?: MidturnCheckpointHook;
@@ -42,14 +44,16 @@ interface AgentRunOptions {
     restoreSessionMemory?: boolean;
 }
 export declare function isContinuableHistory(messages: readonly Message[]): boolean;
-export declare function resolveRepoContext(workspace: string, _history?: Message[], mode?: HarnessMode): RepoContext | undefined;
+export declare function resolveRepoContext(workspace: string, _history?: Message[], mode?: HarnessMode, repoDirectory?: string): RepoContext | undefined;
 export declare class Agent {
     private readonly config;
     private readonly sink;
     private readonly options;
     private checkpointQueue;
+    private readonly restoredToolCalls;
     private checkpointError?;
     private persistedMemory?;
+    private repoDirectory?;
     private readonly memoryCache;
     private readonly client;
     private readonly tools;