@qwen-code/arena-agent 0.0.7-preview.0 → 0.0.7

package/.env.example

@@ -1,6 +1,6 @@
 # Model name. Provider prefixes are stripped for direct connections and kept
 # when LITELLM_PROXY_URL is configured.
-ARENA_MODEL=openai/gpt-4.1-mini
+ARENA_MODEL=openai/qwen-latest-series-invite-beta-v92
 # ARENA_MODEL=anthropic/claude-sonnet-4-20250514
 # ARENA_MODEL=gemini/gemini-2.5-pro
 
@@ -12,29 +12,39 @@ GEMINI_API_KEY=
 # LITELLM_PROXY_URL=http://127.0.0.1:4000/v1
 # LITELLM_API_KEY=
 
-# Direct OpenAI-compatible endpoint, for example DashScope:
+# Direct OpenAI-compatible DashScope endpoint:
 # ARENA_MODEL=qwen3.7-max
 # Default model used by the reproduction scripts:
 # ARENA_API_MODEL=qwen-latest-series-invite-beta-v92
 # ARENA_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1
 # ARENA_API_KEY=
 
-# Trace overrides.
-# ARENA_MAX_TOKENS=32768
+# Trace-compatible model settings.
+# ARENA_MAX_TOKENS=131072
 # ARENA_THINKING_BUDGET=81920
 # ARENA_ENABLE_THINKING=true
-# ARENA_MAX_STEPS=64
+# Context is summarized before a model call when the estimated input reaches
+# this fraction of the configured model context window.
+# ARENA_CONTEXT_WINDOW=1000000
+# ARENA_CONTEXT_COMPACTION_RATIO=0.8
+# ARENA_COMPACTION_SUMMARY_MAX_TOKENS=8192
 # ARENA_EXTRA_BODY={"enable_thinking":true}
 # Transient model failures use full-jitter exponential backoff. The retry delay
 # is capped by ARENA_MODEL_RETRY_MAX_MS and honors Retry-After when present.
 # ARENA_MODEL_MAX_RETRIES=5
 # ARENA_MODEL_RETRY_BASE_MS=1000
 # ARENA_MODEL_RETRY_MAX_MS=30000
+# A stream that stays open but delivers no bytes for this long is aborted and
+# retried like a network fault (0 disables). Some gateways stall silently.
+# ARENA_MODEL_STREAM_IDLE_TIMEOUT_MS=300000
 
 # Daemon storage namespace. One deployed daemon should use one authenticated
 # tenant identity; sessions underneath it have independent workspaces.
 # ARENA_TENANT_ID=local
 # ARENA_SESSION_WORKSPACE_MODE=empty
+# Session state (histories, session metadata, daemon session workspaces)
+# defaults to ~/.arena so runs never write into the task workspace.
+# ARENA_HOME=~/.arena
 
 # Tool backends.
 DASHSCOPE_API_KEY=

package/README.md

@@ -41,8 +41,8 @@ export ARENA_MODEL=anthropic/claude-sonnet-4-20250514
 ```
 
 设置 `LITELLM_PROXY_URL` 时，模型名会原样发送给 LiteLLM。没有 Proxy 时，
-也支持直连 OpenAI、Anthropic OpenAI-compatibility 与 Gemini
-OpenAI-compatibility 接口：
+也支持直连：`openai/` 与 `gemini/` 前缀走各自的 OpenAI-compatibility 接口，
+`anthropic/` 前缀直接使用原生 Anthropic Messages 协议（`/v1/messages`）：
 
 ```bash
 # OpenAI
@@ -56,8 +56,35 @@ export ANTHROPIC_API_KEY=...
 # Gemini
 export ARENA_MODEL=gemini/gemini-2.5-pro
 export GEMINI_API_KEY=...
