@khorsheed/dsh-client-message-tools 0.2.0 → 0.3.1

package/lib/types/client/icons.js

@@ -1,11 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-/**
- * Undo arrow (withdraw/restore), rotate-ccw style: a near-full circle arc
- * (~290°, opening at the top) with a corner arrowhead at its left end
- * pointing the counterclockwise direction. ui-primitives ships no undo/revert
- * glyph, and its refresh glyph carries reload semantics, so this package
- * draws its own.
- * @param props - size and className.
- * @returns the icon element.
- */
-export const IconUndoOutline16 = ({ size = 16, className }) => (_jsxs("svg", { width: size, height: size, className: className, viewBox: "0 0 16 16", fill: "none", stroke: "currentColor", strokeWidth: 1.4, strokeLinecap: "round", strokeLinejoin: "round", xmlns: "http://www.w3.org/2000/svg", children: [_jsx("path", { d: "M2.2 8.7 A5.8 5.8 0 1 0 5.9 3.3 L2.6 6.6" }), _jsx("path", { d: "M2.6 2.4 V6.6 H6.2", fill: "none" })] }));
+export const IconCheckOutlineMedium = ({ size = 16, className }) => (_jsx("svg", { width: size, height: size, className: className, viewBox: "0 0 16 16", fill: "none", xmlns: "http://www.w3.org/2000/svg", "aria-hidden": "true", strokeWidth: 1.3, children: _jsx("path", { d: "M2.25 8.5L5.49732 11.7473C5.90519 12.1552 6.57263 12.1344 6.95426 11.7018L13.75 4", stroke: "currentColor" }) }));
+export const IconChevronDownOutlineMedium = ({ size = 14, className }) => (_jsx("svg", { width: size, height: size, className: className, viewBox: "0 0 16 16", fill: "none", xmlns: "http://www.w3.org/2000/svg", "aria-hidden": "true", strokeWidth: 1.3, children: _jsx("path", { d: "M4 6L7.29289 9.29289C7.68342 9.68342 8.31658 9.68342 8.70711 9.29289L12 6", stroke: "currentColor" }) }));
+export const IconChevronRightOutlineMedium = ({ size = 14, className }) => (_jsx("svg", { width: size, height: size, className: className, viewBox: "0 0 16 16", fill: "none", xmlns: "http://www.w3.org/2000/svg", "aria-hidden": "true", strokeWidth: 1.3, children: _jsx("path", { d: "M6 12L9.29289 8.70711C9.68342 8.31658 9.68342 7.68342 9.29289 7.29289L6 4", stroke: "currentColor" }) }));
+export const IconCopyOutlineMedium = ({ size = 16, className }) => (_jsxs("svg", { width: size, height: size, className: className, viewBox: "0 0 16 16", fill: "none", xmlns: "http://www.w3.org/2000/svg", "aria-hidden": "true", strokeWidth: 1.3, children: [_jsx("rect", { x: "1.52075", y: "4.07373", width: "10.3932", height: "10.3932", rx: "2", stroke: "currentColor" }), _jsx("path", { d: "M11.9792 1.53296C13.36 1.53296 14.4792 2.65225 14.4792 4.03296V9.42847C14.4792 10.3756 13.9521 11.1987 13.1755 11.6228V10.3298C13.3652 10.0787 13.4792 9.7674 13.4792 9.42847V4.03296C13.4792 3.20453 12.8077 2.53296 11.9792 2.53296H6.58374C6.27966 2.53301 5.99684 2.6235 5.7605 2.77905H4.42358C4.85652 2.03463 5.66056 1.53304 6.58374 1.53296H11.9792Z", fill: "currentColor" })] }));
+export const IconEditOutlineMedium = ({ size = 16, className }) => (_jsxs("svg", { width: size, height: size, className: className, viewBox: "0 0 16 16", fill: "none", xmlns: "http://www.w3.org/2000/svg", "aria-hidden": "true", strokeWidth: 1.3, children: [_jsx("path", { d: "M8.85596 2.69971H4.19971C3.37141 2.69971 2.69992 3.37146 2.69971 4.19971V11.8003C2.69992 12.6285 3.37141 13.3003 4.19971 13.3003H11.8003C12.6283 13.2999 13.3001 12.6283 13.3003 11.8003V7.89893H14.3003V11.8003C14.3001 13.1806 13.1806 14.2999 11.8003 14.3003H4.19971C2.81913 14.3003 1.69992 13.1808 1.69971 11.8003V4.19971C1.69992 2.81918 2.81913 1.69971 4.19971 1.69971H8.85596V2.69971Z", fill: "currentColor" }), _jsx("path", { d: "M7.7849 8.23878L13.888 2.13574", stroke: "currentColor" })] }));

