@blade-hq/agent-client 2608.0.2 → 2608.0.3

package/README.md

@@ -76,6 +76,15 @@ await client.auth.getProviders() // 服务端支持的登录方式
 
 `login()` 失败时的错误都带中文原因：弹窗被拦截、窗口被关闭、超时。
 
+令牌要留在自己的服务端时，浏览器只把授权回调拿到的一次性 code 交给后端，由后端换：
+
+```ts
+// ExchangeCodeParams -> ExchangeCodeResult
+const { access_token } = await client.auth.exchangeCode({ code, state, clientOrigin })
+```
+
+`clientOrigin` 要和发起授权时用的 origin 一致；服务端调用会自动补 `Origin` 头。
+
 ## 会话：client.sessions
 
 ### 实时对话（推荐入口）
@@ -130,6 +139,73 @@ await client.sessions.deleteSession(id)
 await client.sessions.getSessionTurns(id)             // 历史消息（投影格式，与实时流同构）
 ```
 
+### 会话回放（演示 / 彩排）
+
+拿一个已经聊完的会话当素材，重现当时的回复和工具调用，**完全不调用模型**。
+用来做演示和彩排：离线可跑、不花钱、不会临场翻车。
+
+**它不是把现有会话切成回放模式，而是派生一个新会话**，源会话原样不动：
+
+```ts
+// 1. 能不能拿它当素材（有并行子智能体、运行快照不完整的不行）
+const { supported, reason } = await client.sessions.getReplayPreview(sourceId)
+if (!supported) return show(reason)   // reason 可直接展示给用户
+
+// 2. 派生回放会话——这一步才是"进入回放"，返回的是一个全新的 session_id
+const { session_id: replayId } = await client.sessions.startReplaySession(sourceId)
+const fast = await client.sessions.startReplaySession(sourceId, 2)  // 或显式 1 | 2 | 5
+
+// 3. 连上它，一出生就带着 replay 状态
+const session = await client.sessions.connect(replayId)
+session.getState().replay
+// → { isReplay: true, speed: 5, sourceSessionId: sourceId }
+```
+
+不传倍速时用 `DEFAULT_REPLAY_SPEED`；所有创建入口都该用它，免得同一个源对话
+从不同入口开出来速度不一样。
+
+**连上之后不会自动播——它跟用户对台词**（下面的 `session` 都是第 3 步连上的**回放会话**）：
+
+```ts
+// 源会话当初第一句问的是"帮我查下当前目录"
+await session.send("帮我查下当前目录")   // 对得上：按倍速重现当时的回复和工具调用
+await session.send("今天天气怎么样")     // 对不上：抛 replayMismatch 等你决定（见下）
+```
+
+**回放中的状态和动作**都挂在会话上，和 `send()` 同级：
+
+```ts
+session.getState().replay      // { isReplay, speed, sourceSessionId } | null（不是回放会话）
+session.getState().viewerRole  // "viewer" 表示只读，改不动回放
+await session.setReplaySpeed(2)
+await session.exitReplay()     // 退出回放，之后的对话真的运行
+```
+
+改回放是 owner 专属（服务端 `PATCH` 走 owner 校验），只读身份下这两个动作是 no-op。
+
+`replay` 是 `SessionState` 的一部分，跟着快照订阅走——Vue 直接接 `shallowRef` 即可，
+不用自己拉状态：
+
+```ts
+const state = shallowRef(session.getState())   // session = connect(replayId) 的返回值
+session.subscribe(() => (state.value = session.getState()))
+// 模板里 state.value.replay?.isReplay / state.value.replay?.speed
+```
+
+连接会话时会一并拉好初始回放状态，所以第一帧就知道自己在不在回放。
+
+**输入冲突**：用户说的话和录制内容对不上时，服务端会推 `replayMismatch`，必须在事件里给出决定：
+
+```ts
+session.on("replayMismatch", ({ expectedMessage, actualMessage, respond }) => {
+  respond("keep_replay")      // 按录制内容继续
+  // respond("continue_replay")  // 从这里开始真的运行
+})
+```
+
+`replayMismatch` **只交给最先注册的处理器**；一个都没注册时默认 `continue_replay`
+（静默转为真实运行）。React 应用可直接用 `@blade-hq/agent-react` 的 `useReplay()`。
+
 ### 工作区文件
 
 ```ts
