dsh-command-context-trim 0.1.0 → 0.2.0

package/lib/index.js

@@ -13,15 +13,19 @@
  * synchronous appends, zero LLM calls, so it works precisely when every request
  * is failing.
  *
+ * The same execution also runs **automatically** on the context wall: a
+ * prepended `agent/request-error` listener trims on `CONTEXT_WINDOW_EXCEEDED` and
+ * retries, and only hands the problem to compaction (prune + summarize) when it
+ * cannot free anything — see `./auto-trim.js`.
+ *
  * @module dsh-command-context-trim
  */
-import { toolPairingBalancedAfter, toolPairingBalancedBefore } from '@deepseek-ai/dsh-compaction';
 import z from '@deepseek-ai/schemastery';
 import { parseTrimArguments, USAGE } from './args.js';
-import { applyTrim, createMarkerMessage, provisionalMarker } from './apply.js';
-import { budgetFor, resolveConfig, retentionFor } from './config.js';
-import { planTrim } from './plan.js';
-import { resolveTarget, targetHeader } from './target.js';
+import { registerAutoTrim } from './auto-trim.js';
+import { resolveConfig } from './config.js';
+import { describeError } from './render.js';
+import { executeTrim } from './trim-session.js';
 
 /** Cordis plugin name. */
 export const name = 'context-trim';
@@ -29,7 +33,7 @@ export const name = 'context-trim';
 /** Services required before the command can be registered. */
 export const inject = ['commands', 'tokenMeter', 'llm'];
 
-/** Loader-facing configuration shape; ranges are enforced by {@link resolveConfig}. */
+/** Loader-facing configuration shape; ranges are enforced by `resolveConfig`. */
 export const Config = z.object({
 	targetRatio: z.number(),
 	reserveOutputTokens: z.number(),
@@ -38,11 +42,14 @@ export const Config = z.object({
 	minTailTokens: z.number(),
 	protectHeadNodes: z.number(),
 	allowTailTrim: z.boolean(),
-	markerSlackTokens: z.number()
+	markerSlackTokens: z.number(),
+	autoTrim: z.boolean(),
+	maxAutoTrimRetries: z.number()
 });
 
 /**
- * Register `/trim` for every composed human-command adapter.
+ * Register `/trim` for every composed human-command adapter, and the automatic
+ * context-overflow handler for every agent.
  * @param ctx - context carrying the command registry, token meter, and LLM service.
  * @param config - untrusted plugin configuration.
  */
@@ -69,6 +76,7 @@ export function apply(ctx, config) {
 			handler
 		});
 	}, 'context-trim lifecycle');
