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

package/dist/resources/sessions.d.ts

@@ -1,6 +1,6 @@
-import type { BackgroundTask } from "../schemas/background";
+import type { BackgroundTask, BackgroundTaskStopResult } from "../schemas/background";
 import type { TurnProjection } from "../schemas/projection";
-import type { SessionDetail, SessionInfo, TemplateId } from "../schemas/session";
+import type { PublishedSolutionRef, SessionDetail, SessionInfo, TemplateId } from "../schemas/session";
 import type { Task } from "../schemas/task";
 import type { BladeClient, UploadProgress } from "../blade-client";
 import type { AgentSession } from "../session/agent-session";
@@ -9,7 +9,12 @@ import type { SessionProfile } from "../types/sdk-profile";
 export interface CreateSessionRequest {
     intent?: string;
     template_id?: TemplateId;
+    /** 正式 Solution 来源。Hub 使用 { source: "hub", org, name }。 */
+    solution_ref?: PublishedSolutionRef;
+    /** @deprecated 请使用结构化的 solution_ref；继续支持以保证现有 SDK 调用无感升级。 */
     solution_id?: string;
+    /** 从已有会话复制其不可变 Solution 与 Skill 运行快照。 */
+    solution_snapshot_session_id?: string;
     biz_role_id?: string | null;
     primary_skill_id?: string | null;
     model?: string | null;
@@ -150,6 +155,12 @@ export interface ImportPreview {
     skills: ImportPreviewSkill[];
     scenario: ImportPreviewScenario | null;
 }
+export interface ImportSessionOptions {
+    /** 导入后改用这个正式 Solution 的最新版。 */
+    solution_ref?: PublishedSolutionRef;
+    /** 导入后改用已有会话的完整运行快照。 */
+    solution_snapshot_session_id?: string;
+}
 export declare class SessionsResource {
     private client;
     constructor(client: BladeClient);
@@ -170,6 +181,7 @@ export declare class SessionsResource {
         offset: number;
         template_id_prefix?: string;
         solution_id?: string;
+        solution_registry_id?: string;
         q?: string;
     }): Promise<PaginatedSessionsResult>;
     listSessionsWithSkillData(): Promise<SkillDevSession[]>;
@@ -250,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;
@@ -285,7 +294,7 @@ export declare class SessionsResource {
     getDownloadDirUrl(sessionId: string, dirPath: string): string;
     exportSession(sessionId: string): Promise<void>;
     previewImport(file: File): Promise<ImportPreview>;
-    importSession(file: File, name?: string, solutionId?: string | null): Promise<{
+    importSession(file: File, name?: string, solutionOverride?: string | null | ImportSessionOptions): Promise<{
         session_id: string;
     }>;
 }

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/schemas/session.d.ts

@@ -4,6 +4,14 @@ export type SessionStatus = typeof SessionStatus.infer;
 export type TemplateId = "default" | "skill_editor" | "ship_attack";
 export type SkillEditorTemplateId = "skill_editor";
 export type ModeId = "planning" | "executing";
+export type PublishedSolutionRef = {
+    source: "builtin";
+    name: string;
+} | {
+    source: "hub";
+    org: string;
+    name: string;
+};
 export interface ReplayState {
     source_session_id?: string;
     status?: "replay" | "autonomous";
@@ -43,6 +51,7 @@ export declare const SessionInfo: import("arktype/internal/variants/object.ts").
     model?: string | null | undefined;
     enable_thinking?: boolean | null | undefined;
     solution_id?: string | null | undefined;
+    solution_ref?: unknown;
     biz_role_id?: string | null | undefined;
     solution?: unknown;
     plan_summary?: string | null | undefined;
@@ -69,6 +78,7 @@ export type SessionInfo = Omit<typeof SessionInfo.infer, "template_id" | "soluti
     model?: string | null;
     enable_thinking?: boolean | null;
     solution_id?: string | null;
+    solution_ref?: PublishedSolutionRef | null;
     biz_role_id?: string | null;
     solution?: Solution | null;
     primary_skill_id?: string | 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.2",
+  "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 会校验两者。
 
-共 114 个公开声明。
+共 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)
@@ -349,6 +357,8 @@ primary_skill_id: string | null | undefined
 runtime_type: "sandbox" | "daemon" | null | undefined
 session_solution_asset_id: string | null | undefined
 solution_id: string | undefined
+solution_ref: PublishedSolutionRef | undefined
+solution_snapshot_session_id: string | undefined
 template_id: TemplateId | undefined
 ```
 
@@ -454,6 +464,13 @@ image_url: { url: string; }
 type: "image_url"
 ```
 
+## `ImportSessionOptions` (interface)
+
+```ts
+solution_ref: PublishedSolutionRef | undefined
+solution_snapshot_session_id: string | undefined
+```
+
 ## `InboundAction` (type)
 
 ```ts
@@ -657,6 +674,14 @@ password_enabled: boolean
 providers: { name: string; authorize_url: string; }[]
 ```
 
+## `PublishedSolutionRef` (type)
+
+```ts
+export type PublishedSolutionRef =
+  | { source: "builtin"; name: string }
+  | { source: "hub"; org: string; name: string }
+```
+
 ## `RawEvent` (interface)
 
 ```ts
@@ -775,6 +800,7 @@ runtime_type: string | null | undefined
 shared: boolean | undefined
 solution: Solution | null | undefined
 solution_id: string | null | undefined
+solution_ref: PublishedSolutionRef | null | undefined
 status: "completed" | "failed" | "interrupted" | "running" | "created" | "waiting_for_input"
 template_id: TemplateId | null | undefined
 updated_at: string
@@ -823,6 +849,7 @@ 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",
@@ -905,11 +932,11 @@ getSessionHistory: (sessionId: string, init?: RequestInit) => Promise<SessionHis
 getSessionTasks: (sessionId: string) => Promise<Task[]>
 getSessionTurns: (sessionId: string) => Promise<TurnProjection[]>
 getSharedSession: (token: string) => Promise<TurnProjection[]>
-importSession: (file: File, name?: string, solutionId?: string | null) => Promise<{ session_id: string; }>
+importSession: (file: File, name?: string, solutionOverride?: string | null | ImportSessionOptions) => Promise<{ session_id: string; }>
 listBackgroundTasks: (sessionId: string, init?: RequestInit) => Promise<BackgroundTask[]>
 listDir: (sessionId: string, dirPath: string) => Promise<FileEntry[]>
 listSessions: (template_id_prefix?: string, solution_id?: string) => Promise<SessionInfo[]>
-listSessionsPaginated: (params: { limit: number; offset: number; template_id_prefix?: string; solution_id?: string; q?: string; }) => Promise<PaginatedSessionsResult>
+listSessionsPaginated: (params: { limit: number; offset: number; template_id_prefix?: string; solution_id?: string; solution_registry_id?: string; q?: string; }) => Promise<PaginatedSessionsResult>
 listSessionsWithSkillData: () => Promise<SkillDevSession[]>
 pinSession: (sessionId: string, pinned: boolean) => Promise<SessionInfo>
 previewImport: (file: File) => Promise<ImportPreview>
@@ -920,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>