@qwen-code/arena-agent 0.0.7 → 0.0.8-dev.0

package/docs/SDK.md

@@ -0,0 +1,521 @@
+# Arena TypeScript SDK 使用指南
+
+Arena SDK 是 `arena serve` 的 TypeScript 客户端，支持 Node.js 20+ 和现代
+浏览器。它封装了 session 创建与恢复、token 刷新、SSE 流式事件、附件、
+`ask_user`、取消和历史读取。
+
+## 1. 启动 Arena 服务
+
+SDK 不直接在客户端运行模型和工具；需要先启动 Arena 服务：
+
+```bash
+npm install
+npm run build
+arena serve
+```
+
+默认地址是 `http://127.0.0.1:3000`。模型和工具密钥配置在 Arena 服务端，
+不要放进使用 SDK 的浏览器代码。
+
+## 2. 安装与导入
+
+发布到 npm 后：
+
+```bash
+npm install arena-codeagent-harness
+```
+
+从本地 tarball 安装：
+
+```bash
+npm pack
+npm install /path/to/arena-codeagent-harness-0.2.0.tgz
+```
+
+SDK 使用 ESM：
+
+```ts
+import {
+  ArenaClient,
+  ArenaApiError,
+  type ArenaCredentials,
+  type ArenaInputRequest,
+  type ArenaServerEvent,
+} from "arena-codeagent-harness";
+```
+
+## 3. 三个核心概念
+
+- `ArenaClient`：连接一个 Arena 服务。
+- `ArenaSession`：一段持久对话及其独立 workspace。
+- Turn：从一条用户消息开始，到 Agent 成功、失败或被取消为止。
+
+同一个 session 可以运行多个 Turn。历史、文件和 workspace 会在这些 Turn
+之间保留。
+
+## 4. 最短可用示例
+
+```ts
+import { ArenaClient } from "arena-codeagent-harness";
+
+const arena = new ArenaClient({
+  baseUrl: "http://127.0.0.1:3000",
+});
+
+const session = await arena.sessions.create();
+const result = await session.run({
+  input: "创建一个 hello.html landing page",
+});
+
+console.log(result.status);
+console.log(result.text);
+console.log(result.files);
+```
+
+`run()` 会收集完整 Turn，适合脚本、服务端任务和不需要逐字渲染的场景。
+
+返回值主要包含：
+
+```ts
+{
+  status: "success" | "error" | "unknown";
+  text: string;
+  reasoning: string;
+  messages: Message[];
+  files: Record<string, unknown>[];
+  events: ArenaServerEvent[];
+  error?: string;
+}
+```
+
+如果只需要一次调用，也可以让 client 自动创建 session：
+
+```ts
+const result = await arena.run({
+  input: "分析这个项目",
+});
+
+console.log(result.text);
+console.log(result.session.credentials);
+```
+
+## 5. Credential、token 与 resume
+
+创建 session 后，服务端返回一组 session credential：
+
+```ts
+{
+  sessionId: string;
+  token: string;
+  expiresAt?: string;
+}
+```
+
+这里的 token 只用于访问对应 Arena session，不是模型 API Key。
+
+### 不需要跨进程恢复
+
+什么都不用保存：
+
+```ts
+const arena = new ArenaClient({
+  baseUrl: "http://127.0.0.1:3000",
+});
+
+const session = await arena.sessions.create();
+```
+
+### 保存最新 credential
+
+SDK 创建 session 或刷新 token 后会调用 `onCredentials`。应用应该始终覆盖
+旧值：
+
+```ts
+let savedCredentials: ArenaCredentials | undefined;
+
+const arena = new ArenaClient({
+  baseUrl: "http://127.0.0.1:3000",
+  onCredentials(credentials) {
+    savedCredentials = credentials;
+  },
+});
+```
+
+Node.js 服务通常应把它保存到数据库或自己的加密存储。浏览器演示可以保存到
+`localStorage`，但生产环境需要评估 XSS 风险：
+
+```ts
+const arena = new ArenaClient({
+  baseUrl: "http://127.0.0.1:3000",
+  onCredentials(credentials) {
+    localStorage.setItem(
+      "arena-session",
+      JSON.stringify(credentials),
+    );
+  },
+});
+```
+
+### 恢复 session
+
+```ts
+const credentials = JSON.parse(
+  localStorage.getItem("arena-session")!,
+) as ArenaCredentials;
+
+const session = arena.sessions.resume(credentials);
+const history = await session.getHistory();
+
+console.log(history.messages);
+console.log(history.activePrompt);
+```
+
+`getHistory()` 同时会设置 SSE 续传需要的 `lastEventId`。恢复后再调用
+`run()`、`stream()` 或 `connect()` 即可继续。
+
+当前服务端还没有用户账号维度的 `sessions.list()`/`sessions.open()`。
+跨设备登录应由服务端把 session 绑定到可信的 `userId`，并在用户登录后重新
+签发短期 session token，而不是在设备之间同步旧 token。
+
+## 6. 流式模式
+
+### 单个 Turn：`stream()`
+
+`stream()` 会自动建立 SSE、上传附件、发送消息，并在本次 Turn 完成后停止：
+
+```ts
+for await (const event of session.stream({
+  input: "创建一个 landing page",
+})) {
+  switch (event.type) {
+    case "text-delta":
+      process.stdout.write(String(event.delta || ""));
+      break;
+
+    case "reasoning-delta":
+      console.log("Reasoning:", event.delta);
+      break;
+
+    case "tool-input-start":
+      console.log("Tool:", event.toolName);
+      break;
+
+    case "tool-output-available":
+      console.log("Tool output:", event.output);
+      break;
+
+    case "data-workspace":
+      console.log("Workspace file:", event.data);
+      break;
+
+    case "trigger:turn-complete":
+      console.log("Turn status:", event.status);
+      break;
+  }
+}
+```
+
+`stream()` 默认在连接断开后使用最近的 SSE event ID 续传。
+
+### 多个 Turn 共用连接：`connect()` + `send()`
+
+Web UI 一般建立一条长期连接，然后发送多个 Turn：
+
+```ts
+const events = session.connect({
+  onEvent(event) {
+    renderEvent(event);
+  },
+  onStateChange(state) {
+    console.log("SSE:", state);
+  },
+  onError(error) {
+    console.error("SSE error:", error);
+  },
+});
+
+await events.ready;
+
+await session.send({ input: "第一个问题" });
+// 收到 trigger:turn-complete 后才能发送下一条。
+
+events.close();
+```
+
+也可以把持久连接作为 async iterable 消费：
+
+```ts
+const events = session.connect();
+await events.ready;
+
+void session.send({ input: "分析 workspace" });
+
+for await (const event of events) {
+  console.log(event);
+  if (event.type === "trigger:turn-complete") break;
+}
+
+events.close();
+```
+
+`events.close()` 只关闭本地 SSE，不会取消服务端正在运行的 Turn。
+
+### 常用事件
+
+| 事件 | 含义 |
+|---|---|
+| `start` | Turn 已开始 |
+| `reasoning-start/delta/end` | reasoning 流 |
+| `text-start/delta/end` | 最终文本流 |
+| `tool-input-start/delta/available` | 模型正在生成工具调用 |
+| `tool-output-available` | 工具执行结果 |
+| `data-agent-status` | 当前模型或工具阶段 |
+| `data-user-input-request` | `ask_user` 正在等待回答 |
+| `data-user-input-submitted` | 回答已经提交 |
+| `data-workspace` | workspace 文件可用 |
+| `data-present-file` | 应立即展示的文件 |
+| `data-messages` | 最新完整消息历史 |
+| `trigger:turn-complete` | Turn 已结束 |
+| `error` | Agent 或协议错误 |
+
+## 7. `ask_user`
+
+### 回调自动回答
+
+适合 CLI、后端服务或已有交互回调的应用：
+
+```ts
+const result = await session.run({
+  input: "帮我设计一个网站",
+  onInputRequired: async (request) => {
+    const question = request.questions[0];
+    if (!question) return [];
+    const option = question.options[0];
+    if (!option) return [];
+
+    return [
+      {
+        questionId: question.id,
+        optionId: option.id,
+      },
+    ];
+  },
+});
+```
+
+如果要提交自由文本：
+
+```ts
+return [
+  {
+    questionId: question.id,
+    customResponse: "使用深色极简风格",
+  },
+];
+```
+
+### UI 手动回答
+
+不传 `onInputRequired`，收到事件后渲染自己的 UI：
+
+```ts
+for await (const event of session.stream({
+  input: "帮我设计一个网站",
+})) {
+  if (event.type !== "data-user-input-request") continue;
+
+  const request = event.data as ArenaInputRequest;
+  const answers = await showQuestionDialog(request.questions);
+
+  await session.respondToInput(request.requestId, answers);
+}
+```
+
+答案格式：
+
+```ts
+type ArenaAnswer = {
+  questionId: string;
+  optionId?: string;
+  customResponse?: string;
+};
+```
+
+## 8. 取消
+
+取消服务端正在运行的 Turn：
+
+```ts
+const cancelled = await session.cancel();
+console.log(cancelled);
+```
+
+使用 `AbortController`：
+
+```ts
+const controller = new AbortController();
+
+setTimeout(() => controller.abort(), 5_000);
+
+for await (const event of session.stream({
+  input: "执行一个复杂任务",
+  signal: controller.signal,
+})) {
+  console.log(event);
+}
+```
+
+`stream()` 的 signal 被 abort 时，SDK 默认也会调用服务端取消接口。设置
+`cancelOnAbort: false` 可以只停止本地消费：
+
+```ts
+for await (const event of session.stream({
+  input: "继续在服务端运行",
+  signal: controller.signal,
+  cancelOnAbort: false,
+})) {
+  console.log(event);
+}
+```
+
+被取消的 partial assistant/tool 历史会由服务端保存。下次发送消息时，服务端
+会注入一次 interruption notice，Agent 可以继续处理。
+
+## 9. 附件与 workspace 文件
+
+### 浏览器 `File`
+
+```ts
+const file = inputElement.files![0]!;
+
+const result = await session.run({
+  input: "总结这个文件",
+  files: [file],
+});
+```
+
+### Node.js
+
+```ts
+import { readFile } from "node:fs/promises";
+
+const bytes = await readFile("./report.pdf");
+
+const result = await session.run({
+  input: "总结这份报告",
+  files: [
+    {
+      name: "report.pdf",
+      data: new Uint8Array(bytes),
+      type: "application/pdf",
+    },
+  ],
+});
+```
+
+`run()`、`stream()` 和 `send()` 都会先上传 `files`，再把附件引用放入消息。
+
+### 分步上传
+
+```ts
+const attachment = await session.upload({
+  name: "notes.txt",
+  data: new TextEncoder().encode("Project notes"),
+  type: "text/plain",
+});
+
+await session.send({
+  input: "整理这份笔记",
+  attachments: [attachment],
+});
+```
+
+### 下载 workspace 文件
+
+```ts
+const blob = await session.download("hello.html");
+console.log(await blob.text());
+```
+
+`workspaceUrl(path)` 可以生成文件 URL。跨域浏览器场景下，直接打开 URL
+不一定携带 Authorization header，应优先使用 `download()`，或让应用服务端
+代理下载。
+
+## 10. 错误处理
+
+非 2xx API 响应会抛出 `ArenaApiError`：
+
+```ts
+try {
+  await session.send({ input: "hello" });
+} catch (error) {
+  if (error instanceof ArenaApiError) {
+    console.error(error.status);
+    console.error(error.body);
+  } else {
+    throw error;
+  }
+}
+```
+
+流式 Agent 错误也可能作为 `error` 和 `trigger:turn-complete` 事件出现。
+`run()` 会把最终状态放在 `result.status` 和 `result.error`。
+
+## 11. 浏览器直接导入
+
+`arena serve` 会在 `/sdk.js` 提供相同的 ESM：
+
+```html
+<script type="module">
+  import { ArenaClient } from "/sdk.js";
+
+  const arena = new ArenaClient();
+  const session = await arena.sessions.create();
+  console.log(await session.run({ input: "你好" }));
+</script>
+```
+
+同源使用时 `baseUrl` 可以省略。跨域时传入完整 Arena 服务地址，并正确配置
+CORS 和认证策略。
+
+## 12. API 速查
+
+### `ArenaClient`
+
+```ts
+arena.getConfig()
+arena.createSession(options?)
+arena.sessions.create(options?)
+arena.resumeSession(credentials)
+arena.sessions.resume(credentials)
+arena.run(streamOptions, createSessionOptions?)
+```
+
+### `ArenaSession`
+
+```ts
+session.credentials
+session.getHistory()
+session.refreshToken()
+session.run(options)
+session.stream(options)
+session.connect(options?)
+session.send(options)
+session.upload(file)
+session.download(path)
+session.workspaceUrl(path)
+session.respondToInput(requestId, answers)
+session.cancel()
+```
+
+### `ArenaEventStream`
+
+```ts
+await events.ready
+await events.closed
+events.close()
+
+for await (const event of events) {
+  // ...
+}
+```

