@khorsheed/dsh-client-message-tools 0.1.0

package/lib/index.js

@@ -0,0 +1,644 @@
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
+import { Remote, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
+import { isAppendSurfaceEvent, isReplacementSurfaceEvent } from "@deepseek-ai/dsh-session/surface";
+//#region lib/types/marker.js
+/**
+* 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
+*/
+/** Plugin source tag identifying every message-tools event. */
+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.
+*/
+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.
+*/
+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.
+*/
+const RESTORED_ASSISTANT_NOTICE = "(以下是先前被撤回、现随恢复放回的助手回复)";
+/** The plugin-tagged source of an edit replacement (op: 'edit'). */
+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'). */
+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'). */
+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). */
+function messageToolsOp(source) {
+	const op = source?.op;
+	return op === "edit" || op === "edit-trigger" || op === "restore-assistant" ? op : void 0;
+}
+/**
+* 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.
+*/
+function isMessageToolsReplacement(event) {
+	return event.type === "user/message" && isReplacementSurfaceEvent(event) && event.data.source.kind === "plugin" && event.data.source.plugin === "message-tools" && messageToolsOp(event.data.source) === void 0;
+}
+/**
+* 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.
+*/
+function isMessageToolsEdit(event) {
+	return event.type === "user/message" && isReplacementSurfaceEvent(event) && event.data.source.kind === "plugin" && event.data.source.plugin === "message-tools" && 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.
+*/
+function isMessageToolsRestore(event) {
+	return event.type === "user/message" && event.surfaceOp === "append" && event.data.source.kind === "plugin" && event.data.source.plugin === "message-tools" && messageToolsOp(event.data.source) === void 0;
+}
+/**
+* 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.
+*/
+function isMessageToolsRestoreAssistant(event) {
+	return event.type === "user/message" && event.surfaceOp === "append" && event.data.source.kind === "plugin" && event.data.source.plugin === "message-tools" && messageToolsOp(event.data.source) === "restore-assistant";
+}
+//#endregion
+//#region lib/types/withdraw.js
+/**
+* Withdrawal planning: a pure fold from the session log and the live surface
+* to the replacement intent. Kept free of cordis and Session internals so the
+* unit tests drive it directly; the service only validates and appends.
+* @module @khorsheed/dsh-client-message-tools/withdraw
+*/
+/**
+* Whether a target seq names an editable user message: an append-surface
+* user-source message (an original), a message-tools restore replay (a
+* restored row withdraws and edits like the message it replays), or a
+* message-tools edit replacement (edit chains — the previous edit's
+* replacement is the surface node). Assistant-text restore replays carry no
+* actions and are excluded.
+*/
+function isEditableTarget(event) {
+	if (event === void 0 || event.type !== "user/message") return false;
+	if (isAppendSurfaceEvent(event)) return event.data.source.kind === "user" || isMessageToolsRestore(event);
+	return isMessageToolsEdit(event);
+}
+/** The span [target, surface tail] with full provenance, or undefined when off-surface. */
+function surfaceSpan(surfaceNodes, targetSeq) {
+	const startIndex = surfaceNodes.indexOf(targetSeq);
+	if (startIndex === -1) return void 0;
+	const sourceEventSeqs = surfaceNodes.slice(startIndex);
+	const end = sourceEventSeqs[sourceEventSeqs.length - 1];
+	/* v8 ignore next -- the slice is non-empty by construction (startIndex names a member) */
+	if (end === void 0) return void 0;
+	return {
+		start: targetSeq,
+		end,
+		sourceEventSeqs
+	};
+}
+/**
+* Plan a withdrawal: the target must be an editable user message (original,
+* restore replay, or edit replacement — see `isEditableTarget`) still present
+* on the live surface; the span covers it and every surface node after it.
+* @param events - the full session log (seq === index).
+* @param surfaceNodes - the current model-visible surface seqs, in order.
+* @param targetSeq - seq of the user message to withdraw.
+* @returns the replacement intent, or the failure code.
+*/
+function planWithdrawal(events, surfaceNodes, targetSeq) {
+	const target = events[targetSeq];
+	if (target === void 0) return {
+		ok: false,
+		code: "target-not-found"
+	};
+	if (!isEditableTarget(target)) return {
+		ok: false,
+		code: "not-a-user-message"
+	};
+	const span = surfaceSpan(surfaceNodes, targetSeq);
+	if (span === void 0) return {
+		ok: false,
+		code: "already-withdrawn"
+	};
+	return {
+		ok: true,
+		plan: span
+	};
+}
+/**
+* Plan an edit: the target must be an editable user message still present on
+* the live surface, and the new text must be non-blank. The span covers the
+* target and every surface node after it — editing an old message discards
+* what followed it. The replacement's content is the new text (no
+* placeholder), so the model context reads the edited message in place.
+* @param events - the full session log (seq === index).
+* @param surfaceNodes - the current model-visible surface seqs, in order.
+* @param targetSeq - seq of the user message to edit.
+* @param text - the edited text.
+* @returns the replacement intent, or the failure code.
+*/
+function planEdit(events, surfaceNodes, targetSeq, text) {
+	if (text.trim() === "") return {
+		ok: false,
+		code: "empty-text"
+	};
+	const target = events[targetSeq];
+	if (target === void 0) return {
+		ok: false,
+		code: "target-not-found"
+	};
+	if (!isEditableTarget(target)) return {
+		ok: false,
+		code: "not-a-user-message"
+	};
+	const span = surfaceSpan(surfaceNodes, targetSeq);
+	if (span === void 0) return {
+		ok: false,
+		code: "already-withdrawn"
+	};
+	return {
+		ok: true,
+		plan: span
+	};
+}
+/** Join the text blocks of one message's content into one plain string. */
+function joinText(blocks) {
+	return blocks.filter((block) => block.type === "text" && typeof block.text === "string").map((block) => block.text).join("");
+}
+/**
+* Join an assistant message's visible text. Normal replies use text blocks;
+* interrupted replies may contain only reasoning. Prefer text when present,
+* otherwise preserve the reasoning so a restore does not drop the only
+* assistant content the user saw.
+*/
+function joinAssistantMessageText(blocks) {
+	const text = joinText(blocks);
+	if (text !== "") return text;
+	return blocks.filter((block) => block.type === "reasoning" && typeof block.text === "string").map((block) => block.text).join("");
+}
+/**
+* The full log seqs shadowed by the latest message-tools withdrawal
+* replacement citing `targetSeq`, or undefined when no such replacement exists
+* (the message left the surface through another producer, e.g. compaction).
+*
+* `sourceEventSeqs` is authoritative for the shadowed *surface* nodes, but an
+* interrupted assistant step may exist only as `assistant/chunk` events (no
+* `assistant/message` ever landed). Those chunks are not surface nodes, so
+* they are absent from `sourceEventSeqs`. The replacement's own `start` and
+* `seq` delimit the whole withdrawn log interval — `[start, seq)` — and are
+* still read from the replacement itself, never guessed from another producer.
+*/
+function findWithdrawnSpan(events, targetSeq) {
+	for (let index = events.length - 1; index > targetSeq; index--) {
+		const event = events[index];
+		if (event !== void 0 && isMessageToolsReplacement(event) && event.sourceEventSeqs?.includes(targetSeq)) {
+			const span = [];
+			for (let seq = event.surfaceOp.start; seq < event.seq; seq++) span.push(seq);
+			return span;
+		}
+	}
+}
+/**
+* Fold one withdrawn span into its replay entries, in span (original) order.
+* Replayed: user-source messages, edit replacements (their content is the
+* last edit's new text), earlier restore replays, and assistant text (framed;
+* restore-assistant replays already carry the frame). Skipped: withdrawal
+* placeholders, edit triggers, other plugin context, and tool calls/results.
+*
+* Assistant text normally comes from `assistant/message` surface events. A
+* turn that was interrupted before finalization may never emit
+* `assistant/message`; its visible content survives only as `assistant/chunk`
+* rows. Those chunks are folded into one assistant replay per step when no
+* final `assistant/message` exists for that step, so withdrawing/restoring an
+* interrupted reply does not lose the partial assistant content.
+*/
+function replayEntries(events, spanSeqs) {
+	const entries = [];
+	let pending;
+	const finalizedSteps = /* @__PURE__ */ new Set();
+	const flushPending = () => {
+		if (pending === void 0) return;
+		if (!pending.finalized) {
+			const text = [...pending.text.values()].join("");
+			const reasoning = [...pending.reasoning.values()].join("");
+			const replay = text !== "" ? text : reasoning;
+			if (replay !== "") entries.push({
+				role: "assistant",
+				text: `${RESTORED_ASSISTANT_NOTICE}\n${replay}`,
+				sourceSeq: pending.sourceSeq
+			});
+		}
+		pending = void 0;
+	};
+	const pushChunk = (event) => {
+		if (finalizedSteps.has(`${event.data.turn}:${event.data.step}`)) return;
+		if (pending === void 0 || pending.turn !== event.data.turn || pending.step !== event.data.step) {
+			flushPending();
+			pending = {
+				turn: event.data.turn,
+				step: event.data.step,
+				sourceSeq: event.seq,
+				text: /* @__PURE__ */ new Map(),
+				reasoning: /* @__PURE__ */ new Map(),
+				finalized: false
+			};
+		}
+		const chunk = event.data.chunk;
+		if (chunk.type === "text-delta") pending.text.set(chunk.index, (pending.text.get(chunk.index) ?? "") + chunk.text);
+		else if (chunk.type === "block-end" && chunk.block.type === "text") pending.text.set(chunk.index, chunk.block.text);
+		else if (chunk.type === "reasoning-delta") pending.reasoning.set(chunk.index, (pending.reasoning.get(chunk.index) ?? "") + chunk.text);
+		else if (chunk.type === "block-end" && chunk.block.type === "reasoning") pending.reasoning.set(chunk.index, chunk.block.text);
+	};
+	const pushAssistantText = (text, sourceSeq) => {
+		if (text !== "") entries.push({
+			role: "assistant",
+			text: `${RESTORED_ASSISTANT_NOTICE}\n${text}`,
+			sourceSeq
+		});
+	};
+	for (const seq of spanSeqs) {
+		const event = events[seq];
+		if (event === void 0) continue;
+		if (isMessageToolsEdit(event)) {
+			flushPending();
+			entries.push({
+				role: "user",
+				content: event.data.content,
+				sourceSeq: seq
+			});
+			continue;
+		}
+		if (event.type === "assistant/chunk") {
+			pushChunk(event);
+			continue;
+		}
+		if (event.type === "user/message") {
+			flushPending();
+			if (event.surfaceOp !== "append") continue;
+			if (event.data.source.kind === "user" || isMessageToolsRestore(event)) entries.push({
+				role: "user",
+				content: event.data.content,
+				sourceSeq: seq
+			});
+			else if (isMessageToolsRestoreAssistant(event)) entries.push({
+				role: "assistant",
+				text: joinText(event.data.content),
+				sourceSeq: seq
+			});
+			continue;
+		}
+		if (event.type === "assistant/message") {
+			finalizedSteps.add(`${event.data.turn}:${event.data.step}`);
+			if (pending !== void 0 && pending.turn === event.data.turn && pending.step === event.data.step) pending.finalized = true;
+			flushPending();
+			pushAssistantText(joinAssistantMessageText(event.data.message.content), seq);
+			continue;
+		}
+	}
+	flushPending();
+	return entries;
+}
+/**
+* Plan a restore: the target must be an editable user message (the same
+* vocabulary as withdrawal — original, restore replay, or edit replacement)
+* that is no longer on the live surface (i.e. withdrawn). Restoring an edit
+* replacement replays the span's last edit text — the replacement's content
+* IS the new text. The surface model is positional — a replaced span folds
+* into exactly one node — so the withdrawn span can never be put back in
+* place; restore replays the span's replayable content (user messages, the
+* last edit's new text, assistant text) as fresh tail messages in original
+* order. When no message-tools replacement cites the target (a foreign
+* shadowing, e.g. compaction), only the target message replays — the span
+* boundary is never re-guessed.
+* @param events - the full session log (seq === index).
+* @param surfaceNodes - the current model-visible surface seqs.
+* @param targetSeq - seq of the withdrawn user message to restore.
+* @returns the restore intent, or the failure code.
+*/
+function planRestore(events, surfaceNodes, targetSeq) {
+	const target = events[targetSeq];
+	if (target === void 0) return {
+		ok: false,
+		code: "target-not-found"
+	};
+	if (!isEditableTarget(target)) return {
+		ok: false,
+		code: "not-a-user-message"
+	};
+	if (surfaceNodes.includes(targetSeq)) return {
+		ok: false,
+		code: "not-withdrawn"
+	};
+	const span = findWithdrawnSpan(events, targetSeq);
+	return {
+		ok: true,
+		plan: { entries: span === void 0 ? [{
+			role: "user",
+			content: target.data.content,
+			sourceSeq: targetSeq
+		}] : replayEntries(events, span) }
+	};
+}
+//#endregion
+//#region lib/types/index.js
+var __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 = 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;
+};
+/**
+* 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 === void 0) 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 === void 0) 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 === void 0) 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 !== void 0) agent.followup(createUserMessage({
+				content: [{
+					type: "text",
+					text: EDIT_TRIGGER_NOTICE
+				}],
+				source: editTriggerSource()
+			}));
+			return {
+				ok: true,
+				value: {
+					replacementSeq: replacement.seq,
+					triggered: agent !== void 0
+				}
+			};
+		}
+	};
+})();
+//#endregion
+export { MessageToolsService, MessageToolsService as default };

package/lib/invariant.js

@@ -0,0 +1,27 @@
+//#region lib/types/invariant.js
+/**
+* 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. */
+const name = "client-message-tools-invariant";
+/** Service required before the companion can reserve package ownership. */
+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.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };