@blade-hq/agent-client 2610.0.1 → 2612.0.0-beta.1

package/dist/internal.d.ts

@@ -0,0 +1,55 @@
+export * from "./index";
+export { isEntryGoneError } from "./resources/sessions";
+export { PollingBackoff } from "./polling-backoff";
+export { EMPTY_PLATFORM_ENDPOINTS, loadPlatformEndpoints, resolveServiceUrl, } from "./platform-endpoints";
+export type { LoadPlatformEndpointsOptions, PlatformEndpoints, PlatformServiceName, } from "./platform-endpoints";
+export { SessionHub } from "./session/hub";
+export type { SessionConnectOptions, SessionHubEvents, SessionHubOptions } from "./session/hub";
+export { sessionStatusFromChatEnd } from "./session/agent-session";
+export type { ChatEndPayload, SessionDetailSnapshot } from "./session/agent-session";
+export { isWorkflowRunToolName, workflowEntriesFromOutput, workflowNameFromArguments, } from "./session/workflow";
+export { isMcpAppData } from "./schemas/mcp-app";
+export type { McpAppArchive, McpAppContextState, McpAppContextUpdate, McpAppData, } from "./schemas/mcp-app";
+export { applyTurnPatch, createInitialSessionState, parentForkToolCallIdFromTurn, upsertTurn, withTurns, reconcileHistoricalUserTurns, reconcileOptimisticUserTurns, toReplaySnapshot, } from "./session/state";
+export { EMPTY_SESSION_QUEUE, canCancelQueuedMessage, canDeliverQueuedMessage, canEditQueuedMessage, isSessionQueueSnapshot, parseQueueAck, queuePauseReasonLabel, queuedMessageStatusLabel, shouldApplySnapshot, } from "./session/queue";
+export type { QueueAck } from "./session/queue";
+export { prependOlder, replaceWindow } from "./session/history-page";
+export type { LiveRevisionState } from "./session/history-page";
+export type { CommandEnvelope, InboundAction, InboundEnvelope } from "./commands/protocol";
+export { isCommandEnvelope, isInboundEnvelope } from "./commands/protocol";
+export { canToggleComputer, computerDaemonVersion, computerOS, computerPlatformLabel, computerState, sortComputers, } from "./resources/computers";
+export type { AccountComputerList, ComputerOS, ComputerState, SessionComputerList, } from "./resources/computers";
+export { ModelsResource } from "./resources/models";
+export { ComputersResource } from "./resources/computers";
+export type { SessionPlugin, SessionPluginActivation } from "./resources/sessions";
+export type { SessionPluginConfigError, SessionPluginConfigSet, SessionPluginConfigState, SessionPluginConfigStateName, SessionPluginConfigSummary, SessionPluginConfigUpdate, } from "./resources/sessions";
+export { ChatGroupsResource } from "./resources/chat-groups";
+export type { ChatGroup } from "./resources/chat-groups";
+export { PluginsResource } from "./resources/plugins";
+export type { PluginCatalogEntry } from "./resources/plugins";
+export type { SiteVisitsResource, SiteVisitsSummary } from "./resources/site-visits";
+export type { GlobalSearchConversationResult, GlobalSearchFileResult, GlobalSearchResult, GlobalSearchResultItem, HistoricalCommand, ImportSessionOptions, ResultFeedback, ResultFeedbackReason, SessionContextStats, SessionHistory, SessionTurnIndex, SessionTurnIndexItem, ShareLinkResult, } from "./resources/sessions";
+export type { ArchivedFileInfo, ArchivedToolCallInfo, CompactionInfo, ToolBridgeContent, } from "./schemas/message";
+export { inferToolStatus } from "./schemas/message";
+export type { ChatEnd, ContentDelta, LlmResponseDone, SessionStatusEvent, SystemError, ToolCallArgumentsDelta, ToolCallCreated, ToolResultDelta, ToolResultDone, } from "./schemas/event";
+export { buildMessageContent, extractTextAttachments, isBackgroundWakeMessage, isHiddenInternalMessage, normalizeMessageContent, } from "./schemas/message-utils";
+export type { ParsedTextAttachment, ParsedTextContext } from "./schemas/message-utils";
+export { contextProjectionData, getContextDisplayState, getContextGroupDisplayState, groupAdjacentContextRuns, } from "./schemas/context";
+export type { ContextAction, ContextDisplayState, ContextGroupDisplayState, ContextProjectionData, ContextProjectionFields, ContextSourceInfo, } from "./schemas/context";
+export type { ContentBlock, FinalArtifact, MemoryRef, PatchEnvelope, PendingQuestionRef, PostChatFollowup, RunTiming, ToolCallProjection, TurnProjection, } from "./schemas/projection";
+export { latestPostChatFollowup } from "./schemas/projection-utils";
+export { buildToolUiCardKey, collectInlineToolUiCards, collectPreviewToolUiCards, isAppDevToolUiCard, isInternalStatusToolUiCard, isToolUiCard, resolveToolUiCardContent, } from "./shared/tool-ui-card";
+export type { InlineToolUiCardEntry, PreviewToolUiCardEntry, ToolUiCard, ToolUiCardContentType, } from "./shared/tool-ui-card";
+export type { ModeId, PrimarySkillParallelMode, PrimarySkillSnapshot, PrimarySkillStageSpec, PrimarySkillStepSpec, PublishedSolutionRef, ReplayPreview, SessionPortMapping, SessionSearchMatch, SkillEditorTemplateId, 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";
+export type { BackgroundTask, BackgroundTaskStopResult } from "./schemas/background";
+export type * from "./types/sdk-profile";
+export { acceptedPostChatFollowupCompletesLatestRun, acknowledgeTurnEvents, ClientProjectionBuilder, hasChatRunEvent, } from "./shared/projection";
+export type { RawEvent } from "./shared/projection";
+export { AuthBusyReconnect, authBusyRetryDelayMs } from "./shared/auth-busy";
+export { isOomText, OOM_MESSAGE } from "./shared/oom";
+export { createSocket } from "./socket";
+export type { CreateSocketOptions, TypedSocket } from "./socket";
+export type { AsrAudioPayload } from "./types/socket-events";

package/dist/internal.js

@@ -0,0 +1,340 @@
+import {
+  AgentSession,
+  AgentSessionError,
+  AuthBusyReconnect,
+  BladeApiError,
+  BladeClient,
+  ChatGroupsResource,
+  ClientProjectionBuilder,
+  ComputersResource,
+  DEFAULT_REPLAY_SPEED,
+  EMPTY_SESSION_QUEUE,
+  ModelsResource,
+  OOM_MESSAGE,
+  PluginsResource,
+  SDK_NAME,
+  SDK_VERSION,
+  SessionHub,
+  SessionInfo,
+  SessionSetupError,
+  SessionStatus,
+  acceptedPostChatFollowupCompletesLatestRun,
+  acknowledgeTurnEvents,
+  applyTurnPatch,
+  authBusyRetryDelayMs,
+  buildMessageContent,
+  buildToolUiCardKey,
+  canCancelQueuedMessage,
+  canDeliverQueuedMessage,
+  canEditQueuedMessage,
+  canToggleComputer,
+  chatErrorForDisplay,
+  collectInlineToolUiCards,
+  collectPreviewToolUiCards,
+  computerDaemonVersion,
+  computerOS,
+  computerPlatformLabel,
+  computerState,
+  contentPreview,
+  contextProjectionData,
+  createInitialSessionState,
+  createSocket,
+  extractTextAttachments,
+  getContextDisplayState,
+  getContextGroupDisplayState,
+  getFileParts,
+  getImageParts,
+  getTextContent,
+  groupAdjacentContextRuns,
+  groupMessagesByLoop,
+  hasChatRunEvent,
+  inferToolStatus,
+  isAppDevToolUiCard,
+  isBackgroundWakeMessage,
+  isEntryGoneError,
+  isHiddenInternalMessage,
+  isInternalStatusToolUiCard,
+  isMcpAppData,
+  isOomText,
+  isRecord,
+  isSessionQueueSnapshot,
+  isToolUiCard,
+  isWorkflowRunToolName,
+  normalizeMessageContent,
+  parentForkToolCallIdFromTurn,
+  parseQueueAck,
+  prependOlder,
+  queuePauseReasonLabel,
+  queuedMessageStatusLabel,
+  reconcileHistoricalUserTurns,
+  reconcileOptimisticUserTurns,
+  replaceWindow,
+  resolveToolUiCardContent,
+  sessionStatusFromChatEnd,
+  shouldApplySnapshot,
+  sortComputers,
+  toReplaySnapshot,
+  transformSlashCommand,
+  upsertTurn,
+  userFacingErrorText,
+  withTurns,
+  workflowEntriesFromOutput,
+  workflowNameFromArguments
+} from "./chunk-U2VELZGU.js";
+
+// 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",
+  "hub",
+  "agent",
+  "oauth",
+  "llmGateway",
+  "gitea",
+  "tile"
+];
+var EMPTY_PLATFORM_ENDPOINTS = Object.freeze({
+  services: Object.freeze({})
+});
+function defaultDocumentBaseUrl() {
+  if (typeof document === "undefined") return void 0;
+  if (document.querySelector("base[href]")) return document.baseURI;
+  if (typeof location !== "undefined" && location.origin) return `${location.origin}/`;
+  return document.baseURI;
+}
+function normalizeServiceUrl(value) {
+  if (typeof value !== "string" || !value.trim()) return null;
+  if (value.includes("?") || value.includes("#")) return null;
+  try {
+    const url = new URL(value.trim());
+    if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+    if (url.username || url.password || url.search || url.hash) return null;
+    return url.toString().replace(/\/$/, "");
+  } catch {
+    return null;
+  }
+}
+function parsePlatformEndpoints(value) {
+  if (!isRecord(value) || !isRecord(value.services)) return null;
+  const services = {};
+  for (const name of PLATFORM_SERVICE_NAMES) {
+    if (!(name in value.services)) continue;
+    const url = normalizeServiceUrl(value.services[name]);
+    if (!url) return null;
+    if (name === "agent" && new URL(url).pathname !== "/") return null;
+    services[name] = url;
+  }
+  return { services };
+}
+async function loadPlatformEndpoints(options = {}) {
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+  const baseUrl = options.baseUrl ?? defaultDocumentBaseUrl();
+  if (!fetchImpl || !baseUrl) return EMPTY_PLATFORM_ENDPOINTS;
+  const controller = new AbortController();
+  const timeout = globalThis.setTimeout(() => controller.abort(), options.timeoutMs ?? 3e3);
+  try {
+    const response = await fetchImpl(new URL("config.json", baseUrl), {
+      cache: "no-store",
+      credentials: "same-origin",
+      headers: { Accept: "application/json" },
+      signal: controller.signal
+    });
+    if (!response.ok) return EMPTY_PLATFORM_ENDPOINTS;
+    return parsePlatformEndpoints(await response.json()) ?? EMPTY_PLATFORM_ENDPOINTS;
+  } catch {
+    return EMPTY_PLATFORM_ENDPOINTS;
+  } finally {
+    globalThis.clearTimeout(timeout);
+  }
+}
+function resolveServiceUrl(endpoints, name, path = "") {
+  const baseUrl = endpoints.services[name];
+  if (!baseUrl) return null;
+  if (!path) return baseUrl;
+  const pathReference = path.trimStart();
+  if (path.includes("\\") || pathReference.startsWith("//") || /^[a-z][a-z0-9+.-]*:/i.test(pathReference)) {
+    return null;
+  }
+  const base = new URL(`${baseUrl}/`);
+  const target = new URL(path.replace(/^\/+/, ""), base);
+  if (target.origin !== base.origin || !target.pathname.startsWith(base.pathname)) {
+    return null;
+  }
+  return target.toString();
+}
+
+// src/commands/protocol.ts
+function isCommandEnvelope(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const record = value;
+  return record.__bladeBridge === true && record.direction === "agent-to-host" && typeof record.action === "string";
+}
+function isInboundEnvelope(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const record = value;
+  return record.__bladeBridge === true && record.direction === "host-to-agent" && (record.action === "addContext" || record.action === "appendInput" || record.action === "sendMessage");
+}
+
+// src/schemas/projection-utils.ts
+function latestPostChatFollowup(turns) {
+  for (let index = turns.length - 1; index >= 0; index -= 1) {
+    const turn = turns[index];
+    if (turn.loop_id === "root" && (turn.role === "user" || turn.role === "assistant") && (turn.kind ?? "message") === "message" && !turn.blocks.some(
+      (block) => ["mode_change", "plan_status", "ask_user_answer"].includes(block.type)
+    )) {
+      return turn.role === "assistant" ? turn.post_chat_followup ?? null : null;
+    }
+  }
+  return null;
+}
+
+// src/schemas/solution.ts
+var LayoutType = /* @__PURE__ */ ((LayoutType2) => {
+  LayoutType2["Default"] = "default";
+  LayoutType2["SkillEditor"] = "skill-editor";
+  LayoutType2["SolutionEditor"] = "solution-editor";
+  LayoutType2["SolutionApp"] = "solution-app";
+  LayoutType2["Custom"] = "custom";
+  return LayoutType2;
+})(LayoutType || {});
+
+// src/schemas/task.ts
+import { type } from "arktype";
+var TaskStatus = type("'pending' | 'in_progress' | 'done' | 'failed' | 'skipped'");
+var Task = type({
+  id: "string",
+  goal: "string",
+  skills: "string[]",
+  depends_on: "string[]",
+  status: TaskStatus,
+  result_summary: "string",
+  number: "string"
+});
+export {
+  AgentSession,
+  AgentSessionError,
+  AuthBusyReconnect,
+  BladeApiError,
+  BladeClient,
+  ChatGroupsResource,
+  ClientProjectionBuilder,
+  ComputersResource,
+  DEFAULT_REPLAY_SPEED,
+  EMPTY_PLATFORM_ENDPOINTS,
+  EMPTY_SESSION_QUEUE,
+  LayoutType,
+  ModelsResource,
+  OOM_MESSAGE,
+  PluginsResource,
+  PollingBackoff,
+  SDK_NAME,
+  SDK_VERSION,
+  SessionHub,
+  SessionInfo,
+  SessionSetupError,
+  SessionStatus,
+  Task,
+  TaskStatus,
+  acceptedPostChatFollowupCompletesLatestRun,
+  acknowledgeTurnEvents,
+  applyTurnPatch,
+  authBusyRetryDelayMs,
+  buildMessageContent,
+  buildToolUiCardKey,
+  canCancelQueuedMessage,
+  canDeliverQueuedMessage,
+  canEditQueuedMessage,
+  canToggleComputer,
+  chatErrorForDisplay,
+  collectInlineToolUiCards,
+  collectPreviewToolUiCards,
+  computerDaemonVersion,
+  computerOS,
+  computerPlatformLabel,
+  computerState,
+  contentPreview,
+  contextProjectionData,
+  createInitialSessionState,
+  createSocket,
+  extractTextAttachments,
+  getContextDisplayState,
+  getContextGroupDisplayState,
+  getFileParts,
+  getImageParts,
+  getTextContent,
+  groupAdjacentContextRuns,
+  groupMessagesByLoop,
+  hasChatRunEvent,
+  inferToolStatus,
+  isAppDevToolUiCard,
+  isBackgroundWakeMessage,
+  isCommandEnvelope,
+  isEntryGoneError,
+  isHiddenInternalMessage,
+  isInboundEnvelope,
+  isInternalStatusToolUiCard,
+  isMcpAppData,
+  isOomText,
+  isSessionQueueSnapshot,
+  isToolUiCard,
+  isWorkflowRunToolName,
+  latestPostChatFollowup,
+  loadPlatformEndpoints,
+  normalizeMessageContent,
+  parentForkToolCallIdFromTurn,
+  parseQueueAck,
+  prependOlder,
+  queuePauseReasonLabel,
+  queuedMessageStatusLabel,
+  reconcileHistoricalUserTurns,
+  reconcileOptimisticUserTurns,
+  replaceWindow,
+  resolveServiceUrl,
+  resolveToolUiCardContent,
+  sessionStatusFromChatEnd,
+  shouldApplySnapshot,
+  sortComputers,
+  toReplaySnapshot,
+  transformSlashCommand,
+  upsertTurn,
+  userFacingErrorText,
+  withTurns,
+  workflowEntriesFromOutput,
+  workflowNameFromArguments
+};
+//# sourceMappingURL=internal.js.map

