@khorsheed/dsh-client-message-tools 0.1.0

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

@@ -0,0 +1,44 @@
+/**
+ * Slot-facing types of the message-tools client half: the injected action
+ * face and the composed props of its two `conversation.chat.node` entries.
+ */
+import type { ModelSelection } from '@deepseek-ai/dsh-api-remotes/client';
+import type { ModelDirectoryState } from '@deepseek-ai/dsh-client-ui-model-selection/client';
+import type { HostObservable, InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+/** Injected action face of the shadowed user-message entry. */
+export interface MessageToolsInjected {
+    hooks: {
+        /** The session's shared model directory (the composer seat's own store; a frozen empty stub when ui-model-selection is absent). */
+        modelDirectory: HostObservable<ModelDirectoryState>;
+    };
+    /** Whether the editor's model chip can switch models in this session. */
+    modelsAvailable: boolean;
+    /** Refresh the advisory model directory (fire-and-forget; errors land on the store). */
+    loadModels: () => void;
+    /** Submit a provider/model/effort selection; resolves to host acceptance. */
+    selectModel: (selection: ModelSelection) => Promise<boolean>;
+    /**
+     * Edit one user message in place: replace it (and the surface tail) with
+     * the edited text, then start the regeneration turn.
+     */
+    editMessage: (targetSeq: number, text: string) => Promise<void>;
+    /** Withdraw one user message and everything after it. */
+    withdrawMessage: (targetSeq: number) => Promise<void>;
+    /**
+     * Backfill text into the session's composer draft (append on a new line
+     * when the draft is non-empty) and surface an info notice; never sends.
+     * Wired to a successful withdrawal — the「重新编辑」divider action shares
+     * the same path.
+     */
+    backfillDraft: (text: string) => void;
+}
+/** Full props of the shadowed 'user'/'steering'/'message-tools-edited'/'message-tools-restored' renderer (all keys share it). */
+export type UserMessageViewProps = PropsRuntime<'conversation.chat.node', 'user' | 'steering' | 'message-tools-edited' | 'message-tools-restored'> & InjectFace<MessageToolsInjected> & PropsLocale<'message-tools'>;
+/** Injected action face of the withdrawal divider entry. */
+export interface WithdrawnDividerInjected {
+    /** Restore the span's withdrawn user message as a fresh tail message. */
+    restoreMessage: (targetSeq: number) => Promise<void>;
+}
+/** Full props of the withdrawal divider renderer. */
+export type WithdrawnDividerViewProps = PropsRuntime<'conversation.chat.node', 'message-tools-withdrawn'> & InjectFace<WithdrawnDividerInjected> & PropsLocale<'message-tools'>;
+//# sourceMappingURL=slots.d.ts.map

package/lib/types/client/slots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slots.d.ts","sourceRoot":"","sources":["../../../src/client/slots.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAA;AACzE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mDAAmD,CAAA;AAC5F,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAA;AAO7G,+DAA+D;AAC/D,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE;QACL,mIAAmI;QACnI,cAAc,EAAE,cAAc,CAAC,mBAAmB,CAAC,CAAA;KACpD,CAAA;IACD,yEAAyE;IACzE,eAAe,EAAE,OAAO,CAAA;IACxB,wFAAwF;IACxF,UAAU,EAAE,MAAM,IAAI,CAAA;IACtB,6EAA6E;IAC7E,WAAW,EAAE,CAAC,SAAS,EAAE,cAAc,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAC5D;;;OAGG;IACH,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/D,yDAAyD;IACzD,eAAe,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACrD;;;;;OAKG;IACH,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CACtC;AAED,iIAAiI;AACjI,MAAM,MAAM,oBAAoB,GAC9B,YAAY,CAAC,wBAAwB,EAAE,MAAM,GAAG,UAAU,GAAG,sBAAsB,GAAG,wBAAwB,CAAC,GAC7G,UAAU,CAAC,oBAAoB,CAAC,GAChC,WAAW,CAAC,eAAe,CAAC,CAAA;AAEhC,4DAA4D;AAC5D,MAAM,WAAW,wBAAwB;IACvC,yEAAyE;IACzE,cAAc,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACrD;AAED,qDAAqD;AACrD,MAAM,MAAM,yBAAyB,GACnC,YAAY,CAAC,wBAAwB,EAAE,yBAAyB,CAAC,GAC/D,UAAU,CAAC,wBAAwB,CAAC,GACpC,WAAW,CAAC,eAAe,CAAC,CAAA"}

package/lib/types/client/slots.js

@@ -0,0 +1 @@
+export {};

package/lib/types/client/withdraw-backfill.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Withdraw-with-backfill choreography for the shadowed user renderer: a
+ * successful withdrawal automatically backfills the withdrawn message's
+ * original text into the session composer draft (never sends); a failed
+ * withdrawal backfills nothing. Kept free of services so the unit tests
+ * drive it with stub verbs (the edit-in-place.ts pattern). The in-place EDIT
+ * path never goes through here — editing has its own channel.
+ */
+/** The verbs of one withdraw-with-backfill, bound to a session by the caller. */
+export interface WithdrawBackfillSteps {
+    /** Withdraw the target message (rejects on failure). */
+    withdraw: () => Promise<void>;
+    /** Backfill text into the composer draft. */
+    backfill: (text: string) => void;
+}
+/**
+ * Withdraw one message, then backfill its text into the draft — only after
+ * the withdrawal lands, and only when there is text to fill (an image-only
+ * message has no draft-worthy text).
+ * @param steps - the withdraw/backfill verbs.
+ * @param text - the withdrawn message's original text.
+ * @returns completion; a failed withdrawal rejects without backfilling.
+ */
+export declare function withdrawAndBackfill(steps: WithdrawBackfillSteps, text: string): Promise<void>;
+//# sourceMappingURL=withdraw-backfill.d.ts.map

package/lib/types/client/withdraw-backfill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withdraw-backfill.d.ts","sourceRoot":"","sources":["../../../src/client/withdraw-backfill.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,iFAAiF;AACjF,MAAM,WAAW,qBAAqB;IACpC,wDAAwD;IACxD,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7B,6CAA6C;IAC7C,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CACjC;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,qBAAqB,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGnG"}

package/lib/types/client/withdraw-backfill.js

@@ -0,0 +1,21 @@
+/**
+ * Withdraw-with-backfill choreography for the shadowed user renderer: a
+ * successful withdrawal automatically backfills the withdrawn message's
+ * original text into the session composer draft (never sends); a failed
+ * withdrawal backfills nothing. Kept free of services so the unit tests
+ * drive it with stub verbs (the edit-in-place.ts pattern). The in-place EDIT
+ * path never goes through here — editing has its own channel.
+ */
+/**
+ * Withdraw one message, then backfill its text into the draft — only after
+ * the withdrawal lands, and only when there is text to fill (an image-only
+ * message has no draft-worthy text).
+ * @param steps - the withdraw/backfill verbs.
+ * @param text - the withdrawn message's original text.
+ * @returns completion; a failed withdrawal rejects without backfilling.
+ */
+export async function withdrawAndBackfill(steps, text) {
+    await steps.withdraw();
+    if (text !== '')
+        steps.backfill(text);
+}

package/lib/types/client/withdrawn-node.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Withdrawal projection on the chat node store: the Definition that claims
+ * message-tools replacement events into divider rows, the Definitions that
+ * claim message-tools restore events into replayed rows (user-message bubbles
+ * and assistant-text lines), the Definition that claims edit replacements
+ * into edited bubbles, plus the pure folds the renderers use (hidden spans,
+ * span counts, read-only replay entries). The assembler matches every
+ * Definition per event and offers no suppression seam; hiding happens in the
+ * renderers and the DOM hider.
+ */
+import type { ChatConversationViewNode, ConversationNodeDefinition } from '@deepseek-ai/dsh-client-runtime/client';
+/** Chat node data of one withdrawal divider row. */
+export interface WithdrawnDividerData {
+    /** Seq of the replacement event; the divider anchors here and the hidden span ends (exclusive). */
+    readonly seq: number;
+    /** First hidden seq: the withdrawn user message itself. */
+    readonly hiddenStartSeq: number;
+}
+/** Chat node data of one edited-message bubble row (the edit replacement itself). */
+export interface EditedMessageData {
+    /** Seq of the edit replacement event; the bubble anchors here and the hidden span ends (exclusive). */
+    readonly seq: number;
+    /** Unix epoch ms from the edit replacement event. */
+    readonly time: number;
+    /** The edited content (what the model now reads in place). */
+    readonly content: readonly unknown[];
+    /** First hidden seq: the pre-edit message the replacement covers. */
+    readonly hiddenStartSeq: number;
+}
+/** Chat node data of one restored (replayed at the tail) user message. */
+export interface RestoredMessageData {
+    /** Seq of the restore event. */
+    readonly seq: number;
+    /** Unix epoch ms from the restore event. */
+    readonly time: number;
+    /** Seq of the withdrawn original this replays, when cited. */
+    readonly restoredFromSeq: number | undefined;
+    /** The replayed content blocks (verbatim — images included). */
+    readonly content: readonly unknown[];
+    /** The original text, replayed verbatim. */
+    readonly text: string;
+}
+/** Chat node data of one restored assistant-text replay line. */
+export interface RestoredAssistantMessageData {
+    /** Seq of the restore-assistant replay event. */
+    readonly seq: number;
+    /** Unix epoch ms from the replay event. */
+    readonly time: number;
+    /** Seq of the withdrawn assistant message this replays, when cited. */
+    readonly restoredFromSeq: number | undefined;
+    /** The assistant reply text (model-facing frame stripped for display). */
+    readonly text: string;
+}
+declare module '@deepseek-ai/dsh-client-ui-conversation/client' {
+    interface ChatNodeDataMap {
+        /** message-tools withdrawal divider marking where a span was hidden. */
+        'message-tools-withdrawn': WithdrawnDividerData;
+        /** message-tools restore row: a withdrawn user message replayed at the tail. */
+        'message-tools-restored': RestoredMessageData;
+        /** message-tools restore line: a withdrawn assistant reply's text replayed at the tail. */
+        'message-tools-restored-assistant': RestoredAssistantMessageData;
+        /** message-tools edit row: the edit replacement rendered as the edited bubble in place. */
+        'message-tools-edited': EditedMessageData;
+    }
+}
+/**
+ * The withdrawal divider Definition: one single-event Context per
+ * message-tools replacement event, anchored at the replacement's seq so the
+ * divider sits exactly where the span was hidden.
+ */
+export declare const withdrawnDividerDefinition: ConversationNodeDefinition<WithdrawnDividerData>;
+/**
+ * The edited-bubble Definition: one single-event Context per message-tools
+ * edit replacement event — the replacement's content IS the edited text, so
+ * the row renders as a normal user bubble (with an「已编辑」badge) exactly
+ * where the span was discarded.
+ */
+export declare const editedMessageDefinition: ConversationNodeDefinition<EditedMessageData>;
+/**
+ * Fold the hidden seq spans out of the live chat nodes, flattened to
+ * `[start, endExclusive, ...]` pairs ordered by start. Both withdrawal
+ * dividers and edit bubbles carry `{ seq, hiddenStartSeq }` spans. The flat
+ * number array keeps the useSession selector stable under shallowEqual until
+ * a withdrawal or edit lands.
+ * @param nodes - every materialized chat node (any order).
+ * @returns the flattened hidden spans.
+ */
+export declare function foldHiddenRanges(nodes: readonly ChatConversationViewNode[]): number[];
+/**
+ * The restore-row Definition: one single-event Context per message-tools
+ * user-message restore event (append-surface, plugin-tagged), replaying the
+ * withdrawn message's content at the tail.
+ */
+export declare const restoredMessageDefinition: ConversationNodeDefinition<RestoredMessageData>;
+/**
+ * The restore-assistant-line Definition: one single-event Context per
+ * message-tools assistant-text restore replay (append-surface, op
+ * 'restore-assistant'), rendering the reply text at the tail. The
+ * model-facing frame is stripped for display — it belongs to the model
+ * context, not the transcript row.
+ */
+export declare const restoredAssistantMessageDefinition: ConversationNodeDefinition<RestoredAssistantMessageData>;
+/**
+ * Count the user-visible messages hidden by one withdrawn span. This mirrors
+ * {@link collectWithdrawnEntries}: context injections, tool calls, turn tails,
+ * and other UI chrome are not counted as “messages”, while restored/edited
+ * rows and reasoning-only assistant steps are.
+ * @param nodes - every materialized chat node.
+ * @param startSeq - first hidden seq (inclusive).
+ * @param endSeq - the divider's seq (exclusive).
+ * @returns the hidden message count.
+ */
+export declare function countHiddenInSpan(nodes: readonly ChatConversationViewNode[], startSeq: number, endSeq: number): number;
+/** One read-only replay entry of the divider's expand area. */
+export interface WithdrawnEntry {
+    /** Source node kind ('user' original or 'assistant-step' summary). */
+    readonly kind: 'user' | 'assistant';
+    /** The entry's text (full for user originals, a text join for assistant steps). */
+    readonly text: string;
+}
+/**
+ * Collect the read-only replay of one withdrawn span: user originals and
+ * assistant text, in anchor order. Other kinds carry no user-readable text
+ * and are skipped. Assistant-step data is kind-keyed (`data.blocks`, with
+ * `data.finalNode.blocks` once settled — `conversation-nodes/assistant.ts`),
+ * not type-keyed like message content. Reads the live node store — call from
+ * event handlers.
+ * @param nodes - every materialized chat node.
+ * @param startSeq - first hidden seq (inclusive).
+ * @param endSeq - the divider's seq (exclusive).
+ * @returns the replay entries.
+ */
+export declare function collectWithdrawnEntries(nodes: readonly ChatConversationViewNode[], startSeq: number, endSeq: number): WithdrawnEntry[];
+/**
+ * Whether one withdrawn span has a LIVE restore row (a restored node citing
+ * the span's first hidden seq and not itself inside a hidden span). When the
+ * restore rows are withdrawn again, the badge clears and the divider's
+ * restore action re-enables — the restore events stay in the log either way.
+ * @param nodes - every materialized chat node.
+ * @param hiddenStartSeq - the span's first hidden seq.
+ * @param ranges - the flattened hidden spans from foldHiddenRanges.
+ * @returns true when a live restore row for the span exists.
+ */
+export declare function hasRestoreForSpan(nodes: readonly ChatConversationViewNode[], hiddenStartSeq: number, ranges: readonly number[]): boolean;
+/**
+ * Whether a span's restore rows have themselves been withdrawn by a later
+ * span. The earlier divider remains as history, but the later divider is the
+ * active restore point; offering restore on both would duplicate the same
+ * logical content when the user toggles withdraw → restore → withdraw.
+ * @param nodes - every materialized chat node.
+ * @param hiddenStartSeq - the span's first hidden seq.
+ * @param ranges - the flattened hidden spans from foldHiddenRanges.
+ * @returns true when this span's restore rows are hidden inside a later span.
+ */
+export declare function isRestoreSuperseded(nodes: readonly ChatConversationViewNode[], hiddenStartSeq: number, ranges: readonly number[]): boolean;
+/**
+ * Whether a node seq falls inside a hidden span.
+ * @param ranges - the flattened spans from foldHiddenRanges.
+ * @param seq - the node seq to test.
+ * @returns true when the seq is hidden.
+ */
+export declare function isSeqHidden(ranges: readonly number[], seq: number): boolean;
+//# sourceMappingURL=withdrawn-node.d.ts.map

package/lib/types/client/withdrawn-node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withdrawn-node.d.ts","sourceRoot":"","sources":["../../../src/client/withdrawn-node.ts"],"names":[],"mappings":"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"}

package/lib/types/client/withdrawn-node.js

@@ -0,0 +1,297 @@
+import { isMessageToolsEdit, isMessageToolsReplacement, isMessageToolsRestore, isMessageToolsRestoreAssistant, stripRestoreAssistantFrame, } from '../marker.js';
+/**
+ * The withdrawal divider Definition: one single-event Context per
+ * message-tools replacement event, anchored at the replacement's seq so the
+ * divider sits exactly where the span was hidden.
+ */
+export const withdrawnDividerDefinition = {
+    kind: 'message-tools-withdrawn',
+    target: 'chat',
+    match: event => isMessageToolsReplacement(event)
+        ? { id: String(event.seq), role: 'start' }
+        : null,
+    start: (_context, match) => {
+        const event = match.event;
+        if (!isMessageToolsReplacement(event)) {
+            throw new Error('message-tools-withdrawn start requires a message-tools replacement event');
+        }
+        return { seq: event.seq, hiddenStartSeq: event.surfaceOp.start };
+    },
+    update: context => context.state,
+    buildViewNode: context => context.state === undefined
+        ? null
+        : {
+            key: context.key,
+            kind: 'message-tools-withdrawn',
+            id: context.id,
+            target: 'chat',
+            anchorSeq: context.state.seq,
+            location: context.start?.location ?? { kind: 'unresolved' },
+            visibility: 'visible',
+            data: context.state,
+        },
+};
+/**
+ * The edited-bubble Definition: one single-event Context per message-tools
+ * edit replacement event — the replacement's content IS the edited text, so
+ * the row renders as a normal user bubble (with an「已编辑」badge) exactly
+ * where the span was discarded.
+ */
+export const editedMessageDefinition = {
+    kind: 'message-tools-edited',
+    target: 'chat',
+    match: event => isMessageToolsEdit(event)
+        ? { id: String(event.seq), role: 'start' }
+        : null,
+    start: (_context, match) => {
+        const event = match.event;
+        if (!isMessageToolsEdit(event)) {
+            throw new Error('message-tools-edited start requires a message-tools edit replacement event');
+        }
+        return {
+            seq: event.seq,
+            time: event.time,
+            content: event.data.content,
+            hiddenStartSeq: event.surfaceOp.start,
+        };
+    },
+    update: context => context.state,
+    buildViewNode: context => context.state === undefined
+        ? null
+        : {
+            key: context.key,
+            kind: 'message-tools-edited',
+            id: context.id,
+            target: 'chat',
+            anchorSeq: context.state.seq,
+            location: context.start?.location ?? { kind: 'unresolved' },
+            visibility: 'visible',
+            data: context.state,
+        },
+};
+/**
+ * Fold the hidden seq spans out of the live chat nodes, flattened to
+ * `[start, endExclusive, ...]` pairs ordered by start. Both withdrawal
+ * dividers and edit bubbles carry `{ seq, hiddenStartSeq }` spans. The flat
+ * number array keeps the useSession selector stable under shallowEqual until
+ * a withdrawal or edit lands.
+ * @param nodes - every materialized chat node (any order).
+ * @returns the flattened hidden spans.
+ */
+export function foldHiddenRanges(nodes) {
+    const pairs = [];
+    for (const node of nodes) {
+        if (node.kind !== 'message-tools-withdrawn' && node.kind !== 'message-tools-edited')
+            continue;
+        const data = node.data;
+        pairs.push([data.hiddenStartSeq, data.seq]);
+    }
+    pairs.sort((left, right) => left[0] - right[0]);
+    return pairs.flat();
+}
+/** Join text blocks into one plain string. */
+function joinText(blocks) {
+    return blocks
+        .filter((block) => block.type === 'text'
+        && typeof block.text === 'string')
+        .map(block => block.text)
+        .join('');
+}
+/** Join AssistantBlock text (kind-keyed, unlike message content's type-keyed blocks). */
+function joinAssistantText(blocks) {
+    const text = blocks
+        .filter((block) => block.kind === 'text'
+        && typeof block.text === 'string')
+        .map(block => block.text)
+        .join('');
+    if (text !== '')
+        return text;
+    // Interrupted assistant steps may contain only reasoning; preserve it in
+    // the divider expand instead of showing an empty span.
+    return blocks
+        .filter((block) => block.kind === 'reasoning'
+        && typeof block.text === 'string')
+        .map(block => block.text)
+        .join('');
+}
+/**
+ * The restore-row Definition: one single-event Context per message-tools
+ * user-message restore event (append-surface, plugin-tagged), replaying the
+ * withdrawn message's content at the tail.
+ */
+export const restoredMessageDefinition = {
+    kind: 'message-tools-restored',
+    target: 'chat',
+    match: event => isMessageToolsRestore(event)
+        ? { id: String(event.seq), role: 'start' }
+        : null,
+    start: (_context, match) => {
+        const event = match.event;
+        if (!isMessageToolsRestore(event)) {
+            throw new Error('message-tools-restored start requires a message-tools restore event');
+        }
+        return {
+            seq: event.seq,
+            time: event.time,
+            restoredFromSeq: event.sourceEventSeqs?.[0],
+            content: event.data.content,
+            text: joinText(event.data.content),
+        };
+    },
+    update: context => context.state,
+    buildViewNode: context => context.state === undefined
+        ? null
+        : {
+            key: context.key,
+            kind: 'message-tools-restored',
+            id: context.id,
+            target: 'chat',
+            anchorSeq: context.state.seq,
+            location: context.start?.location ?? { kind: 'unresolved' },
+            visibility: 'visible',
+            data: context.state,
+        },
+};
+/**
+ * The restore-assistant-line Definition: one single-event Context per
+ * message-tools assistant-text restore replay (append-surface, op
+ * 'restore-assistant'), rendering the reply text at the tail. The
+ * model-facing frame is stripped for display — it belongs to the model
+ * context, not the transcript row.
+ */
+export const restoredAssistantMessageDefinition = {
+    kind: 'message-tools-restored-assistant',
+    target: 'chat',
+    match: event => isMessageToolsRestoreAssistant(event)
+        ? { id: String(event.seq), role: 'start' }
+        : null,
+    start: (_context, match) => {
+        const event = match.event;
+        if (!isMessageToolsRestoreAssistant(event)) {
+            throw new Error('message-tools-restored-assistant start requires a restore-assistant replay event');
+        }
+        return {
+            seq: event.seq,
+            time: event.time,
+            restoredFromSeq: event.sourceEventSeqs?.[0],
+            text: stripRestoreAssistantFrame(joinText(event.data.content)),
+        };
+    },
+    update: context => context.state,
+    buildViewNode: context => context.state === undefined
+        ? null
+        : {
+            key: context.key,
+            kind: 'message-tools-restored-assistant',
+            id: context.id,
+            target: 'chat',
+            anchorSeq: context.state.seq,
+            location: context.start?.location ?? { kind: 'unresolved' },
+            visibility: 'visible',
+            data: context.state,
+        },
+};
+/**
+ * Count the user-visible messages hidden by one withdrawn span. This mirrors
+ * {@link collectWithdrawnEntries}: context injections, tool calls, turn tails,
+ * and other UI chrome are not counted as “messages”, while restored/edited
+ * rows and reasoning-only assistant steps are.
+ * @param nodes - every materialized chat node.
+ * @param startSeq - first hidden seq (inclusive).
+ * @param endSeq - the divider's seq (exclusive).
+ * @returns the hidden message count.
+ */
+export function countHiddenInSpan(nodes, startSeq, endSeq) {
+    return collectWithdrawnEntries(nodes, startSeq, endSeq).length;
+}
+/**
+ * Collect the read-only replay of one withdrawn span: user originals and
+ * assistant text, in anchor order. Other kinds carry no user-readable text
+ * and are skipped. Assistant-step data is kind-keyed (`data.blocks`, with
+ * `data.finalNode.blocks` once settled — `conversation-nodes/assistant.ts`),
+ * not type-keyed like message content. Reads the live node store — call from
+ * event handlers.
+ * @param nodes - every materialized chat node.
+ * @param startSeq - first hidden seq (inclusive).
+ * @param endSeq - the divider's seq (exclusive).
+ * @returns the replay entries.
+ */
+export function collectWithdrawnEntries(nodes, startSeq, endSeq) {
+    const inSpan = nodes
+        .filter(node => node.anchorSeq >= startSeq && node.anchorSeq < endSeq)
+        .sort((left, right) => left.anchorSeq - right.anchorSeq);
+    const entries = [];
+    for (const node of inSpan) {
+        if (node.kind === 'user' || node.kind === 'steering' || node.kind === 'message-tools-edited') {
+            const content = node.data.content ?? [];
+            const text = joinText(content);
+            if (text !== '')
+                entries.push({ kind: 'user', text });
+            continue;
+        }
+        if (node.kind === 'message-tools-restored') {
+            const text = node.data.text ?? '';
+            if (text !== '')
+                entries.push({ kind: 'user', text });
+            continue;
+        }
+        if (node.kind === 'message-tools-restored-assistant') {
+            const text = node.data.text ?? '';
+            if (text !== '')
+                entries.push({ kind: 'assistant', text });
+            continue;
+        }
+        if (node.kind === 'assistant-step') {
+            const data = node.data;
+            const text = joinAssistantText(data.finalNode?.blocks ?? data.blocks ?? []);
+            if (text !== '')
+                entries.push({ kind: 'assistant', text });
+        }
+    }
+    return entries;
+}
+/**
+ * Whether one withdrawn span has a LIVE restore row (a restored node citing
+ * the span's first hidden seq and not itself inside a hidden span). When the
+ * restore rows are withdrawn again, the badge clears and the divider's
+ * restore action re-enables — the restore events stay in the log either way.
+ * @param nodes - every materialized chat node.
+ * @param hiddenStartSeq - the span's first hidden seq.
+ * @param ranges - the flattened hidden spans from foldHiddenRanges.
+ * @returns true when a live restore row for the span exists.
+ */
+export function hasRestoreForSpan(nodes, hiddenStartSeq, ranges) {
+    return nodes.some(node => node.kind === 'message-tools-restored'
+        && node.data.restoredFromSeq === hiddenStartSeq
+        && !isSeqHidden(ranges, node.anchorSeq));
+}
+/**
+ * Whether a span's restore rows have themselves been withdrawn by a later
+ * span. The earlier divider remains as history, but the later divider is the
+ * active restore point; offering restore on both would duplicate the same
+ * logical content when the user toggles withdraw → restore → withdraw.
+ * @param nodes - every materialized chat node.
+ * @param hiddenStartSeq - the span's first hidden seq.
+ * @param ranges - the flattened hidden spans from foldHiddenRanges.
+ * @returns true when this span's restore rows are hidden inside a later span.
+ */
+export function isRestoreSuperseded(nodes, hiddenStartSeq, ranges) {
+    return nodes.some(node => (node.kind === 'message-tools-restored' || node.kind === 'message-tools-restored-assistant')
+        && node.data.restoredFromSeq === hiddenStartSeq
+        && isSeqHidden(ranges, node.anchorSeq));
+}
+/**
+ * Whether a node seq falls inside a hidden span.
+ * @param ranges - the flattened spans from foldHiddenRanges.
+ * @param seq - the node seq to test.
+ * @returns true when the seq is hidden.
+ */
+export function isSeqHidden(ranges, seq) {
+    for (let index = 0; index + 1 < ranges.length; index += 2) {
+        const start = ranges[index];
+        const end = ranges[index + 1];
+        if (start !== undefined && end !== undefined && seq >= start && seq < end)
+            return true;
+    }
+    return false;
+}

package/lib/types/index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * message-tools host half: the `messageTools` Typert Remote service. Its
+ * withdraw/edit methods land surface replacements — the compaction mechanism —
+ * so the target message and everything after it leave the model-visible
+ * surface (edit replacements carry the edited text as their content), and its
+ * restore method tail-replays a withdrawn span's replayable entries, while
+ * the browser half shadows the user-message renderer and projects the
+ * withdrawal divider, edited bubble, and restored rows.
+ * @module @khorsheed/dsh-client-message-tools
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import type { MessageToolsEditRequest, MessageToolsEditResult, MessageToolsRestoreRequest, MessageToolsRestoreResult, MessageToolsWithdrawRequest, MessageToolsWithdrawResult } from './types.ts';
+export type * from './types.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Withdrawal Remote owned by the message-tools plugin. */
+        messageTools: MessageToolsService;
+    }
+}
+/**
+ * messageTools Remote service: appends the withdrawal replacement to the
+ * owning Session and flushes it durable. The replacement event's
+ * plugin-tagged source is the audit trail; no new session event type is
+ * introduced, so session reload stays safe for harnesses without this plugin.
+ */
+export declare class MessageToolsService extends TypertRemoteService {
+    static inject: string[];
+    /**
+     * @param ctx - host context carrying the session store.
+     */
+    constructor(ctx: Context);
+    /**
+     * Withdraw a user message: replace it and every surface node after it with
+     * a minimal plugin-sourced placeholder, hiding the span from the model.
+     * @param request - session identity and target message seq.
+     * @returns the replacement receipt, or a rejection from the closed failure union.
+     */
+    withdraw(request: MessageToolsWithdrawRequest): Promise<MessageToolsWithdrawResult>;
+    /**
+     * Restore a withdrawn span: replay every replayable entry of it (user
+     * messages verbatim — including the last edit's new text — and framed
+     * assistant text; tool calls/results never replay) as fresh plugin-tagged
+     * `user/message` appends at the conversation tail, in original order, each
+     * citing its original event in `sourceEventSeqs`. The surface replace model
+     * is positional — a replaced span folds into one node — so the span cannot
+     * be restored in place; the replayed entries are simply the newest messages
+     * the model sees. Assistant text replays as framed user-role messages:
+     * `assistant/message` cannot carry a plugin source and the turn/step trace
+     * forbids assistant appends outside a step.
+     * @param request - session identity and withdrawn message seq.
+     * @returns the restore receipt, or a rejection from the closed failure union.
+     */
+    restore(request: MessageToolsRestoreRequest): Promise<MessageToolsRestoreResult>;
+    /**
+     * Edit a user message in place: replace it and every surface node after it
+     * with the edited text itself (no placeholder, no tail duplicate — the
+     * edited text appears exactly once, in the replacement event), then start a
+     * regeneration turn. The harness has no wake-without-append path, so the
+     * turn is started by `agent.followup` carrying a minimal plugin-sourced
+     * trigger message (the ankh-guard/schedule pattern); the trigger is not the
+     * edited text and lands once, as itself.
+     * @param request - session identity, target seq, edited text.
+     * @returns the replacement receipt and whether the turn was triggered, or a rejection.
+     */
+    edit(request: MessageToolsEditRequest): Promise<MessageToolsEditResult>;
+}
+export default MessageToolsService;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAMlD,OAAO,EAAU,mBAAmB,EAAE,MAAM,kCAAkC,CAAA;AAM9E,OAAO,KAAK,EACV,uBAAuB,EAAE,sBAAsB,EAC/C,0BAA0B,EAAE,yBAAyB,EACrD,2BAA2B,EAAE,0BAA0B,EACxD,MAAM,YAAY,CAAA;AAEnB,mBAAmB,YAAY,CAAA;AAE/B,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf,2DAA2D;QAC3D,YAAY,EAAE,mBAAmB,CAAA;KAClC;CACF;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,mBAAmB;IAC1D,MAAM,CAAC,MAAM,WAAyB;IAEtC;;OAEG;IACH,YAAY,GAAG,EAAE,OAAO,EAEvB;IAED;;;;;OAKG;IAEG,QAAQ,CAAC,OAAO,EAAE,2BAA2B,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAiBxF;IAED;;;;;;;;;;;;;OAaG;IAEG,OAAO,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAwBrF;IAED;;;;;;;;;;OAUG;IAEG,IAAI,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAqB5E;CACF;eAEc,mBAAmB"}