@blade-hq/agent-client 2610.0.0-beta.47 → 2610.0.0-beta.48

package/README.md

@@ -502,6 +502,15 @@ PATCH / query / FormData / AbortSignal 等完整 HTTP 语义（否则不够用
 > **安全约束**：`client.token` 只应发往 `baseUrl` 同源的接口。不要把它附加到
 > 第三方域名的请求上——那等于把用户的访问凭据交给别人。
 
+### 只读轮询退避
+
+`new PollingBackoff(3000)` 为轮询维护独立退避状态，参数为正常间隔（大于 0、不超过 60 秒）。
+请求成功后调用 `reset()`，失败后调用 `failed(error)`；`waitMs()` 返回剩余等待毫秒数，
+`0` 表示可以请求，`false` 表示停止。HTTP 错误应传入保留响应头的 `BladeApiError`。
+401/403 等确定性错误停止，网络/5xx 指数退避带抖动且最高 60 秒；`Retry-After`
+可以要求更长等待，超出浏览器定时器范围时停止。策略自身不发送请求，调度器须传递
+AbortSignal、在卸载时停止，并避免将它用于自动重放 POST 等有副作用的操作。
+
 ## headless：一次性问答
 
 ```ts
@@ -607,7 +616,7 @@ transformSlashCommand(skillId, prompt, { local: false, installed: false })
 - **SDK 身份**：`SDK_NAME`、`SDK_VERSION`
 - **声明式会话**：`SessionDefinition`、`SolutionDefinition`、`SkillDefinition`、`SessionConfig`、`TextFile`、`SessionSetupError`、`SessionSetupStage`
 - **模型目录**：`ModelsResource`、`ModelCatalog`、`ModelOption`
-- **聊天项目资源（REST）**：`ChatProjectsResource`、`ChatProject`
+- **聊天项目资源（REST）**：`ChatProjectsResource`、`ChatProject`（含 `delete` 永久删除）
 - **会话资源（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`
