@roaming-ai/dsh-group-chat 0.2.2 → 0.3.1

package/lib/types/client/components/AsidePanel.d.ts

@@ -1,31 +1,15 @@
 /**
- * 右侧成员与工作区栏组件
+ * 右侧成员与工作区栏组件。工作区目录编辑态（草稿、文件浏览器）为栏内自有状态。
  * @module dsh-group-chat/client/components
  */
-import type { ReactNode } from 'react';
+import { type ReactNode } from 'react';
 import { type ClientSnapshot, type SnapshotRole } from '../lib/model.ts';
 interface AsidePanelProps {
     snap: ClientSnapshot;
     group: ClientSnapshot['groups'][number];
     asideOpen: boolean;
-    wsDraft: string | null;
-    setWsDraft: (val: string | null) => void;
-    fileBrowser: {
-        open: boolean;
-        loading: boolean;
-        list: import('../../core/types.ts').BrowseResult | null;
-        error: string;
-    } | null;
-    setFileBrowser: (val: {
-        open: boolean;
-        loading: boolean;
-        list: import('../../core/types.ts').BrowseResult | null;
-        error: string;
-    } | null) => void;
     mutate: (args: Record<string, unknown>) => Promise<unknown>;
-    openRoleEditor: (role: SnapshotRole | null) => Promise<void>;
-    openBrowser: (path: string | undefined) => Promise<void>;
-    selectCurrentDir: () => void;
+    openRoleEditor: (role: SnapshotRole | null) => void;
 }
 export declare function AsidePanel(props: AsidePanelProps): ReactNode;
 export {};

package/lib/types/client/components/Bubble.d.ts

@@ -8,12 +8,15 @@
  * @module dsh-group-chat/client/Bubble
  */
 import { type ReactNode } from 'react';
-import { type ClientSnapshot, type SnapshotRole } from '../lib/model.ts';
+import { type SnapshotRole } from '../lib/model.ts';
+import type { SnapshotMessage } from '../lib/model.ts';
 export interface BubbleProps {
-    m: ClientSnapshot['messages'][number];
+    m: SnapshotMessage;
     /** 父级解析好的发言角色（user/system 消息为 null）——避免 Bubble 依赖 snap identity。 */
     role: SnapshotRole | null;
+    busy?: boolean;
+    onRetry?: (messageId: string) => void;
 }
-declare function BubbleInner({ m, role }: BubbleProps): ReactNode;
+declare function BubbleInner({ m, role, busy, onRetry }: BubbleProps): ReactNode;
 export declare const Bubble: import("react").MemoExoticComponent<typeof BubbleInner>;
 export {};

package/lib/types/client/components/ChatPanel.d.ts

@@ -52,6 +52,7 @@ interface ChatPanelProps {
     action: (payload: Record<string, unknown>) => Promise<unknown>;
     mutate: (args: Record<string, unknown>) => Promise<unknown>;
     setMention: (val: AtToken | null) => void;
+    onRetrySpeak: (messageId: string) => void;
 }
 export declare function ChatPanel(props: ChatPanelProps): ReactNode;
 export {};

package/lib/types/client/components/ConstraintList.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 会话流折点处：只读结论备忘卡（超过 4 条默认露 3 条）。
+ * @module dsh-group-chat/client/components
+ */
+import { type ReactNode } from 'react';
+import type { SessionConstraint } from '../../core/types.ts';
+interface ConstraintListProps {
+    items: SessionConstraint[];
+}
+export declare function ConstraintList(props: ConstraintListProps): ReactNode;
+export {};

package/lib/types/client/components/FailCard.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 角色发言失败卡：人话标题 + 可展开原文。操作条由 Bubble 放在气泡外下方。
+ * @module dsh-group-chat/client/FailCard
+ */
+import { type ReactNode } from 'react';
+export interface FailCardProps {
+    raw: string;
+}
+export declare function FailCard(props: FailCardProps): ReactNode;

