@blade-hq/agent-client 1.2.1-alpha.2 → 1.2.1-beta.1

package/README.md

@@ -182,7 +182,7 @@ const unsubscribe = chat.subscribe(() => rerender(chat.getState()))
 ### 动作
 
 ```ts
-await chat.send("你好")                          // 发消息（字符串或多模态内容）
+const accepted = await chat.send("你好")         // 服务端接受后为 true；拒绝时为 false
 await chat.send("换个方案", { mode: "planning" }) // 指定模式/模型等选项
 chat.append("补充：预算不超过 5 万")              // 智能体运行中追加说明
 await chat.stop()                                // 停止当前回复
@@ -385,10 +385,10 @@ function Message({ message }: { message: ChatMessage }) {
 - **SDK 身份**：`SDK_NAME`、`SDK_VERSION`
 - **声明式会话**：`SessionDefinition`、`SolutionDefinition`、`SkillDefinition`、`SessionConfig`、`TextFile`、`SessionSetupError`、`SessionSetupStage`
 - **模型目录**：`ModelsResource`、`ModelCatalog`、`ModelOption`
-- **会话资源（REST）**：`SessionsResource`、`CreateSessionRequest`、`AppCliDefinition`、`AppCliAttachment`、`AttachAppOptions`、`PaginatedSessionsResult`、`SessionHistory`、`SessionContextStats`、`ShareLinkResult`、`FileEntry`、`UploadFileEntry`、`UploadFilesOptions`、`SessionProfile`、`SessionDetail`、`SessionInfo`、`SessionStatus`、`SessionPortMapping`、`ModeId`、`TemplateId`、`PrimarySkillSnapshot`、`PrimarySkillParallelMode`
+- **会话资源（REST）**：`SessionsResource`、`CreateSessionRequest`、`ImportSessionOptions`、`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`
-- **Solution / 任务协议**：`Solution`、`SolutionAppField`、`SolutionAppState`、`SolutionAppUiConfig`、`SolutionRef`、`ExistingSolutionRef`、`PreparedSolution`、`PreparedSolutionAsset`、`LayoutType`、`BizRole`、`TaskStatus`、`BackgroundTask`
+- **Solution / 任务协议**：`Solution`、`SolutionAppField`、`SolutionAppState`、`SolutionAppUiConfig`、`SolutionRef`、`PublishedSolutionRef`、`ExistingSolutionRef`、`PreparedSolution`、`PreparedSolutionAsset`、`LayoutType`、`BizRole`、`TaskStatus`、`BackgroundTask`、`BackgroundTaskStopResult`
 - **Headless**：`HeadlessResource`、`RunOptions`、`RunResult`、`RunTrace`
 - **低层通道（apps/web 等高级集成）**：`createSocket`、`CreateSocketOptions`、`TypedSocket`、`AsrAudioPayload`、`ClientProjectionBuilder`、`RawEvent`

package/dist/index.d.ts

@@ -21,17 +21,17 @@ 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, AppCliAttachment, AppCliDefinition, FileEntry, PaginatedSessionsResult, SessionContextStats, SessionHistory, ShareLinkResult, UploadFileEntry, UploadFilesOptions, } from "./resources/sessions";
+export type { CreateSessionRequest, AppCliAttachment, AppCliDefinition, FileEntry, ImportSessionOptions, 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 type { ModeId, PrimarySkillParallelMode, PrimarySkillSnapshot, SessionDetail, SessionPortMapping, PublishedSolutionRef, 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 type { BackgroundTask, BackgroundTaskStopResult } from "./schemas/background";
 export { ClientProjectionBuilder } from "./shared/projection";
 export type { RawEvent } from "./shared/projection";
 export { createSocket } from "./socket";

package/dist/index.js

@@ -319,13 +319,22 @@ var HeadlessResource = class {
       socket.on("chat:end", onChatEnd);
       socket.on("system:error", onSystemError);
       socket.emit("session:subscribe", { session_id, event_format: "raw" });
-      socket.emit("chat:send", {
-        session_id,
-        message: prompt,
-        headless: true,
-        output_schema: options.schema ?? null,
-        model: options.model ?? null
-      });
+      socket.emit(
+        "chat:send",
+        {
+          session_id,
+          message: prompt,
+          headless: true,
+          output_schema: options.schema ?? null,
+          model: options.model ?? null
+        },
+        (response) => {
+          if (response.status === "accepted") return;
+          rejectAfterChatEnd(
+            new HeadlessError(response.message ?? "headless run was not accepted", response)
+          );
+        }
+      );
     });
   }
 };
@@ -1841,10 +1850,12 @@ function findLatestAssistant(turns, loopId) {
 
 // src/resources/sessions.ts
 function toCreateSessionPayload(request) {
+  const solutionRef = request.solution_ref ?? externalSolutionRef(request.solution_id);
   return {
     intent: request.intent ?? "",
     template_id: request.template_id,
-    solution_id: request.solution_id,
+    solution_id: solutionRef ? void 0 : request.solution_id,
+    solution_ref: solutionRef,
     biz_role_id: request.biz_role_id ?? null,
     model: request.model ?? null,
     enable_thinking: request.enable_thinking ?? null,
@@ -1853,11 +1864,33 @@ function toCreateSessionPayload(request) {
     env: request.env,
     disable_tools: request.disable_tools ?? null,
     session_solution_asset_id: request.session_solution_asset_id ?? null,
+    solution_snapshot_session_id: request.solution_snapshot_session_id ?? null,
     compaction_ratio: request.compaction_ratio ?? null,
     ...request.runtime_type ? { runtime_type: request.runtime_type } : {},
     ...request.daemon_id ? { daemon_id: request.daemon_id } : {}
   };
 }
+var builtinSolutionIds = /* @__PURE__ */ new Set([
+  "app-dev",
+  "general_chat",
+  "multica",
+  "night_build",
+  "skill_editor",
+  "smart_bid",
+  "solution_generate"
+]);
+function externalSolutionRef(solutionId) {
+  if (!solutionId) return void 0;
+  const normalized = solutionId === "default" ? "general_chat" : solutionId.trim();
+  if (builtinSolutionIds.has(normalized)) {
+    return { source: "builtin", name: normalized };
+  }
+  const parts = normalized.split("/");
+  if (parts.length === 2 && parts.every(Boolean)) {
+    return { source: "hub", org: parts[0], name: parts[1] };
+  }
+  return void 0;
+}
 var SessionsResource = class {
   constructor(client) {
     this.client = client;
@@ -1965,13 +1998,18 @@ var SessionsResource = class {
     offset,
     template_id_prefix,
     solution_id,
+    solution_registry_id,
     q
   }) {
     const searchParams = new URLSearchParams();
     searchParams.set("limit", String(limit));
     searchParams.set("offset", String(offset));
     if (template_id_prefix) searchParams.set("template_id_prefix", template_id_prefix);
-    if (solution_id) searchParams.set("solution_id", solution_id);
+    if (solution_registry_id) {
+      searchParams.set("solution_registry_id", solution_registry_id);
+    } else if (solution_id) {
+      searchParams.set("solution_id", solution_id);
+    }
     const trimmedQuery = q?.trim();
     if (trimmedQuery) searchParams.set("q", trimmedQuery);
     return this.client.json("GET", `/api/sessions?${searchParams.toString()}`);
@@ -2227,11 +2265,23 @@ var SessionsResource = class {
     const res = await this.client.formData("POST", "/api/sessions/preview-import", form);
     return res.json();
   }
-  async importSession(file, name, solutionId) {
+  async importSession(file, name, solutionOverride) {
     const form = new FormData();
     form.append("file", file);
     if (name) form.append("name", name);
-    if (solutionId) form.append("solution_id", solutionId);
+    if (typeof solutionOverride === "string") {
+      if (solutionOverride) form.append("solution_id", solutionOverride);
+    } else if (solutionOverride) {
+      if (solutionOverride.solution_ref) {
+        form.append("solution_ref", JSON.stringify(solutionOverride.solution_ref));
+      }
+      if (solutionOverride.solution_snapshot_session_id) {
+        form.append(
+          "solution_snapshot_session_id",
+          solutionOverride.solution_snapshot_session_id
+        );
+      }
+    }
     const res = await this.client.formData("POST", "/api/sessions/import", form);
     return res.json();
   }
@@ -2996,6 +3046,11 @@ function extractTerminalChatEndStatus(events) {
   }
   return null;
 }
+function hasChatRunEvent(events) {
+  return events.some(
+    (event) => event.type !== "session:post_chat_followup" && !event.type.startsWith("compaction:")
+  );
+}
 function isUiMetaLike(value) {
   return isRecord5(value) && ("resourceHTML" in value || "resourceUri" in value || "resourceURI" in value);
 }
@@ -3018,6 +3073,7 @@ var AgentSession = class _AgentSession {
   disposed = false;
   getAppContext = null;
   sendPending = false;
+  manualCompactionPending = false;
   deliveredCommandKeys = /* @__PURE__ */ new Set();
   deliveredToolPreviews = /* @__PURE__ */ new Map();
   oomNotifiedKeys = /* @__PURE__ */ new Set();
@@ -3112,22 +3168,26 @@ var AgentSession = class _AgentSession {
   /** 发送一条消息。字符串或多模态内容均可。 */
   async send(content, options = {}) {
     this.runtime.ensureConnected();
-    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;
+    if (this.state.isStreaming || this.state.activeCompaction || this.sendPending || this.manualCompactionPending) {
+      this.update(
+        (s) => addErrorMessage(s, "\u5F53\u524D\u56DE\u590D\u5C1A\u672A\u7ED3\u675F\u6216\u5BF9\u8BDD\u6B63\u5728\u6574\u7406\uFF0C\u8BF7\u7A0D\u540E\u518D\u53D1\u9001\u3002")
+      );
+      return false;
     }
     this.sendPending = true;
     try {
-      await this.sendUnlocked(content, options);
+      return 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;
+    if (this.state.isStreaming || this.state.activeCompaction || this.manualCompactionPending) {
+      this.update(
+        (s) => addErrorMessage(s, "\u5F53\u524D\u56DE\u590D\u5C1A\u672A\u7ED3\u675F\u6216\u5BF9\u8BDD\u6B63\u5728\u6574\u7406\uFF0C\u8BF7\u7A0D\u540E\u518D\u53D1\u9001\u3002")
+      );
+      return false;
     }
     let appContext;
     if (this.getAppContext) {
@@ -3148,19 +3208,28 @@ var AgentSession = class _AgentSession {
       } 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;
+        return false;
       }
     }
     const askUserAnswer = options.askUserAnswer;
+    let optimisticTurnId = null;
+    let optimisticAskAnswer;
+    let previousAskAnswer;
     if (!(askUserAnswer && typeof askUserAnswer.tool_call_id === "string")) {
-      this.update((s) => addUserMessage(s, content));
+      this.update((state) => {
+        const next = addUserMessage(state, content);
+        optimisticTurnId = next.turns.at(-1)?.turn_id ?? null;
+        return next;
+      });
     }
     this.update((s) => ({ ...s, isStreaming: true }));
     if (askUserAnswer && typeof askUserAnswer.tool_call_id === "string") {
       const { tool_call_id, ...rest } = askUserAnswer;
+      previousAskAnswer = this.state.askAnswers[tool_call_id];
+      optimisticAskAnswer = rest;
       this.update((s) => ({
         ...s,
-        askAnswers: { ...s.askAnswers, [tool_call_id]: rest }
+        askAnswers: { ...s.askAnswers, [tool_call_id]: optimisticAskAnswer }
       }));
     }
     if (!options.replayDecision) {
@@ -3181,15 +3250,54 @@ var AgentSession = class _AgentSession {
     try {
       await this.ensureJoined();
     } catch (error) {
-      this.update(
-        (s) => addErrorMessage(
-          { ...s, isStreaming: false, status: "failed" },
-          error instanceof Error && error.message ? error.message : "\u4F1A\u8BDD\u8BA2\u9605\u5931\u8D25\uFF0C\u6D88\u606F\u672A\u53D1\u9001"
-        )
+      this.rollbackOptimisticSend(
+        optimisticTurnId,
+        askUserAnswer,
+        optimisticAskAnswer,
+        previousAskAnswer,
+        error instanceof Error && error.message ? error.message : "\u4F1A\u8BDD\u8BA2\u9605\u5931\u8D25\uFF0C\u6D88\u606F\u672A\u53D1\u9001"
       );
-      return;
+      return false;
+    }
+    try {
+      const response = await this.runtime.emitWithAck("chat:send", payload, 3e4);
+      if (response?.status !== "accepted") {
+        throw new Error(
+          typeof response?.message === "string" ? response.message : "\u6D88\u606F\u672A\u88AB\u670D\u52A1\u7AEF\u63A5\u53D7"
+        );
+      }
+      return true;
+    } catch (error) {
+      this.rollbackOptimisticSend(
+        optimisticTurnId,
+        askUserAnswer,
+        optimisticAskAnswer,
+        previousAskAnswer,
+        error instanceof Error && error.message ? error.message : "\u6D88\u606F\u53D1\u9001\u5931\u8D25\uFF0C\u8BF7\u91CD\u8BD5"
+      );
+      return false;
     }
-    this.runtime.emitEvent("chat:send", payload);
+  }
+  rollbackOptimisticSend(optimisticTurnId, askUserAnswer, optimisticAskAnswer, previousAskAnswer, message) {
+    this.pendingReplayMessage = null;
+    this.pendingReplayMode = void 0;
+    this.update((current) => {
+      let next = optimisticTurnId ? withTurns(
+        current,
+        current.turns.filter((turn) => turn.turn_id !== optimisticTurnId)
+      ) : current;
+      const toolCallId = askUserAnswer && typeof askUserAnswer.tool_call_id === "string" ? askUserAnswer.tool_call_id : null;
+      if (toolCallId && next.askAnswers[toolCallId] === optimisticAskAnswer) {
+        const askAnswers = { ...next.askAnswers };
+        if (previousAskAnswer === void 0) {
+          delete askAnswers[toolCallId];
+        } else {
+          askAnswers[toolCallId] = previousAskAnswer;
+        }
+        next = { ...next, askAnswers };
+      }
+      return addErrorMessage({ ...next, isStreaming: false }, message);
+    });
   }
   /** 智能体运行期间追加补充说明（不打断当前回复）。 */
   append(text) {
@@ -3203,7 +3311,28 @@ var AgentSession = class _AgentSession {
   }
   /** 手动触发上下文压缩。 */
   compact() {
-    return this.runtime.emitWithAck("chat:compact", { session_id: this.sessionId }, 3e4).then((response) => response ?? {});
+    if (this.state.isStreaming || this.state.activeCompaction || this.manualCompactionPending) {
+      return Promise.resolve({
+        status: "error",
+        message: "\u5F53\u524D\u56DE\u590D\u5C1A\u672A\u7ED3\u675F\u6216\u5BF9\u8BDD\u6B63\u5728\u6574\u7406\uFF0C\u8BF7\u7A0D\u540E\u518D\u8BD5\u3002"
+      });
+    }
+    this.manualCompactionPending = true;
+    this.update((state) => ({
+      ...state,
+      activeCompaction: {
+        turn_id: "pending-manual-compaction",
+        compaction_id: "pending-manual-compaction",
+        status: "streaming",
+        trigger: "manual"
+      }
+    }));
+    return this.runtime.emitWithAck("chat:compact", { session_id: this.sessionId }, 3e4).then((response) => response ?? {}).finally(() => {
+      this.manualCompactionPending = false;
+      if (this.state.activeCompaction?.compaction_id === "pending-manual-compaction") {
+        this.update((state) => ({ ...state, activeCompaction: null }));
+      }
+    });
   }
   /**
    * 把一段业务数据作为附件放进聊天输入框（比如地图上选中的点位）。
@@ -3293,10 +3422,7 @@ var AgentSession = class _AgentSession {
   _handleTurnEvents(events) {
     if (!events.length) return;
     const terminalChatEndStatus = extractTerminalChatEndStatus(events);
-    const followupOnly = events.every(
-      (event) => event.type === "session:post_chat_followup"
-    );
-    if (!terminalChatEndStatus && !followupOnly) {
+    if (!terminalChatEndStatus && hasChatRunEvent(events)) {
       this.markRunningIfIdle();
     }
     if (this.state.turns.length) {
@@ -3370,11 +3496,30 @@ var AgentSession = class _AgentSession {
     this.pendingReplayMessage = null;
     this.pendingReplayMode = void 0;
     const respond = (decision) => {
-      this.runtime.emitEvent("chat:send", {
-        session_id: this.sessionId,
-        message,
-        mode,
-        replay_decision: decision
+      void this.runtime.emitWithAck(
+        "chat:send",
+        {
+          session_id: this.sessionId,
+          message,
+          mode,
+          replay_decision: decision
+        },
+        3e4
+      ).then((response) => {
+        if (response?.status === "accepted") return;
+        this.update(
+          (state) => addErrorMessage(
+            { ...state, isStreaming: false },
+            typeof response?.message === "string" ? response.message : "\u6D88\u606F\u672A\u88AB\u670D\u52A1\u7AEF\u63A5\u53D7"
+          )
+        );
+      }).catch((error) => {
+        this.update(
+          (state) => addErrorMessage(
+            { ...state, isStreaming: false },
+            error instanceof Error && error.message ? error.message : "\u6D88\u606F\u53D1\u9001\u5931\u8D25\uFF0C\u8BF7\u91CD\u8BD5"
+          )
+        );
       });
     };
     const handled = this.emitter.emitFirst("replayMismatch", {
@@ -3656,6 +3801,18 @@ var AgentSession = class _AgentSession {
 };
 
 // src/session/hub.ts
+var BACKGROUND_STATUSES = [
+  "starting",
+  "running",
+  "cancelling",
+  "succeeded",
+  "failed",
+  "cancelled",
+  "lost"
+];
+function normalizeBackgroundStatus(value) {
+  return BACKGROUND_STATUSES.includes(value) ? value : "running";
+}
 var SessionHub = class {
   client;
   sessions = /* @__PURE__ */ new Map();
@@ -3910,7 +4067,11 @@ var SessionHub = class {
               id: taskId,
               command: typeof task.command === "string" ? task.command : "",
               description: typeof task.description === "string" ? task.description : void 0,
-              status: task.status === "running" || task.status === "failed" ? task.status : "done",
+              // Pass the server's status through unchanged. Collapsing it here
+              // made subscribers see a successful-looking "done" for tasks the
+              // REST API correctly reported as cancelled or lost.
+              status: normalizeBackgroundStatus(task.status),
+              failureReason: typeof task.failure_reason === "string" ? task.failure_reason : void 0,
               exitCode: typeof task.exit_code === "number" || task.exit_code === null ? task.exit_code : void 0,
               elapsedSeconds: typeof task.elapsed_seconds === "number" ? task.elapsed_seconds : 0,
               output: Array.isArray(task.output_preview) && task.output_preview.length > 0 ? task.output_preview.join("\n") : void 0
@@ -3953,7 +4114,7 @@ function resolveAuthToken(options) {
 
 // src/version.ts
 var SDK_NAME = "agent-client";
-var SDK_VERSION = true ? "1.2.1-alpha.2" : "1.1.1";
+var SDK_VERSION = true ? "1.2.1-beta.1" : "1.1.1";
 
 // src/socket.ts
 function withSdkIdentity(auth) {
@@ -4406,6 +4567,7 @@ var SessionInfo = type({
   "model?": "string | null",
   "enable_thinking?": "boolean | null",
   "solution_id?": "string | null",
+  "solution_ref?": "unknown",
   "biz_role_id?": "string | null",
   "solution?": "unknown",
   "plan_summary?": "string | null",