@meiyukichan/dsh-sandore 0.1.0-rc.6

package/lib/client/model-faces.d.ts

@@ -0,0 +1,156 @@
+/**
+ * composer 选择器的运行时注入面（模型目录 / 会话权限投影 / 命令执行）。
+ *
+ * 编译期不依赖 DSH 的 ui-model-selection / ui-permission-presets 包（沙盒仓库
+ * 未链接它们），这里按 harness 的 wire 形状自声明最小类型；运行时复用 dev 实例
+ * 已加载的 `ctx.modelDirectories` 服务、会话 projections 与 `remote.commands`，
+ * 行为与 DSH 主 session 的模型/权限选择完全一致（同一数据源、同一 RPC）。
+ * @module @deepseek-ai/dsh-client-ui-sandore/src/client/model-faces
+ */
+/** 可订阅快照面（对齐 runtime 的 `ObservableSnapshot`）。 */
+export interface ObservableFace<T> {
+    getSnapshot(): T;
+    subscribe(fn: () => void): () => void;
+}
+/** 一个会话的完整模型选择。 */
+export interface ModelSelection {
+    /** 注册的 provider 路由。 */
+    provider: string;
+    /** provider 属下的模型 id。 */
+    model: string;
+    /** 推理等级（缺省保留 provider/adapter 默认）。 */
+    reasoningEffort?: string;
+}
+/** adapter 属下的一个推理等级。 */
+export interface ModelReasoningEffort {
+    id: string;
+    name: string;
+    description?: string;
+}
+/** 单个精确模型路由的可选推理元数据。 */
+export interface ModelReasoning {
+    efforts: ModelReasoningEffort[];
+    defaultEffort?: string;
+}
+/** provider 组内展示的一个模型。 */
+export interface ModelCatalogModel {
+    id: string;
+    name: string;
+    description?: string;
+    reasoning?: ModelReasoning;
+}
+/** 一个成功广告了模型的 provider 组。 */
+export interface ModelProviderGroup {
+    id: string;
+    name: string;
+    models: ModelCatalogModel[];
+}
+/** 目录加载失败的 provider。 */
+export interface ModelCatalogFailure {
+    id: string;
+    name: string;
+    message: string;
+}
+/** 模型目录快照（对齐 ui-model-selection 的 `ModelDirectoryState`）。 */
+export interface ModelDirectoryState {
+    current: ModelSelection | null;
+    routable: boolean | null;
+    groups: readonly ModelProviderGroup[];
+    failures: readonly ModelCatalogFailure[];
+    status: 'idle' | 'loading' | 'ready' | 'selecting' | 'error';
+    error: string | null;
+}
+/** 单个会话的共享模型目录控制面（对齐 `ModelDirectory`）。 */
+export interface ModelDirectoryFace {
+    readonly store: ObservableFace<ModelDirectoryState>;
+    load(): Promise<unknown>;
+    select(selection: ModelSelection): Promise<void>;
+    dispose(): void;
+}
+/** `connection.api.sessions` 的最小模型 RPC 面（对齐 harness apiproxy sessions.ts）。 */
+export interface SessionModelsWire {
+    current: ModelSelection;
+    routable: boolean;
+    groups: ModelProviderGroup[];
+    failures: ModelCatalogFailure[];
+}
+/** `connection.api.sessions.models/selectModel` 的最小面。 */
+export interface SessionModelsApi {
+    models(input: {
+        sessionId: string;
+    }): Promise<{
+        result: {
+            ok: boolean;
+            value: SessionModelsWire;
+            error?: {
+                code: string;
+                message: string;
+            };
+        };
+    }>;
+    selectModel(input: {
+        sessionId: string;
+        provider: string;
+        model: string;
+        reasoningEffort?: string;
+    }): Promise<{
+        result: {
+            ok: boolean;
+            value: {
+                selected: ModelSelection;
+            };
+            error?: {
+                code: string;
+                message: string;
+            };
+        };
+    }>;
+}
+/**
+ * 轻量每会话模型目录（对齐 DSH ui-model-selection 的 `ModelDirectory`）：
+ * 直接走 `connection.api.sessions.models/selectModel`（同一 RPC、同一行为），
+ * 不依赖 DSH 会话 scope（sandore 实例会话未必被 DSH 会话列表 staged）。
+ */
+export declare class SandoreModelDirectory implements ModelDirectoryFace {
+    private readonly api;
+    private readonly sessionId;
+    readonly store: ObservableFace<ModelDirectoryState>;
+    private state;
+    private readonly listeners;
+    private generation;
+    private disposed;
+    constructor(api: SessionModelsApi, sessionId: string);
+    /** 刷新目录（失败保留上次好数据；打开菜单时调用，行为同 DSH）。 */
+    load(): Promise<unknown>;
+    /** 选择完整 provider/model/推理等级（提交 `selectModel` 绑定会话）。 */
+    select(selection: ModelSelection): Promise<void>;
+    /** 会话 scope 拆除时调用（沙盒目录随组件卸载回收）。 */
+    dispose(): void;
+    private update;
+}
+/** 权限模式选项。 */
+export interface PermissionOption {
+    value: string;
+    name: string;
+    description?: string;
+}
+/** 权限选择投影值（`projections.permissions`）。 */
+export interface PermissionSelectValue {
+    options: PermissionOption[];
+    currentValue: string;
+}
+/** `remote.commands.execute` 的最小返回面。 */
+export interface CommandExecuteResult {
+    ok: boolean;
+    value?: unknown;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+/**
+ * 解析 `/permission`（无参）命令报告文本：
+ * `current preset workspace-write (available: workspace-write, danger-full-access)`。
+ * 权限投影缺失时作为回退数据源（与 DSH 主 session 的权限选择同一命令路径）。
+ */
+export declare function parsePermissionReport(text: string): PermissionSelectValue | undefined;

package/lib/client/open-discussion.d.ts

@@ -0,0 +1,24 @@
+/**
+ * RunView「打开讨论」按钮的接线 adapter（无 React 依赖，可单测）。
+ *
+ * `createOpenDiscussion` 把宿主 `ctx.sessions` 的打开面接成 RunView 的
+ * `openDiscussion` 回调：调用时经 `sessions.open(instanceId)` 跳转到宿主
+ * Session chat 视图（内含 `sandore-step` 讨论节点）。宿主 Session id ==
+ * instanceId，故 `instanceId` 可安全收窄为 `SessionId`（brand 仅编译期标记，
+ * 运行时就是同一字符串，无任何转换开销）。
+ * @module @deepseek-ai/dsh-client-ui-sandore/src/client/open-discussion
+ */
+import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client';
+/** `createOpenDiscussion` 所需的最小 sessions 打开面（`ctx.sessions` 结构满足）。 */
+export interface SessionsOpenFace {
+    open(id: SessionId): void;
+}
+/** RunView 的「打开讨论」回调签名（无入参，点击后跳宿主会话）。 */
+export type OpenDiscussion = () => void;
+/**
+ * 构造「打开讨论」回调：调用时经 `sessions.open(instanceId)` 跳宿主会话。
+ * @param sessions - `ctx.sessions` 的最小打开面。
+ * @param instanceId - 目标工作流实例 id（宿主 Session id == instanceId）。
+ * @returns 供 RunView `openDiscussion` prop 直接使用的回调。
+ */
+export declare function createOpenDiscussion(sessions: SessionsOpenFace, instanceId: string): OpenDiscussion;

package/lib/client/panel-model.d.ts

@@ -0,0 +1,34 @@
+/**
+ * WorkflowPanel 列表派生纯逻辑（无 React 依赖，可单测）。
+ *
+ * 从 InstanceList / DefinitionList 抽出的共享纯函数：按工作区分组（`deriveGroups`）、
+ * 关键词过滤（`matchesInstanceQuery` / `matchesDefinitionQuery`）与时间戳格式化
+ * （`formatTimestamp`）。这些函数不触碰组件状态与 RPC，输入输出均为普通数据，
+ * 故独立成模块便于单元测试与复用。错误消息归一化见 `describe-error.ts`。
+ * @module @deepseek-ai/dsh-client-ui-sandore/src/client/panel-model
+ */
+import type { WorkspaceView } from '@deepseek-ai/dsh-client-runtime/client';
+import type { InstanceSummary, WorkflowDefinitionEntry } from 'dsh-sandore/remote';
+/** 未分组桶的稳定键（空串，对齐 DSH 的 UNGROUPED_KEY 惯例）。 */
+export declare const UNGROUPED_KEY = "";
+/** 一个工作区分组（含成员实例）。 */
+export interface InstanceGroup {
+    readonly key: string;
+    readonly title: string;
+    readonly instances: readonly InstanceSummary[];
+}
+/** 把 ISO 时间戳格式化为 `YYYY-MM-DD HH:mm`（非法值原样返回）。 */
+export declare function formatTimestamp(value: string): string;
+/** 关键词过滤实例：大小写不敏感匹配 originalInput 或 workflowId。 */
+export declare function matchesInstanceQuery(instance: InstanceSummary, query: string): boolean;
+/** 关键词过滤定义：大小写不敏感匹配 name 或 id。 */
+export declare function matchesDefinitionQuery(definition: WorkflowDefinitionEntry, query: string): boolean;
+/**
+ * 按工作区分组派生：每个工作区一个组（成员命中 `sessionIds`），未命中任何工作区的
+ * 实例归「未分组」桶（置末）。空工作区不渲染组头。
+ * @param instances - 实例摘要列表。
+ * @param workspaces - 工作区成员表（Host 稳定顺序）。
+ * @param ungroupedLabel - 未分组桶的本地化标题。
+ * @returns 有序分组列表。
+ */
+export declare function deriveGroups(instances: readonly InstanceSummary[], workspaces: readonly WorkspaceView[], ungroupedLabel: string): readonly InstanceGroup[];

package/lib/client/remote.d.ts

@@ -0,0 +1,34 @@
+/**
+ * sandore 远程客户端薄封装。
+ *
+ * 从 `dsh-sandore/remote` 默认导入生成的
+ * `TypertRemoteContribution`（供 `ctx.remote.$mount` 挂载），并暴露
+ * `RemoteResult` 解包薄封装：`ok:true` 取 `value`，`ok:false` 抛
+ * `SandoreRemoteError`（`RemoteFailure` 的 `Error` 子类包装，保留 code），
+ * 供组件层统一解包、不静默吞错。
+ * @module @deepseek-ai/dsh-client-ui-sandore/client/remote
+ */
+import type { RemoteFailure, RemoteResult } from '@deepseek-ai/dsh-typert-protocol';
+import sandoreRemote from 'dsh-sandore/remote';
+export { sandoreRemote };
+export type { PingResponse } from 'dsh-sandore/remote';
+/**
+ * 一次 sandore RPC 调用失败（`RemoteFailure` 的 `Error` 子类包装）。
+ *
+ * 保留 `code` 与 `details`，使失败分支可被统一捕获并按 code 路由，
+ * 而非静默吞掉或抛出裸对象。
+ */
+export declare class SandoreRemoteError extends Error {
+    /** Host 侧报错的稳定机器码。 */
+    readonly code: string;
+    /** Host 侧附加的错误详情（JSON 对象）。 */
+    readonly details: object;
+    constructor(failure: RemoteFailure);
+}
+/**
+ * 解包 `RemoteResult`：`ok:true` 取 `value`，`ok:false` 抛 `SandoreRemoteError`。
+ *
+ * 载波层故障已折叠进 `error` 分支，消费者无需 try/catch 恢复；仅装配性
+ * 故障（arity 不匹配、方法未挂载、缺 Context binder）仍 reject。
+ */
+export declare function unwrap<T>(result: RemoteResult<T>): T;

package/lib/client/run-view-model.d.ts

@@ -0,0 +1,304 @@
+/**
+ * RunView 的可测纯逻辑（无 React 依赖）。
+ *
+ * 从 `dsh-sandore/schema`（浏览器安全子路径）导入
+ * `WorkflowTaskState` 等 wire 类型，并以其派生 `DagRunStatus`/`StepStatus`/
+ * `ExecutedStep`/`StageInfo`（避免从包根 `types.ts` 导入带出 `dsh-llm` 依赖）。
+ * 此处提供：7 态 → StateDotState 穷尽映射、运行中/终态判定（驱动 5s 轮询）、
+ * pending 交互分类、retry message 校验与 `RetryMode` 词汇。
+ * @module @deepseek-ai/dsh-client-ui-sandore/src/client/run-view-model
+ */
+import type { StateDotState } from '@deepseek-ai/dsh-client-ui-primitives';
+import type { PendingPermissionEntry, PendingQuestionEntry, WorkflowTaskState } from 'dsh-sandore/schema';
+import type { RevertBoundaryOption } from 'dsh-sandore/types';
+/** 实例生命周期状态（从 `WorkflowTaskState` 派生，避免 dsh-llm 依赖）。 */
+export type DagRunStatus = WorkflowTaskState['status'];
+/** 单个 Step/Stage 执行状态（从 `WorkflowTaskState` 派生）。 */
+export type StepStatus = WorkflowTaskState['executedSteps'][number]['status'];
+/** 已执行 Step 的快照（从 `WorkflowTaskState` 派生）。 */
+export type ExecutedStep = WorkflowTaskState['executedSteps'][number];
+/** Stage 状态快照（从 `WorkflowTaskState` 派生）。 */
+export type StageInfo = WorkflowTaskState['stageInfos'][number];
+/** 重试模式（对齐 `retryStep` 入参 `mode` 的 zod 枚举）。 */
+export type RetryMode = 'continue' | 'revert' | 'fork';
+/** revert 回退点候选（对齐 `listRevertBoundaries` 返回的 `RevertBoundaryOption`）。 */
+export type { RevertBoundaryOption };
+/** replyQuestion 单个问题的回答（对齐 Host 的 `AskUserQuestionAnswerItem`）。 */
+export interface AnswerItem {
+    readonly id: string;
+    readonly selected: readonly string[];
+    readonly custom?: string;
+}
+/** 三种重试模式（供重试表单下拉/选项渲染）。 */
+export declare const RETRY_MODES: readonly RetryMode[];
+/**
+ * StepStatus 7 态 → StateDotState 4 态穷尽映射：
+ * `completed→done`、`failed→error`、`running→ongoing`，其余（等待用户注意的
+ * blocked/ready/interacting/paused）折入 `warning`。
+ * @param status - Step 执行状态。
+ * @returns 四态语义点。
+ */
+export declare function stepDotState(status: StepStatus): StateDotState;
+/**
+ * DagRunStatus 7 态 → StateDotState 4 态穷尽映射：
+ * `completed→done`、`failed→error`、`running→ongoing`，其余（pending/interacting/
+ * aborted/paused）折入 `warning`。
+ * @param status - 实例生命周期状态。
+ * @returns 四态语义点。
+ */
+export declare function runDotState(status: DagRunStatus): StateDotState;
+/**
+ * 实例是否处于「运行中」状态（`running`/`interacting`），决定是否启动 5s 轮询。
+ * @param status - 实例生命周期状态。
+ * @returns 运行中（需轮询）为 true。
+ */
+export declare function isRunningStatus(status: DagRunStatus): boolean;
+/**
+ * 实例是否已进入终态（`completed`/`failed`/`aborted`），终态停止轮询。
+ * @param status - 实例生命周期状态。
+ * @returns 终态为 true。
+ */
+export declare function isTerminalStatus(status: DagRunStatus): boolean;
+/** pending 交互分类结果。 */
+export interface PendingInteractionPartition {
+    /** 待答问题条目。 */
+    readonly questions: readonly PendingQuestionEntry[];
+    /** 待批权限条目。 */
+    readonly permissions: readonly PendingPermissionEntry[];
+}
+/**
+ * 按 `kind` 把 `pendingInteractions` 分为问答与权限两组。
+ *
+ * 探索修正（2026-08）：仅取 `status === 'pending'` 的条目——后端已只持久化 pending，
+ * 此处过滤是防御旧快照（含 replied/rejected 全量历史时避免讨论页复弹接管面板）。
+ * @param interactions - 实例的 pending 交互列表。
+ * @returns 问答与权限两个分组。
+ */
+export declare function partitionInteractions(interactions: readonly (PendingQuestionEntry | PendingPermissionEntry)[]): PendingInteractionPartition;
+/**
+ * 判断字符串是否为空或仅含空白（用于 retry message 等必填文本校验）。
+ * @param value - 待校验文本。
+ * @returns 空白为 true。
+ */
+export declare function isBlank(value: string): boolean;
+/**
+ * Step 对外交互标识：定义 `stepId` 优先，缺省回退唯一执行 `id`。
+ * 与引擎侧 `findStep`（先 `stepId` 后 `id` 反查）保持一致，供
+ * `pauseStep`/`resumeStep`/`retryStep` 入参使用。
+ * @param step - 含 `id` 与可选 `stepId` 的 Step 快照。
+ * @returns 可反查该 Step 的稳定标识。
+ */
+export declare function stepIdOf(step: {
+    readonly id: string;
+    readonly stepId?: string | undefined;
+}): string;
+/**
+ * 判定 Step 是否为可续接的子代理 Step（agent/skill/mcp/prompt），非 shell 合成 session。
+ *
+ * 对齐引擎侧 `recovery-manager.ts` 的 `isSubagentStep`：优先 `sessionMeta.command`
+ * （运行时 session 元数据），缺省回退 `command.type`（定义态命令类型）。shell
+ * 合成 session 无真实子代理，引擎对暂停/重试明确抛 `INVALID_OPERATION`，故 UI 不应
+ * 对其渲染 pause/resume/retry 控件；prompt 为真实子代理会话（决策 D3），与
+ * agent/skill/mcp 同语义。
+ * @param step - 已执行 Step 快照。
+ * @returns 子代理 Step（可暂停/恢复/重试）为 true。
+ */
+export declare function isSubagentStep(step: ExecutedStep): boolean;
+/** 树形导航节点类型。 */
+export type RunTreeNodeType = 'workflow' | 'stage' | 'step' | 'result' | 'artifact';
+/** 树形导航节点。 */
+export interface RunTreeNode {
+    readonly id: string;
+    readonly name: string;
+    readonly type: RunTreeNodeType;
+    /** 节点状态（workflow 为实例生命周期态；stage/step 为 Step 态；叶子无）。 */
+    readonly status?: StepStatus | DagRunStatus | undefined;
+    /** 归属 Step 的稳定标识（stepIdOf；供预览/操作反查）。 */
+    readonly stepId?: string | undefined;
+    /** 子代理会话 id（sessionMeta.childId，供「跳子会话」）。 */
+    readonly childId?: string | undefined;
+    /** 副信息（artifact 的 outputToId / 文件路径）。 */
+    readonly meta?: string | undefined;
+    /** 预览正文（result 的输出文本 / artifact 的文件路径）。 */
+    readonly text?: string | undefined;
+    readonly children?: readonly RunTreeNode[] | undefined;
+}
+/** agent 内嵌消息框的展示行（who + 正文 + 类型）。 */
+export interface ChatLine {
+    /** 行归属（`{stepName} · agent` / `{stepName} · tool`）。 */
+    readonly who: string;
+    /** 行正文（pre-wrap）。 */
+    readonly text: string;
+    /** assistant 正文行 / tool mono 行。 */
+    readonly kind: 'assistant' | 'tool';
+}
+/** 统一时间线的 Step 卡片项。 */
+export interface TimelineStepItem {
+    readonly kind: 'step';
+    readonly stepId: string;
+    readonly name: string;
+    readonly status: StepStatus;
+    /** 循环迭代标签（如 `#1.2`）。 */
+    readonly loopLabel?: string | undefined;
+    /** 段开始时间（ISO，createdAt 优先回退 updatedAt/startedAt；旧实例可能缺）。 */
+    readonly time?: string | undefined;
+    /** completed 态输出文本（text 块拼接）。 */
+    readonly outputText?: string | undefined;
+    /** failed 态错误详情。 */
+    readonly error?: string | undefined;
+    /** 收尾阶段（finalizeMeta.currentPhase：assess/ask/finalize/gate/completed；供状态按钮徽标）。 */
+    readonly finalizePhase?: string | undefined;
+    /** 收尾前一阶段（finalizeMeta.previousPhase；供 UI 展示阶段流转痕迹）。 */
+    readonly finalizePreviousPhase?: string | undefined;
+    /** 收尾错误详情（finalizeMeta.errorDetail，如门禁失败原因；failed 态附加展示）。 */
+    readonly finalizeErrorDetail?: string | undefined;
+    /** Phase B 收尾评估降级原因（finalizeMeta.assessResult.errorDetail；非 undefined 表示压缩降级，completed 态回退显示 output）。 */
+    readonly finalizeAssessErrorDetail?: string | undefined;
+    /** Phase B 收尾评估 fork 会话 id（finalizeMeta.assessResult.forkSessionId，供「收尾中」徽标点击打开）。 */
+    readonly finalizeAssessSessionId?: string | undefined;
+    /** Phase C 门禁 fork 会话 id（finalizeMeta.gateResult.gateSessionId，供「门禁中」徽标点击打开）。 */
+    readonly finalizeGateSessionId?: string | undefined;
+    /** Phase B 收尾评估结果（finalizeMeta.assessResult；completed 态展示 compressedOutput）。 */
+    readonly finalizeAssessResult?: {
+        readonly assessmentRaw: string;
+        readonly compressedOutput?: string;
+        readonly status?: 'running' | 'done';
+    } | undefined;
+    /** Phase C 门禁结果（finalizeMeta.gateResult）。 */
+    readonly finalizeGateResult?: {
+        readonly gatesPassed: boolean;
+        readonly status?: 'running' | 'done' | 'failed';
+    } | undefined;
+    /** Phase A ask 判定结果（finalizeMeta.askResult）。 */
+    readonly finalizeAskResult?: {
+        readonly hasAsk: boolean;
+        readonly askQuestion?: unknown;
+        readonly status?: 'running' | 'done';
+    } | undefined;
+    /** Phase D 路由判断结果（finalizeMeta.routingResult）。 */
+    readonly finalizeRoutingResult?: {
+        readonly branchMeta?: unknown;
+        readonly loopMeta?: unknown;
+        readonly status?: 'running' | 'done';
+    } | undefined;
+    /** Phase D 路由判断 fork 会话 id（finalizeMeta.routingResult.routingSessionId）。 */
+    readonly finalizeRoutingSessionId?: string | undefined;
+    readonly askStatus?: 'running' | 'done';
+    readonly assessStatus?: 'running' | 'done';
+    readonly gateStatus?: 'running' | 'done' | 'failed';
+    readonly routingStatus?: 'running' | 'done';
+    /** 子代理会话 id（跳「查看详情」）。 */
+    readonly childId?: string | undefined;
+    /** 命令类型（step.sessionMeta.command：'shell'/'prompt'/'agent'/'skill'/'mcp'；shell completed 直接显示命令输出）。 */
+    readonly commandType?: string | undefined;
+    /** 是否合成会话（shell 无真实子代理，标题不可点击跳子代理页）。 */
+    readonly synthetic?: boolean | undefined;
+    /** sessionMessages 展示行（内嵌消息框 / 失败·暂停最近 N 条）。 */
+    readonly messages?: readonly ChatLine[] | undefined;
+    readonly visitCount: number;
+    /** 执行段序号（同 stepId 第几次执行段；0-based，缺省 0 = 首次执行）。 */
+    readonly attemptIndex?: number | undefined;
+    /** 暂停定格时间（paused 段展示暂停提示时用）。 */
+    readonly pausedAt?: string | undefined;
+}
+/** 统一时间线的用户气泡项。 */
+export interface TimelineUserItem {
+    readonly kind: 'user';
+    readonly content: string;
+    /** 消息时间（ISO，createdAt）。 */
+    readonly time: string;
+    /** 消息种类（input/resume/retry/answer；旧实例可能缺，回退 input 语义）。 */
+    readonly messageKind?: string | undefined;
+    /** 目标：'broadcast' 或 Step 定义 id（定点）；input 时为 ''。 */
+    readonly target?: string | undefined;
+}
+/** 统一时间线条目（Step 卡片 / 用户气泡，按时间顺序）。 */
+export type TimelineItem = TimelineStepItem | TimelineUserItem;
+/** 相对时间展示结果（由组件用字典文案渲染）。 */
+export type RelativeTime = {
+    readonly kind: 'justNow';
+} | {
+    readonly kind: 'minutes';
+    readonly count: number;
+} | {
+    readonly kind: 'hours';
+    readonly count: number;
+} | {
+    readonly kind: 'days';
+    readonly count: number;
+} | {
+    readonly kind: 'date';
+    readonly text: string;
+};
+/**
+ * 计算相对时间（ISO → 刚刚 / N 分钟前 / N 小时前 / N 天前；跨 7 天回退短日期）。
+ * @param iso - 目标时间（ISO 串），undefined 返回 undefined。
+ * @param nowIso - 基准「现在」（ISO 串）。
+ * @returns 相对时间结果或 undefined。
+ */
+export declare function relativeTimeOf(iso: string | undefined, nowIso: string): RelativeTime | undefined;
+/**
+ * 把 step 的 sessionMessages 派生为展示行（agent 内嵌消息框 / 失败列表用）。
+ * tool 消息 → `┌ tool\n└ 输出摘要`（mono 行）；text/reasoning → 正文行。
+ * @param step - 已执行 Step 快照。
+ * @returns 展示行列表；无消息返回 undefined。
+ */
+export declare function chatLinesOf(step: ExecutedStep): ChatLine[] | undefined;
+/**
+ * 把 `output: ContentBlock[]` 的 text 块拼接为纯文本（无 text 块返回 undefined）。
+ * @param output - Step 执行输出块（引擎在 step-completed 事件/快照中内联）。
+ * @returns 拼接文本或 undefined。
+ */
+export declare function outputTextOf(output: readonly {
+    readonly type: string;
+    readonly text?: string;
+}[] | undefined): string | undefined;
+/** 循环迭代路径 → 展示标签（`#1.2`），非循环返回 undefined。 */
+export declare function loopLabelOf(loopIteration: readonly number[] | undefined): string | undefined;
+/** 取文件路径的 basename（兼容 / 与 \ 分隔；无分隔符时原样返回）。 */
+export declare function fileBaseName(file: string): string;
+/**
+ * 从 `WorkflowTaskState` 构建树形导航数据：workflow → stage → step → result/artifact 叶子。
+ * result 叶子来自 step 输出文本；artifact 叶子来自 `stageContracts` 产物契约的 files。
+ *
+ * Round 26：**完全按 `state.executedSteps` 渲染**——
+ * ① `executedSteps` 里**每条执行段**都展示（含 paused/failed/同 stepId 多次 visit 的
+ *    每一段，不做 attemptIndex 聚合）；
+ * ② step 按自身 `stageId` 归组到 stage 下；
+ * ③ **只展示「有 step 执行记录」的 stage**（空 stage / 尚未执行的 stage 不展示）；
+ * ④ stage 与 step 均按**创建顺序**（executedSteps 数组序 = 引擎追加序）排列。
+ * ⑤ **返回结果按执行段挂载**（每段只挂自己这段的 output 文本）；**产物按 step 级
+ *    归并、只挂到该 stepId 的「最后一段」**（loop 多次 visit 产出同一 outputTo 文件，
+ *    挂一次展示最新产物状态，避免每段重复）。
+ * 无 `stageId` 的异常段归入合成 stage「未分组」兜底（保证所有 step 可见）。
+ * @param state - 实例状态快照。
+ * @returns 树形导航根节点列表（单个 workflow 根）。
+ */
+export declare function buildRunTree(state: WorkflowTaskState): RunTreeNode[];
+/** Round 26：无 stageId 的异常执行段归入的合成 stage id（名称「未分组」）。 */
+export declare const UNASSIGNED_STAGE_ID = "_unassigned";
+/**
+ * 段模型下按「最后活跃段」聚合 Step 列表（DiscussionInput @Step 定点恢复用）。
+ *
+ * 同 stepId 多次执行段（暂停续跑/重试/ask 续问）只保留 attemptIndex 最大的段，
+ * 避免 @Step 选择器重复展示同一 Step 的多个执行段。
+ * @param steps - 实例的 executedSteps（可能含同 stepId 多段）。
+ * @returns 按 stepId 去重后的 Step 快照列表（取最后活跃段；非子代理 Step 原样保留）。
+ */
+export declare function lastActiveSegmentsOf(steps: readonly ExecutedStep[]): ExecutedStep[];
+/**
+ * 从 `WorkflowTaskState` 构建统一时间线（段模型 + 用户消息统一排序）。
+ *
+ * 三路来源严格按 `createdAt` 排序合并：
+ * 1. `userMessages`（input/resume/retry/message，含原始需求——初始 input 消息
+ *    由引擎 makeInitialState 写入，前端不再单独拼 `state.originalInput` 气泡；
+ *    Round 26：**过滤 kind:'answer'**——Phase A ask 的回答是给子代理的内部闭环
+ *    消息，不注入 discussion 时间轴；历史实例已落盘的 answer 记录同样隐藏）
+ * 2. executedSteps 各**执行段**（`createdAt` 为段开始时间；同 stepId 多次执行段
+ *    各自成卡，`attemptIndex` 标注第几次）
+ * 3. running 卡无实时消息流（引擎不写 sessionMessages、无 step-message 事件），
+ *    body 按状态展示输出文本 / 错误 / 运行中占位。
+ * @param state - 实例状态快照。
+ * @returns 时间线条目列表（按 createdAt 升序）。
+ */
+export declare function buildTimeline(state: WorkflowTaskState): TimelineItem[];

package/lib/client/sandore-save.d.ts

@@ -0,0 +1,41 @@
+/**
+ * DagEditor 保存流程的接线与错误归一化（无 React 依赖，可单测）。
+ *
+ * `createSandoreSave` 把 `ctx.remote.sandore` 的 RPC 面接成 DagEditor 的
+ * `save(id, yaml)` 回调：`id === undefined` 走 `createDefinition({ yaml })`，
+ * 否则走 `updateYaml(id, yaml)`，均经 `unwrap` 解包并返回保存后的 id。
+ * `describeSaveError` 把各类错误统一为含「校验详情」的 `SaveErrorInfo`，
+ * 供 DagEditor 的错误分支呈现，而非只回落 message 文案。
+ * @module @deepseek-ai/dsh-client-ui-sandore/src/client/sandore-save
+ */
+import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol';
+import type { WorkflowDefinitionEntry } from 'dsh-sandore/remote';
+/** `createSandoreSave` 所需的最小 remote 面（`ctx.remote.sandore` 结构满足）。 */
+export interface SandoreSaveRemote {
+    createDefinition(input: {
+        yaml: string;
+    }): Promise<RemoteResult<WorkflowDefinitionEntry>>;
+    updateYaml(id: string, yaml: string): Promise<RemoteResult<WorkflowDefinitionEntry>>;
+}
+/** DagEditor 的保存回调签名：`id` 为 `undefined` 时新建，否则更新 YAML；返回保存后的 id。 */
+export type SaveDefinition = (id: string | undefined, yaml: string) => Promise<string>;
+/**
+ * 构造 save 回调：`id === undefined` 走 `createDefinition`，否则走 `updateYaml`，
+ * 返回持久化后的 id。新建首次 `createDefinition`、后续 `updateYaml` 的行为在此成可执行路径。
+ * @param remote - `ctx.remote.sandore` 的最小 RPC 面。
+ * @returns 供 DagEditor `save` prop 直接使用的回调。
+ */
+export declare function createSandoreSave(remote: SandoreSaveRemote): SaveDefinition;
+/** 保存失败归一化结果：`details` 为可直接展示的校验详情文案（无详情时为 `undefined`）。 */
+export interface SaveErrorInfo {
+    readonly message: string;
+    readonly details: string | undefined;
+}
+/**
+ * 把保存流程抛出的任意错误归一化为含校验详情的 `SaveErrorInfo`：
+ * `SandoreRemoteError` 取 `.details`、`WorkflowYamlError` 取 `.code`/`.cause`、
+ * zod 错误取 issues 摘要，其余回落 message。
+ * @param error - 保存流程 catch 到的未知抛错值。
+ * @returns 含统一 message 与可选校验详情的归一化结果。
+ */
+export declare function describeSaveError(error: unknown): SaveErrorInfo;

package/lib/client/sandore-sse.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Sandore SSE 客户端订阅器。
+ *
+ * 用 EventSource 连接 `/sandore/events`，接收引擎推送的 sandore/* 事件。
+ * 模块级单例（多个组件共享一个 EventSource 连接）。
+ */
+type EventListener = (type: string, data: unknown) => void;
+/**
+ * 订阅 sandore SSE 事件。
+ *
+ * @param listener - 事件回调（type 事件名 + data 载荷对象）。
+ * @returns unsubscribe 函数。
+ */
+export declare function subscribeSandoreSse(listener: EventListener): () => void;
+export {};

package/lib/client/step-chat-retry.d.ts

@@ -0,0 +1,44 @@
+/**
+ * StepChatPanel 弹性化的可测纯函数：open 失败退避重试序列、binding 重解析序列、
+ * openError 展示格式化。
+ *
+ * Round 25：StepChatPanel 对子代理会话只 open 一次，`openState='error'` 后永久粘滞
+ * （挂载瞬间的瞬时失败——短 turn 子代理 settle/dispose 过渡窗口——无法自愈，面板
+ * 长期显示「子代理会话加载失败」且实时事件被丢弃）。这里定义有界退避序列供面板重试；
+ * 达上限后停在 error 占位并展示 openError（便于现场锁定确切错误码）。
+ *
+ * 另一个缺陷：子代理 settle/dispose 后 host 广播 `session-removed` → client 列表移除
+ * 该 child → `binding` 转 undefined → 面板停在「正在加载子代理会话…」。这里定义有界
+ * 列表重拉序列（host 列表包含持久化冷会话，`sessions.refresh()` 后 child 可重新绑定）。
+ *
+ * @module @deepseek-ai/dsh-client-ui-sandore/src/client/step-chat-retry
+ */
+/** open 失败重试的退避延迟（毫秒）：1s → 3s → 10s 封顶；超出返回 undefined（停止重试）。 */
+export declare const STEP_CHAT_RETRY_DELAYS_MS: readonly number[];
+/**
+ * 第 `attempt` 次 open 重试前的延迟（0-based；`attempt=0` 表示首次失败后第一次重试）。
+ * @param attempt - 已失败/已重试次数。
+ * @returns 延迟毫秒；达上限返回 undefined（不再重试）。
+ */
+export declare function stepChatRetryDelayMs(attempt: number): number | undefined;
+/** binding 缺失（settle 后 session-removed）时的列表重拉延迟序列（毫秒），有界。 */
+export declare const STEP_CHAT_REBIND_DELAYS_MS: readonly number[];
+/** binding 重解析最大次数（超出停在 loading 占位，避免对已删除 child 空转）。 */
+export declare const STEP_CHAT_MAX_REBINDS: number;
+/**
+ * 第 `attempt` 次 binding 重拉前的延迟（0-based）。
+ * @param attempt - 已重拉次数。
+ * @returns 延迟毫秒；达上限返回 undefined（停止重拉）。
+ */
+export declare function stepChatRebindDelayMs(attempt: number): number | undefined;
+/** `snapshot.openError` 的最小结构面（DSH RpcError：code/message/details）。 */
+export interface StepChatOpenErrorLike {
+    readonly code: string;
+    readonly message?: string | undefined;
+}
+/**
+ * openError → 展示文案（`code: message`；无 message 时仅 code）。
+ * @param error - `snapshot.openError`（RpcError | null）。
+ * @returns 展示文案；null/undefined 返回 undefined（不展示）。
+ */
+export declare function formatOpenError(error: StepChatOpenErrorLike | null | undefined): string | undefined;