@blade-hq/agent-client 2612.0.0-beta.13 → 2612.0.0-beta.14

package/README.md

@@ -788,3 +788,64 @@ Solution 的 `skill_tools_enabled`、是否为 `solution-app`、是否采用 `ni
 已应用的版本 ID 持久保留：当前版本相同请求幂等返回；被后续升级覆盖的版本返回 409，禁止延迟重试回滚配置。主动回退配置应提交新的版本 ID。
 
 分组会话复用现有 validate_group_session 约束，只允许通用助手；切换到业务 Solution 返回 422，普通运行设置可升级，分组绑定保留。
+
+
+### 匿名会话
+
+创建匿名会话需要已认证的客户端。每个匿名会话使用独立持久沙盒，不继承创建者的文件、记忆、个人环境变量或登录凭据。UUID 链接授予该会话的查看、聊天及文件访问权限，请妥善保管。当前不自动回收。
+
+```ts
+const account = new BladeClient({ baseUrl, token: userPat })
+const { session_id } = await account.sessions.createSessionWithRequest({ anonymous: true })
+const link = `${baseUrl}/anonymous/${session_id}`
+
+// 访客只有 UUID 即可连接，不需要账号令牌。
+const visitor = account.forAnonymousSession(session_id)
+const session = await visitor.sessions.connect(session_id)
+await session.send("你好")
+// 用完后释放；匿名客户端在最后一个会话引用释放时断开连接。
+session.dispose()
+```
+
+也可以使用 `new BladeClient({ baseUrl, anonymousSessionId: session_id })`，并把它交给 `BladeProvider` / `ChatView`。`account.sessions.create({ anonymous: true })` 会自动返回已连接的匿名 `AgentSession`；`ChatView createOptions={{ anonymous: true }}` 同样先认证创建，再使用会话凭证连接。账号客户端与匿名客户端分别持有连接，匿名客户端不能创建会话或访问用户级资源。匿名会话只支持 sandbox，不能绑定已有聊天分组、父会话或启用个人记忆。
+
+每个账号最多保留 6 个匿名会话；超过时创建返回 409。使用已认证账号客户端管理和删除旧会话：
+
+```ts
+const retained = await account.sessions.listAnonymousSessions()
+await account.sessions.deleteAnonymousSession(retained[0].id)
+```
+
+删除会永久移除该会话的沙盒、文件与历史，原链接失效。会话凭证不能调用管理接口。
+
+## 后端应用工具连接
+
+`client.connectToolProvider({ providerId, capability, tools })` 返回 `ToolProvider`。仅用于 Node 后端；BA 用户 token 由 BladeClient 提供。`await provider.ready()` 等待已鉴权注册，再将 `provider.url` 和 capability 配入会话 `mcp_sources`。providerId 与 capability 由应用持久化，重连复用。
+
+`ToolProviderOptions` 定义注册参数，`ProviderTool` 定义工具与处理函数，`ProviderToolResult` 定义调用结果。
+
+工具包含 `name`、`description`、`inputSchema` 与异步 `handler(arguments, { sessionId, signal })`；结果为 `content`、可选 `structuredContent` 与 `isError`。sessionId 来自 BA 已授权调用，应用还应校验它对应自身业务会话。AbortSignal 表示取消请求，不保证业务回滚。连接恢复不重放调用；业务动作应使用应用自己的幂等 ID。`provider.dispose()` 关闭连接。SDK 退出登录/更换后端也会关闭来源。
+
+连接使用 `/api/app-tools/connect`，HTTP 后端对应 ws，HTTPS 对应 wss；不要求应用暴露回调地址。需要支持此入口的 BA，未加入 SDK/Server 版本校验。
+
+### 可恢复的文本发送
+
+应用需要在回执丢失或进程重启后确认输入时，使用 SDK 准备请求，并在联网前保存：
+
+```ts
+const request = session.prepareSend("制作报告", { mode: "executing" })
+await savePendingRequest(request) // 应用自己的持久化存储
+const receipt = await session.sendPrepared(request)
+// unknown 时恢复保存的 request 再发送，或查询：
+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；旧服务的普通队列确认不算可靠请求回执。
+
+公开类型：`PreparedSend` 是可持久化的请求快照，`PreparedSendOptions` 是普通输入的执行参数，`DeliveryReceipt` 是接受或查询结果。
+
+匿名客户端不能读取 owner-only `configuration`，详情不返回 `env`。持链接者可以在共享沙盒执行代码，因此显式提供的环境变量会对该会话参与者可见；不要用它保存创建者的私人凭据。第一版不支持匿名 `app-dev`（软件工厂），也不提供同源 HTML 应用展示；文件可以下载查看。
+
+匿名子客户端保留 `commandTransport`，并为匿名命令额外提供第四个可选参数 `{ anonymousSessionId }`。中间件应使用本次调用的 `send()` 保持匿名凭证，或按该范围使用专属通道；不能把命令转发到另一个账号连接。普通命令仍提供原来的三个参数。