+
+# Anthropic 兼容网关（如 DashScope）
+export ARENA_MODEL=anthropic/qwen-latest-series-invite-beta-v92
+export ARENA_API_BASE=https://dashscope.aliyuncs.com/apps/anthropic/v1
+export ARENA_API_KEY=...
 ```
 
+Anthropic 直连默认只用 `x-api-key` 鉴权（同时携带 Authorization 会让部分
+兼容网关挂起）；若网关要求 Bearer token（如 DashScope 的
+claude-code-proxy），收到 401 后会自动切换鉴权方式并记住。流式连接保持
+打开但长时间无字节时（部分网关会静默停滞），按
+`ARENA_MODEL_STREAM_IDLE_TIMEOUT_MS`（默认 300000，设 0 关闭）中止并按
+网络故障重试。
+
+Anthropic 直连在原生协议上完整支持 extended thinking：
+`ARENA_ENABLE_THINKING` / `ARENA_THINKING_BUDGET` 映射为
+`thinking.budget_tokens`（Anthropic 要求启用 thinking 时不调整
+temperature，此时不发送该参数）。带签名的 thinking/redacted_thinking
+block 会原样保存在对应 assistant 消息的 `reasoning_details` 字段——
+Anthropic 要求 tool-use 续跑时回传签名 thinking block，重放历史时会按
+原顺序还原；无签名的 thinking block（部分网关返回 `signature: ""`）
+不参与重放，因为协议不需要它们，而且某些网关收到会挂起。
+`reasoning_content` 仍是纯文本推理，历史契约不变。向
+OpenAI-compatible 服务重放同一份历史时，`reasoning_details` 与 `usage`
+一样在 wire 边界剥离。usage 会映射为 OpenAI 风格字段（`prompt_tokens`
+含 cache 创建/读取部分），同时保留 `input_tokens`、
+`cache_read_input_tokens` 等原生字段。`ARENA_API_BASE` 对 anthropic
+前缀同样生效，可指向兼容 Messages 协议的网关。
+
 任何 OpenAI-compatible 服务都可通过 `ARENA_API_BASE`、`ARENA_API_KEY`
 直连。CLI、TUI 和服务端会读取工作区根目录的 `.env`，且不会覆盖进程中已经
 存在的环境变量。当前 DashScope 配置示例：
@@ -66,16 +93,54 @@ export GEMINI_API_KEY=...
 ARENA_MODEL=qwen3.7-max
 ARENA_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1
 ARENA_API_KEY=sk-...
+ARENA_ENABLE_THINKING=true
+ARENA_THINKING_BUDGET=81920
+ARENA_MAX_TOKENS=131072
+ARENA_CONTEXT_WINDOW=1000000
+ARENA_CONTEXT_COMPACTION_RATIO=0.8
+ARENA_COMPACTION_SUMMARY_MAX_TOKENS=8192
 ```
 
 `DASHSCOPE_API_KEY` 单独供搜索、图片生成和语音工具使用，不会作为模型连接的
 密钥。
 
+Harness 会在每次模型调用前估算消息、reasoning、工具 schema 和图片占用；达到
+`ARENA_CONTEXT_WINDOW × ARENA_CONTEXT_COMPACTION_RATIO`（默认 80%）时，调用
+当前模型把已完成的旧回合生成结构化续作摘要。旧前缀会被替换为与 Arena trace
+一致的 leading `<arena-system-message>`，当前用户回合及其后的 tool-call / result
+链保持原样。摘要重点保留目标、硬约束、发现、已完成/未完成事项、下一步和相关
+文件路径；摘要调用默认关闭 thinking，输出上限由
+`ARENA_COMPACTION_SUMMARY_MAX_TOKENS` 控制（默认 8192）。
+
+`ARENA_CONTEXT_WINDOW` 应设置为所用模型的真实上下文窗口；默认 `1000000` 是
+当前 trace 模型的暂定值。token 数目前是本地保守估算，并非 provider tokenizer
+的精确计数。如果摘要请求失败，Harness 会保留原历史并继续正常模型请求，避免
+摘要服务的瞬时故障直接中断任务。
+
+每次模型请求都会通过 OpenAI-compatible 的 `stream_options.include_usage`
+请求 token 用量，并把服务端在最终 chunk 上报的 `usage` 对象原样记录到该轮
+assistant 消息的 `usage` 字段（`history.json` 与事件流中均可见），供训练
+和成本统计使用。向模型重放历史时，`usage` 会在 wire 边界剥离，不会发回
+服务端。`model.complete` 事件同样携带该轮 `usage`；上下文压缩的摘要调用
+不会在历史中留下消息，其用量通过 `compaction` 事件上报，只在事件流中可
+见。不支持 `stream_options` 的服务可通过 `ARENA_EXTRA_BODY` 覆盖该参数。
+
 模型请求遇到网络错误、HTTP 408/409/429 或 5xx 时会自动重试，默认最多重试
 5 次。没有 `Retry-After` 时使用带随机抖动的指数退避；可通过
 `ARENA_MODEL_MAX_RETRIES`、`ARENA_MODEL_RETRY_BASE_MS` 和
 `ARENA_MODEL_RETRY_MAX_MS` 调整。设 `ARENA_MODEL_MAX_RETRIES=0` 可关闭。
