@blade-hq/agent-client 1.1.1

package/dist/schemas/session.d.ts

@@ -0,0 +1,126 @@
+import type { Solution } from "./solution";
+export declare const SessionStatus: import("arktype/internal/variants/string.ts").StringType<"completed" | "created" | "failed" | "interrupted" | "running" | "waiting_for_input", {}>;
+export type SessionStatus = typeof SessionStatus.infer;
+export type TemplateId = "default" | "skill_editor" | "ship_attack";
+export type SkillEditorTemplateId = "skill_editor";
+export type ModeId = "planning" | "executing";
+export interface ReplayState {
+    source_session_id?: string;
+    status?: "replay" | "autonomous";
+    speed?: 1 | 2 | 5;
+    next_source_entry_id?: string | null;
+    ended_at?: string | null;
+    autonomous_reason?: string | null;
+}
+export interface SessionPortMapping {
+    container_port: number;
+    host_port: number;
+}
+/**
+ * 列表搜索时单条会话的命中信息。
+ * - field='title'：关键词出现在 intent 里，snippet 为 null（标题本身就在 UI 上）
+ * - field='content'：关键词出现在历史消息里，snippet 含截窗预览与角色
+ */
+export interface SessionSearchMatch {
+    field: "title" | "content";
+    snippet: {
+        role: string;
+        text: string;
+    } | null;
+}
+export declare const SessionInfo: import("arktype/internal/variants/object.ts").ObjectType<{
+    id: string;
+    intent: string;
+    status: "completed" | "created" | "failed" | "interrupted" | "running" | "waiting_for_input";
+    created_at: string;
+    updated_at: string;
+    shared?: boolean | undefined;
+    memory_enabled?: boolean | undefined;
+    is_persistent?: boolean | undefined;
+    is_headless?: boolean | undefined;
+    viewer_role?: "owner" | "viewer" | undefined;
+    template_id?: string | null | undefined;
+    model?: string | null | undefined;
+    enable_thinking?: boolean | null | undefined;
+    solution_id?: string | null | undefined;
+    biz_role_id?: string | null | undefined;
+    solution?: unknown;
+    plan_summary?: string | null | undefined;
+    primary_skill_id?: string | null | undefined;
+    bound_skill_id?: string | null | undefined;
+    replay_state?: unknown;
+    is_pinned?: boolean | undefined;
+    pinned_at?: string | null | undefined;
+    is_example?: boolean | undefined;
+    ports?: unknown;
+    disable_tools?: string[] | undefined;
+    runtime_type?: string | null | undefined;
+    daemon_id?: string | null | undefined;
+    match?: unknown;
+}, {}>;
+export type SessionInfo = Omit<typeof SessionInfo.infer, "template_id" | "solution" | "ports" | "match"> & {
+    shared?: boolean;
+    memory_enabled?: boolean;
+    is_persistent?: boolean;
+    is_headless?: boolean;
+    viewer_role?: "owner" | "viewer";
+    template_id?: TemplateId | null;
+    model?: string | null;
+    enable_thinking?: boolean | null;
+    solution_id?: string | null;
+    biz_role_id?: string | null;
+    solution?: Solution | null;
+    primary_skill_id?: string | null;
+    bound_skill_id?: string | null;
+    replay_state?: ReplayState | null;
+    is_pinned?: boolean;
+    pinned_at?: string | null;
+    is_example?: boolean;
+    ports?: SessionPortMapping[];
+    disable_tools?: string[];
+    runtime_type?: "sandbox" | "daemon" | string | null;
+    daemon_id?: string | null;
+    /** 仅在带 q 搜索的列表响应中出现；普通列表里此字段缺省。 */
+    match?: SessionSearchMatch | null;
+};
+/**
+ * 主 skill 配置快照（v2）。创建 session 时从 SKILL.md frontmatter 抽出并
+ * 固化到 session_root/.blade/primary-skill.json；ship-attack 页面骨架的唯
+ * 一数据源。
+ */
+export interface PrimarySkillStepSpec {
+    n: number;
+    label: string;
+}
+export interface PrimarySkillStageSpec {
+    id: string;
+    name: string;
+    steps: PrimarySkillStepSpec[];
+}
+export interface PrimarySkillParallelMode {
+    id: string;
+    name: string;
+    prompt_hint: string;
+}
+export interface PrimarySkillSnapshot {
+    version: number;
+    skill_id: string;
+    title: string;
+    description: string;
+    stages: PrimarySkillStageSpec[];
+    parallel_modes: PrimarySkillParallelMode[];
+    captured_at: string;
+}
+/**
+ * 单 session detail（GET /api/sessions/:id）。列表接口返回 SessionInfo，
+ * detail 在此基础上附加 primary_skill_snapshot。
+ */
+export interface SessionDetail extends SessionInfo {
+    primary_skill_snapshot?: PrimarySkillSnapshot | null;
+    preview_url?: string | null;
+    /**
+     * 会话级环境变量（owner-only）。后端仅在 GET detail 和 PUT /env 响应中返回，
+     * 列表/搜索响应不带此字段。调用 setSessionEnv 后可类型安全地读回。
+     */
+    env?: Record<string, string>;
+}