package/lib/types/client/index.js

@@ -179,7 +179,12 @@ export async function apply(ctx) {
             },
             selectModel: selection => directory === undefined
                 ? Promise.resolve(false)
-                : directory.select(selection).then(() => true, () => false),
+                // Host 0.1.6-alpha.2 turned select() into a never-rejecting
+                // RemoteResult; 0.1.5 still rejects on failure. Read the settled
+                // shape: a value carrying `ok` is the new contract, anything else is
+                // the old void success, and a rejection only happens on the old line
+                // (the official consumer reads `!result.ok` the same way).
+                : directory.select(selection).then(result => (result && typeof result === 'object' && 'ok' in result ? result.ok : true), () => false),
             hooks: {
                 modelDirectory: directory === undefined ? EMPTY_MODEL_DIRECTORY : directory.store,
             },

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

@@ -9,7 +9,7 @@
  * renderers and the DOM hider.
  */
 import type { ChatConversationViewNode } from '@deepseek-ai/dsh-client-ui-chat/client';
-import type { ConversationNodeDefinition } from '@deepseek-ai/dsh-client-ui-conversation/client';
+import type { ConversationNodeDefinition, MessageImageSource } from '@deepseek-ai/dsh-client-ui-conversation/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). */
@@ -89,7 +89,7 @@ export declare const editedMessageDefinition: ConversationNodeDefinition<EditedM
 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
+ * user-message restore event (append-surface, producer-tagged), replaying the
  * withdrawn message's content at the tail.
  */
 export declare const restoredMessageDefinition: ConversationNodeDefinition<RestoredMessageData>;
@@ -105,7 +105,7 @@ export declare const restoredAssistantMessageDefinition: ConversationNodeDefinit
  * 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.
+ * rows, reasoning-only assistant steps, and image-only user messages are.
  * @param nodes - every materialized chat node.
  * @param startSeq - first hidden seq (inclusive).
  * @param endSeq - the divider's seq (exclusive).
@@ -116,16 +116,23 @@ export declare function countHiddenInSpan(nodes: readonly ChatConversationViewNo
 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). */
+    /** The entry's text (full for user originals, a text join for assistant steps; empty for an image-only message). */
     readonly text: string;