package/lib/types/client/components/Fold.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 会话内折叠：高度 0fr→1fr + 溢出滚动遮罩。思考 / 工具 / 失败原文 / 结论备忘共用。
+ * @module dsh-group-chat/client/components
+ */
+import { type ReactNode } from 'react';
+interface FoldProps {
+    open: boolean;
+    children: ReactNode;
+    className?: string;
+}
+export declare function Fold(props: FoldProps): ReactNode;
+interface ClipWellProps {
+    children: ReactNode;
+    maxHeight: number;
+    className?: string;
+    watch?: unknown;
+}
+export declare function ClipWell(props: ClipWellProps): ReactNode;
+export {};

package/lib/types/client/components/HoverTip.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 对齐宿主 Tooltip 的 hover 气泡：portal 到 document.body，躲开
+ * `.dsgc-root` 的 container-type 把 position:fixed 按容器定位。
+ * @module dsh-group-chat/client/components
+ */
+import { type ReactNode } from 'react';
+export type HoverTipSide = 'top' | 'right';
+interface HoverTipProps {
+    label: string;
+    side?: HoverTipSide;
+    delayMs?: number;
+    maxWidth?: number;
+    className?: string;
+    children: ReactNode;
+}
+/**
+ * @param props.label 气泡正文（pre-line）
+ * @param props.side 默认 right（对齐侧栏会话行）；composer 轮数用 top
+ * @param props.delayMs hover 延迟，默认 500；键盘 focus 立即出
+ */
+export declare function HoverTip(props: HoverTipProps): ReactNode;
+export {};

package/lib/types/client/components/MessageFlow.d.ts

@@ -10,6 +10,7 @@ interface MessageFlowProps {
     busyNow: boolean;
     msgById: Record<string, ClientSnapshot['messages'][number]>;
     action: (payload: Record<string, unknown>) => Promise<unknown>;
+    onRetrySpeak: (messageId: string) => void;
 }
 export declare function MessageFlow(props: MessageFlowProps): ReactNode;
 export {};

package/lib/types/client/components/MsgActions.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 消息操作条：贴在气泡外下方。用户/角色消息悬停出「复制」；失败卡常驻「复制 / 重试」。
+ * @module dsh-group-chat/client/MsgActions
+ */
+import { type ReactNode } from 'react';
+export interface MsgActionsProps {
+    copyText: string;
+    onRetry?: () => void;
+    retryDisabled?: boolean;
+    retryTitle?: string;
+    /** 失败卡：不依赖悬停，始终可见。 */
+    always?: boolean;
+}
+export declare function MsgActions(props: MsgActionsProps): ReactNode;

package/lib/types/client/components/NavPanel.d.ts

@@ -1,9 +1,15 @@
 /**
- * 左侧导航栏组件
+ * 左侧导航栏组件（群组 → 会话目录树；群组行与会话行共用重命名/删除三件套）。
  * @module dsh-group-chat/client/components
  */
 import type { ReactNode } from 'react';
 import { type ClientSnapshot } from '../lib/model.ts';