@@ -615,4 +624,4 @@ transformSlashCommand(skillId, prompt, { local: false, installed: false })
 - **消息与投影协议**：`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`
 - **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`、`acknowledgeTurnEvents`、`hasChatRunEvent`、`acceptedPostChatFollowupCompletesLatestRun`、`reconcileOptimisticUserTurns`、`reconcileHistoricalUserTurns`
+- **低层通道（apps/web 等高级集成）**：`createSocket`、`CreateSocketOptions`、`TypedSocket`、`AsrAudioPayload`、`AuthBusyReconnect`、`authBusyRetryDelayMs`、`ClientProjectionBuilder`、`RawEvent`、`acknowledgeTurnEvents`、`hasChatRunEvent`、`acceptedPostChatFollowupCompletesLatestRun`、`reconcileOptimisticUserTurns`、`reconcileHistoricalUserTurns`

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { BladeClient } from "./blade-client";
 export type { BladeClientOptions, UploadProgress } from "./blade-client";
 export { BladeApiError } from "./rest";
+export { PollingBackoff } from "./polling-backoff";
 export type { LoginOptions, LoginResult, TokenStorageMode } from "./auth-login";
 export { EMPTY_PLATFORM_ENDPOINTS, loadPlatformEndpoints, resolveServiceUrl, } from "./platform-endpoints";
 export type { LoadPlatformEndpointsOptions, PlatformEndpoints, PlatformServiceName, } from "./platform-endpoints";
@@ -50,6 +51,7 @@ export { Task, TaskStatus } from "./schemas/task";
 export type { BackgroundTask, BackgroundTaskStopResult } from "./schemas/background";
 export { acceptedPostChatFollowupCompletesLatestRun, acknowledgeTurnEvents, ClientProjectionBuilder, } from "./shared/projection";
 export type { RawEvent } from "./shared/projection";
+export { AuthBusyReconnect, authBusyRetryDelayMs } from "./shared/auth-busy";
 export { createSocket } from "./socket";
 export type { CreateSocketOptions, TypedSocket } from "./socket";
 export type { AsrAudioPayload } from "./types/socket-events";

package/dist/index.js

@@ -3053,6 +3053,50 @@ var ChatProjectsResource = class {
   update(projectId, payload) {
     return this.client.json("PATCH", `/api/chat-projects/${encodeURIComponent(projectId)}`, payload);
   }
+  delete(projectId) {
+    return this.client.json("DELETE", `/api/chat-projects/${encodeURIComponent(projectId)}`);
+  }
+};
+
+// src/shared/auth-busy.ts
+var DEFAULT_RETRY_AFTER_SECONDS = 1;
+var MAX_TIMER_DELAY_MS = 2147483647;
+function errorData(error) {
+  if (typeof error !== "object" || error === null || !("data" in error)) return null;
+  const data = error.data;
+  return typeof data === "object" && data !== null ? data : null;
+}
+function authBusyRetryDelayMs(error) {
+  const data = errorData(error);
+  if (data?.code !== "auth_busy" || Number(data.status) !== 429) return null;
+  const rawRetryAfter = data.retry_after;
+  const seconds = rawRetryAfter == null || String(rawRetryAfter).trim() === "" ? Number.NaN : Number(rawRetryAfter);
+  const delaySeconds = Number.isFinite(seconds) && seconds >= 0 ? seconds : DEFAULT_RETRY_AFTER_SECONDS;
+  return Math.min(delaySeconds * 1e3, MAX_TIMER_DELAY_MS);
+}
+var AuthBusyReconnect = class {
+  timer = null;
+  get pending() {
+    return this.timer !== null;
+  }
+  schedule(error, reconnect) {
+    const delay = authBusyRetryDelayMs(error);
+    if (delay === null) {
+      this.cancel();
+      return false;
+    }
+    this.cancel();
+    this.timer = globalThis.setTimeout(() => {
+      this.timer = null;
+      reconnect();
+    }, delay);
+    return true;
+  }
+  cancel() {
+    if (this.timer === null) return;
+    globalThis.clearTimeout(this.timer);
+    this.timer = null;
+  }
 };
 
 // src/commands/registry.ts
@@ -5099,6 +5143,7 @@ var SessionHub = class {
   connectionListeners = /* @__PURE__ */ new Set();
   bound = false;
   hasConnected = false;
+  authBusyReconnect = new AuthBusyReconnect();
   constructor(client) {
     this.client = client;
   }
@@ -5165,6 +5210,7 @@ var SessionHub = class {
   /** 手动重连（例如登录态变化后）。 */
   reconnect() {
     this.ensureBound();
+    this.authBusyReconnect.cancel();
     const socket = this.client.socket();
     socket.disconnect();
     this.setConnection("connecting");
@@ -5172,11 +5218,13 @@ var SessionHub = class {
   }
   /** 断开连接（不清理 session 实例）。 */
   disconnect() {
+    this.authBusyReconnect.cancel();
     this.client.socket().disconnect();
     this.setConnection("disconnected");
   }
   /** 清理当前身份下缓存的全部会话，避免切换登录身份后复用旧快照。 */
   disposeAll() {
+    this.authBusyReconnect.cancel();
     this.bootstrapPending.clear();
     for (const session of [...this.sessions.values()]) {
       this.forceRelease(session);
@@ -5188,6 +5236,7 @@ var SessionHub = class {
    * turn:* / chat:* 事件都会静默丢弃。
    */
   _handleSocketReplaced() {
+    this.authBusyReconnect.cancel();
     this.bound = false;
     this.setConnection("disconnected");
     if (this.sessions.size === 0) return;
@@ -5240,6 +5289,9 @@ var SessionHub = class {
     if (this.sessions.get(session.sessionId) === session) {
       this.sessions.delete(session.sessionId);
     }
+    if (this.sessions.size === 0) {
+      this.authBusyReconnect.cancel();
+    }
     ;
     this.client.socket().emit("session:unsubscribe", { session_id: session.sessionId });
     return true;
@@ -5248,10 +5300,13 @@ var SessionHub = class {
   forceRelease(session) {
     this.holdCounts.delete(session.sessionId);
     session.dispose();
+    if (this.sessions.size === 0) {
+      this.authBusyReconnect.cancel();
+    }
   }
   ensureConnected() {
     const socket = this.client.socket();
-    if (socket.connected || socket.active) return;
+    if (socket.connected || socket.active || this.authBusyReconnect.pending) return;
     this.setConnection("connecting");
     socket.connect();
   }
@@ -5283,6 +5338,7 @@ var SessionHub = class {
     this.bound = true;
     const socket = this.client.socket();
     socket.on("connect", () => {
+      this.authBusyReconnect.cancel();
       const isReconnect = this.hasConnected;
       this.hasConnected = true;
       this.setConnection("connected");
@@ -5292,8 +5348,24 @@ var SessionHub = class {
         }
       }
     });
-    socket.on("connect_error", () => this.setConnection("disconnected"));
-    socket.on("disconnect", () => this.setConnection("disconnected"));
+    socket.on("connect_error", (error) => {
+      this.setConnection("disconnected");
+      if (this.sessions.size === 0) {
+        this.authBusyReconnect.cancel();
+        return;
+      }
+      if (this.authBusyReconnect.schedule(error, () => {
+        const current = this.client.socket();
+        if (current !== socket || current.connected || current.active) return;
+        this.setConnection("connecting");
+        current.connect();
+      })) return;
+      this.authBusyReconnect.cancel();
+    });
+    socket.on("disconnect", () => {
+      this.authBusyReconnect.cancel();
+      this.setConnection("disconnected");
+    });
     socket.io.on("reconnect_attempt", () => this.setConnection("reconnecting"));
     socket.on("turn:start", (data) => {
       for (const session of this.route(data.session_id)) session._handleTurnStart(data);
@@ -5842,6 +5914,42 @@ function parseXhrHeaders(rawHeaders) {
   return headers;
 }
 
+// src/polling-backoff.ts
+var MAX_BACKOFF_MS = 6e4;
+var MAX_TIMER_MS = 2147483647;
+var PollingBackoff = class {
+  constructor(intervalMs) {
+    this.intervalMs = intervalMs;
+    if (!Number.isFinite(intervalMs) || intervalMs <= 0 || intervalMs > MAX_BACKOFF_MS) {
+      throw new RangeError("Polling interval must be between 0 and 60000 ms");
+    }
+  }
+  intervalMs;
+  failures = 0;
+  nextAt = 0;
+  reset() {
+    this.failures = 0;
+    this.nextAt = 0;
+  }
+  failed(error) {
+    if (error instanceof Error && error.name === "AbortError" || error instanceof BladeApiError && error.status < 500 && error.status !== 408 && error.status !== 429) {
+      this.nextAt = false;
+      return;
+    }
+    this.failures = Math.min(this.failures + 1, 10);
+    const ceiling = Math.min(MAX_BACKOFF_MS, this.intervalMs * 2 ** this.failures);
+    const backoff = Math.max(this.intervalMs, ceiling * (0.5 + Math.random() * 0.5));
+    const header = error instanceof BladeApiError ? error.response.headers.get("Retry-After")?.trim() : void 0;
+    const retryAfter = header ? /^\d+$/.test(header) ? Number(header) * 1e3 : Date.parse(header) - Date.now() : 0;
+    const delay = Math.max(backoff, Number.isNaN(retryAfter) ? 0 : retryAfter);
+    this.nextAt = delay > MAX_TIMER_MS ? false : Date.now() + delay;
+  }
+  /** Zero means ready, false means stop, otherwise wait at least this many ms. */
+  waitMs() {
+    return this.nextAt === false ? false : Math.max(0, this.nextAt - Date.now());
+  }
+};
+
 // src/platform-endpoints.ts
 var PLATFORM_SERVICE_NAMES = [
   "os",
@@ -5924,7 +6032,7 @@ function resolveServiceUrl(endpoints, name, path = "") {
 
 // src/version.ts
 var SDK_NAME = "agent-client";
-var SDK_VERSION = true ? "2610.0.0-beta.47" : "1.1.1";
+var SDK_VERSION = true ? "2610.0.0-beta.48" : "1.1.1";
 
 // src/commands/protocol.ts
 function isCommandEnvelope(value) {
@@ -6026,6 +6134,7 @@ var Task = type2({
 });
 export {
   AgentSession,
+  AuthBusyReconnect,
   BladeApiError,
   BladeClient,
   ChatProjectsResource,
@@ -6035,6 +6144,7 @@ export {
   EMPTY_PLATFORM_ENDPOINTS,
   LayoutType,
   ModelsResource,
+  PollingBackoff,
   SDK_NAME,
   SDK_VERSION,
   SessionHub,
@@ -6045,6 +6155,7 @@ export {
   TaskStatus,
   acceptedPostChatFollowupCompletesLatestRun,
   acknowledgeTurnEvents,
+  authBusyRetryDelayMs,
   buildMessageContent,
   canToggleComputer,
   chatErrorForDisplay,