-流式响应已经开始产出后发生的错误不会整轮重放。
+
+流式响应**开始产出之后**发生的网络中断（如 socket 断开、连接重置、
+`fetch failed`／`terminated`）同样会整轮重试：请求本身是幂等的，会用相同的
+消息历史重新发起，累加器每次重试都会重置，因此写入 `history.json` 的是一次
+干净完整的 assistant 输出。重试沿用上面同一组配置，并在事件流中先发出一个
+`model.retry` 事件（TUI 会显示「reconnecting after a network error」提示）。
+用户主动取消（abort）不会被当作可重试的网络故障。
+
+Agent turn 没有 step 数或整轮墙钟时长上限，会持续执行到模型正常结束、
+请求用户输入、发生不可恢复错误，或用户主动取消。工具自身仍可定义单次调用
+的超时。每个完整的 assistant/tool step 都会原子保存到 `history.json`；
+进程被外部超时终止时，已完成步骤仍可恢复，最多丢失当时正在执行的一步。
 
 ## Headless
 
@@ -88,9 +153,12 @@ arena -p 'create a hello.html landing page' --output stream-json
 daemon 相同的目录层级和 JSON 格式：
 
 ```text
-.arena/tenants/<tenantId>/sessions/<sessionId>/history.json
+~/.arena/tenants/<tenantId>/sessions/<sessionId>/history.json
 ```
 
+session 状态统一存放在 `~/.arena`（可用 `ARENA_HOME` 覆盖），不写入
+workspace，因此不会污染任务工作区或被 diff 工作区的 verifier 观察到。
+
 输出事件及 JSON 结果中的 `session_id` 就是路径里的 `<sessionId>`。
 `history.json` 的格式为 `{"messages":[...]}`，即使结果为 `needs_input`
 或 `error` 也会保存。需要跨命令续写同一份显式历史时，可另外传入
@@ -106,21 +174,53 @@ arena -p '继续实现刚才的方案' --session-id my-session
 ```
 
 首次执行会创建对应的 `history.json`；后续执行会先加载已有消息，追加本轮
-消息后再原子重写完整 JSON 文件。`--session-id` 与 `--history-file` 不能
-同时使用。
+消息，并在初始 user 消息及每个完整 assistant/tool step 后原子重写完整
+JSON 文件。`--session-id` 与 `--history-file` 不能同时使用。
+
+需要附带用户上传文件（尤其是参考图片）时，使用可重复的 `--attach`
+（别名 `--image`），值可以是本地路径或 http(s) URL：
+
+```bash
+arena -p 'redraw this photo with the reference face' \
+  --attach ./my_gf_reference.png \
+  --attach 'https://example.com/uploads/photo.jpg'
+```
+
+每个附件会被保存到工作区 `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 请求的边界处转换为
+OpenAI 风格的 `image_url` 部件。`--attach` 传 URL 时 `image` 直接记录该
+URL（与 baseline 引用附件的方式一致，模型服务端会自行下载；重放历史要求
+该 URL 仍可访问）；本地文件没有可引用的 URL，`image` 存自包含的 base64
+data-URI。
 
 `stream-json` 每行一个 JSON 对象。`start`、`message`、`result` 事件中的
 `messages` 与输入样例保持相同契约：
 
 - system/user：`role` + `content`；图片读取后会持久化一条 multimodal user
   message
-- assistant：`role` + `content` + `reasoning_content`，工具轮含 `tool_calls`
+- assistant：`role` + `content` + `reasoning_content`，工具轮含 `tool_calls`；
+  服务端上报用量时含 `usage`
 - tool：`role` + `tool_call_id` + JSON 字符串 `content`
 
 `assistant.delta` 实时提供 content、reasoning 与 tool-call 参数碎片；
