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

package/dist/platform-endpoints.d.ts

@@ -0,0 +1,14 @@
+export declare const PLATFORM_SERVICE_NAMES: readonly ["os", "hub", "agent", "oauth", "llmGateway", "gitea", "tile"];
+export type PlatformServiceName = (typeof PLATFORM_SERVICE_NAMES)[number];
+export interface PlatformEndpoints {
+    services: Partial<Record<PlatformServiceName, string>>;
+}
+export declare const EMPTY_PLATFORM_ENDPOINTS: PlatformEndpoints;
+export interface LoadPlatformEndpointsOptions {
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}
+export declare function parsePlatformEndpoints(value: unknown): PlatformEndpoints | null;
+export declare function loadPlatformEndpoints(options?: LoadPlatformEndpointsOptions): Promise<PlatformEndpoints>;
+export declare function resolveServiceUrl(endpoints: PlatformEndpoints, name: PlatformServiceName, path?: string): string | null;

package/dist/schemas/context.d.ts

@@ -0,0 +1,34 @@
+export type ContextAction = "published" | "retained" | "removed";
+/** Safe display-source metadata retained for headless consumers. */
+export type ContextSourceInfo = Record<string, unknown>;
+export interface ContextProjectionData {
+    context_kind: string;
+    context_key: string;
+    context_name: string;
+    context_order: number;
+    context_action: ContextAction;
+    context_revision: string;
+    display_title?: string | null;
+    display_summary?: string | null;
+    sources: ContextSourceInfo[];
+}
+export interface ContextProjectionFields {
+    context_kind?: string | null;
+    context_key?: string | null;
+    context_name?: string | null;
+    context_order?: number | null;
+    context_action?: ContextAction | null;
+    context_revision?: string | null;
+    display_title?: string | null;
+    display_summary?: string | null;
+    sources?: ContextSourceInfo[] | null;
+}
+export interface ContextDisplayState {
+    title: string;
+    summary: string;
+    detail: string;
+    isRemoved: boolean;
+}
+export declare function contextProjectionData(fields: ContextProjectionFields): ContextProjectionData | null;
+/** The single status-to-display mapping used by both React chat surfaces. */
+export declare function getContextDisplayState(context: ContextProjectionData): ContextDisplayState;

package/dist/schemas/event.d.ts

@@ -11,6 +11,15 @@ export interface ToolCallCreated {
         arguments: string;
     };
 }
