@blade-hq/agent-client 1.1.12-beta.4 → 1.2.0-beta.1

package/README.md

@@ -196,6 +196,26 @@ chat.dispose()                                   // 彻底释放（什么时候
 
 ### 页面协作：让智能体和你的页面互动
 
+**页面状态与业务后端 → 智能体**：
+
+```ts
+await chat.attachApp({
+  cli: {
+    command: "library",
+    runtime: "python",
+    source: new URL("./agent/library_cli.py", location.href),
+  },
+  getContext: () => ({
+    route: location.pathname,
+    selectedBookId: bookStore.getState().selectedBookId,
+  }),
+})
+```
+
+`getContext` 在每次 `send()` 前执行一次，适合路由、当前选中对象等轻量页面状态；它不做响应式依赖追踪。完整业务数据由开发者自己的 CLI 查询。`command` 是智能体在 Bash 中直接执行的命令名，不会套在 `blade` 命令下。
+
+`runtime: "python"` 使用沙盒系统 Python 运行单文件脚本；`runtime: "executable"` 接受能在 Linux 沙盒运行的可执行文件。`source` 可传 `Blob`、`File` 或浏览器可读取的 URL。应用 CLI 安装成功后随会话工作区保留；运行时可通过 `BLADE_APP_CONTEXT_FILE` 读取同一份页面上下文 JSON。
+
 **智能体 → 页面**（例如智能体让地图高亮某个点）：
 
 ```ts
@@ -365,7 +385,7 @@ function Message({ message }: { message: ChatMessage }) {
 - **SDK 身份**：`SDK_NAME`、`SDK_VERSION`
 - **声明式会话**：`SessionDefinition`、`SolutionDefinition`、`SkillDefinition`、`SessionConfig`、`TextFile`、`SessionSetupError`、`SessionSetupStage`
 - **模型目录**：`ModelsResource`、`ModelCatalog`、`ModelOption`
-- **会话资源（REST）**：`SessionsResource`、`CreateSessionRequest`、`PaginatedSessionsResult`、`SessionHistory`、`SessionContextStats`、`ShareLinkResult`、`FileEntry`、`UploadFileEntry`、`UploadFilesOptions`、`SessionProfile`、`SessionDetail`、`SessionInfo`、`SessionStatus`、`SessionPortMapping`、`ModeId`、`TemplateId`、`PrimarySkillSnapshot`、`PrimarySkillParallelMode`
+- **会话资源（REST）**：`SessionsResource`、`CreateSessionRequest`、`AppCliDefinition`、`AppCliAttachment`、`AttachAppOptions`、`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`

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { BladeApiError } from "./rest";
 export type { LoginOptions, LoginResult, TokenStorageMode } from "./auth-login";
 export { SDK_NAME, SDK_VERSION } from "./version";
 export { AgentSession } from "./session/agent-session";
-export type { SendOptions } from "./session/agent-session";
+export type { AttachAppOptions, SendOptions } from "./session/agent-session";
 export { SessionHub } from "./session/hub";
 export type { AgentSessionEvents, AgentSessionEventName } from "./session/events";
 export { SessionSetupError } from "./session/definition";
@@ -21,7 +21,7 @@ export type { HeadlessResource } from "./resources/headless";
 export { ModelsResource } from "./resources/models";
 export type { ModelCatalog, ModelOption } from "./resources/models";
 export type { SessionsResource } from "./resources/sessions";
-export type { CreateSessionRequest, FileEntry, PaginatedSessionsResult, SessionContextStats, SessionHistory, ShareLinkResult, UploadFileEntry, UploadFilesOptions, } from "./resources/sessions";
+export type { CreateSessionRequest, AppCliAttachment, AppCliDefinition, 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";

package/dist/index.js

@@ -2106,6 +2106,30 @@ var SessionsResource = class {
     );
     return response.json();
   }
+  /** 把应用自己的业务 CLI 安装到会话沙盒，并保留开发者声明的命令名。 */
+  async attachAppCli(sessionId, definition) {
+    let source;
+    if (definition.source instanceof Blob) {
+      source = definition.source;
+    } else {
+      const response2 = await globalThis.fetch(definition.source.toString());
+      if (!response2.ok) {
+        throw new Error(`\u8BFB\u53D6\u5E94\u7528 CLI \u5931\u8D25\uFF1AHTTP ${response2.status}`);
+      }
+      source = await response2.blob();
+    }
+    const filename = definition.filename ?? (typeof File !== "undefined" && definition.source instanceof File ? definition.source.name : void 0) ?? (definition.runtime === "python" ? "app-cli.py" : "app-cli");
+    const form = new FormData();
+    form.append("command", definition.command);
+    form.append("runtime", definition.runtime);
+    form.append("file", source, filename);
+    const response = await this.client.formData(
+      "POST",
+      `/api/sessions/${sessionId}/app-cli`,
+      form
+    );
+    return response.json();
+  }
   async deleteFile(sessionId, filePath) {
     await this.client.json("DELETE", `/api/sessions/${sessionId}/files/${encodeURIComponent(filePath)}`);
   }
@@ -2936,6 +2960,8 @@ var AgentSession = class _AgentSession {
   pendingReplayMode;
   recentChatEndAt = 0;
   disposed = false;
+  getAppContext = null;
+  sendPending = false;
   deliveredCommandKeys = /* @__PURE__ */ new Set();
   deliveredToolPreviews = /* @__PURE__ */ new Map();
   oomNotifiedKeys = /* @__PURE__ */ new Set();
@@ -2962,6 +2988,7 @@ var AgentSession = class _AgentSession {
         listDir: async () => readonlyError(),
         countFiles: async () => readonlyError(),
         downloadFile: async () => readonlyError(),
+        attachAppCli: async () => readonlyError(),
         onDispose: () => void 0
       },
       "connected"
@@ -3016,18 +3043,58 @@ var AgentSession = class _AgentSession {
     return this.commands.onCommand(action, handler);
   }
   // ---------------------------------------------------------------- 动作
+  /**
+   * 声明当前应用提供的页面上下文和业务 CLI。
+   *
+   * CLI 安装成功后才保存 getContext；之后每次 send 前恰好读取一次。
+   */
+  async attachApp(options) {
+    const attachment = options.cli ? await this.runtime.attachAppCli(this.sessionId, options.cli) : null;
+    this.getAppContext = options.getContext;
+    return attachment;
+  }
   /** 发送一条消息。字符串或多模态内容均可。 */
   async send(content, options = {}) {
     this.runtime.ensureConnected();
-    if (this.state.isStreaming) {
+    if (this.state.isStreaming || this.sendPending) {
       this.update((s) => addErrorMessage(s, "\u5F53\u524D\u56DE\u590D\u5C1A\u672A\u7ED3\u675F\uFF0C\u8BF7\u7A0D\u540E\u518D\u53D1\u9001\u3002"));
       return;
     }
+    this.sendPending = true;
+    try {
+      await this.sendUnlocked(content, options);
+    } finally {
+      this.sendPending = false;
+    }
+  }
+  async sendUnlocked(content, options) {
     await this.ensureIdleBeforeSend();
     if (this.state.isStreaming) {
       this.update((s) => addErrorMessage(s, "\u5F53\u524D\u56DE\u590D\u5C1A\u672A\u7ED3\u675F\uFF0C\u8BF7\u7A0D\u540E\u518D\u53D1\u9001\u3002"));
       return;
     }
+    let appContext;
+    if (this.getAppContext) {
+      try {
+        const rawContext = await this.getAppContext();
+        if (!isRecord5(rawContext)) {
+          throw new Error("getContext \u5FC5\u987B\u8FD4\u56DE JSON \u5BF9\u8C61");
+        }
+        const serialized = JSON.stringify(rawContext);
+        if (serialized === void 0) {
+          throw new Error("getContext \u5FC5\u987B\u8FD4\u56DE\u53EF\u5E8F\u5217\u5316\u7684 JSON \u5BF9\u8C61");
+        }
+        const normalized = JSON.parse(serialized);
+        if (!isRecord5(normalized)) {
+          throw new Error("getContext \u5FC5\u987B\u8FD4\u56DE JSON \u5BF9\u8C61");
+        }
+        appContext = normalized;
+      } catch (error) {
+        const message = error instanceof Error && error.message ? `\u8BFB\u53D6\u5E94\u7528\u4E0A\u4E0B\u6587\u5931\u8D25\uFF1A${error.message}` : "\u8BFB\u53D6\u5E94\u7528\u4E0A\u4E0B\u6587\u5931\u8D25\uFF0C\u6D88\u606F\u672A\u53D1\u9001";
+        this.update((s) => addErrorMessage(s, message));
+        return;
+      }
+    }
     const askUserAnswer = options.askUserAnswer;
     if (!(askUserAnswer && typeof askUserAnswer.tool_call_id === "string")) {
       this.update((s) => addUserMessage(s, content));
@@ -3052,7 +3119,8 @@ var AgentSession = class _AgentSession {
       model: options.model,
       thinking_override: options.thinkingOverride,
       whatif: options.whatif,
-      replay_decision: options.replayDecision
+      replay_decision: options.replayDecision,
+      app_context: appContext
     };
     try {
       await this.ensureJoined();
@@ -3633,6 +3701,7 @@ var SessionHub = class {
       listDir: (sessionId, dirPath) => this.client.sessions.listDir(sessionId, dirPath),
       countFiles: (sessionId, dirPath) => this.client.sessions.countFiles(sessionId, dirPath),
       downloadFile: (sessionId, filePath, downloadName) => this.client.sessions.downloadFile(sessionId, filePath, downloadName),
+      attachAppCli: (sessionId, definition) => this.client.sessions.attachAppCli(sessionId, definition),
       onDispose: (session) => {
         if (this.sessions.get(session.sessionId) === session) {
           this.sessions.delete(session.sessionId);
@@ -3825,7 +3894,7 @@ function resolveAuthToken(options) {
 
 // src/version.ts
 var SDK_NAME = "agent-client";
-var SDK_VERSION = true ? "1.1.12-beta.4" : "1.1.1";
+var SDK_VERSION = true ? "1.2.0-beta.1" : "1.1.1";
 
 // src/socket.ts
 function withSdkIdentity(auth) {