-`model.start`、`model.complete`、`tool.start`、`tool.complete` 标记阶段。
-最后的 `result` 带完整可重放消息。当 headless 模型调用 `ask_user` 时，
-输出 `input.required` 后以 `needs_input` 结束，不会阻塞训练 worker。
+`model.start`、`model.complete`、`model.retry`、`tool.start`、`tool.complete`
+标记阶段。最后的 `result` 带完整可重放消息。
+
+`ask_user` 需要交互式前端（TUI/WebUI）来收集选项，因此 **headless（`-p`）与
+无会话的 `/query` 端点不会把 `ask_user` 提供给模型**——只有 TUI 和 WebUI
+交互会话（都注入了 ask-user handler）才会开放该工具。这样 headless 不会再
+卡在 `needs_input` 上阻塞训练 worker。作为兜底，若续写的历史或模型幻觉在无
+handler 的会话里仍调用了 `ask_user`，工具会返回一个 error 结果（提示模型用
+合理默认值继续），而不是 `needs_input`。
 
 图片 `read_file` 的 tool result 使用占位文本；真实图片作为紧随工具结果组的
 multimodal user message 注入并写入历史，因此后续重放不依赖原图片仍然存在。
@@ -135,6 +235,12 @@ arena tui
 arena tui --workspace . --model mock/ask-user --session-id my-session
 ```
 
+workspace 默认是启动命令时的当前目录（可用 `--workspace` 覆盖）。TUI 会把
+实际 workspace root 和 cwd 动态注入 system prompt 与工具 schema；因此本机
+运行时使用本机路径，部署进沙箱后会自然使用沙箱内的实际路径，不需要切换模式。
+TUI 没有内置文件 viewer，因此不会向模型提供 `present_file`；模型会直接报告
+生成文件的实际路径。
+
 assistant 的 reasoning、正文和工具调用状态会边生成边输出。每轮结束都会把
 完整消息原子写入与 headless、daemon 相同的 `history.json`；再次传入相同的
 `--session-id` 会恢复上下文。也可改用工作区内的显式
@@ -241,10 +347,11 @@ npm start
 reasoning、工具输入输出、交互问题及 workspace 文件。session ID 由服务端
 生成；打开页面或点击 New Chat 时只保留浏览器内的空白草稿，首次发送消息
 （包括带附件的消息）时才创建 session。每个 session 的凭证哈希、历史、
-workspace 和 artifacts 分别保存在：
+workspace 和 artifacts 分别保存在（根目录 `~/.arena` 可用 `ARENA_HOME`
+覆盖）：
 
 ```text
-.arena/tenants/<tenantId>/sessions/<sessionId>/
+~/.arena/tenants/<tenantId>/sessions/<sessionId>/
   session.json
   history.json
   workspace/
@@ -324,10 +431,14 @@ curl -N -X POST \
 
 ## 工具
 
-工具规范逐字保存在 `spec/tools.json`，运行时加载并在执行前使用 AJV 校验
-原始 Draft-07 schema。system prompt 以占位符模板编译在 `src/prompts.ts`；
-逐字捕获样本 `spec/message.json` 与 `spec/message-repo.json` 只作为仓库内
-测试 fixture，包含真实会话数据，不随 npm 包发布。工具列表：
+原始规范在源码仓库中逐字保存在：
+
+- `spec/message.json`
+- `spec/tools.json`
+
+构建时会将两份规范生成为 `dist` 内的 JS 数据模块；npm 包不包含原始
+`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`、

package/dist/agent.d.ts

@@ -1,12 +1,16 @@
 import type { ArenaConfig } from "./config.js";
 import { EventSink } from "./protocol.js";
-import type { AgentResult, AskUserHandler, ClientContext, Message, ModelClient, RepoContext, UserTurnMessage } from "./types.js";
+import { ToolExecutor } from "./tools.js";
+import type { AgentResult, AskUserHandler, ClientContext, Message, ModelClient, RepoContext, UserTurnMessage, WorkspaceContext } from "./types.js";
 interface AgentOptions {
     client?: ModelClient;
+    tools?: ToolExecutor;
     askUserHandler?: AskUserHandler;
     sessionId?: string;
     signal?: AbortSignal;
     clientContext?: ClientContext;
+    workspaceContext?: WorkspaceContext;
+    onCheckpoint?: (messages: readonly Message[]) => Promise<void>;
 }
 interface AgentRunOptions {
     interrupted?: boolean;
@@ -18,10 +22,14 @@ export declare class Agent {
     private readonly sink;
     private readonly options;
     private readonly client;
+    private readonly tools;
     readonly sessionId: string;
     constructor(config: ArenaConfig, sink: EventSink, options?: AgentOptions);
     run(prompt: string, history?: Message[], runOptions?: AgentRunOptions): Promise<AgentResult>;
+    private checkpoint;
+    private maybeCompact;
     private assistantTurn;
+    private retryBackoff;
 }
 export declare function finalText(result: AgentResult): string;
 export {};