package/dist/blade-client.d.ts

@@ -1,3 +1,4 @@
+import { ToolProvider, type ToolProviderOptions } from "./tool-provider";
 import { type LoginOptions, type LoginResult, type TokenStorageMode } from "./auth-login";
 import { type BladeFetchInit, type HttpMethod } from "./rest";
 import { AuthResource } from "./resources/auth";
@@ -18,6 +19,8 @@ export interface BladeClientOptions {
      * 浏览器场景也可以不传，改用 client.auth.login() 弹窗登录。
      */
     token?: string | (() => string | null | undefined);
+    /** 只访问此匿名会话；UUID 链接本身是访问凭证，不使用账号令牌。 */
+    anonymousSessionId?: string;
     /**
      * Socket.IO 专用令牌。第一方应用可在 REST 继续使用 cookie 刷新的同时，
      * 把 cookie 换得的短期令牌只用于实时连接；不传时复用 token。
@@ -26,11 +29,15 @@ export interface BladeClientOptions {
     /** login() 取得的令牌存放位置，默认 "local"（localStorage，刷新页面不掉登录）。 */
     tokenStorage?: TokenStorageMode;
     /** Host-owned command transport; event subscriptions stay on the normal socket. */
-    commandTransport?: (event: string, payload: Record<string, unknown>, send: () => Promise<Record<string, unknown>>) => Promise<Record<string, unknown>>;
+    commandTransport?: (event: string, payload: Record<string, unknown>, send: () => Promise<Record<string, unknown>>, scope?: {
+        anonymousSessionId: string;
+    }) => Promise<Record<string, unknown>>;
     fetchImpl?: typeof fetch;
     onRefreshSuccess?: () => void | Promise<void>;
 }
 export declare class BladeClient {
+    private readonly anonymousClients;
+    private readonly toolProviders;
     private refreshPromise;
     private socketInstance;
     private readonly socketReplacementListeners;
@@ -53,6 +60,8 @@ export declare class BladeClient {
     /** 实时会话中枢：client.sessions.connect() 内部使用，一般不直接访问。 */
     readonly hub: SessionHub;
     constructor(options: BladeClientOptions);
+    /** Backend application tools, callable over an outbound WebSocket. */
+    connectToolProvider(options: ToolProviderOptions): ToolProvider;
     /**
      * 弹窗授权登录：用户在弹出的授权页点击"许可授权"后自动取得 PAT，
      * REST 与 Socket.IO 立即生效。只在浏览器可用。
@@ -79,6 +88,8 @@ export declare class BladeClient {
      * 安全约束：该令牌只应发往 baseUrl 同源接口，不要附加到第三方域名的请求上。
      */
     get token(): string | null;
+    /** 获取只访问指定匿名会话的客户端；创建仍由已认证的原客户端完成。 */
+    forAnonymousSession(sessionId: string): BladeClient;
     setBaseUrl(baseUrl: string): void;
     /** 底层 Socket.IO 实例因后端地址变化而被替换时通知高级集成层。 */
     onSocketReplaced(listener: () => void): () => void;

package/dist/{chunk-KPS6X6QX.js → chunk-KT5LY27X.js}

@@ -1,6 +1,219 @@
+// src/rest.ts
+var DOCS_URL = "https://blade-hq.github.io/public-skills/";
+var BladeApiError = class extends Error {
+  response;
+  status;
+  statusText;
+  constructor(response, message) {
+    super(message ?? `\u8BF7\u6C42\u5931\u8D25\uFF08${response.status} ${response.statusText}\uFF09`);
+    this.name = "BladeApiError";
+    this.response = response;
+    this.status = response.status;
+    this.statusText = response.statusText;
+  }
+};
+async function extractErrorDetail(response) {
+  try {
+    const cloned = response.clone();
+    const contentType = cloned.headers.get("content-type") ?? "";
+    if (contentType.includes("application/json")) {
+      const data = await cloned.json();
+      const detail = data?.detail;
+      if (typeof detail === "string" && detail.trim()) return detail;
+      if (Array.isArray(detail) && detail.length > 0) {
+        const first = detail[0];
+        if (first && typeof first.msg === "string") return first.msg;
+      }
+    } else {
+      const text = (await cloned.text()).trim();
+      if (text) return text;
+    }
+  } catch {
+  }
+  return void 0;
+}
+function decorateAuthError(error) {
+  if (!(error instanceof BladeApiError)) return error;
+  if (error.status === 401) {
+    error.message = `${error.message}\uFF08\u672A\u767B\u5F55\u6216\u51ED\u8BC1\u5DF2\u5931\u6548\u3002\u6D4F\u89C8\u5668\u573A\u666F\u8C03\u7528 client.auth.login() \u5F39\u7A97\u767B\u5F55\uFF0C\u81EA\u52A8\u5316\u573A\u666F\u5728 new BladeClient({ token }) \u4F20\u5165 PAT\u3002\u63A5\u5165\u6307\u5357\uFF1A${DOCS_URL}\uFF09`;
+  } else if (error.status === 403) {
+    error.message = `${error.message}\uFF08\u5F53\u524D\u8D26\u53F7\u65E0\u6743\u8BBF\u95EE\u8BE5\u8D44\u6E90\u3002\u63A5\u5165\u6307\u5357\uFF1A${DOCS_URL}\uFF09`;
+  }
+  return error;
+}
+function buildBackendUrl(baseUrl, path) {
+  const base = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+  return new URL(path.startsWith("/") ? path.slice(1) : path, base);
+}
+
+// src/tool-provider.ts
+var ToolProvider = class {
+  constructor(client, options, onDispose) {
+    this.client = client;
+    this.options = options;
+    this.onDispose = onDispose;
+    if (!/^[a-zA-Z0-9_-]{1,128}$/.test(options.providerId) || options.capability.length < 16 || options.capability.length > 4096) throw new Error("Invalid tool provider identity");
+    if (new Set(options.tools.map((t) => t.name)).size !== options.tools.length || options.tools.length > 256) throw new Error("Duplicate or excessive provider tools");
+    this.url = `blade-rpc://${options.providerId}`;
+    this.open();
+  }
+  client;
+  options;
+  onDispose;
+  url;
+  socket;
+  timer;
+  registrationTimer;
+  disposed = false;
+  registered = false;
+  attempts = 0;
+  calls = /* @__PURE__ */ new Map();
+  waiters = /* @__PURE__ */ new Set();
+  /** Resolves only after BA has authenticated and registered this connection. */
+  ready() {
+    if (this.disposed) return Promise.reject(new Error("Tool provider disposed"));
+    if (this.registered) return Promise.resolve();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.waiters.delete(waiter);
+        reject(new Error("Tool provider registration timed out"));
+      }, 25e3);
+      const waiter = { resolve: () => {
+        clearTimeout(timer);
+        resolve();
+      }, reject: (e) => {
+        clearTimeout(timer);
+        reject(e);
+      } };
+      this.waiters.add(waiter);
+    });
+  }
+  reconnect() {
+    if (this.disposed) return;
+    clearTimeout(this.timer);
+    this.reset();
+    this.open();
+  }
+  reset() {
+    clearTimeout(this.registrationTimer);
+    this.registered = false;
+    const socket = this.socket;
+    this.socket = void 0;
+    socket?.close();
+    for (const controller of this.calls.values()) controller.abort();
+    this.calls.clear();
+  }
+  fail(error) {
+    for (const waiter of this.waiters) waiter.reject(error);
+    this.waiters.clear();
+    try {
+      this.options.onError?.(error);
+    } catch {
+    }
+  }
+  open() {
+    if (this.disposed) return;
+    const endpoint = buildBackendUrl(this.client.options.baseUrl, "/api/app-tools/connect");
+    endpoint.protocol = endpoint.protocol === "https:" ? "wss:" : "ws:";
+    let socket;
+    try {
+      const token = this.client.token;
+      if (!token) throw new Error("Tool provider requires a token");
+      const encoded = btoa(Array.from(new TextEncoder().encode(token), (byte) => String.fromCharCode(byte)).join("")).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+      socket = new WebSocket(endpoint, ["blade-rpc", `blade-bearer.${encoded}`]);
+    } catch {
+      this.fail(new Error("Tool provider WebSocket unavailable"));
+      this.schedule();
+      return;
+    }
+    this.socket = socket;
+    this.registrationTimer = setTimeout(() => {
+      if (this.socket === socket) {
+        this.fail(new Error("Tool provider registration timed out"));
+        socket.close();
+      }
+    }, 15e3);
+    socket.addEventListener("open", () => {
+      if (this.socket !== socket) return;
+      socket.send(JSON.stringify({ jsonrpc: "2.0", id: "register", method: "provider/register", params: { providerId: this.options.providerId, capability: this.options.capability } }));
+    });
+    socket.addEventListener("message", (event) => {
+      if (this.socket !== socket || typeof event.data !== "string") return;
+      void this.receive(socket, event.data).catch(() => {
+        this.fail(new Error("Invalid application tool RPC message"));
+        socket.close();
+      });
+    });
+    socket.addEventListener("error", () => {
+      if (this.socket === socket) this.fail(new Error("Application tool connection failed"));
+    });
+    socket.addEventListener("close", () => {
+      if (this.socket !== socket) return;
+      this.reset();
+      this.fail(new Error("Application tool connection closed; unfinished calls will not be replayed"));
+      this.schedule();
+    });
+  }
+  schedule() {
+    if (this.disposed) return;
+    this.timer = setTimeout(() => this.open(), Math.min(1e4, 500 * 2 ** Math.min(this.attempts++, 5)));
+  }
+  async receive(socket, text) {
+    const message = JSON.parse(text);
+    if (message.jsonrpc !== "2.0") throw new Error("Invalid JSON-RPC envelope");
+    if (message.id === "register" && !message.method) {
+      clearTimeout(this.registrationTimer);
+      if (message.error || !message.result?.registered) {
+        this.fail(new Error(message.error?.message ?? "Tool provider registration rejected"));
+        socket.close();
+        return;
+      }
+      this.registered = true;
+      this.attempts = 0;
+      for (const waiter of this.waiters) waiter.resolve();
+      this.waiters.clear();
+      return;
+    }
+    if (!this.registered) throw new Error("Provider not registered");
+    if (message.method === "notifications/cancelled") {
+      this.calls.get(String(message.params?.requestId))?.abort();
+      return;
+    }
+    if (!message.id || typeof message.id !== "string" || this.calls.has(message.id)) throw new Error("Invalid RPC request ID");
+    const controller = new AbortController();
+    this.calls.set(message.id, controller);
+    let response = { jsonrpc: "2.0", id: message.id };
+    try {
+      if (message.method === "tools/list") {
+        response.result = { tools: this.options.tools.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })) };
+      } else if (message.method === "tools/call") {
+        const params = message.params;
+        const tool = this.options.tools.find((t) => t.name === params?.name);
+        if (!tool || typeof params?.sessionId !== "string" || !params.sessionId || !params.arguments || typeof params.arguments !== "object" || Array.isArray(params.arguments)) throw new Error("Invalid or unauthorized tool call");
+        response.result = await tool.handler(params.arguments, { sessionId: params.sessionId, signal: controller.signal });
+      } else {
+        response.error = { code: -32601, message: "Method not found" };
+      }
+    } catch {
+      response = { jsonrpc: "2.0", id: message.id, error: { code: -32e3, message: "Application tool execution failed" } };
+    } finally {
+      this.calls.delete(message.id);
+    }
+    if (this.socket === socket && socket.readyState === WebSocket.OPEN && !controller.signal.aborted) socket.send(JSON.stringify(response));
+  }
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    clearTimeout(this.timer);
+    this.reset();
+    this.fail(new Error("Tool provider disposed"));
+    this.onDispose();
+  }
+};
+
 // src/version.ts
 var SDK_NAME = "agent-client";