package/dist/schemas/solution.d.ts

@@ -0,0 +1,101 @@
+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"
+}
+export interface Solution {
+    id: string;
+    name: string;
+    version: string;
+    description?: string | null;
+    source?: "builtin" | "personal" | string | null;
+    layout_type: LayoutType | string;
+    initial_mode?: "planning" | "executing" | string | null;
+    initial_message?: string | null;
+    preview?: {
+        url: string;
+        title?: string | null;
+    } | null;
+    layout?: {
+        available?: boolean;
+        source_dir?: string;
+        entry?: string;
+        export?: string;
+    } | null;
+    roles?: BizRole[] | null;
+    data?: Record<string, unknown> | null;
+    ui_config?: SolutionAppUiConfig | null;
+}
+export interface SolutionAppUiConfig {
+    branding: {
+        name: string;
+        subtitle?: string;
+        icon_text: string;
+        icon_gradient?: string;
+    };
+    list: {
+        title: string;
+        create_button: string;
+        card?: {
+            subtitle?: string;
+            stats?: Array<{
+                label: string;
+                value: string;
+                color?: string;
+            }>;
+        };
+    };
+    create: {
+        title: string;
+        description?: string;
+        submit_button: string;
+        sections: Array<{
+            id: string;
+            title: string;
+            description?: string;
+            fields: Array<SolutionAppField>;
+        }>;
+    };
+}
+export type SolutionAppField = {
+    id: string;
+    kind: "textarea";
+    label: string;
+    placeholder?: string;
+} | {
+    id: string;
+    kind: "file-upload";
+    accept?: string[];
+    categories?: Array<{
+        label: string;
+        description: string;
+        color: string;
+    }>;
+};
+export interface SolutionAppState {
+    pipeline: Array<{
+        id: string;
+        label: string;
+        status: "done" | "active" | "pending" | "error";
+    }>;
+    meta: Record<string, {
+        label: string;
+        value: string;
+        color?: string;
+    }>;
+}
+export interface BizRole {
+    id: string;
+    name: string;
+    description?: string | null;
+    preview?: {
+        url: string;
+        title?: string | null;
+    } | null;
+}

package/dist/schemas/task.d.ts

@@ -0,0 +1,12 @@
+export declare const TaskStatus: import("arktype/internal/variants/string.ts").StringType<"done" | "failed" | "in_progress" | "pending" | "skipped", {}>;
+export type TaskStatus = typeof TaskStatus.infer;
+export declare const Task: import("arktype/internal/variants/object.ts").ObjectType<{
+    id: string;
+    goal: string;
+    skills: string[];
+    depends_on: string[];
+    status: "done" | "failed" | "in_progress" | "pending" | "skipped";
+    result_summary: string;
+    number: string;
+}, {}>;
+export type Task = typeof Task.infer;

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