+    /**
+     * The entry's user-attached images, in source order — what the withdrawal
+     * hid alongside the text. Always empty for assistant entries: the replay is
+     * user originals plus assistant text, and assistant image blocks stay out
+     * of that vocabulary (see the module note on the replay).
+     */
+    readonly images: readonly MessageImageSource[];
 }
 /**
- * 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.
+ * Collect the read-only replay of one withdrawn span: user originals (text
+ * and attached images alike) and assistant text, in anchor order. Other kinds
+ * carry no user-readable content 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).

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

@@ -26,17 +26,17 @@ export const withdrawnDividerDefinition = {
     kind: 'message-tools-withdrawn',
     target: 'chat',
     match: (event) => {
-        // Packed chunk rows share the bus; the guards speak SessionEvent only.
+        // Attempt and boundary rows share the bus; the guards speak SessionEvent only.
         if (event.type !== 'user/message')
             return null;
         return isMessageToolsReplacement(event) ? { id: String(event.seq), role: 'start' } : null;
     },
     start: (_context, match) => {
         const event = match.event;
-        if (!isMessageToolsReplacement(event)) {
+        if (event.type !== 'user/message' || !isMessageToolsReplacement(event)) {
             throw new Error('message-tools-withdrawn start requires a message-tools replacement event');
         }
-        return { seq: event.seq, hiddenStartSeq: event.surfaceOp.start };
+        return { seq: event.seq, hiddenStartSeq: event.surfaceOp.startSeq };
     },
     update: context => context.state,
     buildViewNode: context => context.state === undefined
@@ -59,14 +59,14 @@ export const editedMessageDefinition = {
     },
     start: (_context, match) => {
         const event = match.event;
-        if (!isMessageToolsEdit(event)) {
+        if (event.type !== 'user/message' || !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,
+            hiddenStartSeq: event.surfaceOp.startSeq,
         };
     },
     update: context => context.state,
@@ -94,6 +94,21 @@ export function foldHiddenRanges(nodes) {
     pairs.sort((left, right) => left[0] - right[0]);
     return pairs.flat();
 }
+/**
+ * Fold one message's content blocks into the gallery slot's image input, in
+ * source order. Only `type: 'image'` blocks with an attachment qualify; a
+ * withdrawn user message must keep its images visible in the divider replay
+ * (they are exactly what the withdrawal hid).
+ */
+function imageSources(blocks) {
+    const images = [];
+    for (const block of blocks) {
+        const b = block;
+        if (b.type === 'image' && b.attachment !== undefined)
+            images.push({ attachment: b.attachment });
+    }
+    return images;
+}
 /** Join text blocks into one plain string. */
 function joinText(blocks) {
     return blocks
@@ -121,7 +136,7 @@ function joinAssistantText(blocks) {
 }
 /**
  * The restore-row Definition: one single-event Context per message-tools
- * user-message restore event (append-surface, plugin-tagged), replaying the
+ * user-message restore event (append-surface, producer-tagged), replaying the
  * withdrawn message's content at the tail.
  */
 export const restoredMessageDefinition = {
@@ -134,7 +149,7 @@ export const restoredMessageDefinition = {
     },
     start: (_context, match) => {
         const event = match.event;
-        if (!isMessageToolsRestore(event)) {
+        if (event.type !== 'user/message' || !isMessageToolsRestore(event)) {
             throw new Error('message-tools-restored start requires a message-tools restore event');
         }
         return {
@@ -167,7 +182,7 @@ export const restoredAssistantMessageDefinition = {
     },
     start: (_context, match) => {
         const event = match.event;
-        if (!isMessageToolsRestoreAssistant(event)) {
+        if (event.type !== 'user/message' || !isMessageToolsRestoreAssistant(event)) {
             throw new Error('message-tools-restored-assistant start requires a restore-assistant replay event');
         }
         return {
@@ -186,7 +201,7 @@ export const restoredAssistantMessageDefinition = {
  * 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.
+ * rows, reasoning-only assistant steps, and image-only user messages are.
  * @param nodes - every materialized chat node.
  * @param startSeq - first hidden seq (inclusive).
  * @param endSeq - the divider's seq (exclusive).
@@ -196,12 +211,12 @@ 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.
+ * Collect the read-only replay of one withdrawn span: user originals (text
+ * and attached images alike) and assistant text, in anchor order. Other kinds
+ * carry no user-readable content 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).
@@ -216,27 +231,30 @@ export function collectWithdrawnEntries(nodes, startSeq, endSeq) {
         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 });
+            const images = imageSources(content);
+            if (text !== '' || images.length > 0)
+                entries.push({ kind: 'user', text, images });
             continue;
         }
         if (node.kind === 'message-tools-restored') {
-            const text = node.data.text ?? '';
-            if (text !== '')
-                entries.push({ kind: 'user', text });
+            const data = node.data;
+            const text = data.text ?? '';
+            const images = imageSources(data.content ?? []);
+            if (text !== '' || images.length > 0)
+                entries.push({ kind: 'user', text, images });
             continue;
         }
         if (node.kind === 'message-tools-restored-assistant') {
             const text = node.data.text ?? '';
             if (text !== '')
-                entries.push({ kind: 'assistant', text });
+                entries.push({ kind: 'assistant', text, images: [] });
             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 });
+                entries.push({ kind: 'assistant', text, images: [] });
         }
     }
     return entries;

package/lib/types/index.d.ts

@@ -21,7 +21,7 @@ declare module '@deepseek-ai/cordis' {
 /**
  * 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
+ * producer-owned 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 {
@@ -32,7 +32,7 @@ export declare class MessageToolsService extends TypertRemoteService {
     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.
+     * a minimal producer-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.
      */
@@ -40,14 +40,14 @@ export declare class MessageToolsService extends TypertRemoteService {
     /**
      * 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.
+     * assistant text; tool calls/results never replay) as fresh
+     * producer-sourced `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` requires the model 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.
      */
@@ -57,7 +57,7 @@ export declare class MessageToolsService extends TypertRemoteService {
      * 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
+     * turn is started by `agent.followup` carrying a minimal producer-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.

package/lib/types/index.js

@@ -36,12 +36,13 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
 import { SessionSeq } from '@deepseek-ai/dsh-session';
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
 import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
-import { EDIT_TRIGGER_NOTICE, MESSAGE_TOOLS_PLUGIN, WITHDRAWN_NOTICE, editReplacementSource, editTriggerSource, restoreAssistantSource, } from './marker.js';
+import { EDIT_TRIGGER_NOTICE, WITHDRAWN_NOTICE, editReplacementSource, editTriggerSource, messageToolsSource, restoreAssistantSource, } from './marker.js';
+import { registerRestoreProjection } from './restore-projection.js';
 import { planEdit, planRestore, planWithdrawal } from './withdraw.js';
 /**
  * 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
+ * producer-owned source is the audit trail; no new session event type is
  * introduced, so session reload stays safe for harnesses without this plugin.
  */
 let MessageToolsService = (() => {
@@ -68,10 +69,14 @@ let MessageToolsService = (() => {
         constructor(ctx) {
             super(ctx, 'messageTools');
             __runInitializers(this, _instanceExtraInitializers);
+            // Seam registry S12: on a host whose session fold can carry a user/message
+            // projection, restore replays derive assistant-role without the frame;
+            // every degrade path leaves the framed user-role channel verbatim.
+            registerRestoreProjection(ctx);
         }
         /**
          * Withdraw a user message: replace it and every surface node after it with
-         * a minimal plugin-sourced placeholder, hiding the span from the model.
+         * a minimal producer-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.
          */
@@ -84,9 +89,9 @@ let MessageToolsService = (() => {
                 return { ok: false, error: { code: planned.code } };
             const replacement = session.append('user/message', createUserMessage({
                 content: [{ type: 'text', text: WITHDRAWN_NOTICE }],
-                source: { kind: 'plugin', plugin: MESSAGE_TOOLS_PLUGIN },
+                source: messageToolsSource(),
             }), {
-                surfaceOp: { op: 'replace', start: SessionSeq(planned.plan.start), end: SessionSeq(planned.plan.end) },
+                surfaceOp: { op: 'replace', startSeq: SessionSeq(planned.plan.start), endSeq: SessionSeq(planned.plan.end) },
                 sourceEventSeqs: planned.plan.sourceEventSeqs.map(seq => SessionSeq(seq)),
             });
             await this.ctx.sessions.flush(session);
@@ -98,14 +103,14 @@ let MessageToolsService = (() => {
         /**
          * 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.
+         * assistant text; tool calls/results never replay) as fresh
+         * producer-sourced `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` requires the model 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.
          */
@@ -121,7 +126,7 @@ let MessageToolsService = (() => {
                 const message = entry.role === 'user'
                     ? createUserMessage({
                         content: [...entry.content],
-                        source: { kind: 'plugin', plugin: MESSAGE_TOOLS_PLUGIN },
+                        source: messageToolsSource(),
                     })
                     : createUserMessage({
                         content: [{ type: 'text', text: entry.text }],
@@ -141,7 +146,7 @@ let MessageToolsService = (() => {
          * 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
+         * turn is started by `agent.followup` carrying a minimal producer-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.
@@ -158,7 +163,7 @@ let MessageToolsService = (() => {
                 content: [{ type: 'text', text: request.text }],
                 source: editReplacementSource(),
             }), {
-                surfaceOp: { op: 'replace', start: SessionSeq(planned.plan.start), end: SessionSeq(planned.plan.end) },
+                surfaceOp: { op: 'replace', startSeq: SessionSeq(planned.plan.start), endSeq: SessionSeq(planned.plan.end) },
                 sourceEventSeqs: planned.plan.sourceEventSeqs.map(seq => SessionSeq(seq)),
             });
             await this.ctx.sessions.flush(session);

package/lib/types/marker.d.ts

@@ -1,7 +1,23 @@
-import type { MessageSource } from '@deepseek-ai/dsh-llm/message';
+import type { ContextFormed, MessageSource } from '@deepseek-ai/dsh-llm/message';
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types';
-/** Plugin source tag identifying every message-tools event. */
+/**
+ * The producer-owned source kind identifying every message-tools event. It is
+ * also the legacy wrapper's `plugin` value: released V3 logs carry
+ * `{ kind: 'plugin', plugin: 'message-tools' }` (a pre-V4 host still serves
+ * them verbatim), and the official V3→V4 migration rewrites those to
+ * `kind: 'plugin:message-tools'` — {@link isMessageToolsSource} accepts all
+ * three durable forms.
+ */
 export declare const MESSAGE_TOOLS_PLUGIN = "message-tools";
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        /** message-tools producer: withdrawal/edit replacements, edit triggers, restore replays. */
+        'message-tools': {
+            kind: 'message-tools';
+            readonly op?: MessageToolsOp;
+        } & ContextFormed;
+    }
+}
 /**
  * Model-facing placeholder left on the surface in place of the withdrawn
  * span. The span itself is hidden from the model; this minimal user message
@@ -17,21 +33,36 @@ export declare const WITHDRAWN_NOTICE = "(\u7528\u6237\u64A4\u56DE\u4E86\u8FD9\u
 export declare const EDIT_TRIGGER_NOTICE = "(\u7528\u6237\u7F16\u8F91\u4E86\u4E0A\u4E00\u6761\u6D88\u606F\uFF0C\u8BF7\u6309\u7F16\u8F91\u540E\u7684\u5185\u5BB9\u91CD\u65B0\u56DE\u7B54)";
 /**
  * Model-facing frame preceding a replayed assistant text in a restore: the
- * replay lands as a user-role message (assistant/message cannot carry a
- * plugin source, and the session turn/step trace forbids ad-hoc assistant
- * appends), so the frame keeps the role honest for the model.
+ * replay lands as a user-role message (assistant/message requires the model
+ * source, and the session turn/step trace forbids ad-hoc assistant
+ * appends), so the frame keeps the role honest for the model. On hosts whose
+ * session fold carries the S12 `user/message` projection the frame never
+ * reaches the model — the projection strips it and corrects the role at
+ * derivation time; everywhere else it is the role-honesty device.
  */
 export declare const RESTORED_ASSISTANT_NOTICE = "(\u4EE5\u4E0B\u662F\u5148\u524D\u88AB\u64A4\u56DE\u3001\u73B0\u968F\u6062\u590D\u653E\u56DE\u7684\u52A9\u624B\u56DE\u590D)";
-/** The `op` discriminator on a message-tools plugin source. */
+/** The `op` discriminator on a message-tools source. */
 export type MessageToolsOp = 'edit' | 'edit-trigger' | 'restore-assistant';
-/** The plugin-tagged source of an edit replacement (op: 'edit'). */
+/** The producer-owned source of a withdrawal replacement or a user-message restore replay (no op). */
+export declare function messageToolsSource(): MessageSource;
+/** The producer-owned source of an edit replacement (op: 'edit'). */
 export declare function editReplacementSource(): MessageSource;
-/** The plugin-tagged source of an edit trigger message (op: 'edit-trigger'). */
+/** The producer-owned source of an edit trigger message (op: 'edit-trigger'). */
 export declare function editTriggerSource(): MessageSource;
-/** The plugin-tagged source of a restored assistant-text replay (op: 'restore-assistant'). */
+/** The producer-owned source of a restored assistant-text replay (op: 'restore-assistant'). */
 export declare function restoreAssistantSource(): MessageSource;
-/** Read the op discriminator off a message source (absent on legacy events). */
+/** Read the op discriminator off a message source (absent on plain withdrawal/restore events). */
 export declare function messageToolsOp(source: unknown): MessageToolsOp | undefined;
+/**
+ * Whether a durable source belongs to message-tools, in every form the log
+ * can hold: the current producer-owned kind (`message-tools`), the V3→V4
+ * migrated kind (`plugin:message-tools` — released V3 files rewritten once by
+ * the official migration), and the released V3 wrapper a pre-V4 host still
+ * serves verbatim (`{ kind: 'plugin', plugin: 'message-tools' }`).
+ * @param source - the persisted message source to test.
+ * @returns true when the source names this producer.
+ */
+export declare function isMessageToolsSource(source: unknown): boolean;
 /**
  * Strip the model-facing restore frame from a replayed assistant text for
  * DISPLAY: the frame belongs to the model context (role honesty), never to
@@ -44,8 +75,8 @@ export declare function stripRestoreAssistantFrame(text: string): string;
 export type MessageToolsReplacementEvent = SessionEvent<'user/message'> & {
     readonly surfaceOp: {
         readonly op: 'replace';
-        readonly start: number;
-        readonly end: number;
+        readonly startSeq: number;
+        readonly endSeq: number;
     };
 };
 /** One message-tools edit replacement event, narrowed (same shape, `op: 'edit'` source). */
@@ -56,8 +87,9 @@ export type MessageToolsRestoreEvent = SessionEvent<'user/message'> & {
 };
 /**
  * Whether the event is a message-tools WITHDRAWAL replacement: a
- * `user/message` surface replacement whose source carries this plugin's tag
- * and no `op` discriminator (legacy and current withdrawals both).
+ * `user/message` surface replacement whose source names this producer
+ * (any durable form — see {@link isMessageToolsSource}) with no `op`
+ * discriminator.
  * @param event - the session event to test.
  * @returns the event narrowed to a withdrawal replacement when matched.
  */
@@ -78,7 +110,7 @@ export declare function isMessageToolsEdit(event: SessionEvent): event is Messag
 export declare function isMessageToolsRestore(event: SessionEvent): event is MessageToolsRestoreEvent;
 /**
  * Whether the event is a message-tools edit trigger: the minimal
- * plugin-sourced message that starts the regeneration turn after an edit.
+ * producer-sourced message that starts the regeneration turn after an edit.
  * @param event - the session event to test.
  * @returns the event narrowed to an edit trigger when matched.
  */