+	registerAutoTrim(ctx, resolved);
 }
 
 /**
@@ -83,7 +91,17 @@ async function execute(ctx, config, invocation) {
 	if (parsed.error !== undefined) return { kind: 'error', text: `${parsed.error}\n${USAGE}` };
 	let running;
 	try {
-		running = invocation.agent.runMaintenance((agentSignal) => trimOnce(ctx, config, invocation, parsed, agentSignal));
+		running = invocation.agent.runMaintenance(async (agentSignal) => {
+			const signal = AbortSignal.any([invocation.signal, agentSignal]);
+			const { result } = await executeTrim(ctx, config, {
+				agent: invocation.agent,
+				signal,
+				requestedRoute: parsed.route,
+				explicitBudget: parsed.budget,
+				check: parsed.check
+			});
+			return result;
+		});
 	} catch (error) {
 		return { kind: 'error', text: `Trim needs an idle agent: ${describeError(error)}` };
 	}
@@ -94,139 +112,3 @@ async function execute(ctx, config, invocation) {
 		return { kind: 'error', text: `Trim failed: ${describeError(error)}` };
 	}
 }
-
-/**
- * Plan and apply one trim; the whole session-visible mutation happens here.
- * @param ctx - plugin context.
- * @param config - resolved configuration.
- * @param invocation - command invocation (agent, signal).
- * @param parsed - parsed command arguments.
- * @param agentSignal - cancellation owned by the maintenance reservation.
- * @returns a command result.
- */
-async function trimOnce(ctx, config, invocation, parsed, agentSignal) {
-	const signal = AbortSignal.any([invocation.signal, agentSignal]);
-	signal.throwIfAborted();
-	const session = invocation.agent.session;
-	assertNoOpenCompaction(session);
-	const target = parsed.budget === undefined ? await resolveTarget(ctx, invocation.agent, parsed.route, signal) : undefined;
-	const budget = parsed.budget ?? budgetFor(target.contextWindow, config);
-	const label = target === undefined ? `an explicit ${budget}-token budget` : `${target.label} (window ${target.contextWindow})`;
-	const header = target === undefined ? undefined : targetHeader(session, target);
-	const measurement = ctx.tokenMeter.measure(session, header);
-	const nodes = measurement.nodes.map((node) => ({ seq: node.seq, heuristicTokens: node.heuristicTokens }));
-	if (nodes.length === 0) {
-		return { kind: 'success', text: `Nothing to trim: ${session.id} has no model-visible messages yet.` };
-	}
-	// The retained tail scales with the capacity being fitted: the target window
-	// when one is known, otherwise the explicit budget itself.
-	const retainTokens = retentionFor(target?.contextWindow ?? budget, config);
-	const envelopeTokens = Math.max(0, measurement.totalTokens - measurement.surfaceTokens);
-	const planFor = (markerTokens) =>
-		planTrim({
-			nodes,
-			envelopeTokens,
-			budget,
-			markerCost: markerTokens + config.markerSlackTokens,
-			retainTokens,
-			minTailTokens: config.minTailTokens,
-			protectHeadNodes: config.protectHeadNodes,
-			allowTailTrim: config.allowTailTrim,
-			isBalancedBefore: (seq) => toolPairingBalancedBefore(session, seq),
-			isBalancedAfter: (seq) => toolPairingBalancedAfter(session, seq)
-		});
-	let markerTokens = ctx.tokenMeter.estimateMessage(provisionalMarker());
-	let plan = planFor(markerTokens);
-	if (plan.kind !== 'span') return describeNonSpan(plan, label);
-	let marker = createMarkerMessage(plan, target?.label ?? `budget ${budget}`, budget);
-	const finalMarkerTokens = ctx.tokenMeter.estimateMessage(marker);
-	if (finalMarkerTokens > markerTokens) {
-		// The marker now carries real numbers; re-plan once so its own price is exact.
-		plan = planFor(finalMarkerTokens);
-		if (plan.kind !== 'span') return describeNonSpan(plan, label);
-		marker = createMarkerMessage(plan, target?.label ?? `budget ${budget}`, budget);
-		markerTokens = finalMarkerTokens;
-	}
-	if (parsed.check) return { kind: 'success', text: preview(plan, label, markerTokens) };
-	const replacement = applyTrim(session, plan, marker);
-	const after = ctx.tokenMeter.measure(session, header);
-	return { kind: 'success', text: report(plan, after, label, markerTokens), sourceEventSeq: replacement.seq };
-}
-
-/** Refuse to rewrite a surface while a compaction bracket is open. */
-function assertNoOpenCompaction(session) {
-	for (let seq = session.seq - 1; seq >= 0; seq -= 1) {
-		const event = session.eventAt(seq);
-		if (event === undefined) continue;
-		if (event.type === 'compaction/end') return;
-		// A seed boundary proves any earlier unmatched start belongs to a previous lifecycle.
-		if (event.type === 'session/end-seed') return;
-		if (event.type === 'compaction/start') {
-			throw new Error('a compaction is already in progress in this session; wait for it to finish, then retry');
-		}
-	}
-}
-
-/** Render every non-span outcome as a final command result. */
-function describeNonSpan(plan, label) {
-	switch (plan.kind) {
-		case 'fits':
-			return {
-				kind: 'success',
-				text: `Already within budget: ~${plan.totalTokens} / ${plan.budget} tokens for ${label}. Nothing to trim.`
-			};
-		case 'envelope':
-			return {
-				kind: 'error',
-				text: [
-					`Fixed request overhead alone (~${plan.envelopeTokens} tokens of system prompt and tool schemas) exceeds the ${plan.budget}-token budget for ${label}.`,
-					'Trimming conversation history cannot help: raise the backend context size (the model\'s contextWindow in settings.yaml, or the server\'s context flag) or reduce mounted tools and skills, then retry.'
-				].join('\n')
-			};
-		case 'no-span':
-			return {
-				kind: 'error',
-				text: `Nothing safely trimmable for ${label}: ${plan.reason}, or no tool-pairing balanced cut exists.`
-			};
-		case 'insufficient':
-			return {
-				kind: 'error',
-				text: [
-					`Cannot free enough for ${label}: the largest balanced span frees ~${plan.maxFreeable} of the ~${plan.need} tokens needed.`,
-					`Protected content: task statement ~${plan.protectedHeadTokens} tokens, recent tail ~${plan.protectedTailTokens} tokens (retain target ~${plan.retainTokens}).`,
-					'Try /compact (it summarizes instead of dropping), a larger window, or /trim with an explicit budget after another reduction.'
-				].join('\n')
-			};
-		default:
-			return { kind: 'error', text: `Trim could not plan a reduction (${String(plan.kind)}).` };
-	}
-}
-
-/** Render a dry run. */
-function preview(plan, label, markerTokens) {
-	return [
-		`Would trim ${plan.shadowedSeqs.length} messages (seqs ${plan.startSeq}-${plan.endSeq}, ~${plan.shadowedTokens} tokens → ${markerTokens}-token marker) for ${label}.`,
-		`Request size: ~${plan.totalTokens} → ~${plan.projectedTotal} tokens (target ${plan.budget}). Nothing was changed.`
-	].join('\n');
-}
-
-/** Render a committed trim against the re-measured request. */
-function report(plan, after, label, markerTokens) {
-	const lines = [
-		`Trimmed ${plan.shadowedSeqs.length} messages (seqs ${plan.startSeq}-${plan.endSeq}, ~${plan.shadowedTokens} tokens → ${markerTokens}-token marker) for ${label}.`,
-		`Request size: ~${plan.totalTokens} → ~${after.totalTokens} tokens (target ${plan.budget}).`
-	];
-	if (plan.relaxedRetention) {
-		lines.push(`Retention relaxed to ~${plan.retainTokens} tokens to reach the budget.`);
-	}
-	return lines.join('\n');
-}
-
-/** Render a thrown value without trusting its string coercion. */
-function describeError(error) {
-	try {
-		return error instanceof Error ? error.message : String(error);
-	} catch {
-		return '<unrenderable thrown value>';
-	}
-}