@@ -0,0 +1,179 @@
+import { type RawEvent } from "../shared/projection";
+import type { MessageContent } from "../schemas/message";
+import type { PatchEnvelope, TurnProjection } from "../schemas/projection";
+import type { SessionStatus } from "../schemas/session";
+import { type CommandHandler } from "../commands/registry";
+import { type AgentSessionEvents } from "./events";
+import { type ConnectionStatus, type SessionState } from "./state";
+/** SessionHub 注入给 AgentSession 的运行时依赖（socket 收发 + REST 补数）。 */
+export interface SessionRuntime {
+    emitEvent(event: string, data: unknown): void;
+    emitWithAck(event: string, data: unknown, timeoutMs: number): Promise<Record<string, unknown> | undefined>;
+    ensureConnected(): void;
+    fetchTurns(sessionId: string): Promise<TurnProjection[]>;
+    onDispose(session: AgentSession): void;
+}
+export interface SendOptions {
+    /** planning / executing 模式。 */
+    mode?: string;
+    /** AskUserQuestion 的作答（tool_call_id + 选项）。 */
+    askUserAnswer?: Record<string, unknown>;
+    /** 本次运行的模型覆盖。 */
+    model?: string;
+    /** 本次运行是否强制开/关思考。 */
+    thinkingOverride?: boolean;
+    whatif?: {
+        from_step: number;
+        quotes: Array<Record<string, unknown>>;
+        deprecate_entry_ids: string[];
+    };
+    replayDecision?: "keep_replay" | "continue_replay";
+}
+export declare function sessionStatusFromChatEnd(status: string | undefined): SessionStatus;
+/**
+ * 一个会话的实时状态机：封装 Socket.IO 订阅、历史 + 流式合流、断线补数，
+ * 对外只有三样东西——状态快照（getState/subscribe）、动作（send/stop/…）、
+ * 语义事件（on/onCommand）。
+ *
+ * 状态完全归属实例：同一页面创建多个 AgentSession 互不干扰。
+ */
+export declare class AgentSession {
+    readonly sessionId: string;
+    private state;
+    private readonly listeners;
+    private readonly emitter;
+    private readonly commands;
+    private readonly runtime;
+    private readonly projectionBuilder;
+    private readonly pendingTurnPatches;
+    private patchFlushHandle;
+    private patchFlushCancel;
+    private joined;
+    private joinPending;
+    private pendingReplayMessage;
+    private pendingReplayMode;
+    private recentChatEndAt;
+    private disposed;
+    private readonly deliveredCommandKeys;
+    private readonly deliveredToolPreviews;
+    private readonly oomNotifiedKeys;
+    private readonly seenToolCallIds;
+    private readonly finishedToolCallIds;
+    private readonly emittedMessageTurnIds;
+    constructor(sessionId: string, runtime: SessionRuntime, connection: ConnectionStatus);
+    /** 从一份静态 turn 快照构造只展示历史的会话（例如公开分享页）。 */
+    static fromTurns(sessionId: string, turns: TurnProjection[]): AgentSession;
+    /** 返回当前会话快照。引用稳定：状态未变化时返回同一对象。 */
+    getState(): SessionState;
+    /** 订阅状态变化。返回取消订阅函数。 */
+    subscribe(listener: () => void): () => void;
+    private setState;
+    private update;
+    /** 监听语义事件（底层逃生舱，见 events.ts）。返回取消函数。 */
+    on<K extends keyof AgentSessionEvents>(name: K, handler: (event: AgentSessionEvents[K]) => void): () => void;
+    off<K extends keyof AgentSessionEvents>(name: K, handler: (event: AgentSessionEvents[K]) => void): void;
+    /**
+     * 监听智能体下发给宿主页面的指令。
+     *
+     * action 是技能作者在工具返回值 `_meta.bridge` 里写的契约字符串（如
+     * "map.highlight"），由你和技能作者约定；注册前到达的指令会被缓冲补投。
+     */
+    onCommand(action: string, handler: CommandHandler): () => void;
+    /** 发送一条消息。字符串或多模态内容均可。 */
+    send(content: MessageContent, options?: SendOptions): Promise<void>;
+    /** 智能体运行期间追加补充说明（不打断当前回复）。 */
+    append(text: string): void;
+    /** 停止当前回复。 */
+    stop(): Promise<Record<string, unknown>>;
+    /** 手动触发上下文压缩。 */
+    compact(): Promise<Record<string, unknown>>;
+    /**
+     * 把一段业务数据作为附件放进聊天输入框（比如地图上选中的点位）。
+     * 附件随下一条消息一起发给智能体。需要 ChatView / useChat 渲染层配合展示；
+     * 无 UI 场景可直接用 send()。
+     */
+    attach(label: string, data: unknown): void;
+    /** 往聊天输入框追加一段文字（不发送）。 */
+    insertText(text: string): void;
+    /** 释放订阅与监听器。之后该实例不再接收任何事件。 */
+    dispose(): void;
+    get isDisposed(): boolean;
+    /** @internal 连接状态变化（同 client 下所有会话共享一条连接）。 */
+    _setConnection(connection: ConnectionStatus): void;
+    /** @internal socket 重连后由 Hub 调用：重新加入房间并补数。 */
+    _rejoinAfterReconnect(): Promise<void>;
+    /** @internal 首次连接：加载历史 + 加入房间。 */
+    _bootstrap(): Promise<void>;
+    /** @internal */
+    _handleTurnStart(turn: TurnProjection): void;
+    /** @internal */
+    _handleTurnPatch(patch: PatchEnvelope): void;
+    /** @internal */
+    _handleTurnEnd(turn: TurnProjection): void;
+    /** @internal 历史回放通道（event_format: raw）。 */
+    _handleTurnEvents(events: RawEvent[]): void;
+    /** @internal */
+    _handleChatStart(): void;
+    /** @internal */
+    _handleChatEnd(status: string): void;
+    /** @internal */
+    _handleSystemError(message: string): void;
+    /** @internal */
+    _handleTaskUpdated(tasks: unknown[]): void;
+    /** @internal */
+    _handleWorkspaceFilesChanged(filePath?: string): void;
+    /** @internal */
+    _handleSessionUpdated(data: {
+        intent?: string;
+        status?: SessionStatus;
+        model?: string | null;
+        bound_skill_id?: string | null;
+        replay_state?: Record<string, unknown> | null;
+    }): void;
+    /** @internal */
+    _handleRewind(checkpointId: string): void;
+    /** @internal */
+    _handleReplayMismatch(data: {
+        actual_message?: string;
+        expected_message?: string;
+    }): void;
+    /** @internal */
+    _handleSystemNotification(loopId: string, notification: Record<string, unknown>): void;
+    /** @internal */
+    _handleBackgroundTask(task: {
+        id: string;
+        command: string;
+        description?: string;
+        status: "running" | "done" | "failed";
+        exitCode?: number | null;
+        elapsedSeconds: number;
+        output?: string;
+    }): void;
+    /** @internal */
+    _handleArtifact(event: AgentSessionEvents["artifact"]): void;
+    /** @internal 加入房间的应答里带 is_running，据此校准流式状态。 */
+    _applyRunningState(isRunning: boolean): void;
+    private markRunningIfIdle;
+    private finishStreaming;
+    private applyTurn;
+    private schedulePatchFlush;
+    private cancelPatchFlush;
+    private flushPatches;
+    /** turn 数据落地后统一派生语义事件（指令 / 工具调用 / 消息 / 模式 / 预览 / OOM）。 */
+    private emitTurnDerivedEvents;
+    private dispatchCommand;
+    private notifySandboxOom;
+    private syncTurnsFromHistory;
+    /**
+     * 把历史里的指令补投给宿主页面。
+     *
+     * 重开会话、断线补数时，地图高亮这类"页面当前状态"必须能恢复——
+     * 否则刷新一次页面，之前智能体让页面做的事就全丢了。
+     * 只回放指令：toolCall / message 这些事件如果按历史全量重放，
+     * 监听器会在挂载瞬间收到几百条陈年事件。
+     * dispatch 内部按 deliveredCommandKeys 去重，重复调用安全。
+     */
+    private replayCommandsFromTurns;
+    private ensureJoined;
+    private ensureIdleBeforeSend;
+}

