@khorsheed/dsh-client-message-tools 0.1.0

package/lib/types/index.js

@@ -0,0 +1,175 @@
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+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 { 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
+ * introduced, so session reload stays safe for harnesses without this plugin.
+ */
+let MessageToolsService = (() => {
+    let _classSuper = TypertRemoteService;
+    let _instanceExtraInitializers = [];
+    let _withdraw_decorators;
+    let _restore_decorators;
+    let _edit_decorators;
+    return class MessageToolsService extends _classSuper {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _withdraw_decorators = [Remote('withdraw')];
+            _restore_decorators = [Remote('restore')];
+            _edit_decorators = [Remote('edit')];
+            __esDecorate(this, null, _withdraw_decorators, { kind: "method", name: "withdraw", static: false, private: false, access: { has: obj => "withdraw" in obj, get: obj => obj.withdraw }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _restore_decorators, { kind: "method", name: "restore", static: false, private: false, access: { has: obj => "restore" in obj, get: obj => obj.restore }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _edit_decorators, { kind: "method", name: "edit", static: false, private: false, access: { has: obj => "edit" in obj, get: obj => obj.edit }, metadata: _metadata }, null, _instanceExtraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        static inject = ['sessions', 'agents'];
+        /**
+         * @param ctx - host context carrying the session store.
+         */
+        constructor(ctx) {
+            super(ctx, 'messageTools');
+            __runInitializers(this, _instanceExtraInitializers);
+        }
+        /**
+         * 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.
+         */
+        async withdraw(request) {
+            const session = this.ctx.sessions.get(request.sessionId);
+            if (session === undefined)
+                return { ok: false, error: { code: 'session-not-found' } };
+            const planned = planWithdrawal(session.events, session.surface.nodes, request.targetSeq);
+            if (!planned.ok)
+                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 },
+            }), {
+                surfaceOp: { op: 'replace', start: planned.plan.start, end: planned.plan.end },
+                sourceEventSeqs: [...planned.plan.sourceEventSeqs],
+            });
+            await this.ctx.sessions.flush(session);
+            return {
+                ok: true,
+                value: { replacementSeq: replacement.seq, shadowedCount: planned.plan.sourceEventSeqs.length },
+            };
+        }
+        /**
+         * 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.
+         */
+        async restore(request) {
+            const session = this.ctx.sessions.get(request.sessionId);
+            if (session === undefined)
+                return { ok: false, error: { code: 'session-not-found' } };
+            const planned = planRestore(session.events, session.surface.nodes, request.targetSeq);
+            if (!planned.ok)
+                return { ok: false, error: { code: planned.code } };
+            const appendedSeqs = [];
+            for (const entry of planned.plan.entries) {
+                const message = entry.role === 'user'
+                    ? createUserMessage({
+                        content: [...entry.content],
+                        source: { kind: 'plugin', plugin: MESSAGE_TOOLS_PLUGIN },
+                    })
+                    : createUserMessage({
+                        content: [{ type: 'text', text: entry.text }],
+                        source: restoreAssistantSource(),
+                    });
+                appendedSeqs.push(session.append('user/message', message, {
+                    surfaceOp: 'append',
+                    sourceEventSeqs: [entry.sourceSeq],
+                }).seq);
+            }
+            await this.ctx.sessions.flush(session);
+            /* v8 ignore next -- entries is never empty (the target itself always replays), so [0] exists */
+            return { ok: true, value: { restoredSeq: appendedSeqs[0] ?? request.targetSeq } };
+        }
+        /**
+         * 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.
+         */
+        async edit(request) {
+            const session = this.ctx.sessions.get(request.sessionId);
+            if (session === undefined)
+                return { ok: false, error: { code: 'session-not-found' } };
+            const planned = planEdit(session.events, session.surface.nodes, request.targetSeq, request.text);
+            if (!planned.ok)
+                return { ok: false, error: { code: planned.code } };
+            const replacement = session.append('user/message', createUserMessage({
+                content: [{ type: 'text', text: request.text }],
+                source: editReplacementSource(),
+            }), {
+                surfaceOp: { op: 'replace', start: planned.plan.start, end: planned.plan.end },
+                sourceEventSeqs: [...planned.plan.sourceEventSeqs],
+            });
+            await this.ctx.sessions.flush(session);
+            const agent = this.ctx.agents.get(request.sessionId);
+            if (agent !== undefined) {
+                agent.followup(createUserMessage({
+                    content: [{ type: 'text', text: EDIT_TRIGGER_NOTICE }],
+                    source: editTriggerSource(),
+                }));
+            }
+            return { ok: true, value: { replacementSeq: replacement.seq, triggered: agent !== undefined } };
+        }
+    };
+})();
+export { MessageToolsService };
+export default MessageToolsService;

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@khorsheed/dsh-client-message-tools`.
+ * @module @khorsheed/dsh-client-message-tools/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "client-message-tools-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"invariant.d.ts","sourceRoot":"","sources":["../../src/invariant.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAKlD,oCAAoC;AACpC,eAAO,MAAM,IAAI,mCAAmC,CAAA;AACpD,2EAA2E;AAC3E,eAAO,MAAM,MAAM,UAAiB,CAAA;AAYpC;;;;GAIG;AACH,eAAO,MAAM,KAAK,QAAS,OAAO,KAAG,OAAO,CAAC,MAAM,IAAI,CACU,CAAA"}

package/lib/types/invariant.js

@@ -0,0 +1,25 @@
+/**
+ * Package-owned invariant companion for `@khorsheed/dsh-client-message-tools`.
+ * @module @khorsheed/dsh-client-message-tools/invariant
+ */
+const PACKAGE_NAME = '@khorsheed/dsh-client-message-tools';
+/** Cordis companion plugin name. */
+export const name = 'client-message-tools-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * No runtime invariant: the withdrawal write passes through Session.append,
+ * whose surface validation rejects any replacement that misses a shadowed
+ * surface node, and the client contributions (one Definition, two slot
+ * entries) ride the slot/declaration lifecycles disposed with the plugin
+ * fiber. The package's unit tests exercise the plan fold and the projection
+ * helpers, so no second authority exists to check at runtime.
+ */
+const install = () => { };
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+/* jscpd:ignore-end */

package/lib/types/marker.d.ts

@@ -0,0 +1,94 @@
+import type { MessageSource } from '@deepseek-ai/dsh-llm/message';
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types';
+/** Plugin source tag identifying every message-tools event. */
+export declare const MESSAGE_TOOLS_PLUGIN = "message-tools";
+/**
+ * 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
+ * keeps the surface non-empty and tells the model why the transcript jumps.
+ */
+export declare const WITHDRAWN_NOTICE = "(\u7528\u6237\u64A4\u56DE\u4E86\u8FD9\u6761\u6D88\u606F\u53CA\u5176\u540E\u7684\u6240\u6709\u5185\u5BB9)";
+/**
+ * Model-facing trigger message that starts the regeneration turn after an
+ * edit replacement lands (no wake-without-append path exists in the harness;
+ * `agent.followup` is the sanctioned seam). It is NOT the edited text — that
+ * appears exactly once, in the replacement event.
+ */
+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.
+ */
+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. */
+export type MessageToolsOp = 'edit' | 'edit-trigger' | 'restore-assistant';
+/** The plugin-tagged source of an edit replacement (op: 'edit'). */
+export declare function editReplacementSource(): MessageSource;
+/** The plugin-tagged 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'). */
+export declare function restoreAssistantSource(): MessageSource;
+/** Read the op discriminator off a message source (absent on legacy events). */
+export declare function messageToolsOp(source: unknown): MessageToolsOp | undefined;
+/**
+ * Strip the model-facing restore frame from a replayed assistant text for
+ * DISPLAY: the frame belongs to the model context (role honesty), never to
+ * the transcript row. Texts without the frame pass through unchanged.
+ * @param text - the replayed content's joined text.
+ * @returns the display text without the frame prefix.
+ */
+export declare function stripRestoreAssistantFrame(text: string): string;
+/** One message-tools withdrawal replacement event, narrowed. */
+export type MessageToolsReplacementEvent = SessionEvent<'user/message'> & {
+    readonly surfaceOp: {
+        readonly op: 'replace';
+        readonly start: number;
+        readonly end: number;
+    };
+};
+/** One message-tools edit replacement event, narrowed (same shape, `op: 'edit'` source). */
+export type MessageToolsEditEvent = MessageToolsReplacementEvent;
+/** One message-tools append-side event (restore or edit trigger), narrowed. */
+export type MessageToolsRestoreEvent = SessionEvent<'user/message'> & {
+    readonly surfaceOp: 'append';
+};
+/**
+ * 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).
+ * @param event - the session event to test.
+ * @returns the event narrowed to a withdrawal replacement when matched.
+ */
+export declare function isMessageToolsReplacement(event: SessionEvent): event is MessageToolsReplacementEvent;
+/**
+ * Whether the event is a message-tools EDIT replacement: a `user/message`
+ * surface replacement whose content IS the edited text (`op: 'edit'`).
+ * @param event - the session event to test.
+ * @returns the event narrowed to an edit replacement when matched.
+ */
+export declare function isMessageToolsEdit(event: SessionEvent): event is MessageToolsEditEvent;
+/**
+ * Whether the event is a message-tools restore: an append-surface
+ * `user/message` replaying a withdrawn message at the conversation tail.
+ * @param event - the session event to test.
+ * @returns the event narrowed to a message-tools restore when matched.
+ */
+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.
+ * @param event - the session event to test.
+ * @returns the event narrowed to an edit trigger when matched.
+ */
+export declare function isMessageToolsTrigger(event: SessionEvent): event is MessageToolsRestoreEvent;
+/**
+ * Whether the event is a message-tools ASSISTANT-text restore replay: an
+ * append-surface `user/message` carrying a withdrawn assistant reply's text
+ * (framed, user-role — see {@link RESTORED_ASSISTANT_NOTICE}).
+ * @param event - the session event to test.
+ * @returns the event narrowed to a restore-assistant replay when matched.
+ */
+export declare function isMessageToolsRestoreAssistant(event: SessionEvent): event is MessageToolsRestoreEvent;
+//# sourceMappingURL=marker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"marker.d.ts","sourceRoot":"","sources":["../../src/marker.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAA;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAA;AAElE,+DAA+D;AAC/D,eAAO,MAAM,oBAAoB,kBAAkB,CAAA;AAEnD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,6GAAwB,CAAA;AAErD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,iJAA8B,CAAA;AAE9D;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,+HAA2B,CAAA;AAEjE,+DAA+D;AAC/D,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,cAAc,GAAG,mBAAmB,CAAA;AAE1E,oEAAoE;AACpE,wBAAgB,qBAAqB,IAAI,aAAa,CAErD;AAED,gFAAgF;AAChF,wBAAgB,iBAAiB,IAAI,aAAa,CAEjD;AAED,8FAA8F;AAC9F,wBAAgB,sBAAsB,IAAI,aAAa,CAEtD;AAED,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,cAAc,GAAG,SAAS,CAG1E;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG/D;AAED,gEAAgE;AAChE,MAAM,MAAM,4BAA4B,GAAG,YAAY,CAAC,cAAc,CAAC,GAAG;IACxE,QAAQ,CAAC,SAAS,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;CAC7F,CAAA;AAED,4FAA4F;AAC5F,MAAM,MAAM,qBAAqB,GAAG,4BAA4B,CAAA;AAEhE,+EAA+E;AAC/E,MAAM,MAAM,wBAAwB,GAAG,YAAY,CAAC,cAAc,CAAC,GAAG;IACpE,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAA;CAC7B,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,YAAY,GAAG,KAAK,IAAI,4BAA4B,CAMpG;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,KAAK,IAAI,qBAAqB,CAMtF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,YAAY,GAAG,KAAK,IAAI,wBAAwB,CAM5F;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,YAAY,GAAG,KAAK,IAAI,wBAAwB,CAM5F;AAED;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,YAAY,GAAG,KAAK,IAAI,wBAAwB,CAMrG"}

package/lib/types/marker.js

@@ -0,0 +1,131 @@
+/**
+ * Shared message-tools markers: the plugin source tag stamped on withdrawal
+ * replacement events, the `op` discriminator telling edit replacements, edit
+ * triggers, and assistant-text restore replays apart from withdrawals and
+ * user-message restores, the model-facing placeholder and trigger texts, and
+ * the pure predicates both the Host service and the browser projection
+ * consume. No new session event type is ever written — an
+ * out-of-harness event type cannot carry `ignorable: true` (Session.append
+ * assigns the envelope), so a persisted unknown type would make
+ * session-persistence refuse the log on reload. The events themselves are the
+ * durable audit trail.
+ * @module @khorsheed/dsh-client-message-tools/marker
+ */
+import { isReplacementSurfaceEvent } from '@deepseek-ai/dsh-session/surface';
+/** Plugin source tag identifying every message-tools event. */
+export const MESSAGE_TOOLS_PLUGIN = 'message-tools';
+/**
+ * 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
+ * keeps the surface non-empty and tells the model why the transcript jumps.
+ */
+export const WITHDRAWN_NOTICE = '(用户撤回了这条消息及其后的所有内容)';
+/**
+ * Model-facing trigger message that starts the regeneration turn after an
+ * edit replacement lands (no wake-without-append path exists in the harness;
+ * `agent.followup` is the sanctioned seam). It is NOT the edited text — that
+ * appears exactly once, in the replacement event.
+ */
+export const EDIT_TRIGGER_NOTICE = '(用户编辑了上一条消息，请按编辑后的内容重新回答)';
+/**
+ * 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.
+ */
+export const RESTORED_ASSISTANT_NOTICE = '(以下是先前被撤回、现随恢复放回的助手回复)';
+/** The plugin-tagged source of an edit replacement (op: 'edit'). */
+export function editReplacementSource() {
+    return Object.freeze({ kind: 'plugin', plugin: MESSAGE_TOOLS_PLUGIN, op: 'edit' });
+}
+/** The plugin-tagged source of an edit trigger message (op: 'edit-trigger'). */
+export function editTriggerSource() {
+    return Object.freeze({ kind: 'plugin', plugin: MESSAGE_TOOLS_PLUGIN, op: 'edit-trigger' });
+}
+/** The plugin-tagged source of a restored assistant-text replay (op: 'restore-assistant'). */
+export function restoreAssistantSource() {
+    return Object.freeze({ kind: 'plugin', plugin: MESSAGE_TOOLS_PLUGIN, op: 'restore-assistant' });
+}
+/** Read the op discriminator off a message source (absent on legacy events). */
+export function messageToolsOp(source) {
+    const op = source?.op;
+    return op === 'edit' || op === 'edit-trigger' || op === 'restore-assistant' ? op : undefined;
+}
+/**
+ * Strip the model-facing restore frame from a replayed assistant text for
+ * DISPLAY: the frame belongs to the model context (role honesty), never to
+ * the transcript row. Texts without the frame pass through unchanged.
+ * @param text - the replayed content's joined text.
+ * @returns the display text without the frame prefix.
+ */
+export function stripRestoreAssistantFrame(text) {
+    const prefix = `${RESTORED_ASSISTANT_NOTICE}\n`;
+    return text.startsWith(prefix) ? text.slice(prefix.length) : text;
+}
+/**
+ * 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).
+ * @param event - the session event to test.
+ * @returns the event narrowed to a withdrawal replacement when matched.
+ */
+export function isMessageToolsReplacement(event) {
+    return event.type === 'user/message'
+        && isReplacementSurfaceEvent(event)
+        && event.data.source.kind === 'plugin'
+        && event.data.source.plugin === MESSAGE_TOOLS_PLUGIN
+        && messageToolsOp(event.data.source) === undefined;
+}
+/**
+ * Whether the event is a message-tools EDIT replacement: a `user/message`
+ * surface replacement whose content IS the edited text (`op: 'edit'`).
+ * @param event - the session event to test.
+ * @returns the event narrowed to an edit replacement when matched.
+ */
+export function isMessageToolsEdit(event) {
+    return event.type === 'user/message'
+        && isReplacementSurfaceEvent(event)
+        && event.data.source.kind === 'plugin'
+        && event.data.source.plugin === MESSAGE_TOOLS_PLUGIN
+        && messageToolsOp(event.data.source) === 'edit';
+}
+/**
+ * Whether the event is a message-tools restore: an append-surface
+ * `user/message` replaying a withdrawn message at the conversation tail.
+ * @param event - the session event to test.
+ * @returns the event narrowed to a message-tools restore when matched.
+ */
+export function isMessageToolsRestore(event) {
+    return event.type === 'user/message'
+        && event.surfaceOp === 'append'
+        && event.data.source.kind === 'plugin'
+        && event.data.source.plugin === MESSAGE_TOOLS_PLUGIN
+        && messageToolsOp(event.data.source) === undefined;
+}
+/**
+ * Whether the event is a message-tools edit trigger: the minimal
+ * plugin-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.
+ */
+export function isMessageToolsTrigger(event) {
+    return event.type === 'user/message'
+        && event.surfaceOp === 'append'
+        && event.data.source.kind === 'plugin'
+        && event.data.source.plugin === MESSAGE_TOOLS_PLUGIN
+        && messageToolsOp(event.data.source) === 'edit-trigger';
+}
+/**
+ * Whether the event is a message-tools ASSISTANT-text restore replay: an
+ * append-surface `user/message` carrying a withdrawn assistant reply's text
+ * (framed, user-role — see {@link RESTORED_ASSISTANT_NOTICE}).
+ * @param event - the session event to test.
+ * @returns the event narrowed to a restore-assistant replay when matched.
+ */
+export function isMessageToolsRestoreAssistant(event) {
+    return event.type === 'user/message'
+        && event.surfaceOp === 'append'
+        && event.data.source.kind === 'plugin'
+        && event.data.source.plugin === MESSAGE_TOOLS_PLUGIN
+        && messageToolsOp(event.data.source) === 'restore-assistant';
+}

package/lib/types/types.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Wire vocabulary shared by the messageTools Host Remote and its browser
+ * callers. Types only: the generated Remote codecs import this module
+ * type-side, and the client bundle never inlines host runtime code.
+ * @module @khorsheed/dsh-client-message-tools/types
+ */
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+/**
+ * Withdraw one user message: hide it and everything logged after it from the
+ * model surface and the chat projection.
+ */
+export interface MessageToolsWithdrawRequest {
+    /** Session that owns the target message. */
+    readonly sessionId: SessionId;
+    /** Seq of the append-surface `user/message` event to withdraw. */
+    readonly targetSeq: number;
+}
+/** What a landed withdrawal appended. */
+export interface MessageToolsWithdrawal {
+    /** Seq of the replacement event now standing in for the withdrawn span. */
+    readonly replacementSeq: number;
+    /** Count of surface nodes the replacement shadows. */
+    readonly shadowedCount: number;
+}
+/** Withdrawal failure vocabulary (closed union). */
+export type MessageToolsWithdrawFailure = {
+    readonly code: 'session-not-found';
+} | {
+    readonly code: 'target-not-found';
+} | {
+    readonly code: 'not-a-user-message';
+} | {
+    readonly code: 'already-withdrawn';
+};
+/** Withdrawal outcome: a landed receipt or a rejected failure. */
+export type MessageToolsWithdrawResult = {
+    readonly ok: true;
+    readonly value: MessageToolsWithdrawal;
+} | {
+    readonly ok: false;
+    readonly error: MessageToolsWithdrawFailure;
+};
+/**
+ * Restore a withdrawn user message: replay its content as a fresh user
+ * message at the conversation tail (positional restore is impossible — see
+ * the package README).
+ */
+export interface MessageToolsRestoreRequest {
+    /** Session that owns the withdrawn message. */
+    readonly sessionId: SessionId;
+    /** Seq of the withdrawn append-surface `user/message` event to restore. */
+    readonly targetSeq: number;
+}
+/** What a landed restore appended. */
+export interface MessageToolsRestoration {
+    /** Seq of the appended replay event. */
+    readonly restoredSeq: number;
+}
+/** Restore failure vocabulary (closed union). */
+export type MessageToolsRestoreFailure = {
+    readonly code: 'session-not-found';
+} | {
+    readonly code: 'target-not-found';
+} | {
+    readonly code: 'not-a-user-message';
+} | {
+    readonly code: 'not-withdrawn';
+};
+/** Restore outcome: a landed receipt or a rejected failure. */
+export type MessageToolsRestoreResult = {
+    readonly ok: true;
+    readonly value: MessageToolsRestoration;
+} | {
+    readonly ok: false;
+    readonly error: MessageToolsRestoreFailure;
+};
+/**
+ * Edit a user message in place: replace it (and the surface tail) with the
+ * edited text, then start a regeneration turn over the replaced surface.
+ */
+export interface MessageToolsEditRequest {
+    /** Session that owns the target message. */
+    readonly sessionId: SessionId;
+    /** Seq of the editable user message (an original or a previous edit's replacement). */
+    readonly targetSeq: number;
+    /** The edited text (non-blank). */
+    readonly text: string;
+}
+/** What a landed edit appended and started. */
+export interface MessageToolsEdit {
+    /** Seq of the replacement event carrying the edited text. */
+    readonly replacementSeq: number;
+    /** Whether the regeneration turn was triggered (false when no live agent). */
+    readonly triggered: boolean;
+}
+/** Edit failure vocabulary (closed union). */
+export type MessageToolsEditFailure = {
+    readonly code: 'session-not-found';
+} | {
+    readonly code: 'target-not-found';
+} | {
+    readonly code: 'not-a-user-message';
+} | {
+    readonly code: 'already-withdrawn';
+} | {
+    readonly code: 'empty-text';
+};
+/** Edit outcome: a landed receipt or a rejected failure. */
+export type MessageToolsEditResult = {
+    readonly ok: true;
+    readonly value: MessageToolsEdit;
+} | {
+    readonly ok: false;
+    readonly error: MessageToolsEditFailure;
+};
+//# sourceMappingURL=types.d.ts.map

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

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

package/lib/types/types.js

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