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

package/dist/session/agent-session.d.ts

@@ -108,6 +108,20 @@ export declare class AgentSession {
     private pendingReplayMode;
     private pendingReplayKbIds;
     private recentChatEndAt;
+    /**
+     * 最近一次已经通过 `error` 事件投递过的服务端失败（`message` + `code`）。
+     *
+     * `chat:send` 被代理时服务端会先发 `system:error`、再用同一条失败回 ack，两条
+     * 通道都会到达这里：前者走 `_handleSystemError`，后者走发送失败的回滚。不去重
+     * 的话调用方会收到两次同一个 `error`（重复提示、重试逻辑跑两遍）。
+     *
+     * 带代际边界，只认「本次 `emitWithAck` 等待期间」投递的那一条：否则队列/停止
+     * 失败留下的标记会一直挂着，之后一次无关的订阅失败只是文案码相同就被当成
+     * 重复而静音。用单调递增的代际号而不是时间戳，同一毫秒内的两条也不会混淆。
+     */
+    private lastDeliveredSystemError;
+    /** 每次投递 `system:error` 递增，用于判定某条失败是否属于本次等待。 */
+    private systemErrorGeneration;
     private subscriptionReplaySource;
     private disposed;
     private getAppContext;
@@ -288,7 +302,7 @@ export declare class AgentSession {
     /** @internal */
     _handleChatEnd(status: string): void;
     /** @internal */
-    _handleSystemError(message: string): void;
+    _handleSystemError(message: string, code?: string): void;
     /** @internal */
     _handleTaskUpdated(tasks: unknown[]): void;
     /** @internal */

package/dist/session/errors.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 一次会话操作的失败。
+ *
+ * `code` 是服务端给的机器可读原因（如 `owner_timeout` / `route_broken`），
+ * 调用方据此决定要不要重试；`message` 是可以直接展示的业务文案，不要当协议解析。
+ */
+export declare class AgentSessionError extends Error {
+    readonly name = "AgentSessionError";
+    readonly code?: string;
+    constructor(message: string, code?: string);
+}

package/dist/session/events.d.ts

@@ -31,9 +31,15 @@ export interface AgentSessionEvents {
     chatEnd: {
         status: string;
     };
-    /** 运行错误（system:error、发送失败等）。 */
+    /**
+     * 运行错误（system:error、发送失败等）。
+     *
+     * `code` 是服务端给的机器可读原因（如 `owner_timeout` / `route_broken`），
+     * 供调用方决定要不要重试；`message` 是可以直接展示的业务文案。
+     */
     error: {
         message: string;
+        code?: string;
     };
     /** planning / executing 模式切换。 */
     modeChange: {

package/dist/session/queue.d.ts

@@ -65,6 +65,11 @@ export interface QueueOperationResult {
     /** 服务端快照；缺失时为 null，调用方不得据此清空本地队列。 */
     snapshot: SessionQueueSnapshot | null;
     message: string | null;
+    /**
+     * 服务端给的机器可读失败原因（如 `owner_timeout` / `route_broken` / `owner_busy`），
+     * 供调用方决定要不要重试；`message` 是可以直接展示的业务文案。
+     */
+    code?: string;
 }
 /** 判定一份载荷是不是完整的权威队列快照（广播事件用）。 */
 export declare function isSessionQueueSnapshot(value: unknown): value is SessionQueueSnapshot;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blade-hq/agent-client",
-  "version": "2610.0.0-beta.80",
+  "version": "2610.0.0-beta.82",
   "description": "Blade Agent 框架无关客户端：会话实时状态机、REST 通道、弹窗登录、页面协作。浏览器与 Node.js 通用。",
   "repository": {
     "type": "git",

package/public-api.md

@@ -3,7 +3,7 @@
 > 本文件由 `scripts/public-api-report.mjs` 生成，请勿手改。
 > 公共面变更时重新生成本报告，并同步更新 README 对应章节——CI 会校验两者。
 
-共 244 个公开声明。
+共 245 个公开声明。
 
 ## `acceptedPostChatFollowupCompletesLatestRun` (function)
 
@@ -103,6 +103,16 @@ subscribe: (listener: () => void) => () => void
 updateQueuedMessage: (itemId: string, expectedVersion: number, content: string) => Promise<QueueOperationResult>
 ```
 
+## `AgentSessionError` (class)
+
+```ts
+cause: unknown
+code: string | undefined
+message: string
+name: "AgentSessionError"
+stack: string | undefined
+```
+
 ## `AgentSessionEventName` (type)
 
 ```ts
@@ -117,7 +127,7 @@ attachRequested: { label: string; content: string; }
 backgroundTask: { id: string; command: string; description?: string; status: "starting" | "running" | "cancelling" | "succeeded" | "failed" | "cancelled" | "lost"; failureReason?: string | null; exitCode?: number | null; elapsedSeconds: number; output?: string; }
 chatEnd: { status: string; }
 command: { action: string; payload: unknown; toolCallId?: string; }
-error: { message: string; }
+error: { message: string; code?: string; }
 insertTextRequested: { text: string; }
 message: { message: ChatMessage; turn: TurnProjection; }
 modeChange: { mode: "planning" | "executing"; }
@@ -1325,6 +1335,7 @@ queuedMessageStatusLabel: (status: QueuedMessageStatus) => string
 ## `QueueOperationResult` (interface)
 
 ```ts
+code: string | undefined
 conflict: boolean
 message: string | null
 ok: boolean