dsh-command-context-trim 0.1.1 → 0.2.2

package/lib/index.js

@@ -13,16 +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 { replaceKeys } from './session-compat.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';
@@ -30,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(),
@@ -39,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.
  */
@@ -70,6 +76,7 @@ export function apply(ctx, config) {
 			handler
 		});
 	}, 'context-trim lifecycle');
+	registerAutoTrim(ctx, resolved);
 }
 
 /**
@@ -84,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)}` };
 	}
@@ -95,147 +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,
-		// Harness 0.1.5+ carries the system prompt as surface node 0. It is never
-		// elidable, and no elided span may cross it: dropping it would strip the
-		// model's instructions, and letting it consume head protection would expose
-		// the user's original request instead.
-		...(session.eventAt(node.seq)?.type === 'system/message' ? { barrier: true } : {})
-	}));
-	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, replaceKeys());
-	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 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.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. */
-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

@@ -17,7 +17,11 @@
  *   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 final node**, and the retained tail.
+ * - **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.
@@ -31,6 +35,8 @@
  * @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.
  */
 
 /**
@@ -69,20 +75,21 @@ 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',
@@ -91,10 +98,44 @@ export function planTrim(input) {
 		maxFreeable: weakest?.maxFreeable ?? 0,
 		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.
@@ -104,17 +145,25 @@ 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: protectedHeadTokens(nodes, input.protectHeadNodes)
+		protectedHeadTokens: protectedHeadTokens(nodes, input.protectHeadNodes),
+		protectedUserTokens: newestUserIndex === -1 ? 0 : nodes[newestUserIndex].heuristicTokens
 	});
 	const headEnd = protectedHeadEnd(nodes, input.protectHeadNodes);
 	if (lastElidable < headEnd) return shortfall(0);
 	let weakest = null;
-	for (const region of elidableRegions(nodes, headEnd, lastElidable)) {
+	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;
@@ -172,12 +221,26 @@ function protectedHeadEnd(nodes, protectHeadNodes) {
 	return nodes.length;
 }
 
-/** Maximal runs of elidable indices inside `[from, to]`. */
-function elidableRegions(nodes, from, to) {
+/** 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) {
+		if (nodes[index].barrier === true || index === extraBarrier) {
 			if (start !== null) regions.push({ start, end: index - 1 });
 			start = null;
 			continue;

package/lib/prune-first.js

@@ -0,0 +1,131 @@
+/**
+ * In-place tool-result slimming, run **before** any span elision.
+ *
+ * DSH already owns this idea (`@deepseek-ai/dsh-compaction-tool-result-pruner`),
+ * but a host-plane plugin can only reach that service where compaction itself is
+ * mounted on the host plane. In a 0.1.5 web profile the host row is disabled and
+ * the pruner is re-mounted inside an agent-preset isolate realm, where
+ * `ctx.get('toolResultPruner')` resolves nothing. So this module prefers the
+ * official service when it is visible and otherwise performs the same transform
+ * itself, which keeps the cheap reduction ahead of the expensive one:
+ *
+ *   slim oversized tool results in place  →  elide a whole span  →  compaction
+ *
+ * The transform mirrors the official one: text is measured and sliced in Unicode
+ * code points (never splitting a surrogate pair), the head and tail are kept, one
+ * marker replaces the removed middle, non-text blocks keep their order, and the
+ * replacement carries the complete original event data except `content` — so the
+ * tool call keeps its result and the step stays intact.
+ *
+ * A `tool/result` replacement is only legal inside an open turn, which is exactly
+ * the state the automatic overflow path runs in; the idle `/trim` command never
+ * uses this module.
+ *
+ * @module dsh-command-context-trim/prune-first
+ */
+import { freezeMessage } from '@deepseek-ai/dsh-llm';
+import { replaceKeys, replacementOp } from './session-compat.js';
+
+/**
+ * Marker replacing the removed middle. Deliberately worded for the model and
+ * distinct from DSH's own `[... tool result middle pruned ...]`, so a session log
+ * shows which producer slimmed a node.
+ */
+export const TRIM_MARKER = '\n\n[... tool result middle trimmed to fit the context window ...]\n\n';
+
+/**
+ * Slim every over-budget tool result on the current surface.
+ * @param ctx - plugin context; `ctx.get('toolResultPruner')` is used when present.
+ * @param session - session whose surface is rewritten.
+ * @param config - resolved configuration.
+ * @returns `{ pruned, via, replacementSeq }`; `pruned` is the number of nodes rewritten.
+ */
+export function shrinkOversizedToolResults(ctx, session, config) {
+	if (config.preferInPlacePrune !== true) return { pruned: 0, via: 'disabled' };
+	const official = ctx.get?.('toolResultPruner');
+	if (official !== undefined && typeof official.pruneSession === 'function') {
+		const outcome = official.pruneSession(session);
+		const pruned = Array.isArray(outcome?.pruned) ? outcome.pruned.length : 0;
+		return { pruned, via: 'service', replacementSeq: outcome?.pruned?.at(-1)?.replacementSeq };
+	}
+	const keys = replaceKeys();
+	let pruned = 0;
+	let replacementSeq;
+	// Snapshot first: replacements are appended while iterating.
+	for (const seq of [...session.surface.nodes]) {
+		const event = session.eventAt(seq);
+		if (event?.type !== 'tool/result') continue;
+		const result = event.data.message.content[0];
+		const content = pruneContent(result.content, config);
+		if (content === null) continue;
+		const message = freezeMessage({
+			...event.data.message,
+			content: [{ ...result, content }]
+		});
+		session.append('compaction/prune', {
+			shadowedRange: { start: seq, end: seq },
+			shadowedSeqs: [seq],
+			shadowedTokenCount: ctx.tokenMeter.estimateMessage(event.data.message)
+		});
+		const replacement = session.append('tool/result', { ...event.data, message }, {
+			surfaceOp: replacementOp(keys, seq, seq),
+			sourceEventSeqs: [seq]
+		});
+		pruned += 1;
+		replacementSeq = replacement.seq;
+	}
+	return { pruned, via: 'inline', ...(replacementSeq === undefined ? {} : { replacementSeq }) };
+}
+
+/**
+ * Measure tool-result text in Unicode code points; non-text blocks cost zero.
+ * @param blocks - tool-result content blocks.
+ * @returns total code points across text blocks.
+ */
+export function measureContent(blocks) {
+	let chars = 0;
+	for (const block of blocks) if (block.type === 'text') chars += codePointLength(block.text);
+	return chars;
+}
+
+/**
+ * Replace an over-budget text middle while retaining rich-block order.
+ * @param blocks - original tool-result content.
+ * @param config - resolved configuration with the character budgets.
+ * @returns rewritten content, or `null` when the text is already within budget.
+ */
+export function pruneContent(blocks, config) {
+	const totalChars = measureContent(blocks);
+	if (totalChars <= config.pruneThresholdChars) return null;
+	const removedStart = config.pruneHeadChars;
+	const removedEnd = totalChars - config.pruneTailChars;
+	const pruned = [];
+	let consumed = 0;
+	let markerInserted = false;
+	for (const block of blocks) {
+		if (block.type !== 'text') {
+			pruned.push(block);
+			continue;
+		}
+		const points = Array.from(block.text);
+		const blockStart = consumed;
+		const blockEnd = blockStart + points.length;
+		const headEnd = Math.min(points.length, Math.max(0, removedStart - blockStart));
+		const tailStart = Math.min(points.length, Math.max(0, removedEnd - blockStart));
+		const marker = blockStart < removedEnd && blockEnd > removedStart && !markerInserted ? TRIM_MARKER : '';
+		if (marker.length > 0) markerInserted = true;
+		const text = points.slice(0, headEnd).join('') + marker + points.slice(tailStart).join('');
+		if (text.length > 0) pruned.push({ ...block, text });
+		consumed = blockEnd;
+	}
+	if (!markerInserted) return null;
+	const charsAfter = measureContent(pruned);
+	// Refuse a rewrite that would not actually be smaller and within budget.
+	if (charsAfter > config.pruneThresholdChars || charsAfter >= totalChars) return null;
+	return pruned;
+}
+
+/** Count Unicode code points without splitting surrogate pairs. */
+function codePointLength(text) {
+	return Array.from(text).length;
+}

package/lib/render.js

@@ -0,0 +1,133 @@
+/**
+ * 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>';
+	}
+}
+
+/**
+ * Render one automatic-path outcome, which may be an in-place slim with no span
+ * elision, a span elision, or a slim followed by a span elision.
+ * @param outcome - the object returned by `executeTrim`.
+ * @returns a single-line account.
+ */
+export function logLineFor(outcome) {
+	if (outcome.plan === undefined) {
+		return (
+			`slimmed ${outcome.pruned.pruned} oversized tool result(s) in place for ${outcome.label}; ` +
+			`request ~${outcome.before.totalTokens} → ~${outcome.after.totalTokens} tokens`
+		);
+	}
+	const base = logLine(outcome.plan, outcome.after, outcome.label);
+	if (outcome.pruned === undefined || outcome.pruned.pruned === 0) return base;
+	return `${outcome.pruned.pruned} tool result(s) slimmed in place, then ${base}`;
+}

package/lib/target.js

@@ -40,8 +40,10 @@ export function latestRoute(session) {
  * @returns `{ provider, model, contextWindow, label }`.
  * @throws when no route can be determined, the route is unknown, or its adapter declares no window.
  */
-export async function resolveTarget(ctx, agent, requested, signal) {
-	const route = requested ?? latestRoute(agent.session) ?? agentRoute(agent);
+export async function resolveTarget(ctx, agent, requested, signal, options = {}) {
+	const primary =
+		options.routedOnly === true ? routedTarget(agent.session) ?? latestRoute(agent.session) : latestRoute(agent.session);
+	const route = requested ?? primary ?? agentRoute(agent);
 	if (route === undefined) {
 		throw new Error('cannot determine the target model: select a model in this session first, or pass an explicit budget (e.g. /trim 32k)');
 	}
@@ -82,6 +84,20 @@ export function targetHeader(session, target) {
 	});
 }
 
+/**
+ * The route the last durable request was actually built for: the one that just
+ * overflowed during automatic recovery.
+ * @param session - session whose log is read.
+ * @returns `{ provider, model, source }`, or undefined when nothing was routed yet.
+ */
+export function routedTarget(session) {
+	const config = session.requestHeader()?.config;
+	if (config === undefined) return undefined;
+	if (typeof config.provider !== 'string' || config.provider.length === 0) return undefined;
+	if (typeof config.model !== 'string' || config.model.length === 0) return undefined;
+	return { provider: config.provider, model: config.model, source: 'request' };
+}
+
 /** Per-agent configured route, used only before any request was routed. */
 function agentRoute(agent) {
 	const provider = agent.options?.provider;