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

package/dist/resources/sessions.d.ts

@@ -1,4 +1,4 @@
-import type { BackgroundTask } from "../schemas/background";
+import type { BackgroundTask, BackgroundTaskStopResult } from "../schemas/background";
 import type { TurnProjection } from "../schemas/projection";
 import type { PublishedSolutionRef, SessionDetail, SessionInfo, TemplateId } from "../schemas/session";
 import type { Task } from "../schemas/task";
@@ -262,10 +262,7 @@ export declare class SessionsResource {
     }>;
     listBackgroundTasks(sessionId: string, init?: RequestInit): Promise<BackgroundTask[]>;
     getBackgroundTask(sessionId: string, taskId: string, tail?: number, init?: RequestInit): Promise<BackgroundTask>;
-    stopBackgroundTask(sessionId: string, taskId: string): Promise<{
-        message: string;
-        task?: BackgroundTask | null;
-    }>;
+    stopBackgroundTask(sessionId: string, taskId: string): Promise<BackgroundTaskStopResult>;
     probeSessionUrl(sessionId: string, url: string): Promise<{
         reachable: boolean;
         requires_proxy: boolean;

package/dist/schemas/background.d.ts

@@ -2,8 +2,16 @@ export interface BackgroundTask {
     id: string;
     command: string;
     description?: string;
-    status: "queued" | "starting" | "running" | "succeeded" | "done" | "failed" | "timeout" | "cancelled" | "lost";
-    legacy_status?: "running" | "done" | "failed";
+    /**
+     * The server's real status. Never collapse these client-side: telling a user
+     * that a cancelled or lost task is "done" is exactly the lie this replaced.
+     *
+     * `lost` means the platform stopped being able to track the process, not
+     * that it failed — it may still be running.
+     */
+    status: "starting" | "running" | "cancelling" | "succeeded" | "failed" | "cancelled" | "lost";
+    /** Set on `failed` to say why, e.g. `start_failed`, `log_budget_exceeded`. */
+    failure_reason?: string | null;
     exit_code?: number | null;
     elapsed_seconds: number;
     output_lines_count?: number;
@@ -12,5 +20,12 @@ export interface BackgroundTask {
     log_path?: string | null;
     started_at?: number | null;
     finished_at?: number | null;
-    heartbeat_at?: number | null;
+}
+/** Outcome of a stop request. `ok: false` is a real answer, not an error. */
+export interface BackgroundTaskStopResult {
+    ok: boolean;
+    message: string;
+    /** Why the stop could not be confirmed, e.g. `still_running`, `probe_unknown`. */
+    reason?: string | null;
+    task?: BackgroundTask | null;
 }

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

@@ -67,6 +67,7 @@ export declare class AgentSession {
     private disposed;
     private getAppContext;
     private sendPending;
+    private manualCompactionPending;
     private readonly deliveredCommandKeys;
     private readonly deliveredToolPreviews;
     private readonly oomNotifiedKeys;
@@ -99,8 +100,9 @@ export declare class AgentSession {
      */
     attachApp(options: AttachAppOptions): Promise<AppCliAttachment | null>;
     /** 发送一条消息。字符串或多模态内容均可。 */
-    send(content: MessageContent, options?: SendOptions): Promise<void>;
+    send(content: MessageContent, options?: SendOptions): Promise<boolean>;
     private sendUnlocked;
+    private rollbackOptimisticSend;
     /** 智能体运行期间追加补充说明（不打断当前回复）。 */
     append(text: string): void;
     /** 停止当前回复。 */
@@ -166,15 +168,7 @@ export declare class AgentSession {
     /** @internal */
     _handleSystemNotification(loopId: string, notification: Record<string, unknown>): void;
     /** @internal */
-    _handleBackgroundTask(task: {
-        id: string;
-        command: string;
-        description?: string;
-        status: "running" | "done" | "failed";
-        exitCode?: number | null;
-        elapsedSeconds: number;
-        output?: string;
-    }): void;
+    _handleBackgroundTask(task: AgentSessionEvents["backgroundTask"]): void;
     /** @internal */
     _handleArtifact(event: AgentSessionEvents["artifact"]): void;
     /** @internal 加入房间的应答里带 is_running，据此校准流式状态。 */

package/dist/session/events.d.ts

@@ -88,7 +88,14 @@ export interface AgentSessionEvents {
         id: string;
         command: string;
         description?: string;
-        status: "running" | "done" | "failed";
+        /**
+         * 与 REST 一致的真实状态。不要在客户端合并这些值：把 cancelled / lost
+         * 显示成"完成"会让订阅方拿到与 REST 相反的结论。
+         * lost 表示平台跟丢了这个进程，不代表它失败，也可能仍在运行。
+         */
+        status: "starting" | "running" | "cancelling" | "succeeded" | "failed" | "cancelled" | "lost";
+        /** failed 时说明原因，如 start_failed、log_budget_exceeded。 */
+        failureReason?: string | null;
         exitCode?: number | null;
         elapsedSeconds: number;
         output?: string;

package/dist/types/socket-events.d.ts

@@ -344,6 +344,18 @@ export declare namespace AgentBoardFileOpPayloadSchema {
     }
 }
 export type AgentBoardFileOpPayload = AgentBoardFileOpPayloadSchema.AgentBoardFileOpPayload;
+export declare namespace ChatSendAckSchema {
+    type Status = string;
+    type Message = (string | null);
+    type Code = (string | number | null);
+    interface ChatSendAck {
+        status: Status;
+        message?: Message;
+        code?: Code;
+        [k: string]: unknown;
+    }
+}
+export type ChatSendAck = ChatSendAckSchema.ChatSendAck;
 export declare namespace ChatStopAckSchema {
     type Status = string;
     type Message = (string | null);
@@ -369,7 +381,7 @@ export declare namespace ChatCompactAckSchema {
 }
 export type ChatCompactAck = ChatCompactAckSchema.ChatCompactAck;
 export interface ClientToServerEvents {
-    "chat:send": (payload: ChatSendPayload) => void;
+    "chat:send": (payload: ChatSendPayload, ack: (response: ChatSendAck) => void) => void;
     "chat:stop": (payload: ChatStopPayload, ack: (response: ChatStopAck) => void) => void;
     "chat:append": (payload: ChatAppendPayload) => void;
     "chat:compact": (payload: ChatCompactPayload, ack: (response: ChatCompactAck) => void) => void;

package/package.json

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

package/public-api.md

@@ -3,7 +3,7 @@
 > 本文件由 `scripts/public-api-report.mjs` 生成，请勿手改。
 > 公共面变更时重新生成本报告，并同步更新 README 对应章节——CI 会校验两者。
 
-共 116 个公开声明。
+共 117 个公开声明。
 
 ## `ActiveCompactionState` (interface)
 
@@ -49,7 +49,7 @@ listDir: (dirPath?: string) => Promise<FileEntry[]>
 off: <K extends keyof AgentSessionEvents>(name: K, handler: (event: AgentSessionEvents[K]) => void) => void
 on: <K extends keyof AgentSessionEvents>(name: K, handler: (event: AgentSessionEvents[K]) => void) => () => void
 onCommand: (action: string, handler: CommandHandler) => () => void
-send: (content: MessageContent, options?: SendOptions) => Promise<void>
+send: (content: MessageContent, options?: SendOptions) => Promise<boolean>
 sessionId: string
 stop: () => Promise<Record<string, unknown>>
 subscribe: (listener: () => void) => () => void
@@ -66,7 +66,7 @@ export type AgentSessionEventName = keyof AgentSessionEvents
 ```ts
 artifact: { filePath: string; contentType: string; title: string; content: string; oldString?: string; newString?: string; kind: "created" | "updated"; }
 attachRequested: { label: string; content: string; }
-backgroundTask: { id: string; command: string; description?: string; status: "running" | "done" | "failed"; exitCode?: number | null; elapsedSeconds: number; output?: 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; }
@@ -161,16 +161,24 @@ command: string
 description: string | undefined
 elapsed_seconds: number
 exit_code: number | null | undefined
+failure_reason: string | null | undefined
 finished_at: number | null | undefined
-heartbeat_at: number | null | undefined
 id: string
-legacy_status: "failed" | "running" | "done" | undefined
 log_path: string | null | undefined
 output: string | undefined
 output_lines_count: number | undefined
 output_preview: string[] | undefined
 started_at: number | null | undefined
-status: "failed" | "running" | "done" | "cancelled" | "queued" | "starting" | "succeeded" | "timeout" | "lost"
+status: "failed" | "running" | "cancelled" | "starting" | "cancelling" | "succeeded" | "lost"
+```
+
+## `BackgroundTaskStopResult` (interface)
+
+```ts
+message: string
+ok: boolean
+reason: string | null | undefined
+task: BackgroundTask | null | undefined
 ```
 
 ## `BizRole` (interface)
@@ -939,7 +947,7 @@ rewindSession: (sessionId: string, checkpointId: string) => Promise<{ id: string
 setSessionEnv: (sessionId: string, env: Record<string, string>) => Promise<SessionDetail>
 shareFile: (sessionId: string, sourcePath: string, linkName?: string, shareFolder?: string) => Promise<{ path: string; target: string; }>
 startReplaySession: (sourceSessionId: string, speed?: 1 | 2 | 5) => Promise<{ session_id: string; }>
-stopBackgroundTask: (sessionId: string, taskId: string) => Promise<{ message: string; task?: BackgroundTask | null; }>
+stopBackgroundTask: (sessionId: string, taskId: string) => Promise<BackgroundTaskStopResult>
 switchBranch: (sessionId: string, checkpointId: string) => Promise<{ id: string; leaf_id: string; }>
 tokenizeMessages: (messages: Array<Record<string, unknown>>, options?: { model?: string; add_generation_prompt?: boolean; enable_thinking?: boolean | null; tools?: Array<Record<string, unknown>>; }) => Promise<TokenizeResult>
 tokenizePrompt: (prompt: string, model?: string) => Promise<TokenizeResult>