@blade-hq/agent-client 2612.0.0-beta.43 → 2612.0.0-beta.45

package/README.md

@@ -452,6 +452,47 @@ await client.computers.setEnabled(sessionId, computer.id, false)  // 停用
 
 `ComputersResource` 是 `client.computers` 的类型。
 
+### 手机：client.phones
+
+用户接进来的 Android 手机。手机在这台工作环境里就是一台 adb 设备，智能体可以直接
+用 `adb` 命令操作它。和一键可用的电脑不同，手机要先在设置页拿到一把**接入密钥**
+填进手机 App，App 连上来之后设备自动登记。
+
+```ts
+const { phones } = await client.phones.listAccount()
+// PhoneList → { phones: PhoneDevice[] }
+// PhoneDevice: { id, label, serial, model, android_version, created_at,
+//                last_seen_at, online, adb_online, enabled, session_id }
+
+await client.phones.setEnabled(sessionId, phone.id, true)   // 本次会话可以用它
+await client.phones.setEnabled(sessionId, phone.id, false)  // 停用
+```
+
+`online` 和 `adb_online` 是**两件独立的事**，会单独坏：
+
+- `online`：手机此刻连着后端。连上就算，不等沙盒。
+- `adb_online`：沙盒里的 adb 此刻能对它执行命令。需要 adb 认证通过。
+
+手机连着但沙盒里没装 adb、或者认证没过，`online` 仍然是 true 而 `adb_online` 是
+false。合成一个「离线」会让人去排查网络，而问题在沙盒。
+
+`PhoneState` 是把这两个字段折成 UI 状态的唯一出处（`phoneState(phone)`），不要
+在调用方重新拼一遍判断。
+
+```ts
+const key = await client.phones.getKey()
+// PhoneAccessKey → { key, hub_url, connector_url }
+
+await client.phones.resetKey()   // 换一把新密钥并作废旧密钥
+await client.phones.revokeKey()  // 作废，之后手机重连一律被拒
+```
+
+`key` 是以 `pk_` 开头的长期凭据，没作废就一直有效。`hub_url` 是服务器地址（协议+
+主机+端口），`connector_url` 是手机 App 的下载地址，管理员可以配成自己的静态文件。
+
+`PhonesResource` 是 `client.phones` 的类型，`PhoneDevice` / `PhoneAccessKey` /
+`PhoneList` / `PhoneHealth` / `PhonePipeline` / `PhoneState` 是配套的公开类型。
+
 ## AgentSession
 
 一个会话的实时状态机。**状态归属实例**：同一页面建多个会话互不干扰。