package/package.json

@@ -1,17 +1,30 @@
 {
   "name": "@qwen-code/arena-agent",
-  "version": "0.0.7",
+  "version": "0.0.8-dev.0",
   "description": "A TypeScript CodeAgent harness reconstructed from Arena message and tool traces.",
   "type": "module",
-  "types": "./dist/sdk.d.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/sdk.d.ts",
-      "import": "./dist/sdk.js"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     },
     "./sdk": {
       "types": "./dist/sdk.d.ts",
       "import": "./dist/sdk.js"
+    },
+    "./agent": {
+      "types": "./dist/agent.d.ts",
+      "import": "./dist/agent.js"
+    },
+    "./tools": {
+      "types": "./dist/tools.d.ts",
+      "import": "./dist/tools.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
     }
   },
   "bin": {
@@ -19,6 +32,7 @@
   },
   "files": [
     "dist",
+    "docs/SDK.md",
     "web",
     "README.md",
     ".env.example"
@@ -28,13 +42,13 @@
   },
   "scripts": {
     "generate:canonical-data": "node scripts/generate-canonical-data.mjs",
-    "prebuild": "npm run generate:canonical-data",
+    "prebuild": "pnpm run generate:canonical-data",
     "build": "tsc -p tsconfig.json && tsc -p tsconfig.web.json",
     "dev": "tsx src/cli.ts serve",
     "tui": "tsx src/cli.ts tui",
-    "prepack": "npm run build",
+    "prepack": "pnpm run build",
     "start": "node dist/cli.js serve",
-    "pretest": "npm run build",
+    "pretest": "pnpm run build",
     "test": "tsx --test test/*.test.ts",
     "test:tool-replay": "ARENA_TOOL_REPLAY_TESTS=1 tsx --test test/tool-replay.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.web.json --noEmit"