+export interface ToolCallArgumentsDelta {
+    index: number;
+    id: string;
+    loop_name?: string;
+    function: {
+        name: string;
+    };
+    arguments_delta: string;
+}
 export interface ToolResultDone {
     tool_call_id: string;
     loop_name?: string;

package/dist/schemas/message.d.ts

@@ -1,4 +1,5 @@
 import type { ContentBlock, PendingQuestionRef, ToolBridgeContent } from "./projection";
+import type { ContextProjectionData } from "./context";
 export interface TextContentPart {
     type: "text";
     text: string;
@@ -70,6 +71,8 @@ export interface ChatMessage {
     duration_ms?: number;
     timestamp?: string;
     entry_id?: string;
+    /** Stable React key retained when an optimistic user message is confirmed. */
+    render_id?: string;
     parent_id?: string | null;
     loop_name?: string;
     /** Entry kind from backend -- present for non-message entries like mode changes. */
@@ -80,4 +83,6 @@ export interface ChatMessage {
     blocks?: ContentBlock[];
     /** Compaction metadata for compaction turns. */
     compaction?: CompactionInfo;
+    /** Sourced Context metadata for rendering or headless consumers. */
+    context?: ContextProjectionData;
 }

package/dist/schemas/projection.d.ts

@@ -47,7 +47,7 @@ export interface TurnProjection {
     sequence: number;
     turn_id: string;
     loop_id: string;
-    kind?: "message" | "compaction";
+    kind?: "message" | "context" | "compaction";
     role: "user" | "assistant" | "system";
     status: "streaming" | "completed" | "paused" | "failed" | "interrupted";
     blocks: ContentBlock[];
@@ -59,6 +59,17 @@ export interface TurnProjection {
     context_window?: number;
     memory_refs?: MemoryRef[] | null;
     parent_fork_tool_call_id?: string | null;
+    context_kind?: string | null;
+    context_key?: string | null;
+    context_name?: string | null;
+    context_order?: number | null;
+    context_action?: import("./context").ContextAction | null;
+    context_revision?: string | null;
+    display_title?: string | null;
+    display_summary?: string | null;
+    sources?: import("./context").ContextSourceInfo[] | null;
+    /** Client-only stable identity for reconciling an optimistic user turn. */
+    client_render_id?: string | null;
     compaction_id?: string | null;
     summary_preview?: string | null;
     summary_full?: string | null;

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

@@ -53,6 +53,8 @@ export interface SendOptions {
         deprecate_entry_ids: string[];
     };
     replayDecision?: "keep_replay" | "continue_replay";
+    /** 用户 @ 的知识库 id：后端先用原话在这些库里预检索，本轮 kb_search 也默认限定在这些库。 */
+    kbIds?: number[];
 }
 export declare function sessionStatusFromChatEnd(status: string | undefined): SessionStatus;
 /**

package/dist/session/state.d.ts

@@ -1,10 +1,12 @@
 import type { ChatMessage, CompactionInfo, MessageContent } from "../schemas/message";
 import type { ContentBlock, PatchEnvelope, TurnProjection } from "../schemas/projection";
 import type { ReplaySpeed, ReplayState, SessionStatus } from "../schemas/session";
-/** 一次 AskUserQuestion 的用户作答（选项选择 + 自定义输入）。 */
+/** 一次 AskUserQuestion 的用户作答（选项选择 + 自定义输入 + 可选补充）。 */
 export interface AskUserAnswerData {
     selections: Record<number, number[]>;
     custom: Record<number, string>;
+    /** 选完选项后的自由补充，空着就是没有。 */
+    note?: string;
 }
 export interface AgentLoopInfo {
     toolCallId: string;
@@ -55,6 +57,7 @@ export interface ReplaySnapshot {
 export declare function toReplaySnapshot(raw: ReplayState | null | undefined): ReplaySnapshot | null;
 export declare function createInitialSessionState(sessionId: string): SessionState;
 export declare function extractModeFromBlocks(blocks: ContentBlock[]): "planning" | "executing" | null;
+export declare function reconcileOptimisticUserTurns(currentTurns: TurnProjection[], incomingTurns: TurnProjection[]): TurnProjection[];
 /**
  * 用一份新的 turn 列表重建会话状态。
  * addErrorMessage 注入的 role==="error" 消息不在 turns 里，默认会被物化过程抹掉；

package/dist/shared/projection/builder.d.ts

@@ -37,6 +37,7 @@ export declare class ClientProjectionBuilder {
     seedSequence(maxSeq: number): void;
     _seedTurns(turns: TurnProjection[]): void;
     private onMemoryInject;
+    private onContextEntry;
     private onLoopTurn;
     private onModeChange;
     private onPlanStatusUpdate;
@@ -49,6 +50,7 @@ export declare class ClientProjectionBuilder {
     private onPostChatFollowup;
     private onDelta;
     private onToolCallCreated;
+    private onToolCallArgumentsDelta;
     private onResponseDone;
     private onToolResultDone;
     private onToolResultDelta;

package/dist/shared/projection/context.d.ts

@@ -0,0 +1,3 @@
+import type { TurnProjection } from "../../schemas/projection";
+/** Build one Context turn from the canonical entry used by live and history paths. */
+export declare function buildContextTurn(entry: Record<string, unknown>, sequence: number): TurnProjection | null;

package/dist/shared/projection/history.d.ts

@@ -4,6 +4,7 @@ export interface RawHistoryEntry {
     kind?: string;
     loop_name?: string;
     message?: Record<string, unknown>;
+    source?: Record<string, unknown>;
     data?: Record<string, unknown>;
     timestamp?: string;
     [key: string]: unknown;

package/dist/shared/projection/index.d.ts

@@ -1,3 +1,4 @@
 export { acceptedPostChatFollowupCompletesLatestRun, ClientProjectionBuilder, type RawEvent, type ProjectionUpdate, } from "./builder";
 export { type TurnState, createTurnState, snapshot, PAUSE_TOOL_NAMES } from "./state";
 export { projectHistory, type RawHistoryEntry } from "./history";
+export { buildContextTurn } from "./context";

package/dist/types/socket-events.d.ts

@@ -32,6 +32,7 @@ export declare namespace ChatSendPayloadSchema {
         [k: string]: unknown;
     } | null);
     type CompactionRatio = (number | null);
+    type KbIds = (number[] | null);
     interface ChatSendPayload {
         session_id: SessionId;
         message: Message;
@@ -48,6 +49,7 @@ export declare namespace ChatSendPayloadSchema {
         runtime_env?: RuntimeEnv;
         app_context?: AppContext;
         compaction_ratio?: CompactionRatio;
+        kb_ids?: KbIds;
         [k: string]: unknown;
     }
     interface Message {
@@ -183,6 +185,14 @@ export declare namespace ChatEndPayloadSchema {
     }
 }
 export type ChatEndPayload = ChatEndPayloadSchema.ChatEndPayload;
+export declare namespace SessionCreatedPayloadSchema {
+    type SessionId = string;
+    interface SessionCreatedPayload {
+        session_id: SessionId;
+        [k: string]: unknown;
+    }
+}
+export type SessionCreatedPayload = SessionCreatedPayloadSchema.SessionCreatedPayload;
 export declare namespace SessionUpdatedPayloadSchema {
     type SessionId = string;
     type Model = (string | null);
@@ -405,6 +415,7 @@ export interface ServerToClientEvents {
     "chat:start": (payload: ChatStartPayload) => void;
     "chat:end": (payload: ChatEndPayload) => void;
     "chat:append:ack": (payload: unknown) => void;
+    "session:created": (payload: SessionCreatedPayload) => void;
     "session:updated": (payload: SessionUpdatedPayload) => void;
     "workspace:files_changed": (payload: WorkspaceFilesChangedPayload) => void;
     "system:error": (payload: SystemErrorPayload) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blade-hq/agent-client",
-  "version": "2610.0.0-beta.2",
+  "version": "2610.0.0-beta.21",
   "description": "Blade Agent 框架无关客户端：会话实时状态机、REST 通道、弹窗登录、页面协作。浏览器与 Node.js 通用。",
   "repository": {
     "type": "git",

package/public-api.md

@@ -3,7 +3,7 @@
 > 本文件由 `scripts/public-api-report.mjs` 生成，请勿手改。
 > 公共面变更时重新生成本报告，并同步更新 README 对应章节——CI 会校验两者。
 
-共 136 个公开声明。
+共 150 个公开声明。
 
 ## `acceptedPostChatFollowupCompletesLatestRun` (function)
 
@@ -133,6 +133,7 @@ tool_name: string | null | undefined
 
 ```ts
 custom: Record<number, string>
+note: string | undefined
 selections: Record<number, number[]>
 ```
 
@@ -263,6 +264,7 @@ buildMessageContent: (text: string, attachments: Array<{ kind: "file"; name: str
 blocks: ContentBlock[] | undefined
 compaction: CompactionInfo | undefined
 content: MessageContent
+context: ContextProjectionData | undefined
 duration_ms: number | undefined
 entry_id: string | undefined
 kind: string | undefined
@@ -270,6 +272,7 @@ loop_name: string | undefined
 memory_refs: MemoryRefInfo[] | undefined
 parent_id: string | null | undefined
 reasoning: string | undefined
+render_id: string | undefined
 role: "error" | "user" | "assistant" | "tool"
 status: "streaming" | "completed" | "paused" | "failed" | "interrupted" | undefined
 timestamp: string | undefined
@@ -345,6 +348,61 @@ type: "text" | "thinking" | "tool_use" | "tool_result" | "tool_ui" | "tool_bridg
 contentPreview: (content: MessageContent, maxLen?: number) => string
 ```
 
+## `ContextAction` (type)
+
+```ts
+export type ContextAction = "published" | "retained" | "removed"
+```
+
+## `ContextDisplayState` (interface)
+
+```ts
+detail: string
+isRemoved: boolean
+summary: string
+title: string
+```
+
+## `contextProjectionData` (function)
+
+```ts
+contextProjectionData: (fields: ContextProjectionFields) => ContextProjectionData | null
+```
+
+## `ContextProjectionData` (interface)
+
+```ts
+context_action: ContextAction
+context_key: string
+context_kind: string
+context_name: string
+context_order: number
+context_revision: string
+display_summary: string | null | undefined
+display_title: string | null | undefined
+sources: ContextSourceInfo[]
+```
+
+## `ContextProjectionFields` (interface)
+
+```ts
+context_action: ContextAction | null | undefined
+context_key: string | null | undefined
+context_kind: string | null | undefined
+context_name: string | null | undefined
+context_order: number | null | undefined
+context_revision: string | null | undefined
+display_summary: string | null | undefined
+display_title: string | null | undefined
+sources: ContextSourceInfo[] | null | undefined
+```
+
+## `ContextSourceInfo` (type)
+
+```ts
+export type ContextSourceInfo = Record<string, unknown>
+```
+
 ## `createInitialSessionState` (function)
 
 ```ts
@@ -409,6 +467,12 @@ allowedOrigins: string[]
 iframe: HTMLIFrameElement | undefined
 ```
 
+## `EMPTY_PLATFORM_ENDPOINTS` (const)
+
+```ts
+EMPTY_PLATFORM_ENDPOINTS: PlatformEndpoints
+```
+
 ## `ExchangeCodeParams` (interface)
 
 ```ts
@@ -465,6 +529,12 @@ label: string
 target: string
 ```
 
+## `getContextDisplayState` (function)
+
+```ts
+getContextDisplayState: (context: ContextProjectionData) => ContextDisplayState
+```
+
 ## `getFileParts` (function)
 
 ```ts
@@ -601,6 +671,20 @@ export enum LayoutType {
 }
 ```
 
+## `loadPlatformEndpoints` (function)
+
+```ts
+loadPlatformEndpoints: (options?: LoadPlatformEndpointsOptions) => Promise<PlatformEndpoints>
+```
+
+## `LoadPlatformEndpointsOptions` (interface)
+
+```ts
+baseUrl: string | undefined
+fetchImpl: { (input: RequestInfo | URL, init?: RequestInit): Promise<Response>; (input: string | URL | Request, init?: RequestInit): Promise<Response>; } | undefined
+timeoutMs: number | undefined
+```
+
 ## `LoginOptions` (interface)
 
 ```ts
@@ -713,6 +797,18 @@ sequence: number
 turn_id: string
 ```
 
+## `PlatformEndpoints` (interface)
+
+```ts
+services: Partial<Record<"os" | "hub" | "agent" | "oauth" | "llmGateway" | "gitea" | "tile", string>>
+```
+
+## `PlatformServiceName` (type)
+
+```ts
+export type PlatformServiceName = (typeof PLATFORM_SERVICE_NAMES)[number]
+```
+
 ## `PostChatFollowup` (interface)
 
 ```ts
@@ -785,6 +881,12 @@ payload: Record<string, unknown>
 type: string
 ```
 
+## `reconcileOptimisticUserTurns` (function)
+
+```ts
+reconcileOptimisticUserTurns: (currentTurns: TurnProjection[], incomingTurns: TurnProjection[]) => TurnProjection[]
+```
+
 ## `ReplayPreview` (interface)
 
 ```ts
@@ -819,6 +921,12 @@ speed: ReplaySpeed | undefined
 status: "replay" | "autonomous" | undefined
 ```
 
+## `resolveServiceUrl` (function)
+
+```ts
+resolveServiceUrl: (endpoints: PlatformEndpoints, name: PlatformServiceName, path?: string) => string | null
+```
+
 ## `ResultFeedback` (interface)
 
 ```ts
@@ -890,6 +998,7 @@ SDK_VERSION: string
 
 ```ts
 askUserAnswer: Record<string, unknown> | undefined
+kbIds: number[] | undefined
 mode: string | undefined
 model: string | undefined
 replayDecision: "keep_replay" | "continue_replay" | undefined
@@ -1328,13 +1437,22 @@ archived_count: number | null | undefined
 archived_files: ArchivedFileInfo[] | null | undefined
 archived_tool_calls: ArchivedToolCallInfo[] | null | undefined
 blocks: ContentBlock[]
+client_render_id: string | null | undefined
 compaction_id: string | null | undefined
+context_action: ContextAction | null | undefined
+context_key: string | null | undefined
+context_kind: string | null | undefined
+context_name: string | null | undefined
+context_order: number | null | undefined
+context_revision: string | null | undefined
 context_window: number | undefined
+display_summary: string | null | undefined
+display_title: string | null | undefined
 duration_ms: number | undefined
 failure_reason: string | null | undefined
 fallback_applied: boolean | null | undefined
 id: string
-kind: "message" | "compaction" | undefined
+kind: "message" | "context" | "compaction" | undefined
 loop_id: string
 memory_refs: MemoryRef[] | null | undefined
 model: string | null | undefined
@@ -1343,6 +1461,7 @@ post_chat_followup: PostChatFollowup | null | undefined
 role: "user" | "assistant" | "system"
 saved_ratio: number | null | undefined
 sequence: number
+sources: ContextSourceInfo[] | null | undefined
 started_at: string | null | undefined
 status: "streaming" | "completed" | "paused" | "failed" | "interrupted"
 summary_full: string | null | undefined