-var SDK_VERSION = true ? "2612.0.0-beta.13" : "1.1.1";
+var SDK_VERSION = true ? "2612.0.0-beta.14" : "1.1.1";
 
 // src/auth-login.ts
 function isAuthCallbackMessage(value) {
@@ -128,54 +341,6 @@ async function loginWithPopup(client, options = {}) {
   });
 }
 
-// src/rest.ts
-var DOCS_URL = "https://blade-hq.github.io/public-skills/";
-var BladeApiError = class extends Error {
-  response;
-  status;
-  statusText;
-  constructor(response, message) {
-    super(message ?? `\u8BF7\u6C42\u5931\u8D25\uFF08${response.status} ${response.statusText}\uFF09`);
-    this.name = "BladeApiError";
-    this.response = response;
-    this.status = response.status;
-    this.statusText = response.statusText;
-  }
-};
-async function extractErrorDetail(response) {
-  try {
-    const cloned = response.clone();
-    const contentType = cloned.headers.get("content-type") ?? "";
-    if (contentType.includes("application/json")) {
-      const data = await cloned.json();
-      const detail = data?.detail;
-      if (typeof detail === "string" && detail.trim()) return detail;
-      if (Array.isArray(detail) && detail.length > 0) {
-        const first = detail[0];
-        if (first && typeof first.msg === "string") return first.msg;
-      }
-    } else {
-      const text = (await cloned.text()).trim();
-      if (text) return text;
-    }
-  } catch {
-  }
-  return void 0;
-}
-function decorateAuthError(error) {
-  if (!(error instanceof BladeApiError)) return error;
-  if (error.status === 401) {
-    error.message = `${error.message}\uFF08\u672A\u767B\u5F55\u6216\u51ED\u8BC1\u5DF2\u5931\u6548\u3002\u6D4F\u89C8\u5668\u573A\u666F\u8C03\u7528 client.auth.login() \u5F39\u7A97\u767B\u5F55\uFF0C\u81EA\u52A8\u5316\u573A\u666F\u5728 new BladeClient({ token }) \u4F20\u5165 PAT\u3002\u63A5\u5165\u6307\u5357\uFF1A${DOCS_URL}\uFF09`;
-  } else if (error.status === 403) {
-    error.message = `${error.message}\uFF08\u5F53\u524D\u8D26\u53F7\u65E0\u6743\u8BBF\u95EE\u8BE5\u8D44\u6E90\u3002\u63A5\u5165\u6307\u5357\uFF1A${DOCS_URL}\uFF09`;
-  }
-  return error;
-}
-function buildBackendUrl(baseUrl, path) {
-  const base = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
-  return new URL(path.startsWith("/") ? path.slice(1) : path, base);
-}
-
 // src/resources/auth.ts
 var AuthResource = class {
   constructor(client) {
@@ -2241,6 +2406,7 @@ function projectHistory(entries) {
         loop_id: loopId,
         kind: "message",
         role,
+        client_request_id: stringOrNull(entry.client_request_id),
         status: message._error ? "failed" : message._interrupted ? "interrupted" : "completed",
         blocks,
         tool_calls: toolCalls,
@@ -3109,6 +3275,7 @@ var SessionInfo = type({
   created_at: "string",
   updated_at: "string",
   "shared?": "boolean",
+  "anonymous?": "boolean",
   "memory_enabled?": "boolean",
   "is_persistent?": "boolean",
   "initiator?": "'ui' | 'sdk' | 'unknown' | null",
@@ -3160,6 +3327,7 @@ function toCreateSessionPayload(request) {
   const solutionRef = request.solution_ref ?? externalSolutionRef(request.solution_id);
   return {
     intent: request.intent ?? "",
+    anonymous: request.anonymous,
     solution_id: solutionRef ? void 0 : request.solution_id,
     solution_ref: solutionRef,
     biz_role_id: request.biz_role_id ?? null,
@@ -3318,7 +3486,7 @@ var SessionsResource = class {
       return this.createDeclared(request);
     }
     const { session_id } = await this.createSessionWithRequest(request);
-    return this.connect(session_id);
+    return request.anonymous ? this.client.forAnonymousSession(session_id).sessions.connect(session_id) : this.connect(session_id);
   }
   async createDeclared(definition) {
     const { intent, solution, skills = [], config } = definition;
@@ -3621,6 +3789,12 @@ var SessionsResource = class {
       checkpoint_id: checkpointId
     });
   }
+  listAnonymousSessions() {
+    return this.client.json("GET", "/api/anonymous-sessions");
+  }
+  deleteAnonymousSession(sessionId) {
+    return this.client.json("DELETE", `/api/anonymous-sessions/${encodeURIComponent(sessionId)}`);
+  }
   deleteSession(sessionId, options) {
     const query = options?.deleteWorkspace ? "?delete_workspace=true" : "";
     return this.client.json("DELETE", `/api/sessions/${sessionId}${query}`);
@@ -4964,6 +5138,7 @@ function projectionToMessage(turn) {
     ...toolCalls ? { tool_calls: toolCalls } : {},
     loop_name: turn.loop_id,
     entry_id: turn.turn_id,
+    ...turn.client_request_id ? { client_request_id: turn.client_request_id } : {},
     status: turn.status,
     ...typeof turn.duration_ms === "number" ? { duration_ms: turn.duration_ms } : {},
     ...turn.started_at ? { timestamp: turn.started_at } : {},
@@ -5768,6 +5943,71 @@ var AgentSession = class _AgentSession {
     this.getAppContext = options.getContext;
     return attachment;
   }
+  /** 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"].includes(key))) {
+      throw new Error("\u53EF\u9760\u6587\u672C\u53D1\u9001\u4E0D\u652F\u6301\u8FD9\u4E9B\u53C2\u6570\uFF0C\u8BF7\u4F7F\u7528 send()");
+    }
+    return { sessionId: this.sessionId, requestId: createClientRequestId(), content, options: JSON.parse(JSON.stringify(options)) };
+  }
+  /** Durably enqueue an ordinary text input. 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 {
+      this.runtime.ensureConnected();
+      const response = await this.runtime.emitWithAck("chat:append", {
+        session_id: this.sessionId,
+        client_request_id: request.requestId,
+        message: request.content,
+        prepared_options: {
+          mode: request.options.mode,
+          model: request.options.model,
+          thinking_override: request.options.thinkingOverride,
+          reasoning_level: request.options.reasoningLevel
+        }
+      }, QUEUE_ACK_TIMEOUT_MS);
+      const result = parseQueueAck(response, this.sessionId);
+      if (result.snapshot) this.update((state) => withQueue(state, result.snapshot));
+      if (!result.ok) return {
+        requestId: request.requestId,
+        status: response?.status === "conflict" ? "rejected" : "unknown",
+        message: result.message ?? void 0
+      };
+      const delivery = response?.delivery;
+      if (!isRecord(delivery) || delivery.status !== "accepted") return { requestId: request.requestId, status: "unknown" };
+      return {
+        requestId: request.requestId,
+        status: "accepted",
+        itemId: typeof delivery.item_id === "string" ? delivery.item_id : void 0,
+        queueStatus: typeof delivery.queue_status === "string" ? delivery.queue_status : void 0,
+        executionId: typeof delivery.execution_id === "string" ? delivery.execution_id : null
+      };
+    } catch {
+      return { requestId: request.requestId, status: "unknown" };
+    }
+  }
+  /** Owner-authorized lookup; receipts remain until the session is deleted. */
+  async getDelivery(requestId) {
+    try {
+      this.runtime.ensureConnected();
+      const response = await this.runtime.emitWithAck("chat:queue:request", {
+        session_id: this.sessionId,
+        client_request_id: requestId
+      }, QUEUE_ACK_TIMEOUT_MS);
+      if (response?.status === "accepted") return {
+        requestId,
+        status: "accepted",
+        itemId: typeof response.item_id === "string" ? response.item_id : void 0,
+        queueStatus: typeof response.queue_status === "string" ? response.queue_status : void 0,
+        executionId: typeof response.execution_id === "string" ? response.execution_id : null
+      };
+      if (response?.status === "not_found") return { requestId, status: "not_found" };
+      return { requestId, status: "unknown", message: typeof response?.message === "string" ? response.message : void 0 };
+    } catch {
+      return { requestId, status: "unknown" };
+    }
+  }
   /** 发送一条消息。字符串或多模态内容均可。 */
   async send(content, options = {}) {
     this.runtime.ensureConnected();
@@ -7440,6 +7680,7 @@ var SessionHub = class {
     this.client.socket().emit("session:unsubscribe", { session_id: session.sessionId });
     if (this.statusWatchCounts.has(session.sessionId)) this.emitStatusSubscribe([session.sessionId]);
     else this.statusLogCursors.delete(session.sessionId);
+    if (this.client.options.anonymousSessionId && !this.needsConnection()) this.disconnect();
     return true;
   }
   statusCursor(sessionId) {
@@ -7761,12 +8002,14 @@ function createSocket(options) {
 
 // src/blade-client.ts
 var REFRESH_PATH = "/api/auth/refresh";
-var BladeClient = class {
+var BladeClient = class _BladeClient {
+  anonymousClients = /* @__PURE__ */ new Map();
+  toolProviders = /* @__PURE__ */ new Set();
   refreshPromise = null;
   socketInstance = null;
   socketReplacementListeners = /* @__PURE__ */ new Set();
   /** login() / setToken() 热挂载的令牌，优先级高于构造参数。 */
-  runtimeToken = null;
+  runtimeToken = void 0;
   options;
   auth;
   headless;
@@ -7784,6 +8027,9 @@ var BladeClient = class {
   /** 实时会话中枢：client.sessions.connect() 内部使用，一般不直接访问。 */
   hub;
   constructor(options) {
+    if (options.anonymousSessionId !== void 0 && !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(options.anonymousSessionId)) {
+      throw new Error("\u533F\u540D\u4F1A\u8BDD ID \u5FC5\u987B\u662F UUID v4");
+    }
     this.options = {
       ...options,
       baseUrl: normalizeBaseUrl(options.baseUrl)
@@ -7797,10 +8043,16 @@ var BladeClient = class {
     this.chatGroups = new ChatGroupsResource(this);
     this.siteVisits = new SiteVisitsResource(this);
     this.hub = new SessionHub(this);
-    if (this.options.token === void 0) {
-      this.runtimeToken = readStoredToken(this.options.baseUrl);
+    if (this.options.token === void 0 && !this.options.anonymousSessionId) {
+      this.runtimeToken = readStoredToken(this.options.baseUrl) ?? void 0;
     }
   }
+  /** Backend application tools, callable over an outbound WebSocket. */
+  connectToolProvider(options) {
+    const provider = new ToolProvider(this, options, () => this.toolProviders.delete(provider));
+    this.toolProviders.add(provider);
+    return provider;
+  }
   /**
    * 弹窗授权登录：用户在弹出的授权页点击"许可授权"后自动取得 PAT，
    * REST 与 Socket.IO 立即生效。只在浏览器可用。
@@ -7820,7 +8072,12 @@ var BladeClient = class {
     const previousToken = this.resolveToken();
     this.runtimeToken = token;
     const nextToken = this.resolveToken();
+    if (token === null) for (const provider of this.toolProviders) provider.dispose();
     if (previousToken !== nextToken) {
+      for (const provider of this.toolProviders) {
+        if (nextToken) provider.reconnect();
+        else provider.dispose();
+      }
       this.hub.disposeAll();
     }
     writeStoredToken(this.options.baseUrl, token, this.options.tokenStorage ?? "local");
@@ -7853,12 +8110,27 @@ var BladeClient = class {
   get token() {
     return this.resolveRestToken();
   }
+  /** 获取只访问指定匿名会话的客户端；创建仍由已认证的原客户端完成。 */
+  forAnonymousSession(sessionId) {
+    let client = this.anonymousClients.get(sessionId);
+    if (!client) {
+      client = new _BladeClient({ baseUrl: this.options.baseUrl, anonymousSessionId: sessionId, fetchImpl: this.options.fetchImpl, commandTransport: this.options.commandTransport });
+      this.anonymousClients.set(sessionId, client);
+    }
+    return client;
+  }
   setBaseUrl(baseUrl) {
     const nextBaseUrl = normalizeBaseUrl(baseUrl);
     if (nextBaseUrl === this.options.baseUrl) {
       return;
     }
+    for (const provider of this.toolProviders) provider.dispose();
     this.hub.disposeAll();
+    for (const client of this.anonymousClients.values()) {
+      client.hub.disposeAll();
+      client.hub.disconnect();
+    }
+    this.anonymousClients.clear();
     this.options.baseUrl = nextBaseUrl;
     if (this.socketInstance) {
       this.socketInstance.removeAllListeners();
@@ -7898,7 +8170,10 @@ var BladeClient = class {
         else resolve(ack ?? {});
       });
     });
-    return this.options.commandTransport?.(event, payload, send) ?? send();
+    const transport = this.options.commandTransport;
+    if (!transport) return send();
+    const handled = this.options.anonymousSessionId ? transport(event, payload, send, { anonymousSessionId: this.options.anonymousSessionId }) : transport(event, payload, send);
+    return handled ?? send();
   }
   async json(method, path, body) {
     const response = await this.fetch(method, path, {
@@ -8041,6 +8316,7 @@ var BladeClient = class {
     }
   }
   async tryRefresh() {
+    if (this.options.anonymousSessionId) return false;
     if (this.refreshPromise) {
       return this.refreshPromise;
     }
@@ -8075,14 +8351,16 @@ var BladeClient = class {
     return this.resolveRestToken();
   }
   resolveRestToken() {
+    if (this.options.anonymousSessionId) return `ba-anonymous-${this.options.anonymousSessionId}`;
     return this.resolveToken();
   }
   resolveSocketToken() {
-    if (this.runtimeToken) return this.runtimeToken;
+    if (this.options.anonymousSessionId) return `ba-anonymous-${this.options.anonymousSessionId}`;
+    if (this.runtimeToken !== void 0) return this.runtimeToken;
     return resolveTokenOption(this.options.socketToken ?? this.options.token);
   }
   resolveToken() {
-    if (this.runtimeToken) return this.runtimeToken;
+    if (this.runtimeToken !== void 0) return this.runtimeToken;
     return resolveTokenOption(this.options.token);
   }
   formDataWithUploadProgress(method, path, form, options, isRetry = false) {
@@ -8180,9 +8458,10 @@ function parseXhrHeaders(rawHeaders) {
 }
 
 export {
+  BladeApiError,
+  ToolProvider,
   SDK_NAME,
   SDK_VERSION,
-  BladeApiError,
   isRecord,
   normalizePluginRefs,
   normalizeTopicAssetRefs,
@@ -8264,4 +8543,4 @@ export {
   createSocket,
   BladeClient
 };
-//# sourceMappingURL=chunk-KPS6X6QX.js.map
+//# sourceMappingURL=chunk-KT5LY27X.js.map