@@ -151,8 +227,10 @@ await chat.downloadFile("输出/简历.md", "简历.md") // 浏览器下载
 ### 模型目录
 
 ```ts
-const { default: defaultModel, models } = await client.models.list()
+const { default: defaultModel, models, baseUrl } = await client.models.list()
 // models: Array<{ id, label }>
+// baseUrl: 平台默认模型服务的 OpenAI 兼容地址，自建应用带用户令牌可直接调；
+//          各部署端口不同，别写死，老版本 Server 返回空串。
 ```
 
 ## AgentSession
@@ -171,6 +249,8 @@ chat.getState()
 //   mode,            "planning" | "executing" | null
 //   connection,      连接状态："connected" | "connecting" | "reconnecting" | "disconnected"
 //   errorMessage,    最近一次运行错误
+//   replay,          回放状态：{ isReplay, speed, sourceSessionId } | null
+//   viewerRole,      "owner" | "viewer" | null（只读身份改不动会话）
 //   turns, askAnswers, agentLoops, activeCompaction   进阶字段
 // }
 
@@ -365,6 +445,29 @@ function Message({ message }: { message: ChatMessage }) {
 }
 ```
 
+### 让用户挑一个技能来做事
+
+自己实现技能选择器时，用 `transformSlashCommand` 把选中的技能翻译成智能体能执行的一段话：
+
+```ts
+import { transformSlashCommand, type SkillMentionAvailability } from "@blade-hq/agent-client"
+
+transformSlashCommand("org/data-analysis", "分析这份季度报表")
+// "请使用 org/data-analysis skill 完成任务\n分析这份季度报表"
+```
+
+第三个参数说明这个技能眼下能不能直接用。技能装没装、加载没加载，用户不需要知道，但智能体需要——传进来之后它会被翻译成对应的 CLI 步骤：
+
+```ts
+// Blade Hub 上已安装、但当前会话还没加载：要求先 use
+transformSlashCommand(skillId, prompt, { local: false, installed: true })
+
+// Blade Hub 上还没安装：要求先 install 再 use
+transformSlashCommand(skillId, prompt, { local: false, installed: false })
+```
+
+不传第三个参数时按本地已有处理，和不带这个参数的老用法结果一致。
+
 ## 常见问题
 
 | 现象 | 原因与解法 |
@@ -386,9 +489,10 @@ function Message({ message }: { message: ChatMessage }) {
 - **声明式会话**：`SessionDefinition`、`SolutionDefinition`、`SkillDefinition`、`SessionConfig`、`TextFile`、`SessionSetupError`、`SessionSetupStage`
 - **模型目录**：`ModelsResource`、`ModelCatalog`、`ModelOption`
 - **会话资源（REST）**：`SessionsResource`、`CreateSessionRequest`、`ImportSessionOptions`、`AppCliDefinition`、`AppCliAttachment`、`AttachAppOptions`、`PaginatedSessionsResult`、`SessionHistory`、`SessionContextStats`、`ShareLinkResult`、`FileEntry`、`UploadFileEntry`、`UploadFilesOptions`、`SessionProfile`、`SessionDetail`、`SessionInfo`、`SessionStatus`、`SessionPortMapping`、`ModeId`、`TemplateId`、`PrimarySkillSnapshot`、`PrimarySkillParallelMode`
+- **会话回放**：`ReplayState`、`ReplaySpeed`、`ReplayPreview`、`ReplaySnapshot`、`toReplaySnapshot`、`DEFAULT_REPLAY_SPEED`
 - **会话状态机**：`SessionHub`、`SessionState`、`SendOptions`、`ConnectionStatus`、`AskUserAnswerData`、`AgentLoopInfo`、`ActiveCompactionState`、`createInitialSessionState`、`AgentSessionEventName`
 - **页面协作**：`EmbeddedChat`、`EmbeddedChatOptions`、`CommandHandler`、`CommandEnvelope`、`InboundAction`、`InboundEnvelope`、`isCommandEnvelope`、`isInboundEnvelope`
-- **消息与投影协议**：`MessageContent`、`MessageContentPart`、`TextContentPart`、`ImageUrlContentPart`、`FileContentPart`、`ToolCallInfo`、`ToolBridgeContent`、`CompactionInfo`、`MemoryRefInfo`、`ArchivedFileInfo`、`ArchivedToolCallInfo`、`TurnProjection`、`ContentBlock`、`PatchEnvelope`、`MemoryRef`、`buildMessageContent`、`normalizeMessageContent`、`isHiddenInternalMessage`、`transformSlashCommand`、`extractTextAttachments`、`ParsedTextAttachment`、`ParsedTextContext`
+- **消息与投影协议**：`MessageContent`、`MessageContentPart`、`TextContentPart`、`ImageUrlContentPart`、`FileContentPart`、`ToolCallInfo`、`ToolBridgeContent`、`CompactionInfo`、`MemoryRefInfo`、`ArchivedFileInfo`、`ArchivedToolCallInfo`、`TurnProjection`、`ContentBlock`、`PatchEnvelope`、`MemoryRef`、`buildMessageContent`、`normalizeMessageContent`、`isHiddenInternalMessage`、`transformSlashCommand`、`SkillMentionAvailability`、`extractTextAttachments`、`ParsedTextAttachment`、`ParsedTextContext`
 - **Solution / 任务协议**：`Solution`、`SolutionAppField`、`SolutionAppState`、`SolutionAppUiConfig`、`SolutionRef`、`PublishedSolutionRef`、`ExistingSolutionRef`、`PreparedSolution`、`PreparedSolutionAsset`、`LayoutType`、`BizRole`、`TaskStatus`、`BackgroundTask`、`BackgroundTaskStopResult`
 - **Headless**：`HeadlessResource`、`RunOptions`、`RunResult`、`RunTrace`
 - **低层通道（apps/web 等高级集成）**：`createSocket`、`CreateSocketOptions`、`TypedSocket`、`AsrAudioPayload`、`ClientProjectionBuilder`、`RawEvent`

package/dist/index.d.ts

@@ -9,14 +9,14 @@ export { SessionHub } from "./session/hub";
 export type { AgentSessionEvents, AgentSessionEventName } from "./session/events";
 export { SessionSetupError } from "./session/definition";
 export type { SessionConfig, SessionDefinition, SessionSetupStage, SkillDefinition, TextFile, SolutionDefinition, } from "./session/definition";
-export { createInitialSessionState } from "./session/state";
-export type { AskUserAnswerData, AgentLoopInfo, ActiveCompactionState, ConnectionStatus, SessionState, } from "./session/state";
+export { createInitialSessionState, toReplaySnapshot } from "./session/state";
+export type { AskUserAnswerData, AgentLoopInfo, ActiveCompactionState, ConnectionStatus, ReplaySnapshot, SessionState, } from "./session/state";
 export { connectEmbedded } from "./commands/embedded";
 export type { EmbeddedChat, EmbeddedChatOptions } from "./commands/embedded";
 export type { CommandHandler } from "./commands/registry";
 export type { CommandEnvelope, InboundAction, InboundEnvelope } from "./commands/protocol";
 export { isCommandEnvelope, isInboundEnvelope } from "./commands/protocol";
-export type { AuthResource, ProvidersResponse, UserInfo } from "./resources/auth";
+export type { AuthResource, ExchangeCodeParams, ExchangeCodeResult, ProvidersResponse, UserInfo, } from "./resources/auth";
 export type { HeadlessResource } from "./resources/headless";
 export { ModelsResource } from "./resources/models";
 export type { ModelCatalog, ModelOption } from "./resources/models";
@@ -24,10 +24,11 @@ export type { SessionsResource } from "./resources/sessions";
 export type { CreateSessionRequest, AppCliAttachment, AppCliDefinition, FileEntry, ImportSessionOptions, PaginatedSessionsResult, SessionContextStats, SessionHistory, ShareLinkResult, UploadFileEntry, UploadFilesOptions, } from "./resources/sessions";
 export type { ArchivedFileInfo, ArchivedToolCallInfo, ChatMessage, CompactionInfo, FileContentPart, ImageUrlContentPart, MemoryRefInfo, MessageContent, MessageContentPart, TextContentPart, ToolBridgeContent, ToolCallInfo, } from "./schemas/message";
 export { buildMessageContent, contentPreview, extractTextAttachments, getFileParts, getImageParts, getTextContent, groupMessagesByLoop, isHiddenInternalMessage, normalizeMessageContent, transformSlashCommand, } from "./schemas/message-utils";
-export type { ParsedTextAttachment, ParsedTextContext } from "./schemas/message-utils";
+export type { ParsedTextAttachment, ParsedTextContext, SkillMentionAvailability, } from "./schemas/message-utils";
 export type { ContentBlock, MemoryRef, PatchEnvelope, TurnProjection } from "./schemas/projection";
+export { DEFAULT_REPLAY_SPEED } from "./schemas/session";
 export { SessionInfo, SessionStatus } from "./schemas/session";
-export type { ModeId, PrimarySkillParallelMode, PrimarySkillSnapshot, SessionDetail, SessionPortMapping, PublishedSolutionRef, TemplateId, } from "./schemas/session";
+export type { ModeId, PrimarySkillParallelMode, PrimarySkillSnapshot, ReplayPreview, ReplaySpeed, ReplayState, SessionDetail, SessionPortMapping, PublishedSolutionRef, TemplateId, } from "./schemas/session";
 export { LayoutType } from "./schemas/solution";
 export type { BizRole, Solution, SolutionAppField, SolutionAppState, SolutionAppUiConfig, } from "./schemas/solution";
 export { Task, TaskStatus } from "./schemas/task";

package/dist/index.js

@@ -2,6 +2,9 @@
 function isAuthCallbackMessage(value) {
   return typeof value === "object" && value !== null && value.type === "blade-agent:sdk-auth";
 }
+var AUTH_ERROR_HINTS = {
+  pat_unavailable: "\u6CA1\u80FD\u4E3A\u4F60\u51C6\u5907\u8BBF\u95EE\u51ED\u636E\u3002\u8BF7\u9000\u51FA\u540E\u91CD\u65B0\u767B\u5F55 Blade \u518D\u8BD5\u4E00\u6B21\uFF1B\u82E5\u4ECD\u7136\u5931\u8D25\uFF0C\u8BF7\u8054\u7CFB\u7BA1\u7406\u5458\u3002"
+};
 function randomState() {
   const bytes = new Uint8Array(24);
   crypto.getRandomValues(bytes);
@@ -79,18 +82,22 @@ async function loginWithPopup(client, options = {}) {
       if (event.data.state !== state) return;
       const message = event.data;
       stopCloseWatch();
-      try {
-        popup.close();
-      } catch {
-      }
+      const closePopup = () => {
+        try {
+          popup.close();
+        } catch {
+        }
+      };
       if (message.status === "denied") {
+        closePopup();
         settle(() => reject(new Error("\u4F60\u53D6\u6D88\u4E86\u6388\u6743\uFF0C\u672A\u5B8C\u6210\u767B\u5F55\u3002")));
         return;
       }
       if (message.status !== "success" || !message.code) {
-        settle(() => reject(new Error(message.error || "\u767B\u5F55\u5931\u8D25\uFF0C\u672A\u53D6\u5F97\u6388\u6743\u7801\u3002")));
+        settle(() => reject(new Error(AUTH_ERROR_HINTS[message.error ?? ""] ?? message.error ?? "\u767B\u5F55\u5931\u8D25\uFF0C\u672A\u53D6\u5F97\u6388\u6743\u7801\u3002")));
         return;
       }
+      closePopup();
       client.json("POST", "/api/auth/sdk/token", {
         code: message.code,
         state,
@@ -174,6 +181,24 @@ var AuthResource = class {
   login(options) {
     return this.client.login(options);
   }
+  /**
+   * 用一次性 code 换 PAT。给**服务端**用：浏览器把 code 交给你自己的后端，
+   * 后端换到的 PAT 不进浏览器。浏览器里直接用 `login()` 就够了。
+   *
+   * 服务端调用时会自己补上 `Origin` 头（浏览器会自动带，服务端不会，缺了
+   * 后端报 `missing_request_origin`）。
+   */
+  exchangeCode(params) {
+    return this.client.jsonFromInit("/api/auth/sdk/token", {
+      method: "POST",
+      headers: { Origin: params.clientOrigin },
+      body: JSON.stringify({
+        code: params.code,
+        state: params.state,
+        client_origin: params.clientOrigin
+      })
+    });
+  }
   /** 清除 login() 存储的令牌。 */
   logoutToken() {
     this.client.logoutToken();
@@ -407,6 +432,47 @@ var ModelsResource = class {
   }
 };
 
+// src/schemas/session.ts
+import { type } from "arktype";
+var SessionStatus = type(
+  "'created' | 'running' | 'completed' | 'failed' | 'interrupted' | 'waiting_for_input'"
+);
+var DEFAULT_REPLAY_SPEED = 5;
+var SessionInfo = type({
+  id: "string",
+  intent: "string",
+  status: SessionStatus,
+  created_at: "string",
+  updated_at: "string",
+  "shared?": "boolean",
+  "memory_enabled?": "boolean",
+  "is_persistent?": "boolean",
+  "is_headless?": "boolean",
+  "viewer_role?": "'owner' | 'viewer'",
+  "template_id?": "string | null",
+  "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",
+  "primary_skill_id?": "string | null",
+  // ship-attack v2：后端 engine.set_bound_skill 写入的"绑定 skill id"。
+  // 未绑定 / 非 ship-attack session 为 null。
+  "bound_skill_id?": "string | null",
+  "replay_state?": "unknown",
+  "is_pinned?": "boolean",
+  "pinned_at?": "string | null",
+  "is_example?": "boolean",
+  "ports?": "unknown",
+  "disable_tools?": "string[]",
+  "runtime_type?": "string | null",
+  "daemon_id?": "string | null",
+  "workspace_path?": "string | null",
+  "match?": "unknown"
+});
+
 // src/session/definition.ts
 var SessionSetupError = class extends Error {
   constructor(message, stage, sessionId, options) {
@@ -827,6 +893,28 @@ function sourceLoopFor(loopId, loopDescriptions) {
   if (!description) return null;
   return { loop_name: loopId, description };
 }
+var MAX_FINAL_ARTIFACTS = 3;
+function normalizeFinalArtifacts(raw) {
+  if (!Array.isArray(raw)) return [];
+  const artifacts = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const item of raw) {
+    if (typeof item !== "object" || item === null) continue;
+    const record = item;
+    const target = String(record.target ?? "").trim();
+    if (!target || seen.has(target)) continue;
+    const isLink = /^https?:\/\//i.test(target);
+    if (!isLink && target.split("/").includes("..")) continue;
+    seen.add(target);
+    artifacts.push({
+      kind: isLink ? "link" : "file",
+      target,
+      label: String(record.label ?? "").trim()
+    });
+    if (artifacts.length === MAX_FINAL_ARTIFACTS) break;
+  }
+  return artifacts;
+}
 function normalizePostChatFollowup(data, assistantEntryId) {
   const raw = data.suggestions;
   const suggestions = [];
@@ -838,11 +926,13 @@ function normalizePostChatFollowup(data, assistantEntryId) {
     }
   }
   const recaption = String(data.recaption ?? "");
-  if (suggestions.length === 0 && !recaption) return null;
+  const finalArtifacts = normalizeFinalArtifacts(data.final_artifacts);
+  if (suggestions.length === 0 && !recaption && finalArtifacts.length === 0) return null;
   return {
     assistant_entry_id: assistantEntryId,
     recaption,
-    suggestions: suggestions.slice(0, 3)
+    suggestions: suggestions.slice(0, 3),
+    final_artifacts: finalArtifacts
   };
 }
 function normalizeChildPause(pausePayload) {
@@ -1673,7 +1763,7 @@ function projectHistory(entries) {
         loop_id: loopId,
         kind: "message",
         role,
-        status: message._error ? "failed" : "completed",
+        status: message._error ? "failed" : message._interrupted ? "interrupted" : "completed",
         blocks,
         tool_calls: toolCalls,
         model: stringOrNull(message.model),
@@ -2130,12 +2220,16 @@ var SessionsResource = class {
   pinSession(sessionId, pinned) {
     return this.client.json("PATCH", `/api/sessions/${sessionId}/pin`, { pinned });
   }
-  startReplaySession(sourceSessionId, speed = 5) {
+  startReplaySession(sourceSessionId, speed = DEFAULT_REPLAY_SPEED) {
     return this.client.json("POST", `/api/sessions/${sourceSessionId}/replay`, { speed });
   }
   updateReplaySession(sessionId, payload) {
     return this.client.json("PATCH", `/api/sessions/${sessionId}/replay`, payload);
   }
+  /** 查询会话能否作为回放来源；不支持时 reason 可直接展示，用来提前禁用入口。 */
+  getReplayPreview(sessionId) {
+    return this.client.json("GET", `/api/sessions/${sessionId}/replay/preview`);
+  }
   updateSharing(sessionId, shared) {
     return this.client.json("PATCH", `/api/sessions/${sessionId}/sharing`, { shared });
   }
@@ -2589,10 +2683,15 @@ function contentPreview(content, maxLen = 80) {
   const text = getTextContent(content).trim();
   return text.length > maxLen ? `${text.slice(0, maxLen)}\u2026` : text;
 }
-function transformSlashCommand(skillName, rawInput) {
+function transformSlashCommand(skillName, rawInput, { local = true, installed = true } = {}) {
   const prompt = rawInput.replace(`<skill>${skillName}</skill>`, "").trim();
-  return prompt ? `\u8BF7\u4F7F\u7528 ${skillName} skill \u5B8C\u6210\u4EFB\u52A1
+  if (local) {
+    return prompt ? `\u8BF7\u4F7F\u7528 ${skillName} skill \u5B8C\u6210\u4EFB\u52A1
 ${prompt}` : `\u8BF7\u4F7F\u7528 ${skillName} skill \u5B8C\u6210\u4EFB\u52A1`;
+  }
+  const steps = installed ? `\u8BF7\u5148\u8FD0\u884C blade hub skill use ${skillName} \u52A0\u8F7D\u6280\u80FD` : `\u8BE5\u6280\u80FD\u5C1A\u672A\u5B89\u88C5\u3002\u8BF7\u5148\u8FD0\u884C blade hub skill install ${skillName} \u5B89\u88C5\uFF0C\u518D\u8FD0\u884C blade hub skill use ${skillName} \u52A0\u8F7D`;
+  return prompt ? `${steps}\uFF0C\u7136\u540E\u5B8C\u6210\u4EFB\u52A1\uFF1A
+${prompt}` : `${steps}\uFF0C\u7136\u540E\u4F7F\u7528\u5B83\u5B8C\u6210\u4EFB\u52A1`;
 }
 var ATTACHMENT_TAG_RE = /\[附件:\s*([^\]]+)\](?:[ \t]*已上传到工作区路径:[ \t]*([^\r\n]+))?/g;
 var CONTEXT_PART_RE = /^\[上下文:\s*([^\]]+)\]\n([\s\S]*)$/;