package/lib/plan.js

@@ -8,6 +8,21 @@
  * and the original request are the two pieces of high-value context; everything
  * between them is what a smaller window can afford to lose.
  *
+ * Two node classes are never elidable:
+ *
+ * - **Barriers** (`barrier: true`) — the system prompt. Harness 0.1.5 moved it
+ *   from the request header onto the surface as node 0, which makes it
+ *   *trimmable* by position: dropping it would strip the model's instructions,
+ *   and letting it consume the head-protection budget would expose the user's
+ *   original request instead. Barriers are therefore untouchable and split the
+ *   elidable space into regions, and `protectHeadNodes` counts only non-barrier
+ *   nodes so it keeps protecting the task statement.
+ * - **The newest `user/message`** — the live human instruction — plus the
+ *   retained tail. An earlier rule protected the final surface node outright,
+ *   which deadlocked exactly the common overflow shape: a large assistant
+ *   tool-call whose tool result is the last node could not be removed as a pair,
+ *   leaving only a few tokens freeable while the request stayed over the wall.
+ *
  * Nothing here touches a session: the planner receives measured node prices and
  * two balance predicates, so every branch is directly testable.
  *
@@ -18,17 +33,21 @@
  * @typedef {object} TrimNode
  * @property {number} seq - surface event sequence of the node.
  * @property {number} heuristicTokens - the token meter's heuristic price for it.