package/dist/session/events.d.ts

@@ -0,0 +1,143 @@
+import type { ChatMessage, ToolCallInfo } from "../schemas/message";
+import type { TurnProjection } from "../schemas/projection";
+import type { SessionStatus } from "../schemas/session";
+/**
+ * AgentSession 的语义事件表。
+ *
+ * 这是"底层逃生舱"（L1）：React 使用者优先用 useChat() 的响应式状态（L2）
+ * 或 <ChatView onToolCall/commands> 的声明式入口（L3），一般不需要直接监听。
+ * Vue / 无框架集成者用 session.on(...) 精确订阅。
+ */
+export interface AgentSessionEvents {
+    /** 一条消息物化完成（turn 离开 streaming 状态）。 */
+    message: {
+        message: ChatMessage;
+        turn: TurnProjection;
+    };
+    /** 智能体发起了一次工具调用（首次出现）。 */
+    toolCall: {
+        toolCall: ToolCallInfo;
+        turn: TurnProjection;
+    };
+    /** 一次工具调用出结果（done / error / cancelled）。 */
+    toolResult: {
+        toolCall: ToolCallInfo;
+        turn: TurnProjection;
+    };
+    /** 一轮回复结束。status: completed / paused / interrupted / failed。 */
+    chatEnd: {
+        status: string;
+    };
+    /** 运行错误（system:error、发送失败等）。 */
+    error: {
+        message: string;
+    };
+    /** planning / executing 模式切换。 */
+    modeChange: {
+        mode: "planning" | "executing";
+    };
+    /**
+     * 智能体给宿主页面下发指令。
+     *
+     * action 的来源：技能作者在工具实现的返回值 JSON 里写 `_meta.bridge:
+     * { action, payload }`，后端剥离后经事件流送达前端。action 是技能作者与
+     * 宿主页面开发者约定的业务契约字符串（如 "map.highlight"），LLM 不参与、
+     * SDK 不做枚举。一般用 session.onCommand(action, fn) 消费，而不是监听本事件。
+     */
+    command: {
+        action: string;
+        payload: unknown;
+        toolCallId?: string;
+    };
+    /** 系统通知（技能阶段提示、后台任务启动等）。 */
+    notification: {
+        type: string;
+        title: string;
+        detail?: string;
+        status: "info" | "running" | "done" | "error";
+        loopId?: string;
+        metadata?: Record<string, unknown>;
+    };
+    /** 工作区文件发生变化（写文件、重命名等）。 */
+    workspaceChanged: {
+        filePath?: string;
+    };
+    /** 智能体产出了文件成果（artifact:created / artifact:updated）。 */
+    artifact: {
+        filePath: string;
+        contentType: string;
+        title: string;
+        content: string;
+        oldString?: string;
+        newString?: string;
+        kind: "created" | "updated";
+    };
+    /** 工具返回值带 _meta.ui 的可视化预览（resource HTML / URI）。 */
+    toolPreview: {
+        toolCallId: string;
+        type: "resource-html" | "resource-uri";
+        content: string;
+        title: string;
+    };
+    /** 任务清单（TaskCreate 等）更新。 */
+    taskListUpdated: {
+        tasks: unknown[];
+    };
+    /** 沙盒后台命令状态更新。 */
+    backgroundTask: {
+        id: string;
+        command: string;
+        description?: string;
+        status: "running" | "done" | "failed";
+        exitCode?: number | null;
+        elapsedSeconds: number;
+        output?: string;
+    };
+    /** 会话被回溯到某个检查点。 */
+    rewind: {
+        checkpointId: string;
+    };
+    /** 会话属性（名称、状态、绑定技能等）被服务端更新。 */
+    sessionUpdated: {
+        intent?: string;
+        status?: SessionStatus;
+        model?: string | null;
+        boundSkillId?: string | null;
+        replayState?: Record<string, unknown> | null;
+    };
+    /** 回放输入不匹配，需要决定保持回放还是转自主模式。 */
+    replayMismatch: {
+        actualMessage?: string;
+        expectedMessage?: string;
+        respond: (decision: "keep_replay" | "continue_replay") => void;
+    };
+    /** 沙盒内存超限自动重启。 */
+    sandboxOom: {
+        toolCallId: string;
+    };
+    /** session.attach() 被调用，渲染层（ChatView/useChat）应把它显示为输入框附件。 */
+    attachRequested: {
+        label: string;
+        content: string;
+    };
+    /** session.insertText() 被调用，渲染层应把文字追加到输入框。 */
+    insertTextRequested: {
+        text: string;
+    };
+}
+export type AgentSessionEventName = keyof AgentSessionEvents;
+type Handler<E> = (event: E) => void;
+export declare class Emitter<Events> {
+    private handlers;
+    on<K extends keyof Events>(name: K, handler: Handler<Events[K]>): () => void;
+    off<K extends keyof Events>(name: K, handler: Handler<Events[K]>): void;
+    emit<K extends keyof Events>(name: K, event: Events[K]): void;
+    /**
+     * 只把事件交给最先注册的处理器。用于必须由单一交互入口作答的事件，
+     * 避免多个 UI 同时弹窗并提交相互冲突的决定。
+     */
+    emitFirst<K extends keyof Events>(name: K, event: Events[K]): boolean;
+    listenerCount(name: keyof Events): number;
+    clear(): void;
+}
+export {};