@@ -2678,6 +2777,14 @@ function groupMessagesByLoop(messages) {
 }
 
 // src/session/state.ts
+function toReplaySnapshot(raw) {
+  if (!raw || !raw.status) return null;
+  return {
+    isReplay: raw.status === "replay",
+    speed: raw.speed ?? 1,
+    sourceSessionId: raw.source_session_id ?? null
+  };
+}
 function createInitialSessionState(sessionId) {
   return {
     sessionId,
@@ -2690,7 +2797,9 @@ function createInitialSessionState(sessionId) {
     errorMessage: null,
     askAnswers: {},
     agentLoops: {},
-    activeCompaction: null
+    activeCompaction: null,
+    replay: null,
+    viewerRole: null
   };
 }
 function parseAgentDescription(argumentsJson) {
@@ -3141,6 +3250,11 @@ var AgentSession = class _AgentSession {
   patchFlushCancel = null;
   joined = false;
   joinPending = null;
+  // 回放控制请求排成一条队列。连着点"5x"再点"退出回放"时，并发发出去的两个
+  // 请求响应可能乱序回来，晚到的旧值会把已经退出的会话又显示成回放中；用
+  // 序号丢弃过期响应又会在失败时留下中间态。串行执行就没有这些情况：每个
+  // 响应都是当时最新的，失败也只影响自己。
+  replayQueue = Promise.resolve();
   pendingReplayMessage = null;
   pendingReplayMode;
   recentChatEndAt = 0;
@@ -3171,6 +3285,10 @@ var AgentSession = class _AgentSession {
         emitWithAck: async () => readonlyError(),
         ensureConnected: readonlyError,
         fetchTurns: async () => turns,
+        // 静态历史没有回放身份可言，给个空详情即可，不要抛错——_bootstrap
+        // 不会跑到这里，但保持只读语义一致。
+        fetchSessionInfo: async () => ({ replay_state: null }),
+        updateReplay: async () => readonlyError(),
         listDir: async () => readonlyError(),
         countFiles: async () => readonlyError(),
         downloadFile: async () => readonlyError(),
@@ -3462,10 +3580,13 @@ var AgentSession = class _AgentSession {
     this.joinPending = null;
     try {
       await this.ensureJoined();
-      await this.syncTurnsFromHistory({
-        clearOnEmpty: true,
-        preserveChangesSince: turnsBeforeRejoin
-      });
+      await Promise.all([
+        this.syncTurnsFromHistory({
+          clearOnEmpty: true,
+          preserveChangesSince: turnsBeforeRejoin
+        }),
+        this.syncReplayFromSession()
+      ]);
     } catch {
     }
   }
@@ -3473,6 +3594,40 @@ var AgentSession = class _AgentSession {
   async _bootstrap() {
     await this.syncTurnsFromHistory({ suppressErrors: false });
     await this.ensureJoined();
+    await this.syncReplayFromSession();
+  }
+  /** 改回放是 owner 专属（服务端 PATCH 走 _get_owned_session）。 */
+  get canControlReplay() {
+    return this.state.viewerRole !== "viewer";
+  }
+  /** 拉一次会话详情，填回放状态和只读身份；失败按非回放会话处理，不挡启动。 */
+  async syncReplayFromSession() {
+    try {
+      const info = await this.runtime.fetchSessionInfo(this.sessionId);
+      const replay = toReplaySnapshot(info.replay_state);
+      const viewerRole = info.viewer_role ?? null;
+      this.update((s) => ({ ...s, replay, viewerRole }));
+    } catch {
+    }
+  }
+  /** 调整回放倍速；不是回放会话、或只读身份时什么都不做。 */
+  async setReplaySpeed(speed) {
+    if (!this.state.replay?.isReplay || !this.canControlReplay) return;
+    await this.applyReplayControl({ speed });
+  }
+  /** 退出回放，之后的对话交给真实模型运行；不是回放会话、或只读身份时什么都不做。 */
+  async exitReplay() {
+    if (!this.state.replay?.isReplay || !this.canControlReplay) return;
+    await this.applyReplayControl({ status: "autonomous" });
+  }
+  /** 把一次回放控制请求排进队列；前一个完成后才发出，响应直接安装。 */
+  applyReplayControl(payload) {
+    const run = this.replayQueue.then(async () => {
+      const result = await this.runtime.updateReplay(this.sessionId, payload);
+      this.update((s) => ({ ...s, replay: toReplaySnapshot(result) }));
+    });
+    this.replayQueue = run.catch(() => void 0);
+    return run;
   }
   /** @internal */
   _handleTurnStart(turn) {
@@ -3552,6 +3707,10 @@ var AgentSession = class _AgentSession {
     if (data.status) {
       this.update((s) => ({ ...s, status: data.status ?? s.status }));
     }
+    if (data.replay_state !== void 0) {
+      const replay = toReplaySnapshot(data.replay_state);
+      this.update((s) => ({ ...s, replay }));
+    }
     this.emitter.emit("sessionUpdated", {
       intent: data.intent,
       status: data.status,
@@ -4001,6 +4160,8 @@ var SessionHub = class {
       }),
       ensureConnected: () => this.ensureConnected(),
       fetchTurns: (sessionId) => this.client.sessions.getSessionTurns(sessionId),
+      fetchSessionInfo: (sessionId) => this.client.sessions.getSession(sessionId),
+      updateReplay: (sessionId, payload) => this.client.sessions.updateReplaySession(sessionId, payload).then((result) => result.replay_state ?? null),
       listDir: (sessionId, dirPath) => this.client.sessions.listDir(sessionId, dirPath),
       countFiles: (sessionId, dirPath) => this.client.sessions.countFiles(sessionId, dirPath),
       downloadFile: (sessionId, filePath, downloadName) => this.client.sessions.downloadFile(sessionId, filePath, downloadName),
@@ -4222,7 +4383,7 @@ function resolveAuthToken(options) {
 
 // src/version.ts
 var SDK_NAME = "agent-client";
-var SDK_VERSION = true ? "2608.0.2" : "1.1.1";
+var SDK_VERSION = true ? "2608.0.3" : "1.1.1";
 
 // src/socket.ts
 function withSdkIdentity(auth) {
@@ -4674,46 +4835,6 @@ function connectEmbedded(options) {
   };
 }
 
-// src/schemas/session.ts
-import { type } from "arktype";
-var SessionStatus = type(
-  "'created' | 'running' | 'completed' | 'failed' | 'interrupted' | 'waiting_for_input'"
-);
-var SessionInfo = type({
-  id: "string",
-  intent: "string",
-  status: SessionStatus,
-  created_at: "string",
-  updated_at: "string",
-  "shared?": "boolean",
-  "memory_enabled?": "boolean",
-  "is_persistent?": "boolean",
-  "is_headless?": "boolean",
-  "viewer_role?": "'owner' | 'viewer'",
-  "template_id?": "string | null",
-  "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",
-  "primary_skill_id?": "string | null",
-  // ship-attack v2：后端 engine.set_bound_skill 写入的"绑定 skill id"。
-  // 未绑定 / 非 ship-attack session 为 null。
-  "bound_skill_id?": "string | null",
-  "replay_state?": "unknown",
-  "is_pinned?": "boolean",
-  "pinned_at?": "string | null",
-  "is_example?": "boolean",
-  "ports?": "unknown",
-  "disable_tools?": "string[]",
-  "runtime_type?": "string | null",
-  "daemon_id?": "string | null",
-  "workspace_path?": "string | null",
-  "match?": "unknown"
-});
-
 // src/schemas/solution.ts
 var LayoutType = /* @__PURE__ */ ((LayoutType2) => {
   LayoutType2["Default"] = "default";
@@ -4745,6 +4866,7 @@ export {
   BladeApiError,
   BladeClient,
   ClientProjectionBuilder,
+  DEFAULT_REPLAY_SPEED,
   LayoutType,
   ModelsResource,
   SDK_NAME,
@@ -4769,6 +4891,7 @@ export {
   isHiddenInternalMessage,
   isInboundEnvelope,
   normalizeMessageContent,
+  toReplaySnapshot,
   transformSlashCommand
 };
 //# sourceMappingURL=index.js.map