@yumiai/chat-widget 0.1.2 → 0.2.1

package/dist/index.d.cts

@@ -1,7 +1,18 @@
-import React from 'react';
+import * as React$1 from 'react';
+import React__default, { RefObject } from 'react';
+import { k as ProvenanceGraphSnapshot, a as ChatWidgetMessages, C as ChatWidgetLocale } from './GraphStatsLegend-D5bPeXB_.cjs';
+export { E as EdgeType, F as FetchGraphOptions, b as FilterBar, G as GraphBuilder, c as GraphEdge, d as GraphFilter, e as GraphSSEPayload, f as GraphStatsLegend, g as GraphToolbar, N as NodeDetailPanel, h as NodeType, P as ProvenanceGraph3D, i as ProvenanceGraphDrawerContent, j as ProvenanceGraphFetcher, l as ProvenanceNode, m as fetchProvenanceGraph, r as resolveMessages, u as useProvenanceGraph } from './GraphStatsLegend-D5bPeXB_.cjs';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+export { J as JsonRenderActionHandler, a as JsonRenderStandalone, b as JsonRenderStandaloneProps } from './JsonRenderStandalone-UsTcST4G.cjs';
 
-type MessageContentType = 'text' | 'think' | 'plan' | 'artifact' | 'json_schema' | 'html_schema' | 'json_schema_wait';
-type NotificationType = 'user_input' | 'node_notification' | 'start' | 'model_start' | 'model_result' | 'model_end' | 'agent_start' | 'agent_result' | 'agent_end' | 'artifact_start' | 'artifact_result' | 'artifact_end' | 'plan_start' | 'plan_result' | 'plan_end' | 'mcp_generating' | 'mcp_start' | 'mcp_result' | 'mcp_end' | 'finish' | 'canceled' | 'error' | 'human_input_request' | 'human_input_received' | 'human_input_timeout' | 'human_input_completed' | 'session_title' | 'compression_started' | 'compression_completed' | 'node_summary';
+type MessageContentType = 'text' | 'think' | 'plan' | 'artifact' | 'json_schema' | 'html_schema' | 'json_schema_wait' | 'gen_ui_card' | 'gen_ui_page' | 'gen_ui_meta';
+type NotificationType = 'user_input' | 'node_notification' | 'start' | 'model_start' | 'model_result' | 'model_end' | 'agent_start' | 'agent_result' | 'agent_end' | 'artifact_start' | 'artifact_result' | 'artifact_end' | 'plan_start' | 'plan_result' | 'plan_end' | 'mcp_generating' | 'mcp_start' | 'mcp_result' | 'mcp_end' | 'finish' | 'canceled' | 'error' | 'human_input_request' | 'human_input_received' | 'human_input_timeout' | 'human_input_completed'
+/** [DEPRECATED 起 JETP-073] session 级 LLM 起名；仅在兼容期 dual-write 中复用，
+ *  新代码请改用 'client_title'。 */
+ | 'session_title'
+/** JETP-073：client（"办公室"）级 LLM 起名 notification。controller 派发为
+ *  ``ClientTitleEvent``；上游消费方按 ``client_id`` 增量更新本地 cache。 */
+ | 'client_title' | 'compression_started' | 'compression_completed' | 'node_summary';
 interface UiConfig {
     display_type: 'content' | 'command' | 'browser' | 'query' | 'path' | 'trigger' | 'thinking' | 'params';
     icon?: string;
@@ -28,6 +39,37 @@ interface SSEMessage {
     content_type: MessageContentType;
     content: string;
     timestamp?: string;
+    spec_id?: string;
+    render_mode?: 'card' | 'page';
+    /** JETP-045 Layer 1：客户端连接子空间标识；后端 Notification.client_id 透传下来。 */
+    client_id?: string;
+    /**
+     * JETP-045 Phase 2 P2-T03：与所属 LLM 物理流对齐的边界 ID。
+     * MODEL_START / 中间 chunk / MODEL_END 共享同一 stream_uuid。
+     * 前端 useMessageAggregator.messageKey 主分支按此聚合 → 彻底解决 Bug 1
+     * （撞键导致 think2 头部错合到 think1）。
+     * 旧后端不下发 → undefined → useMessageAggregator 走兜底分支保持向后兼容。
+     */
+    stream_uuid?: string;
+    /**
+     * JETP-045 Phase 2 P2-T08/T10：所属 turn 在 (interaction_id, callee_instance_id)
+     * 内的单调序号；与 db-writer ``MAX(turn_index)+1`` 同算法。
+     * 前端 ``turnCursorRef`` 用 ``${iid}::${callee}`` 为 key 推进；断线重连发
+     * subscribe 时按 (iid, callee, max_turn_index) 形式上报，服务端只补
+     * ``turn_index > max_turn_index`` 的 turn（AC-TURN-002/005）。
+     */
+    turn_index?: number;
+    /**
+     * JETP-045：被叫 agent 实例 ID。AC-TURN-003 多 callee 独立 cursor 必需。
+     * 旧后端可能直接把 ``agent_instance_id`` 当 callee 用 → adapter 透传。
+     */
+    callee_instance_id?: number;
+    /**
+     * JETP-045 Phase 6 — 触发该 notification 的源连接 ID（后端 Notification.connection_id_from）。
+     * 前端 ``useMessageAggregator`` 用 ``connection_id_from === my_connection_id`` 识别 echo。
+     * 旧后端不下发 → undefined → 不做 echo 抑制，回退到 Phase 1-5 行为 (AC-CONN-008)。
+     */
+    connection_id_from?: string;
 }
 interface PlanItem {
     text: string;
@@ -84,6 +126,9 @@ interface Artifact {
     id: string;
     name: string;
     type: string;
+    /** 后端资源 ID，与附件/工作区文件关联 */
+    resource_id?: string;
+    mime_type?: string;
     size?: string;
     content?: string;
     preview?: string;
@@ -105,7 +150,98 @@ interface HITLResponse {
     await_command_uuid: string;
     data: unknown;
     confirmed: boolean;
+    /** JETP-040: Optional attached files for multipart HITL upload */
+    files?: File[];
+    session_id?: number;
+    agent_instance_id?: number;
+    text?: string;
+    /**
+     * JETP-003 ADR-006 v1.1.2 / WS2.6 — V2 ``c_<22 base62>`` window/conversation
+     * identifier for the chat-widget instance that produced this response.
+     *
+     * Stage A grayscale (current): when omitted on A2UI payloads, jetagents
+     * /api/human-response increments ``hip_client_id_missing_total`` Counter
+     * + WARN log and falls back to session-wide routing.
+     *
+     * Stage B strict cutover (post-grayscale): A2UI payloads (data with
+     * ``__action`` + ``spec_id``) without client_id will be rejected.
+     *
+     * The chat-widget always knows its own client_id (from useClientIdAllocator
+     * → ``currentClientId``); GenUIProvider injects it into GenUIContext, and
+     * ActionBridge / handleHITLSubmit auto-fill this field when not set by
+     * the caller.
+     */
+    client_id?: string;
 }
+/**
+ * JETP-083 WS3.7.6 — pending HIL Entity projection returned by
+ * ``GET /api/genui/pending``.
+ *
+ * Shape mirrors `jetagents/main.py:get_genui_pending` 1:1; fields are
+ * derived from `HilEntity` + the principal-scoped projection helper.
+ *
+ * Phase 1 invariants:
+ * - The returned list contains *only* HILs whose `resolved_recipients`
+ *   include the connecting principal — backend ACL via the registry's
+ *   principal index. No client-side filter is needed (or sufficient).
+ * - `recipientsSummary.recipientCount` is intentionally a count, not a
+ *   list of co-recipients, to avoid leaking other users' identities.
+ *   Phase 2 multi-recipient delivery may extend this with masked
+ *   summaries.
+ * - `state` is always a non-terminal state (registry filters out
+ *   resolved/cancelled/expired before returning).
+ */
+interface PendingHIL {
+    hilId: string;
+    specId: string;
+    /** Note: backend stores as string even when the URL `session_id` is int. */
+    sessionId: string;
+    state: 'pending' | 'delivered' | 'in_progress' | 'partially_resolved';
+    schemaVersion: 'v1';
+    createdAt: string | null;
+    lastUpdatedAt: string | null;
+    origin: {
+        agentId: string | null;
+        /** Originating client_id; audit-only after WS3.7.4. */
+        clientId: string | null;
+        /** Compact origin principal — drops null fields. */
+        principal: {
+            principalKind?: string;
+            principalKey?: string;
+            realmId?: string;
+            authInstanceId?: string;
+        } | null;
+    };
+    recipientsSummary: {
+        delivery: 'first_wins' | 'all_must' | 'quorum' | 'broadcast_first_wins';
+        selectorKind: 'literal' | 'role' | 'group' | 'realm';
+        recipientCount: number;
+        /** Whether the connecting principal is a recipient (sanity flag). */
+        includeSelf: boolean;
+    };
+}
+/**
+ * Terminal lifecycle marker for a spec, emitted by the backend via the
+ * `gen_ui_meta` channel as either:
+ *
+ * - `{op:"replace", path:"/_meta/cancelled", value:{reason}}` — HIL on the
+ *   spec was cancelled (user, agent, or system-initiated; see WS3.7.5).
+ * - `{op:"replace", path:"/_meta/error", value:{error_code, payload}}`
+ *   or legacy flat `{error, payload}` — terminal error such as
+ *   `patch_rounds_exceeded` (ADR-012 D1).
+ *
+ * The aggregator surfaces this in `specLifecycleMap` keyed by spec_id; the
+ * host UI can disable the form, dim the card, or show a banner. Once a spec
+ * has a lifecycle entry, further patches for it should be visually muted.
+ */
+type SpecLifecycleEntry = {
+    state: 'cancelled';
+    reason: string;
+} | {
+    state: 'error';
+    errorCode: string;
+    payload?: Record<string, unknown>;
+};
 interface AggregatedMessage {
     id: string;
     agentInstanceId: number;
@@ -129,18 +265,39 @@ interface AggregatedMessage {
     artifact?: Artifact;
     artifacts?: Artifact[];
     hitlRequest?: HITLRequest;
+    specId?: string;
+    uiPatches?: string[];
+    renderMode?: 'card' | 'page';
+    /** JETP-045 Layer 1：客户端连接子空间标识。 */
+    clientId?: string;
+    /**
+     * JETP-045 Phase 6 — 触发该消息的源连接 ID；与 ``SSEMessage.connection_id_from`` 透传。
+     * 仅用于 UI 调试/数据回放；echo 的渲染策略由 ``isEcho`` 决定。
+     */
+    connectionIdFrom?: string;
+    /**
+     * JETP-045 Phase 6 (AC-CONN-006/007) — 该消息是否由"我这条连接"自己回环触发。
+     * - true：UI 应抑制 user_input 的重复渲染（已由 round.userMessage optimistic 显示）；
+     *         其余非 user_input 类型仍照常渲染，仅可作为视觉淡化提示。
+     * - false / undefined：来自其他 tab/连接 或旧后端无 ``connection_id_from`` ⇒ 视为远端。
+     */
+    isEcho?: boolean;
 }
 interface Round {
     interactionId: string;
     index: number;
     userMessage: string;
     timestamp: string;
+    /** 用户消息时间戳（毫秒），可选；缺省时可用 `timestamp` 解析 */
+    startedAt?: number;
     status: 'running' | 'completed' | 'error';
     plan?: TaskPlan;
     messages: AggregatedMessage[];
     topPosition?: number;
     /** 本轮次内已收到 agent_end 的 agent_instance_id 集合，与 notification_turns 的 agent start/stop 对齐，用于子 Agent 卡片「已完成」判断 */
     endedAgentInstanceIds?: Set<number>;
+    /** JETP-045 Layer 1：客户端连接子空间标识。 */
+    clientId?: string;
 }
 type ExecutionStatus = 'idle' | 'running' | 'compressing' | 'completed' | 'error';
 interface ChatWidgetConfig {
@@ -150,8 +307,33 @@ interface ChatWidgetConfig {
     typewriterSpeed?: number;
     autoScroll?: boolean;
     childAgentMaxHeight?: number;
-    theme?: 'light' | 'dark' | 'auto';
+    theme?: 'light' | 'dark' | 'midnight' | 'neumorphism' | 'auto';
     displayLevels?: number[];
+    /**
+     * Whether to reuse agent_instance_id from session history when restoring a session.
+     *
+     * - `true` (default): cache the historical agent_instance_id and send it with
+     *   new messages, ensuring the same agent executor handles follow-up requests.
+     *   Best for single-user continuation of an existing conversation.
+     *
+     * - `false`: do NOT cache the historical agent_instance_id; each new message
+     *   lets the backend create a fresh agent executor. This avoids InstanceTaskQueue
+     *   contention and is required for multi-user collaboration on a shared session.
+     */
+    reuseAgentInstance?: boolean;
+    transport?: 'ws' | 'sse';
+    /**
+     * 是否在 ChatWidget mount 时立即调用 ``adapter.createSession`` 预分配 session+workspace。
+     *
+     * - ``true``（默认）：保留原 SDK 行为，让首次 ``sendMessage`` 不必等会话创建。
+     *   适合"嵌入式单会话"场景（host 始终给确定 sessionId 或希望开局立即就绪）。
+     *
+     * - ``false``：不在 mount 时建会话；只有用户调用 ``api.sendMessage`` 或 host 显式
+     *   传入 sessionId 时才进入会话流程。适合"多会话侧栏 + 选择/新建"的 host
+     *   （如 Demo App、JetForge Console），避免每次刷新都在后端 page 列表里
+     *   留下空 session。
+     */
+    eagerSessionCreation?: boolean;
 }
 declare const DEFAULT_CONFIG: Required<ChatWidgetConfig>;
 interface ChatWidgetProps {
@@ -159,25 +341,304 @@ interface ChatWidgetProps {
     sessionId?: string | number;
     initialMessages?: Round[];
     config?: ChatWidgetConfig;
-    renderHeaderExtra?: (sessionId: string | number) => React.ReactNode;
-    renderFooter?: (api: ChatWidgetAPI | null) => React.ReactNode;
-    renderToolResult?: (displayType: string, data: ToolCallData) => React.ReactNode | null;
+    renderHeaderExtra?: (sessionId: string | number) => React__default.ReactNode;
+    renderFooter?: (api: ChatWidgetAPI | null) => React__default.ReactNode;
+    renderToolResult?: (displayType: string, data: ToolCallData) => React__default.ReactNode | null;
     locale?: 'zh-CN' | 'en-US';
+    messages?: Partial<ChatWidgetMessages>;
     onArtifactClick?: (artifact: Artifact) => void;
+    onSelectionAsk?: (reference: FileReference) => void;
+    onBeforeCopy?: (reference: FileReference) => void;
     onHITLSubmit?: (response: HITLResponse) => Promise<void>;
+    onConnectionChange?: (connected: boolean) => void;
+    onRoundChange?: (rounds: Round[]) => void;
+    onMessageAppended?: (message: AggregatedMessage) => void;
+    onRoundStart?: (interactionId: string, userMessage: string) => void;
+    onRoundEnd?: (interactionId: string) => void;
     onStatusChange?: (status: ExecutionStatus) => void;
     onError?: (error: Error) => void;
+    onInteraction?: (event: ChatWidgetInteractionEvent) => void;
     onReady?: (api: ChatWidgetAPI) => void;
     className?: string;
-    style?: React.CSSProperties;
+    style?: React__default.CSSProperties;
     height?: number | string;
+    /** 自建 jp-kicanvas 脚本 URL；未设则用 VITE_KICANVAS_SCRIPT_URL 或官方 CDN */
+    kicanvasScriptUrl?: string;
+    /** JETP-038: Current human user alias for discussion participation (e.g. "user:alice"). Defaults to "user". */
+    currentUserAlias?: string;
+}
+interface SkillSummary {
+    id: string;
+    name: string;
+    displayName: string;
+    description: string;
+    version?: string;
+    category?: string;
+    tags?: string[];
+}
+interface SkillListParams {
+    search?: string;
+    page?: number;
+    pageSize?: number;
+}
+interface SkillListResponse {
+    skills: SkillSummary[];
+    total: number;
+    page: number;
+    pageSize: number;
+}
+interface SelectedSkillRef {
+    id: string;
+    name: string;
+    version?: string;
+}
+type InteractionEventType = 'child-agent-toggle' | 'tool-result-toggle' | 'think-toggle' | 'todo-toggle' | 'todo-item-click' | 'link-click' | 'xref-navigate' | 'file-download' | 'artifact-click' | 'plan-step-click' | 'reference-add' | 'reference-remove' | 'viewer-open' | 'viewer-close' | 'immersive-toggle' | 'message-copy' | 'hitl-submit' | 'skill-select' | 'skill-remove' | 'skill-popup-open' | 'skill-popup-close' | 'skill-search'
+/**
+ * 会话生命周期：controller 真新建出 session 后触发（adapter.createSession 成功 /
+ * 后端通过 SSE ``session_info`` 推回新 session_id 都算）。从 ``sessionId`` prop
+ * 恢复历史会话不会触发本事件。
+ * metadata: ``{ sessionId: number, agentId?: string }``
+ */
+ | 'session-created'
+/**
+ * 会话信息更新：当前以 session_title 变化为唯一来源——SSE ``session_title`` 通知到达、
+ * loadHistory 取 detail / 兜底 sessionDetail 拿到非空 title 都会触发一次。
+ * metadata: ``{ sessionId: number, sessionTitle?: string }``
+ */
+ | 'session-updated';
+interface ChatWidgetInteractionEvent {
+    type: InteractionEventType;
+    target: string;
+    metadata?: Record<string, unknown>;
+    timestamp: number;
+}
+/**
+ * Controller 对外暴露的"会话生命周期事件"——比 InteractionEvent 更窄：
+ * 只关心"创建" / "信息更新"，不耦合 UI 交互层。ChatWidget 默认把它转译成
+ * ``'session-created' / 'session-updated'`` 这两条 InteractionEvent；高级宿主
+ * 也可以直接拿 controller 的 ``onSessionEvent`` 自己处理，绕开 InteractionContext。
+ */
+interface SessionLifecycleEvent {
+    type: 'created' | 'updated';
+    sessionId: number;
+    /** updated 时携带最新 session_title；created 一般为空。 */
+    sessionTitle?: string;
+    /** created 时携带 agentId，便于宿主统计 / 路由。 */
+    agentId?: string;
+    /** created 的来源：显式 createSession vs 后端 SSE 推回。 */
+    source?: 'explicit' | 'sse';
+}
+/**
+ * JETP-073：client（"办公室"）级 title 解析事件。
+ *
+ * controller 在以下时机各 emit 一次：
+ *   - SSE/WS ``client_title`` notification 到达（backend `node_title_agent`
+ *     基于 first_agent_start 派生出 LLM 起名后通过 redis stream 推下来）。
+ *
+ * 与 ``SessionLifecycleEvent.updated`` 关键区别：
+ *   - SessionLifecycleEvent 绑定 ``sessionId``；一个 session 一次。
+ *   - ClientTitleEvent 绑定 ``clientId``；多 client session 下每个 client 一次。
+ *
+ * sessionId 字段仅作上下文 hint，可能为 -1（loadHistory 中 session 未敲定时）。
+ * 真正的 routing key 是 ``clientId``。
+ */
+interface ClientTitleEvent {
+    type: 'client_title';
+    /** controller 当时持有的 currentSessionId；-1 表示未知（loadHistory 阶段）。 */
+    sessionId: number;
+    /** v2 client_id：``c_<22 base62>``。后端保证非空。 */
+    clientId: string;
+    /** LLM 派生的 client title（已被 backend 截到 ≤24 字）。 */
+    clientTitle: string;
+}
+/**
+ * 前端在发送一条消息时显式指定要用的模型，覆盖该 agent 在后端注册的默认 ``ModelMeta``。
+ *
+ * 设计：
+ * - ``name`` 必须是后端 fusion 能识别的 model 标识；前端不做白名单（后端校验）。
+ * - ``scope`` 决定是否透传到此次调用派生出的所有子 agent：
+ *   - ``'root'`` 只覆盖入口 agent 自己；子 agent 仍按各自 ``AgentMeta.model``。
+ *   - ``'all'``（默认）父 → 子 → 孙都用同一个 model，便于"指定模型跑完一棵任务树"。
+ * - ``settings`` 是增量字段，会浅合并进 ``ModelMeta.settings``（如 ``{ temperature: 0.3 }``）。
+ *
+ * 不在第一版做的事：按 role 映射 (`{ ask: 'haiku', deliver: 'opus' }`)、
+ * 自动降级到 agent 默认模型（语义上"用户授权使用且仅使用这个 model"）。
+ */
+interface ModelOverride {
+    name: string;
+    scope?: 'root' | 'all';
+    settings?: Record<string, unknown>;
+}
+/**
+ * 单条模型记录，等价于 hip ``Model`` DTO。每条 = 一个 (channel, model_name) 对。
+ *
+ * 何时用：上层希望让用户显式挑渠道（高阶面板 / 调试视图）。
+ * 想法是稳定 ``id`` 直接映射到 ``ModelOverride.name``——若上层需要传渠道路由，
+ * 就传完整 id（``channel/name``）；想让后端按账号策略选渠道，就传 ``name``。
+ */
+interface ModelListItemRaw {
+    id: string;
+    name: string;
+    channel: string;
+    created: number;
+    /**
+     * 该 (channel, model_name) 当前是否可用——hip-server 联表 model-lake
+     * ``/internal/model-status`` 的判定结果。
+     *
+     * **fail-safe 默认 true**：当 hip 端 status 接口拉不到 / 该 id 不在结果集时
+     * 都视为可用，避免一个内部接口故障让 picker 整体空列表。前端按"显式 false 才隐藏"
+     * 处理，**不要**对未定义状态做特殊兜底（与后端契约一致）。
+     *
+     * 字段为 optional 是为了兼容尚未升级到带 availability 的 hip 老版本：
+     * 解析方未拿到字段时按 true 处理（``ModelPicker`` 已经实现该兜底）。
+     */
+    available?: boolean;
+}
+/**
+ * 聚合形态（``group_by=name``），等价于 hip ``GroupedModel`` DTO。
+ * 每条 = 一个 model_name + 该 name 下所有可用渠道。
+ *
+ * 用法：picker 直接展示 ``name`` / ``displayName``，用户挑后把 ``name``
+ * 灌入 ``ModelOverride.name``，后端自行按账号策略选渠道。
+ */
+interface ModelListItemGrouped {
+    name: string;
+    channels: string[];
+    /**
+     * Channels 的子集，只含 ``available=true`` 的渠道。
+     * 前端不展示渠道时直接消费 ``defaultChannel``；
+     * 展示渠道时可用此把不可用的置灰。Optional 兼容老版本 hip。
+     */
+    availableChannels?: string[];
+    /**
+     * 该 name 下默认选中的渠道。
+     * 选取规则（hip 端）：**先 available 再 created** —— 即优先在 available
+     * 渠道里选注册时间最早的；全不可用才 fallback 到整体最早。
+     */
+    defaultChannel: string;
+    created: number;
+    /**
+     * 该 name 下是否至少有一个渠道可用。前端可用此快速决定"整行隐藏"。
+     * Optional 兼容老版本 hip：未定义时按 true 处理。
+     */
+    anyAvailable?: boolean;
+}
+/**
+ * Basename 聚合形态下的"渠道-完整 name"组合，等价于 hip ``BasenameVariant``。
+ *
+ * 关键约束：``name`` 字段是 model-lake 视角的**完整 model_name**
+ * （``anthropic__claude-opus-4`` / ``claude-opus-4-6`` / ``qwen__qwen3-max`` 等），
+ * 必须原样回传给后端 ``ModelOverride.name``。``basename`` 仅是 UI 标签，**不能**
+ * 替代 name —— 否则会丢失渠道路由信息（同 basename 不同渠道 = 不同账号 / 不同价格）。
+ */
+interface ModelListVariant {
+    name: string;
+    channel: string;
+    created: number;
+    /**
+     * 该 variant 当前是否可用，语义同 ``ModelListItemRaw.available``。
+     * fail-safe 默认 true（optional + 未定义按 true 处理）。
+     */
+    available?: boolean;
+}
+/**
+ * Basename 聚合形态（``group_by=basename``），等价于 hip ``BasenameGrouped``。
+ *
+ * 设计动机：model-lake 入库时 openrouter 渠道把 ``provider/model``
+ * （如 ``qwen/qwen3-max``）反规范化为 ``provider__model``（``qwen__qwen3-max``），
+ * 与 ali 渠道的 ``qwen3-max`` 在 ``ModelListItemGrouped`` 视角下被识别为不同 name，
+ * 实际上是同一物理模型。Basename 聚合再合并一层，给 picker 一个"无重复"的列表。
+ *
+ * 用法：picker 列表 = ``basename``；点开后展开 ``variants``，让用户挑渠道；
+ * 选定后把对应 variant 的 ``name`` 灌入 ``ModelOverride.name``。
+ */
+interface ModelListItemBasenameGrouped {
+    basename: string;
+    variants: ModelListVariant[];
+    /**
+     * 默认选中的 variant。
+     * 选取规则（hip 端）：**先 available 再 created** —— 即优先在 available
+     * variant 里选注册时间最早的；全不可用才 fallback 到整体最早。
+     */
+    defaultVariant: ModelListVariant;
+    created: number;
+    /**
+     * 该 basename 下是否至少有一个 variant 可用。前端可据此整行隐藏，
+     * 让运营态 picker 不出现"全部下游挂掉"的死项。Optional 兼容老版本 hip：
+     * 未定义时按 true 处理。
+     */
+    anyAvailable?: boolean;
+}
+interface ListModelsResponse<TItem = ModelListItemBasenameGrouped> {
+    items: TItem[];
+    total: number;
+}
+/**
+ * adapter.listModels 入参；保持极简、不引入 channel 之外的过滤维度——
+ * 进一步的"按租户/角色"过滤应在 backend 端做（hip 后续可加 query 参数），
+ * 而不是让前端自己穿配置文件。
+ */
+interface ListModelsParams {
+    /**
+     * 默认 ``'basename'``：按物理模型 basename 聚合，picker 默认形态。
+     * - ``'name'``     → 按完整 model_name 聚合（不归一 ``__`` ↔ ``/``）；
+     * - ``'none'``     → 返回 raw（按 channel/name 对）。
+     */
+    groupBy?: 'basename' | 'name' | 'none';
 }
 interface ChatWidgetAPI {
-    sendMessage: (message: string, agentId?: string) => void;
+    sendMessage: (message: string, agentId?: string, inlineRefs?: FileReference[], selectedSkills?: SelectedSkillRef[], overrideInstanceId?: number | null, clientId?: string, fileAttachments?: FileAttachment[], modelOverride?: ModelOverride | null) => void | Promise<void>;
     getCurrentRound: () => Round | null;
     getAllRounds: () => Round[];
     scrollToBottom: () => void;
     getStatus: () => ExecutionStatus;
+    /** Register a handler to receive references inline (e.g. insert into RichInput). When set, references bypass the external chip list. */
+    setReferenceInsertHandler: (handler: ((ref: FileReference) => void) | null) => void;
+    /**
+     * JETP-052 F-3c：在当前 session 内"开一个新对话流的浮动窗"。
+     *
+     * 编排：
+     *   1. 调用后端 ``POST /api/session/{sid}/clients`` 拿到 v2 ``c_<22>`` client_id
+     *   2. 把它加入 ``useFloatingWindows`` 浮动窗列表（``openWith``，附 title + contextPreloads 元数据）
+     *   3. 乐观更新到 ``useSessionClients`` 列表（sidebar 立刻可见）
+     *
+     * 失败时 reject；调用方 catch 后可以走 toast 或重试。
+     * 返回新分配的 v2 client_id（业务层可用来后续 sendMessage(clientId=...)）。
+     */
+    openClientWindow?: (opts: {
+        title?: string;
+        contextPreloads?: unknown[];
+    }) => Promise<string>;
+    /**
+     * 协作式停止当前 session 的 Agent 执行 —— 通过 `adapter.stopAgent` 走
+     * `POST /api/session/stop`，由后端写 Redis stop 信号；运行时检查点会在下一个
+     * tick 退出。详细机制见 `ChatWidgetAdapter.stopAgent` 注释。
+     *
+     * 设计要点（与 `useAgentControl().stop` 共享同一底层路径）：
+     * - **HTTP 单通道**：不依赖 WS 是否在线；跨 Pod 仍能命中；与 pause/resume 走 WS
+     *   的策略解耦（pause/resume 修改 pool 进程内状态，必须 WS 直送对应 Pod）。
+     * - **幂等**：后端键已存在时返回 `success(data={})`，连点两次安全。
+     * - **可选**：自定义 adapter 未实现 `stopAgent` 时本字段为 `undefined`，UI 应
+     *   据此降级（例如 DefaultComposer 在没有 stopAgent 时仍走旧 disabled 行为）。
+     *
+     * 何时存在：
+     * - `currentSessionId` 已就绪 **且** `adapter.stopAgent` 是函数 → 暴露此方法；
+     * - 否则为 `undefined`，避免给 UI 带来"按了没反应"的错觉。
+     *
+     * 失败语义：内部已 catch 网络错误并 `console.warn`，不向上抛 —— 让按钮 UI 不必
+     * 写自己的 try/catch；如宿主需要错误回调，请自行包一层 `try { await api.stopAgent() }`。
+     */
+    stopAgent?: () => Promise<void>;
+    /** JETP-040: File upload state and actions. Undefined when adapter does not support uploads. */
+    fileUpload?: {
+        attachments: UploadedFileInfo[];
+        readyFiles: FileAttachment[];
+        isUploading: boolean;
+        addFiles: (files: File[]) => void;
+        removeFile: (resourceId: string) => void;
+        clear: () => void;
+        enabled: boolean;
+    };
 }
 interface ToolCallData {
     tool_name: string;
@@ -213,6 +674,14 @@ interface NotificationTurn {
     status: string;
     timestamp_start: number | null;
     timestamp_end: number | null;
+    raw_message_count?: number;
+    /** JETP-045 Layer 1：客户端连接子空间标识。 */
+    client_id?: string;
+}
+interface PaginatedHistoryResponse {
+    turns: NotificationTurn[];
+    has_more: boolean;
+    next_cursor: string | null;
 }
 interface ResourceContent {
     resource_id: string;
@@ -223,6 +692,34 @@ interface ResourceContent {
     file_size: number | null;
     is_binary: boolean;
     content: string;
+    /** Direct URL for binary content (e.g. MinIO presigned URL), avoids base64 transfer for large files */
+    content_url?: string;
+    /** Language hint for syntax highlighting (e.g. "python", "go"); inferred from extension when absent */
+    language?: string;
+}
+/** Result of resolving a resource_id via ResourceProvider (CWRF-008) */
+interface ResourceResolveResult {
+    url?: string;
+    content?: string;
+    contentUrl?: string;
+    mimeType?: string;
+    fileName?: string;
+    isText?: boolean;
+    gitPath?: string;
+}
+/** File entry returned by listDirectoryFiles (CWRF-009) */
+interface DirectoryFileEntry {
+    resource_id: string;
+    file_name: string;
+    git_path: string;
+    download_url?: string;
+    node_type: string;
+}
+/** Options for listDirectoryFiles (CWRF-009) */
+interface ListDirectoryFilesOptions {
+    extensions?: string[];
+    recursive?: boolean;
+    generateUrls?: boolean;
 }
 interface SessionDetail {
     session_id: number;
@@ -230,20 +727,594 @@ interface SessionDetail {
     status?: string;
     created_at?: string;
 }
+interface PoolAgentAction {
+    tool_call_id: string;
+    tool: string;
+    purpose: string;
+    status: 'running' | 'completed' | 'failed' | string;
+    ts: number;
+}
+interface PoolAgent {
+    agent_instance_id: number;
+    agent_id: string;
+    agent_alias?: string;
+    /**
+     * JETP-083 WS3.7.7 follow-up: ``PAUSED`` is emitted by the backend
+     * ``RuntimeMonitor.agent_pool_status`` projection when the agent
+     * instance is blocked in ``_await_genui_blocking`` waiting on a HIL
+     * reply. ``PoolStatusPopover`` maps it to the ``paused`` state-key
+     * (label "等待人工" / "Awaiting human"); previously it fell through to
+     * the ``unknown`` bucket and the popover rendered "未知".
+     */
+    state: 'RUNNING' | 'PAUSED' | 'COMPLETED' | 'LOST' | string;
+    task_purpose?: string;
+    recent_actions?: PoolAgentAction[];
+    /**
+     * JETP-074（无退化路径版）：agent 归属到的 client（"办公室"），**必填**。
+     * backend MonitorRegistry.register 已严格化（缺 cid → ValueError），到达前端的
+     * 每个 PoolAgent 都必须有 cid；usePoolObservation 在 push/poll 路径上对缺 cid
+     * 的 patch 直接 console.error + drop，不让无 cid 的 agent 污染 observation。
+     */
+    client_id: string;
+}
+interface PoolStatusResponse {
+    session_id: number;
+    total: number;
+    agents: PoolAgent[];
+}
+interface MentionTarget {
+    identifier: string;
+    agent_id?: string;
+    agent_instance_id?: number;
+}
+interface PostDiscussionMessageRequest {
+    discussion_path: string;
+    speaker: string;
+    message_type: string;
+    mentions: string[];
+    mention_targets?: MentionTarget[];
+    body: string;
+    title?: string;
+}
+interface PostDiscussionMessageResponse {
+    ok: boolean;
+    message_index: number;
+    status: string;
+    remaining_messages: number;
+    participants_changed: boolean;
+    error?: string;
+    unresolved_mentions?: string[];
+}
+/**
+ * JETP-075: User-initiated discussion creation (POST /api/session/{sid}/discussion/create).
+ *
+ * Field shape mirrors backend Pydantic ``PostDiscussionCreateRequest`` 1:1
+ * (jetagents/runtime/discuss/api.py). 详见
+ * doc/proposals/JETP-075-user-initiated-discussion/00_protocol.md §2.
+ *
+ * 必填字段（pydantic ``Field(...)`` 强制）：
+ *   - ``topic``        : 1..100 chars, 进 YAML front-matter ``topic:``
+ *   - ``creator``      : ``user:<id>``，必须出现在 participants 内
+ *   - ``participants`` : 2..20 alias，第一位 = creator
+ *
+ * 可选字段：
+ *   - ``max_messages``           : 5..500，默认 50
+ *   - ``initial_body``           : ≤ 4000 chars；非空时同步写入首条消息并触发 ``_run_write_hook``
+ *   - ``initial_mentions``       : 必须是 participants 子集（service-level guard）
+ *   - ``initial_mention_targets``: 与 ``/message`` 端点同形态，用于 pin agent_instance_id
+ */
+interface CreateDiscussionRequest {
+    topic: string;
+    creator: string;
+    participants: string[];
+    max_messages?: number;
+    initial_body?: string;
+    initial_mentions?: string[];
+    initial_mention_targets?: MentionTarget[];
+}
+/**
+ * JETP-075: Response of POST /api/session/{sid}/discussion/create。
+ *
+ * 字段含义见 doc/proposals/JETP-075-user-initiated-discussion/00_protocol.md §2/§5：
+ *   - ``ok``                 : false 时 error 非空
+ *   - ``discussion_path``    : ``discussions/<slug>-<unix_ms>.disc.md`` 相对 workspace_root
+ *   - ``status``             : 创建后恒为 ``'active'``；schema 上对齐 DiscussionMeta.status
+ *   - ``message_count``      : 0 if no initial_body, 1 otherwise
+ *   - ``participants``       : echo 回完整列表（前端可用来 hydrate 浮窗 metadata）
+ *   - ``error``              : 错误时填，如 ``"creator must appear in participants"``
+ *   - ``unresolved_mentions``: initial_mentions 中无法在 session pool 解析的 alias 子集
+ */
+interface CreateDiscussionResponse {
+    ok: boolean;
+    discussion_path: string;
+    status: 'active' | 'converging' | 'resolved';
+    message_count: number;
+    participants: string[];
+    error: string;
+    unresolved_mentions: string[];
+}
+/**
+ * JETP-057：``getSessionHistory`` 入参契约。
+ *
+ * 设计：doc/proposals/JETP-057-history-by-client-id/chat-widget/01_adapter_design.md
+ *
+ * - ``clientIds`` 必传：禁止前端忘传 → 后端走 session-only 全表扫的退化路径。
+ *   常见取值：``['main']`` / ``['main', 'file:abc.txt', 'sel:section-1']``。
+ * - ``includeInFlight`` 默认 false（与后端默认对齐）；前端控制器层默认传 true，
+ *   避免 in-flight 子 agent 卡刷新后消失。
+ * - ``pageSize`` / ``beforeCursor`` 用于 keyset 分页（可选）。
+ */
+interface GetSessionHistoryOptions {
+    clientIds: string[];
+    pageSize?: number;
+    beforeCursor?: string;
+    includeInFlight?: boolean;
+}
+/**
+ * Session 列表项（用于侧栏 / 会话切换面板）。
+ *
+ * 字段优先级（用于 title 显示）：
+ *   1. ``sessionTitle`` —— 后端 SESSION_TITLE 通知落库的"对话标题"，最权威。
+ *   2. ``summary`` —— 首轮模型摘要，作为 fallback。
+ *   3. 都无 → 调用方自行兜底（如 "会话 {id}"）。
+ *
+ * 历史背景：JETP-058 之前 demo 误用 ``title`` 字段名，永远拿不到值；
+ * 现在 SDK 强制规范化为 ``sessionTitle``，adapter 层负责把后端各种字段名
+ * 翻译过来。
+ */
+interface SessionListItem {
+    id: number;
+    sessionTitle?: string | null;
+    summary?: string | null;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+    /** 可选：会话累计运行时长（秒），后端有则透传。 */
+    runningTime?: number | null;
+}
+interface ListSessionsParams {
+    /** 1-based 页码；默认 1。 */
+    page?: number;
+    /** 每页大小；默认 20。 */
+    pageSize?: number;
+}
+interface ListSessionsResponse {
+    items: SessionListItem[];
+    total: number;
+    page: number;
+    pageSize: number;
+}
 interface ChatWidgetAdapter {
     createSession(agentId: string): Promise<{
         sessionId: number;
         instanceId: number;
     }>;
     getSessionDetail(sessionId: number): Promise<SessionDetail>;
-    getSessionHistory(sessionId: number): Promise<NotificationTurn[]>;
+    /**
+     * List sessions belonging to the current user (paged).
+     *
+     * 用于宿主侧栏 / `<SessionListPanel>`。当 adapter 不实现该方法时，
+     * `<SessionListPanel>` 显示"unsupported"空态，`useSessionList().supported`
+     * 返回 false。adapter 应负责字段名规范化（snake_case → SDK 标准）。
+     */
+    listSessions?(params?: ListSessionsParams): Promise<ListSessionsResponse>;
+    /**
+     * Delete a session by id.
+     *
+     * 当 adapter 不实现该方法时，`<SessionListPanel>` 隐藏每行的删除按钮，
+     * `useSessionList().canDelete` 返回 false。
+     */
+    deleteSession?(sessionId: number): Promise<void>;
+    getSessionHistory(sessionId: number, options: GetSessionHistoryOptions): Promise<NotificationTurn[] | PaginatedHistoryResponse>;
     getResourceContent(sessionId: number, resourceId: string): Promise<ResourceContent>;
     submitHITLResponse(response: HITLResponse): Promise<void>;
+    /**
+     * JETP-083 WS3.7.6 — fetch pending Collaborative HIL entities for the
+     * connecting principal.
+     *
+     * Used by `useGenUIPending(sessionId)` on session connect / reconnect
+     * (e.g. fresh client, reload, hot-failover). Returns *only* HILs whose
+     * `resolved_recipients` include the connecting principal — the backend
+     * applies the ACL via the registry's principal-scoped index, so this
+     * endpoint cannot leak across users.
+     *
+     * When absent, JETP-083 connect-time hydration is disabled and the
+     * widget falls back to live-only behaviour: a HIL pause is only seen
+     * by the originating client. (Same as pre-WS3.7.6 behaviour.)
+     *
+     * Backend: `GET /api/genui/pending?session_id=...` (jetagents `main.py`).
+     */
+    getPendingHILs?(sessionId: number): Promise<PendingHIL[]>;
+    /**
+     * 触发"协作式停止"信号：直接 `POST /api/session/stop`，由后端 handler 把
+     * `agent:signal:stop:{session_id}:{interaction_id}=stop` 写入 Redis；运行时
+     * 各检查点（agent_state_machine_v2 / simple_agent_pool / agent_executor /
+     * base_pusher）轮询同一 key 后 yield `StoppedAgentCommand` 优雅退出，并由
+     * pusher 推送 `CANCELED` 通知。
+     *
+     * 设计要点：
+     * - **不依赖 WS 活性**：HTTP 任意 Pod 接到都能写入共享 Redis，跨 Pod 一致；
+     *   而 WS `control_agent` 必须命中持有该 session pool 的同一进程。
+     * - **后端幂等**：键已为 `"stop"` 时直接返回 `success(data={})`，不会重复发
+     *   `CANCELED`，前端连点两次安全。
+     * - **与 pause/resume 解耦**：pause/resume 修改 pool 进程内状态，必须 WS 直送；
+     *   stop 只是写一个全局 Redis 标志，HTTP 更稳。
+     *
+     * 参数说明：
+     * - `sessionId`：必填；后端从 DB 取该 session 的最新 event 来定位 stop key。
+     * - `agentInstanceId`：保留参数，**当前后端 handler 不读**（仅 session 维度
+     *   停止整轮交互）；保留是为了未来若引入实例级停止时调用方无需变更签名。
+     *
+     * 失败语义：401 由 adapter 的 `authedFetch` 自动 refresh + 重试；其它非 200
+     * 应抛 `ChatWidgetNetworkError`（含后端 `error("no event in session")` 等业务
+     * 失败码），上层据此 toast / 解锁按钮，避免吞错。
+     *
+     * 可选实现：自定义 adapter 未实现时，`useAgentControl.stop` 会回退到原 WS
+     * `control_agent { action: 'stop' }` 路径以保持向后兼容。
+     */
+    stopAgent?(params: {
+        sessionId: number;
+        agentInstanceId?: number;
+    }): Promise<void>;
     getStreamUrl(): string;
+    /**
+     * WebSocket URL for persistent session-level downlink (CWRF-010 S3 architecture).
+     * When provided and the session is active, the controller prefers WS over SSE.
+     * Messages are sent via fire-and-confirm POST; responses arrive through this WS channel.
+     * Falls back to SSE when absent or WS connection fails.
+     */
+    getWsUrl?(sessionId: number): string;
     getAuthHeaders(): Record<string, string>;
     getExtraHeaders?(): Record<string, string>;
+    /**
+     * Build the SSE request body for the stream endpoint.
+     * If implemented, ChatWidget uses the returned object as the POST body.
+     * If absent, ChatWidget sends the default simplified format {message, agent_id, ...}.
+     */
+    buildStreamBody?(params: {
+        message: string;
+        agentId: string;
+        sessionId: number | null;
+        interactionId: string;
+        agentInstanceId?: number;
+        callerInstanceId?: number;
+        selectedSkills?: SelectedSkillRef[];
+        activeSpecIds?: string[];
+        /**
+         * JETP-045 Layer 1：客户端连接子空间标识。
+         * 推荐由 `useClientId` hook 派生；不传时 adapter 兜底为 'main'。
+         */
+        clientId?: string;
+        /**
+         * JETP-045 Phase 6 — Layer 1.5 物理连接 ID（前端 ``useConnectionId`` 派生）。
+         * adapter 应把它写入 body 的 ``connection_id`` 字段；缺省时不写入，后端按
+         * "未知连接" 处理（不做 echo 抑制，等同 Phase 1-5 行为）。
+         */
+        connectionId?: string;
+        fileAttachments?: FileAttachment[];
+        /**
+         * 前端指定的"本次调用使用的模型"，覆盖 agent 的默认 ``ModelMeta``。
+         * 缺省 / null 时维持原行为（agent 自己的注册模型），与历史版本完全兼容。
+         * 详见 ``ModelOverride``。
+         */
+        modelOverride?: ModelOverride | null;
+    }): object;
+    listSkills?(params?: SkillListParams): Promise<SkillListResponse>;
     onAuthFailure?(): void;
     refreshAuth?(): Promise<boolean>;
+    /**
+     * Batch-resolve @xref RID references to file metadata.
+     * When absent, ResourceChip falls back to displaying the @xref description text.
+     */
+    resolveXrefs?(refs: XrefRef[]): Promise<XrefMeta[]>;
+    /**
+     * Obtain a direct URL for a resource (e.g. MinIO/S3 presigned URL) for streaming large binary files.
+     * When absent, falls back to base64 decoding from ResourceContent.content.
+     */
+    getResourceUrl?(sessionId: number, resourceId: string): Promise<string>;
+    /**
+     * Obtain a server-rendered preview URL for office/legacy files (CWRF-008).
+     * Backend converts the file (e.g. via LibreOffice headless) and returns a URL to the converted HTML/PDF.
+     * When absent, office viewers fall back to client-side rendering or download link.
+     */
+    getPreviewUrl?(sessionId: number, resourceId: string, format?: 'html' | 'pdf'): Promise<string>;
+    /**
+     * Transform a raw SSE JSON object into ChatWidget SSEMessage format.
+     * Used when connecting directly to backends that emit a different SSE schema
+     * (e.g. JetAgents Notification format vs ChatWidget flat format).
+     * Returns an array of SSEMessage objects (one notification may expand to multiple messages).
+     * Return null/undefined to drop the message.
+     */
+    transformSSEMessage?(raw: Record<string, unknown>): SSEMessage[] | null;
+    /**
+     * Fetch provenance graph snapshot for a session.
+     * When absent, provenance features are disabled.
+     */
+    getProvenanceGraph?(sessionId: number, params?: {
+        since_turn_id?: number;
+        limit?: number;
+    }): Promise<ProvenanceGraphSnapshot>;
+    /**
+     * List files in a directory, filtered by extensions (CWRF-009).
+     * Used by KiCad project viewer to discover all design files in a project directory.
+     * When absent, project-level multi-file viewing is unavailable.
+     */
+    listDirectoryFiles?(sessionId: number, dirPrefix: string, options?: ListDirectoryFilesOptions): Promise<DirectoryFileEntry[]>;
+    /**
+     * Create an artifact share link (JETP-034).
+     * When absent, Share button is hidden in jr-page viewer.
+     */
+    shareArtifact?(params: {
+        artifactId: string;
+        sessionId: number;
+        title?: string;
+        artifactType?: 'file' | 'jr-page';
+        shareType?: 1 | 2;
+    }): Promise<{
+        shareCode: string;
+        shareUrl: string;
+        password?: string;
+    } | null>;
+    /**
+     * Query the agent pool observation status for a session.
+     * Returns the list of agent instances and their states from MonitorRegistry.
+     * When absent, observation-driven status is disabled and the widget falls
+     * back to event-driven status tracking.
+     */
+    getPoolStatus?(sessionId: number): Promise<PoolStatusResponse>;
+    /**
+     * 拉取"用户可选模型清单"。**唯一来源**是 hip-server，**不走 fusion**。
+     *
+     * 当 adapter 不实现该方法时，上层 ModelPicker 应隐藏自身（fall back 到 agent
+     * 注册的默认模型，行为与历史版本完全一致）。
+     *
+     * URL 拼接规则：
+     *   ``${hipBaseUrl}/api/v1/models?...``，``hipBaseUrl`` 缺省时退化为相对 URL，
+     *   交给开发态 vite proxy / 生产态网关接管，与本 adapter 其他 hip 调用一致。
+     *
+     * 三态 vs. 抛错：
+     *   - 网络/服务故障 → 抛 ``ChatWidgetNetworkError``，让 UI 决定降级（toast + 隐藏）；
+     *   - 清单为空（数组长度 0） → 正常返回，UI 表现为"暂无可选模型"，不弹错；
+     *   - 不同 ``groupBy`` 返回不同的 item 形态，靠泛型在编译期收敛。
+     */
+    listModels?<TGroup extends 'basename' | 'name' | 'none' = 'basename'>(params?: ListModelsParams & {
+        groupBy?: TGroup;
+    }): Promise<ListModelsResponse<TGroup extends 'basename' ? ModelListItemBasenameGrouped : TGroup extends 'name' ? ModelListItemGrouped : ModelListItemRaw>>;
+    /**
+     * 按 ``agentId`` 查询该 agent 在后端注册的默认模型，**仅用于 picker 展示态**。
+     *
+     * 与 ``listModels`` 一样唯一走 hip-server（``GET /api/v1/agents/{agent_id}/default-model``），
+     * 不绕 fusion。该端点是后续 hip 全量代理 jetagents 的入口之一。
+     *
+     * 三态约定：
+     *   - 命中：返回 ``{ name, displayName?, version? }``，picker 把展示态自动定位到该 model；
+     *   - 业务找不到 / 上游 404：返回 ``null``（**不抛**），picker 退化到"显示默认模型"标签；
+     *   - 网络/超时/5xx：返回 ``null``（**不抛**），同上兜底；调用方真的关心错误时
+     *     可以观察 ``console.warn``。
+     *
+     * 这种"全部失败都吞成 null"的策略是有意为之：
+     *   该方法是"展示性的人因优化"，**不能因为它失败就阻塞用户输入**——
+     *   失败时 picker 仍可正常工作，只是少一个细节。所以 adapter 这一层吃掉异常，
+     *   而不是把它推给 UI 层做 try/catch。
+     *
+     * 当 adapter 不实现该方法时，picker 永远只显示"默认模型"占位，不报错。
+     */
+    getAgentDefaultModel?(agentId: string): Promise<{
+        name: string;
+        displayName?: string;
+        version?: string;
+    } | null>;
+    /**
+     * JETP-038: Post a human message to a discussion file.
+     * When absent, DiscussionComposer is hidden.
+     */
+    postDiscussionMessage?(sessionId: number, req: PostDiscussionMessageRequest): Promise<PostDiscussionMessageResponse>;
+    /**
+     * JETP-075: Create a new discussion file (user-initiated).
+     *
+     * 调用后端 ``POST /api/session/{sid}/discussion/create``：
+     *   - 在 workspace 下生成 ``discussions/<slug>-<unix_ms>.disc.md``
+     *   - YAML front-matter 持久化 topic / participants / created_by 等元数据
+     *   - 若 ``initial_body`` 非空，同时写入首条消息并触发 ``DiscussionWriteHook``
+     *     （进而 reinvoke @ 中的 agent / 投递 inbox notification）
+     *
+     * **当 adapter 不实现该方法时**：宿主端"创建讨论"入口必须隐藏或禁用，
+     * 否则会出现"前端开了浮窗但 .disc.md 不存在 → DiscussionViewer 一直显示
+     * 占位"的退化症（即 JETP-075 修复的 bug 形态）。
+     *
+     * 协议契约：``CreateDiscussionRequest`` / ``CreateDiscussionResponse``
+     * 与后端 Pydantic schema 1:1 对齐，详见
+     * doc/proposals/JETP-075-user-initiated-discussion/00_protocol.md §2。
+     *
+     * 错误处理（adapter 应原样抛出供上层 try/catch）：
+     *   - 400 → ``CreateDiscussionResponse.error`` 非空（topic empty / creator
+     *           not in participants / mentions not subset）
+     *   - 404 → workspace 未 onboard，宿主侧应 toast 提示
+     *   - 409 → 同毫秒 slug 碰撞，宿主侧建议重试一次（带新 ts）
+     *   - 5xx → 网络/持久化失败，按 ChatWidgetNetworkError 风格抛出
+     */
+    createDiscussion?(sessionId: number, body: CreateDiscussionRequest): Promise<CreateDiscussionResponse>;
+    /**
+     * JETP-038: List agents in the session pool (for @mention autocomplete).
+     * When absent, MentionAutocomplete only shows current participants.
+     */
+    getPoolAgents?(sessionId: number): Promise<PoolAgent[]>;
+    /**
+     * Download all visible workspace files as a single .zip archive.
+     * When absent, the download button is hidden in WorkspacePanel.
+     */
+    downloadWorkspaceZip?(sessionId: number): Promise<void>;
+    /**
+     * JETP-040 / JETP-058: Upload files to the knowledge base (batch).
+     * Returns resource_ids for use in send_message file contents.
+     * When sessionId is provided, files are also registered in the workspace.
+     * When absent, file attachment UI is hidden.
+     *
+     * `clientId` (JETP-058, v2 `^c_[A-Za-z0-9]{22}$`) 必填：服务端 ARTIFACT_* 通知的
+     * Layer-1 子空间标识。整 batch 复用同一 cid；retry 必须传同一 cid，让
+     * `_aggregate_turn` 走 `interaction_id` 幂等键合并到同一序列。
+     */
+    uploadFiles?(files: File[], sessionId: number | undefined, clientId: string): Promise<FileUploadResult>;
+    /**
+     * JETP-040: Poll upload processing status for previously uploaded files.
+     */
+    getUploadStatus?(resourceIds: string[]): Promise<FileUploadStatusResult>;
+    /**
+     * JETP-040 / JETP-058: Upload files directly to the workspace file system.
+     * When absent, the upload button is hidden in WorkspacePanel.
+     *
+     * `options.clientId` (JETP-058, v2) 必填，理由同 `uploadFiles`。
+     */
+    uploadWorkspaceFiles?(sessionId: number, files: File[], options: {
+        targetDirectory?: string;
+        clientId: string;
+    }): Promise<WorkspaceUploadResult>;
+    createWorkspaceDirectory?(sessionId: number, dirName: string, parentPath?: string): Promise<{
+        code: number;
+        message: string;
+    }>;
+    renameWorkspaceItem?(sessionId: number, oldPath: string, newName: string): Promise<{
+        code: number;
+        message: string;
+    }>;
+    deleteWorkspaceItems?(sessionId: number, paths: string[]): Promise<{
+        code: number;
+        message: string;
+    }>;
+    moveWorkspaceItems?(sessionId: number, sourcePaths: string[], targetDir: string): Promise<{
+        code: number;
+        message: string;
+    }>;
+    copyWorkspaceItems?(sessionId: number, sourcePaths: string[], targetDir: string): Promise<{
+        code: number;
+        message: string;
+    }>;
+}
+/** Input parameter for @xref reference resolution */
+interface XrefRef {
+    /** Raw URI, e.g. "rid://res-abc123#§3.2" or "url://docs.example.com/api" */
+    uri: string;
+    /** Description parameter from the @xref markup */
+    description: string;
+    /** Relationship type */
+    relation: 'cites' | 'implements' | 'extends' | 'derived_from' | 'supersedes' | 'related';
+}
+/** Return value from resolveXrefs */
+interface XrefMeta {
+    /** Corresponding original URI */
+    uri: string;
+    /** Resolved file name */
+    file_name?: string;
+    /** File MIME type */
+    mime_type?: string;
+    /** File path in workspace */
+    git_path?: string;
+    /** Resource ID usable with getResourceContent */
+    resource_id?: string;
+    /** File size in bytes */
+    file_size?: number;
+}
+/** Frontend @xref parse result — aligned with backend xref_parser.py XrefRecord format */
+interface XrefRecord {
+    relation: string;
+    target_resource: string;
+    target_file_id: string | null;
+    target_location: string | null;
+    description: string;
+    source_line: number;
+}
+/** File category enum — routes to the correct viewer */
+type FileCategory$1 = 'markdown' | 'code' | 'text' | 'image' | 'video' | 'audio' | 'html' | 'json' | 'pdf' | 'kicad' | '3d' | 'step' | 'gerber' | 'word' | 'excel' | 'powerpoint' | 'unknown';
+/** KiCad 画布点选（需 jp-kicanvas 透出 kicanvas:select + detail.jp） */
+interface KicadCanvasSelectionPayload {
+    uuid: string | null;
+    snippet: string | null;
+    /** 为 true 表示收到画布选中事件但无 detail.jp（当前为官方 KiCanvas） */
+    noJp?: boolean;
+    /** 点击位置相对于画布容器的坐标，用于浮动工具栏定位 */
+    anchorRect?: {
+        top: number;
+        left: number;
+        width: number;
+        height: number;
+    };
+    /** 多选时的所有 uuid+snippet 列表 */
+    items?: Array<{
+        uuid: string;
+        snippet: string | null;
+    }>;
+}
+interface FileReference {
+    resourceId: string;
+    sessionId: number;
+    fileName: string;
+    mimeType?: string | null;
+    specId?: string;
+    selection?: {
+        text: string;
+        startLine?: number;
+        endLine?: number;
+        /** PDF page number (1-based) */
+        page?: number;
+        /** End page when selection spans pages */
+        endPage?: number;
+        /** Base64 data-url when an image was selected */
+        imageSrc?: string;
+    };
+}
+interface UploadedFileInfo {
+    resourceId: string;
+    fileName: string;
+    gitPath?: string;
+    localFile?: File;
+    status: 'uploading' | 'processing' | 'ready' | 'error';
+    progress?: string;
+    error?: string;
+}
+interface FileUploadResult {
+    status?: 'accepted' | 'partial_success' | 'failed';
+    code?: number;
+    message: string;
+    data: {
+        files: Array<{
+            resource_id: string;
+            original_filename: string;
+            status: number;
+            message: string;
+            git_path?: string;
+            git_commit_hash?: string;
+        }>;
+        errors?: Array<{
+            original_filename: string;
+            error: string;
+        }>;
+        total_files: number;
+        successful_uploads: number;
+        failed_uploads: number;
+    };
+}
+interface FileUploadStatusResult {
+    status: string;
+    data: {
+        files: Array<{
+            resource_id: string;
+            status: number;
+            progress?: string | null;
+        }>;
+        successful_count: number;
+        failed_count: number;
+        not_found_resource_ids: string[];
+        total_requested: number;
+    };
+}
+interface WorkspaceUploadResult {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+interface FileAttachment {
+    resourceId: string;
+    fileName: string;
+    gitPath?: string;
 }
 declare function mergeConsecutiveThinkMessages(messages: AggregatedMessage[]): AggregatedMessage[];
 interface TodoCardProps {
@@ -267,6 +1338,9 @@ interface MessageContentProps {
     enableTypewriter?: boolean;
     typewriterSpeed?: number;
     onArtifactClick?: (artifact: Artifact) => void;
+    onHITLSubmit?: (response: HITLResponse) => Promise<void>;
+    renderToolResult?: (displayType: string, data: ToolCallData) => React__default.ReactNode | null;
+    observedInstanceStates?: Map<number, PoolAgent>;
 }
 interface ChildAgentCardProps {
     message: AggregatedMessage;
@@ -279,6 +1353,9 @@ interface ChildAgentCardProps {
     endedAgentInstanceIds?: Set<number>;
     /** 本轮次全部消息，用于判断该 agent 是否有未完成的工具（子 agent 的 MCP 消息可能挂在别的 parent 下，不在此卡片的 children 里） */
     allRoundMessages?: AggregatedMessage[];
+    onHITLSubmit?: (response: HITLResponse) => Promise<void>;
+    /** Observation-driven instance states from MonitorRegistry (pool observation). */
+    observedInstanceStates?: Map<number, PoolAgent>;
 }
 interface PlanCardProps {
     plan: TaskPlan;
@@ -287,24 +1364,90 @@ interface PlanCardProps {
 }
 
 /**
- * ChatWidget 主组件
+ * ChatWidget 主组件 — UI Shell
  *
- * 严格按照设计文档实现：
- * - SSE 消息流处理
- * - 动态置顶（滚动切换，带防抖和滞后阈值）
- * - 多轮对话展示
- * - 平滑过渡动画（淡入淡出）
- * - 子 Agent 卡片
- * - Human-in-the-loop 支持
+ * Business logic (SSE, aggregation, session, status) is delegated to
+ * useChatWidgetController.  This file only owns DOM/scroll/viewer/animation.
  */
 
-declare const ChatWidget: React.FC<ChatWidgetProps>;
+declare const ChatWidget: React__default.FC<ChatWidgetProps>;
+
+type IconName = 'robot' | 'chat' | 'clipboard' | 'paperclip' | 'chart' | 'notepad' | 'warning' | 'check' | 'checkCircle' | 'hourglass' | 'spinner' | 'x' | 'xCircle' | 'circle' | 'caretDown' | 'caretRight' | 'lightning' | 'gear' | 'play' | 'brain' | 'list' | 'file' | 'fileText' | 'fileCode' | 'filePdf' | 'filePlus' | 'fileXls' | 'fileDoc' | 'filePpt' | 'fileCsv' | 'fileZip' | 'download' | 'arrowsOut' | 'arrowsIn' | 'arrowUp' | 'minus' | 'magnifyingGlass' | 'globe' | 'code' | 'terminal' | 'package' | 'copy' | 'link' | 'share' | 'arrowLeft' | 'info' | 'compress' | 'eye' | 'circuitry' | 'user' | 'image' | 'folder' | 'folderOpen' | 'house' | 'pencilSimple' | 'chatCircleDots' | 'pushPin' | 'pause' | 'stop' | 'table' | 'layers' | 'brackets' | 'usersThree' | 'uploadSimple' | 'plus' | 'folderPlus' | 'arrowRight' | 'dotsThree' | 'cpu' | 'sparkle' | 'chevronDown';
+
+type IconWeight = 'thin' | 'light' | 'regular' | 'bold' | 'fill' | 'duotone';
+interface IconProps {
+    name: IconName;
+    size?: number;
+    weight?: IconWeight;
+    className?: string;
+    color?: string;
+    style?: React__default.CSSProperties;
+    'aria-hidden'?: boolean;
+    'aria-label'?: string;
+}
+declare const Icon: React__default.FC<IconProps>;
+
+type TransportMode = 'ws' | 'sse';
+interface AgentInstanceState {
+    agentInstanceId: number;
+    status: 'running' | 'paused' | 'finished' | 'stopped' | 'error';
+    name?: string;
+    interactionId?: string;
+}
+interface SessionChannelMessage {
+    type: string;
+    data: unknown;
+    interactionId?: string;
+    agentInstanceId?: number;
+    seq?: number;
+}
+interface AgentControlFrame {
+    action: 'pause' | 'resume' | 'stop';
+    agentInstanceId: number;
+}
+interface UseSessionChannelOptions {
+    sessionId: number | null;
+    wsUrl?: string | null;
+    token?: string | null;
+    transport?: TransportMode;
+    enabled?: boolean;
+    /**
+     * JETP-045 P5 (P2-T11/T13)：cursor 形态升级为 ``Map<"${iid}::${callee}", max_turn_index>``。
+     * 多 callee fan-out 场景下不再撞 key（旧 ``Record<iid, max>`` 会丢一个 callee
+     * 的记录）。subscribe 时序列化为 array of (interaction_id, callee_instance_id,
+     * max_turn_index)；后端 ``/ws/session/{id}`` handler (PR-8 P2-T14) 同时支持
+     * 旧 dict 形态以兼容老前端。
+     */
+    turnCursorRef?: RefObject<Map<string, number>>;
+    onMessage?: (msg: SessionChannelMessage) => void;
+    onStatusEvent?: (event: SessionChannelMessage) => void;
+    /** Fired when the server sends DB-sourced recovery turns after detecting
+     *  that Redis Streams have been trimmed past the client's cursor. */
+    onRecoveryTurns?: (turns: unknown[]) => void;
+}
+interface UseSessionChannelReturn {
+    connected: boolean;
+    transport: TransportMode;
+    agentStates: Map<number, AgentInstanceState>;
+    sendControlFrame: (frame: AgentControlFrame) => void;
+    lastSeq: number;
+    /** Force reconnect if WS is not connected; resolves when connected or rejects on timeout. */
+    ensureConnected: () => Promise<void>;
+}
+declare function useSessionChannel(options: UseSessionChannelOptions): UseSessionChannelReturn;
 
 /**
  * SSE 连接 Hook (SDK version)
  *
- * Auth and headers are fully delegated to ChatWidgetAdapter,
- * eliminating direct localStorage / env-var coupling.
+ * JETP-056 P2 收敛：
+ * - 全链路统一 ``fetch + ReadableStream``：废弃浏览器 ``EventSource``。
+ *   原因：``EventSource`` API 不支持自定义 header，无法注入 ``Authorization``，
+ *   在 Bearer-only 部署下完全跳过鉴权（依赖 cookie 兜底是错的）。
+ * - 鉴权 / 401 重试 / onAuthFailure 全部收敛到 ``useAuthedFetch``：
+ *   - useSSE 不再手写 401 重试逻辑；
+ *   - 与 useChatWidgetController 等其他鉴权入口共用同一条策略链。
+ * - 下游 SSE 解析逻辑（reader loop / data: 解析 / transformSSEMessage）保持不变，
+ *   行为兼容；GET 与 POST 仅在 ``method`` / ``body`` 上有差异。
  */
 
 type ConnectionStatus = 'idle' | 'connecting' | 'connected' | 'disconnected' | 'error';
@@ -324,6 +1467,132 @@ interface UseSSEReturn {
 }
 declare function useSSE(options: UseSSEOptions): UseSSEReturn;
 
+/**
+ * usePoolObservation — observation-driven agent pool status
+ *
+ * Hybrid push+poll strategy:
+ *   Push:  pool_snapshot events from the WS status stream give near-instant updates.
+ *   Poll:  GET /api/monitor/pool/{session_id} at adaptive intervals as a reliable fallback.
+ *
+ * Consumers:
+ *   - Top bar:           sessionBusy  (any RUNNING agent in the session)
+ *   - Child agent cards: instanceStates.get(agentInstanceId)
+ *   - Input box:         caller checks the primary agent instance via instanceStates
+ */
+
+interface PoolObservation {
+    sessionBusy: boolean;
+    instanceStates: Map<number, PoolAgent>;
+    poolAgents: PoolAgent[];
+}
+
+interface ChatWidgetControllerOptions {
+    adapter: ChatWidgetAdapter;
+    sessionId?: string | number;
+    reuseAgentInstance?: boolean;
+    activeSpecIdsRef?: React.RefObject<string[]>;
+    /** Transport mode: 'ws' uses WebSocket, 'sse' uses Server-Sent Events. No fallback between them. */
+    transport?: 'ws' | 'sse';
+    /**
+     * JETP-058：拉历史时透传给 adapter 的 v2 ``c_<22>`` client_ids 列表。
+     *
+     * - **不再有 legacy "main" 默认值**：v2-only 强约束下，调用方未派生出任何 v2 cid 之前
+     *   controller 不会发起 history 请求（避免 silent fallback 写脏数据）；
+     * - 由 ChatWidget 内部派生为该 session 全部任务话池 cid 列表后再下传；
+     * - 空数组 / undefined → controller skip 调 adapter，等下一轮派生到非空 list 时自动重拉。
+     */
+    historyClientIds?: string[];
+    /**
+     * JETP-057：拉历史时是否包含 status='building' 的 in-flight turns。
+     * 前端默认 ``true`` —— 否则刷新后正在跑的子 agent 卡片会暂时消失。
+     */
+    historyIncludeInFlight?: boolean;
+    /**
+     * 是否在 mount 时立即调用 ``adapter.createSession`` 预分配 session+workspace。
+     * 默认 ``true`` 保持原 SDK 行为；多会话宿主（如 Demo / Console）应传 ``false``，
+     * 避免每次刷新（无 ``sessionId`` prop 的 mount）都在后端 page 列表里插入空 session。
+     */
+    eagerSessionCreation?: boolean;
+    onStatusChange?: (status: ExecutionStatus) => void;
+    onConnectionChange?: (connected: boolean) => void;
+    onRoundChange?: (rounds: Round[]) => void;
+    onMessageAppended?: (message: AggregatedMessage, round?: Round) => void;
+    onRoundStart?: (interactionId: string, userMessage: string) => void;
+    onRoundEnd?: (interactionId: string) => void;
+    onError?: (error: Error) => void;
+    onDiscussionUpdate?: (event: Record<string, unknown>) => void;
+    /**
+     * 会话生命周期事件回调。controller 在以下时机各 emit 一次：
+     *
+     *   - `created` ：``adapter.createSession`` 成功 / 后端通过 SSE ``session_info`` 推回新 session_id；
+     *     从 ``sessionId`` prop 恢复历史会话不会触发本事件。
+     *   - `updated` ：当前以 ``session_title`` 变化为唯一来源 —— SSE ``session_title`` 通知 /
+     *     ``loadHistory`` 取 detail / 兜底 ``getSessionDetail`` 拿到非空 title 都会各触发一次。
+     *
+     * ChatWidget 默认会把这两条 emit 转译成 ``'session-created' / 'session-updated'``
+     * InteractionEvent；如果宿主不走 InteractionContext，可以直接读这个回调。
+     */
+    onSessionEvent?: (event: SessionLifecycleEvent) => void;
+    /**
+     * JETP-073：client（"办公室"）级 title 解析事件回调。
+     *
+     * 触发时机：SSE/WS 收到 ``notification_type: 'client_title'`` 消息（backend
+     * `node_title_agent` 在 first agent start 后基于 LLM 派生出的客户端标题）。
+     *
+     * 与 ``onSessionEvent`` 关键区别：
+     *   - ``onSessionEvent.updated`` 一个 session 触发一次；
+     *   - ``onClientTitleEvent`` 一个 session 内每个 client 各触发一次（多 client 场景常见）。
+     *
+     * 上层（如 yumiai-web ``WorkspaceCore``）把 ``clientId → clientTitle`` 累加到本地 map，
+     * 下游派生（如 ``useDeriveCubicleClients``）优先使用 backend 真值，缺值时再 fallback。
+     *
+     * 本回调不会被 controller 内部消化掉；message 也不会进入 rounds（被
+     * ``LIFECYCLE_TURN_TYPES`` 过滤）。
+     */
+    onClientTitleEvent?: (event: ClientTitleEvent) => void;
+}
+interface ChatWidgetControllerState {
+    executionStatus: ExecutionStatus;
+    connectionStatus: ConnectionStatus;
+    /** Effective transport mode: 'ws' when WebSocket is active, 'sse' otherwise */
+    activeTransport: 'ws' | 'sse';
+    rounds: Round[];
+    /** Interaction IDs owned by this tab (sent locally or loaded from history). */
+    localInteractionIds: ReadonlySet<string>;
+    currentSessionId: number | null;
+    sessionTitle: string;
+    todoMap: Map<string, TodoData>;
+    specMetaMap: Map<string, {
+        resourceId: string;
+        gitPath: string;
+    }>;
+    /** JETP-083 WS3.7.5 — terminal lifecycle markers (cancelled/error) by spec_id. */
+    specLifecycleMap: Map<string, SpecLifecycleEntry>;
+    sendMessage: (message: string, agentId?: string, inlineRefs?: FileReference[], selectedSkills?: SelectedSkillRef[], overrideInstanceId?: number | null, clientId?: string, fileAttachments?: FileAttachment[], modelOverride?: ModelOverride | null) => Promise<void>;
+    widgetAPI: ChatWidgetAPI;
+    /** Agent instance states tracked via WS status stream. Empty map when SSE transport. */
+    agentStates: Map<number, AgentInstanceState>;
+    /** Send agent control frame (pause/resume/stop) via WS. No-op when SSE. */
+    sendControlFrame: UseSessionChannelReturn['sendControlFrame'];
+    /** Whether any agent is RUNNING in the session (observation-driven, for top bar). */
+    sessionBusy: boolean;
+    /** Whether the WebSocket is connected (for useDiscussions polling adjustment). */
+    wsConnected: boolean;
+    /** Whether the primary (level-0) agent instance is RUNNING (observation-driven, for input box). */
+    primaryAgentBusy: boolean;
+    /** Full pool observation data (for child agent cards). */
+    poolObservation: PoolObservation;
+    /** JETP-037: whether more older pages are available */
+    hasMore: boolean;
+    /** JETP-037: whether an older page is currently loading */
+    loadingMore: boolean;
+    /** JETP-037: trigger loading of the next older page */
+    loadOlderPage: () => Promise<void>;
+    /** Ensure a session exists, creating one with retries if needed. */
+    ensureSession: () => Promise<number>;
+}
+declare function useChatWidgetController(options: ChatWidgetControllerOptions): ChatWidgetControllerState;
+
 /**
  * 消息聚合 Hook
  *
@@ -343,95 +1612,1427 @@ interface MessageAggregatorState {
 interface UseMessageAggregatorReturn {
     state: MessageAggregatorState;
     todoMap: Map<string, TodoData>;
+    specMetaMap: Map<string, {
+        resourceId: string;
+        gitPath: string;
+    }>;
+    /** JETP-083 WS3.7.5 — terminal lifecycle markers (cancelled / error) keyed by spec_id. */
+    specLifecycleMap: Map<string, SpecLifecycleEntry>;
     processMessage: (message: SSEMessage) => void;
     getRoundsList: () => Round[];
     getCurrentRound: () => Round | null;
-    startNewRound: (interactionId: string, userMessage: string) => void;
+    startNewRound: (interactionId: string, userMessage: string, clientId?: string) => void;
     loadRounds: (rounds: Round[]) => void;
+    prependRounds: (olderRounds: Round[]) => void;
+    mergeRecoveryRounds: (rounds: Round[]) => void;
     finalizeRound: (interactionId: string) => void;
+    loadTodoMap: (entries: Map<string, TodoData>) => void;
+    loadSpecMetaMap: (entries: Map<string, {
+        resourceId: string;
+        gitPath: string;
+    }>) => void;
+    loadSpecLifecycleMap: (entries: Map<string, SpecLifecycleEntry>) => void;
     clear: () => void;
+    /**
+     * JETP-045 Phase 6 (P6-T07) — 设置当前 tab 的物理连接 ID。
+     * Aggregator 用 ``msg.connection_id_from === myConnectionId`` 识别 echo (AC-CONN-006/007)。
+     * Controller 在 mount 期间用 ``useConnectionId()`` 派生后调用一次即可；多次调用幂等。
+     * 不传或传 undefined ⇒ 关闭 echo 检测，行为退化到 Phase 1-5 (AC-CONN-008)。
+     */
+    setMyConnectionId: (id: string | undefined) => void;
 }
 declare function useMessageAggregator(): UseMessageAggregatorReturn;
 
+interface ProjectFile {
+    name: string;
+    url?: string;
+    content?: string;
+}
+interface UseProjectFilesOptions {
+    gitPath: string;
+    extensions: string[];
+    enabled: boolean;
+    recursive?: boolean;
+    generateUrls?: boolean;
+    /** Extra deps that trigger re-discovery (e.g. file content for project files). */
+    deps?: unknown[];
+}
+interface UseProjectFilesResult {
+    files: ProjectFile[];
+    loading: boolean;
+    error: string | null;
+}
 /**
- * 置顶区域组件
- * 显示当前置顶轮次的用户消息、任务计划和 Todo
+ * Generic hook: discover and load all files matching given extensions
+ * under the directory derived from `gitPath`.
+ *
+ * Works for any viewer that needs sibling-file discovery:
+ * KiCad (.kicad_sch/.kicad_pcb), Gerber (.gbr/.drl), etc.
  */
+declare function useProjectFiles(opts: UseProjectFilesOptions): UseProjectFilesResult;
 
-declare const PinnedArea: React.FC<PinnedAreaProps>;
+interface ViewerTab {
+    id: string;
+    resourceId: string;
+    fileName: string;
+    mimeType?: string;
+    isNew?: boolean;
+    isDirty?: boolean;
+    annotationCount?: number;
+    openedAt: number;
+}
+interface UseViewerTabsReturn {
+    tabs: ViewerTab[];
+    activeTabId: string | null;
+    addTab: (tab: Omit<ViewerTab, 'id' | 'openedAt' | 'isNew'>) => string;
+    removeTab: (tabId: string) => void;
+    switchTab: (tabId: string) => void;
+    updateTab: (tabId: string, updates: Partial<ViewerTab>) => void;
+    getActiveTab: () => ViewerTab | null;
+    markSeen: (tabId: string) => void;
+    findByResourceId: (resourceId: string) => ViewerTab | undefined;
+    clearAll: () => void;
+}
+declare function useViewerTabs(): UseViewerTabsReturn;
 
-/**
- * 轮次标题组件
- * 在消息流中显示非置顶轮次的用户消息和计划
- */
+type EscHandler = () => boolean | void;
+declare const ESC_PRIORITY: {
+    readonly INLINE_INPUT: 60;
+    readonly FLOATING_TOOLBAR: 50;
+    readonly ANNOTATION_FAB: 40;
+    readonly OVERLAY: 30;
+    readonly EXIT_IMMERSIVE: 10;
+};
+declare function useEscStack(handler: EscHandler, active: boolean, priority?: number): void;
 
-declare const RoundHeader: React.FC<RoundHeaderProps>;
+interface ArtifactRef {
+    resourceId: string;
+    fileName: string;
+    mimeType?: string;
+}
+interface UseAutoTabOptions {
+    artifacts: ArtifactRef[];
+    tabs: UseViewerTabsReturn;
+    enabled?: boolean;
+    autoOpenSplit?: () => void;
+}
+declare function useAutoTab({ artifacts, tabs, enabled, autoOpenSplit, }: UseAutoTabOptions): void;
 
-/**
- * 消息内容组件
- * 根据消息类型渲染不同的内容
- * 文本类型使用 Streamdown 渲染 Markdown（代码高亮、Mermaid、数学公式、CJK）
- * 保留逐字打字机效果：将逐步展开的文本交给 Streamdown 渲染
- */
+interface WorkspaceFile {
+    resourceId: string;
+    fileName: string;
+    gitPath: string;
+    mimeType?: string;
+    downloadUrl?: string;
+    nodeType: string;
+    timestamp?: number;
+}
+interface WorkspaceTreeNode {
+    id: string;
+    name: string;
+    path: string;
+    type: 'file' | 'dir';
+    children?: WorkspaceTreeNode[];
+    file?: WorkspaceFile;
+}
+interface UseWorkspaceFilesOptions {
+    adapter: ChatWidgetAdapter;
+    sessionId: number | null;
+    pollIntervalMs?: number;
+    /** When this flips from false→true (WS reconnect), trigger an immediate refresh. */
+    wsConnected?: boolean;
+}
+interface UseWorkspaceFilesReturn {
+    files: WorkspaceFile[];
+    tree: WorkspaceTreeNode[];
+    recentChanges: WorkspaceFile[];
+    fileCount: number;
+    loading: boolean;
+    error: Error | null;
+    refresh: () => void;
+}
+declare function useWorkspaceFiles({ adapter, sessionId, pollIntervalMs, wsConnected, }: UseWorkspaceFilesOptions): UseWorkspaceFilesReturn;
 
-declare const MessageContent: React.FC<MessageContentProps>;
+interface TreePersistState {
+    expandedPaths: string[];
+    scrollTop: number;
+}
+declare function useTreePersist(sessionId: number | null): {
+    load: () => TreePersistState | null;
+    save: (state: TreePersistState) => void;
+};
 
-/**
- * 子 Agent 卡片组件
- * 可折叠，固定高度，内部滚动
- */
+interface UseAgentControlOptions {
+    channel: UseSessionChannelReturn | null;
+    adapter: ChatWidgetAdapter;
+    sessionId: number | null;
+}
+declare function useAgentControl({ channel, adapter, sessionId, }: UseAgentControlOptions): {
+    pause: (agentInstanceId: number) => Promise<void>;
+    resume: (agentInstanceId: number) => Promise<void>;
+    stop: (agentInstanceId: number) => Promise<void>;
+};
 
-declare const ChildAgentCard: React.FC<ChildAgentCardProps & {
-    onArtifactClick?: (artifact: Artifact) => void;
-}>;
+type AnnotationKind = 'file-level' | 'anchored';
+interface AnnotationAnchor {
+    text: string;
+    startLine?: number;
+    endLine?: number;
+    elementId?: string;
+}
+interface AnnotationInteraction {
+    id: string;
+    interactionIds: string[];
+    resourceId: string;
+    kind: AnnotationKind;
+    anchor?: AnnotationAnchor;
+    createdAt: number;
+    lastMessageAt: number;
+    preview?: string;
+    lastRoundCompleted?: boolean;
+    agentInstanceId?: number;
+    /** JETP-045 P3-T01：Layer 1 子空间标识；旧名 channelId。 */
+    clientId?: string;
+}
+interface AnnotationMessage {
+    role: 'user' | 'assistant';
+    text: string;
+    interactionId: string;
+    timestamp?: number;
+}
 
+interface AnnotationAllocateOpts {
+    /** 'file' for file-level, 'selection' for anchored. */
+    kind: 'file' | 'selection';
+    /** 资源 ID（必填，作为 context_preloads.source_uri / refId）。 */
+    resourceId: string;
+    /** 选区 anchor（仅 selection 用，作为 context_preloads.rangeHash 的源数据）。 */
+    anchor?: AnnotationAnchor;
+    /** 用于人类可读标题（如文件名 + 选区文本片段）。 */
+    title?: string;
+}
 /**
- * 任务计划卡片组件
+ * JETP-058 v2-only：批注/选区对话流的 v2 cid 分配器。
+ * ChatWidget 注入闭包，内部组装 contextPreloads 后调 allocator.createClient。
+ * 返回的 cid 必须是 v2 ``c_<22>``。
  */
+type AnnotationClientIdAllocator = (opts: AnnotationAllocateOpts) => Promise<string>;
+interface UseAnnotationsOptions {
+    sendMessage: (message: string, agentId?: string, inlineRefs?: any[], selectedSkills?: any[], overrideInstanceId?: number | null, clientId?: string) => Promise<void>;
+    rounds: Round[];
+    activeResourceId: string | null;
+    /**
+     * JETP-058：分配 v2 cid。每个 (resourceId + anchor) 维度懒分配一次，缓存复用；
+     * 失败时直接抛错（ChatWidget 通过 toast 暴露），不再静默 fallback `file:`/`sel:` 字面量。
+     */
+    allocateClientId: AnnotationClientIdAllocator;
+}
+interface UseAnnotationsReturn {
+    interactions: AnnotationInteraction[];
+    activeInteractions: AnnotationInteraction[];
+    fileLevelForResource: AnnotationInteraction | null;
+    anchoredForResource: AnnotationInteraction[];
+    getMessages: (interactionId: string) => AnnotationMessage[];
+    startFileLevelAnnotation: (resourceId: string, message: string) => Promise<void>;
+    startAnchoredAnnotation: (resourceId: string, anchor: AnnotationAnchor, message: string) => Promise<void>;
+    sendFollowUp: (interactionId: string, message: string) => Promise<void>;
+    isCreating: boolean;
+}
+declare function useAnnotations({ sendMessage, rounds, activeResourceId, allocateClientId, }: UseAnnotationsOptions): UseAnnotationsReturn;
 
-declare const PlanCard: React.FC<PlanCardProps>;
-
-declare const TodoCard: React.FC<TodoCardProps>;
+interface ShortcutDef {
+    key: string;
+    meta?: boolean;
+    shift?: boolean;
+    handler: () => void;
+}
+interface UseShortcutsOptions {
+    shortcuts: ShortcutDef[];
+    enabled?: boolean;
+}
+declare function useShortcuts({ shortcuts, enabled }: UseShortcutsOptions): void;
 
-/**
- * Schema 表单渲染器
- * 根据 JSON schema 动态生成表单 UI
- */
+declare function useNarrowMode(containerRef: React.RefObject<HTMLElement | null>, breakpoint?: number): boolean;
 
-interface SchemaNode {
-    type: string;
-    key?: string;
-    name?: string;
-    props?: Record<string, unknown>;
-    children?: SchemaNode[];
-    options?: Array<{
-        label: string;
-        value: string;
-    }>;
-    rules?: Array<{
-        required?: boolean;
-        message?: string;
-    }>;
-    schema?: SchemaNode;
+interface ReadReceipt {
+    agent: string;
+    read: boolean;
 }
-interface SchemaFormRendererProps {
-    schema: SchemaNode;
-    onSubmit?: (values: Record<string, unknown>) => void | Promise<void>;
-    awaitCommandUuid?: string;
+interface DiscussionMessage {
+    speaker: string;
+    timestamp: string;
+    type: 'message' | 'finding' | 'question' | 'proposal' | 'decision' | 'action_item';
+    mentions: string[];
+    title?: string;
+    body: string;
+    readReceipts?: ReadReceipt[];
+}
+interface DiscussionMeta {
+    topic: string;
+    created: string;
+    status: 'active' | 'converging' | 'resolved' | 'archived';
+    participants: string[];
+    max_messages?: number;
+    discussion_mode?: string;
+    converge_grace?: number;
+    tags?: string[];
+}
+interface DiscussionFile {
+    resourceId: string;
+    fileName: string;
+    gitPath: string;
+    meta: DiscussionMeta;
+    messages: DiscussionMessage[];
+    messageCount: number;
+    pendingReceiptCount: number;
+}
+interface UseDiscussionsOptions {
+    adapter: ChatWidgetAdapter;
+    sessionId: number | null;
+    currentUser?: string;
+    pollIntervalMs?: number;
+    wsConnected?: boolean;
+    poolAgents?: PoolAgent[];
 }
-declare const SchemaFormRenderer: React.FC<SchemaFormRendererProps>;
+interface UseDiscussionsReturn {
+    discussions: DiscussionFile[];
+    totalCount: number;
+    activeCount: number;
+    newDiscussionIds: Set<string>;
+    loading: boolean;
+    refresh: () => void;
+    refreshSingleDiscussion: (gitPath: string) => Promise<void>;
+    postMessage: (discussionPath: string, body: string, messageType: string, mentions: string[]) => Promise<PostDiscussionMessageResponse>;
+    discussionUnread: number;
+    clearDiscussionUnread: () => void;
+    handleWsDiscussionUpdate: (event: Record<string, unknown>) => void;
+}
+declare function parseDiscussionMessages(raw: string): {
+    meta: DiscussionMeta | null;
+    messages: DiscussionMessage[];
+};
+declare function useDiscussions({ adapter, sessionId, currentUser, pollIntervalMs, wsConnected, poolAgents, }: UseDiscussionsOptions): UseDiscussionsReturn;
 
-interface ToolCardBufferingProps {
-    message: AggregatedMessage;
+interface UseFileUploadOptions {
+    adapter: ChatWidgetAdapter;
+    sessionId?: number | null;
+    ensureSession?: () => Promise<number>;
+    pollIntervalMs?: number;
+    maxFileSize?: number;
+    onUploadSuccess?: () => void;
+    /**
+     * JETP-058: ChatWidget 当前活跃的 v2 client_id（用户正在看的话池）。
+     * 当 batch 第一次入队时被快照到 batch；后续 retry 复用同一 cid，
+     * 让后端 _aggregate_turn 走 interaction_id 幂等键合并到同一 ARTIFACT_* 序列。
+     * `null` 表示当前没有活跃话池（例如刚切到老 session 还未选择话池），
+     * 此时 hook 会调 `ensureClientId()` 现场创建一个 v2 cid。
+     */
+    currentClientId?: string | null;
+    /**
+     * JETP-058: 当 `currentClientId` 缺失时调用，返回一个新的 v2 client_id。
+     * 通常来自 `useClientIdAllocator.createClient(sessionId, ...)`。
+     * 若未提供且 `currentClientId` 也为 null，则上传立即失败（早失败 > 半成品入库）。
+     */
+    ensureClientId?: () => Promise<string>;
 }
-declare const ToolCardBuffering: React.FC<ToolCardBufferingProps>;
+interface UseFileUploadReturn {
+    attachments: UploadedFileInfo[];
+    readyFiles: FileAttachment[];
+    isUploading: boolean;
+    addFiles: (files: File[]) => void;
+    removeFile: (resourceId: string) => void;
+    clear: () => void;
+}
+/**
+ * JETP-040: Shared hook managing the two-step file upload lifecycle.
+ * 1. Upload files via adapter.uploadFiles() -> get resource IDs
+ * 2. Poll adapter.getUploadStatus() until all files are 'ready' or 'error'
+ */
+declare function useFileUpload(options: UseFileUploadOptions): UseFileUploadReturn;
+
+interface ContextPreload {
+    /** 上下文类型，例如 ``'file'``、``'selection'``、``'manual'``。 */
+    kind: string;
+    /** 资源路径（文件对话） */
+    refPath?: string;
+    /** 资源 ID（已落库的文件） */
+    refId?: string;
+    /** 选区哈希（选区对话） */
+    rangeHash?: string;
+    /** 任意附加元数据（被后端透传，不参与路由） */
+    meta?: Record<string, unknown>;
+}
+interface CreateClientOptions {
+    /** 客户端建议标题；后端会再做模型识别覆盖。 */
+    title?: string;
+    /** 初始上下文（不参与 client_id 派生，仅元数据）。 */
+    contextPreloads?: ContextPreload[];
+}
+interface CreateClientResponse {
+    id: string;
+    title: string;
+    context_preloads: ContextPreload[];
+    is_legacy: boolean;
+    archived: boolean;
+    last_active_at: number;
+}
+interface UseClientIdAllocatorReturn {
+    /**
+     * 创建新 client；返回后端分配的 v2 client_id。
+     * 双击防抖：相同 (sessionId, title, preloads) 内联 Promise 复用。
+     */
+    createClient: (sessionId: string | number, opts?: CreateClientOptions) => Promise<string>;
+    /**
+     * 兼容期：把一个 legacy client_id 导入到后端 v2 `clients` 表（best-effort，不抛错）。
+     */
+    ensureLegacy: (sessionId: string | number, legacyId: string) => Promise<void>;
+}
+/**
+ * 公开 HttpError，便于上层 ChatWidget 用 ``err instanceof HttpError`` +
+ * ``err.code === 'BUSINESS_ERROR'`` 区分网络错 vs 业务错（如 Session not allowed），
+ * 给出对症的 UI 提示。
+ */
+declare class HttpError extends Error {
+    status: number;
+    code: string | null;
+    constructor(status: number, code: string | null, message: string);
+}
+/**
+ * 创建一个 client allocator hook。
+ *
+ * @param apiBase 可选 API 基地址（如 ``'https://api.example.com'``）；缺省走同源相对路径。
+ * @param opts.adapter JETP-056：完整 ChatWidgetAdapter；优先级最高，走 useAuthedFetch
+ *   统一处理 Authorization / 401 → refreshAuth 重试 / onAuthFailure 通知。
+ * @param opts.getAuthHeaders JETP-054 hotfix（兼容期保留）：仅注入 JWT/Bearer 头。
+ *   adapter 未提供时使用；两者都未提供时退化为只走 cookie（向后兼容旧测试）。
+ */
+declare function useClientIdAllocator(apiBase?: string, opts?: {
+    adapter?: ChatWidgetAdapter | null;
+    getAuthHeaders?: () => Record<string, string>;
+}): UseClientIdAllocatorReturn;
+
+interface ClientItem {
+    id: string;
+    title: string;
+    contextPreloads: unknown[];
+    isLegacy: boolean;
+    archived: boolean;
+    lastActiveAt: number;
+}
+interface UseSessionClientsReturn {
+    items: ClientItem[];
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+    /** 局部更新（新建后乐观插入）；按 id 去重并置顶。 */
+    prependLocal: (it: ClientItem) => void;
+    /**
+     * 已成功拉到 ``items`` 的 sessionId（成功或失败均更新；失败时 ``items`` 保留旧值，但本字段仍前推
+     * → 上层可据此判断"对当前 sid 至少完成过一次拉取"，避免 React useEffect 闭包时序坑：
+     * 同 commit 内 hook 的 setLoading(true) 还没生效时，上层 useEffect 看到的是上一渲染的 false，
+     * 仅靠 ``loading`` 守门会被绕过 → 误判该 session 是空 session 而 POST 创建新 cid。
+     * 必须改用 ``loadedSessionId === currentSessionId`` 的正向断言。
+     */
+    loadedSessionId: string | number | null;
+}
+/**
+ * 业务错误：HTTP 200 但 jetagents ResponseModel.code !== 200 时由 refresh 抛出。
+ *
+ * 上层（如 ChatWidget init-effect）可以 ``err instanceof BusinessError`` 区分：
+ *   - 网络/服务故障（普通 Error） → 可重试
+ *   - 业务级拒绝（如 "Session not allowed"）→ 不应自动重试或自动建空 client
+ */
+declare class BusinessError extends Error {
+    code: number;
+    constructor(code: number, message: string);
+}
+/**
+ * @param sessionId 当前 session ID；为 `null` 时不发起请求。
+ * @param apiBase 可选 API 基地址（如 ``'https://api.example.com'``）；缺省走同源相对路径。
+ * @param opts.adapter JETP-056：完整 ChatWidgetAdapter；走 useAuthedFetch 统一鉴权。
+ * @param opts.getAuthHeaders JETP-054 hotfix（兼容期保留）：仅注入 JWT/Bearer 头。
+ */
+declare function useSessionClients(sessionId: string | number | null, apiBase?: string, opts?: {
+    adapter?: ChatWidgetAdapter | null;
+    getAuthHeaders?: () => Record<string, string>;
+}): UseSessionClientsReturn;
+
+interface UseSessionListOptions {
+    adapter: ChatWidgetAdapter | null | undefined;
+    /** 每页大小；默认 20。 */
+    pageSize?: number;
+    /** 周期重拉间隔（毫秒）；不传则不开启轮询。 */
+    pollMs?: number;
+    /**
+     * 外部触发重拉的版本号；任何递增即触发一次刷新。
+     * 用于把"会话发了第一条消息 / 接收到 SESSION_TITLE 通知"等外部事件
+     * 转译为列表刷新，无需调用方手工持有 ref。
+     */
+    refreshKey?: number;
+    /** 当前激活的会话 id；用于在删除时通知调用方"激活的那条没了"。 */
+    activeSessionId?: number;
+    /**
+     * 删除当前激活会话后的回调；典型用法是把 ChatWidget.sessionId 置 null
+     * 并触发新会话或显示空态。
+     */
+    onActiveSessionRemoved?: (id: number) => void;
+    /** Adapter 抛 401 时的钩子；通常对接 LoginPage / tokenStore.clear。 */
+    onAuthFailure?: () => void;
+    /** 通用错误回调；只在最近一次拉取失败时回调一次。 */
+    onError?: (err: unknown) => void;
+}
+interface UseSessionListReturn {
+    sessions: SessionListItem[];
+    loading: boolean;
+    page: number;
+    totalPages: number;
+    setPage: (page: number) => void;
+    refresh: () => void;
+    deleteSession: (id: number) => Promise<void>;
+    /** adapter 是否实现了 listSessions。 */
+    supported: boolean;
+    /** adapter 是否实现了 deleteSession。 */
+    canDelete: boolean;
+    /** 最近一次拉取/删除的错误对象；成功后清空。 */
+    error: unknown;
+}
+/**
+ * 通用会话列表 hook：负责拉取、分页、轮询、可见性恢复、删除与认证失败处理。
+ *
+ * 设计原则：
+ *   1. 不耦合 UI——只暴露状态与命令，便于宿主自行渲染（侧栏 / 抽屉 / 命令面板等）。
+ *   2. Adapter 能力可选——`supported / canDelete` 透传 adapter 是否实现对应方法，
+ *      让 UI 决定显示空态还是隐藏按钮。
+ *   3. 删除操作乐观更新——先从本地列表移除再触发后台请求；失败则强制重拉拉回真值。
+ */
+declare function useSessionList(options: UseSessionListOptions): UseSessionListReturn;
+
+interface NotificationConfig {
+    sound: boolean;
+    toast: boolean;
+    toastDuration: number;
+    badgeAnimation: boolean;
+}
+interface AttentionToast {
+    id: string;
+    text: string;
+    agentName?: string;
+    timestamp: number;
+}
+interface UseAttentionManagerOptions {
+    fileViewerOpen: boolean;
+    immersive: boolean;
+    config?: Partial<NotificationConfig>;
+}
+declare function useAttentionManager({ fileViewerOpen, immersive, config: configOverrides, }: UseAttentionManagerOptions): {
+    unreadCount: number;
+    toasts: AttentionToast[];
+    trackNewMessage: (agentName?: string, preview?: string) => void;
+    clearUnread: () => void;
+    dismissToast: (id: string) => void;
+    pauseToast: (id: string) => void;
+    resumeToast: (id: string) => void;
+    notificationConfig: NotificationConfig;
+};
+
+/**
+ * 置顶区域组件
+ * 显示当前置顶轮次的用户消息、任务计划和 Todo
+ */
+
+declare const PinnedArea: React__default.FC<PinnedAreaProps>;
+
+/**
+ * 轮次标题组件
+ * 在消息流中显示非置顶轮次的用户消息和计划
+ */
+
+declare const RoundHeader: React__default.FC<RoundHeaderProps>;
+
+interface RoundMessageListProps {
+    round: Round;
+    config: Required<ChatWidgetConfig>;
+    onArtifactClick?: (artifact: any) => void;
+    onHITLSubmit?: (response: HITLResponse) => Promise<void>;
+    renderToolResult?: (displayType: string, data: ToolCallData) => React__default.ReactNode | null;
+    observedInstanceStates?: Map<number, PoolAgent>;
+}
+declare const RoundMessageList: React__default.FC<RoundMessageListProps>;
+
+/**
+ * RoundsView ── ChatWidget 主对话流的可复用渲染组件
+ *
+ * 设计目标：
+ *   把 ChatWidget.tsx 里 `localRounds.map(...)` + RoundHeader + RoundMessageList
+ *   的内联 markup 抽成单一组件，让：
+ *     1. ChatWidget 内部两处（overlay / immersive 主区）共享同一份渲染逻辑；
+ *     2. 外部消费者（如 yumiai-web 工作空间浮窗）能直接 import SDK 主流的"对话气泡 +
+ *        子 agent 卡 + 工具卡 + plan / todo 头"完整一套，而不再自造样式。
+ *
+ * 不变量：
+ *   - 不依赖 ChatWidget 上下文，只接受 props（rounds + config + 可选 callback）。
+ *   - 调用方需保证某个祖先节点带 `.ycw` 主题 class（color/spacing token 的来源）。
+ *   - 只渲染 round 列表本身，不负责 header / sidebar / composer / 加载状态等。
+ *     scroll 容器、自动滚动到底部、上拉分页等也由调用方决定（保持组件原子）。
+ *
+ * 与 ChatWidget 主流的等价性：
+ *   markup 与 ChatWidget.tsx#1457-1474 / #1700-1722 完全一致：
+ *     <div class="ycw-message-list-container">
+ *       <div class="ycw-message-list">
+ *         {rounds.map(round => (
+ *           <Fragment>
+ *             {index > 0 && <div class="ycw-round-separator">…</div>}
+ *             <div class="ycw-round-container">
+ *               <RoundHeader … todoMap={todoMap} />
+ *               <RoundMessageList … observedInstanceStates={…} />
+ *             </div>
+ *           </Fragment>
+ *         ))}
+ *       </div>
+ *     </div>
+ */
+
+interface RoundsViewProps {
+    /** 待渲染的轮次列表（顺序 = 时间正序）。 */
+    rounds: Round[];
+    /** ChatWidget 配置；不传则用 DEFAULT_CONFIG。 */
+    config?: ChatWidgetConfig;
+    /** controller.todoMap，传入则 RoundHeader 会显示 todo 进度。 */
+    todoMap?: Map<string, TodoData>;
+    /** controller.poolObservation.instanceStates，子 Agent 卡用它判断 running/ended。 */
+    observedInstanceStates?: Map<number, PoolAgent>;
+    /** Artifact 点击回调（chip 等位置打开预览时使用）。 */
+    onArtifactClick?: (artifact: Artifact) => void;
+    /** HITL 表单提交回调。 */
+    onHITLSubmit?: (response: HITLResponse) => Promise<void>;
+    /** 自定义 tool 渲染。 */
+    renderToolResult?: (displayType: string, data: ToolCallData) => React__default.ReactNode | null;
+    /** 空态自定义；不传则不渲染任何东西（让外层贴自己的空态）。 */
+    emptyFallback?: React__default.ReactNode;
+    /** 容器自定义 className（追加在 .ycw-message-list-container 上）。 */
+    className?: string;
+    /** 测试钩子。 */
+    testId?: string;
+}
+/**
+ * RoundsView ──「per-round Header + RoundMessageList」批量渲染。
+ *
+ * 注意：本组件只负责渲染当前传入的 rounds，**不做过滤 / 排序 / 去重**。
+ * 调用方（如 ChatWidget per-cid 视图、yumiai-web 浮窗）自己根据
+ * cid / sid / scope 把 controller.rounds 切片后再传进来。
+ */
+declare const RoundsView: React__default.FC<RoundsViewProps>;
+
+declare const MessageContent: React__default.FC<MessageContentProps>;
+
+/**
+ * 子 Agent 卡片组件
+ * 可折叠，固定高度，内部滚动
+ */
+
+declare const ChildAgentCard: React__default.FC<ChildAgentCardProps & {
+    onArtifactClick?: (artifact: Artifact) => void;
+}>;
+
+/**
+ * 任务计划卡片组件
+ */
+
+declare const PlanCard: React__default.FC<PlanCardProps>;
+
+declare const TodoCard: React__default.FC<TodoCardProps>;
+
+interface SchemaNode {
+    type: string;
+    key?: string;
+    name?: string;
+    props?: Record<string, unknown>;
+    children?: SchemaNode[];
+    options?: Array<{
+        label: string;
+        value: string;
+    }>;
+    rules?: Array<{
+        required?: boolean;
+        message?: string;
+    }>;
+    schema?: SchemaNode;
+}
+
+interface SchemaFormRendererProps {
+    schema: SchemaNode;
+    onSubmit?: (values: Record<string, unknown>) => void | Promise<void>;
+    awaitCommandUuid?: string;
+}
+declare const SchemaFormRenderer: React__default.FC<SchemaFormRendererProps>;
+
+interface ToolCardBufferingProps {
+    message: AggregatedMessage;
+    observedInstanceStates?: Map<number, PoolAgent>;
+}
+declare const ToolCardBuffering: React__default.FC<ToolCardBufferingProps>;
+
+interface PdfImageSelection {
+    page: number;
+    imageIndex: number;
+    imageSrc: string;
+    rect: DOMRect;
+}
+
+interface GerberLayerSelectPayload {
+    snippet: string;
+    anchorRect: {
+        top: number;
+        left: number;
+    } | null;
+}
+
+type KicanvasJpTheme = 'jp-light' | 'jp-dark' | 'jp-midnight' | 'jp-neu';
+interface KicadFile {
+    name: string;
+    content?: string;
+    url?: string;
+}
+
+/**
+ * Type contract for the multi-file HTML project viewer.
+ *
+ * Spec: docs/proposals/CWRF-011-html-project-viewer/00_protocol/01_html_file_contract.md
+ *
+ * Invariants enforced by `useHtmlProject`:
+ *   - `HtmlFile.name` is a normalized POSIX path relative to the project root
+ *     (no leading `/`, no `..` segments, no backslashes).
+ *   - At least one of `content` / `url` is present.
+ */
+/**
+ * One file inside an HTML project.
+ *
+ * Selection rules:
+ *   - Text resources (HTML/CSS/JS/JSON/SVG) ship as `content` (UTF-8).
+ *   - Binary resources (images/fonts/audio/video) ship as `url`
+ *     (already a `https:` presigned URL or a `blob:` URL).
+ *   - When both are present, `url` wins (saves memory in Blob strategy).
+ */
+interface HtmlFile {
+    /** Normalized POSIX path relative to the project root (e.g. `"index.html"`, `"css/layout.css"`). */
+    name: string;
+    /** UTF-8 text content. Required when `url` is missing. */
+    content?: string;
+    /** Presigned or blob URL. Required when `content` is missing. */
+    url?: string;
+    /** MIME type used to construct the right Blob. Defaults to extension lookup if absent. */
+    mime?: string;
+}
+/**
+ * Strategy used to render the HTML project inside the iframe.
+ *
+ * - `'auto'`: pick `'inline'` or `'blob'` from `detectHtmlProjectFeatures`.
+ *   ESM `import` / dynamic `import()` / `fetch('./...')` → `'blob'`; otherwise `'inline'`.
+ * - `'inline'`: force inline; `sandbox="allow-scripts"`.
+ * - `'blob'`: force blob; `sandbox="allow-scripts allow-same-origin"`.
+ */
+type HtmlProjectStrategy = 'auto' | 'inline' | 'blob';
+/**
+ * State machine reported via `HtmlProjectOptions.onStateChange`.
+ */
+type HtmlViewerState = {
+    kind: 'idle';
+} | {
+    kind: 'loading';
+} | {
+    kind: 'rendering';
+    strategy: 'inline' | 'blob';
+    entryName: string;
+} | {
+    kind: 'fallback-single';
+    reason: string;
+} | {
+    kind: 'error';
+    message: string;
+};
+/**
+ * Caller-controlled options that opt the viewer into multi-file project mode.
+ *
+ * When omitted (or when `files` is empty) the viewer falls back to the
+ * legacy single-file `srcDoc` rendering path, preserving prior behaviour.
+ */
+interface HtmlProjectOptions {
+    /** Project file tree. The entry HTML may or may not be present here; when absent it is provided by `content`. */
+    files?: HtmlFile[];
+    /** Entry file name (relative to project root). Defaults to `basename(props.fileName ?? 'index.html')`. */
+    entryName?: string;
+    /** True while the host is still discovering project files; viewer shows loading state and skips strategy selection. */
+    projectLoading?: boolean;
+    /** Render strategy. Defaults to `'auto'`. */
+    strategy?: HtmlProjectStrategy;
+    /** Project byte budget. Above this the viewer warns and falls back to single-file. Default: 16 MiB. */
+    maxBytes?: number;
+    /** Per-file inline budget. Larger text files are routed through Blob URLs even in inline mode (mixed mode). Default: 256 KiB. */
+    inlineFileMaxBytes?: number;
+    /** Notification of state machine transitions, useful for surfacing loading / strategy badges in the host UI. */
+    onStateChange?: (state: HtmlViewerState) => void;
+    /**
+     * Enable the runtime ESM/asset resolver shim (CWRF-012) for blob
+     * strategy. When `true` (default), runtime-evaluated imports such as
+     * `` import(`../games/${name}`) ``, `fetch('./data.json')`,
+     * `new Worker('./w.js')`, and `new URL(rel, import.meta.url)` are
+     * routed through `window.__YCW_RESOLVE__` so they resolve to the
+     * matching blob URL at call time.
+     *
+     * Set to `false` to opt out and restore the strict CWRF-011 behaviour
+     * (only literal specifiers are rewritten; runtime forms throw).
+     */
+    runtimeShim?: boolean;
+}
+
+/**
+ * `HtmlViewer` is the entry dispatcher for the multi-file HTML project viewer.
+ *
+ * Spec: docs/proposals/CWRF-011-html-project-viewer/05_integration/01_html_viewer_dispatch.md
+ *
+ * Responsibilities:
+ *   - Decide between three rendering paths based on `htmlOptions`:
+ *       1. Single-file fallback (`htmlOptions` absent / `files` empty)
+ *          → behaviour identical to the legacy `HtmlViewer.tsx`.
+ *       2. Loading placeholder (`htmlOptions.projectLoading === true`)
+ *          → display loading text, no iframe yet.
+ *       3. Project mode (`files` present) → run `chooseStrategy` and
+ *          render `<InlineRenderer>` or `<BlobRenderer>` accordingly.
+ *   - Wire selection / link / xref postMessage bridge for *all* paths so
+ *     consumer callbacks behave identically regardless of strategy.
+ *   - Emit `htmlOptions.onStateChange` transitions so the host UI can
+ *     surface a strategy badge / fallback warning.
+ *   - Hard-cap project size via `htmlOptions.maxBytes` (default 16 MiB).
+ *
+ * Re-export shim: `viewers/HtmlViewer.tsx` exposes this default to keep
+ * external `import HtmlViewer from '@yumiai/chat-widget/.../HtmlViewer'`
+ * paths intact (AC-HTMLP-096).
+ */
+interface HtmlViewerSelectionState {
+    text: string;
+    rect: DOMRect;
+}
+
+interface FileViewerKicadOptions {
+    /** 覆盖默认 KiCanvas 脚本 URL（也可用构建时 VITE_KICANVAS_SCRIPT_URL） */
+    kicanvasScriptUrl?: string;
+    onKicadCanvasSelection?: (payload: KicadCanvasSelectionPayload) => void;
+    /** Sync kicanvas UI chrome + canvas background with chat-widget theme */
+    kicanvasTheme?: KicanvasJpTheme;
+    /** Controlled view mode for external toggle */
+    view?: 'canvas' | 'source';
+    onViewChange?: (v: 'canvas' | 'source') => void;
+    /** Multi-file project files (CWRF-009) */
+    files?: KicadFile[];
+    /** True while project files are still being discovered */
+    projectLoading?: boolean;
+}
+interface FileViewerGerberOptions {
+    onGerberSelection?: (payload: GerberLayerSelectPayload) => void;
+}
+interface FileViewerPdfOptions {
+    onImageSelect?: (sel: PdfImageSelection | null) => void;
+}
+interface FileViewerProps {
+    content: ResourceContent;
+    onXrefClick?: (xref: XrefRecord) => void;
+    onLinkClick?: (url: string) => void;
+    onHtmlSelectionChange?: (selection: HtmlViewerSelectionState | null) => void;
+    className?: string;
+    kicadOptions?: FileViewerKicadOptions;
+    gerberOptions?: FileViewerGerberOptions;
+    pdfOptions?: FileViewerPdfOptions;
+    /** CWRF-011: passthrough for multi-file HTML project options. */
+    htmlOptions?: HtmlProjectOptions;
+}
+declare const FileViewer: React__default.FC<FileViewerProps>;
+
+interface FileViewerModalProps {
+    open: boolean;
+    onClose: () => void;
+    initialResource: ResourceContent | null;
+    initialArtifact?: Artifact | null;
+    loading?: boolean;
+    error?: string | null;
+    adapter?: ChatWidgetAdapter;
+    sessionId?: number | null;
+}
+declare const FileViewerModal: React__default.FC<FileViewerModalProps>;
+
+interface FileViewerPanelProps {
+    initialResource: ResourceContent | null;
+    initialArtifact?: Artifact | null;
+    loading?: boolean;
+    error?: string | null;
+    adapter?: ChatWidgetAdapter;
+    sessionId?: number | null;
+    onReference?: (ref: FileReference) => void;
+    onSelectionAsk?: (ref: FileReference) => void;
+    onBeforeCopy?: (ref: FileReference) => void;
+    onClose?: () => void;
+    onFullscreen?: () => void;
+    kicanvasScriptUrl?: string;
+    kicanvasTheme?: KicanvasJpTheme;
+}
+declare const FileViewerPanel: React__default.FC<FileViewerPanelProps>;
+
+declare function getFileCategory(ext: string, mimeType: string | null): FileCategory$1;
+declare function getExtension(fileName: string | undefined | null): string;
+declare function inferLanguage(ext: string): string;
+
+/**
+ * Convert ResourceContent to a renderable source URL.
+ * Priority: content_url > data URI (small binary) > Blob URL (large binary) > raw text.
+ */
+declare function contentToSrc(res: ResourceContent): string;
+declare function formatFileSize(bytes: number): string;
+
+declare function parseXrefs(content: string): XrefRecord[];
+
+interface LinkCardProps {
+    xref: XrefRecord;
+    className?: string;
+}
+declare const LinkCard: React__default.FC<LinkCardProps>;
+
+interface ResourceChipProps {
+    xref: XrefRecord;
+    meta?: XrefMeta;
+    onClick?: () => void;
+    className?: string;
+}
+declare const ResourceChip: React__default.FC<ResourceChipProps>;
+
+interface HoverPreviewProps {
+    fileName: string;
+    mimeType?: string | null;
+    previewText?: string;
+    rect: DOMRect | null;
+    visible: boolean;
+}
+declare const HoverPreview: React__default.FC<HoverPreviewProps>;
+
+interface UseHoverPreviewOptions {
+    containerRef: React__default.RefObject<HTMLElement | null>;
+    onHover?: (artifactId: string) => void;
+    delay?: number;
+}
+declare function useHoverPreview({ containerRef, onHover, delay, }: UseHoverPreviewOptions): {
+    previewVisible: boolean;
+    previewFileName: string;
+    previewMimeType: string | undefined;
+    previewRect: DOMRect | null;
+    dismissPreview: () => void;
+};
+
+interface SelectionData {
+    text: string;
+    startLine?: number;
+    endLine?: number;
+    sectionId?: string;
+    jsonPath?: string;
+    timestamp?: number;
+    componentRef?: string;
+}
+interface SnapshotData {
+    dataUrl: string;
+    width: number;
+    height: number;
+    label?: string;
+}
+interface ViewerInteractionAdapter {
+    canSelectText: boolean;
+    canSelectRegion: boolean;
+    canCaptureSnapshot: boolean;
+    canReferenceByLine: boolean;
+    canReferenceBySection: boolean;
+    canReferenceByPath: boolean;
+    canReferenceByTimestamp: boolean;
+    canReferenceByComponent: boolean;
+    minPanelWidth: number;
+    preferredRatio: number;
+    getSelection(): SelectionData | null;
+    createSnapshot?(): SnapshotData;
+    createReference(selection: SelectionData): FileReference;
+}
+declare const VIEWER_CAPABILITIES: Record<string, Partial<ViewerInteractionAdapter>>;
+declare function getViewerCapabilities(category: string): Partial<ViewerInteractionAdapter>;
+
+interface SplitPanelProps {
+    open: boolean;
+    position?: 'left' | 'right';
+    defaultRatio?: number;
+    minPrimaryWidth?: number;
+    minSecondaryWidth?: number;
+    onClose: () => void;
+    children: React__default.ReactNode;
+    primaryContent: React__default.ReactNode;
+    immersive?: boolean;
+    onImmersiveChange?: (immersive: boolean) => void;
+    unreadCount?: number;
+    onChatFocus?: () => void;
+    references?: FileReference[];
+    onImmersiveSend?: (text: string) => void;
+    onRemoveReference?: (index: number) => void;
+    toasts?: AttentionToast[];
+    onDismissToast?: (id: string) => void;
+    onPauseToast?: (id: string) => void;
+    onResumeToast?: (id: string) => void;
+    tabs?: ViewerTab[];
+    activeTabId?: string | null;
+    onTabSwitch?: (tabId: string) => void;
+    onTabClose?: (tabId: string) => void;
+    onRailHome?: () => void;
+    onRailWorkspace?: () => void;
+    onRailAnnotation?: () => void;
+    annotationCount?: number;
+    activeOverlay?: 'home' | 'workspace' | 'discussion' | 'annotation' | null;
+    overlayContent?: React__default.ReactNode;
+    fabContent?: React__default.ReactNode;
+    contextLabel?: string;
+    /** v2: Channel sidebar (replaces rail when provided) */
+    sidebarContent?: React__default.ReactNode;
+    /** v2: Floating conversation windows layer */
+    floatingLayerContent?: React__default.ReactNode;
+}
+declare const SplitPanel: React__default.FC<SplitPanelProps>;
+
+interface AttentionToastListProps {
+    toasts: AttentionToast[];
+    onDismiss: (id: string) => void;
+    onPause?: (id: string) => void;
+    onResume?: (id: string) => void;
+    onClick?: () => void;
+}
+declare const AttentionToastList: React__default.FC<AttentionToastListProps>;
+
+interface SelectionState {
+    text: string;
+    rect: DOMRect;
+    startLine?: number;
+    endLine?: number;
+    /** PDF page number (1-based) from data-page attribute */
+    page?: number;
+    endPage?: number;
+}
+interface SelectionBridgeOptions {
+    containerRef: React.RefObject<HTMLElement | null>;
+    resourceContext: {
+        resourceId: string;
+        sessionId: number;
+        fileName: string;
+        mimeType?: string | null;
+        specId?: string;
+    };
+    enabled?: boolean;
+}
+declare function useSelectionBridge({ containerRef, resourceContext, enabled, }: SelectionBridgeOptions): {
+    selection: SelectionState | null;
+    buildReference: () => FileReference;
+    clearSelection: () => void;
+};
+
+interface FloatingToolbarProps {
+    selection: SelectionState | null;
+    onAsk: () => void;
+    onCopy?: () => void;
+    anchorRef: React__default.RefObject<HTMLElement | null>;
+}
+declare const FloatingToolbar: React__default.FC<FloatingToolbarProps>;
+
+interface ContextChipProps {
+    reference: FileReference;
+    onRemove?: () => void;
+}
+declare const ContextChip: React__default.FC<ContextChipProps>;
+
+interface FloatingInputProps {
+    visible: boolean;
+    references: FileReference[];
+    onSend: (text: string) => void;
+    onRemoveReference: (index: number) => void;
+    onClose: () => void;
+    placeholder?: string;
+    contextLabel?: string;
+}
+declare const FloatingInput: React__default.FC<FloatingInputProps>;
+
+interface SmartPasteOptions {
+    enabled: boolean;
+    onReference: (ref: FileReference) => void;
+}
+declare function useSmartPaste({ enabled, onReference }: SmartPasteOptions): void;
+
+interface RichInputHandle {
+    insertChip: (ref: FileReference) => void;
+    insertSkillChip: (skill: SkillSummary) => void;
+    focus: () => void;
+    clear: () => void;
+    getText: () => string;
+    getReferences: () => FileReference[];
+    getSkills: () => SkillSummary[];
+}
+interface RichInputProps {
+    placeholder?: string;
+    disabled?: boolean;
+    onSubmit?: (text: string, references: FileReference[], skills: SkillSummary[]) => void;
+    onChipRemove?: (ref: FileReference) => void;
+    onSkillChipRemove?: (skill: SkillSummary) => void;
+    onSlashTrigger?: (prefix: string) => void;
+    onSlashDismiss?: () => void;
+    removeAriaLabel?: string;
+    skillRemoveAriaLabel?: string;
+    className?: string;
+    /** JETP-040: Callback when user selects local files for upload */
+    onFilesSelected?: (files: File[]) => void;
+    /** JETP-040: Currently attached/uploading files */
+    attachments?: UploadedFileInfo[];
+    /** JETP-040: Remove an uploaded file attachment */
+    onRemoveAttachment?: (resourceId: string) => void;
+    /** JETP-040: Whether file upload is supported (controls attach button visibility) */
+    enableFileUpload?: boolean;
+    /** JETP-040: True while files are still uploading/processing — blocks send */
+    isUploading?: boolean;
+    /**
+     * 插在附件按钮（+）左侧的控件，例如 Agent 选择器。
+     * 与 ``enableFileUpload`` 独立，保证顺序为：leading → 附件 → 输入区。
+     */
+    leadingControls?: React__default.ReactNode;
+    /**
+     * 用于 ``getText()`` 序列化 skill chip 时的包裹模板。
+     * 模板中的 ``{{name}}`` 会被替换为 ``{{SKILL:<displayName>}}`` 占位符，
+     * 这样前端 ``parseUserMessage`` 仍能识别 chip 位置，
+     * 同时上行 message text 自带模板前后缀（用户气泡 + 后端 prompt 同步）。
+     * 不传则退化为只输出裸 ``{{SKILL:<displayName>}}``。
+     */
+    skillTextTemplate?: string;
+}
+declare const RichInput: React__default.ForwardRefExoticComponent<RichInputProps & React__default.RefAttributes<RichInputHandle>>;
+
+/**
+ * Model 注册表 / 持久化 helpers
+ * --------------------------------------------------
+ * 仅负责 "AUTO sentinel + 持久化 + 校验 + basename 归一化"，
+ * 真正的列表数据由 ``useModels`` hook 从 adapter 拉。
+ *
+ * 持久化语义（**per-agent**，key = ``chat_widget_last_model_name:${agentId}``）：
+ *   · 空 / null      → AUTO（跟随该 agent 注册的默认模型，不传 ``modelOverride``）
+ *   · 非空字符串      → 该 agent 下用户上次选择的 model name；进入 composer 时若该 name
+ *                       仍在清单内 → 复用，否则降级回 AUTO（不弹错，避免运维下线 model
+ *                       反向骚扰用户）
+ *
+ * 为什么按 agent 分桶（v2）：
+ *   v1 用了一个全局 key，问题是切 agent 时残留上一个 agent 的选择，
+ *   ModelPicker 的"value != null → 显示用户选择"分支永远比"value == null →
+ *   定位 agent 默认"分支优先，结果切 agent 完全看不到新 agent 的默认 model。
+ *   按 agent 存储后，切到没选过的 agent → value=null → picker 自动定位 agent 默认；
+ *   切回选过的 agent → value 复原 → picker 显示用户上次的选择。
+ */
+/** AUTO 的字面量 sentinel；null 也等价 AUTO，但显式常量更便于代码对比。 */
+declare const MODEL_AUTO: null;
+type ModelChoice = string | null;
+/**
+ * 把 model_name 归一为 "物理模型 basename"，**必须与 hip-server
+ * ``internal/remote/modellake/service.go::modelBasename`` 保持等价**。
+ *
+ * 规则：
+ *   1. 把 ``__`` 视作 ``/``（model-lake 入库时 openrouter 渠道做的反规范化）；
+ *   2. 取归一化后最末段（``/`` 之后的部分）。
+ *
+ * 示例：
+ *   ``anthropic/claude-opus-4-6``       → ``claude-opus-4-6``  ← agent 配里的写法
+ *   ``anthropic__claude-opus-4-6``      → ``claude-opus-4-6``  ← model-lake openrouter 渠道
+ *   ``claude-opus-4-6``                 → ``claude-opus-4-6``  ← model-lake 直连 anthropic
+ *   ``qwen__qwen3-max``                 → ``qwen3-max``
+ *   ``gpt-5-mini``                      → ``gpt-5-mini``
+ *
+ * 用途：让 ModelPicker 能把 jetagents 那侧的 ``vendor/model`` 命名跟
+ * model-lake 列表里的各种渠道命名对齐，否则 agent 默认模型永远命中不了清单。
+ *
+ * 不能替代真正发后端的 ``ModelOverride.name`` —— 那是用户在 picker 里点中的
+ * variant.name 原值，basename 仅作 UI 标签 / 反查 key。
+ */
+declare function modelBasename(name: string): string;
+declare function isShowModelChannels(): boolean;
+/**
+ * 读取该 agent 上次选择的 model name；返回 ``null`` 表示 AUTO（无 override）。
+ *  · 不做"是否仍在清单内"的校验 —— 那是 ``useModels`` 拉到清单后才能判定，
+ *    在这一层强校验会把"网络挂了但用户希望恢复"的可恢复链路一并切断。
+ *  · ``agentId`` 为空时直接返回 AUTO，避免拼出 "chat_widget_last_model_name:" 这样的脏 key。
+ *  · 新 key 未命中时尝试旧 key（yumiai_*），命中则视为继承（不主动迁移写入，
+ *    交给下次 saveLastModelName 顺手落到新 key）。
+ */
+declare function loadLastModelName(agentId: string): ModelChoice;
+/**
+ * 写入该 agent 当前选择。``null`` / 空串 → 删除 key（恢复 AUTO）。
+ * 静默失败（隐私模式 / 配额满都不应让 UI 崩）。
+ *
+ * **副作用**：第一次写入新 key 时顺便清掉旧的 v1 全局 key 与 yumiai 旧前缀 key，
+ * 避免不同浏览器下用户看到不同行为。幂等，重复执行无副作用。
+ */
+declare function saveLastModelName(agentId: string, name: ModelChoice): void;
+
+interface ModelPickerProps {
+    /** 当前选择；null = AUTO（跟随 agent 默认） */
+    value: ModelChoice;
+    onChange: (next: ModelChoice) => void;
+    adapter: ChatWidgetAdapter;
+    disabled?: boolean;
+    compact?: boolean;
+    /**
+     * 当前 agent 在后端注册的默认模型 ``name`` —— **仅用于 picker 展示态**。
+     *
+     * 行为分两条线，必须分清：
+     *   · **展示态**：``value == null`` 且本字段命中清单时，trigger 文案 + AUTO 行 hint
+     *     都自动定位到该模型，让用户一眼看到"当前 agent 实际会用哪个 model"。
+     *   · **发送态**：``value == null`` 时**永远**不带 ``modelOverride``，由后端按 agent 默认走。
+     *
+     * null / undefined / 没命中清单 → picker 退化为"显示『默认模型』占位"。
+     */
+    agentDefaultModelName?: string | null;
+    /**
+     * 是否允许触发 listModels 请求。默认 true。
+     * 游客态（未登录）使用：传 false → 内部 useModels enabled=false 不发请求，
+     * 同时 trigger 走 inert 分支，hover 提示"登录后可选模型"。
+     */
+    enabled?: boolean;
+}
+declare function ModelPicker({ value, onChange, adapter, disabled, compact, agentDefaultModelName, enabled, }: ModelPickerProps): react_jsx_runtime.JSX.Element;
+
+interface UseModelsResult {
+    items: ModelListItemBasenameGrouped[];
+    loading: boolean;
+    /** null = 没出过错 */
+    error: string | null;
+    /** 手动强制重拉（如登录态切换、tenant 切换） */
+    refresh: () => void;
+}
+interface UseModelsOptions {
+    /**
+     * 是否允许触发 listModels 请求。默认 true（保持向后兼容）。
+     *
+     * 主要使用场景：游客态 marketing hero。访客没有 access_token，
+     * 调 hip `GET /api/v1/models` 必然 401。把 enabled 显式设为 false → 完全跳过请求，
+     * UI 自然走 inert 占位。
+     */
+    enabled?: boolean;
+}
+declare function useModels(adapter: ChatWidgetAdapter, options?: UseModelsOptions): UseModelsResult;
+
+interface AgentDefaultModelInfo {
+    name: string;
+    displayName?: string;
+    version?: string;
+}
+interface UseAgentDefaultModelResult {
+    /** null = 没查到 / 还没拉 / adapter 不支持 / 拉失败（任何一种） */
+    info: AgentDefaultModelInfo | null;
+    loading: boolean;
+}
+interface UseAgentDefaultModelOptions {
+    /**
+     * 是否允许触发后端请求。默认 true（保持向后兼容）。
+     *
+     * 主要使用场景：游客态。访客没有 access_token，调 hip 必然 401；
+     * 把 enabled 显式设为 false 完全跳过请求。
+     *
+     * enabled === false 时：内部强制 setInfo(null) + loading 不动，行为等价于 agentId 为空。
+     */
+    enabled?: boolean;
+}
+declare function useAgentDefaultModel(adapter: ChatWidgetAdapter, agentId: string | undefined, options?: UseAgentDefaultModelOptions): UseAgentDefaultModelResult;
+
+/**
+ * DefaultComposer — SDK 默认的对话输入组件。
+ *
+ * 把 RichInput + SkillSelector + useSkillOrchestration + 文件上传 + InteractionContext
+ * 拼装成开箱即用的 footer composer。宿主只需要：
+ *
+ *   <ChatWidget
+ *     ...
+ *     renderFooter={(api) => <DefaultComposer api={api} adapter={adapter} agentId={agentId} />}
+ *   />
+ *
+ * 之前 demo 端通过 deep import 内部模块自己拼装，现已收回为 SDK 公共组件，
+ * 同时保留 deep import 路径不破坏既有调用方。
+ */
+
+interface DefaultComposerProps {
+    /** ChatWidget 通过 onReady 暴露的 API；DefaultComposer 内部据此发消息、订阅文件上传状态。 */
+    api: ChatWidgetAPI | null;
+    /** 当前生效的 adapter，传给 useSkillOrchestration 拉取技能列表。 */
+    adapter: ChatWidgetAdapter | null;
+    /**
+     * 当用户提交时使用的 agentId。如果业务允许动态切换，请用 controlled props 在外层维护并传入。
+     * 不传则不带 agentId（让 SDK 走默认）。
+     */
+    agentId?: string;
+    /**
+     * 在输入行最前（「+」附件左侧）展示 Agent 下拉；与 ``agentId`` / ``onAgentIdChange`` 搭配使用。
+     * 不传或空数组则不展示。
+     */
+    agentSelectOptions?: readonly {
+        value: string;
+        label: string;
+    }[];
+    /** Agent 下拉变更时回调；提供 ``agentSelectOptions`` 时应传入以便受控更新。 */
+    onAgentIdChange?: (agentId: string) => void;
+    /**
+     * 是否处于忙碌态（running / compressing），决定 placeholder 与按钮是否可发送。
+     * 通常由宿主从 ``onStatusChange`` 同步过来。
+     */
+    loading?: boolean;
+    /** 完全禁用输入。 */
+    disabled?: boolean;
+    /**
+     * 自定义提交 hook：返回 false 表示拦截发送（业务可在此做敏感词或字数校验等）。
+     * 不传则直接调用 ``api.sendMessage``。
+     */
+    onBeforeSend?: (text: string, skills: SelectedSkillRef[]) => boolean | void;
+    /** 发送按钮文案；默认 'Send' / 加载中 '…'。 */
+    sendLabel?: React__default.ReactNode;
+    /** 自定义 className，便于宿主套主题。 */
+    className?: string;
+    /**
+     * 是否启用 ModelPicker —— 在 agent 下拉旁边渲染一个"本次发送使用的模型"切换器。
+     *
+     * 三态：
+     *   · ``true``：始终渲染（adapter 不支持 ``listModels`` 时 ModelPicker 自身会降级到 inert 占位）；
+     *   · ``false`` / 缺省：完全不渲染（向后兼容，老调用方零侵入）；
+     *   · ``'auto'``：``adapter.listModels`` 为函数时渲染，否则不渲染。
+     *
+     * 数据&发送链路：
+     *   · 用 ``adapter.listModels({ groupBy:'basename' })`` 拉清单；
+     *   · 用 ``adapter.getAgentDefaultModel(agentId)`` 做"agent 默认"展示态定位；
+     *   · 用户选定后调 ``api.sendMessage(... , modelOverride={ name })``，
+     *     由 adapter buildStreamBody 写入 body.model_override。
+     *
+     * 受控/非受控：见 ``modelValue`` / ``onModelChange``。
+     */
+    enableModelPicker?: boolean | 'auto';
+    /**
+     * 受控 modelChoice。``null`` = AUTO（不传 modelOverride，跟随 agent 默认）。
+     * 不传时 DefaultComposer 走非受控模式，内部用 useState 管理，并按 ``agentId``
+     * 持久化到 ``localStorage`` (``chat_widget_last_model_name:<agentId>``)。
+     */
+    modelValue?: ModelChoice;
+    onModelChange?: (next: ModelChoice) => void;
+    /**
+     * 是否查询 ``adapter.getAgentDefaultModel`` 用于 ModelPicker 展示态定位。
+     * 默认 true；游客态宿主可置 false 完全跳过请求。
+     */
+    enableAgentDefaultModelLookup?: boolean;
+}
+declare const DefaultComposer: React__default.FC<DefaultComposerProps>;
+
+interface SessionListPanelProps {
+    adapter: ChatWidgetAdapter | null | undefined;
+    /** 当前激活会话；用于高亮 + 删除时的"激活态消失"判定。 */
+    activeSessionId?: number;
+    /** 选中某条会话的回调。 */
+    onSelectSession: (id: number) => void;
+    /** 点击"新建会话"按钮的回调；不传则不显示该按钮。 */
+    onNewSession?: () => void;
+    /** 点击"退出"按钮的回调；不传则不显示该按钮。 */
+    onLogout?: () => void;
+    /** 删除当前激活会话后的回调（典型用法是 setSessionId(undefined)）。 */
+    onActiveSessionRemoved?: (id: number) => void;
+    /** 401 钩子；缺省时由调用方在 adapter.onAuthFailure 里处理。 */
+    onAuthFailure?: () => void;
+    /** 外部触发刷新的版本号；任何递增即重拉。 */
+    refreshKey?: number;
+    /** 周期重拉间隔；不传不轮询。 */
+    pollMs?: number;
+    /** 每页大小；默认 20。 */
+    pageSize?: number;
+    /** 自定义标题；默认走 i18n。 */
+    title?: React__default.ReactNode;
+    /** 删除前确认；返回 false 中止。默认走 window.confirm。 */
+    confirmDelete?: (item: SessionListItem) => boolean | Promise<boolean>;
+    /** 自定义条目渲染（保留 onClick / 删除按钮包裹由组件负责）。 */
+    renderItemTitle?: (item: SessionListItem) => React__default.ReactNode;
+    className?: string;
+}
+/**
+ * 通用会话侧栏。可直接挂载，也可作为参考实现：复杂场景下推荐
+ * 调用方自己用 `useSessionList` + 自有 UI 拼装。
+ */
+declare const SessionListPanel: React__default.FC<SessionListPanelProps>;
 
 interface DefaultJetAgentsAdapterOptions {
     baseUrl: string;
     getToken: () => string | null;
     refreshToken?: () => Promise<string | null>;
     getOrgId?: () => string | null;
+    getUserId?: () => string | null;
+    hipBaseUrl?: string;
     onAuthFailure?: () => void;
+    /**
+     * 可选：每次请求前由上层动态返回额外 header。
+     *
+     * 设计目的：让宿主应用（例如 yumiai-web）把 i18n locale、tenant、feature flag 等
+     * 横切关注点统一注入到 adapter 的所有 HTTP 出口（fetchJSON / fetchHipJSON /
+     * fetchMultipart / SSE startStream），而无需修改 adapter 内部任何端点。
+     *
+     * 调用时机：每次构造请求 headers 时同步调用一次（在 `getAuthHeaders()` 中合并），
+     * 因此实现侧可以读取最新的可变状态（如 currentLocale）而不需要重建 adapter。
+     *
+     * 优先级：同名 key 时，本钩子返回值会被 `getAuthHeaders()` 内已设置的鉴权字段覆盖
+     * （Authorization / X-User-ID / X-User-Roles / X-Org-Id），但会高于 caller 在
+     * fetchJSON(init.headers) 里传入的同名字段（caller 仍可通过显式传 header 覆盖）。
+     *
+     * 典型用法：
+     * ```ts
+     * new DefaultJetAgentsAdapter({
+     *   ...,
+     *   getExtraHeaders: () => ({
+     *     'Accept-Language': getCurrentLocale(),
+     *     'X-Locale': getCurrentLocale(),
+     *   }),
+     * })
+     * ```
+     */
+    getExtraHeaders?: () => Record<string, string> | undefined;
+    /**
+     * 可选：每次构造 send_message body 时由上层动态返回客户端环境上下文。
+     *
+     * 设计目的：让宿主应用注入用户的 IANA 时区 / UTC offset / locale 等
+     * **随消息一起上行**的元数据，与 `body.catalog_fragment` 走完全相同的
+     * 路径（`buildStreamBody` 内部直接组装、不经过 params）。后端就能在
+     * 生成提示词、日志、个性化回复时使用这些信息（例如"按你的当地时间提醒"
+     * 或"这条消息发自 Asia/Shanghai"）。
+     *
+     * 与 `getExtraHeaders` 的分工：
+     *   · header（getExtraHeaders）：横切给所有 HTTP 端点，后端中间件统一处理。
+     *   · body.client_context（本钩子）：仅 send_message 上行，与对话内容
+     *     绑定持久化，便于后端 / Prompt 引擎在生成时引用。
+     *
+     * 调用时机：每次 `buildStreamBody()` 调用时同步执行一次，因此实现可以
+     * 实时读取当前 locale / 系统时区，无需重建 adapter。
+     *
+     * 默认行为：钩子未提供 / 返回 `undefined` 字段时，由 SDK 内部用
+     * `Intl.DateTimeFormat().resolvedOptions().timeZone` 兜底自动检测，
+     * 保证 body.client_context 永远有合法字段（与 catalog_fragment 一样自治）。
+     *
+     * 典型用法：
+     * ```ts
+     * new DefaultJetAgentsAdapter({
+     *   ...,
+     *   getClientContext: () => snapshotClientContext(getCurrentLocale()),
+     * })
+     * ```
+     *
+     * 字段含义：
+     *   · timezone               IANA tz name，如 'Asia/Shanghai'。
+     *   · timezoneOffsetMinutes  当前 UTC 偏移分钟（正东负西，与 ECMA
+     *                            getTimezoneOffset 符号相反）。
+     *   · locale                 当前 BCP47 locale，如 'zh-CN'。
+     */
+    getClientContext?: () => Partial<{
+        timezone: string;
+        timezoneOffsetMinutes: number;
+        locale: string;
+    }> | undefined;
 }
 declare class DefaultJetAgentsAdapter implements ChatWidgetAdapter {
     private readonly baseUrl;
@@ -443,14 +3044,196 @@ declare class DefaultJetAgentsAdapter implements ChatWidgetAdapter {
         instanceId: number;
     }>;
     getSessionDetail(sessionId: number): Promise<SessionDetail>;
-    getSessionHistory(sessionId: number): Promise<NotificationTurn[]>;
+    /**
+     * 后端 ``GET /api/session/page`` 返回 ``{ items: DbSession[], total }``，
+     * DbSession.to_dict() 字段名是 snake_case + ``session_title`` 而非 ``title``。
+     * adapter 在这一层做规范化，向上层暴露统一的 ``SessionListItem``。
+     */
+    listSessions(params?: ListSessionsParams): Promise<ListSessionsResponse>;
+    deleteSession(sessionId: number): Promise<void>;
+    getSessionHistory(sessionId: number, options: GetSessionHistoryOptions): Promise<NotificationTurn[] | PaginatedHistoryResponse>;
+    /**
+     * JETP-058 v2-only — clientIds 参数规范化 + 严格校验。
+     *
+     * 与 JETP-057 差异：
+     * - 旧实现允许 ``[A-Za-z0-9._:\\-/]+`` 字符集（兼容 ``main`` / ``file:*`` / ``sel:*``）；
+     * - 新实现仅接受 ``^c_[A-Za-z0-9]{22}$``，其它一律 ``RangeError`` fail-fast。
+     *
+     * 任何不合法都立刻抛错（fail-fast，不发请求）；
+     * 对调用方意味着：未派生出 v2 cid 之前不要调 getSessionHistory（与 controller skip 配合）。
+     */
+    private _normalizeClientIdsOrThrow;
     getResourceContent(sessionId: number, resourceId: string): Promise<ResourceContent>;
+    getResourceUrl(sessionId: number, resourceId: string): Promise<string>;
+    getPreviewUrl(sessionId: number, resourceId: string, format?: 'html' | 'pdf'): Promise<string>;
     submitHITLResponse(response: HITLResponse): Promise<void>;
+    /**
+     * JETP-083 WS3.7.6 — fetch pending Collaborative HIL entities for the
+     * connecting principal (scoped to one session).
+     *
+     * Wire shape (jetagents `main.py:get_genui_pending`):
+     *   ```
+     *   GET /api/genui/pending?session_id=<int>
+     *   → { code: 200, data: { session_id, pending: [...PendingHIL...] } }
+     *   ```
+     *
+     * Field-name normalisation (snake_case → camelCase) is done here so
+     * the SDK type surface stays idiomatic TS and `useGenUIPending` can
+     * consume `PendingHIL[]` directly.
+     *
+     * Failure modes:
+     * - HTTP error → throws (caller decides to toast / retry / silent drop).
+     * - Empty list → returns `[]` (legitimate state — no pending HILs).
+     * - Malformed payload → returns `[]` and logs warn (defensive; never
+     *   surfaces "endpoint exists but data unusable" as a hard error to
+     *   the widget reconnect path).
+     */
+    getPendingHILs(sessionId: number): Promise<PendingHIL[]>;
+    /**
+     * 触发协作式停止：`POST /api/session/stop`，由 jetagents handler 把
+     * `agent:signal:stop:{session_id}:{interaction_id}=stop` 写入 Redis；
+     * 运行时检查点（agent_state_machine_v2 / simple_agent_pool /
+     * agent_executor / base_pusher）轮询同一 key 后 yield `StoppedAgentCommand`
+     * 优雅退出，并由 pusher 推送 `CANCELED` 通知。详见 `ChatWidgetAdapter.stopAgent`。
+     *
+     * 实现细节：
+     * - 复用 `fetchJSON`，自带 15s 超时、Bearer JWT 注入、401 单次 refresh 重试、
+     *   `ChatWidgetNetworkError` 抛出；与 widget 内其它 HTTP 出口策略对齐。
+     * - body 必须包含 `command: 'stop'`：后端 `AgentControlRequest` 是
+     *   `Literal["pause","resume","stop"]`，缺字段会被 Pydantic 拒为 422，即便
+     *   handler 实际只读 `session_id`。
+     * - `agent_instance_id` 上行只是为了后端日志/未来兼容；当前 handler 不读。
+     * - 业务码（如 `error("no event in session")`）走 `code != 200` 分支，
+     *   显式抛 `ChatWidgetNetworkError`，避免上层吞错；幂等场景（已停过）后端
+     *   返回 `code: 200, data: {}`，本方法 resolve 不抛。
+     */
+    stopAgent(params: {
+        sessionId: number;
+        agentInstanceId?: number;
+    }): Promise<void>;
     getStreamUrl(): string;
+    getWsUrl(sessionId: number): string;
     getAuthHeaders(): Record<string, string>;
+    listSkills(params?: SkillListParams): Promise<SkillListResponse>;
+    buildStreamBody(params: {
+        message: string;
+        agentId: string;
+        sessionId: number | null;
+        interactionId: string;
+        agentInstanceId?: number;
+        callerInstanceId?: number;
+        selectedSkills?: SelectedSkillRef[];
+        activeSpecIds?: string[];
+        /** JETP-045 Layer 1：客户端连接子空间标识（前端 owned）。 */
+        clientId?: string;
+        /**
+         * JETP-045 Phase 6 — Layer 1.5 物理连接 ID（``useConnectionId`` 派生）。
+         * 用于后端 echo 抑制；缺省（旧调用方）时不写入 body，后端按"未知连接"处理。
+         */
+        connectionId?: string;
+        fileAttachments?: FileAttachment[];
+        /**
+         * 前端"本次调用使用的模型"覆盖项；缺省 / null 时不写入 body，
+         * 后端按 agent 注册的默认 ``ModelMeta`` 走（与历史完全一致）。
+         */
+        modelOverride?: ModelOverride | null;
+    }): object;
+    /**
+     * Convert raw JetAgents Notification SSE to ChatWidget flat SSEMessage format.
+     * Mirrors JetForge's AIStreamEvent.to_chat_widget_messages() logic.
+     */
+    transformSSEMessage(raw: Record<string, unknown>): SSEMessage[] | null;
+    shareArtifact(params: {
+        artifactId: string;
+        sessionId: number;
+        title?: string;
+        artifactType?: 'file' | 'jr-page';
+        shareType?: 1 | 2;
+    }): Promise<{
+        shareCode: string;
+        shareUrl: string;
+        password?: string;
+    } | null>;
+    listDirectoryFiles(sessionId: number, dirPrefix: string, options?: ListDirectoryFilesOptions): Promise<DirectoryFileEntry[]>;
+    getPoolStatus(sessionId: number): Promise<PoolStatusResponse>;
+    /**
+     * 拉取可选模型清单。**走 hip-server，不走 fusion**（见 ChatWidgetAdapter.listModels 注释）。
+     *
+     *   - hipBaseUrl 缺省时直接抛错（拒绝 fall back 到 ``baseUrl``，避免误把 jetagents
+     *     当成模型注册表）；这种配置下上层 picker 应表现为"未启用模型选择"。
+     *   - 后端约定：响应体 ``{ success, data: { items, total } }``；这里把内层 data 拆出来
+     *     给上层，与其他 adapter 方法风格一致。
+     *   - hip 端字段是 snake_case（``default_channel``）；在这一层做一次转 camelCase，
+     *     上游业务永远只见 camelCase。
+     */
+    listModels<TGroup extends 'basename' | 'name' | 'none' = 'basename'>(params?: ListModelsParams & {
+        groupBy?: TGroup;
+    }): Promise<ListModelsResponse<TGroup extends 'basename' ? ModelListItemBasenameGrouped : TGroup extends 'name' ? ModelListItemGrouped : ModelListItemRaw>>;
+    /**
+     * 拉取 agent 在后端注册的默认模型，仅供 picker 展示态使用。
+     *
+     * 三态全部吞成 null（详见 ChatWidgetAdapter.getAgentDefaultModel 注释）：
+     *   - 业务找不到：hip 返回 ``{ success: false, error.code: 'NOT_FOUND' }``（HTTP 200）；
+     *   - 上游异常 / 网络 / 超时 / 5xx：fetchHipJSON 抛 ChatWidgetNetworkError，这里 catch 后返回 null；
+     *   - 200 但 ``data.name`` 缺失：当作脏数据，返回 null。
+     *
+     * 这种策略避免"agent 默认模型查不到"阻塞用户输入；实在需要追错的话看 ``console.warn``。
+     */
+    getAgentDefaultModel(agentId: string): Promise<{
+        name: string;
+        displayName?: string;
+        version?: string;
+    } | null>;
+    postDiscussionMessage(sessionId: number, req: PostDiscussionMessageRequest): Promise<PostDiscussionMessageResponse>;
+    createDiscussion(sessionId: number, req: CreateDiscussionRequest): Promise<CreateDiscussionResponse>;
+    getPoolAgents(sessionId: number): Promise<PoolAgent[]>;
+    downloadWorkspaceZip(sessionId: number): Promise<void>;
+    private _saveBlobResponse;
+    uploadFiles(files: File[], sessionId: number | undefined, clientId: string): Promise<FileUploadResult>;
+    getUploadStatus(resourceIds: string[]): Promise<FileUploadStatusResult>;
+    uploadWorkspaceFiles(sessionId: number, files: File[], options: {
+        targetDirectory?: string;
+        clientId: string;
+    }): Promise<WorkspaceUploadResult>;
+    createWorkspaceDirectory(sessionId: number, dirName: string, parentPath?: string): Promise<{
+        code: number;
+        message: string;
+    }>;
+    private _wsPost;
+    renameWorkspaceItem(sessionId: number, oldPath: string, newName: string): Promise<{
+        code: number;
+        message: string;
+    }>;
+    deleteWorkspaceItems(sessionId: number, paths: string[]): Promise<{
+        code: number;
+        message: string;
+    }>;
+    moveWorkspaceItems(sessionId: number, sourcePaths: string[], targetDir: string): Promise<{
+        code: number;
+        message: string;
+    }>;
+    copyWorkspaceItems(sessionId: number, sourcePaths: string[], targetDir: string): Promise<{
+        code: number;
+        message: string;
+    }>;
     onAuthFailure(): void;
     refreshAuth(): Promise<boolean>;
+    private fetchHipJSON;
+    private fetchMultipart;
+    private static readonly FETCH_TIMEOUT_MS;
     private fetchJSON;
+    /**
+     * JETP-056 P2 — adapter 内部所有 HTTP 出口统一走这一条路径：
+     * - 自动注入 `getAuthHeaders()`（caller header 优先级更高，可覆盖）；
+     * - 401 → `refreshAuth()` 单次重试；重试仍非 401 直接返回（让 caller 处理 200/4xx/5xx）；
+     * - refresh 失败或重试仍 401 → `onAuthFailure()` + 抛 `ChatWidgetAuthError`；
+     * - 不消费 body，返回 raw `Response`，让 caller 决定 `.json()` / `.blob()` / 错误处理。
+     *
+     * 这是 adapter 侧"统一鉴权 + 401 兜底"的唯一出口，等价于 React 侧的 `useAuthedFetch`。
+     * 散落 fetch（HITL upload / artifact-share / mkdir / wsPost / resource raw / download zip）
+     * 都已收敛到此方法，避免漏注 401 处理与 token 漂移。
+     */
+    private authedFetch;
 }
 
 declare class ChatWidgetAuthError extends Error {
@@ -462,5 +3245,420 @@ declare class ChatWidgetNetworkError extends Error {
     readonly name: "ChatWidgetNetworkError";
     constructor(message: string, statusCode: number);
 }
+/**
+ * JETP-054 — `client_id` 协议守门错误。
+ *
+ * 抛出场景（前端硬错误，不再 silent fallback 'main'）：
+ * 1. session 已就绪但 v2 client_id 分配在 N 次重试后仍失败；
+ * 2. 调用方（adapter / controller）在到达发送层时仍未拿到合法 cid；
+ * 3. 后端在 strict 模式下返回 `CLIENT_ID_REQUIRED` 4xx（统一映射到本错误）。
+ *
+ * 设计意图：
+ * - 把"路径异常"显式化，便于上层 toast / retry / 上报；
+ * - 与后端 `ClientIdRequiredError` 形成端到端契约对齐；
+ * - 与 `ChatWidgetAuthError` / `ChatWidgetNetworkError` 同级别，可被业务统一捕获。
+ */
+declare class InvalidClientIdError extends Error {
+    readonly reason: 'missing' | 'session_not_ready' | 'allocation_failed' | 'legacy_main' | 'legacy_format' | 'session_forbidden';
+    readonly sessionId?: string | number | null | undefined;
+    readonly name: "InvalidClientIdError";
+    constructor(message: string, reason: 'missing' | 'session_not_ready' | 'allocation_failed' | 'legacy_main' | 'legacy_format' | 'session_forbidden', sessionId?: string | number | null | undefined);
+}
+
+declare const I18nContext: React$1.Context<ChatWidgetMessages>;
+declare function useChatWidgetI18n(): {
+    messages: ChatWidgetMessages;
+    t: (key: keyof ChatWidgetMessages, params?: Record<string, string | number>) => string;
+    locale: ChatWidgetLocale;
+};
+
+declare function organizeMessagesByLevel(messages: Round['messages']): {
+    rootMessages: Round['messages'];
+    childrenMap: Map<string, Round['messages']>;
+};
+
+declare function getStatusDisplay(sessionBusy: boolean, connectionStatus: string, executionStatus: ExecutionStatus, i18n: ChatWidgetMessages): {
+    icon: string;
+    iconName: IconName;
+    text: string;
+};
+
+declare function fileTypeIcon(mimeOrExt: string): IconName;
+
+type FileCategory = 'sch' | 'pcb' | 'pro' | 'gerber' | 'pdf' | 'excel' | 'code' | 'image' | 'text' | 'json' | 'other';
+declare function fileTypeCategory(mimeOrExt: string): FileCategory;
+declare function fileTypeColor(mimeOrExt: string): string;
+
+interface WorkspacePanelProps {
+    open: boolean;
+    onClose: () => void;
+    tree: WorkspaceTreeNode[];
+    recentChanges?: WorkspaceFile[];
+    onSelectFile: (file: WorkspaceFile) => void;
+    highlightedIds?: Set<string>;
+    fileCount?: number;
+    initialExpandedPaths?: string[];
+    onExpandStateChange?: (paths: string[]) => void;
+    onDownloadAll?: () => Promise<void>;
+    onUploadFiles?: (files: File[], targetDirectory?: string) => Promise<void>;
+    onCreateFolder?: (folderName: string, parentPath?: string) => Promise<void>;
+    onRename?: (oldPath: string, newName: string) => Promise<void>;
+    onDelete?: (paths: string[]) => Promise<void>;
+    onMove?: (sourcePaths: string[], targetDir: string) => Promise<void>;
+    onCopy?: (sourcePaths: string[], targetDir: string) => Promise<void>;
+}
+declare const WorkspacePanel: React__default.FC<WorkspacePanelProps>;
+
+interface DiscussionPanelProps {
+    open: boolean;
+    onClose: () => void;
+    discussions: DiscussionFile[];
+    newDiscussionIds?: Set<string>;
+    currentUserAlias?: string;
+    sessionId?: number;
+    adapter?: ChatWidgetAdapter;
+    poolAgents?: PoolAgent[];
+    onRefresh?: () => void;
+    onPostMessage?: (discussionPath: string, body: string, messageType: string, mentions: string[]) => Promise<PostDiscussionMessageResponse>;
+}
+declare const DiscussionPanel: React__default.FC<DiscussionPanelProps>;
+
+interface DiscussionViewerProps {
+    discussion: DiscussionFile;
+    currentUserAlias?: string;
+    sessionId?: number;
+    adapter?: ChatWidgetAdapter;
+    poolAgents?: PoolAgent[];
+    onClose: () => void;
+    onRefresh?: () => void;
+    onPostMessage?: (discussionPath: string, body: string, messageType: string, mentions: string[]) => Promise<PostDiscussionMessageResponse>;
+}
+declare const DiscussionViewer: React__default.FC<DiscussionViewerProps>;
+
+interface DiscussionComposerProps {
+    discussion: DiscussionFile;
+    sessionId: number;
+    currentUser: string;
+    adapter: ChatWidgetAdapter;
+    onMessageSent: () => void;
+    onPostMessage?: (discussionPath: string, body: string, messageType: string, mentions: string[]) => Promise<PostDiscussionMessageResponse>;
+    disabled?: boolean;
+    allowedTypes?: string[];
+    poolAgents?: PoolAgent[];
+}
+declare const DiscussionComposer: React__default.FC<DiscussionComposerProps>;
+
+interface MentionAutocompleteProps {
+    trigger: string;
+    participants: string[];
+    poolAgents: PoolAgent[];
+    onSelect: (alias: string, isNewParticipant: boolean) => void;
+    onClose: () => void;
+}
+declare const MentionAutocomplete: React__default.FC<MentionAutocompleteProps>;
+
+interface AnnotationFABProps {
+    resourceId: string | null;
+    fileName: string;
+    onSend: (message: string) => void;
+    visible: boolean;
+    expanded?: boolean;
+    onToggle?: (expanded: boolean) => void;
+    disabled?: boolean;
+}
+declare const AnnotationFAB: React__default.FC<AnnotationFABProps>;
+
+interface AnnotationPanelMessage {
+    role: 'user' | 'assistant';
+    text: string;
+    timestamp?: number;
+}
+interface AnnotationPanelProps {
+    open: boolean;
+    onClose: () => void;
+    fileLevelConversation: {
+        id: string;
+        messages: AnnotationPanelMessage[];
+        preview?: string;
+    } | null;
+    anchoredAnnotations: Array<{
+        id: string;
+        anchor?: {
+            text: string;
+            startLine?: number;
+            endLine?: number;
+        };
+        messages: AnnotationPanelMessage[];
+        preview?: string;
+    }>;
+    activeAnnotationId: string | null;
+    onSetActive: (id: string | null) => void;
+    onSendFollowUp: (annotationId: string, text: string) => void;
+    isCreating?: boolean;
+}
+declare const AnnotationPanel: React__default.FC<AnnotationPanelProps>;
+
+interface AnnotationAnchorRect {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+}
+interface InlineAnnotationInputProps {
+    anchorRect: AnnotationAnchorRect;
+    anchorText?: string;
+    onSend: (message: string) => void;
+    onClose: () => void;
+    onFallback?: () => void;
+    placeholder?: string;
+    containerRect?: DOMRect;
+}
+declare const InlineAnnotationInput: React__default.FC<InlineAnnotationInputProps>;
+
+interface AgentGroupPanelProps {
+    open: boolean;
+    onClose: () => void;
+    agents: Map<number, AgentInstanceState>;
+    onPause: (agentInstanceId: number) => void;
+    onResume: (agentInstanceId: number) => void;
+    onStop: (agentInstanceId: number) => void;
+}
+declare const AgentGroupPanel: React__default.FC<AgentGroupPanelProps>;
+
+interface RailAction {
+    id: string;
+    icon: React__default.ReactNode;
+    label: string;
+    badge?: number;
+    onClick: () => void;
+    active?: boolean;
+}
+interface ImmersiveShellProps {
+    children: React__default.ReactNode;
+    tabBar?: React__default.ReactNode;
+    /** v2: Channel sidebar replaces rail + overlays */
+    sidebar?: React__default.ReactNode;
+    /** v2: Floating conversation windows layer */
+    floatingLayer?: React__default.ReactNode;
+    /** v1 (legacy): overlay content — only rendered when sidebar is not provided */
+    overlay?: React__default.ReactNode;
+    fab?: React__default.ReactNode;
+    unreadCount?: number;
+    annotationCount?: number;
+    onRailHome?: () => void;
+    onRailWorkspace?: () => void;
+    onRailAnnotation?: () => void;
+    onExitImmersive?: () => void;
+    activeOverlay?: 'home' | 'workspace' | 'discussion' | 'annotation' | null;
+    extraRailActions?: RailAction[];
+}
+declare const ImmersiveShell: React__default.FC<ImmersiveShellProps>;
+
+interface TabBarProps {
+    tabs: ViewerTab[];
+    activeTabId: string | null;
+    onTabClick: (tabId: string) => void;
+    onTabClose: (tabId: string) => void;
+    maxVisible?: number;
+}
+declare const TabBar: React__default.FC<TabBarProps>;
+
+interface ChatOverlayProps {
+    children: React__default.ReactNode;
+    open: boolean;
+    onClose: () => void;
+    unreadCount?: number;
+}
+declare const ChatOverlay: React__default.FC<ChatOverlayProps>;
+
+/**
+ * SkillSelector — pure rendering component (JETP-032).
+ *
+ * Receives all data and callbacks as props; contains zero business logic.
+ * All state management lives in useSkillOrchestration.
+ */
+
+interface SkillSelectorProps {
+    visible: boolean;
+    skills: SkillSummary[];
+    loading: boolean;
+    error: string | null;
+    selectedIndex: number;
+    hasMore: boolean;
+    emptyText: string;
+    loadingText: string;
+    errorText: string;
+    loadMoreText: string;
+    selectorLabel: string;
+    onSelect: (skill: SkillSummary) => void;
+    onClose: () => void;
+    onLoadMore: () => void;
+    renderSkillIcon?: (skill: SkillSummary) => React__default.ReactNode;
+}
+declare const SkillSelector: React__default.FC<SkillSelectorProps>;
+
+/**
+ * useSkillData — data-fetching layer for skill selector (JETP-032).
+ *
+ * Manages: API calls to adapter.listSkills, debounced search,
+ * pagination (append + dedupe), loading/error states.
+ * Does NOT manage: UI visibility, keyboard navigation, or DOM.
+ */
+
+interface UseSkillDataOptions {
+    adapter: ChatWidgetAdapter | null;
+    debounceMs?: number;
+}
+interface UseSkillDataReturn {
+    skills: SkillSummary[];
+    loading: boolean;
+    error: string | null;
+    total: number;
+    hasMore: boolean;
+    search: (text: string) => void;
+    loadMore: () => void;
+    reset: () => void;
+}
+declare function useSkillData(options: UseSkillDataOptions): UseSkillDataReturn;
+
+/**
+ * useSkillSelectorState — UI-state layer for skill selector (JETP-032).
+ *
+ * Manages: popup visibility, selected item index, keyboard navigation.
+ * Does NOT manage: data fetching, adapter calls, or DOM insertion.
+ */
+interface UseSkillSelectorStateReturn {
+    visible: boolean;
+    selectedIndex: number;
+    open: (itemCount: number) => void;
+    close: () => void;
+    moveDown: (itemCount: number) => void;
+    moveUp: (itemCount: number) => void;
+    setSelectedIndex: (idx: number) => void;
+}
+declare function useSkillSelectorState(): UseSkillSelectorStateReturn;
+
+/**
+ * useSkillOrchestration — orchestration layer for skill selector (JETP-032).
+ *
+ * Composes useSkillData + useSkillSelectorState, connects to RichInput
+ * (via ref), and dispatches InteractionEvents through the provided dispatch.
+ */
+
+interface UseSkillOrchestrationOptions {
+    adapter: ChatWidgetAdapter | null;
+    dispatch?: ((event: ChatWidgetInteractionEvent) => void) | null;
+}
+interface UseSkillOrchestrationReturn {
+    data: UseSkillDataReturn;
+    state: UseSkillSelectorStateReturn;
+    handleSlashTrigger: (prefix: string) => void;
+    handleSkillSelect: (skill: SkillSummary) => void;
+    handleClose: (reason: 'escape' | 'blur' | 'select') => void;
+    handleSearch: (text: string) => void;
+    buildEnrichedText: (rawText: string) => string;
+    selectedSkillsRef: React.MutableRefObject<SkillSummary[]>;
+}
+declare function useSkillOrchestration(options: UseSkillOrchestrationOptions): UseSkillOrchestrationReturn;
+
+interface ResourceProviderProps {
+    adapter: ChatWidgetAdapter;
+    sessionId?: number;
+    children: React__default.ReactNode;
+}
+declare const ResourceProvider: React__default.FC<ResourceProviderProps>;
+
+interface ShareResourceProviderProps {
+    /** Base URL for the share API (e.g., "https://api.example.com/share") */
+    shareBaseUrl: string;
+    /** Share token for authentication */
+    shareToken?: string;
+    children: React__default.ReactNode;
+}
+declare const ShareResourceProvider: React__default.FC<ShareResourceProviderProps>;
+
+interface ResourceContextValue {
+    resolveResource(resourceId: string): Promise<ResourceResolveResult>;
+    resolvePreviewUrl?(resourceId: string, format: 'html' | 'pdf'): Promise<string>;
+    listDirectoryFiles?(dirPrefix: string, options?: ListDirectoryFilesOptions): Promise<DirectoryFileEntry[]>;
+    sessionId?: number;
+}
+declare const ResourceContext: React$1.Context<ResourceContextValue | null>;
+declare function useResourceContext(): ResourceContextValue | null;
+
+interface ResourceInput {
+    resource_id?: string;
+    url?: string;
+    content?: string;
+}
+interface ResourceState {
+    loading: boolean;
+    error?: string;
+    url?: string;
+    content?: string;
+    mimeType?: string;
+    fileName?: string;
+    gitPath?: string;
+}
+/**
+ * Resolve a resource from url, resource_id, or inline content.
+ * Priority: url > resource_id > content.
+ */
+declare function useResource(input: ResourceInput): ResourceState;
+
+/**
+ * prepareJsonRenderSpec — 把"老格式"的 GenUI spec 标准化到 @json-render 当前
+ * 预期的形态。
+ *
+ * 历史背景：
+ *   后端较早期吐出的 spec 用了两种与 @json-render 当前规范不一致的写法，
+ *   share viewer / 任何离线消费方都需要在喂给 Renderer 之前做一次翻译，
+ *   否则要么报 schema 错，要么模板插值不生效。之前这套翻译只散落在 demo
+ *   的 ``share-app.tsx`` 里，每个嵌入方都要复制一份；现在收回 SDK 作为
+ *   公共工具。
+ *
+ * 处理项：
+ *   1. ``{$cond: [c, t, e]}`` →
+ *      ``{$cond: c, $then: t, $else: e?}``
+ *   2. ``{$state|$item|$index, op, value}`` （op ∈ eq/neq/gt/gte/lt/lte）→
+ *      ``{$state|$item|$index, [op]: value}``
+ *   3. ``$template`` 字符串里的占位翻译（沿用早期 share viewer 的行为）：
+ *        - ``{{/state/x}}`` → ``${/x}`` （剥掉 ``/state/`` 前缀，因为新版
+ *          ``$template`` 解析器自身的 root 就是 state，再带 ``/state/`` 会
+ *          双层路径）
+ *        - ``{{x}}`` 或 ``{{user/age}}`` → ``${/x}`` / ``${/user/age}``
+ *          （相对路径自动补 ``/`` 前缀变绝对路径）
+ *        - ``{{/x}}`` → ``${/x}`` （已是绝对路径，原样保留）
+ *   4. CWRF-013 Phase 0 spec migrator (``./migrator``) — strip protocol-lie
+ *      fields (Item 01 DataTable filterable/groupBy/expandable) before the
+ *      renderer sees them, with LRU caching + warning de-dup so repeat
+ *      renders of the same spec are silent. See
+ *      ``docs/proposals/CWRF-013-a2ui-systematic-upgrade/00_protocol/04_spec_migrator.md``.
+ *
+ * 输入会原样深拷贝，不修改入参。无法识别的结构原样保留。
+ */
+/**
+ * 接受任意 spec 形态（含老格式），返回标准化后的可直接喂给 ``@json-render``
+ * Renderer / SDK ``<JsonRenderStandalone>`` 的对象。
+ *
+ * 不处理 ``null`` / 非对象 —— 原样返回，方便链式调用。
+ *
+ * Pipeline order:
+ *   1. CWRF-013 spec migrator (Phase 0) — strip protocol-lie fields with
+ *      cached + dedupe-warned ``migrateSpecCached``. Runs FIRST so later
+ *      template / expression normalisation only sees honest specs.
+ *      Idempotent: same spec on second render hits the LRU cache and
+ *      emits no extra console.warn (see ``./migrator/dry-run.ts``).
+ *   2. Expression normalisation (``$cond`` array → triplet, ``op``/``value``
+ *      → key-shorthand).
+ *   3. Template rewriting (``{{...}}`` → ``${/...}``).
+ */
+declare function prepareJsonRenderSpec<T = Record<string, unknown>>(raw: unknown): T;
+
+/**
+ * 在 KiCad S-expression 正文中定位包含指定 uuid 的最外层括号表（通常为 symbol/footprint 等图元块）。
+ * 纯函数，无 DOM 依赖 — CWRF-003 §1.3 Compound Value。
+ */
+declare function extractKicadSexprByUuid(content: string, uuid: string): string | null;
 
-export { type AggregatedMessage, type Artifact, ChatWidget, type ChatWidgetAPI, type ChatWidgetAdapter, ChatWidgetAuthError, type ChatWidgetConfig, ChatWidgetNetworkError, type ChatWidgetProps, ChildAgentCard, type ConnectionStatus, DEFAULT_CONFIG, DefaultJetAgentsAdapter, type DefaultJetAgentsAdapterOptions, type ExecutionStatus, type HITLRequest, type HITLResponse, MessageContent, type MessageContentType, type NotificationTurn, type NotificationType, PinnedArea, PlanCard, type PlanItem, type ResourceContent, type Round, RoundHeader, type SSEMessage, SchemaFormRenderer, type SessionDetail, type TaskPlan, TodoCard, type TodoData, type TodoGroup, type TodoPhase, type TodoStats, type TodoTask, type ToolCallData, ToolCardBuffering, type UiConfig, isTodoNotificationContent, mergeConsecutiveThinkMessages, useMessageAggregator, useSSE };
+export { type AgentControlFrame, type AgentDefaultModelInfo, AgentGroupPanel, type AgentGroupPanelProps, type AgentInstanceState, type AggregatedMessage, type AnnotationAnchor, type AnnotationAnchorRect, AnnotationFAB, type AnnotationFABProps, type AnnotationInteraction, type AnnotationKind, type AnnotationMessage, AnnotationPanel, type AnnotationPanelMessage, type AnnotationPanelProps, type Artifact, type ArtifactRef, type AttentionToast, AttentionToastList, type AttentionToastListProps, ChatOverlay, type ChatOverlayProps, ChatWidget, type ChatWidgetAPI, type ChatWidgetAdapter, ChatWidgetAuthError, type ChatWidgetConfig, type ChatWidgetControllerOptions, type ChatWidgetControllerState, type ChatWidgetInteractionEvent, ChatWidgetLocale, ChatWidgetMessages, ChatWidgetNetworkError, type ChatWidgetProps, ChildAgentCard, HttpError as ClientAllocatorHttpError, type ClientTitleEvent, type ConnectionStatus, ContextChip, type ContextChipProps, type ContextPreload, type CreateClientOptions, type CreateClientResponse, type CreateDiscussionRequest, type CreateDiscussionResponse, DEFAULT_CONFIG, DefaultComposer, type DefaultComposerProps, DefaultJetAgentsAdapter, type DefaultJetAgentsAdapterOptions, type DirectoryFileEntry, DiscussionComposer, type DiscussionComposerProps, type DiscussionFile, type DiscussionMessage, type DiscussionMeta, DiscussionPanel, type DiscussionPanelProps, DiscussionViewer, type DiscussionViewerProps, ESC_PRIORITY, type EscHandler, type ExecutionStatus, type FileAttachment, type FileCategory$1 as FileCategory, type FileReference, type FileUploadResult, type FileUploadStatusResult, FileViewer, FileViewerModal, type FileViewerModalProps, FileViewerPanel, type FileViewerPanelProps, type FileViewerProps, FloatingInput, type FloatingInputProps, FloatingToolbar, type FloatingToolbarProps, type HITLRequest, type HITLResponse, HoverPreview, type HoverPreviewProps, I18nContext, Icon, type IconName, type IconProps, type IconWeight, ImmersiveShell, type ImmersiveShellProps, InlineAnnotationInput, type InlineAnnotationInputProps, type InteractionEventType, InvalidClientIdError, type KicadCanvasSelectionPayload, LinkCard, type ListDirectoryFilesOptions, type ListModelsParams, type ListModelsResponse, type ListSessionsParams, type ListSessionsResponse, MODEL_AUTO, MentionAutocomplete, type MentionAutocompleteProps, type MentionTarget, MessageContent, type MessageContentType, type ModelChoice, type ModelListItemBasenameGrouped, type ModelListItemGrouped, type ModelListItemRaw, type ModelListVariant, type ModelOverride, ModelPicker, type ModelPickerProps, type NotificationConfig, type NotificationTurn, type NotificationType, type PendingHIL, PinnedArea, PlanCard, type PlanItem, type PoolAgent, type PoolAgentAction, type PoolStatusResponse, type PostDiscussionMessageRequest, type PostDiscussionMessageResponse, type ProjectFile, ProvenanceGraphSnapshot, type RailAction, type ReadReceipt, ResourceChip, type ResourceContent, ResourceContext, type ResourceContextValue, type ResourceInput, ResourceProvider, type ResourceState, RichInput, type RichInputHandle, type RichInputProps, type Round, RoundHeader, RoundMessageList, RoundsView, type RoundsViewProps, type SSEMessage, SchemaFormRenderer, type SelectedSkillRef, type SelectionBridgeOptions, type SelectionData, type SelectionState, type SessionChannelMessage, type ClientItem as SessionClientItem, BusinessError as SessionClientsBusinessError, type SessionDetail, type SessionLifecycleEvent, type SessionListItem, SessionListPanel, type SessionListPanelProps, ShareResourceProvider, type ShortcutDef, type SkillListParams, type SkillListResponse, SkillSelector, type SkillSelectorProps, type SkillSummary, type SmartPasteOptions, type SnapshotData, type SpecLifecycleEntry, SplitPanel, type SplitPanelProps, TabBar, type TabBarProps, type TaskPlan, TodoCard, type TodoData, type TodoGroup, type TodoPhase, type TodoStats, type TodoTask, type ToolCallData, ToolCardBuffering, type TransportMode, type TreePersistState, type UiConfig, type UploadedFileInfo, type UseAgentControlOptions, type UseAgentDefaultModelOptions, type UseAgentDefaultModelResult, type UseAnnotationsOptions, type UseAnnotationsReturn, type UseAttentionManagerOptions, type UseAutoTabOptions, type UseClientIdAllocatorReturn, type UseDiscussionsOptions, type UseDiscussionsReturn, type UseFileUploadOptions, type UseFileUploadReturn, type UseHoverPreviewOptions, type UseModelsOptions, type UseModelsResult, type UseProjectFilesOptions, type UseProjectFilesResult, type UseSessionChannelOptions, type UseSessionChannelReturn, type UseSessionClientsReturn, type UseSessionListOptions, type UseSessionListReturn, type UseShortcutsOptions, type UseSkillDataOptions, type UseSkillDataReturn, type UseSkillOrchestrationOptions, type UseSkillOrchestrationReturn, type UseSkillSelectorStateReturn, type UseViewerTabsReturn, type UseWorkspaceFilesOptions, type UseWorkspaceFilesReturn, VIEWER_CAPABILITIES, type ViewerInteractionAdapter, type ViewerTab, type WorkspaceFile, WorkspacePanel, type WorkspacePanelProps, type WorkspaceTreeNode, type WorkspaceUploadResult, type XrefMeta, type XrefRecord, type XrefRef, contentToSrc, extractKicadSexprByUuid, fileTypeCategory, fileTypeColor, fileTypeIcon, formatFileSize, getExtension, getFileCategory, getStatusDisplay, getViewerCapabilities, inferLanguage, isShowModelChannels, isTodoNotificationContent, loadLastModelName, mergeConsecutiveThinkMessages, modelBasename, organizeMessagesByLevel, parseDiscussionMessages, parseXrefs, prepareJsonRenderSpec, saveLastModelName, useAgentControl, useAgentDefaultModel, useAnnotations, useAttentionManager, useAutoTab, useChatWidgetController, useChatWidgetI18n, useClientIdAllocator, useDiscussions, useEscStack, useFileUpload, useHoverPreview, useMessageAggregator, useModels, useNarrowMode, useProjectFiles, useResource, useResourceContext, useSSE, useSelectionBridge, useSessionChannel, useSessionClients, useSessionList, useShortcuts, useSkillData, useSkillOrchestration, useSkillSelectorState, useSmartPaste, useTreePersist, useViewerTabs, useWorkspaceFiles };