package/dist/internal.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/polling-backoff.ts","../src/platform-endpoints.ts","../src/commands/protocol.ts","../src/schemas/projection-utils.ts","../src/schemas/solution.ts","../src/schemas/task.ts"],"sourcesContent":["import { BladeApiError } from \"./rest\"\n\nconst MAX_BACKOFF_MS = 60_000\nconst MAX_TIMER_MS = 2_147_483_647\n\n/** Scheduling policy for read-only polling; never sends or replays a request. */\nexport class PollingBackoff {\n  private failures = 0\n  private nextAt: number | false = 0\n\n  constructor(private readonly intervalMs: number) {\n    if (!Number.isFinite(intervalMs) || intervalMs <= 0 || intervalMs > MAX_BACKOFF_MS) {\n      throw new RangeError(\"Polling interval must be between 0 and 60000 ms\")\n    }\n  }\n\n  reset(): void {\n    this.failures = 0\n    this.nextAt = 0\n  }\n\n  failed(error: unknown): void {\n    if (\n      (error instanceof Error && error.name === \"AbortError\") ||\n      (error instanceof BladeApiError && error.status < 500 &&\n        error.status !== 408 && error.status !== 429)\n    ) {\n      this.nextAt = false\n      return\n    }\n    this.failures = Math.min(this.failures + 1, 10)\n    const ceiling = Math.min(MAX_BACKOFF_MS, this.intervalMs * 2 ** this.failures)\n    const backoff = Math.max(this.intervalMs, ceiling * (0.5 + Math.random() * 0.5))\n    const header = error instanceof BladeApiError\n      ? error.response.headers.get(\"Retry-After\")?.trim()\n      : undefined\n    const retryAfter = header\n      ? /^\\d+$/.test(header) ? Number(header) * 1000 : Date.parse(header) - Date.now()\n      : 0\n    const delay = Math.max(backoff, Number.isNaN(retryAfter) ? 0 : retryAfter)\n    // Oversized server delays must not overflow browser timers into a hot loop.\n    this.nextAt = delay > MAX_TIMER_MS ? false : Date.now() + delay\n  }\n\n  /** Zero means ready, false means stop, otherwise wait at least this many ms. */\n  waitMs(): number | false {\n    return this.nextAt === false ? false : Math.max(0, this.nextAt - Date.now())\n  }\n}\n","import { isRecord } from \"./shared/type-guards\"\n\nexport const PLATFORM_SERVICE_NAMES = [\n  \"os\",\n  \"hub\",\n  \"agent\",\n  \"oauth\",\n  \"llmGateway\",\n  \"gitea\",\n  \"tile\",\n] as const\n\nexport type PlatformServiceName = (typeof PLATFORM_SERVICE_NAMES)[number]\n\nexport interface PlatformEndpoints {\n  services: Partial<Record<PlatformServiceName, string>>\n}\n\nexport const EMPTY_PLATFORM_ENDPOINTS: PlatformEndpoints = Object.freeze({\n  services: Object.freeze({}),\n})\n\nexport interface LoadPlatformEndpointsOptions {\n  baseUrl?: string\n  fetchImpl?: typeof fetch\n  timeoutMs?: number\n}\n\nfunction defaultDocumentBaseUrl(): string | undefined {\n  if (typeof document === \"undefined\") return undefined\n  if (document.querySelector(\"base[href]\")) return document.baseURI\n  if (typeof location !== \"undefined\" && location.origin) return `${location.origin}/`\n  return document.baseURI\n}\n\nfunction normalizeServiceUrl(value: unknown): string | null {\n  if (typeof value !== \"string\" || !value.trim()) return null\n  if (value.includes(\"?\") || value.includes(\"#\")) return null\n  try {\n    const url = new URL(value.trim())\n    if (url.protocol !== \"http:\" && url.protocol !== \"https:\") return null\n    if (url.username || url.password || url.search || url.hash) return null\n    return url.toString().replace(/\\/$/, \"\")\n  } catch {\n    return null\n  }\n}\n\nexport function parsePlatformEndpoints(value: unknown): PlatformEndpoints | null {\n  if (!isRecord(value) || !isRecord(value.services)) return null\n\n  const services: Partial<Record<PlatformServiceName, string>> = {}\n  for (const name of PLATFORM_SERVICE_NAMES) {\n    if (!(name in value.services)) continue\n    const url = normalizeServiceUrl(value.services[name])\n    if (!url) return null\n    if (name === \"agent\" && new URL(url).pathname !== \"/\") return null\n    services[name] = url\n  }\n\n  return { services }\n}\n\nexport async function loadPlatformEndpoints(\n  options: LoadPlatformEndpointsOptions = {},\n): Promise<PlatformEndpoints> {\n  const fetchImpl = options.fetchImpl ?? globalThis.fetch\n  const baseUrl = options.baseUrl ?? defaultDocumentBaseUrl()\n  if (!fetchImpl || !baseUrl) return EMPTY_PLATFORM_ENDPOINTS\n\n  const controller = new AbortController()\n  const timeout = globalThis.setTimeout(() => controller.abort(), options.timeoutMs ?? 3_000)\n  try {\n    const response = await fetchImpl(new URL(\"config.json\", baseUrl), {\n      cache: \"no-store\",\n      credentials: \"same-origin\",\n      headers: { Accept: \"application/json\" },\n      signal: controller.signal,\n    })\n    if (!response.ok) return EMPTY_PLATFORM_ENDPOINTS\n    return parsePlatformEndpoints(await response.json()) ?? EMPTY_PLATFORM_ENDPOINTS\n  } catch {\n    return EMPTY_PLATFORM_ENDPOINTS\n  } finally {\n    globalThis.clearTimeout(timeout)\n  }\n}\n\nexport function resolveServiceUrl(\n  endpoints: PlatformEndpoints,\n  name: PlatformServiceName,\n  path = \"\",\n): string | null {\n  const baseUrl = endpoints.services[name]\n  if (!baseUrl) return null\n  if (!path) return baseUrl\n  const pathReference = path.trimStart()\n  if (\n    path.includes(\"\\\\\") ||\n    pathReference.startsWith(\"//\") ||\n    /^[a-z][a-z0-9+.-]*:/i.test(pathReference)\n  ) {\n    return null\n  }\n  const base = new URL(`${baseUrl}/`)\n  const target = new URL(path.replace(/^\\/+/, \"\"), base)\n  if (target.origin !== base.origin || !target.pathname.startsWith(base.pathname)) {\n    return null\n  }\n  return target.toString()\n}\n","/**\n * 页面协作协议（对应后端 `_meta.bridge` 通道，见 docs/specs/260417-embed-bridge）。\n *\n * ## action 从哪里来\n *\n * 智能体 → 宿主方向的每一条指令，都源自**技能作者写的工具代码**：工具返回值\n * JSON 里带 `_meta.bridge: { action, payload }`，后端在持久化前把它剥离成独立\n * 事件送达前端（LLM 的对话历史里读不到它）。因此：\n *\n * - action 字符串（如 \"map.highlight\"）是**技能作者与宿主页面开发者之间的业务\n *   契约**，LLM 不参与协议、SDK 不做枚举校验；\n * - 宿主页面用 `session.onCommand(\"map.highlight\", fn)` 消费；\n * - 未注册 handler 的 action 会进入有限缓冲等待注册，超限后丢弃并 console 告警。\n *\n * 宿主 → 智能体方向只有三个白名单动作：attach（附件入输入框）/ insertText\n * （追加输入文本）/ send（直接发消息），对应协议层的 addContext / appendInput /\n * sendMessage。\n */\n\nexport interface CommandEnvelope {\n  __bladeBridge: true\n  direction: \"agent-to-host\"\n  action: string\n  payload: unknown\n  meta: {\n    sessionId: string\n    toolCallId?: string\n    timestamp: number\n  }\n}\n\nexport type InboundAction = \"addContext\" | \"appendInput\" | \"sendMessage\"\n\nexport interface InboundEnvelope {\n  __bladeBridge: true\n  direction: \"host-to-agent\"\n  action: InboundAction\n  payload: unknown\n}\n\nexport function isCommandEnvelope(value: unknown): value is CommandEnvelope {\n  if (typeof value !== \"object\" || value === null) return false\n  const record = value as Record<string, unknown>\n  return (\n    record.__bladeBridge === true &&\n    record.direction === \"agent-to-host\" &&\n    typeof record.action === \"string\"\n  )\n}\n\nexport function isInboundEnvelope(value: unknown): value is InboundEnvelope {\n  if (typeof value !== \"object\" || value === null) return false\n  const record = value as Record<string, unknown>\n  return (\n    record.__bladeBridge === true &&\n    record.direction === \"host-to-agent\" &&\n    (record.action === \"addContext\" || record.action === \"appendInput\" || record.action === \"sendMessage\")\n  )\n}\n","import type { PostChatFollowup, TurnProjection } from \"./projection\"\n\n/** 返回最新根会话轮次的小结；新用户消息到达后旧小结立即失效。 */\nexport function latestPostChatFollowup(turns: TurnProjection[]): PostChatFollowup | null {\n  for (let index = turns.length - 1; index >= 0; index -= 1) {\n    const turn = turns[index]\n    if (\n      turn.loop_id === \"root\" &&\n      (turn.role === \"user\" || turn.role === \"assistant\") &&\n      (turn.kind ?? \"message\") === \"message\" &&\n      !turn.blocks.some((block) =>\n        [\"mode_change\", \"plan_status\", \"ask_user_answer\"].includes(block.type),\n      )\n    ) {\n      return turn.role === \"assistant\" ? (turn.post_chat_followup ?? null) : null\n    }\n  }\n  return null\n}\n","export enum LayoutType {\n  Default = \"default\",\n  SkillEditor = \"skill-editor\",\n  SolutionEditor = \"solution-editor\",\n  SolutionApp = \"solution-app\",\n  Custom = \"custom\",\n}\n\nexport interface Solution {\n  id: string\n  name: string\n  version: string\n  description?: string | null\n  source?: \"builtin\" | \"personal\" | string | null\n  layout_type: LayoutType | string\n  initial_mode?: \"planning\" | \"executing\" | string | null\n  initial_message?: string | null\n  preview?: { url: string; title?: string | null } | null\n  layout?: {\n    available?: boolean\n    source_dir?: string\n    entry?: string\n    export?: string\n  } | null\n  roles?: BizRole[] | null\n  data?: Record<string, unknown> | null\n  ui_config?: SolutionAppUiConfig | null\n}\n\nexport interface SolutionAppUiConfig {\n  branding: {\n    name: string\n    subtitle?: string\n    icon_text: string\n    icon_gradient?: string\n  }\n  list: {\n    title: string\n    create_button: string\n    card?: {\n      subtitle?: string\n      stats?: Array<{\n        label: string\n        value: string\n        color?: string\n      }>\n    }\n  }\n  create: {\n    title: string\n    description?: string\n    submit_button: string\n    sections: Array<{\n      id: string\n      title: string\n      description?: string\n      fields: Array<SolutionAppField>\n    }>\n  }\n}\n\nexport type SolutionAppField =\n  | {\n      id: string\n      kind: \"textarea\"\n      label: string\n      placeholder?: string\n    }\n  | {\n      id: string\n      kind: \"file-upload\"\n      accept?: string[]\n      categories?: Array<{\n        label: string\n        description: string\n        color: string\n      }>\n    }\n\nexport interface SolutionAppState {\n  pipeline: Array<{\n    id: string\n    label: string\n    status: \"done\" | \"active\" | \"pending\" | \"error\"\n  }>\n  meta: Record<\n    string,\n    {\n      label: string\n      value: string\n      color?: string\n    }\n  >\n}\n\nexport interface BizRole {\n  id: string\n  name: string\n  description?: string | null\n  preview?: { url: string; title?: string | null } | null\n}\n","import { type } from \"arktype\"\n\nexport const TaskStatus = type(\"'pending' | 'in_progress' | 'done' | 'failed' | 'skipped'\")\nexport type TaskStatus = typeof TaskStatus.infer\n\nexport const Task = type({\n  id: \"string\",\n  goal: \"string\",\n  skills: \"string[]\",\n  depends_on: \"string[]\",\n  status: TaskStatus,\n  result_summary: \"string\",\n  number: \"string\",\n})\nexport type Task = typeof Task.infer\n"],"mappings":"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","names":["LayoutType"]}

package/dist/schemas/projection.d.ts

@@ -66,6 +66,7 @@ export interface TurnProjection {
     kind?: "message" | "context" | "compaction";
     role: "user" | "assistant" | "system";
     status: "streaming" | "completed" | "paused" | "failed" | "interrupted";
+    error_message?: string | null;
     blocks: ContentBlock[];
     tool_calls: ToolCallProjection[];
     model?: string | null;
@@ -134,6 +135,8 @@ export interface PatchEnvelope {
             tool_call_id?: string;
             tool_name?: string;
             workspace_path?: string;
+            /** 本次工具改动的文件（相对工作区）；缺省表示不知道具体文件。 */
+            paths?: string[];
         };
     };
 }

package/dist/schemas/solution.d.ts

@@ -1,11 +1,7 @@
 export declare enum LayoutType {
     Default = "default",
     SkillEditor = "skill-editor",
-    BladeCoa = "blade-coa",
     SolutionEditor = "solution-editor",
-    SolutionEditor2 = "solution-editor2",
-    ChatPreview = "chat-preview",
-    ChatOnly = "chat-only",
     SolutionApp = "solution-app",
     Custom = "custom"
 }

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

@@ -15,11 +15,13 @@ export interface SessionRuntime {
     fetchTurnsPage(sessionId: string, query?: SessionTurnsQuery, init?: RequestInit): Promise<SessionTurnsPage>;
     fetchTurnIndex(sessionId: string): Promise<SessionTurnIndex>;
     fetchCommands(sessionId: string): Promise<HistoricalCommand[]>;
-    /** 会话详情，目前只用来取回放状态。 */
-    fetchSessionInfo(sessionId: string): Promise<{
-        replay_state?: ReplayState | null;
-        viewer_role?: "owner" | "viewer";
-    }>;
+    /**
+     * 会话详情包含会话状态、回放状态、查看权限和运行时类型。`fresh` 为 true 时必须取最新值
+     * （重连补数）；为 false 时宿主可以复用刚取过的一份（进入会话）。
+     */
+    fetchSessionInfo(sessionId: string, options?: {
+        fresh?: boolean;
+    }): Promise<SessionDetailSnapshot>;
     updateReplay(sessionId: string, payload: {
         speed?: ReplaySpeed;
         status?: "autonomous";
@@ -34,6 +36,20 @@ export interface SessionRuntime {
      */
     onDispose(session: AgentSession): boolean;
 }
+export interface SessionDetailSnapshot {
+    status?: SessionStatus;
+    replay_state?: ReplayState | null;
+    viewer_role?: "owner" | "viewer";
+    runtime_type?: string | null;
+}
+/** 服务端 chat:end 载荷里 AgentSession 关心的字段。 */
+export interface ChatEndPayload {
+    status?: string;
+    /** 排队中断：服务端取消了排队中的发送，`cancelled_client_request_ids` 是被取消的请求。 */
+    queued?: boolean;
+    cancelled_client_request_ids?: unknown;
+    pause_tool_data?: Record<string, unknown>;
+}
 export interface AttachAppOptions {
     /** 可选；只需要页面上下文时无需提供 CLI。 */
     cli?: AppCliDefinition;
@@ -49,6 +65,8 @@ export interface SendOptions {
     model?: string;
     /** 本次运行是否强制开/关思考。 */
     thinkingOverride?: boolean;
+    /** 本次运行的推理强度（模型支持时生效）。 */
+    reasoningLevel?: string;
     whatif?: {
         from_step: number;
         quotes: Array<Record<string, unknown>>;
@@ -74,6 +92,10 @@ export declare function sessionStatusFromChatEnd(status: string | undefined): Se
 export declare class AgentSession {
     readonly sessionId: string;
     private state;
+    /** status 每变化一次加一（单调递增）。异步读取会话详情时据此判断请求期间状态是否变过，避免 running→终态→running 这类来回被误认为「没变」。 */
+    private statusRevision;
+    /** 实时事件写入 status 时调用：值不变也要记一次，才能识别请求期间收到过更新的状态。 */
+    private noteLiveStatus;
     private readonly listeners;
     private readonly emitter;
     private readonly commands;
@@ -127,6 +149,20 @@ export declare class AgentSession {
     private getAppContext;
     private sendPending;
     private manualCompactionPending;
+    /** 手动整理的在途标记，同时写进状态（界面据此保持「正在整理」，见 SessionState.compactionPending）。 */
+    private setManualCompactionPending;
+    /** 最近一次还在等服务端结果的发送请求 id；排队中断的 chat:end 据此判断回滚是否过期。 */
+    private pendingChatRequestId;
+    /** 会话详情给出的运行时类型；"native" 时启用原生智能体的投影规则（见 _handleTurnEvents / _handleChatEnd）。 */
+    private runtimeType;
+    /** workflow_run_id → 触发它的 workflow:run 工具调用 id（只有 run:start 事件带工具调用 id）。 */
+    private readonly workflowRunToolCalls;
+    /**
+     * 第一方 Web 的精简模式传输优化：订阅时是否要 token 级事件。null 表示宿主没设置，订阅时不带这个字段。
+     * `desiredStreamTokens` 是宿主最新的选择；运行中不切换，等这一轮结束再重订阅。
+     */
+    private desiredStreamTokens;
+    private joinedStreamTokens;
     private readonly deliveredCommandKeys;
     private readonly deliveredToolPreviews;
     private readonly oomNotifiedKeys;
@@ -135,6 +171,7 @@ export declare class AgentSession {
     private readonly emittedMessageTurnIds;
     constructor(sessionId: string, runtime: SessionRuntime, connection: ConnectionStatus, options?: {
         staticHistory?: boolean;
+        streamTokens?: boolean | null;
     });
     /**
      * 静态历史（分享页 / `fromTurns`）：没有目录接口，也**没有**"目录还没到位"这个中间态。
@@ -143,8 +180,11 @@ export declare class AgentSession {
      * 旧分支的发言，拿它兜底会把已经失效的 entry id 重新摆到轨道上，点了必然找不到。
      */
     readonly isStatic: boolean;
-    /** 从一份静态 turn 快照构造只展示历史的会话（例如公开分享页）。 */
-    static fromTurns(sessionId: string, turns: TurnProjection[]): AgentSession;
+    /**
+     * 从一份静态 turn 快照构造只展示历史的会话（例如公开分享页）。`overrides` 覆盖展示相关的少数字段
+     * （只读身份、开发调试页模拟的流式状态）。
+     */
+    static fromTurns(sessionId: string, turns: TurnProjection[], overrides?: Partial<Pick<SessionState, "isStreaming" | "status" | "viewerRole">>): AgentSession;
     /** 返回当前会话快照。引用稳定：状态未变化时返回同一对象。 */
     getState(): SessionState;
     get hasOlderHistory(): boolean;
@@ -169,6 +209,17 @@ export declare class AgentSession {
      * 否则"运行刚结束时点一下侧栏"就会把终态对账一起中止，流式与历史对不上。
      */
     cancelPendingLocate(): void;
+    /**
+     * 历史被外部改写后（rewind / checkout 分支等由宿主发起的操作）整窗重新加载最新一页：
+     * 作废在途的旧结果，递增 `timelineRevision`；同时向服务端确认一次运行状态（改写期间错过的
+     * chat:end 会让界面停在「运行中」）。
+     */
+    reloadHistory(): Promise<boolean>;
+    /**
+     * 向服务端确认会话此刻是否在运行，校准流式状态（残留的「运行中」会被清掉）。只在已加入房间时
+     * 生效；不带 resume，服务端不会重发上一轮的终态事件（否则会被当成一次新的结束）。
+     */
+    refreshRunningState(): Promise<void>;
     /**
      * timeline 被整体改写（rewind / checkout / 释放）：推进纪元，并把在途定位请求一并中止
      * ——它已经属于旧 timeline，却还占着替换队列，会让改写后的权威窗口排在后面等它跑完。
@@ -281,8 +332,10 @@ export declare class AgentSession {
     private enqueueSubscription;
     /** 改回放是 owner 专属（服务端 PATCH 走 _get_owned_session）。 */
     private get canControlReplay();
-    /** 拉一次会话详情，填回放状态和只读身份；失败按非回放会话处理，不挡启动。 */
-    private syncReplayFromSession;
+    /** 拉一次会话详情，填会话状态、回放状态、只读身份和运行时类型；失败不挡启动。 */
+    private syncSessionFromDetail;
+    /** 安装一份会话详情；`statusRevisionAtRequest` 是发出请求时的状态修订号。 */
+    private applySessionDetail;
     /** 调整回放倍速；不是回放会话、或只读身份时什么都不做。 */
     setReplaySpeed(speed: ReplaySpeed): Promise<void>;
     /** 退出回放，之后的对话交给真实模型运行；不是回放会话、或只读身份时什么都不做。 */
@@ -299,14 +352,17 @@ export declare class AgentSession {
     _handleTurnEvents(events: RawEvent[], replayed?: boolean): void;
     /** @internal */
     _handleChatStart(): void;
-    /** @internal */
-    _handleChatEnd(status: string): void;
+    /**
+     * @internal 返回 false 表示这是一条过期的排队回滚（被取消的是更早的请求，当前运行不受影响），
+     * Hub 据此不把它当成一次运行结束广播出去。
+     */
+    _handleChatEnd(payload?: ChatEndPayload): boolean;
     /** @internal */
     _handleSystemError(message: string, code?: string): void;
     /** @internal */
     _handleTaskUpdated(tasks: unknown[]): void;
     /** @internal */
-    _handleWorkspaceFilesChanged(filePath?: string): void;
+    _handleWorkspaceFilesChanged(filePath?: string, paths?: string[] | null): void;
     /** @internal */
     _handleSessionUpdated(data: {
         workspace_path?: string;
@@ -334,6 +390,20 @@ export declare class AgentSession {
     _applyRunningState(isRunning: boolean, liveRevisionAtJoin?: number): void;
     private markRunningIfIdle;
     private finishStreaming;
+    /**
+     * 原生智能体常在用户发言之前就宣告一个空的 assistant 回合（投影的起点），它的真实内容会随第一条
+     * 输出再发一次。消息列表在启动期间本来就显示一个「正在生成」占位，两者并存会出现两个占位，
+     * 所以只丢掉原生会话里这种空的流式回合。
+     */
+    private isNativeBootstrapTurn;
+    /** 实时 workflow:* 事件叠加到对应工具调用的时间线上（见 workflow.ts 的来源规则）。 */
+    private applyWorkflowEvents;
+    /**
+     * @internal 宿主改了 token 订阅偏好（精简模式）。空闲时立即重订阅；运行中等这一轮结束再换，
+     * 避免在输出中途丢掉 token 流。
+     */
+    _setStreamTokens(enabled: boolean): void;
+    private applyDesiredStreamTokens;
     private completeChat;
     private markTurnFresh;
     private markOptimisticTurnPending;

package/dist/session/events.d.ts

@@ -67,9 +67,23 @@ export interface AgentSessionEvents {
         loopId?: string;
         metadata?: Record<string, unknown>;
     };
-    /** 工作区文件发生变化（写文件、重命名等）。 */
+    /**
+     * 工作区文件发生变化（写文件、重命名等）。`paths` 是已知的变化路径（相对工作区，
+     * 目录以 `/` 结尾）；没有 `filePath` 也没有 `paths` 时表示不知道具体变了什么。
+     */
     workspaceChanged: {
         filePath?: string;
+        paths?: string[];
+        /** 工具切换了会话工作目录时的新目录（例如绑定到分组工作区）。 */
+        workspacePath?: string;
+    };
+    /**
+     * 一条回合在实时通道上落地（新出现或内容更新），供宿主做自己的副作用（打开预览、标记面板未读等）。
+     * 历史加载（REST）不触发；`source` 区分真正的实时更新与订阅时服务端重发的缓冲。
+     */
+    turnUpdated: {
+        turn: TurnProjection;
+        source: "live" | "bootstrap_replay" | "reconnect_replay";
     };
     /** 智能体产出了文件成果（artifact:created / artifact:updated）。 */
     artifact: {