@blade-hq/agent-client 2610.0.0-beta.51 → 2610.0.0-beta.53

package/README.md

@@ -397,6 +397,7 @@ chat.getState()
 //   connection,      连接状态："connected" | "connecting" | "reconnecting" | "disconnected"
 //   errorMessage,    最近一次运行错误
 //   replay,          回放状态：{ isReplay, speed, sourceSessionId } | null
+//   queue,           等待消息队列快照：{ session_id, revision, paused, pause_reason, items }
 //   viewerRole,      "owner" | "viewer" | null（只读身份改不动会话）
 //   nextBefore, loadingOlder,  历史分页游标与加载状态
 //   turns, askAnswers, agentLoops, activeCompaction   进阶字段
@@ -412,8 +413,8 @@ const unsubscribe = chat.subscribe(() => rerender(chat.getState()))
 ```ts
 const accepted = await chat.send("你好")         // 服务端接受后为 true；拒绝时为 false
 await chat.send("换个方案", { mode: "planning" }) // 指定模式/模型等选项
-chat.append("补充：预算不超过 5 万")              // 智能体运行中追加说明
-await chat.stop()                                // 停止当前回复
+await chat.queueMessage("补充：预算不超过 5 万")   // 运行中入队；返回服务端确认结果与冲突原因
+await chat.stop()                                // 停止当前回复（同时暂停队列，需 resumeQueue 继续）
 await chat.compact()                             // 手动压缩上下文
 if (chat.hasOlderHistory) await chat.loadOlderHistory()
 chat.dispose()                                   // 彻底释放（什么时候该调见下方说明）
@@ -423,6 +424,28 @@ chat.dispose()                                   // 彻底释放（什么时候
 > 1. 用户明确关闭或删除了这个会话，之后不会再回来；
 > 2. 页面长期开着并且会不断创建一次性会话（比如批量任务面板），需要主动回收。
 
+### 等待消息队列
+
+队列由服务端持久化：运行中发送、暂停期间发送都进入队尾，按顺序逐条执行；关掉页面不影响已确认的入队，重新打开恢复真实状态。等待消息**不会**提前伪装成聊天记录——它只在队列区域展示，真正被接收后才进入消息流。
+
+```ts
+const result = await chat.queueMessage("顺便看下这个报错") // 入队（运行中排队 / 暂停期间照常入队）
+// result: { ok, conflict, snapshot, message }
+
+await chat.updateQueuedMessage(item.id, item.version, "改好的正文")
+await chat.reorderQueuedMessages(queue.revision, pendingIdsInNewOrder) // ordered_ids 必须是当前 pending 条目 id 的完整集合
+await chat.cancelQueuedMessage(item.id, item.version)
+await chat.deliverQueuedMessage(item.id, item.version) // 立即补充：交给当前运行在下一个接收点消费
+await chat.resumeQueue()   // 暂停后继续执行
+await chat.refreshQueue()  // 手动拉一份权威快照（首次连接与每次重连已自动拉取）
+```
+
+`chat.getState().queue` 是 `SessionQueueSnapshot`：`{ session_id, revision, paused, pause_reason, items }`。它只会被 revision 更新的快照替换——乱序到达的旧广播不会把新状态顶回去。`items` 只包含 `pending`（待执行）与 `delivering`（等待接收）。
+
+- **冲突处理**：`conflict` 表示乐观并发或状态校验失败，服务端快照已自动刷新到本地，此时保留用户草稿并说明原因即可；`ok=false` 且 `snapshot` 为 null（例如鉴权失败）时不要改动本地队列。`queueMessage` 结果未知（ack 超时）时会用同一个 `client_request_id` 重试一次，不会制造第二条。
+- **可操作性判定**：`canEditQueuedMessage` / `canCancelQueuedMessage` / `canDeliverQueuedMessage` 只对 `pending` 返回 true；文案用 `queuedMessageStatusLabel` 与 `queuePauseReasonLabel`。
+- **自己处理广播**：需要绕过状态机时用 `isSessionQueueSnapshot` + `shouldApplySnapshot` + `EMPTY_SESSION_QUEUE`；解析自定义 ack 用 `parseQueueAck`，返回统一的 `QueueOperationResult`（`QueueAck` 是 ack 的线格式）。
+
 ### 页面协作：让智能体和你的页面互动
 
 **页面状态与业务后端 → 智能体**：
@@ -684,9 +707,11 @@ HTML 一律判无效）；`isInternalStatusToolUiCard` 识别内部「阶段进
 - **声明式会话**：`SessionDefinition`、`SolutionDefinition`、`SkillDefinition`、`SessionConfig`、`TextFile`、`SessionSetupError`、`SessionSetupStage`
 - **模型目录**：`ModelsResource`、`ModelCatalog`、`ModelOption`
 - **聊天项目资源（REST）**：`ChatProjectsResource`、`ChatProject`（含 `delete` 永久删除）
+- **全站访问统计（REST）**：`SiteVisitsResource`、`SiteVisitsSummary`（`client.siteVisits.record()` 上报一次页面访问、`client.siteVisits.summary()` 只读快照）。这两个操作走独立匿名传输：不带 bearer、不触发 401 登录刷新，只依赖匿名访客 Cookie，供内置 Web 同源使用。
 - **会话资源（REST）**：`SessionsResource`、`CreateSessionRequest`、`ImportSessionOptions`、`AppCliDefinition`、`AppCliAttachment`、`AttachAppOptions`、`PaginatedSessionsResult`、`GlobalSearchResult`、`GlobalSearchResultItem`、`GlobalSearchConversationResult`、`GlobalSearchFileResult`、`SessionHistory`、`SessionContextStats`、`ResultFeedback`、`ResultFeedbackReason`、`ShareLinkResult`、`FileEntry`、`UploadFileEntry`、`UploadFilesOptions`、`SessionProfile`、`SessionDetail`、`SessionInfo`、`SessionStatus`、`SessionPortMapping`、`ModeId`、`TemplateId`、`PrimarySkillSnapshot`、`PrimarySkillParallelMode`
 - **会话回放**：`ReplayState`、`ReplaySpeed`、`ReplayPreview`、`ReplaySnapshot`、`toReplaySnapshot`、`DEFAULT_REPLAY_SPEED`
 - **会话状态机**：`SessionHub`、`SessionConnectOptions`、`SessionState`、`SendOptions`、`ConnectionStatus`、`AskUserAnswerData`、`AgentLoopInfo`、`ActiveCompactionState`、`createInitialSessionState`、`AgentSessionEventName`
+- **会话消息队列**：`SessionQueueSnapshot`、`QueuedMessage`、`QueuedMessageStatus`、`QueueAck`、`QueueOperationResult`、`EMPTY_SESSION_QUEUE`、`isSessionQueueSnapshot`、`shouldApplySnapshot`、`parseQueueAck`、`canEditQueuedMessage`、`canCancelQueuedMessage`、`canDeliverQueuedMessage`、`queuedMessageStatusLabel`、`queuePauseReasonLabel`
 - **页面协作**：`EmbeddedChat`、`EmbeddedChatOptions`、`CommandHandler`、`CommandEnvelope`、`InboundAction`、`InboundEnvelope`、`isCommandEnvelope`、`isInboundEnvelope`
 - **消息与投影协议**：`MessageContent`、`MessageContentPart`、`TextContentPart`、`ImageUrlContentPart`、`FileContentPart`、`ToolCallInfo`、`ToolBridgeContent`、`CompactionInfo`、`ContextProjectionData`、`ContextProjectionFields`、`ContextDisplayState`、`ContextGroupDisplayState`、`ContextAction`、`ContextSourceInfo`、`MemoryRefInfo`、`ArchivedFileInfo`、`ArchivedToolCallInfo`、`TurnProjection`、`ContentBlock`、`PatchEnvelope`、`MemoryRef`、`PostChatFollowup`、`FinalArtifact`、`contextProjectionData`、`getContextDisplayState`、`getContextGroupDisplayState`、`groupAdjacentContextRuns`、`latestPostChatFollowup`、`buildMessageContent`、`normalizeMessageContent`、`isHiddenInternalMessage`、`transformSlashCommand`、`SkillMentionAvailability`、`extractTextAttachments`、`ParsedTextAttachment`、`ParsedTextContext`
 - **MCP Apps 留档与卡片判定**：`McpAppData`、`isMcpAppData`、`McpAppContextState`、`McpAppContextUpdate`、`ToolUiCard`、`ToolUiCardContentType`、`InlineToolUiCardEntry`、`PreviewToolUiCardEntry`、`isToolUiCard`、`resolveToolUiCardContent`、`buildToolUiCardKey`、`isInternalStatusToolUiCard`、`isAppDevToolUiCard`、`collectInlineToolUiCards`、`collectPreviewToolUiCards`（`McpAppContextState` / `McpAppContextUpdate` 配合 `sessions.getMcpAppContext` / `sessions.updateMcpAppContext`：App 保存的状态在下一个新运行才进入模型上下文）

package/dist/blade-client.d.ts

@@ -6,6 +6,7 @@ import { ComputersResource } from "./resources/computers";
 import { ModelsResource } from "./resources/models";
 import { SessionsResource } from "./resources/sessions";
 import { ChatProjectsResource } from "./resources/chat-projects";
+import { SiteVisitsResource } from "./resources/site-visits";
 import { SessionHub } from "./session/hub";
 import { type TypedSocket } from "./socket";
 export interface BladeClientOptions {
@@ -39,6 +40,11 @@ export declare class BladeClient {
     readonly models: ModelsResource;
     readonly sessions: SessionsResource;
     readonly chatProjects: ChatProjectsResource;
+    /**
+     * 全站访问统计：匿名读写，不带 bearer 也不触发登录刷新。
+     * 只有内置 Web 的同源页面使用，第三方宿主页面不会被自动统计。
+     */
+    readonly siteVisits: SiteVisitsResource;
     /** 实时会话中枢：client.sessions.connect() 内部使用，一般不直接访问。 */
     readonly hub: SessionHub;
     constructor(options: BladeClientOptions);
@@ -87,7 +93,6 @@ export declare class BladeClient {
     private buildHeaders;
     private buildUrl;
     private baseUrlWithTrailingSlash;
-    private toBaseRelativePath;
     private isSameBackendUrl;
     private shouldRefreshFor401;
     private hasExplicitBearerToken;

package/dist/index.d.ts

@@ -17,6 +17,8 @@ export { SessionSetupError } from "./session/definition";
 export type { SessionConfig, SessionDefinition, SessionSetupStage, SkillDefinition, TextFile, SolutionDefinition, } from "./session/definition";
 export { createInitialSessionState, reconcileHistoricalUserTurns, reconcileOptimisticUserTurns, toReplaySnapshot, } from "./session/state";
 export type { AskUserAnswerData, AgentLoopInfo, ActiveCompactionState, ConnectionStatus, ReplaySnapshot, SessionState, } from "./session/state";
+export { EMPTY_SESSION_QUEUE, canCancelQueuedMessage, canDeliverQueuedMessage, canEditQueuedMessage, isSessionQueueSnapshot, parseQueueAck, queuePauseReasonLabel, queuedMessageStatusLabel, shouldApplySnapshot, } from "./session/queue";
+export type { QueueAck, QueueOperationResult, QueuedMessage, QueuedMessageStatus, SessionQueueSnapshot, } from "./session/queue";
 export { connectEmbedded } from "./commands/embedded";
 export type { EmbeddedChat, EmbeddedChatOptions } from "./commands/embedded";
 export type { CommandHandler } from "./commands/registry";
@@ -34,6 +36,7 @@ export type { SessionPlugin, SessionPluginActivation } from "./resources/session
 export type { SessionPluginConfigError, SessionPluginConfigSet, SessionPluginConfigState, SessionPluginConfigStateName, SessionPluginConfigSummary, SessionPluginConfigUpdate, } from "./resources/sessions";
 export { ChatProjectsResource } from "./resources/chat-projects";
 export type { ChatProject } from "./resources/chat-projects";
+export type { SiteVisitsResource, SiteVisitsSummary } from "./resources/site-visits";
 export { hasChatRunEvent } from "./shared/projection";
 export type { CreateSessionRequest, AppCliAttachment, AppCliDefinition, FileEntry, ImportSessionOptions, PaginatedSessionsResult, GlobalSearchConversationResult, GlobalSearchFileResult, GlobalSearchResult, GlobalSearchResultItem, ResultFeedback, ResultFeedbackReason, HistoricalCommand, SessionContextStats, SessionHistory, SessionTurnsPage, ShareLinkResult, UploadFileEntry, UploadFilesOptions, } from "./resources/sessions";
 export type { ArchivedFileInfo, ArchivedToolCallInfo, ChatMessage, CompactionInfo, FileContentPart, ImageUrlContentPart, MemoryRefInfo, MessageContent, MessageContentPart, TextContentPart, ToolBridgeContent, ToolCallInfo, } from "./schemas/message";

package/dist/index.js

@@ -167,6 +167,10 @@ function decorateAuthError(error) {
   }
   return error;
 }
+function buildBackendUrl(baseUrl, path) {
+  const base = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+  return new URL(path.startsWith("/") ? path.slice(1) : path, base);
+}
 
 // src/resources/auth.ts
 var AuthResource = class {
@@ -3131,6 +3135,43 @@ var ChatProjectsResource = class {
   }
 };
 
+// src/resources/site-visits.ts
+var SITE_VISITS_PATH = "/api/site-visits";
+var REQUEST_TIMEOUT_MS = 5e3;
+var SiteVisitsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /** 上报一次页面访问，返回当前快照；不承诺本次已计入或已落盘。 */
+  record() {
+    return this.request("POST");
+  }
+  /** 只读快照：不设置访客 Cookie，也不增加任何计数。 */
+  summary() {
+    return this.request("GET");
+  }
+  async request(method) {
+    const url = buildBackendUrl(this.client.options.baseUrl, SITE_VISITS_PATH);
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    try {
+      const response = await (this.client.options.fetchImpl ?? fetch)(url.toString(), {
+        method,
+        // 访客 Cookie 是唯一的去重依据，必须随请求往返。
+        credentials: "include",
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        throw new BladeApiError(response, await extractErrorDetail(response));
+      }
+      return await response.json();
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+};
+
 // src/shared/auth-busy.ts
 var DEFAULT_RETRY_AFTER_SECONDS = 1;
 var MAX_TIMER_DELAY_MS = 2147483647;
@@ -3310,6 +3351,123 @@ function replaceWindow(current, page, liveRevisionAtStart, liveRevisions) {
   ]);
 }
 
+// src/session/queue.ts
+var EMPTY_SESSION_QUEUE = {
+  session_id: "",
+  revision: 0,
+  paused: false,
+  pause_reason: null,
+  items: []
+};
+var QUEUE_FAILURE_MESSAGE = "\u961F\u5217\u64CD\u4F5C\u5931\u8D25";
+var QUEUED_MESSAGE_STATUSES = [
+  "pending",
+  "delivering",
+  "claimed",
+  "consumed",
+  "cancelled"
+];
+function toQueuedMessage(value) {
+  if (!isRecord(value)) return null;
+  const status = typeof value.status === "string" && QUEUED_MESSAGE_STATUSES.includes(value.status) ? value.status : null;
+  if (typeof value.id !== "string" || typeof value.content !== "string" || typeof value.position !== "number" || typeof value.version !== "number" || typeof value.created_at !== "string" || typeof value.updated_at !== "string" || status === null) {
+    return null;
+  }
+  const item = {
+    id: value.id,
+    content: value.content,
+    position: value.position,
+    version: value.version,
+    status,
+    created_at: value.created_at,
+    updated_at: value.updated_at
+  };
+  if (typeof value.target_run_id === "string") item.target_run_id = value.target_run_id;
+  if (typeof value.error === "string") item.error = value.error;
+  return item;
+}
+function toQueueSnapshot(value, fallbackSessionId) {
+  if (!isRecord(value)) return null;
+  if (typeof value.revision !== "number" || !Number.isInteger(value.revision) || value.revision < 0) {
+    return null;
+  }
+  if (typeof value.paused !== "boolean") return null;
+  if (!Array.isArray(value.items)) return null;
+  const pauseReason = value.pause_reason;
+  if (pauseReason !== null && pauseReason !== void 0 && typeof pauseReason !== "string") {
+    return null;
+  }
+  const items = [];
+  for (const raw of value.items) {
+    const item = toQueuedMessage(raw);
+    if (!item) return null;
+    items.push(item);
+  }
+  return {
+    session_id: typeof value.session_id === "string" && value.session_id ? value.session_id : fallbackSessionId,
+    revision: value.revision,
+    paused: value.paused,
+    pause_reason: typeof pauseReason === "string" ? pauseReason : null,
+    items
+  };
+}
+function isSessionQueueSnapshot(value) {
+  if (!isRecord(value) || typeof value.session_id !== "string") return false;
+  return toQueueSnapshot(value, value.session_id) !== null;
+}
+function shouldApplySnapshot(current, next) {
+  if (!isSessionQueueSnapshot(next)) return false;
+  if (current?.session_id && next.session_id !== current.session_id) return false;
+  return next.revision > (current?.revision ?? -1);
+}
+function parseQueueAck(response, fallbackSessionId) {
+  if (!isRecord(response)) {
+    return { ok: false, conflict: false, snapshot: null, message: QUEUE_FAILURE_MESSAGE };
+  }
+  const message = typeof response.message === "string" && response.message ? response.message : null;
+  const status = response.status;
+  if (status !== "ok" && status !== "conflict") {
+    return { ok: false, conflict: false, snapshot: null, message: message ?? QUEUE_FAILURE_MESSAGE };
+  }
+  const snapshot2 = toQueueSnapshot(response, fallbackSessionId);
+  if (status === "conflict") {
+    return { ok: false, conflict: true, snapshot: snapshot2, message: message ?? QUEUE_FAILURE_MESSAGE };
+  }
+  if (!snapshot2) {
+    return { ok: false, conflict: false, snapshot: null, message: message ?? QUEUE_FAILURE_MESSAGE };
+  }
+  return { ok: true, conflict: false, snapshot: snapshot2, message };
+}
+function canEditQueuedMessage(item) {
+  return item.status === "pending";
+}
+function canCancelQueuedMessage(item) {
+  return item.status === "pending";
+}
+function canDeliverQueuedMessage(item) {
+  return item.status === "pending";
+}
+var QUEUED_MESSAGE_STATUS_LABELS = {
+  pending: "\u5F85\u6267\u884C",
+  delivering: "\u7B49\u5F85\u63A5\u6536",
+  claimed: "",
+  consumed: "",
+  cancelled: ""
+};
+function queuedMessageStatusLabel(status) {
+  return QUEUED_MESSAGE_STATUS_LABELS[status] ?? "";
+}
+var QUEUE_PAUSE_REASON_LABELS = {
+  user_stop: "\u5DF2\u6682\u505C",
+  run_failed: "\u4EFB\u52A1\u5F02\u5E38\u5DF2\u6682\u505C",
+  run_unknown: "\u4EFB\u52A1\u7ED3\u675F\u72B6\u6001\u672A\u77E5\uFF0C\u5DF2\u6682\u505C",
+  server_restart: "\u670D\u52A1\u91CD\u542F\u5DF2\u6682\u505C"
+};
+function queuePauseReasonLabel(reason) {
+  if (!reason) return null;
+  return QUEUE_PAUSE_REASON_LABELS[reason] ?? reason;
+}
+
 // src/schemas/mcp-app.ts
 function isMcpAppData(value) {
   return isRecord(value) && typeof value.sourceId === "string" && value.sourceId.length > 0 && typeof value.resourceUri === "string" && value.resourceUri.startsWith("ui://") && typeof value.mimeType === "string" && isRecord(value.resourceMeta) && isRecord(value.toolInput) && isRecord(value.toolResult);
@@ -3608,6 +3766,7 @@ function createInitialSessionState(sessionId) {
     agentLoops: {},
     activeCompaction: null,
     replay: null,
+    queue: EMPTY_SESSION_QUEUE,
     viewerRole: null,
     nextBefore: null,
     loadingOlder: false
@@ -4015,6 +4174,10 @@ function withTurns(state, turns) {
     status: isWaitingForInput ? "waiting_for_input" : state.status
   };
 }
+function withQueue(state, snapshot2) {
+  if (!shouldApplySnapshot(state.queue, snapshot2)) return state;
+  return { ...state, queue: snapshot2 };
+}
 var localTurnCounter = 0;
 function addUserMessage(state, content, clientRequestId) {
   localTurnCounter += 1;
@@ -4092,6 +4255,7 @@ function markStreamingTurns(state, turnStatus, toolCallStatus) {
 var OOM_MESSAGE = "\u6C99\u76D2\u5185\u5B58\u4F7F\u7528\u8D85\u51FA\u9650\u5236\uFF0C\u5DF2\u81EA\u52A8\u91CD\u542F\u3002\u5982\u679C\u7ECF\u5E38\u89E6\u53D1\uFF0C\u53EF\u4EE5\u8054\u7CFB\u7BA1\u7406\u5458\u8C03\u6574\u989D\u5EA6\u3002";
 var COMMAND_RESTORE_RETRY_BASE_MS = 1e3;
 var COMMAND_RESTORE_RETRY_MAX_MS = 3e4;
+var QUEUE_ACK_TIMEOUT_MS = 1e4;
 var fallbackRequestCounter = 0;
 function createClientRequestId() {
   if (typeof globalThis.crypto?.randomUUID === "function") {
@@ -4138,6 +4302,14 @@ function isToolBridgeContent(value) {
 function isCursorInvalidError(error) {
   return typeof error === "object" && error !== null && "status" in error && error.status === 409;
 }
+function queueRequestFailure(error) {
+  return {
+    ok: false,
+    conflict: false,
+    snapshot: null,
+    message: error instanceof Error && error.message ? error.message : "\u961F\u5217\u64CD\u4F5C\u5931\u8D25"
+  };
+}
 function commandDeliveryKey(deliveryId) {
   return `tool-command:${deliveryId}`;
 }
@@ -4180,8 +4352,6 @@ var AgentSession = class _AgentSession {
   modeRevision = 0;
   liveRevisions = /* @__PURE__ */ new Map();
   pendingOptimisticTurnIds = /* @__PURE__ */ new Set();
-  /** Consecutive supplements are persisted as one authoritative user turn. */
-  pendingAppendTurnId = null;
   olderPending = null;
   replaceInFlight = 0;
   // 回放控制请求排成一条队列。连着点"5x"再点"退出回放"时，并发发出去的两个
@@ -4354,21 +4524,95 @@ var AgentSession = class _AgentSession {
       this.sendPending = false;
     }
   }
-  /** Queue a plain-text prompt while a turn is streaming. */
-  async queue(content) {
+  /**
+   * 入队一条等待消息（运行中排队 / 暂停期间照常入队）。
+   *
+   * ack 超时或传输失败时结果未知：用**同一个** `client_request_id` 重试一次，
+   * 服务端按 `(session_id, client_request_id)` 幂等，不会制造第二条。
+   */
+  async queueMessage(content) {
     const text = content.trim();
-    if (!text) return false;
-    this.runtime.ensureConnected();
-    this.runtime.emitEvent("chat:append", { session_id: this.sessionId, message: text });
-    return true;
+    if (!text) {
+      return { ok: false, conflict: false, snapshot: null, message: "\u6D88\u606F\u4E0D\u80FD\u4E3A\u7A7A" };
+    }
+    const payload = {
+      session_id: this.sessionId,
+      message: text,
+      client_request_id: createClientRequestId()
+    };
+    try {
+      return await this.requestQueueAck("chat:append", payload);
+    } catch {
+      try {
+        return await this.requestQueueAck("chat:append", payload);
+      } catch (error) {
+        return queueRequestFailure(error);
+      }
+    }
   }
-  async listQueue() {
-    const response = await this.runtime.emitWithAck("chat:queue:list", { session_id: this.sessionId }, 1e4);
-    return Array.isArray(response?.items) ? response.items : [];
+  /** 修改一条等待消息的正文；`expectedVersion` 是客户端看到的条目版本。 */
+  async updateQueuedMessage(itemId, expectedVersion, content) {
+    return this.runQueueCommand("chat:queue:update", {
+      session_id: this.sessionId,
+      item_id: itemId,
+      expected_version: expectedVersion,
+      message: content
+    });
   }
-  async cancelQueued(id) {
-    const response = await this.runtime.emitWithAck("chat:queue:cancel", { session_id: this.sessionId, id }, 1e4);
-    return response?.cancelled === true;
+  /**
+   * 重排等待消息。`orderedIds` 必须是当前 pending 条目 id 的**完整集合**（顺序任意），
+   * 服务端按 `expectedRevision` 校验后整体替换顺序。
+   */
+  async reorderQueuedMessages(expectedRevision, orderedIds) {
+    return this.runQueueCommand("chat:queue:reorder", {
+      session_id: this.sessionId,
+      expected_revision: expectedRevision,
+      ordered_ids: orderedIds
+    });
+  }
+  /** 删除一条等待消息；不传版本时由服务端自行判定。 */
+  async cancelQueuedMessage(itemId, expectedVersion) {
+    return this.runQueueCommand("chat:queue:cancel", {
+      session_id: this.sessionId,
+      item_id: itemId,
+      expected_version: expectedVersion
+    });
+  }
+  /** 立即补充：把等待消息交给当前运行，在下一个接收点消费，不停止也不另起一轮。 */
+  async deliverQueuedMessage(itemId, expectedVersion) {
+    return this.runQueueCommand("chat:queue:deliver", {
+      session_id: this.sessionId,
+      item_id: itemId,
+      expected_version: expectedVersion
+    });
+  }
+  /** 继续执行：清除暂停，并按当前顺序恢复逐条接续。 */
+  async resumeQueue() {
+    return this.runQueueCommand("chat:queue:resume", { session_id: this.sessionId });
+  }
+  /** 拉取一份权威队列快照。首次连接与每次重连后由实例自动调用，也可以手动刷新。 */
+  async refreshQueue() {
+    return this.runQueueCommand("chat:queue:list", { session_id: this.sessionId });
+  }
+  /**
+   * 发出一条队列命令并安装 ack 里的快照。
+   * 传输层失败（超时 / 断线）会 reject，由调用方决定是否重试。
+   */
+  async requestQueueAck(event, payload) {
+    this.runtime.ensureConnected();
+    const response = await this.runtime.emitWithAck(event, payload, QUEUE_ACK_TIMEOUT_MS);
+    const result = parseQueueAck(response, this.sessionId);
+    const snapshot2 = result.snapshot;
+    if (snapshot2) this.update((state) => withQueue(state, snapshot2));
+    return result;
+  }
+  /** 队列命令的对外入口：传输失败只体现为失败结果，不向调用方抛异常。 */
+  async runQueueCommand(event, payload) {
+    try {
+      return await this.requestQueueAck(event, payload);
+    } catch (error) {
+      return queueRequestFailure(error);
+    }
   }
   async sendUnlocked(content, options) {
     await this.ensureIdleBeforeSend();
@@ -4494,40 +4738,7 @@ var AgentSession = class _AgentSession {
     if (optimisticTurnId) {
       this.pendingOptimisticTurnIds.delete(optimisticTurnId);
       this.liveRevisions.delete(optimisticTurnId);
-      if (this.pendingAppendTurnId === optimisticTurnId) this.pendingAppendTurnId = null;
-    }
-  }
-  /** 智能体运行期间追加补充说明（不打断当前回复）。 */
-  append(text) {
-    this.runtime.ensureConnected();
-    const existingAppendId = this.pendingAppendTurnId;
-    let optimisticTurnId = existingAppendId;
-    this.update((state) => {
-      const existing = existingAppendId ? state.turns.find((turn) => turn.turn_id === existingAppendId) : void 0;
-      if (existing && existing.role === "user") {
-        const blocks = existing.blocks.map(
-          (block, index) => index === 0 && block.type === "text" ? { ...block, content: `${block.content}
-${text}` } : block
-        );
-        return withTurns(state, state.turns.map(
-          (turn) => turn.turn_id === existingAppendId ? { ...turn, blocks } : turn
-        ));
-      }
-      const next = addUserMessage(state, text, createClientRequestId());
-      optimisticTurnId = next.turns.at(-1)?.turn_id ?? null;
-      return next;
-    });
-    if (optimisticTurnId) {
-      this.pendingAppendTurnId = optimisticTurnId;
-      if (!this.pendingOptimisticTurnIds.has(optimisticTurnId)) {
-        this.markOptimisticTurnPending(optimisticTurnId);
-      }
     }
-    this.runtime.emitEvent("chat:append", {
-      session_id: this.sessionId,
-      message: text,
-      ...optimisticTurnId ? { client_request_id: optimisticTurnId.slice("local-user-".length) } : {}
-    });
   }
   /** 停止当前回复。 */
   stop() {
@@ -4621,6 +4832,15 @@ ${text}` } : block
     if (this.state.connection === connection) return;
     this.update((s) => ({ ...s, connection }));
   }
