@blade-hq/agent-client 2610.0.0-beta.80 → 2610.0.0-beta.82

package/README.md

@@ -478,7 +478,7 @@ await chat.refreshQueue()  // 手动拉一份权威快照（首次连接与每
 
 - **冲突处理**：`conflict` 表示乐观并发或状态校验失败，服务端快照已自动刷新到本地，此时保留用户草稿并说明原因即可；`ok=false` 且 `snapshot` 为 null（例如鉴权失败）时不要改动本地队列。`queueMessage` 结果未知（ack 超时）时会用同一个 `client_request_id` 重试一次，不会制造第二条。
 - **可操作性判定**：`canEditQueuedMessage` / `canCancelQueuedMessage` / `canDeliverQueuedMessage` 只对 `pending` 返回 true；文案用 `queuedMessageStatusLabel` 与 `queuePauseReasonLabel`。
-- **自己处理广播**：需要绕过状态机时用 `isSessionQueueSnapshot` + `shouldApplySnapshot` + `EMPTY_SESSION_QUEUE`；解析自定义 ack 用 `parseQueueAck`，返回统一的 `QueueOperationResult`（`QueueAck` 是 ack 的线格式）。
+- **自己处理广播**：需要绕过状态机时用 `isSessionQueueSnapshot` + `shouldApplySnapshot` + `EMPTY_SESSION_QUEUE`；解析自定义 ack 用 `parseQueueAck`，返回统一的 `QueueOperationResult`（`QueueAck` 是 ack 的线格式；`code` 是路由失败原因，供调用方决定是否重试）。
 
 ### 页面协作：让智能体和你的页面互动
 
