@blade-hq/agent-client 2608.0.2 → 2608.0.3

package/dist/resources/auth.d.ts

@@ -16,6 +16,24 @@ export interface ProvidersResponse {
     }>;
     password_enabled: boolean;
 }
+export interface ExchangeCodeParams {
+    /** 授权回调页 postMessage 回来的一次性 code。 */
+    code: string;
+    /** 发起授权时用的 state，必须原样传回。 */
+    state: string;
+    /** 发起授权的页面 origin，要和 authorize 时传的 `client_origin` 完全一致。 */
+    clientOrigin: string;
+}
+export interface ExchangeCodeResult {
+    access_token: string;
+    token_type: string;
+    user: {
+        id: string;
+        username: string;
+        display_name: string;
+        avatar_url: string | null;
+    };
+}
 export declare class AuthResource {
     private client;
     constructor(client: BladeClient);
@@ -24,6 +42,14 @@ export declare class AuthResource {
      * 自动取得 PAT 并热挂载到当前 client。等价于 client.login()。
      */
     login(options?: LoginOptions): Promise<LoginResult>;
+    /**
+     * 用一次性 code 换 PAT。给**服务端**用：浏览器把 code 交给你自己的后端，
+     * 后端换到的 PAT 不进浏览器。浏览器里直接用 `login()` 就够了。
+     *
+     * 服务端调用时会自己补上 `Origin` 头（浏览器会自动带，服务端不会，缺了
+     * 后端报 `missing_request_origin`）。
+     */
+    exchangeCode(params: ExchangeCodeParams): Promise<ExchangeCodeResult>;
     /** 清除 login() 存储的令牌。 */
     logoutToken(): void;
     getProviders(): Promise<ProvidersResponse>;

package/dist/resources/models.d.ts

@@ -6,6 +6,12 @@ export interface ModelOption {
 export interface ModelCatalog {
     default: string;
     models: ModelOption[];
+    /**
+     * 平台默认模型服务的 OpenAI 兼容地址（Server ≥ 提供 `baseUrl` 的版本才有，否则为空）。
+     * 自建应用可以带用户的 PAT 直接调它，不必让用户自己填地址——网关端口各部署不同，
+     * 推算不出来。
+     */
+    baseUrl?: string;
 }
 /** Server 可供当前用户选择的模型目录。 */
 export declare class ModelsResource {

package/dist/resources/sessions.d.ts

@@ -1,6 +1,6 @@
 import type { BackgroundTask, BackgroundTaskStopResult } from "../schemas/background";
 import type { TurnProjection } from "../schemas/projection";
-import type { PublishedSolutionRef, SessionDetail, SessionInfo, TemplateId } from "../schemas/session";
+import type { PublishedSolutionRef, ReplayPreview, ReplaySpeed, 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";
@@ -203,15 +203,17 @@ export declare class SessionsResource {
     }): Promise<SessionDetail>;
     setSessionEnv(sessionId: string, env: Record<string, string>): Promise<SessionDetail>;
     pinSession(sessionId: string, pinned: boolean): Promise<SessionInfo>;
-    startReplaySession(sourceSessionId: string, speed?: 1 | 2 | 5): Promise<{
+    startReplaySession(sourceSessionId: string, speed?: ReplaySpeed): Promise<{
         session_id: string;
     }>;
     updateReplaySession(sessionId: string, payload: {
-        speed?: 1 | 2 | 5;
+        speed?: ReplaySpeed;
         status?: "autonomous";
     }): Promise<{
         replay_state: SessionInfo["replay_state"];
     }>;
+    /** 查询会话能否作为回放来源；不支持时 reason 可直接展示，用来提前禁用入口。 */
+    getReplayPreview(sessionId: string): Promise<ReplayPreview>;
     updateSharing(sessionId: string, shared: boolean): Promise<{
         shared: boolean;
     }>;

package/dist/schemas/message-utils.d.ts

@@ -12,11 +12,21 @@ export declare function buildMessageContent(text: string, attachments: Array<{
     mimeType?: string;
 }>): MessageContent;
 export declare function contentPreview(content: MessageContent, maxLen?: number): string;
+/** `/` 选中的技能当前处于什么状态，决定智能体要不要先装、先加载。 */
+export interface SkillMentionAvailability {
+    /** 本地已有（内置 / 技能目录 / 会话已加载），直接可用。 */
+    local?: boolean;
+    /** Blade Hub 上该账号是否已安装。本地技能恒为 true。 */
+    installed?: boolean;
+}
 /**
  * Transform a skill mention into a natural language skill invocation.
  * Strips the `<skill>name</skill>` tag from the raw input and prepends the instruction.
+ *
+ * Hub 技能装没装、加载没加载，用户不需要知道，但智能体需要——所以把状态翻译
+ * 成它能直接照做的 CLI 步骤。不传 availability 时按本地技能处理，与旧行为一致。
  */
-export declare function transformSlashCommand(skillName: string, rawInput: string): string;
+export declare function transformSlashCommand(skillName: string, rawInput: string, { local, installed }?: SkillMentionAvailability): string;
 export interface ParsedTextAttachment {
     name: string;
     uploadedPath?: string;

package/dist/schemas/session.d.ts

@@ -12,14 +12,31 @@ export type PublishedSolutionRef = {
     org: string;
     name: string;
 };
+/** 回放时录制内容的播放倍速。 */
+export type ReplaySpeed = 1 | 2 | 5;
+/**
+ * 新建回放会话时的默认倍速。
+ *
+ * 所有创建入口都用它——曾经侧栏走 API 默认 5x、设置菜单初始化成 1x，
+ * 同一个源对话从不同入口开出来速度不一样。
+ */
+export declare const DEFAULT_REPLAY_SPEED: ReplaySpeed;
 export interface ReplayState {
     source_session_id?: string;
     status?: "replay" | "autonomous";
-    speed?: 1 | 2 | 5;
+    speed?: ReplaySpeed;
     next_source_entry_id?: string | null;
     ended_at?: string | null;
     autonomous_reason?: string | null;
 }
+/** 某个会话能否作为回放来源。 */
+export interface ReplayPreview {
+    session_id: string;
+    intent?: string | null;
+    supported: boolean;
+    /** supported 为 false 时给出的原因，可直接展示给用户。 */
+    reason?: string | null;
+}
 export interface SessionPortMapping {
     container_port: number;
     host_port: number;

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

@@ -1,7 +1,7 @@
 import { type RawEvent } from "../shared/projection";
 import type { MessageContent } from "../schemas/message";
 import type { PatchEnvelope, TurnProjection } from "../schemas/projection";
-import type { SessionStatus } from "../schemas/session";
+import type { ReplaySpeed, ReplayState, SessionStatus } from "../schemas/session";
 import { type CommandHandler } from "../commands/registry";
 import { type AgentSessionEvents } from "./events";
 import type { AppCliAttachment, AppCliDefinition, FileEntry } from "../resources/sessions";
@@ -12,6 +12,15 @@ export interface SessionRuntime {
     emitWithAck(event: string, data: unknown, timeoutMs: number): Promise<Record<string, unknown> | undefined>;
     ensureConnected(): void;
     fetchTurns(sessionId: string): Promise<TurnProjection[]>;
+    /** 会话详情，目前只用来取回放状态。 */
+    fetchSessionInfo(sessionId: string): Promise<{
+        replay_state?: ReplayState | null;
+        viewer_role?: "owner" | "viewer";
+    }>;
+    updateReplay(sessionId: string, payload: {
+        speed?: ReplaySpeed;
+        status?: "autonomous";
+    }): Promise<ReplayState | null>;
     listDir(sessionId: string, dirPath: string): Promise<FileEntry[]>;
     countFiles(sessionId: string, dirPath?: string): Promise<number>;
     downloadFile(sessionId: string, filePath: string, downloadName?: string): Promise<void>;
@@ -65,6 +74,7 @@ export declare class AgentSession {
     private patchFlushCancel;
     private joined;
     private joinPending;
+    private replayQueue;
     private pendingReplayMessage;
     private pendingReplayMode;
     private recentChatEndAt;
@@ -139,6 +149,16 @@ export declare class AgentSession {
     _rejoinAfterReconnect(): Promise<void>;
     /** @internal 首次连接：加载历史 + 加入房间。 */
     _bootstrap(): Promise<void>;
+    /** 改回放是 owner 专属（服务端 PATCH 走 _get_owned_session）。 */
+    private get canControlReplay();
+    /** 拉一次会话详情，填回放状态和只读身份；失败按非回放会话处理，不挡启动。 */
+    private syncReplayFromSession;
+    /** 调整回放倍速；不是回放会话、或只读身份时什么都不做。 */
+    setReplaySpeed(speed: ReplaySpeed): Promise<void>;
+    /** 退出回放，之后的对话交给真实模型运行；不是回放会话、或只读身份时什么都不做。 */
+    exitReplay(): Promise<void>;
+    /** 把一次回放控制请求排进队列；前一个完成后才发出，响应直接安装。 */
+    private applyReplayControl;
     /** @internal */
     _handleTurnStart(turn: TurnProjection): void;
     /** @internal */

package/dist/session/state.d.ts

@@ -1,6 +1,6 @@
 import type { ChatMessage, CompactionInfo, MessageContent } from "../schemas/message";
 import type { ContentBlock, PatchEnvelope, TurnProjection } from "../schemas/projection";
-import type { SessionStatus } from "../schemas/session";
+import type { ReplaySpeed, ReplayState, SessionStatus } from "../schemas/session";
 /** 一次 AskUserQuestion 的用户作答（选项选择 + 自定义输入）。 */
 export interface AskUserAnswerData {
     selections: Record<number, number[]>;
@@ -39,7 +39,20 @@ export interface SessionState {
     askAnswers: Record<string, AskUserAnswerData>;
     agentLoops: Record<string, AgentLoopInfo>;
     activeCompaction: ActiveCompactionState | null;
+    /** 回放（演示 / 彩排）状态；不是回放会话时为 null。 */
+    replay: ReplaySnapshot | null;
+    /** 当前身份对这个会话的权限；"viewer" 表示只读（分享链接打开的）。 */
+    viewerRole: "owner" | "viewer" | null;
 }
+/** 回放会话的快照视图，由服务端的 replay_state 归一化而来。 */
+export interface ReplaySnapshot {
+    /** 仍在按录制内容走；转自主运行后为 false。 */
+    isReplay: boolean;
+    speed: ReplaySpeed;
+    sourceSessionId: string | null;
+}
+/** 把服务端的 replay_state 归一化成快照；不是回放会话时返回 null。 */
+export declare function toReplaySnapshot(raw: ReplayState | null | undefined): ReplaySnapshot | null;
 export declare function createInitialSessionState(sessionId: string): SessionState;
 export declare function extractModeFromBlocks(blocks: ContentBlock[]): "planning" | "executing" | null;
 /**

package/dist/shared/projection/helpers.d.ts

@@ -26,6 +26,13 @@ export declare function sourceLoopFor(loopId: string, loopDescriptions: Map<stri
     loop_name: string;
     description: string;
 } | null;
+/** 本轮交付给用户的成果：工作区里的文件，或可以打开的网址。 */
+export interface FinalArtifact {
+    kind: "file" | "link";
+    /** file 是文件路径（相对工作目录或容器内绝对路径）；link 是 http/https 网址。 */
+    target: string;
+    label: string;
+}
 /**
  * Shared by the streaming and history channels — both must decide "is this
  * follow-up showable" identically. Returns null when there is nothing to show.
@@ -34,6 +41,7 @@ export declare function normalizePostChatFollowup(data: Record<string, unknown>,
     assistant_entry_id: string;
     recaption: string;
     suggestions: string[];
+    final_artifacts: FinalArtifact[];
 } | null;
 export declare function normalizeChildPause(pausePayload: Record<string, unknown>): {
     pauseToolData: Record<string, unknown>;

package/package.json

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

package/public-api.md

@@ -3,7 +3,7 @@
 > 本文件由 `scripts/public-api-report.mjs` 生成，请勿手改。
 > 公共面变更时重新生成本报告，并同步更新 README 对应章节——CI 会校验两者。
 
-共 117 个公开声明。
+共 126 个公开声明。
 
 ## `ActiveCompactionState` (interface)
 
@@ -42,6 +42,7 @@ compact: () => Promise<Record<string, unknown>>
 countFiles: (dirPath?: string) => Promise<number>
 dispose: () => void
 downloadFile: (filePath: string, downloadName?: string) => Promise<void>
+exitReplay: () => Promise<void>
 getState: () => SessionState
 insertText: (text: string) => void
 isDisposed: boolean
@@ -51,6 +52,7 @@ on: <K extends keyof AgentSessionEvents>(name: K, handler: (event: AgentSessionE
 onCommand: (action: string, handler: CommandHandler) => () => void
 send: (content: MessageContent, options?: SendOptions) => Promise<boolean>
 sessionId: string
+setReplaySpeed: (speed: ReplaySpeed) => Promise<void>
 stop: () => Promise<Record<string, unknown>>
 subscribe: (listener: () => void) => () => void
 ```
@@ -147,6 +149,7 @@ getContext: () => Record<string, unknown> | Promise<Record<string, unknown>>
 ## `AuthResource` (class)
 
 ```ts
+exchangeCode: (params: ExchangeCodeParams) => Promise<ExchangeCodeResult>
 getMe: () => Promise<UserInfo>
 getProviders: () => Promise<ProvidersResponse>
 login: (options?: LoginOptions) => Promise<LoginResult>
@@ -376,6 +379,12 @@ path: string | undefined
 token: string | (() => string | null | undefined) | undefined
 ```
 
+## `DEFAULT_REPLAY_SPEED` (const)
+
+```ts
+DEFAULT_REPLAY_SPEED: ReplaySpeed
+```
+
 ## `EmbeddedChat` (interface)
 
 ```ts
@@ -393,6 +402,22 @@ allowedOrigins: string[]
 iframe: HTMLIFrameElement | undefined
 ```
 
+## `ExchangeCodeParams` (interface)
+
+```ts
+clientOrigin: string
+code: string
+state: string
+```
+
+## `ExchangeCodeResult` (interface)
+
+```ts
+access_token: string
+token_type: string
+user: { id: string; username: string; display_name: string; avatar_url: string | null; }
+```
+
 ## `ExistingSolutionRef` (interface)
 
 ```ts
@@ -571,6 +596,7 @@ export type ModeId = "planning" | "executing"
 ## `ModelCatalog` (interface)
 
 ```ts
+baseUrl: string | undefined
 default: string
 models: ModelOption[]
 ```
@@ -689,6 +715,40 @@ payload: Record<string, unknown>
 type: string
 ```
 
+## `ReplayPreview` (interface)
+
+```ts
+intent: string | null | undefined
+reason: string | null | undefined
+session_id: string
+supported: boolean
+```
+
+## `ReplaySnapshot` (interface)
+
+```ts
+isReplay: boolean
+sourceSessionId: string | null
+speed: ReplaySpeed
+```
+
+## `ReplaySpeed` (type)
+
+```ts
+export type ReplaySpeed = 1 | 2 | 5
+```
+
+## `ReplayState` (interface)
+
+```ts
+autonomous_reason: string | null | undefined
+ended_at: string | null | undefined
+next_source_entry_id: string | null | undefined
+source_session_id: string | undefined
+speed: ReplaySpeed | undefined
+status: "replay" | "autonomous" | undefined
+```
+
 ## `RunOptions` (interface)
 
 ```ts
@@ -925,6 +985,7 @@ downloadFile: (sessionId: string, filePath: string, downloadName?: string) => Pr
 exportSession: (sessionId: string) => Promise<void>
 getBackgroundTask: (sessionId: string, taskId: string, tail?: number, init?: RequestInit) => Promise<BackgroundTask>
 getDownloadDirUrl: (sessionId: string, dirPath: string) => string
+getReplayPreview: (sessionId: string) => Promise<ReplayPreview>
 getSession: (sessionId: string, init?: RequestInit) => Promise<SessionDetail>
 getSessionCheckpoints: (sessionId: string, init?: RequestInit) => Promise<{ nodes: CheckpointNode[]; leaf_id: string | null; }>
 getSessionContextStats: (sessionId: string, init?: RequestInit) => Promise<SessionContextStats>
@@ -946,12 +1007,12 @@ revokeShare: (sessionId: string, token: string) => Promise<{ revoked: boolean; }
 rewindSession: (sessionId: string, checkpointId: string) => Promise<{ id: string; content: 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; }>
+startReplaySession: (sourceSessionId: string, speed?: ReplaySpeed) => Promise<{ session_id: string; }>
 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>
-updateReplaySession: (sessionId: string, payload: { speed?: 1 | 2 | 5; status?: "autonomous"; }) => Promise<{ replay_state: SessionInfo["replay_state"]; }>
+updateReplaySession: (sessionId: string, payload: { speed?: ReplaySpeed; status?: "autonomous"; }) => Promise<{ replay_state: SessionInfo["replay_state"]; }>
 updateSession: (sessionId: string, payload: { intent?: string; }) => Promise<SessionDetail>
 updateSessionMemory: (sessionId: string, memoryEnabled: boolean) => Promise<{ memory_enabled: boolean; }>
 updateSharing: (sessionId: string, shared: boolean) => Promise<{ shared: boolean; }>
@@ -970,9 +1031,11 @@ errorMessage: string | null
 isStreaming: boolean
 messages: ChatMessage[]
 mode: "planning" | "executing" | null
+replay: ReplaySnapshot | null
 sessionId: string
 status: "completed" | "failed" | "interrupted" | "running" | "created" | "waiting_for_input" | null
 turns: TurnProjection[]
+viewerRole: "owner" | "viewer" | null
 ```
 
 ## `SessionStatus` (type)
@@ -998,6 +1061,13 @@ files: TextFile[]
 name: string
 ```
 
+## `SkillMentionAvailability` (interface)
+
+```ts
+installed: boolean | undefined
+local: boolean | undefined
+```
+
 ## `Solution` (interface)
 
 ```ts
@@ -1141,10 +1211,16 @@ result: unknown
 status: "done" | "error" | "cancelled" | "awaiting_answer" | "pending" | undefined
 ```
 
+## `toReplaySnapshot` (function)
+
+```ts
+toReplaySnapshot: (raw: ReplayState | null | undefined) => ReplaySnapshot | null
+```
+
 ## `transformSlashCommand` (function)
 
 ```ts
-transformSlashCommand: (skillName: string, rawInput: string) => string
+transformSlashCommand: (skillName: string, rawInput: string, { local, installed }?: SkillMentionAvailability) => string
 ```
 
 ## `TurnProjection` (interface)