+  /**
+   * @internal 服务端广播的权威队列快照。
+   * 结构不合法或 revision 不新的一律丢弃，绝不用旧快照覆盖新状态。
+   */
+  _handleQueueUpdated(payload) {
+    if (!isSessionQueueSnapshot(payload)) return;
+    const snapshot2 = payload;
+    this.update((state) => withQueue(state, snapshot2));
+  }
   /** @internal socket 重连后由 Hub 调用：重新加入房间并补数。 */
   _rejoinAfterReconnect() {
     this.timelineEpoch += 1;
@@ -4663,7 +4883,7 @@ ${text}` } : block
         this.subscriptionReplaySource = null;
       }
       this.scheduleHistoricalCommandRestore(commandRecoveryGeneration);
-      await this.syncReplayFromSession();
+      await Promise.all([this.syncReplayFromSession(), this.refreshQueue()]);
     });
   }
   /** 订阅生命周期串行执行；一次失败只由自己的调用方观察，不截断后续重连。 */
@@ -5507,6 +5727,7 @@ var SessionHub = class {
       if (isReconnect) {
         for (const session of this.sessions.values()) {
           void session._rejoinAfterReconnect();
+          void session.refreshQueue();
         }
       }
     });
@@ -5568,6 +5789,9 @@ var SessionHub = class {
     socket.on("system:error", (data) => {
       for (const session of this.route(data.session_id)) session._handleSystemError(data.message);
     });
+    socket.on("chat:queue:updated", (data) => {
+      for (const session of this.route(data?.session_id)) session._handleQueueUpdated(data);
+    });
     socket.on(
       "system:notification",
       (data) => {
@@ -5711,6 +5935,11 @@ var BladeClient = class {
   models;
   sessions;
   chatProjects;
+  /**
+   * 全站访问统计：匿名读写，不带 bearer 也不触发登录刷新。
+   * 只有内置 Web 的同源页面使用，第三方宿主页面不会被自动统计。
+   */
+  siteVisits;
   /** 实时会话中枢：client.sessions.connect() 内部使用，一般不直接访问。 */
   hub;
   constructor(options) {
@@ -5724,6 +5953,7 @@ var BladeClient = class {
     this.models = new ModelsResource(this);
     this.sessions = new SessionsResource(this);
     this.chatProjects = new ChatProjectsResource(this);
+    this.siteVisits = new SiteVisitsResource(this);
     this.hub = new SessionHub(this);
     if (this.options.token === void 0) {
       this.runtimeToken = readStoredToken(this.options.baseUrl);
@@ -5894,7 +6124,7 @@ var BladeClient = class {
     return response;
   }
   buildAuthedUrl(path) {
-    const url = new URL(this.toBaseRelativePath(path), this.baseUrlWithTrailingSlash());
+    const url = buildBackendUrl(this.options.baseUrl, path);
     const token = this.resolveTokenForUrl(url);
     if (token) {
       url.searchParams.set("token", token);
@@ -5913,14 +6143,11 @@ var BladeClient = class {
     return result;
   }
   buildUrl(path) {
-    return new URL(this.toBaseRelativePath(path), this.baseUrlWithTrailingSlash());
+    return buildBackendUrl(this.options.baseUrl, path);
   }
   baseUrlWithTrailingSlash() {
     return this.options.baseUrl.endsWith("/") ? this.options.baseUrl : `${this.options.baseUrl}/`;
   }
-  toBaseRelativePath(path) {
-    return path.startsWith("/") ? path.slice(1) : path;
-  }
   isSameBackendUrl(url) {
     const base = new URL(this.baseUrlWithTrailingSlash());
     if (url.origin !== base.origin) {
@@ -6194,7 +6421,7 @@ function resolveServiceUrl(endpoints, name, path = "") {
 
 // src/version.ts
 var SDK_NAME = "agent-client";
-var SDK_VERSION = true ? "2610.0.0-beta.51" : "1.1.1";
+var SDK_VERSION = true ? "2610.0.0-beta.53" : "1.1.1";
 
 // src/commands/protocol.ts
 function isCommandEnvelope(value) {
@@ -6304,6 +6531,7 @@ export {
   ComputersResource,
   DEFAULT_REPLAY_SPEED,
   EMPTY_PLATFORM_ENDPOINTS,
+  EMPTY_SESSION_QUEUE,
   LayoutType,
   ModelsResource,
   PollingBackoff,
@@ -6320,6 +6548,9 @@ export {
   authBusyRetryDelayMs,
   buildMessageContent,
   buildToolUiCardKey,
+  canCancelQueuedMessage,
+  canDeliverQueuedMessage,
+  canEditQueuedMessage,
   canToggleComputer,
   chatErrorForDisplay,
   collectInlineToolUiCards,
@@ -6348,16 +6579,21 @@ export {
   isInboundEnvelope,
   isInternalStatusToolUiCard,
   isMcpAppData,
+  isSessionQueueSnapshot,
   isToolUiCard,
   latestPostChatFollowup,
   loadPlatformEndpoints,
   normalizeMessageContent,
+  parseQueueAck,
   prependOlder,
+  queuePauseReasonLabel,
+  queuedMessageStatusLabel,
   reconcileHistoricalUserTurns,
   reconcileOptimisticUserTurns,
   replaceWindow,
   resolveServiceUrl,
   resolveToolUiCardContent,
+  shouldApplySnapshot,
   sortComputers,
   toReplaySnapshot,
   transformSlashCommand