@@ -544,9 +544,11 @@ 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))
+chat.on("error",      (e) => console.error(e.message, e.code))
 ```
 
+`error` 的 `message` 是可以直接展示的业务文案；`code` 是服务端给的机器可读原因（如 `owner_timeout` / `route_broken` / `owner_busy`），调用方据此决定要不要提示重试，不要解析 `message`。同一组原因也以 `AgentSessionError.code` 的形式抛出（`send()` 这类只回布尔值的入口从 `error` 事件拿），队列 API 则通过 `QueueOperationResult.code` 给出。
+
 完整事件表见 `AgentSessionEvents` 类型定义（含 `modeChange` / `workspaceChanged` / `artifact` / `notification` / `backgroundTask` / `taskListUpdated` / `rewind` / `replayMismatch` 等）。`toolResult.source` 区分实时结果、首次连接回放和断线重连回放；`on()` 返回取消函数，handler 抛异常只告警、不影响会话。
 
 分页响应是 `SessionTurnsPage`，其中 `nextBefore: string | null` 是唯一的“还有更早历史”真值。历史页面指令通过独立的 `HistoricalCommand` 日志恢复，不混进展示页。自定义状态容器可复用 `prependOlder`、`replaceWindow` 与 `LiveRevisionState`，但一般直接使用 `AgentSession` 即可。
@@ -739,6 +741,7 @@ HTML 一律判无效）；`isInternalStatusToolUiCard` 识别内部「阶段进
 - **客户端与登录**：`BladeClientOptions`、`LoginOptions`、`LoginResult`、`TokenStorageMode`、`UploadProgress`、`BladeApiError`、`AuthResource`、`ProvidersResponse`、`UserInfo`
 - **SDK 身份**：`SDK_NAME`、`SDK_VERSION`
 - **声明式会话**：`SessionDefinition`、`SolutionDefinition`、`SkillDefinition`、`SessionConfig`、`TextFile`、`SessionSetupError`、`SessionSetupStage`
+- **会话错误**：`AgentSessionError`（`code` 是服务端路由失败原因，供调用方决定是否重试）
 - **模型目录**：`ModelsResource`、`ModelCatalog`、`ModelOption`
 - **聊天分组资源（REST）**：`ChatGroupsResource`、`ChatGroup`（含 `delete` 永久删除）；`client.chatGroups`。旧名 `ChatProjectsResource`、`ChatProject`、`client.chatProjects` 与 `chat_project_id` 字段已随分组改名一并移除，接入方请改用 `chatGroups` 与 `chat_group_id`
 - **插件目录（REST，无会话）**：`PluginsResource`、`PluginCatalogEntry`（`client.plugins`）。首页这类还没有会话的界面用它读名称、业务名与图标 token

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export type { LoadPlatformEndpointsOptions, PlatformEndpoints, PlatformServiceNa
 export { SDK_NAME, SDK_VERSION } from "./version";
 export { AgentSession } from "./session/agent-session";
 export type { AttachAppOptions, SendOptions } from "./session/agent-session";
+export { AgentSessionError } from "./session/errors";
 export { SessionHub } from "./session/hub";
 export type { SessionConnectOptions } from "./session/hub";
 export type { AgentSessionEvents, AgentSessionEventName } from "./session/events";

package/dist/index.js

@@ -3591,18 +3591,37 @@ function parseQueueAck(response, fallbackSessionId) {
     return { ok: false, conflict: false, snapshot: null, message: QUEUE_FAILURE_MESSAGE };
   }
   const message = typeof response.message === "string" && response.message ? response.message : null;
+  const code = typeof response.code === "string" && response.code ? response.code : void 0;
   const status = response.status;
   if (status !== "ok" && status !== "conflict" && status !== "queued") {
-    return { ok: false, conflict: false, snapshot: null, message: message ?? QUEUE_FAILURE_MESSAGE };
+    return {
+      ok: false,
+      conflict: false,
+      snapshot: null,
+      message: message ?? QUEUE_FAILURE_MESSAGE,
+      ...code ? { code } : {}
+    };
   }
   const snapshot2 = toQueueSnapshot(response, fallbackSessionId);
   if (status === "conflict") {
-    return { ok: false, conflict: true, snapshot: snapshot2, message: message ?? QUEUE_FAILURE_MESSAGE };
+    return {
+      ok: false,
+      conflict: true,
+      snapshot: snapshot2,
+      message: message ?? QUEUE_FAILURE_MESSAGE,
+      ...code ? { code } : {}
+    };
   }
   if (!snapshot2) {
-    return { ok: false, conflict: false, snapshot: null, message: message ?? QUEUE_FAILURE_MESSAGE };
+    return {
+      ok: false,
+      conflict: false,
+      snapshot: null,
+      message: message ?? QUEUE_FAILURE_MESSAGE,
+      ...code ? { code } : {}
+    };
   }
-  return { ok: true, conflict: false, snapshot: snapshot2, message };
+  return { ok: true, conflict: false, snapshot: snapshot2, message, ...code ? { code } : {} };
 }
 function canEditQueuedMessage(item) {
   return item.status === "pending";
@@ -4427,6 +4446,16 @@ function markStreamingTurns(state, turnStatus, toolCallStatus) {
   return withTurns(state, turns);
 }
 
+// src/session/errors.ts
+var AgentSessionError = class extends Error {
+  name = "AgentSessionError";
+  code;
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+  }
+};
+
 // src/session/agent-session.ts
 var OOM_MESSAGE = "\u6C99\u76D2\u5185\u5B58\u4F7F\u7528\u8D85\u51FA\u9650\u5236\uFF0C\u5DF2\u81EA\u52A8\u91CD\u542F\u3002\u5982\u679C\u7ECF\u5E38\u89E6\u53D1\uFF0C\u53EF\u4EE5\u8054\u7CFB\u7BA1\u7406\u5458\u8C03\u6574\u989D\u5EA6\u3002";
 var COMMAND_RESTORE_RETRY_BASE_MS = 1e3;
@@ -4444,6 +4473,16 @@ var OOM_KEYWORDS_RE = /(?:\b(?:exit_code|ExitedWith|exited with)|退出码)\D*(?
 function isOomText(value) {
   return typeof value === "string" && OOM_KEYWORDS_RE.test(value);
 }
+function describeSessionError(error, fallback) {
+  if (error instanceof AgentSessionError) {
+    return {
+      message: error.message || fallback,
+      ...error.code ? { code: error.code } : {}
+    };
+  }
+  if (error instanceof Error && error.message) return { message: error.message };
+  return { message: fallback };
+}
 function parseJsonRecord(value) {
   if (isRecord(value)) return value;
   if (typeof value !== "string") return null;
@@ -4479,11 +4518,12 @@ function isCursorInvalidError(error) {
   return typeof error === "object" && error !== null && "status" in error && error.status === 409;
 }
 function queueRequestFailure(error) {
+  const failure = error instanceof AgentSessionError ? { message: error.message, ...error.code ? { code: error.code } : {} } : { message: error instanceof Error && error.message ? error.message : "\u961F\u5217\u64CD\u4F5C\u5931\u8D25" };
   return {
     ok: false,
     conflict: false,
     snapshot: null,
-    message: error instanceof Error && error.message ? error.message : "\u961F\u5217\u64CD\u4F5C\u5931\u8D25"
+    ...failure
   };
 }
 function commandDeliveryKey(deliveryId) {
@@ -4551,6 +4591,20 @@ var AgentSession = class _AgentSession {
   pendingReplayMode;
   pendingReplayKbIds;
   recentChatEndAt = 0;
+  /**
+   * 最近一次已经通过 `error` 事件投递过的服务端失败（`message` + `code`）。
+   *
+   * `chat:send` 被代理时服务端会先发 `system:error`、再用同一条失败回 ack，两条
+   * 通道都会到达这里：前者走 `_handleSystemError`，后者走发送失败的回滚。不去重
+   * 的话调用方会收到两次同一个 `error`（重复提示、重试逻辑跑两遍）。
+   *
+   * 带代际边界，只认「本次 `emitWithAck` 等待期间」投递的那一条：否则队列/停止
+   * 失败留下的标记会一直挂着，之后一次无关的订阅失败只是文案码相同就被当成
+   * 重复而静音。用单调递增的代际号而不是时间戳，同一毫秒内的两条也不会混淆。
+   */
+  lastDeliveredSystemError = null;
+  /** 每次投递 `system:error` 递增，用于判定某条失败是否属于本次等待。 */
+  systemErrorGeneration = 0;
   subscriptionReplaySource = null;
   disposed = false;
   getAppContext = null;
@@ -4965,16 +5019,19 @@ var AgentSession = class _AgentSession {
     try {
       await this.ensureJoined();
     } catch (error) {
+      const failure = describeSessionError(error, "\u4F1A\u8BDD\u8BA2\u9605\u5931\u8D25\uFF0C\u6D88\u606F\u672A\u53D1\u9001");
       this.rollbackOptimisticSend(
         optimisticTurnId,
         askUserAnswer,
         optimisticAskAnswer,
         previousAskAnswer,
         wasStreaming,
-        error instanceof Error && error.message ? error.message : "\u4F1A\u8BDD\u8BA2\u9605\u5931\u8D25\uFF0C\u6D88\u606F\u672A\u53D1\u9001"
+        failure.message,
+        failure.code
       );
       return false;
     }
+    const waitStartedAt = this.systemErrorGeneration;
     try {
       const response = await this.runtime.emitWithAck("chat:send", payload, 3e4);
       if (response?.status === "queued") {
@@ -4993,24 +5050,28 @@ var AgentSession = class _AgentSession {
         return true;
       }
       if (response?.status !== "accepted") {
-        throw new Error(
-          typeof response?.message === "string" ? response.message : "\u6D88\u606F\u672A\u88AB\u670D\u52A1\u7AEF\u63A5\u53D7"
+        throw new AgentSessionError(
+          typeof response?.message === "string" ? response.message : "\u6D88\u606F\u672A\u88AB\u670D\u52A1\u7AEF\u63A5\u53D7",
+          typeof response?.code === "string" ? response.code : void 0
         );
       }
       return true;
     } catch (error) {
+      const failure = describeSessionError(error, "\u6D88\u606F\u53D1\u9001\u5931\u8D25\uFF0C\u8BF7\u91CD\u8BD5");
       this.rollbackOptimisticSend(
         optimisticTurnId,
         askUserAnswer,
         optimisticAskAnswer,
         previousAskAnswer,
         wasStreaming,
-        error instanceof Error && error.message ? error.message : "\u6D88\u606F\u53D1\u9001\u5931\u8D25\uFF0C\u8BF7\u91CD\u8BD5"
+        failure.message,
+        failure.code,
+        waitStartedAt
       );
       return false;
     }
   }
-  rollbackOptimisticSend(optimisticTurnId, askUserAnswer, optimisticAskAnswer, previousAskAnswer, wasStreaming, message) {
+  rollbackOptimisticSend(optimisticTurnId, askUserAnswer, optimisticAskAnswer, previousAskAnswer, wasStreaming, message, code, waitStartedAt) {
     this.discardOptimisticSend(
       optimisticTurnId,
       askUserAnswer,
@@ -5020,6 +5081,12 @@ var AgentSession = class _AgentSession {
     this.update(
       (current) => addErrorMessage(wasStreaming ? current : { ...current, isStreaming: false }, message)
     );
+    const delivered = this.lastDeliveredSystemError;
+    if (waitStartedAt !== void 0 && delivered && delivered.generation > waitStartedAt && delivered.message === message && delivered.code === code) {
+      this.lastDeliveredSystemError = null;
+      return;
+    }
+    this.emitter.emit("error", { message, ...code ? { code } : {} });
   }
   /** 撤回一次乐观提交：移除乐观消息、恢复提问作答、清掉回放草稿。 */
   discardOptimisticSend(optimisticTurnId, askUserAnswer, optimisticAskAnswer, previousAskAnswer) {
@@ -5284,7 +5351,12 @@ var AgentSession = class _AgentSession {
   }
   /** @internal */
   _handleChatStart() {
-    this.update((s) => ({ ...s, status: "running", errorMessage: null, isStreaming: true }));
+    this.update((s) => ({
+      ...s,
+      status: "running",
+      errorMessage: null,
+      isStreaming: true
+    }));
   }
   /** @internal */
   _handleChatEnd(status) {
@@ -5292,14 +5364,31 @@ var AgentSession = class _AgentSession {
     this.completeChat(status);
   }
   /** @internal */
-  _handleSystemError(message) {
+  _handleSystemError(message, code) {
     this.flushPatches();
     const finalMessage = isOomText(message) ? OOM_MESSAGE : message;
     this.update(
-      (s) => addErrorMessage(markFailed({ ...s, status: "failed", errorMessage: finalMessage, isStreaming: false }), finalMessage)
+      (s) => addErrorMessage(
+        markFailed({
+          ...s,
+          status: "failed",
+          errorMessage: finalMessage,
+          isStreaming: false
+        }),
+        finalMessage
+      )
     );
     this.recentChatEndAt = Date.now();
-    this.emitter.emit("error", { message: finalMessage });
+    this.systemErrorGeneration += 1;
+    this.lastDeliveredSystemError = {
+      message: finalMessage,
+      ...code ? { code } : {},
+      generation: this.systemErrorGeneration
+    };
+    this.emitter.emit("error", {
+      message: finalMessage,
+      ...code ? { code } : {}
+    });
   }
   /** @internal */
   _handleTaskUpdated(tasks) {
@@ -5834,8 +5923,9 @@ var AgentSession = class _AgentSession {
       5e3
     ).then((response) => {
       if (response && response.ok === false) {
-        throw new Error(
-          typeof response.message === "string" && response.message ? response.message : "Session subscription failed"
+        throw new AgentSessionError(
+          typeof response.message === "string" && response.message ? response.message : "Session subscription failed",
+          typeof response.code === "string" ? response.code : void 0
         );
       }
       this.joined = true;
@@ -6144,9 +6234,15 @@ var SessionHub = class {
         session._handleChatEnd(data?.status ?? "completed");
       }
     });
-    socket.on("system:error", (data) => {
-      for (const session of this.route(data.session_id)) session._handleSystemError(data.message);
-    });
+    socket.on(
+      "system:error",
+      (data) => {
+        const code = data.code == null ? void 0 : String(data.code);
+        for (const session of this.route(data.session_id)) {
+          session._handleSystemError(data.message, code);
+        }
+      }
+    );
     socket.on("chat:queue:updated", (data) => {
       for (const session of this.route(data?.session_id)) session._handleQueueUpdated(data);
     });
@@ -6803,7 +6899,7 @@ function resolveServiceUrl(endpoints, name, path = "") {
 
 // src/version.ts
 var SDK_NAME = "agent-client";
-var SDK_VERSION = true ? "2610.0.0-beta.80" : "1.1.1";
+var SDK_VERSION = true ? "2610.0.0-beta.82" : "1.1.1";
 
 // src/commands/protocol.ts
 function isCommandEnvelope(value) {
@@ -6905,6 +7001,7 @@ var Task = type2({
 });
 export {
   AgentSession,
+  AgentSessionError,
   AuthBusyReconnect,
   BladeApiError,
   BladeClient,