@qwen-code/arena-agent 0.0.10-dev.14 → 0.0.10-dev.16

package/.env.example

@@ -28,6 +28,10 @@ ARENA_HARNESS_MODE=arena
 # ARENA_STREAM_HISTORY=full
 # ARENA_CODE_STREAM_HISTORY remains a lower-priority compatibility alias.
 
+# Headless configuration: a redacted startup record and actual request settings
+# on stderr and in the session's startup-config.jsonl. Set false to disable both.
+# ARENA_CONFIG_LOGGING=true
+
 # Native provider fallbacks used when OPENAI_BASE_URL/API_KEY are unset.
 # ANTHROPIC_BASE_URL=https://api.anthropic.com/v1
 # ANTHROPIC_API_KEY=
@@ -64,11 +68,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=
@@ -87,14 +98,14 @@ ARENA_HARNESS_MODE=arena
 # Agent Arena: threshold is 250000 unless BOTH variables below have valid
 # values, in which case threshold = context window * ratio.
 # Code Arena keeps independent controls (default window 1000000, ratio 0.7).
-# Rolling counts use completed-request usage plus newer messages; summary
-# mode uses the historical local token estimate.
+# Compaction counts use completed-request usage plus newer messages.
 # ARENA_CONTEXT_WINDOW=1000000
 # ARENA_CONTEXT_COMPACTION_RATIO=0.25
-# Restore Agent Arena background memory: unset defaults to --single-step only.
+# 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
 # Provisional Agent Arena background-memory budget for newly archivable content.
+# Uses request-usage deltas with local supplements; local counts omit tool-call IDs.
 # ARENA_MEMORY_UPDATE_TOKENS=24000
 # Default: rolling memory 131072; summary mode and Code Arena 8192.
 # ARENA_COMPACTION_SUMMARY_MAX_TOKENS=131072
@@ -157,6 +168,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
@@ -168,8 +185,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,39 @@
 
 ## [Unreleased]
 
+## [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
+
+- 后台记忆更新按服务端 token 用量差分判断新增预算，减少长签名造成的提前更新。
+- 默认恢复同 session 的后台记忆，避免多轮调用重复更新；可用 `ARENA_RESTORE_SESSION_MEMORY=false` 或 `--no-restore-session-memory` 关闭。
+
+### 通用
+
+- 本地上下文估算忽略工具调用 ID，避免内嵌长签名抬高计数。
+- Headless 记录生效配置、脱敏输入及实际模型请求参数和工具列表，输出到 stderr 与会话的 `startup-config.jsonl`，可用 `ARENA_CONFIG_LOGGING=false` 关闭。
+
 ## [0.0.10-dev.14] - 2026-10-26
 
 ### 通用
@@ -267,7 +300,9 @@
 - `bash` 用于一次性命令，区分超时与信号终止，并清理遗留后台进程；需要持续运行
   的任务改用进程工具。预览端口支持 E2B Host 探测及按需返回告警。
 
-[Unreleased]: https://code.alibaba-inc.com/know-how/arena-harness/compare?from=v0.0.10-dev.14&to=master&mergeBase=true
+[Unreleased]: https://code.alibaba-inc.com/know-how/arena-harness/compare?from=v0.0.10-dev.16&to=master&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
 [0.0.10-dev.12]: https://code.alibaba-inc.com/know-how/arena-harness/compare?from=v0.0.10-dev.11&to=v0.0.10-dev.12&mergeBase=true

package/README.md

@@ -113,6 +113,55 @@ code-harness --file prompt.txt --mode react
 `CODE_HARNESS_MODE`、`ARENA_MODE` 及旧模式别名。详细目录和发包决策见
 [`docs/MODES_AND_RELEASES.md`](docs/MODES_AND_RELEASES.md)。
 
