@blade-hq/agent-client 1.1.12-beta.3 → 1.2.0-beta.1

package/dist/resources/sessions.d.ts

@@ -115,6 +115,21 @@ export type UploadFileEntry = File | {
 export interface UploadFilesOptions {
     onProgress?: (progress: UploadProgress) => void;
 }
+export interface AppCliDefinition {
+    /** 智能体在 Bash 中直接执行的业务命令名，例如 `library`。 */
+    command: string;
+    /** Python 脚本由沙盒系统 Python 执行；executable 必须是 Linux 可执行文件。 */
+    runtime: "python" | "executable";
+    /** CLI 文件本身，或浏览器可以读取的 URL。 */
+    source: Blob | string | URL;
+    /** source 是普通 Blob 时使用的上传文件名。 */
+    filename?: string;
+}
+export interface AppCliAttachment {
+    command: string;
+    runtime: "python" | "executable";
+    digest: string;
+}
 export interface ImportPreviewSkill {
     name: string;
     description: string;
@@ -241,6 +256,7 @@ export declare class SessionsResource {
     }>;
     probeSessionUrl(sessionId: string, url: string): Promise<{
         reachable: boolean;
+        requires_proxy: boolean;
     }>;
     listDir(sessionId: string, dirPath: string): Promise<FileEntry[]>;
     countFiles(sessionId: string, dirPath?: string): Promise<number>;
@@ -250,6 +266,8 @@ export declare class SessionsResource {
         uploaded: string[];
         failed: string[];
     }>;
+    /** 把应用自己的业务 CLI 安装到会话沙盒，并保留开发者声明的命令名。 */
+    attachAppCli(sessionId: string, definition: AppCliDefinition): Promise<AppCliAttachment>;
     deleteFile(sessionId: string, filePath: string): Promise<void>;
     writeFile(sessionId: string, filePath: string, content: string): Promise<{
         success: boolean;

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

@@ -4,7 +4,7 @@ import type { PatchEnvelope, TurnProjection } from "../schemas/projection";
 import type { SessionStatus } from "../schemas/session";
 import { type CommandHandler } from "../commands/registry";
 import { type AgentSessionEvents } from "./events";
-import type { FileEntry } from "../resources/sessions";
+import type { AppCliAttachment, AppCliDefinition, FileEntry } from "../resources/sessions";
 import { type ConnectionStatus, type SessionState } from "./state";
 /** SessionHub 注入给 AgentSession 的运行时依赖（socket 收发 + REST 补数）。 */
 export interface SessionRuntime {
@@ -15,8 +15,15 @@ export interface SessionRuntime {
     listDir(sessionId: string, dirPath: string): Promise<FileEntry[]>;
     countFiles(sessionId: string, dirPath?: string): Promise<number>;
     downloadFile(sessionId: string, filePath: string, downloadName?: string): Promise<void>;
+    attachAppCli(sessionId: string, definition: AppCliDefinition): Promise<AppCliAttachment>;
     onDispose(session: AgentSession): void;
 }
+export interface AttachAppOptions {
+    /** 可选；只需要页面上下文时无需提供 CLI。 */
+    cli?: AppCliDefinition;
+    /** 每次发送前执行一次；返回当前页面状态的 JSON 对象快照。 */
+    getContext: () => Record<string, unknown> | Promise<Record<string, unknown>>;
+}
 export interface SendOptions {
     /** planning / executing 模式。 */
     mode?: string;
@@ -58,6 +65,8 @@ export declare class AgentSession {
     private pendingReplayMode;
     private recentChatEndAt;
     private disposed;
+    private getAppContext;
+    private sendPending;
     private readonly deliveredCommandKeys;
     private readonly deliveredToolPreviews;
     private readonly oomNotifiedKeys;
@@ -83,8 +92,15 @@ export declare class AgentSession {
      * "map.highlight"），由你和技能作者约定；注册前到达的指令会被缓冲补投。
      */
     onCommand(action: string, handler: CommandHandler): () => void;
+    /**
+     * 声明当前应用提供的页面上下文和业务 CLI。
+     *
+     * CLI 安装成功后才保存 getContext；之后每次 send 前恰好读取一次。
+     */
+    attachApp(options: AttachAppOptions): Promise<AppCliAttachment | null>;
     /** 发送一条消息。字符串或多模态内容均可。 */
     send(content: MessageContent, options?: SendOptions): Promise<void>;
+    private sendUnlocked;
     /** 智能体运行期间追加补充说明（不打断当前回复）。 */
     append(text: string): void;
     /** 停止当前回复。 */

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

@@ -27,6 +27,9 @@ export declare namespace ChatSendPayloadSchema {
     type RuntimeEnv = ({
         [k: string]: string;
     } | null);
+    type AppContext = ({
+        [k: string]: unknown;
+    } | null);
     type CompactionRatio = (number | null);
     interface ChatSendPayload {
         session_id: SessionId;
@@ -41,6 +44,7 @@ export declare namespace ChatSendPayloadSchema {
         whatif?: (WhatIfPayload | null);
         replay_decision?: ReplayDecision;
         runtime_env?: RuntimeEnv;
+        app_context?: AppContext;
         compaction_ratio?: CompactionRatio;
         [k: string]: unknown;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blade-hq/agent-client",
-  "version": "1.1.12-beta.3",
+  "version": "1.2.0-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 会校验两者。
 
-共 111 个公开声明。
+共 114 个公开声明。
 
 ## `ActiveCompactionState` (interface)
 
@@ -37,6 +37,7 @@ toolCallId: string
 ```ts
 append: (text: string) => void
 attach: (label: string, data: unknown) => void
+attachApp: (options: AttachAppOptions) => Promise<AppCliAttachment | null>
 compact: () => Promise<Record<string, unknown>>
 countFiles: (dirPath?: string) => Promise<number>
 dispose: () => void
@@ -84,6 +85,23 @@ toolResult: { toolCall: ToolCallInfo; turn: TurnProjection; }
 workspaceChanged: { filePath?: string; }
 ```
 
+## `AppCliAttachment` (interface)
+
+```ts
+command: string
+digest: string
+runtime: "python" | "executable"
+```
+
+## `AppCliDefinition` (interface)
+
+```ts
+command: string
+filename: string | undefined
+runtime: "python" | "executable"
+source: string | Blob | URL
+```
+
 ## `ArchivedFileInfo` (interface)
 
 ```ts
@@ -119,6 +137,13 @@ export type AsrAudioPayload =
   | { pcm: ArrayBuffer | Uint8Array; request_id?: string }
 ```
 
+## `AttachAppOptions` (interface)
+
+```ts
+cli: AppCliDefinition | undefined
+getContext: () => Record<string, unknown> | Promise<Record<string, unknown>>
+```
+
 ## `AuthResource` (class)
 
 ```ts
@@ -857,6 +882,7 @@ export type SessionSetupStage = "solution" | "session" | "skill" | "connection"
 ## `SessionsResource` (class)
 
 ```ts
+attachAppCli: (sessionId: string, definition: AppCliDefinition) => Promise<AppCliAttachment>
 checkoutSession: (sessionId: string, checkpointId: string, position: "before" | "turn_end", mode?: "both" | "conversation" | "code", linear?: boolean) => Promise<{ id: string; content: string; position: string; mode?: string; files_restored?: boolean; linear?: boolean; }>
 connect: (sessionId: string) => Promise<AgentSession>
 copyFile: (sessionId: string, filePath: string) => Promise<{ path: string; }>
@@ -887,7 +913,7 @@ listSessionsPaginated: (params: { limit: number; offset: number; template_id_pre
 listSessionsWithSkillData: () => Promise<SkillDevSession[]>
 pinSession: (sessionId: string, pinned: boolean) => Promise<SessionInfo>
 previewImport: (file: File) => Promise<ImportPreview>
-probeSessionUrl: (sessionId: string, url: string) => Promise<{ reachable: boolean; }>
+probeSessionUrl: (sessionId: string, url: string) => Promise<{ reachable: boolean; requires_proxy: boolean; }>
 renameFile: (sessionId: string, filePath: string, newName: string) => Promise<{ path: string; }>
 revokeShare: (sessionId: string, token: string) => Promise<{ revoked: boolean; }>
 rewindSession: (sessionId: string, checkpointId: string) => Promise<{ id: string; content: string; }>