@blade-hq/agent-client 2612.0.0-beta.27 → 2612.0.0-beta.29

package/README.md

@@ -534,7 +534,7 @@ await chat.attachApp({
 })
 ```
 
-`getContext` 在每次 `send()` 前执行一次，适合路由、当前选中对象等轻量页面状态；它不做响应式依赖追踪。完整业务数据由开发者自己的 CLI 查询。`command` 是智能体在 Bash 中直接执行的命令名，不会套在 `blade` 命令下。
+`getContext` 在启动新一轮的 `send()` 前执行一次；运行中的引导和排队消息沿用当前运行的应用上下文，不重复采集。上下文适合承载路由、当前选中对象等轻量页面状态，不做响应式依赖追踪。完整业务数据由开发者自己的 CLI 查询。`command` 是智能体在 Bash 中直接执行的命令名，不会套在 `blade` 命令下。
 
 `runtime: "python"` 使用沙盒系统 Python 运行单文件脚本；`runtime: "executable"` 接受能在 Linux 沙盒运行的可执行文件。`source` 可传 `Blob`、`File` 或浏览器可读取的 URL。应用 CLI 安装成功后随会话工作区保留；运行时可通过 `BLADE_APP_CONTEXT_FILE` 读取同一份页面上下文 JSON。
 
@@ -861,3 +861,39 @@ await session.sendPrepared(request)
 ```
 
 每条消息最多 20 份资料，ID 不重复，每份正文最多 64000 个 Unicode 字符，整个资料 JSON 最多 256 KiB，超限拒绝。文件沿用指定会话的鉴权与路径解析，不接受外部 URL；仅有 `name` 的文件显示不可用。带资料的可靠消息作为独立一轮排队，不能走只传正文的「立即补充」。原生智能体目前不支持此通道。
+
+## 后端应用共享连接
+
+PA 等后端服务使用 `BladeApplicationClient`，全部用户共享两条按需建立的 WebSocket。
+每个用户仍使用自己的 bearer token；REST 请求和会话权限按用户隔离。
+
+```ts
+const application = new BladeApplicationClient({ baseUrl: "http://ba:8020" })
+const client = application.forUser(userId, { token: userToken })
+const session = await client.hub.connect(sessionId)
+// 服务退出时释放全部通道
+application.dispose()
+```
+
+`forUser` 缓存同一用户的客户端；凭据更新调用该客户端的 `setToken`，退出调用 `logoutToken`。
+`connectionCount` 返回当前已建立的物理连接数。重连恢复订阅和工具注册，业务命令与工具动作不重放。
+`ApplicationUserTransport` 是该客户端注入 `BladeClientOptions.applicationTransport` 的传输契约。
+普通 `BladeClient` 继续使用原有 Socket.IO 和工具连接。
+
+
+### 应用提供的文本 Context
+
+`PreparedSendOptions.contextAttachments` 中的资料可声明 `update_format: "snapshot" | "diff"`。
+声明后 `id` 是当前会话内稳定的来源标识，`content` 是完整文本状态（推荐 Markdown），
+runner 将其作为独立 Context 投影：内容不变不再注入，`diff` 由 Projector 对完整状态计算，
+可见基线丢失时补完整快照。调用者不要传预先计算的 patch。
+不声明该字段时仍是原有的消息级附件快照。业务处理成功游标由应用自行维护，Context 注入不表示业务已提交。
+
+```ts
+session.send("请处理新增工作", {
+  contextAttachments: [
+    { id: "work-directory", label: "工作目录", content: directoryMarkdown, update_format: "diff" },
+    { id: "pending-work", label: "新增记录", content: pendingMarkdown, update_format: "snapshot" },
+  ],
+})
+```

package/dist/application-client.d.ts

@@ -0,0 +1,19 @@
+import { BladeClient, type BladeClientOptions } from "./blade-client";
+import type { TypedSocket } from "./socket";
+/** Transport selected by BladeApplicationClient; ordinary clients use Socket.IO. */
+export interface ApplicationUserTransport {
+    socket(): TypedSocket;
+    provider(): WebSocket;
+    invalidate(): void;
+}
+/** Backend application: all users share two lazy WebSockets; REST keeps user credentials. */
+export declare class BladeApplicationClient {
+    private readonly options;
+    private readonly channels;
+    private readonly clients;
+    private readonly applicationId;
+    constructor(options: Pick<BladeClientOptions, "baseUrl" | "fetchImpl">);
+    forUser(userId: string, options: Omit<BladeClientOptions, "baseUrl" | "applicationTransport" | "anonymousSessionId">): BladeClient;
+    get connectionCount(): number;
+    dispose(): void;
+}

package/dist/blade-client.d.ts

@@ -1,3 +1,4 @@
+import type { ApplicationUserTransport } from "./application-client";
 import { SandboxResource } from "./resources/sandbox";
 import { ToolProvider, type ToolProviderOptions } from "./tool-provider";
 import { type LoginOptions, type LoginResult, type TokenStorageMode } from "./auth-login";
@@ -33,6 +34,8 @@ export interface BladeClientOptions {
     commandTransport?: (event: string, payload: Record<string, unknown>, send: () => Promise<Record<string, unknown>>, scope?: {
         anonymousSessionId: string;
     }) => Promise<Record<string, unknown>>;
+    /** Backend shared application transport, installed by BladeApplicationClient. */
+    applicationTransport?: ApplicationUserTransport;
     fetchImpl?: typeof fetch;
     onRefreshSuccess?: () => void | Promise<void>;
 }
@@ -43,7 +46,6 @@ export declare class BladeClient {
     private cookieLogoutPending;
     private socketInstance;
     private readonly socketReplacementListeners;
-    /** login() / setToken() 热挂载的令牌，优先级高于构造参数。 */
     private runtimeToken;
     readonly options: BladeClientOptions;
     readonly sandbox: SandboxResource;
@@ -116,13 +118,6 @@ export declare class BladeClient {
     private isSameBackendUrl;
     private shouldRefreshFor401;
     private hasExplicitBearerToken;
-    /**
-     * 等一次令牌刷新，但调用方中止请求时不再等下去。
-     *
-     * 刷新本身是共享的（`refreshPromise`，别的请求也在等它），这里只是让这次已被取消的
-     * 请求尽早结束——否则它会一直挂在调用方（定位）的串行队列里，用户改选的新目标要等到
-     * 刷新结束才轮得到。
-     */
     private tryRefreshUnlessAborted;
     private tryRefresh;
     private resolveTokenForUrl;