+### 启动配置日志
+
+`arena -p`、`--file` 和 `--continue` 默认在 stderr 输出一条 `[arena:config]`
+JSON 启动日志，并将同一条记录追加到会话目录下的 `startup-config.jsonl`，与
+`history.json` 放在一起。日志中的 `run.configLogFile` 给出完整路径；AP 可直接
+收集 stderr，或从 `ARENA_HOME` 指定的状态目录读取文件。
+
+`config` 按环境变量名记录解析后的主模型、工具、搜索、图片与语音、缓存、代理、
+预览和快照配置，包括默认值；没有对应环境变量的计算结果保留字段名，例如
+`compactionThresholdTokens`。同一设置使用主变量名，例如 `OPENAI_MODEL` 表示最终选中的
+模型，即使输入来自 `ARENA_MODEL` 或 `--model`。未配置或当前模式不适用的项记为 `null`。
+工具配置表示启动时的默认设置，单次工具调用仍可覆盖超时、选择声音等参数。
+
+`inputs.environment` 和 `inputs.workspaceEnv` 分别保留启动环境和工作区 `.env` 的
+相关原始键值，包括被覆盖的值；`inputs.arguments` 记录解析后的 CLI 选项。进程环境
+优先于 `.env`，CLI 参数在加载配置后覆盖，续跑记录恢复后的模式和模型。未知的
+`ARENA_*` 等变量只出现在输入中，不会被当成生效配置。这里只记录 harness 相关设置，
+不会转储整个进程环境。快照配置只采用启动环境；server/TUI 专用配置在 headless 中不生效。
+
+`connection` 记录实际模型协议和连接地址，`connection.sources` 标明最终使用的地址和
+凭据来源，例如 `OPENAI_API_KEY` 或 `ANTHROPIC_API_KEY`；密钥值仍会脱敏。
+`run.cwd` 记录实际工作目录，`run.history` 记录历史是否加载、消息数、来源，以及
+模型和模式是否继承历史。不带 `--continue` 时，同一 session 也可能加载已有历史。
+`sessionMemoryAvailable` 只表示存在可供检查的快照，`restoreSessionMemory` 表示允许恢复，
+不表示已通过历史匹配检查。`inputs.workspaceEnvFile` 记录 `.env` 的路径、读取状态和错误码。
+`modelInput.inputAllowed` 汇总文字、图片、视频和音频的输入开关，图片等开关也保留在
+`config.ARENA_MODEL_SUPPORTS_*_INPUT`。`modelInput.sources` 说明每种模态的判断来源：
+对应环境变量名表示显式覆盖，`model_registry` 表示命中内置模型规则，
+`unknown_model_default` 表示未知模型默认允许尝试；这种默认值不表示已验证远端支持。
+`registryKnown`、`registryRule` 和 `normalizedModel` 可用于核对模型名是否被正确识别。
+这些字段描述主模型的输入能力，与图片、语音生成工具使用的模型配置分开。
+`modelInput.transport.userContent` 另行说明传输处理：Chat Completions 为 `passthrough`，
+当前 Responses/Anthropic 编码器为 `text_and_images_only`；模态开关不会扩展编码器支持范围。
+设置 `ARENA_EXTRA_BODY.model` 时，`modelInput.requestModelOverride` 会单独显示该覆盖值，
+模态规则仍按 `modelInput.model` 判断。`imageFallback` 记录图片转文字 fallback 是否启用、
+原因和启用时的实际连接；它只适用于 Agent Arena 的 `read_file` 图片输入。
+
+密钥只显示 `[set]` / `[unset]`，URL 移除账号、密码、查询参数与片段，自定义提示词
+和额外请求体中的自由文本仅记录字符数与 SHA-256。
+
+启动记录的 `event` 为 `startup_config`。实际 HTTP 请求准备好后，会在相同位置补写
+`model_request_config`，记录协议映射和 `ARENA_EXTRA_BODY` 覆盖后的模型、参数与工具名称，
+使用接口字段名，例如 `max_output_tokens`。被协议省略的参数不会出现在这条记录中。
+同一进程内相同请求配置只记录一次；模型、参数或工具定义变化时再记录。
+因此可以直接核对温度、thinking 设置和工具是否真正进入请求，无需从启动配置推导。
+这条记录表示请求已构造，不表示服务端已接受；完整调用过程仍可查看 `llm-calls.jsonl`。
+`ARENA_MODEL_CALL_LOGGING=false` 不影响配置日志；设置 `ARENA_CONFIG_LOGGING=false`
+会同时关闭 stderr 和文件中的启动、请求配置日志。stdout 输出格式保持不变。
+
 ### 中途快照与单步执行
 
 Headless CLI 可通过 JavaScript Hook 决定何时继续或创建 Harbor 快照。工具校验在
