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

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

@@ -892,6 +892,11 @@ function toolStatusFromResult(result) {
 }
 
 // src/shared/projection/builder.ts
+function isConversationTurn(turn) {
+  return (turn.role === "user" || turn.role === "assistant") && (turn.kind ?? "message") === "message" && !turn.blocks.some(
+    (block) => block.type === "mode_change" || block.type === "plan_status" || block.type === "ask_user_answer"
+  );
+}
 var ClientProjectionBuilder = class {
   activeTurns = /* @__PURE__ */ new Map();
   lastTurnIds = /* @__PURE__ */ new Map();
@@ -948,6 +953,8 @@ var ClientProjectionBuilder = class {
         return this.onAskUserAnswer(loopId, payload);
       case "user:message":
         return this.onUserMessage(loopId, payload);
+      case "session:post_chat_followup":
+        return this.onPostChatFollowup(payload);
     }
     if (event.type.startsWith("compaction:"))
       return this.onCompaction(event.type, loopId, payload);
@@ -1005,6 +1012,18 @@ var ClientProjectionBuilder = class {
       this.seq = maxSeq;
     }
   }
+  _seedTurns(turns) {
+    const latestTurns = /* @__PURE__ */ new Map();
+    for (const turn of turns) {
+      this.seedSequence(turn.sequence);
+      if (!isConversationTurn(turn)) continue;
+      const current = latestTurns.get(turn.loop_id);
+      if (!current || turn.sequence >= current.sequence) {
+        latestTurns.set(turn.loop_id, turn);
+      }
+    }
+    this.latestTurns = latestTurns;
+  }
   // --- Event handlers ---
   onMemoryInject(loopId, payload) {
     const refs = payload.memory_refs;
@@ -1193,6 +1212,27 @@ var ClientProjectionBuilder = class {
       usage: null,
       duration_ms: 0
     };
+    this.latestTurns.set("root", turn);
+    return [{ kind: "upsert", turn }];
+  }
+  onPostChatFollowup(payload) {
+    const assistantEntryId = String(payload.assistant_entry_id ?? "");
+    const latest = this.latestTurns.get("root");
+    if (!latest || latest.role !== "assistant" || latest.turn_id !== assistantEntryId) {
+      return null;
+    }
+    const suggestions = payload.suggestions;
+    const postChatFollowup = Array.isArray(suggestions) && suggestions.length === 3 && suggestions.every((value) => typeof value === "string") ? {
+      assistant_entry_id: assistantEntryId,
+      recaption: String(payload.recaption ?? ""),
+      suggestions
+    } : null;
+    if (!postChatFollowup) return null;
+    const turn = {
+      ...latest,
+      post_chat_followup: postChatFollowup
+    };
+    this.latestTurns.set("root", turn);
     return [{ kind: "upsert", turn }];
   }
   // --- Delta / streaming events ---
@@ -1545,11 +1585,24 @@ function projectHistory(entries) {
   const toolOwners = /* @__PURE__ */ new Map();
   const latestAssistantByLoop = /* @__PURE__ */ new Map();
   const pendingChildPauses = /* @__PURE__ */ new Map();
+  let latestRootMessage = null;
   let sequence = 0;
   for (const entry of entries) {
     const kind = String(entry.kind ?? "");
     const loopId = String(entry.loop_name ?? "root");
     const id = String(entry.id ?? `history-${sequence + 1}`);
+    if (kind === "post_chat_followup" && isRecord3(entry.data)) {
+      const assistantEntryId = String(entry.data.assistant_entry_id ?? "");
+      const suggestions = entry.data.suggestions;
+      if (latestRootMessage?.role === "assistant" && latestRootMessage.turn_id === assistantEntryId && Array.isArray(suggestions) && suggestions.length === 3 && suggestions.every((value) => typeof value === "string")) {
+        latestRootMessage.post_chat_followup = {
+          assistant_entry_id: assistantEntryId,
+          recaption: String(entry.data.recaption ?? ""),
+          suggestions
+        };
+      }
+      continue;
+    }
     if (kind === "message" && isRecord3(entry.message)) {
       const message = entry.message;
       const role = String(message.role ?? "");
@@ -1586,6 +1639,9 @@ function projectHistory(entries) {
         duration_ms: numberOrZero(message._duration_ms),
         started_at: typeof entry.timestamp === "string" ? entry.timestamp : void 0
       };
+      if (loopId === "root" && (role === "user" || role === "assistant")) {
+        latestRootMessage = turn;
+      }
       turns.push(turn);
       if (role === "assistant") latestAssistantByLoop.set(loopId, turn);
       for (const toolCall of toolCalls) toolOwners.set(toolCall.id, turn);
@@ -2106,6 +2162,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 +3016,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 +3044,7 @@ var AgentSession = class _AgentSession {
         listDir: async () => readonlyError(),
         countFiles: async () => readonlyError(),
         downloadFile: async () => readonlyError(),
+        attachAppCli: async () => readonlyError(),
         onDispose: () => void 0
       },
       "connected"
@@ -3016,18 +3099,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 +3175,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();
@@ -3169,11 +3293,14 @@ var AgentSession = class _AgentSession {
   _handleTurnEvents(events) {
     if (!events.length) return;
     const terminalChatEndStatus = extractTerminalChatEndStatus(events);
-    if (!terminalChatEndStatus) {
+    const followupOnly = events.every(
+      (event) => event.type === "session:post_chat_followup"
+    );
+    if (!terminalChatEndStatus && !followupOnly) {
       this.markRunningIfIdle();
     }
     if (this.state.turns.length) {
-      this.projectionBuilder.seedSequence(Math.max(...this.state.turns.map((t) => t.sequence)));
+      this.projectionBuilder._seedTurns(this.state.turns);
     }
     const updates = this.projectionBuilder.processBatch(events);
     for (const update of updates) {
@@ -3633,6 +3760,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 +3953,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.1.12-beta.5" : "1.1.1";
 
 // src/socket.ts
 function withSdkIdentity(auth) {