package/dist/session/hub.d.ts

@@ -0,0 +1,44 @@
+import type { BladeClient } from "../blade-client";
+import { AgentSession } from "./agent-session";
+import type { ConnectionStatus } from "./state";
+/**
+ * 每个 BladeClient 一个：管理一条 Socket.IO 连接，按 session_id 把事件
+ * 路由给各 AgentSession 实例。多会话共享连接、状态互不干扰。
+ */
+export declare class SessionHub {
+    private readonly client;
+    private readonly sessions;
+    private readonly bootstrapPending;
+    private connection;
+    private readonly connectionListeners;
+    private bound;
+    private hasConnected;
+    constructor(client: BladeClient);
+    /** 当前 Socket.IO 连接状态。 */
+    getConnection(): ConnectionStatus;
+    /** 订阅连接状态变化。 */
+    onConnectionChange(listener: (status: ConnectionStatus) => void): () => void;
+    /** 取得（或复用）一个会话的 AgentSession，并完成历史加载 + 房间订阅。 */
+    connect(sessionId: string): Promise<AgentSession>;
+    /** 已有实例则返回，不触发网络请求。 */
+    peek(sessionId: string): AgentSession | undefined;
+    /** 手动重连（例如登录态变化后）。 */
+    reconnect(): void;
+    /** 断开连接（不清理 session 实例）。 */
+    disconnect(): void;
+    /** 清理当前身份下缓存的全部会话，避免切换登录身份后复用旧快照。 */
+    disposeAll(): void;
+    /**
+     * @internal 底层 socket 被换掉时由 BladeClient 调用（如 setBaseUrl）。
+     * 事件监听器绑在旧 socket 实例上，换新实例后必须重绑，否则所有
+     * turn:* / chat:* 事件都会静默丢弃。
+     */
+    _handleSocketReplaced(): void;
+    private runtimeFor;
+    private ensureConnected;
+    private setConnection;
+    /** 事件带 session_id 时精确路由；缺省时按当前唯一活跃会话兜底。 */
+    private route;
+    private ensureBound;
+    private routeArtifact;
+}

