dsh-command-context-trim 0.1.0 → 0.2.0

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;

package/lib/trim-session.js

@@ -0,0 +1,129 @@
+/**
+ * One trim execution, shared by the `/trim` command and the automatic
+ * context-overflow path.
+ *
+ * Everything session-visible happens here: measure the current request under the
+ * target route, plan the oldest balanced span, and apply it as two synchronous
+ * appends. The caller owns only *when* to invoke it (`/trim` inside an idle-agent
+ * reservation, the automatic path inside a failing step) and how to render the
+ * outcome.
+ *
+ * @module dsh-command-context-trim/trim-session
+ */
+import { toolPairingBalancedAfter, toolPairingBalancedBefore } from '@deepseek-ai/dsh-compaction';
+import { applyTrim, createMarkerMessage, provisionalMarker } from './apply.js';
+import { budgetFor, retentionFor } from './config.js';
+import { planTrim } from './plan.js';
+import { describeNonSpan, preview, report } from './render.js';
+import { replaceKeys } from './session-compat.js';
+import { resolveTarget, targetHeader } from './target.js';
+
+/**
+ * @typedef {object} TrimRequest
+ * @property {object} agent - agent owning the session to trim.
+ * @property {AbortSignal} [signal] - cancellation for the whole execution.
+ * @property {{ provider: string, model: string }} [requestedRoute] - explicit target route.
+ * @property {number} [explicitBudget] - explicit token budget instead of a resolved window.
+ * @property {boolean} [check] - plan only, mutate nothing.
+ * @property {boolean} [routedOnly] - target the route the last durable request used.
+ */
+
+/**
+ * Execute one trim.
+ * @param ctx - plugin context (token meter, LLM service).
+ * @param config - resolved configuration.
+ * @param request - what to trim and how far.
+ * @returns `{ result, plan?, label?, before?, after?, replacement?, markerTokens? }`;
+ *   `result` is a command result, and `replacement` is present only when the
+ *   surface was actually rewritten.
+ */
+export async function executeTrim(ctx, config, request) {
+	const { agent, signal, requestedRoute, explicitBudget, check = false, routedOnly = false } = request;
+	signal?.throwIfAborted?.();
+	const session = agent.session;
+	assertNoOpenCompaction(session);
+	const target =
+		explicitBudget === undefined ? await resolveTarget(ctx, agent, requestedRoute, signal, { routedOnly }) : undefined;
+	const budget = explicitBudget ?? 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) => {
+		const type = session.eventAt(node.seq)?.type;
+		return {
+			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.
+			...(type === 'system/message' ? { barrier: true } : {}),
+			// The newest human prompt is the anchor the planner must never elide.
+			...(type === 'user/message' ? { userMessage: true } : {})
+		};
+	});
+	if (nodes.length === 0) {
+		return { result: { 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 { result: describeNonSpan(plan, label), plan, label, before: measurement };
+	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 { result: describeNonSpan(plan, label), plan, label, before: measurement };
+		marker = createMarkerMessage(plan, target?.label ?? `budget ${budget}`, budget);
+		markerTokens = finalMarkerTokens;
+	}
+	if (check) {
+		return { result: { kind: 'success', text: preview(plan, label, markerTokens) }, plan, label, before: measurement };
+	}
+	const replacement = applyTrim(session, plan, marker, replaceKeys());
+	const after = ctx.tokenMeter.measure(session, header);
+	return {
+		result: { kind: 'success', text: report(plan, after, label, markerTokens), sourceEventSeq: replacement.seq },
+		plan,
+		label,
+		before: measurement,
+		after,
+		markerTokens,
+		replacement
+	};
+}
+
+/**
+ * Refuse to rewrite a surface while a compaction bracket is open.
+ * @param session - session whose log is inspected.
+ * @throws when an unmatched `compaction/start` is open in the current lifecycle.
+ */
+export 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');
+		}
+	}
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-command-context-trim",
-  "version": "0.1.0",
-  "description": "Model-free /trim command for DeepSeek Harness — drop the oldest, least valuable span of conversation context so a session can continue on a smaller-window model, without any model call.",
+  "version": "0.2.0",
+  "description": "Model-free /trim for DeepSeek Harness — drop the oldest, least valuable span of context on demand (the `/trim` command) or automatically when a request hits the model's context wall, without any model call.",
   "license": "MIT",
   "author": "snailium",
   "type": "module",
@@ -27,7 +27,8 @@
   "scripts": {
     "test": "node --test",
     "link:harness": "bash scripts/dev-link-harness.sh",
-    "prepublishOnly": "npm test"
+    "prepublishOnly": "npm test",
+    "e2e:mock": "node scripts/mock-overflow-server.mjs"
   },
   "dsh": {
     "bundle": {
@@ -35,14 +36,14 @@
     }
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-commands": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-compaction": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-invariants": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-session": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-token-meter": "^0.1.2-rc.1",
-    "@deepseek-ai/schemastery": "^3.18.1"
+    "@deepseek-ai/cordis": ">=4.0.2",
+    "@deepseek-ai/dsh-commands": ">=0.1.2-rc.1",
+    "@deepseek-ai/dsh-compaction": ">=0.1.2-rc.1",
+    "@deepseek-ai/dsh-invariants": ">=0.1.2-rc.1",
+    "@deepseek-ai/dsh-llm": ">=0.1.2-rc.1",
+    "@deepseek-ai/dsh-session": ">=0.1.2-rc.1",
+    "@deepseek-ai/dsh-token-meter": ">=0.1.2-rc.1",
+    "@deepseek-ai/schemastery": ">=3.18.1"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/cordis": {
@@ -71,9 +72,11 @@
     }
   },
   "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
     "@deepseek-ai/dsh-compaction": "0.1.2-rc.1",
     "@deepseek-ai/dsh-llm": "0.1.2-rc.1",
     "@deepseek-ai/dsh-session": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-token-meter": "^0.1.2-rc.1",
     "@deepseek-ai/schemastery": "3.18.2"
   },
   "keywords": [