+/** 目录树节点编辑态形状（群组/会话共用）。 */
+type NodeEdit = {
+    kind: 'group' | 'session';
+    id: string;
+    value: string;
+};
 interface NavPanelProps {
     snap: ClientSnapshot;
     search: string;
@@ -15,16 +21,8 @@ interface NavPanelProps {
     setGid: (val: string) => void;
     setSid: (val: string) => void;
     setPartsSel: (val: string[] | null) => void;
-    renameDraft: {
-        kind: 'group' | 'session';
-        id: string;
-        value: string;
-    } | null;
-    setRenameDraft: (val: {
-        kind: 'group' | 'session';
-        id: string;
-        value: string;
-    } | null) => void;
+    renameDraft: NodeEdit | null;
+    setRenameDraft: (val: NodeEdit | null) => void;
     confirmDel: {
         kind: 'group' | 'session';
         id: string;

package/lib/types/client/components/RoleDrawer.d.ts

@@ -7,11 +7,12 @@ import { type ModelsResponse, type RoleDraft } from '../lib/model.ts';
 export interface RoleDrawerProps {
     draft: RoleDraft;
     set: (draft: RoleDraft) => void;
+    /** 保存目标群组（upsertRole 落库）。 */
+    groupId: string;
     models: ModelsResponse | null;
     modelsError: string | null;
     onRetryModels: () => void;
-    onSave: () => void;
+    mutate: (args: Record<string, unknown>) => Promise<unknown>;
     onCancel: () => void;
-    formError: string;
 }
 export declare function RoleDrawer(props: RoleDrawerProps): ReactNode;

package/lib/types/client/components/ToolRow.d.ts

@@ -3,7 +3,7 @@
  * @module dsh-group-chat/client/ToolRow
  */
 import { type ReactNode } from 'react';
-import type { ToolCallView } from '../lib/model.ts';
+import type { ToolCallRecord } from '../../core/types.ts';
 export declare function ToolRow(props: {
-    c: ToolCallView;
+    c: ToolCallRecord;
 }): ReactNode;

package/lib/types/client/hooks/useComposer.d.ts

@@ -8,13 +8,18 @@ import type { SnapshotRole } from '../lib/model.ts';
 export declare function useComposerEffects(inputRef: React.RefObject<HTMLDivElement>, scrollRef: React.RefObject<HTMLDivElement>, input: string, atBottom: boolean, snap: unknown): {
     onMsgsScroll: () => boolean | undefined;
 };
-export declare function useComposerInput(inputRef: React.RefObject<HTMLDivElement>, setInput: (val: string) => void, setMention: (val: AtToken | null) => void, setMentionIdx: (val: number) => void): {
+export declare function useComposerInput(inputRef: React.RefObject<HTMLDivElement>, setInput: (val: string) => void, setMention: (val: AtToken | null) => void, setMentionIdx: (val: number) => void, sessionId?: string | null): {
     syncFromDOM: () => void;
     onInputCE: () => void;
     onPasteCE: (e: ReactClipboardEvent<HTMLDivElement>) => void;
     onDragOverCE: (e: ReactDragEvent<HTMLDivElement>) => void;
     onDropCE: (e: ReactDragEvent<HTMLDivElement>) => void;
 };
+/**
+ * 按会话恢复草稿：切会话时先把当前 HTML 写入旧槽，再灌入新槽；
+ * 面板重挂载（主会话⇄群聊）时 editor 是新节点，从模块缓存灌回。
+ */
+export declare function useComposerDraft(sessionId: string | null | undefined, inputRef: React.RefObject<HTMLDivElement>, setInput: (val: string) => void, setMention: (val: AtToken | null) => void): void;
 export declare function useMentionChip(inputRef: React.RefObject<HTMLDivElement>, setMention: (val: AtToken | null) => void, setMentionIdx: (val: number) => void, syncFromDOM: () => void): {
     insertChip: (role: SnapshotRole) => void;
     insertFileChip: (path: string, kind: "file" | "directory") => void;

package/lib/types/client/hooks/useGroupChatState.d.ts

@@ -47,26 +47,10 @@ export declare function useGroupChatState(): {
     setConfirmClear: import("react").Dispatch<import("react").SetStateAction<boolean>>;
     roleDraft: RoleDraft | null;
     setRoleDraft: import("react").Dispatch<import("react").SetStateAction<RoleDraft | null>>;
-    roleFormError: string;
-    setRoleFormError: import("react").Dispatch<import("react").SetStateAction<string>>;
     models: ModelsResponse | null;
     setModels: import("react").Dispatch<import("react").SetStateAction<ModelsResponse | null>>;
     modelsError: string | null;
     setModelsError: import("react").Dispatch<import("react").SetStateAction<string | null>>;
-    fileBrowser: {
-        open: boolean;
-        loading: boolean;
-        list: import("../../core/types.ts").BrowseResult | null;
-        error: string;
-    } | null;
-    setFileBrowser: import("react").Dispatch<import("react").SetStateAction<{
-        open: boolean;
-        loading: boolean;
-        list: import("../../core/types.ts").BrowseResult | null;
-        error: string;
-    } | null>>;
-    wsDraft: string | null;
-    setWsDraft: import("react").Dispatch<import("react").SetStateAction<string | null>>;
     partsSel: string[] | null;
     setPartsSel: import("react").Dispatch<import("react").SetStateAction<string[] | null>>;
     rounds: number;

package/lib/types/client/lib/composer-draft.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 未发送草稿：按会话 id 分槽，模块级跨挂载存活。
+ * 主会话⇄群聊会整页卸载 composer，contentEditable 的 HTML 必须自行记住。
+ * @module dsh-group-chat/client/composer-draft
+ */
+export interface ComposerDraft {
+    html: string;
+    text: string;
+}
+/** 读指定会话草稿；命中则提到 LRU 最近端。 */
+export declare function readComposerDraft(sessionId: string | null | undefined): ComposerDraft;
+/** 写入；空草稿删槽。超出上限淘汰最旧槽。 */
+export declare function writeComposerDraft(sessionId: string | null | undefined, html: string, text: string): void;
+/** 发送成功或明确丢弃时摘槽。 */
+export declare function clearComposerDraft(sessionId: string | null | undefined): void;
+/** 测试用：清空全部槽位。 */
+export declare function resetComposerDrafts(): void;

package/lib/types/client/lib/model.d.ts

@@ -2,7 +2,7 @@
  * 浏览器半共享常量与小工具（纯函数，无 React 依赖）。
  * @module dsh-group-chat/client/model
  */
-import type { RoleRecord, Snapshot, ToolCallRecord } from '../../core/types.ts';
+import type { Snapshot } from '../../core/types.ts';
 /** 会话列表状态派生与文案（core 纯函数，供 NavPanel 渲染）。 */
 export { sessStatus, SESS_STATUS_LABEL, type SessStatus } from '../../core/status.ts';
 /** 角色标识色调色板（与宿主半一致）。 */
@@ -72,9 +72,3 @@ export interface RoleDraft {
 }
 export declare function draftFromRole(role: SnapshotRole): RoleDraft;
 export declare function blankDraft(): RoleDraft;
-/** 工具调用行的展示参数。 */
-export type ToolCallView = ToolCallRecord;
-/** 草稿是否可作为角色落库（宿主侧再校验一次）。 */
-export declare function draftMissing(draft: RoleDraft): string;
-/** RoleRecord 兼容视图（快照角色行即其展示子集）。 */
-export type RoleView = RoleRecord;

package/lib/types/client/utils/utils.d.ts

@@ -13,14 +13,14 @@ export declare function execCommand(commandId: 'delete' | 'insertHTML' | 'insert
  * DIV/P 块前补换行（防粘贴残留的块级包裹）。
  */
 export declare function serializeInput(root: HTMLElement): string;
-/** @角色芯片的 HTML（原子元素：contenteditable=false + draggable，退格整删）。 */
+/** @角色芯片的 HTML（原子元素：contenteditable=false + draggable，退格整删；fresh=插入后需营救选区，加 data-new 标记）。 */
 export declare function chipHtml(role: {
     id: string;
     name: string;
     color?: string;
-}): string;
-/** @文件芯片的 HTML（原子元素：contenteditable=false + draggable，退格整删）。 */
-export declare function fileChipHtml(path: string, kind: 'file' | 'directory'): string;
+}, fresh?: boolean): string;
+/** @文件芯片的 HTML（原子元素：contenteditable=false + draggable，退格整删；fresh 同 chipHtml）。 */
+export declare function fileChipHtml(path: string, kind: 'file' | 'directory', fresh?: boolean): string;
 /**
  * 光标前的活跃 @token（角色或文件弹层触发判定）。
  *

package/lib/types/core/constraints.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 会话约束备忘纯逻辑：滑动 40 条窗口、挤出集、压行、临时原文、解析与截断。
+ * @module dsh-group-chat/core/constraints
+ */
+import { type MessageRecord, type SessionConstraint, type SessionRecord } from './types.ts';
+/** 当场原文窗口（含系统行）。 */
+export declare const WINDOW_SIZE = 40;
+/** 折叠失败时临时原文条数上限。 */
+export declare const TEMP_MAX_MESSAGES = 20;
+/** 折叠失败时临时原文总长上限。 */
+export declare const TEMP_MAX_CHARS = 16000;
+/** 单轮折叠最多消耗的挤出条数（含系统行；超出留待下一轮）。 */
+export declare const FOLD_MAX_MESSAGES = 40;
+/** 单轮折叠输入总长上限（格式化后）。 */
+export declare const FOLD_MAX_CHARS = 16000;
+/** 备忘条数上限。 */
+export declare const CONSTRAINT_MAX_ITEMS = 12;
+/** 备忘总长上限（条目前缀+正文）。 */
+export declare const CONSTRAINT_MAX_CHARS = 1200;
+/** 单条备忘正文上限。 */
+export declare const CONSTRAINT_ITEM_MAX_CHARS = 160;
+export declare const KIND_LABEL: Record<SessionConstraint['kind'], string>;
+/** 已折入水位（缺省 0）。 */
+export declare function constraintsWatermark(sess: SessionRecord): number;
+/** 重试：只取失败卡之前的时间线；untilId 不在列表则原样。 */
+export declare function prefixIds(ids: string[], untilId?: string): string[];
+/**
+ * 新挤出：seq > 水位 且不在最近 40 条。只扫窗口外前缀（旧→新）。
+ * untilId：重试时把窗口截到该消息之前，不带上后面已经发生的发言。
+ */
+export declare function squeezedMessages(messages: Map<string, MessageRecord>, sess: SessionRecord, untilId?: string): MessageRecord[];
+/** 说话人展示名（折叠输入 / transcript 共用）。 */
+export declare function speakerLabel(speaker: string, roleName?: string): string;
+/** 单条消息压成 transcript 行（正文 8k + 工具一行摘要）。 */
+export declare function formatTranscriptLine(m: MessageRecord, name: string): string;
+/**
+ * 单轮折叠消耗前缀：从最旧挤出起，最多 40 条 / 16k；系统行与失败卡计入消耗但不进模型。
+ * 水位只能推到 consumed 的 max seq，剩余留待下一轮。
+ */
+export declare function takeFoldBatch(squeezed: MessageRecord[], nameOf: (m: MessageRecord) => string): {
+    consumed: MessageRecord[];
+    lines: string[];
+    hasUser: boolean;
+    allSystem: boolean;
+};
+/**
+ * 未折入的挤出原文（失败缓冲）：只格式化最近 20 条，再按 16k 从最旧往下丢。
+ */
+export declare function tempTranscript(squeezed: MessageRecord[], nameOf: (m: MessageRecord) => string): string;
+/** 水位 = 本批挤出的 max(seq)；空批为 0。 */
+export declare function squeezedMaxSeq(squeezed: MessageRecord[]): number;
+/** hydrate / 模型输出：非法 kind 丢条目；空 text 丢；条数与总长截断。 */
+export declare function sanitizeConstraints(raw: unknown): SessionConstraint[];
+/**
+ * 解析折叠模型输出。null = 解析失败（水位不推）；[] = 无新结论（水位推、备忘不动）。
+ */
+export declare function parseConstraints(raw: string): SessionConstraint[] | null;
+/** 本批无用户消息时，新的已定/否决降为未决。 */
+export declare function downgradeWithoutUser(list: SessionConstraint[], hasUser: boolean): SessionConstraint[];
+/** system 提示词「已确认约束」块；空则空串。 */
+export declare function constraintBlock(list: SessionConstraint[] | undefined): string;

package/lib/types/core/errors.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 角色发言失败：供应商原文 → 人话标题/原因（core 纯函数，无 React）。
+ * 原始 JSON 仍落盘在消息 text 里，UI 默认只展示短因，展开才看原文。
+ * @module dsh-group-chat/core/errors
+ */
+export interface SpeakFailureView {
+    /** 一行标题，例如「额度已用尽」。 */
+    title: string;
+    /** 可选短因：重置时间、HTTP 状态等。 */
+    detail?: string;
+    /** 复制/排障用的供应商原文（已剥「模型输出异常终止: 」前缀）。 */
+    raw: string;
+}
+/** 剥旧系统胶囊与引擎包装前缀，保留供应商原文。 */
+export declare function unwrapSpeakFailure(raw: string): string;
+/** 旧系统胶囊文案：角色「名」发言失败：原文。对不上则 null。 */
+export declare function parseLegacyRoleFailure(text: string): {
+    roleName: string;
+    rest: string;
+} | null;
+export interface RoleRef {
+    id: string;
+    name: string;
+    provider?: string;
+    model?: string;
+}
+export interface FailedMessageRef {
+    speaker: string;
+    text: string;
+    error?: boolean;
+    failedRoleId?: string;
+}
+/** 发言失败卡：error 标记，或旧系统胶囊文案。 */
+export declare function isSpeakFailure(m: FailedMessageRef): boolean;
+/** 失败回合对应角色：failedRoleId / speaker / 旧文案里的角色名（恰好一名才命中）。 */
+export declare function resolveFailedRole<T extends RoleRef>(m: FailedMessageRef, roles: T[]): T | null;
+/**
+ * 把旧系统失败行挂到对应角色（恰好一名命中才迁）。
+ * 返回是否改写了记录。
+ */
+export declare function repairFailedMessage(m: {
+    speaker: string;
+    text: string;
+    error?: boolean;
+    failedRoleId?: string;
+    model?: string;
+}, roles: RoleRef[]): boolean;
+/**
+ * 把供应商错误压成可扫描的标题 + 短因。
+ * 未知形态回退为「发言失败」，原文仍可展开。
+ */
+export declare function classifySpeakFailure(raw: string): SpeakFailureView;
+/** 失败卡默认复制内容：标题 + 短因 + 原文。 */
+export declare function formatSpeakFailureCopy(view: SpeakFailureView): string;

package/lib/types/core/json.d.ts

@@ -7,3 +7,9 @@ import type { MessageRecord, RoleRecord } from './types.ts';
 export declare function messageJson(m: Partial<MessageRecord> | undefined): Record<string, unknown> | null;
 /** 角色 → 落盘 JSON（groupId 由目录归属，不再写入）。 */
 export declare function roleJson(r: Partial<RoleRecord>): Record<string, unknown>;
+/**
+ * 宽容 JSON 提取（模型输出/供应商错误原文的统一解析入口）：
+ * 取首个 { 至末个 } 的片段解析，仅接受普通对象；失败返回 null。
+ * 代码围栏剥离由调用方按需先行处理（供应商错误原文不剥）。
+ */
+export declare function looseJson(raw: string): Record<string, unknown> | null;

package/lib/types/core/types.d.ts

@@ -29,6 +29,17 @@ export interface GroupRecord {
     roleIds: string[];
     sessionIds: string[];
 }
+/** 会话约束条目类型（窗口外结论/约束备忘）。 */
+export type ConstraintKind = 'decided' | 'rejected' | 'open';
+/** 全部合法约束类型。 */
+export declare const CONSTRAINT_KINDS: readonly ConstraintKind[];
+/** 合法 kind 原样，其余 undefined。 */
+export declare function asConstraintKind(value: unknown): ConstraintKind | undefined;
+/** 一条无主结论/约束（已定 / 否决 / 未决）。 */
+export interface SessionConstraint {
+    kind: ConstraintKind;
+    text: string;
+}
 /** 会话：消息挂在会话上。 */
 export interface SessionRecord {
     id: string;
@@ -39,6 +50,10 @@ export interface SessionRecord {
     namePinned?: boolean;
     /** 主题已被手动编辑：自动整理永久跳过（隐式固定）。 */
     topicPinned?: boolean;
+    /** 窗口外结论/约束备忘；空则省略。 */
+    constraints?: SessionConstraint[];
+    /** 已折入备忘的最大消息 seq；0/缺省 = 尚未折过。 */
+    constraintsUpToSeq?: number;
     messageIds: string[];
     createdAt: number;
 }
@@ -76,6 +91,8 @@ export interface MessageRecord {
     thinkingSummary?: string;
     model?: string;
     error?: boolean;
+    /** 发言失败时的角色 id；刷新后仍可对该条点重试。角色消息 speaker 即角色 id，此字段冗余兼容旧系统错误行。 */
+    failedRoleId?: string;
     toolCalls?: ToolCallRecord[];
     ts: number;
 }
@@ -114,6 +131,8 @@ export interface RunState {
     childProc: import('node:child_process').ChildProcess | null;
     /** 最近一次 run 的结束标记：会话列表「已完成/已出错」状态的数据源。 */
     finished: RunFinished | null;
+    /** 原地重试时被覆盖的失败消息 id；普通 send 为 null。 */
+    replaceMessageId: string | null;
 }
 /** 角色发言的引擎产物。 */
 export interface SpeakResult {
@@ -174,75 +193,72 @@ export interface FileSearchResult {
     }[];
     error?: string;
 }
-/** 发到客户端的全量快照（wire 形态）。 */
+/** 快照内的会话行（wire 形态：不含 hydrate 用的固定标记与折入水位）。 */
+export type SnapshotSession = Omit<SessionRecord, 'namePinned' | 'topicPinned' | 'constraintsUpToSeq'>;
+/** 快照内的消息行（wire 形态：思考全文与摘要不外发）。 */
+export type SnapshotMessage = Omit<MessageRecord, 'reasoningFull' | 'thinkingSummary'>;
+/** 发到客户端的全量快照（wire 形态；各表行由领域记录派生，字段增删由编译器同步）。 */
 export interface Snapshot {
     revision: number;
-    run: {
-        running: boolean;
-        sessionId: string | null;
-        currentRoleId: string | null;
-        partial: string;
-        partialReasoning: string;
-        pendingConfirm: PendingConfirm | null;
-        finished: RunFinished | null;
-    };
+    run: Omit<RunState, 'stopping' | 'queue' | 'confirmSignal' | 'childProc'>;
     lastCreated: LastCreated | null;
-    groups: {
-        id: string;
-        name: string;
-        workspaceDir: string;
-        permissionTier: PermissionTier;
-        roleIds: string[];
-        sessionIds: string[];
-    }[];
-    sessions: {
-        id: string;
-        groupId: string;
-        name: string;
-        topic: string;
-        messageIds: string[];
-        createdAt: number;
-    }[];
-    roles: {
-        id: string;
-        groupId: string;
-        name: string;
-        color?: string;
-        persona: string;
-        provider: string;
-        model: string;
-        temperature?: number;
-        reasoningEffort?: string;
-        enabled: boolean;
-        thinking: boolean;
-    }[];
-    messages: {
-        id: string;
-        sessionId: string;
-        seq: number;
-        speaker: string;
-        text: string;
-        reasoning?: string;
-        model?: string;
-        error?: boolean;
-        toolCalls?: ToolCallRecord[];
-        ts: number;
-    }[];
+    groups: GroupRecord[];
+    sessions: SnapshotSession[];
+    roles: RoleRecord[];
+    messages: SnapshotMessage[];
     error?: string;
 }
-/** mutate 动作的参数形态（op 分发见 host/service）。 */
-export interface MutateArgs {
-    op: string;
-    groupId?: string;
-    sessionId?: string;
-    roleId?: string;
-    role?: Partial<RoleRecord>;
+/** mutate 动作的参数形态（判别联合：按 op 收窄各分支字段；wire 上字段可缺，消费方各自守卫）。 */
+export type MutateArgs = {
+    op: 'createGroup';
+    name?: string;
+} | {
+    op: 'renameGroup';
+    groupId: string;
     name?: string;
+} | {
+    op: 'deleteGroup';
+    groupId: string;
+} | {
+    op: 'createSession';
+    groupId: string;
+    name?: string;
+} | {
+    op: 'renameSession';
+    sessionId: string;
+    name?: string;
+} | {
+    op: 'deleteSession';
+    sessionId: string;
+} | {
+    op: 'setTopic';
+    sessionId: string;
     topic?: string;
+} | {
+    op: 'upsertRole';
+    groupId: string;
+    role?: Partial<RoleRecord>;
+} | {
+    op: 'deleteRole';
+    roleId: string;
+} | {
+    op: 'setRoleEnabled';
+    roleId: string;
+    enabled?: boolean;
+} | {
+    op: 'setWorkspaceDir';
+    groupId: string;
     path?: string;
+} | {
+    op: 'setPermissionTier';
+    groupId: string;
     tier?: string;
-    enabled?: boolean;
-}
+} | {
+    op: 'ackFinish';
+} | {
+    op: 'clearMessages';
+    sessionId: string;
+};
 /** send 动作的参数形态。 */
 export interface SendArgs {
     sessionId: string;

package/lib/types/host/api/actions.d.ts

@@ -1,6 +1,6 @@
 /**
  * 动作分发（handleAction，POST /api/group-chat/action 的载荷）：
- * mutate（12 种 CRUD/配置操作）| send | stop | confirmCommand | models | efforts。
+ * mutate（12 种 CRUD/配置操作）| send | retrySpeak | stop | confirmCommand | models | efforts。
  * @module dsh-group-chat/host/api/actions
  */
 import type { Snapshot } from '../../core/types.ts';