@@ -214,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>`：
@@ -367,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`
@@ -400,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。
@@ -446,9 +523,18 @@ Agent Arena 历史 metadata 记录本次压缩方式；下一次运行仍以当
 以下后台记忆机制适用于 `rolling` 模式。
 
 Agent Arena 在每次模型调用前检查新增对话预算：自上次成功记忆更新以来，
-可归档内容的本地估算达到 `ARENA_MEMORY_UPDATE_TOKENS`（默认 24000）时，
+可归档内容的 token 增量达到 `ARENA_MEMORY_UPDATE_TOKENS`（默认 24000）时，
 启动一个后台记忆更新任务。24000 是根据历史日志选择的暂定策略，不是已确认的官方常数。
 已有记忆、系统提示词和工具定义不计入新增预算；最新完整的模型／工具步骤保留原文。
+新增预算优先用该段首个有效 assistant 的 input usage 作为基线，减去公共输入前缀：
+末个有效 assistant 的 total usage 减去该基线，再补估段首用户消息及末尾工具结果。
+total 缺失时尝试 input/output 相加；只有 input 时，连同该 assistant 一起补估。
+缺失 usage 的中间步骤由后续 input 覆盖，没有可用基线、input usage 倒退或用量自相矛盾时回退本地估算。
+差分依赖同一模型和稳定的输入前缀；切换模型或工具定义后若 usage 未被清除，
+仅靠数值无法识别所有口径变化。
+回填已归档消息仍会触发现有的历史前缀校验失效，清除覆盖位置并重新计算新增范围。
+本地估算忽略工具调用 ID（包括 Responses 的函数调用 ID）和 usage 元数据，
+保留参数、结果正文及图片计数；实际历史与请求中的 ID 和签名保持完整。
 更新完成只刷新缓存，主模型继续使用原上下文。
 
 整体上下文达到压缩阈值时才回注最新记忆。Agent Arena 默认固定为 250,000 tokens；
@@ -480,10 +566,11 @@ Agent Arena 使用捕获的 session-memory 协议：只输出变化章节并合
 这些字段及 `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 和服务端，
-命令行标志优先）。恢复前会校验记忆覆盖的历史前缀；不匹配的缓存会被丢弃。
+Agent Arena 默认恢复后台记忆缓存，包括同 session 的新一轮 `-p`、`--continue`
+和 `--single-step`。设置 `ARENA_RESTORE_SESSION_MEMORY=false` 或
+`--no-restore-session-memory` 可显式关闭（适用于 CLI、TUI 和服务端，命令行标志优先）；
+`--restore-session-memory` 可覆盖环境变量的关闭设置。
+恢复前会校验记忆覆盖的历史前缀；不匹配的缓存会被丢弃。
 关闭恢复不会删除仍有效的已存快照。恢复缓存本身不触发压缩，也不影响历史里
 已应用的 `compaction` 记录。
 
@@ -1041,7 +1128,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` 将
@@ -1052,8 +1140,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 代理缩略图，并保持既有工具结果格式和工作区文件命名不变。
@@ -1064,11 +1153,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 边界稳定分块，同一轮内
@@ -1083,10 +1186,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

@@ -1,5 +1,6 @@
 import { type ArenaConfig } from "./config.js";
 import { type StoredSessionMemory, type SessionMemoryCache } from "./compaction.js";
+import { type ModelRequestObserver } from "./provider.js";
 import { EventSink } from "./protocol.js";
 import { type HarnessMode } from "./mode.js";
 import { ToolExecutor } from "./tools.js";
@@ -15,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;
@@ -28,6 +31,7 @@ interface AgentOptions {
     /** Explicit Agent Arena override of the resolved compaction threshold. */
     compactionThresholdTokens?: number;
     onModelFailure?: (messages: readonly Message[], error: unknown) => void;
+    onModelRequest?: ModelRequestObserver;
     /** Reuse immutable loaded history messages instead of cloning the full prefix. */
     reuseHistoryMessages?: boolean;
 }
@@ -36,18 +40,20 @@ interface AgentRunOptions {
     userMessage?: UserTurnMessage;
     resumeFromHistory?: boolean;
     singleStep?: boolean;
-    /** Defaults to singleStep. Restores the cache without forcing compaction. */
+    /** Overrides config; defaults to true. Restores the cache without forcing compaction. */
     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;