package/dist/session/state.d.ts

@@ -0,0 +1,57 @@
+import type { ChatMessage, CompactionInfo, MessageContent } from "../schemas/message";
+import type { ContentBlock, PatchEnvelope, TurnProjection } from "../schemas/projection";
+import type { SessionStatus } from "../schemas/session";
+/** 一次 AskUserQuestion 的用户作答（选项选择 + 自定义输入）。 */
+export interface AskUserAnswerData {
+    selections: Record<number, number[]>;
+    custom: Record<number, string>;
+}
+export interface AgentLoopInfo {
+    toolCallId: string;
+    description: string;
+    status: "running" | "done" | "error" | "cancelled" | "awaiting_answer";
+}
+export interface ActiveCompactionState extends CompactionInfo {
+    turn_id: string;
+    status: "streaming" | "completed" | "paused" | "failed" | "interrupted";
+}
+export type ConnectionStatus = "connecting" | "connected" | "reconnecting" | "disconnected";
+/**
+ * 一个会话的完整快照。引用不可变：任何变更都会产生新对象，
+ * 满足 React `useSyncExternalStore` / Vue `shallowRef` 的订阅契约。
+ */
+export interface SessionState {
+    sessionId: string;
+    /** 服务端投影的原始 turn 列表（按 sequence 有序）。 */
+    turns: TurnProjection[];
+    /** 由 turns 物化出的聊天消息列表，UI 直接渲染。 */
+    messages: ChatMessage[];
+    /** 智能体是否正在流式回复。 */
+    isStreaming: boolean;
+    /** 会话状态（running / completed / failed / waiting_for_input / interrupted …）。 */
+    status: SessionStatus | null;
+    /** 当前模式（planning / executing），来自 mode_change 事件。 */
+    mode: "planning" | "executing" | null;
+    /** Socket.IO 连接状态（同一 client 下所有会话共享）。 */
+    connection: ConnectionStatus;
+    /** 最近一次运行错误消息（system:error 等）。 */
+    errorMessage: string | null;
+    askAnswers: Record<string, AskUserAnswerData>;
+    agentLoops: Record<string, AgentLoopInfo>;
+    activeCompaction: ActiveCompactionState | null;
+}
+export declare function createInitialSessionState(sessionId: string): SessionState;
+export declare function extractModeFromBlocks(blocks: ContentBlock[]): "planning" | "executing" | null;
+/**
+ * 用一份新的 turn 列表重建会话状态。
+ * addErrorMessage 注入的 role==="error" 消息不在 turns 里，默认会被物化过程抹掉；
+ * 这里沿用锚点策略：只保留锚定在"当前最后一个 turn"上的错误气泡，
+ * turn 推进（新消息 / rewind / 重连）时旧错误自动消失。
+ */
+export declare function withTurns(state: SessionState, turns: TurnProjection[]): SessionState;
+export declare function addUserMessage(state: SessionState, content: MessageContent): SessionState;
+export declare function upsertTurn(state: SessionState, turn: TurnProjection): SessionState;
+export declare function applyTurnPatch(state: SessionState, patch: PatchEnvelope): SessionState;
+export declare function addErrorMessage(state: SessionState, content: string): SessionState;
+export declare function markInterrupted(state: SessionState): SessionState;
+export declare function markFailed(state: SessionState): SessionState;