@blade-hq/agent-client 1.1.1

package/README.md

@@ -0,0 +1,351 @@
+# @blade-hq/agent-client
+
+Blade Agent 的框架无关客户端。浏览器和 Node.js 都能用；用 Vue、Svelte 或自建 UI 的团队直接用这个包，React 团队一般用上层的 `@blade-hq/agent-react`。
+
+它做三件事：
+
+1. **实时会话**（`AgentSession`）：把 Socket.IO 协议、历史加载、流式合流、断线重连全部封装掉，你只面对"状态快照 + 动作 + 事件"。
+2. **登录**：`client.auth.login()` 弹窗授权，用户点一下"许可授权"就拿到访问令牌，不用手工复制粘贴。
+3. **REST**：只类型化会话相关的少数接口（`client.sessions.*`）。长尾接口 SDK 不封装，对照 Swagger 用原生 `fetch` + `client.token` 自行调用。
+
+```bash
+npm install @blade-hq/agent-client
+```
+
+## 快速开始
+
+```html
+<button id="login">登录 Blade</button>
+```
+
+```ts
+import { BladeClient, getTextContent } from "@blade-hq/agent-client"
+
+const client = new BladeClient({ baseUrl: "https://blade.example.com" })
+
+// 登录必须由用户点击触发：浏览器会拦截非用户操作弹出的窗口
+document.querySelector("#login")!.addEventListener("click", async () => {
+  await client.auth.login()
+
+  const chat = await client.sessions.create()
+  chat.subscribe(() => {
+    const { messages, isStreaming } = chat.getState()
+    // 换成你自己的渲染。content 可能是字符串也可能是内容块数组（多模态消息），
+    // 用 getTextContent 两种都能处理，不要自己写 typeof 判断
+    console.log(messages.map((m) => getTextContent(m.content)), isStreaming)
+  })
+  await chat.send("帮我分析一下这份数据")
+})
+```
+
+Node.js / 自动化脚本用 token（PAT 在 Blade 设置页创建）：
+
+```ts
+const client = new BladeClient({
+  baseUrl: "https://blade.example.com",
+  token: process.env.BLADE_TOKEN,
+})
+```
+
+## BladeClient
+
+### 构造
+
+```ts
+new BladeClient({
+  baseUrl: "https://blade.example.com", // 后端地址；同域部署可传 ""
+  token: "sk-blade-xxx",                // 可选：PAT。不传则用 cookie 或 login()
+  tokenStorage: "local",                // 可选：login() 的令牌存哪（"local" 默认 / "memory"）
+})
+```
+
+> **`baseUrl` 填哪个地址？** 必须是 Blade Agent 后端的地址（形如 `http://<主机>:8020`），只要域名和端口、不带路径。
+> 注意别填成你平时打开的 Blade OS 地址（同主机的 `:80`）—— 那是另一套接口，SDK 连不上。
+
+### 登录相关
+
+```ts
+await client.auth.login()      // 弹窗授权登录，成功后 REST 与实时连接立即生效
+client.auth.logoutToken()      // 清除 login() 存的令牌
+client.setToken("sk-blade-x")  // 手动热挂载令牌（null 表示清除）
+client.hasToken()              // 是否持有令牌
+client.token                   // 当前令牌（长尾接口自行调用时填进 Authorization 头）
+await client.auth.getMe()      // 当前用户信息（未登录时抛 401）
+await client.auth.getProviders() // 服务端支持的登录方式
+```
+
+`login()` 失败时的错误都带中文原因：弹窗被拦截、窗口被关闭、超时。
+
+## 会话：client.sessions
+
+### 实时对话（推荐入口）
+
+```ts
+// 连接已有会话
+const chat = await client.sessions.connect("会话id")
+
+// 或：创建新会话并直接连接
+const newChat = await client.sessions.create()
+const configured = await client.sessions.create({ intent: "数据分析", model: "gpt-4o" })
+```
+
+两者都返回 [`AgentSession`](#agentsession)。
+
+> **`sessionId` 从哪来？** 三种，按需选：
+> 1. **不用管它** —— 首次接入最省事：`client.sessions.create()` 直接建一个新会话，用不着 ID。React 的 `<ChatView />` 不传 `sessionId` 也一样。
+> 2. **自己建、自己存**：`const { session_id } = await client.sessions.createSessionWithRequest({ intent: "季度报表分析" })`。把返回的 `session_id`（后端是蛇形命名）存进你的数据库或 URL，用户下次进来传给 `connect(sessionId)`（前端参数是驼峰），就能接着上次的对话。
+> 3. **列出用户已有的**：`await client.sessions.listSessions()`，让用户自己挑。
+
+### 会话管理（REST）
+
+```ts
+await client.sessions.listSessions()                  // 会话列表
+await client.sessions.getSession(id)                  // 会话详情
+await client.sessions.updateSession(id, { intent: "新标题" })
+await client.sessions.deleteSession(id)
+await client.sessions.getSessionTurns(id)             // 历史消息（投影格式，与实时流同构）
+```
+
+### 工作区文件
+
+```ts
+await client.sessions.listDir(id, "")                        // 列目录
+await client.sessions.uploadFiles(id, "", fileInput.files)   // 上传（支持进度回调）
+await client.sessions.writeFile(id, "notes.md", "# 内容")
+await client.sessions.deleteFile(id, "notes.md")
+client.buildAuthedUrl(`/api/sessions/${id}/files/report.pdf`) // 带鉴权的下载/预览地址
+```
+
+## AgentSession
+
+一个会话的实时状态机。**状态归属实例**：同一页面建多个会话互不干扰。
+
+### 状态
+
+```ts
+chat.getState()
+// {
+//   messages,        聊天消息列表（直接渲染）
+//   isStreaming,     是否正在回复
+//   status,          会话状态：created / running / completed / failed /
+//                    interrupted / waiting_for_input（未加载时为 null）
+//   mode,            "planning" | "executing" | null
+//   connection,      连接状态："connected" | "connecting" | "reconnecting" | "disconnected"
+//   errorMessage,    最近一次运行错误
+//   turns, askAnswers, agentLoops, activeCompaction   进阶字段
+// }
+
+const unsubscribe = chat.subscribe(() => rerender(chat.getState()))
+```
+
+快照不可变：状态一变就换新对象引用，可直接接 React `useSyncExternalStore` 或 Vue `shallowRef`（见 public-skills 的 Vue 接入文档）。
+
+### 动作
+
+```ts
+await chat.send("你好")                          // 发消息（字符串或多模态内容）
+await chat.send("换个方案", { mode: "planning" }) // 指定模式/模型等选项
+chat.append("补充：预算不超过 5 万")              // 智能体运行中追加说明
+await chat.stop()                                // 停止当前回复
+await chat.compact()                             // 手动压缩上下文
+chat.dispose()                                   // 彻底释放（什么时候该调见下方说明）
+```
+
+> **什么时候调 `dispose()`？** 组件卸载时**不要**调 —— 会话实例由 client 缓存着，用户切走再切回来能直接复用，历史消息不用重新加载。只有这两种情况才调：
+> 1. 用户明确关闭或删除了这个会话，之后不会再回来；
+> 2. 页面长期开着并且会不断创建一次性会话（比如批量任务面板），需要主动回收。
+
+### 页面协作：让智能体和你的页面互动
+
+**智能体 → 页面**（例如智能体让地图高亮某个点）：
+
+```ts
+chat.onCommand("map.highlight", (payload) => {
+  // payload 类型是 unknown（内容由技能作者决定），用前自行断言或校验
+  const { points } = payload as { points: Array<{ lng: number; lat: number }> }
+  map.highlight(points)
+})
+```
+
+`"map.highlight"` 这个 action 字符串从哪来？——它是**技能作者**在工具实现的返回值里写的。技能侧（Python 工具）长这样：
+
+```python
+def highlight_points(points):
+    return {
+        "ok": True,
+        "message": f"已定位 {len(points)} 个点位",
+        "_meta": {"bridge": {"action": "map.highlight", "payload": {"points": points}}},
+    }
+```
+
+后端会把 `_meta.bridge` 从对话历史里剥离（LLM 看不到它），单独送到前端。所以 action 是**技能作者和页面开发者之间约定的暗号**，SDK 不限制取值。在 `onCommand` 注册之前到达的指令会被缓冲，注册时立刻补投，不存在"注册晚了漏消息"。
+
+**页面 → 智能体**（例如用户在地图上选了个点）：
+
+```ts
+chat.attach("选中点位", { lng: 116.4, lat: 39.9 }) // 变成聊天输入框里的附件
+chat.insertText("请分析这个区域")                   // 往输入框追加文字（不发送）
+await chat.send("这里适合开店吗？")                 // 直接发消息
+```
+
+`attach` / `insertText` 需要有渲染层（ChatView 或你自己监听 `attachRequested` / `insertTextRequested` 事件）才有可见效果；纯脚本场景直接用 `send`。
+
+### 语义事件（进阶）
+
+大多数场景用不到——React 用 hook、指令用 `onCommand`。需要精确监听时：
+
+```ts
+chat.on("toolCall",   (e) => console.log("调用工具", e.toolCall.name))
+chat.on("toolResult", (e) => console.log("工具结果", e.toolCall.result))
+chat.on("message",    (e) => console.log("新消息", e.message))
+chat.on("chatEnd",    (e) => console.log("回复结束", e.status))
+chat.on("error",      (e) => console.error(e.message))
+```
+
+完整事件表见 `AgentSessionEvents` 类型定义（含 `modeChange` / `workspaceChanged` / `artifact` / `notification` / `backgroundTask` / `taskListUpdated` / `rewind` / `replayMismatch` 等）。`on()` 返回取消函数；handler 抛异常只告警，不影响会话。
+
+## iframe 嵌入形态：connectEmbedded
+
+如果你不是嵌组件，而是把 **Blade 的聊天页面整个用 iframe 嵌进自己系统**，宿主页面用 `connectEmbedded` 拿到同构的协作 API：
+
+```ts
+import { connectEmbedded } from "@blade-hq/agent-client"
+
+const chat = connectEmbedded({
+  iframe: document.querySelector<HTMLIFrameElement>("#blade")!,
+  allowedOrigins: ["https://blade.example.com"], // 必填：Blade 页面的来源，防伪造
+})
+chat.onCommand("map.highlight", (payload) => {
+  const { points } = payload as { points: Array<{ lng: number; lat: number }> }
+  map.highlight(points)
+})
+chat.attach("选中点位", { lng: 116.4, lat: 39.9 })
+chat.send("这里适合开店吗？")
+chat.dispose() // 页面卸载时
+```
+
+同页组件形态和 iframe 形态的协作 API 完全一致，业务代码可以原样复用。
+
+## 长尾 REST：用原生 fetch
+
+SDK 只类型化会话、登录、headless 三类接口。其余几百个后端接口一律不封装——
+对照 Swagger（`<后端地址>/docs`）用原生 `fetch` 调用，把 `client.token` 填进
+`Authorization` 头即可：
+
+```ts
+const resp = await fetch(`${baseUrl}/api/memories/search?q=xxx`, {
+  headers: { Authorization: `Bearer ${client.token}` },
+})
+const memories = await resp.json()
+```
+
+不做通用包装是有意的：包装唯一的增值是自动带令牌，代价却是要补齐
+PATCH / query / FormData / AbortSignal 等完整 HTTP 语义（否则不够用），
+而且 SDK 隐式携带凭据存在误把令牌发往第三方域的风险。显式暴露 `client.token`
+让责任边界回到标准 `fetch`，两个问题都不存在。
+
+> **安全约束**：`client.token` 只应发往 `baseUrl` 同源的接口。不要把它附加到
+> 第三方域名的请求上——那等于把用户的访问凭据交给别人。
+
+## headless：一次性问答
+
+```ts
+// 无头模式：直接拿结构化结果，不需要自己处理流式事件
+await client.headless.run("统计上月订单量", { schema })
+```
+
+## 版本握手
+
+本 SDK 与 Server 是配套的：`@blade-hq/agent-client` 2.x 需要 Server 1.1.1 及以上。
+
+SDK 在首次建立会话前会查询 `GET /api/version`。版本不匹配时抛出
+`VersionMismatchError`，报错文案里写清楚双方版本号和该升级哪一端，
+而不是让你对着一个莫名其妙的运行时异常发呆：
+
+```ts
+import { VersionMismatchError } from "@blade-hq/agent-client"
+
+try {
+  const chat = await client.sessions.create()
+} catch (error) {
+  if (error instanceof VersionMismatchError) {
+    console.error(error.message) // 含双方版本号与建议动作
+  }
+}
+```
+
+旧接入方的选择：继续用 `@blade-hq/agent-kit` 1.1.0 对接 1.1.0 及以下的 Server，
+或升级到本包对接 1.1.1 及以上的 Server。**不支持交叉组合**，两个方向都会被明确拦截。
+
+开发环境不受影响：预发布版本号（如 `1.1.1-dev.3`）一律放行。
+
+## 自己渲染消息
+
+`message.content` 有两种形态：纯文字时是字符串；带图片、文件的消息则是内容块数组。别自己写 `typeof` 判断，用这几个函数，两种形态都能处理：
+
+```ts
+import {
+  getTextContent,
+  getImageParts,
+  getFileParts,
+  groupMessagesByLoop,
+  contentPreview,
+} from "@blade-hq/agent-client"
+
+// 文字部分
+getTextContent(message.content)        // "帮我看看这张图"
+
+// 图片部分：返回 [{ type: "image_url", image_url: { url } }, ...]
+getImageParts(message.content).map((part) => part.image_url.url)
+
+// 文件部分
+getFileParts(message.content)
+
+// 其他
+groupMessagesByLoop(messages)          // 按主/子智能体分组（智能体会派生子智能体干活）
+contentPreview(message.content, 80)    // 截断预览
+```
+
+一个完整的渲染示例：
+
+```tsx
+function Message({ message }: { message: ChatMessage }) {
+  const text = getTextContent(message.content)
+  const images = getImageParts(message.content)
+  return (
+    <div>
+      {text && <p>{text}</p>}
+      {images.map((part) => (
+        <img key={part.image_url.url} src={part.image_url.url} alt="" />
+      ))}
+    </div>
+  )
+}
+```
+
+## 常见问题
+
+| 现象 | 原因与解法 |
+| --- | --- |
+| 401，提示未登录 | 浏览器调 `client.auth.login()`；脚本检查 token 是否有效 |
+| login() 报"弹窗被拦截" | 浏览器设置里允许该站点弹窗，或改用 PAT |
+| login() 报 403 来源未允许 | 让管理员把你的页面 origin 加进后端 `BLADE_SDK_AUTH_ALLOWED_ORIGINS` |
+| socket 一直 connecting | 检查 baseUrl 是否可达、跨域时后端是否允许你的 origin |
+| VersionMismatchError | SDK 与 Server 版本不配套，按报错提示升级其中一端，见「版本握手」 |
+| onCommand 收不到指令 | 确认技能工具返回值里写了 `_meta.bridge`，action 拼写与注册一致 |
+
+更多接入教程（Vue 完整示例、GIS 协作闭环、AI 助手接入指南）见 [public-skills 文档站](https://github.com/blade-hq/public-skills)。
+
+## 附录：公开类型索引
+
+完整签名见 [public-api.md](./public-api.md)（由 `scripts/public-api-report.mjs` 生成并在 CI 校验）。
+
+- **客户端与登录**：`BladeClientOptions`、`LoginOptions`、`LoginResult`、`TokenStorageMode`、`UploadProgress`、`BladeApiError`、`AuthResource`、`ProvidersResponse`、`UserInfo`
+- **版本握手**：`ServerVersionInfo`、`SDK_NAME`、`SDK_VERSION`、`MIN_SERVER_VERSION`
+- **会话资源（REST）**：`SessionsResource`、`CreateSessionRequest`、`PaginatedSessionsResult`、`SessionHistory`、`SessionContextStats`、`ShareLinkResult`、`FileEntry`、`UploadFileEntry`、`UploadFilesOptions`、`SessionProfile`、`SessionDetail`、`SessionInfo`、`SessionStatus`、`SessionPortMapping`、`ModeId`、`TemplateId`、`PrimarySkillSnapshot`、`PrimarySkillParallelMode`
+- **会话状态机**：`SessionHub`、`SessionState`、`SendOptions`、`ConnectionStatus`、`AskUserAnswerData`、`AgentLoopInfo`、`ActiveCompactionState`、`createInitialSessionState`、`AgentSessionEventName`
+- **页面协作**：`EmbeddedChat`、`EmbeddedChatOptions`、`CommandHandler`、`CommandEnvelope`、`InboundAction`、`InboundEnvelope`、`isCommandEnvelope`、`isInboundEnvelope`
+- **消息与投影协议**：`MessageContent`、`MessageContentPart`、`TextContentPart`、`ImageUrlContentPart`、`FileContentPart`、`ToolCallInfo`、`ToolBridgeContent`、`CompactionInfo`、`MemoryRefInfo`、`ArchivedFileInfo`、`ArchivedToolCallInfo`、`TurnProjection`、`ContentBlock`、`PatchEnvelope`、`MemoryRef`、`buildMessageContent`、`normalizeMessageContent`、`isHiddenInternalMessage`、`transformSlashCommand`、`extractTextAttachments`、`ParsedTextAttachment`、`ParsedTextContext`
+- **Solution / 任务协议**：`Solution`、`SolutionAppField`、`SolutionAppState`、`SolutionAppUiConfig`、`SolutionRef`、`ExistingSolutionRef`、`PreparedSolution`、`PreparedSolutionAsset`、`LayoutType`、`BizRole`、`TaskStatus`、`BackgroundTask`
+- **Headless**：`HeadlessResource`、`RunOptions`、`RunResult`、`RunTrace`
+- **低层通道（apps/web 等高级集成）**：`createSocket`、`CreateSocketOptions`、`TypedSocket`、`AsrAudioPayload`、`ClientProjectionBuilder`、`RawEvent`

package/dist/auth-login.d.ts

@@ -0,0 +1,29 @@
+import type { BladeClient } from "./blade-client";
+/**
+ * 弹窗授权登录，与 Chrome 扩展共用同一套后端授权内核（见 server/routes/sdk_auth.py）：
+ *
+ * 1. 弹窗打开 `GET /api/auth/sdk/authorize?client_origin=<本页 origin>&state=<随机值>`
+ * 2. 用户点击「许可授权」→ 回调页把 `{ type: "blade-agent:sdk-auth", state, code }`
+ *    postMessage 定向发回本页（code 一次性、5 分钟有效）
+ * 3. SDK 用 `POST /api/auth/sdk/token`（code + state + client_origin）换取 PAT，
+ *    存储并热挂载（REST 与 Socket.IO 同时生效）
+ */
+export interface LoginOptions {
+    /** 弹窗尺寸，默认 480x640。 */
+    width?: number;
+    height?: number;
+    /** 超时毫秒数，默认 5 分钟（与后端授权码有效期一致）。 */
+    timeoutMs?: number;
+}
+export interface LoginResult {
+    token: string;
+    user?: {
+        id?: string;
+        username?: string;
+        display_name?: string;
+    };
+}
+export type TokenStorageMode = "local" | "memory";
+export declare function readStoredToken(baseUrl: string): string | null;
+export declare function writeStoredToken(baseUrl: string, token: string | null, mode: TokenStorageMode): void;
+export declare function loginWithPopup(client: BladeClient, options?: LoginOptions): Promise<LoginResult>;

package/dist/auth.d.ts

@@ -0,0 +1,8 @@
+export interface AuthOptions {
+    token?: string | (() => string | null | undefined);
+}
+export declare function buildAuthHeaders(options: AuthOptions): Record<string, string>;
+export declare function buildSocketAuth(options: AuthOptions): {
+    token: string;
+} | undefined;
+export declare function resolveAuthToken(options: AuthOptions): string | null;

package/dist/blade-client.d.ts

@@ -0,0 +1,113 @@
+import { type LoginOptions, type LoginResult, type TokenStorageMode } from "./auth-login";
+import { type BladeFetchInit, type HttpMethod } from "./rest";
+import { AuthResource } from "./resources/auth";
+import { HeadlessResource } from "./resources/headless";
+import { SessionsResource } from "./resources/sessions";
+import { SessionHub } from "./session/hub";
+import { type TypedSocket } from "./socket";
+export interface BladeClientOptions {
+    /** 后端地址，如 "https://blade.example.com"。浏览器里传空字符串则使用当前域名。 */
+    baseUrl: string;
+    /**
+     * 访问令牌（PAT）。不传时按 cookie 会话模式工作；
+     * 浏览器场景也可以不传，改用 client.auth.login() 弹窗登录。
+     */
+    token?: string | (() => string | null | undefined);
+    /**
+     * Socket.IO 专用令牌。第一方应用可在 REST 继续使用 cookie 刷新的同时，
+     * 把 cookie 换得的短期令牌只用于实时连接；不传时复用 token。
+     */
+    socketToken?: string | (() => string | null | undefined);
+    /** login() 取得的令牌存放位置，默认 "local"（localStorage，刷新页面不掉登录）。 */
+    tokenStorage?: TokenStorageMode;
+    fetchImpl?: typeof fetch;
+    onRefreshSuccess?: () => void | Promise<void>;
+}
+export declare class BladeClient {
+    private refreshPromise;
+    private socketInstance;
+    private readonly socketReplacementListeners;
+    /** login() / setToken() 热挂载的令牌，优先级高于构造参数。 */
+    private runtimeToken;
+    readonly options: BladeClientOptions;
+    readonly auth: AuthResource;
+    readonly headless: HeadlessResource;
+    readonly sessions: SessionsResource;
+    /** 实时会话中枢：client.sessions.connect() 内部使用，一般不直接访问。 */
+    readonly hub: SessionHub;
+    /** 版本握手结果缓存：每个 client 实例只探测一次，不逐请求重复。 */
+    private versionCheck;
+    constructor(options: BladeClientOptions);
+    /**
+     * 弹窗授权登录：用户在弹出的授权页点击"许可授权"后自动取得 PAT，
+     * REST 与 Socket.IO 立即生效。只在浏览器可用。
+     */
+    login(options?: LoginOptions): Promise<LoginResult>;
+    /** 退出登录：清除 login() 存储的令牌并断开实时连接。 */
+    logoutToken(): void;
+    /** 热挂载访问令牌（null 表示清除）。会重建 Socket.IO 连接以携带新凭证。 */
+    setToken(token: string | null): void;
+    /** 当前是否持有访问令牌（不代表令牌一定有效）。 */
+    hasToken(): boolean;
+    /**
+     * 当前访问令牌（PAT），未登录时为 null。
+     *
+     * SDK 只封装会话相关接口；其余长尾接口对照后端 Swagger（`<baseUrl>/docs`）
+     * 用原生 fetch 自行调用，把本令牌填入 Authorization 头即可：
+     *
+     * ```ts
+     * fetch(`${baseUrl}/api/memories/search?q=xxx`, {
+     *   headers: { Authorization: `Bearer ${client.token}` },
+     * })
+     * ```
+     *
+     * 安全约束：该令牌只应发往 baseUrl 同源接口，不要附加到第三方域名的请求上。
+     */
+    get token(): string | null;
+    /**
+     * 版本握手：首次连接前查询 Server 版本，不匹配则抛 VersionMismatchError。
+     * 结果缓存在实例上，失败的探测不缓存以便重试。
+     */
+    ensureVersionCompatible(): Promise<void>;
+    /**
+     * 读取 /api/version。接口存在但 404/响应不合法 → null（按旧 Server 处理）；
+     * 网络层不可达（后端没启动、端口不通、代理配错）→ 抛连接错误。
+     * 两者必须区分：把「后端没起」误报成「版本不匹配，请改用 agent-kit」
+     * 会把开发者引向完全错误的排查方向。
+     */
+    private fetchServerVersion;
+    setBaseUrl(baseUrl: string): void;
+    /** 底层 Socket.IO 实例因后端地址变化而被替换时通知高级集成层。 */
+    onSocketReplaced(listener: () => void): () => void;
+    socket(): TypedSocket;
+    json<T>(method: HttpMethod, path: string, body?: unknown): Promise<T>;
+    jsonFromInit<T>(path: string, init?: RequestInit): Promise<T>;
+    text(method: HttpMethod, path: string): Promise<string>;
+    textFromInit(path: string, init?: RequestInit): Promise<string>;
+    responseFromInit(path: string, init?: RequestInit): Promise<Response>;
+    blob(method: HttpMethod, path: string): Promise<Blob>;
+    formData(method: HttpMethod, path: string, form: FormData, options?: {
+        expectOk?: boolean;
+        onUploadProgress?: (progress: UploadProgress) => void;
+    }): Promise<Response>;
+    fetch(method: HttpMethod, path: string, init?: BladeFetchInit, isRetry?: boolean): Promise<Response>;
+    buildAuthedUrl(path: string): string;
+    private buildHeaders;
+    private buildUrl;
+    private baseUrlWithTrailingSlash;
+    private toBaseRelativePath;
+    private isSameBackendUrl;
+    private shouldRefreshFor401;
+    private hasExplicitBearerToken;
+    private tryRefresh;
+    private resolveTokenForUrl;
+    private resolveRestToken;
+    private resolveSocketToken;
+    private resolveToken;
+    private formDataWithUploadProgress;
+}
+export interface UploadProgress {
+    loaded: number;
+    total?: number;
+    percent?: number;
+}

package/dist/commands/embedded.d.ts

@@ -0,0 +1,32 @@
+import { type CommandHandler } from "./registry";
+/**
+ * iframe 嵌入形态的宿主端协作对象：当你把 Blade 的聊天页面用 iframe 嵌进
+ * 自己的系统时，用它与 iframe 里的智能体互通——API 与同页嵌入的
+ * AgentSession 完全一致（onCommand / attach / insertText / send）。
+ *
+ * action 的来源与同页形态相同：技能作者在工具返回值 JSON 的 `_meta.bridge`
+ * 字段里写 `{ action, payload }`，Blade 页面检测到自己处于 iframe 中时会把
+ * 它 postMessage 给宿主页面（见 docs/specs/260417-embed-bridge）。
+ */
+export interface EmbeddedChatOptions {
+    /** 嵌入 Blade 页面的 iframe 元素。不传则监听来自任意子窗口的消息。 */
+    iframe?: HTMLIFrameElement;
+    /**
+     * 允许接收消息的来源（Blade 页面的 origin，如 "https://blade.example.com"）。
+     * 必填：不校验来源会让任意第三方页面伪造智能体指令。
+     */
+    allowedOrigins: string[];
+}
+export interface EmbeddedChat {
+    /** 监听智能体下发的指令（注册前到达的会缓冲补投）。返回取消函数。 */
+    onCommand(action: string, handler: CommandHandler): () => void;
+    /** 把业务数据作为附件放进 iframe 里的聊天输入框。 */
+    attach(label: string, data: unknown): void;
+    /** 往 iframe 里的聊天输入框追加文字。 */
+    insertText(text: string): void;
+    /** 直接代用户发送一条消息。 */
+    send(text: string): void;
+    /** 停止监听并释放资源。 */
+    dispose(): void;
+}
+export declare function connectEmbedded(options: EmbeddedChatOptions): EmbeddedChat;

package/dist/commands/protocol.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 页面协作协议（对应后端 `_meta.bridge` 通道，见 docs/specs/260417-embed-bridge）。
+ *
+ * ## action 从哪里来
+ *
+ * 智能体 → 宿主方向的每一条指令，都源自**技能作者写的工具代码**：工具返回值
+ * JSON 里带 `_meta.bridge: { action, payload }`，后端在持久化前把它剥离成独立
+ * 事件送达前端（LLM 的对话历史里读不到它）。因此：
+ *
+ * - action 字符串（如 "map.highlight"）是**技能作者与宿主页面开发者之间的业务
+ *   契约**，LLM 不参与协议、SDK 不做枚举校验；
+ * - 宿主页面用 `session.onCommand("map.highlight", fn)` 消费；
+ * - 未注册 handler 的 action 会进入有限缓冲等待注册，超限后丢弃并 console 告警。
+ *
+ * 宿主 → 智能体方向只有三个白名单动作：attach（附件入输入框）/ insertText
+ * （追加输入文本）/ send（直接发消息），对应协议层的 addContext / appendInput /
+ * sendMessage。
+ */
+export interface CommandEnvelope {
+    __bladeBridge: true;
+    direction: "agent-to-host";
+    action: string;
+    payload: unknown;
+    meta: {
+        sessionId: string;
+        toolCallId?: string;
+        timestamp: number;
+    };
+}
+export type InboundAction = "addContext" | "appendInput" | "sendMessage";
+export interface InboundEnvelope {
+    __bladeBridge: true;
+    direction: "host-to-agent";
+    action: InboundAction;
+    payload: unknown;
+}
+export declare function isCommandEnvelope(value: unknown): value is CommandEnvelope;
+export declare function isInboundEnvelope(value: unknown): value is InboundEnvelope;

package/dist/commands/registry.d.ts

@@ -0,0 +1,21 @@
+export type CommandHandler = (payload: unknown, meta: {
+    toolCallId?: string;
+}) => void;
+/**
+ * 指令注册表：onCommand 事后注册 + 注册前缓冲补投。
+ *
+ * action 的来源见 ./protocol.ts 顶部说明——它由技能作者在工具返回值的
+ * `_meta.bridge` 字段里写入，是技能作者与宿主页面开发者的业务契约。
+ * 缓冲的意义：指令可能在页面还没来得及调用 onCommand 时就到达（比如
+ * 历史回放），先存起来、注册时立刻补投，消除"注册晚了漏事件"的坑。
+ */
+export declare class CommandRegistry {
+    private handlers;
+    private buffered;
+    onCommand(action: string, handler: CommandHandler): () => void;
+    dispatch(action: string, payload: unknown, meta?: {
+        toolCallId?: string;
+    }): void;
+    private invoke;
+    clear(): void;
+}

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+export { BladeClient } from "./blade-client";
+export type { BladeClientOptions, UploadProgress } from "./blade-client";
+export { BladeApiError } from "./rest";
+export type { LoginOptions, LoginResult, TokenStorageMode } from "./auth-login";
+export { VersionMismatchError, SDK_NAME, SDK_VERSION, MIN_SERVER_VERSION } from "./version";
+export type { ServerVersionInfo } from "./version";
+export { AgentSession } from "./session/agent-session";
+export type { SendOptions } from "./session/agent-session";
+export { SessionHub } from "./session/hub";
+export type { AgentSessionEvents, AgentSessionEventName } from "./session/events";
+export { createInitialSessionState } from "./session/state";
+export type { AskUserAnswerData, AgentLoopInfo, ActiveCompactionState, ConnectionStatus, SessionState, } from "./session/state";
+export { connectEmbedded } from "./commands/embedded";
+export type { EmbeddedChat, EmbeddedChatOptions } from "./commands/embedded";
+export type { CommandHandler } from "./commands/registry";
+export type { CommandEnvelope, InboundAction, InboundEnvelope } from "./commands/protocol";
+export { isCommandEnvelope, isInboundEnvelope } from "./commands/protocol";
+export type { AuthResource, ProvidersResponse, UserInfo } from "./resources/auth";
+export type { HeadlessResource } from "./resources/headless";
+export type { SessionsResource } from "./resources/sessions";
+export type { CreateSessionRequest, FileEntry, PaginatedSessionsResult, SessionContextStats, SessionHistory, ShareLinkResult, UploadFileEntry, UploadFilesOptions, } from "./resources/sessions";
+export type { ArchivedFileInfo, ArchivedToolCallInfo, ChatMessage, CompactionInfo, FileContentPart, ImageUrlContentPart, MemoryRefInfo, MessageContent, MessageContentPart, TextContentPart, ToolBridgeContent, ToolCallInfo, } from "./schemas/message";
+export { buildMessageContent, contentPreview, extractTextAttachments, getFileParts, getImageParts, getTextContent, groupMessagesByLoop, isHiddenInternalMessage, normalizeMessageContent, transformSlashCommand, } from "./schemas/message-utils";
+export type { ParsedTextAttachment, ParsedTextContext } from "./schemas/message-utils";
+export type { ContentBlock, MemoryRef, PatchEnvelope, TurnProjection } from "./schemas/projection";
+export { SessionInfo, SessionStatus } from "./schemas/session";
+export type { ModeId, PrimarySkillParallelMode, PrimarySkillSnapshot, SessionDetail, SessionPortMapping, TemplateId, } from "./schemas/session";
+export { LayoutType } from "./schemas/solution";
+export type { BizRole, Solution, SolutionAppField, SolutionAppState, SolutionAppUiConfig, } from "./schemas/solution";
+export { Task, TaskStatus } from "./schemas/task";
+export type { BackgroundTask } from "./schemas/background";
+export { ClientProjectionBuilder } from "./shared/projection";
+export type { RawEvent } from "./shared/projection";
+export { createSocket } from "./socket";
+export type { CreateSocketOptions, TypedSocket } from "./socket";
+export type { AsrAudioPayload } from "./types/socket-events";
+export type * from "./types/sdk-profile";