+ * @property {boolean} [barrier] - true for a node that may never be elided and
+ *   that no elided span may cross (the system prompt).
+ * @property {boolean} [userMessage] - true for human prompts; the newest one is
+ *   treated as a barrier so an ongoing instruction is never elided.
  */
 
 /**
  * @typedef {object} TrimPlanInput
  * @property {readonly TrimNode[]} nodes - current surface nodes in model-visible order.
- * @property {number} envelopeTokens - non-surface request price (system prompt + tool schemas).
+ * @property {number} envelopeTokens - non-surface request price (tool schemas and other fixed request data).
  * @property {number} budget - target total request size in tokens.
  * @property {number} markerCost - priced replacement marker, including configured slack.
  * @property {number} retainTokens - preferred verbatim recent-tail budget.
  * @property {number} minTailTokens - absolute floor for that retained tail.
- * @property {number} protectHeadNodes - leading nodes that must never be elided.
+ * @property {number} protectHeadNodes - leading non-barrier nodes that must never be elided.
  * @property {boolean} allowTailTrim - whether the elided span may reach into the retained tail.
  * @property {(seq: number) => boolean} isBalancedBefore - tool-pairing balance before a node.
  * @property {(seq: number) => boolean} isBalancedAfter - tool-pairing balance after a node.
@@ -45,7 +64,8 @@ export function planTrim(input) {
 		totalTokens: input.envelopeTokens + surfaceTokens,
 		surfaceTokens,
 		envelopeTokens: input.envelopeTokens,
-		budget: input.budget
+		budget: input.budget,
+		hasBarrier: input.nodes.some((node) => node.barrier === true)
 	};
 	if (common.totalTokens <= input.budget) return { kind: 'fits', ...common };
 	if (input.envelopeTokens >= input.budget) return { kind: 'envelope', ...common };
@@ -55,32 +75,67 @@ export function planTrim(input) {
 	const need = common.totalTokens - input.budget;
 	const configuredRetention = input.retainTokens;
 	let weakest = null;
-	for (const retainTokens of retentionLadder(configuredRetention, input.minTailTokens)) {
-		const attempt = attemptSpan({ ...input, retainTokens, need });
+	for (const configuration of attemptConfigurations(input, configuredRetention)) {
+		const attempt = attemptSpan({ ...input, ...configuration, need });
 		if (attempt.kind === 'span') {
 			return {
 				kind: 'span',
 				...common,
 				...attempt,
 				need,
-				retainTokens,
-				relaxedRetention: retainTokens < configuredRetention,
+				retainTokens: configuration.retainTokens,
+				relaxedRetention: configuration.retainTokens < configuredRetention,
+				reachedFinalNode: configuration.allowFinalNode === true,
 				projectedTotal: common.totalTokens - attempt.freedTokens
 			};
 		}
-		if (weakest === null || attempt.maxFreeable > weakest.maxFreeable) weakest = { ...attempt, retainTokens };
+		if (weakest === null || attempt.maxFreeable > weakest.maxFreeable) weakest = { ...attempt, retainTokens: configuration.retainTokens };
 	}
 	return {
 		kind: 'insufficient',
 		...common,
 		need,
 		maxFreeable: weakest?.maxFreeable ?? 0,
-		protectedHeadTokens: headTokens(input.nodes, input.protectHeadNodes),
+		protectedHeadTokens: protectedHeadTokens(input.nodes, input.protectHeadNodes),
 		protectedTailTokens: weakest?.protectedTailTokens ?? 0,
+		protectedUserTokens: weakest?.protectedUserTokens ?? 0,
 		retainTokens: configuredRetention
 	};
 }
 
+/**
+ * The search order, most conservative first. The final surface node is a
+ * *preference*, not a law: keeping it is always tried before dropping it, and
+ * dropping it happens only when no other span can free enough.
+ *
+ * 1. stay outside the retained tail and keep the final node (the configured
+ *    retention, relaxed step by step only if the fit otherwise fails);
+ * 2. may reach into the retained tail, still keeping the final node;
+ * 3. last resort: a span that includes the final node (typically the current
+ *    step's assistant tool-call plus its tool result, which can only be removed
+ *    as a pair).
+ *
+ * Elision always starts at the oldest balanced cut, so within every tier the
+ * oldest content goes first. A strict `allowTailTrim: false` ends the list after
+ * tier 1: the retained tail then is a hard boundary.
+ * @param input - planning input.
+ * @param configuredRetention - the preferred verbatim recent-tail budget.
+ * @returns ordered attempt configurations.
+ */
+function attemptConfigurations(input, configuredRetention) {
+	const insideTail = retentionLadder(configuredRetention, input.minTailTokens).map((retainTokens) => ({
+		retainTokens,
+		tailHard: true,
+		allowFinalNode: false
+	}));
+	if (input.allowTailTrim !== true) return insideTail;
+	return [
+		...insideTail,
+		{ retainTokens: configuredRetention, tailHard: false, allowFinalNode: false },
+		{ retainTokens: configuredRetention, tailHard: false, allowFinalNode: true }
+	];
+}
+
 /**
  * Try one retention budget, returning the smallest oldest-anchored balanced span
  * that frees at least `need` tokens.
@@ -90,26 +145,52 @@ export function planTrim(input) {
 function attemptSpan(input) {
 	const nodes = input.nodes;
 	const tailStart = tailStartIndex(nodes, input.retainTokens);
-	const lastElidable = input.allowTailTrim ? nodes.length - 2 : Math.min(nodes.length - 2, tailStart - 1);
+	// The newest human instruction is the anchor: it must never be elided, and no
+	// span may cross it.
+	const newestUserIndex = newestUserMessageIndex(nodes);
+	// How far right a span may reach: a hard tail boundary when this attempt keeps
+	// the retained tail, otherwise the end of the surface.
+	const tailFloor = input.tailHard === true ? Math.min(nodes.length - 1, tailStart - 1) : nodes.length - 1;
+	// The final node is kept unless this attempt is the last-resort tier.
+	const lastElidable = input.allowFinalNode === true ? tailFloor : Math.min(tailFloor, nodes.length - 2);
 	const shortfall = (maxFreeable) => ({
 		kind: 'shortfall',
 		maxFreeable,
 		protectedTailTokens: tailTokens(nodes, tailStart),
-		protectedHeadTokens: headTokens(nodes, input.protectHeadNodes)
+		protectedHeadTokens: protectedHeadTokens(nodes, input.protectHeadNodes),
+		protectedUserTokens: newestUserIndex === -1 ? 0 : nodes[newestUserIndex].heuristicTokens
 	});
-	const from = Math.min(input.protectHeadNodes, nodes.length - 1);
-	if (lastElidable < from) return shortfall(0);
+	const headEnd = protectedHeadEnd(nodes, input.protectHeadNodes);
+	if (lastElidable < headEnd) return shortfall(0);
+	let weakest = null;
+	for (const region of elidableRegions(nodes, headEnd, lastElidable, newestUserIndex)) {
+		const attempt = attemptRegion(nodes, region, input);
+		if (attempt === null) continue;
+		if (attempt.kind === 'span') return attempt;
+		if (weakest === null || attempt.maxFreeable > weakest.maxFreeable) weakest = attempt;
+	}
+	return shortfall(weakest?.maxFreeable ?? 0);
+}
+
+/**
+ * Grow the smallest balanced span from one region's oldest balanced cut.
+ * @param nodes - full priced surface.
+ * @param region - inclusive index range free of barriers.
+ * @param input - planning input carrying `need`, `markerCost`, and the balance predicates.
+ * @returns a `span` plan, or this region's best `shortfall`.
+ */
+function attemptRegion(nodes, region, input) {
 	let start = -1;
-	for (let index = from; index <= lastElidable; index += 1) {
+	for (let index = region.start; index <= region.end; index += 1) {
 		if (input.isBalancedBefore(nodes[index].seq)) {
 			start = index;
 			break;
 		}
 	}
-	if (start === -1) return shortfall(0);
+	if (start === -1) return null;
 	let accumulated = 0;
 	let best = null;
-	for (let index = start; index <= lastElidable; index += 1) {
+	for (let index = start; index <= region.end; index += 1) {
 		accumulated += nodes[index].heuristicTokens;
 		if (!input.isBalancedAfter(nodes[index].seq)) continue;
 		const freedTokens = accumulated - input.markerCost;
@@ -126,9 +207,48 @@ function attemptSpan(input) {
 		}
 		if (freedTokens >= input.need) break;
 	}
-	return best === null ? shortfall(0) : best.freedTokens >= input.need
-		? { kind: 'span', ...best }
-		: shortfall(best.freedTokens);
+	return best === null ? null : best.freedTokens >= input.need ? { kind: 'span', ...best } : { kind: 'shortfall', maxFreeable: best.freedTokens };
+}
+
+/** Index just past the `protectHeadNodes`-th non-barrier node. */
+function protectedHeadEnd(nodes, protectHeadNodes) {
+	let counted = 0;
+	for (let index = 0; index < nodes.length; index += 1) {
+		if (nodes[index].barrier === true) continue;
+		counted += 1;
+		if (counted >= protectHeadNodes) return index + 1;
+	}
+	return nodes.length;
+}
+
+/** Index of the newest human prompt on the surface, or -1 when there is none. */
+function newestUserMessageIndex(nodes) {
+	let found = -1;
+	for (let index = 0; index < nodes.length; index += 1) if (nodes[index].userMessage === true) found = index;
+	return found;
+}
+
+/**
+ * Maximal runs of elidable indices inside `[from, to]`.
+ * @param nodes - full priced surface.
+ * @param from - inclusive first index to consider.
+ * @param to - inclusive last index to consider.
+ * @param extraBarrier - one additional index treated as a barrier (the newest user message).
+ * @returns contiguous index runs a span may occupy.
+ */
+function elidableRegions(nodes, from, to, extraBarrier) {
+	const regions = [];
+	let start = null;
+	for (let index = from; index <= to; index += 1) {
+		if (nodes[index].barrier === true || index === extraBarrier) {
+			if (start !== null) regions.push({ start, end: index - 1 });
+			start = null;
+			continue;
+		}
+		if (start === null) start = index;
+	}
+	if (start !== null) regions.push({ start, end: to });
+	return regions;
 }
 
 /**
@@ -162,9 +282,9 @@ function tailTokens(nodes, tailStart) {
 	return total;
 }
 
-/** Tokens held by the protected leading nodes. */
-function headTokens(nodes, protectHeadNodes) {
+/** Tokens held by the protected prefix, barriers included. */
+function protectedHeadTokens(nodes, protectHeadNodes) {
 	let total = 0;
-	for (let index = 0; index < Math.min(protectHeadNodes, nodes.length); index += 1) total += nodes[index].heuristicTokens;
+	for (let index = 0; index < protectedHeadEnd(nodes, protectHeadNodes); index += 1) total += nodes[index].heuristicTokens;
 	return total;
 }

package/lib/render.js

@@ -0,0 +1,115 @@
+/**
+ * Command-result and log rendering, shared by the `/trim` command and the
+ * automatic context-overflow path.
+ *
+ * @module dsh-command-context-trim/render
+ */
+
+/**
+ * Render every non-span planning outcome as a final command result.
+ * @param plan - the plan returned by `planTrim`.
+ * @param label - human label of the target route.
+ * @returns a command result.
+ */
+export function describeNonSpan(plan, label) {
+	switch (plan.kind) {
+		case 'fits':
+			return {
+				kind: 'success',
+				text: `Already within budget: ~${plan.totalTokens} / ${plan.budget} tokens for ${label}. Nothing to trim.`
+			};
+		case 'envelope':
+			return {
+				kind: 'error',
+				text: [
+					`Fixed request overhead alone (~${plan.envelopeTokens} tokens of tool schemas and other non-surface request data) exceeds the ${plan.budget}-token budget for ${label}.`,
+					'Trimming conversation history cannot help: raise the backend context size (the model\'s contextWindow in settings.yaml, or the server\'s context flag) or reduce mounted tools and skills, then retry.'
+				].join('\n')
+			};
+		case 'no-span':
+			return {
+				kind: 'error',
+				text: `Nothing safely trimmable for ${label}: ${plan.reason}, or no tool-pairing balanced cut exists.`
+			};
+		case 'insufficient':
+			return {
+				kind: 'error',
+				text: [
+					`Cannot free enough for ${label}: the largest balanced span frees ~${plan.maxFreeable} of the ~${plan.need} tokens needed.`,
+					`Protected content: task statement ~${plan.protectedHeadTokens} tokens, recent tail ~${plan.protectedTailTokens} tokens (retain target ~${plan.retainTokens})` +
+						`${plan.protectedUserTokens > 0 ? `, newest instruction ~${plan.protectedUserTokens} tokens (never elided)` : ''}` +
+						`${plan.hasBarrier ? ', plus the system prompt, which is never trimmed' : ''}.`,
+					'Try /compact (it summarizes instead of dropping), a larger window, or /trim with an explicit budget after another reduction.'
+				].join('\n')
+			};
+		default:
+			return { kind: 'error', text: `Trim could not plan a reduction (${String(plan.kind)}).` };
+	}
+}
+
+/**
+ * Render a dry run.
+ * @param plan - a committed span plan.
+ * @param label - human label of the target route.
+ * @param markerTokens - measured price of the replacement marker.
+ * @returns the dry-run text.
+ */
+export function preview(plan, label, markerTokens) {
+	return [
+		`Would trim ${plan.shadowedSeqs.length} messages (seqs ${plan.startSeq}-${plan.endSeq}, ~${plan.shadowedTokens} tokens → ${markerTokens}-token marker) for ${label}.`,
+		`Request size: ~${plan.totalTokens} → ~${plan.projectedTotal} tokens (target ${plan.budget}). Nothing was changed.`,
+		...(plan.reachedFinalNode === true
+			? ['Note: nothing else can free enough — this plan has to remove the final surface message as a tool-call/result pair.']
+			: [])
+	].join('\n');
+}
+
+/**
+ * Render a committed trim against the re-measured request.
+ * @param plan - the committed span plan.
+ * @param after - post-trim measurement.
+ * @param label - human label of the target route.
+ * @param markerTokens - measured price of the replacement marker.
+ * @returns the report text.
+ */
+export function report(plan, after, label, markerTokens) {
+	const lines = [
+		`Trimmed ${plan.shadowedSeqs.length} messages (seqs ${plan.startSeq}-${plan.endSeq}, ~${plan.shadowedTokens} tokens → ${markerTokens}-token marker) for ${label}.`,
+		`Request size: ~${plan.totalTokens} → ~${after.totalTokens} tokens (target ${plan.budget}).`
+	];
+	if (plan.relaxedRetention) {
+		lines.push(`Retention relaxed to ~${plan.retainTokens} tokens to reach the budget.`);
+	}
+	if (plan.reachedFinalNode === true) {
+		lines.push('Nothing else could free enough: the final surface message was removed as part of a tool-call/result pair.');
+	}
+	return lines.join('\n');
+}
+
+/**
+ * Render a committed trim as one log line, for the automatic path.
+ * @param plan - the committed span plan.
+ * @param after - post-trim measurement.
+ * @param label - human label of the target route.
+ * @returns a single-line account.
+ */
+export function logLine(plan, after, label) {
+	return (
+		`freed ~${plan.freedTokens} tokens over ${plan.shadowedSeqs.length} messages (seqs ${plan.startSeq}-${plan.endSeq}) for ${label}; ` +
+		`request ~${plan.totalTokens} → ~${after.totalTokens} tokens (budget ${plan.budget})` +
+		`${plan.reachedFinalNode === true ? ' (last resort: the final message went as a tool-call/result pair)' : ''}`
+	);
+}
+
+/**
+ * Render a thrown value without trusting its string coercion.
+ * @param error - the caught value (`unknown` in catch clauses).
+ * @returns a printable message.
+ */
+export function describeError(error) {
+	try {
+		return error instanceof Error ? error.message : String(error);
+	} catch {
+		return '<unrenderable thrown value>';
+	}
+}

package/lib/session-compat.js

@@ -0,0 +1,80 @@
+/**
+ * Version tolerance for the harness's positional replacement marker.
+ *
+ * DeepSeek Harness renamed the surface-replacement keys in 0.1.5
+ * (`{op:'replace', start, end}` → `{op:'replace', startSeq, endSeq}`), and the
+ * session rejects any other shape at append time. Rather than parse a version
+ * string, the accepted shape is probed once against the harness actually
+ * installed: a throwaway detached session appends one replacement with each
+ * candidate and reports the first accepted.
+ *
+ * @module dsh-command-context-trim/session-compat
+ */
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { Session } from '@deepseek-ai/dsh-session';
+
+/** Candidate key sets, newest harness first. */
+const CANDIDATES = Object.freeze([
+	Object.freeze({ start: 'startSeq', end: 'endSeq' }),
+	Object.freeze({ start: 'start', end: 'end' })
+]);
+
+/** Cached probe result for the installed harness. */
+let cached;
+
+/**
+ * The replacement-marker keys this harness accepts.
+ * @returns `{ start, end }` key names.
+ * @throws when the harness accepts none of the known shapes.
+ */
+export function replaceKeys() {
+	cached ??= detectReplaceKeys();
+	return cached;
+}
+
+/**
+ * Probe every known marker shape against a detached session.
+ * @returns the first accepted key set.
+ * @throws when no known shape is accepted.
+ */
+export function detectReplaceKeys() {
+	for (const candidate of CANDIDATES) {
+		if (acceptsReplacement(candidate)) return candidate;
+	}
+	throw new Error(
+		'context-trim: this harness build accepts neither the 0.1.5+ nor the legacy positional replacement marker; ' +
+			'report it with the installed @deepseek-ai/dsh-session version'
+	);
+}
+
+/**
+ * Build the positional replacement marker in the harness's own key spelling.
+ * @param keys - key set returned by {@link replaceKeys}.
+ * @param startSeq - inclusive first shadowed surface seq.
+ * @param endSeq - inclusive last shadowed surface seq.
+ * @returns the marker to pass as `surfaceOp`.
+ */
+export function replacementOp(keys, startSeq, endSeq) {
+	return { op: 'replace', [keys.start]: startSeq, [keys.end]: endSeq };
+}
+
+/** Whether one detached session accepts a replacement written with these keys. */
+function acceptsReplacement(keys) {
+	try {
+		const session = Session.create('context-trim-probe');
+		session.append('user/message', probeMessage('probe first'), { surfaceOp: 'append' });
+		session.append('user/message', probeMessage('probe second'), { surfaceOp: 'append' });
+		session.append('user/message', probeMessage('probe marker'), {
+			surfaceOp: replacementOp(keys, 1, 1),
+			sourceEventSeqs: [1]
+		});
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** One frozen probe message; detached sessions never publish it. */
+function probeMessage(text) {
+	return createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'plugin', plugin: 'context-trim-probe' } });
+}