@blade-hq/agent-client 2610.0.0-beta.2 → 2610.0.0-beta.21

package/README.md

@@ -2,16 +2,21 @@
 
 Blade Agent 的框架无关客户端。浏览器和 Node.js 都能用；用 Vue、Svelte 或自建 UI 的团队直接用这个包，React 团队一般用上层的 `@blade-hq/agent-react`。
 
-它做三件事：
+它做四件事：
 
 1. **实时会话**（`AgentSession`）：把 Socket.IO 协议、历史加载、流式合流、断线重连全部封装掉，你只面对"状态快照 + 动作 + 事件"。
 2. **登录**：`client.auth.login()` 弹窗授权，用户点一下"许可授权"就拿到访问令牌，不用手工复制粘贴。
 3. **REST**：类型化会话和模型目录（`client.sessions.*`、`client.models.list()`）。其他长尾接口对照 Swagger 用原生 `fetch` + `client.token` 调用。
+4. **部署端点**：从同源 `config.json` 读取其他 Blade 服务的公开地址，不根据主机名和固定端口猜测拓扑。
 
 ```bash
 npm install @blade-hq/agent-client
 ```
 
+默认装到的是当前长期支持版（LTS），厂内离线交付按它开发。要跟两周一发的公网版本，改用 `@next`。
+
+最稳妥的做法是先读目标 Server 的 `GET /api/version`，按返回的版本号在 `package.json` 里钉死——NPM 的 `latest` 不一定和目标环境跑的版本一致。
+
 ## 快速开始
 
 ```html
@@ -47,6 +52,27 @@ const client = new BladeClient({
 })
 ```
 
+## 部署端点
+
+Blade 平台前端需要跳转其他服务时，读取当前 origin 的公开配置：
+
+```ts
+import { loadPlatformEndpoints, resolveServiceUrl } from "@blade-hq/agent-client"
+
+const endpoints = await loadPlatformEndpoints()
+const hubUrl = resolveServiceUrl(endpoints, "hub", "/skills/42")
+if (hubUrl) window.open(hubUrl)
+```
+
+`loadPlatformEndpoints()` 请求 `config.json`，超过 3 秒、网络失败或配置非法时返回空配置；
+调用方应隐藏对应入口。文件只能放浏览器可访问的公开地址，不能写 Docker 服务名、令牌或
+其他内部配置。应用部署在子路径时，通过 `baseUrl` 显式传入部署根路径。
+`resolveServiceUrl()` 的 `path` 只接受服务内相对路径；绝对 URL、反斜杠和越出服务
+base path 的路径返回 `null`。
+
+公开类型为 `PlatformEndpoints`、`PlatformServiceName`、`LoadPlatformEndpointsOptions`；
+需要同步初始化时可直接使用 `EMPTY_PLATFORM_ENDPOINTS`。
+
 ## BladeClient
 
 ### 构造
@@ -520,7 +546,7 @@ transformSlashCommand(skillId, prompt, { local: false, installed: false })
 - **会话回放**：`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`、`PostChatFollowup`、`FinalArtifact`、`latestPostChatFollowup`、`buildMessageContent`、`normalizeMessageContent`、`isHiddenInternalMessage`、`transformSlashCommand`、`SkillMentionAvailability`、`extractTextAttachments`、`ParsedTextAttachment`、`ParsedTextContext`
+- **消息与投影协议**：`MessageContent`、`MessageContentPart`、`TextContentPart`、`ImageUrlContentPart`、`FileContentPart`、`ToolCallInfo`、`ToolBridgeContent`、`CompactionInfo`、`ContextProjectionData`、`ContextProjectionFields`、`ContextDisplayState`、`ContextAction`、`ContextSourceInfo`、`MemoryRefInfo`、`ArchivedFileInfo`、`ArchivedToolCallInfo`、`TurnProjection`、`ContentBlock`、`PatchEnvelope`、`MemoryRef`、`PostChatFollowup`、`FinalArtifact`、`contextProjectionData`、`getContextDisplayState`、`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`、`acceptedPostChatFollowupCompletesLatestRun`
+- **低层通道（apps/web 等高级集成）**：`createSocket`、`CreateSocketOptions`、`TypedSocket`、`AsrAudioPayload`、`ClientProjectionBuilder`、`RawEvent`、`acceptedPostChatFollowupCompletesLatestRun`、`reconcileOptimisticUserTurns`

package/dist/index.d.ts

@@ -2,6 +2,8 @@ export { BladeClient } from "./blade-client";
 export type { BladeClientOptions, UploadProgress } from "./blade-client";
 export { BladeApiError } from "./rest";
 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";
 export { SDK_NAME, SDK_VERSION } from "./version";
 export { AgentSession } from "./session/agent-session";
 export type { AttachAppOptions, SendOptions } from "./session/agent-session";
@@ -9,7 +11,7 @@ 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, toReplaySnapshot } from "./session/state";
+export { createInitialSessionState, reconcileOptimisticUserTurns, 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";
@@ -24,6 +26,8 @@ export type { SessionsResource } from "./resources/sessions";
 export type { CreateSessionRequest, AppCliAttachment, AppCliDefinition, FileEntry, ImportSessionOptions, PaginatedSessionsResult, GlobalSearchConversationResult, GlobalSearchFileResult, GlobalSearchResult, GlobalSearchResultItem, ResultFeedback, ResultFeedbackReason, 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 { contextProjectionData, getContextDisplayState, } from "./schemas/context";
+export type { ContextAction, ContextDisplayState, ContextProjectionData, ContextProjectionFields, ContextSourceInfo, } from "./schemas/context";
 export type { ParsedTextAttachment, ParsedTextContext, SkillMentionAvailability, } from "./schemas/message-utils";
 export type { ContentBlock, FinalArtifact, MemoryRef, PatchEnvelope, PostChatFollowup, TurnProjection, } from "./schemas/projection";
 export { latestPostChatFollowup } from "./schemas/projection-utils";