@@ -751,7 +792,7 @@ chat.renderers = {
 - **页面协作**：`CommandHandler`、`BladeChatMountRenderers`、`MountRenderer`、`MountRendererObject`、`MountResult`、`MountHandle`
 - **会话资源（REST）**：`SessionsResource`、`CreateSessionRequest`、`McpSourceConfig`、`PaginatedSessionsResult`、`SessionInfo`、`SessionStatus`、`SessionDetail`、`DEFAULT_REPLAY_SPEED`、`ReplaySpeed`、`ReplayState`、`SessionTurnsPage`、`SessionTurnsQuery`、`FileEntry`、`UploadFileEntry`、`UploadFilesOptions`、`AppCliDefinition`、`AppCliAttachment`
 - **模型目录**：`ModelsResource`、`ModelCatalog`、`ModelOption`
-- **沙盒脚本**：`SandboxResource`、`SandboxScriptRequest`、`SandboxScriptResult`。`client.sandbox.execute({ script, cwd, timeout })` 在当前登录用户的沙盒执行脚本，无需创建智能体会话；`cwd` 使用绝对路径，`timeout` 单位为秒，默认及最大值为 120。结果包含有界输出、可为空的退出码、超时标志和错误信息；无法启动或无法确认停止时应检查 `error`，不能仅凭退出码判断成功。
+- **沙盒脚本**：`SandboxResource`、`SandboxScriptRequest`、`SandboxScriptResult`。`client.sandbox.execute({ script, cwd, timeout })` 在当前登录用户的沙盒执行脚本，无需创建智能体会话；`cwd` 使用绝对路径，`timeout` 单位为秒，默认及最大值为 120。结果包含合并诊断输出 `output`、独立标准输出 `stdout` 及其截断标志 `stdout_truncated`、可为空的退出码、超时标志和错误信息；无法启动或无法确认停止时应检查 `error`，不能仅凭退出码判断成功。
 - **远程电脑**：`ComputersResource`、`SessionComputer`、`AccountComputer`
 - **Headless**：`HeadlessResource`、`RunOptions`、`RunResult`、`RunTrace`
 - **消息**：`ChatMessage`、`MessageContent`、`MessageContentPart`、`TextContentPart`、`ImageUrlContentPart`、`FileContentPart`、`ToolCallInfo`、`WorkflowStepInfo`(固定流程运行时每步的留档，挂在 `workflow:run` 的 `ToolCallInfo.workflow_steps` 上)、`MemoryRefInfo`、`getTextContent`、`getImageParts`、`getFileParts`、`contentPreview`、`groupMessagesByLoop`、`chatErrorForDisplay`、`transformSlashCommand`、`SkillMentionAvailability`、`userFacingErrorText`
@@ -843,7 +884,9 @@ const delivery = await session.getDelivery(request.requestId)
 
 同一保存请求可重试，BA 不重复入队；同 ID 改变正文或参数会拒绝。接收结果 `accepted` 表示输入已持久化，不表示任务完成。`unknown` 表示无法确认，`not_found` 是查询未找到；不得因此生成新 ID。查询可返回队列项、队列状态和执行 ID；记录保留至会话删除。
 
-此接口复用后端等待队列：空闲时自动开始，运行中等待，暂停时保留。可靠请求不能编辑或作为立即补充，但可以取消、重排和继续。支持普通文本、模式、模型、思考与推理强度；AskUser 作答、多模态、whatif 和 replay 继续使用 `send()`。需要支持 `prepared_options` 及 `chat:queue:request` 的 BA；旧服务的普通队列确认不算可靠请求回执。
+此接口复用后端持久化投递：空闲时自动开始，默认在运行中等待，暂停时保留。设置 `queueWhenRunning: false` 时补充当前运行，PA 使用此模式。可靠请求不能编辑，但可以立即补充、取消、重排和继续。支持普通文本、模式、模型、思考与推理强度；AskUser 作答、多模态、whatif 和 replay 继续使用 `send()`。需要支持 `prepared_options` 及 `chat:queue:request` 的 BA；旧服务的普通队列确认不算可靠请求回执。
+
+`PreparedSendOptions.headless: true` 让可靠输入使用 BA 的 `submit_result` 交付契约，运行中追加仍遵循 `queueWhenRunning`。`session.getState().lastRun` 保留最近 BA 执行终态（`runId`、`status`、原始 `result`），实时与重连日志补发一致，不依赖消息分页。调用方应通过 `getDelivery(requestId).executionId` 关联本轮执行，不能把上一轮终态当成本轮结果。
 
 公开类型：`PreparedSend` 是可持久化的请求快照，`PreparedSendOptions` 是普通输入的执行参数，`DeliveryReceipt` 是接受或查询结果。
 
@@ -869,7 +912,7 @@ await persist(request)
 await session.sendPrepared(request)
 ```
 
-每条消息最多 20 份资料，ID 不重复，每份正文最多 64000 个 Unicode 字符，整个资料 JSON 最多 256 KiB，超限拒绝。文件沿用指定会话的鉴权与路径解析，不接受外部 URL；仅有 `name` 的文件显示不可用。带资料的可靠消息作为独立一轮排队，不能走只传正文的「立即补充」。原生智能体目前不支持此通道。
+每条消息最多 20 份资料，ID 不重复，每份正文最多 64000 个 Unicode 字符，整个资料 JSON 最多 256 KiB，超限拒绝。文件沿用指定会话的鉴权与路径解析，不接受外部 URL；仅有 `name` 的文件显示不可用。带资料的可靠消息支持 `queueWhenRunning: false` 或「立即补充」；正文和资料一起交给当前运行，资料仍通过标准 Context 注入。原生智能体目前不支持此通道。
 
 ## 连接器管理
 
@@ -915,3 +958,13 @@ session.send("请处理新增工作", {
 ### 创建或修改连接器
 
 `client.connectors.startGeneration({ connector?, onCreated?, initiator? })` 统一创建生成会话并发送带技能引用的可见消息，返回 `{ session_id, sent }`。`connector` 传已有连接器的名称与展示名表示修改；`onCreated` 仅用于宿主登记缓存、导航。`initiator` 默认 `sdk`，内置 Web 使用 `ui`，保留历史列表和通知语义。选定连接器的名称与展示名通过标准 Context 附件传递，用户消息保持固定，包内文字不会被提升成用户指令。SDK 在发送前调用回调，并释放自身的会话引用。生成结束仍需用户到设置里的连接器正式连接。
+
+### Android 浏览器授权回传
+
+BA/PA 安卓端在系统浏览器授权时使用 S256 PKCE。服务端接收原生端交回的一次性 code 后，需同时转交该请求的 verifier 和产品；普通网页弹窗不需要这两个字段：
+
+```ts
+await client.auth.exchangeCode({ code, state, clientOrigin, codeVerifier, androidApp: "pa" })
+```
+
+`state` 必须与发起请求时一致；PA 还须校验自身登录请求 cookie。访问令牌保存在自己的服务端，不能通过回调 URL 或网页消息转发。手机端回传及部署约定见仓库 `docs/specs/261026-android-browser-login/`。

package/dist/blade-client.d.ts

@@ -6,6 +6,7 @@ import { type BladeFetchInit, type HttpMethod } from "./rest";
 import { AuthResource } from "./resources/auth";
 import { HeadlessResource } from "./resources/headless";
 import { ComputersResource } from "./resources/computers";
+import { PhonesResource } from "./resources/phones";
 import { ModelsResource } from "./resources/models";
 import { SessionsResource } from "./resources/sessions";
 import { PluginsResource } from "./resources/plugins";
@@ -53,6 +54,8 @@ export declare class BladeClient {
     readonly auth: AuthResource;
     readonly headless: HeadlessResource;
     readonly computers: ComputersResource;
+    /** 用户接进来的手机：账号级清单、会话启用、画面信令。 */
+    readonly phones: PhonesResource;
     readonly models: ModelsResource;
     readonly sessions: SessionsResource;
     /** 按用户读取的插件目录与图标；没有会话时也能用。 */

package/dist/{chunk-XAXUPUD2.js → chunk-ME7O7RJC.js}

@@ -224,7 +224,7 @@ var ToolProvider = class {
 
 // src/version.ts
 var SDK_NAME = "agent-client";
-var SDK_VERSION = true ? "2612.0.0-beta.43" : "1.1.1";
+var SDK_VERSION = true ? "2612.0.0-beta.45" : "1.1.1";
 
 // src/auth-login.ts
 function isAuthCallbackMessage(value) {
@@ -378,6 +378,7 @@ var AuthResource = class {
       headers: { Origin: params.clientOrigin },
       body: JSON.stringify({
         code: params.code,
+        ...params.codeVerifier ? { code_verifier: params.codeVerifier, android_app: params.androidApp } : {},
         state: params.state,
         client_origin: params.clientOrigin
       })
@@ -3259,6 +3260,94 @@ var ComputersResource = class {
   }
 };
 
+// src/resources/phones.ts
+function phoneState(phone) {
+  if (phone.enabled) return "enabled";
+  return phone.online ? "idle" : "offline";
+}
+function sortPhones(phones) {
+  return [...phones].sort((a, b) => {
+    const byCreated = (a.created_at ?? "").localeCompare(b.created_at ?? "");
+    if (byCreated !== 0) return byCreated;
+    return a.label.localeCompare(b.label);
+  });
+}
+function phoneSerialLabel(phone) {
+  return phone.serial.trim();
+}
+var PhonesResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /** 账号下的全部手机（不含"本次会话是否可用"）。 */
+  async listAccount() {
+    return this.client.json("GET", "/api/phone/devices");
+  }
+  /**
+   * 当前接入密钥；没有就补一个。
+   *
+   * **取的时候不轮换**：每次打开设置页都换钥匙会让已配好的手机集体掉线。
+   */
+  getKey() {
+    return this.client.json("GET", "/api/phone/key");
+  }
+  /** 换一把新密钥（旧的立即失效）。 */
+  resetKey() {
+    return this.client.json("POST", "/api/phone/key/reset");
+  }
+  /** 作废密钥；设备记录保留，用户下次取密钥会得到一把新的。 */
+  async revokeKey() {
+    await this.client.fetch("DELETE", "/api/phone/key");
+  }
+  async remove(phoneId) {
+    await this.client.fetch("DELETE", `/api/phone/devices/${encodeURIComponent(phoneId)}`);
+  }
+  /** 本次会话能用的手机 + 账号下的其他手机。 */
+  listForSession(sessionId) {
+    return this.client.json(
+      "GET",
+      `/api/sessions/${encodeURIComponent(sessionId)}/phones`
+    );
+  }
+  setEnabled(sessionId, phoneId, enabled) {
+    return this.client.json(
+      "PUT",
+      `/api/sessions/${encodeURIComponent(sessionId)}/phones/${encodeURIComponent(phoneId)}/enabled`,
+      { enabled }
+    );
+  }
+  health(sessionId, phoneId) {
+    return this.client.json(
+      "GET",
+      `/api/sessions/${encodeURIComponent(sessionId)}/phones/${encodeURIComponent(phoneId)}/health`
+    );
+  }
+  /**
+   * WHEP 信令：POST 一个 SDP offer，拿到 answer。
+   *
+   * 走 `textFromInit` 而不是 `json()`：SDP 是纯文本，`json()` 会强制序列化成
+   * JSON；也不能用裸 `fetch`，那会丢掉 bearer token。
+   */
+  async whep(sessionId, phoneId, offerSdp) {
+    return this.client.textFromInit(
+      `/api/sessions/${encodeURIComponent(sessionId)}/phones/${encodeURIComponent(phoneId)}/whep`,
+      {
+        method: "POST",
+        body: offerSdp,
+        headers: { "content-type": "application/sdp" }
+      }
+    );
+  }
+  /** 用户点「刷新画面」：让后台重新确认隧道服务并忘掉记住的 token。 */
+  async wake(sessionId, phoneId) {
+    await this.client.json(
+      "POST",
+      `/api/sessions/${encodeURIComponent(sessionId)}/phones/${encodeURIComponent(phoneId)}/wake`
+    );
+  }
+};
+
 // src/resources/models.ts
 var ModelsResource = class {
   constructor(client) {
@@ -5021,6 +5110,7 @@ function createInitialSessionState(sessionId) {
     mode: null,
     connection: "disconnected",
     errorMessage: null,
+    lastRun: null,
     askAnswers: {},
     agentLoops: {},
     activeCompaction: null,
@@ -6027,14 +6117,14 @@ var AgentSession = class _AgentSession {
   /** Prepare a durable text input without sending any network request. */
   prepareSend(content, options = {}) {
     if (!content.trim()) throw new Error("\u6D88\u606F\u4E0D\u80FD\u4E3A\u7A7A");
-    if (Object.keys(options).some((key) => !["mode", "model", "thinkingOverride", "reasoningLevel", "contextAttachments"].includes(key))) {
+    if (Object.keys(options).some((key) => !["mode", "model", "thinkingOverride", "reasoningLevel", "contextAttachments", "queueWhenRunning", "headless"].includes(key))) {
       throw new Error("\u53EF\u9760\u6587\u672C\u53D1\u9001\u4E0D\u652F\u6301\u8FD9\u4E9B\u53C2\u6570\uFF0C\u8BF7\u4F7F\u7528 send()");
     }
     const snapshot2 = JSON.parse(JSON.stringify(options));
     if (snapshot2.contextAttachments) snapshot2.contextAttachments = snapshotContextAttachments(snapshot2.contextAttachments);
     return { sessionId: this.sessionId, requestId: createClientRequestId(), content, options: snapshot2 };
   }
-  /** Durably enqueue an ordinary text input. Retries must reuse the saved request. */
+  /** Durably send a text input with its saved delivery intent. Retries must reuse the saved request. */
   async sendPrepared(request) {
     if (request.sessionId !== this.sessionId) throw new Error("\u53D1\u9001\u8BF7\u6C42\u4E0D\u5C5E\u4E8E\u5F53\u524D\u4F1A\u8BDD");
     try {
@@ -6046,6 +6136,8 @@ var AgentSession = class _AgentSession {
         prepared_options: {
           mode: request.options.mode,
           model: request.options.model,
+          ...request.options.headless !== void 0 ? { headless: request.options.headless } : {},
+          ...request.options.queueWhenRunning !== void 0 ? { queue_when_running: request.options.queueWhenRunning } : {},
           thinking_override: request.options.thinkingOverride,
           reasoning_level: request.options.reasoningLevel,
           ...request.options.contextAttachments ? { context_attachments: request.options.contextAttachments } : {}
@@ -6672,11 +6764,13 @@ var AgentSession = class _AgentSession {
     if (delivery.reload) {
       this.activeReplayPlaybackId = null;
       this.projectionBuilder.reset();
+      this.update((state) => ({ ...state, lastRun: null }));
       this.pendingTurnPatches.clear();
       this.epochReloadRequested += 1;
     }
     this.runEpochReload();
     for (const event of events) {
+      if (event.type === "chat:end") this.recordRunResult(event.payload);
       const playbackId = typeof event.payload.playback_id === "string" ? event.payload.playback_id : null;
       if (event.type === "chat:start") this.activeReplayPlaybackId = null;
       if (event.type === "replay:start" && playbackId) {
@@ -6776,6 +6870,14 @@ var AgentSession = class _AgentSession {
       isStreaming: true
     }));
   }
+  recordRunResult(payload) {
+    const runId = payload.chat_run_id;
+    if (payload.queued || typeof runId !== "string" || !runId) return;
+    this.update((state) => ({
+      ...state,
+      lastRun: { runId, status: payload.status ?? "completed", result: payload.result }
+    }));
+  }
   _handleChatEnd(payload = {}) {
     const status = payload.status ?? "completed";
     if (payload.queued === true) {
@@ -6785,6 +6887,7 @@ var AgentSession = class _AgentSession {
         return false;
       }
     }
+    this.recordRunResult(payload);
     this.pendingChatRequestId = null;
     this.noteLiveStatus();
     this.flushPatches();
@@ -8008,6 +8111,8 @@ var BladeClient = class _BladeClient {
   auth;
   headless;
   computers;
+  /** 用户接进来的手机：账号级清单、会话启用、画面信令。 */
+  phones;
   models;
   sessions;
   /** 按用户读取的插件目录与图标；没有会话时也能用。 */
@@ -8033,6 +8138,7 @@ var BladeClient = class _BladeClient {
     this.auth = new AuthResource(this);
     this.headless = new HeadlessResource(this);
     this.computers = new ComputersResource(this);
+    this.phones = new PhonesResource(this);
     this.models = new ModelsResource(this);
     this.sessions = new SessionsResource(this);
     this.plugins = new PluginsResource(this);
@@ -9072,6 +9178,9 @@ export {
   computerDaemonVersion,
   sortComputers,
   ComputersResource,
+  phoneState,
+  sortPhones,
+  phoneSerialLabel,
   ModelsResource,
   isLocalConnectorName,
   ConnectorsResource,
@@ -9131,4 +9240,4 @@ export {
   BladeClient,
   BladeApplicationClient
 };
-//# sourceMappingURL=chunk-XAXUPUD2.js.map
+//# sourceMappingURL=chunk-ME7O7RJC.js.map