dsh-context-pruner 0.0.0-stage → 0.1.1

package/lib/inspect.js

@@ -0,0 +1,390 @@
+/**
+ * Surface inspection for dsh-context-pruner.
+ *
+ * Turns the raw token-meter node list into something a human can actually use:
+ * readable conversation rounds with content previews, instead of bare seq and
+ * token numbers.
+ *
+ * The motivating failure: a first version printed 466 nodes of `seq / tokens /
+ * share`, where every share rounded to 0% and no line said what the node
+ * contained. The numbers were correct and useless.
+ *
+ * @module dsh-context-pruner/inspect
+ */
+
+import { isHumanTurn } from "./rounds.js";
+
+/** How much message text to show per round line. */
+const PREVIEW_CHARS = 96;
+
+/** Roles that can open a new conversation round. */
+const ROUND_OPENER_ROLES = new Set(["user"]);
+
+/** Opening tag of a framed compaction checkpoint body. */
+const SUMMARY_OPEN_TAG = "<compacted-summary>";
+
+/** Closing tag of a framed compaction checkpoint body. */
+const SUMMARY_CLOSE_TAG = "</compacted-summary>";
+
+/**
+ * Opening sentences of the fixed checkpoint boilerplate.
+ *
+ * Both framings ship: "This is an automatically generated checkpoint…" from the
+ * stock backend and "This is a correction checkpoint…" from this plugin's. The
+ * two real openings are named rather than matching a bare "This is ", which
+ * would strip ordinary prose that happens to begin that way.
+ */
+const CHECKPOINT_OPENINGS = [
+	"This is an automatically generated checkpoint",
+	"This is a correction checkpoint"
+];
+
+/**
+ * Remove checkpoint boilerplate from the head of a block.
+ *
+ * The boilerplate is fixed English text. It is usually its own block, but a
+ * producer may emit it in the SAME block as the framed body. Dropping the whole
+ * block on a prefix match would then discard the summary along with it, so only
+ * the boilerplate's own span is removed and whatever follows is kept.
+ *
+ * @param text - full text of one content block.
+ * @returns the text after the boilerplate, or `text` when there is none.
+ */
+function stripCheckpointPreamble(text) {
+	for (const opening of CHECKPOINT_OPENINGS) {
+		if (!text.startsWith(opening)) continue;
+		const end = text.indexOf("\n\n", opening.length);
+		if (end !== -1) return text.slice(end + 2);
+		// No paragraph break: the whole block is boilerplate UNLESS a framing
+		// tag follows, in which case the tag and whatever it wraps are content.
+		// Returning "" unconditionally here would discard the summary whenever a
+		// producer emitted the preamble and the body in a single block.
+		const tag = text.indexOf(SUMMARY_OPEN_TAG, opening.length);
+		return tag === -1 ? "" : text.slice(tag);
+	}
+	return text;
+}
+
+/**
+ * Whether a block is nothing but checkpoint boilerplate.
+ *
+ * @param text - full text of one content block.
+ * @returns true when the block carries no content beyond the preamble.
+ */
+function isCheckpointPreamble(text) {
+	return stripCheckpointPreamble(text).trim().length === 0 && text.trim().length > 0;
+}
+
+/**
+ * Extract the meaningful body of a compaction checkpoint block.
+ *
+ * A checkpoint message is framed across several content blocks:
+ *
+ *   block 0: "<boilerplate preamble>"
+ *   block 1: "<compacted-summary>\n\n<the actual summary>"
+ *   block 2: "</compacted-summary>"
+ *
+ * The boilerplate is ~285 characters of fixed English text that every
+ * checkpoint repeats. Showing it in a listing is actively harmful: the reader
+ * sees the same sentence on every checkpoint node and never learns what the
+ * summary actually says.
+ *
+ * Two things make this exact, and both are pinned by `test/rounds.mjs` so the
+ * browser panel cannot drift away from it again:
+ *
+ *   - The PREAMBLE is removed by its own opening words. Removing the whole
+ *     block on a prefix match would discard the body when a producer emits both
+ *     in one block.
+ *   - The opening tag leads a LATER block, not the tail of block 0, so the tag
+ *     is searched for anywhere in the block rather than assumed at its end.
+ *
+ * @param text - full text of one content block.
+ * @returns the body after the opening tag, or `text` when there is none.
+ */
+function stripCheckpointOpening(text) {
+	const withoutPreamble = stripCheckpointPreamble(text);
+	const start = withoutPreamble.indexOf(SUMMARY_OPEN_TAG);
+	if (start === -1) return withoutPreamble;
+	return withoutPreamble.slice(start + SUMMARY_OPEN_TAG.length);
+}
+
+/**
+ * Whether a block is nothing but the closing framing tag.
+ *
+ * @param text - full text of one content block.
+ * @returns true when the block carries only framing.
+ */
+function isClosingTagBlock(text) {
+	return text.trim() === SUMMARY_CLOSE_TAG;
+}
+
+/**
+ * Flatten one message's content into a single preview line.
+ *
+ * Non-text blocks are summarised by kind so a tool call or image is still
+ * visible in the listing rather than silently vanishing. Checkpoint framing is
+ * stripped so a summarized node previews its conclusion.
+ *
+ * This is the union of every framing rule: the preamble is dropped, the opening
+ * tag is honoured wherever it appears, the closing tag is removed inline, and a
+ * block left empty by any of those is discarded rather than contributing a
+ * blank entry. The browser panel's `stripCheckpointFraming` in `lib/client.js`
+ * applies the identical rule, and `test/rounds.mjs` asserts the two agree on a
+ * table of real layouts — the two sides diverging here is what previously made
+ * every checkpoint preview as the same sentence of English boilerplate.
+ *
+ * @param message - derived message for a surface node.
+ * @param max - maximum characters to keep.
+ * @returns a collapsed one-line preview.
+ */
+export function previewMessage(message, max = PREVIEW_CHARS) {
+	if (message === null || message === undefined) return "(no message)";
+
+	const parts = [];
+	for (const block of message.content ?? []) {
+		// A block can be null or carry a non-string `text` (`content: [null]`
+		// round-trips through `deriveEventMessage`, and a partially streamed
+		// block can hold a placeholder). Unguarded, these THREW out of
+		// `describeNodes` and took down the whole `/prune` listing — a
+		// read-only command failing on malformed history.
+		if (block === null || block === undefined || typeof block !== "object") continue;
+
+		if (block.type === "text") {
+			if (typeof block.text !== "string") continue;
+			if (isClosingTagBlock(block.text)) continue;
+			// The closing tag may also sit inline, after the body in the same
+			// block, so it is removed rather than only whole-block-matched.
+			const body = stripCheckpointOpening(block.text).split(SUMMARY_CLOSE_TAG).join("");
+			if (body.trim().length === 0) continue;
+			parts.push(body);
+		} else if (block.type === "tool-call") {
+			parts.push(`[tool:${block.name ?? "?"}]`);
+		} else if (block.type === "image") {
+			parts.push("[image]");
+		} else if (typeof block.type === "string") {
+			parts.push(`[${block.type}]`);
+		}
+	}
+
+	const text = parts.join(" ").replace(/\s+/g, " ").trim();
+	if (text.length === 0) return "(empty)";
+	return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+
+/**
+ * Build a readable node descriptor for every surface position.
+ *
+ * @param session - live session whose surface is inspected.
+ * @param nodes - token-priced nodes from the meter, in surface order.
+ * @returns one descriptor per node, aligned with `nodes`.
+ */
+export function describeNodes(session, nodes) {
+	return nodes.map((node, position) => {
+		const event = session.eventAt(node.seq);
+		const message = session.deriveEventMessage(event);
+		const role = message?.role ?? event?.type ?? "unknown";
+		const preview = previewMessage(message);
+		// The message's own text, untruncated, so classification sees the real
+		// prefix rather than the 96-character preview.
+		const text = messageText(message);
+		return {
+			position,
+			seq: node.seq,
+			tokens: node.tokens,
+			role,
+			preview,
+			// `source` is the harness's own structured marker for an injected
+			// message; `isHumanTurn` prefers it and falls back to text prefixes.
+			source: message?.source,
+			opensRound:
+				ROUND_OPENER_ROLES.has(role) && isHumanTurn(text, message?.source)
+		};
+	});
+}
+
+/**
+ * Flatten a message's text blocks without truncation.
+ *
+ * Used for classification, which must see the whole prefix rather than the
+ * truncated preview. Guards block shape for the same reason `previewMessage`
+ * does: `content: [null]` and non-string `text` both occur in real histories,
+ * and an unguarded read takes down the entire listing.
+ *
+ * @param message - derived message for a surface node.
+ * @returns the concatenated text, or an empty string.
+ */
+function messageText(message) {
+	if (message === null || message === undefined) return "";
+	const parts = [];
+	for (const block of message.content ?? []) {
+		if (block === null || block === undefined || typeof block !== "object") continue;
+		if (block.type === "text" && typeof block.text === "string") parts.push(block.text);
+	}
+	return parts.join(" ").replace(/\s+/g, " ").trim();
+}
+
+/**
+ * Group node descriptors into conversation rounds.
+ *
+ * A round opens at each genuine HUMAN turn and absorbs every following node
+ * until the next one. This is the unit a human reasons about ("that round where
+ * we tried the wrong fix"), and it is what makes a 466-node session legible.
+ *
+ * Machine notices — background-job reports, runtime context, system reminders,
+ * model-change notices, slash-command echoes — are folded into the round they
+ * arrived in rather than opening a round of their own. They share the
+ * `user/message` surface type, so an opener-per-user-message rule counted 31
+ * rounds on a session holding 16 human turns; because the extras sit BETWEEN
+ * the human turns, the resulting indices were not merely offset but
+ * non-uniform, which made `/prune drop <a>-<b>` address the wrong span.
+ *
+ * Nodes BEFORE the first human turn are held and then absorbed into that first
+ * round. This matters on essentially every real session: the shipped
+ * `SystemPromptProjection` commits the rendered system prompt as surface node 0,
+ * and a runtime-context snapshot commonly follows it. Starting a round on those
+ * nodes invents a round whose heading is scaffolding AND splits the span, so the
+ * `lib/client.js` panel — which must produce the same indices — mirrors this
+ * hold-over exactly (pinned by `test/rounds.mjs`).
+ *
+ * `startSeq`/`endSeq` keep their meaning — the first and last surface node
+ * BELONGING to the round — so a notice that arrived before the round's human
+ * message stays inside the span rather than becoming un-addressable. Only
+ * `title`, the node used for display, prefers the human message.
+ *
+ * @param descriptors - descriptors from {@link describeNodes}.
+ * @returns rounds, each with its node range, token total, and previews.
+ */
+export function groupRounds(descriptors) {
+	const rounds = [];
+	let current = null;
+	// Nodes seen before the first human turn. A session commonly opens with a
+	// runtime snapshot, and those nodes must land INSIDE the first round so the
+	// span covering the round is complete and nothing becomes un-droppable.
+	// Starting a round on them instead both invented a round and split the span.
+	let leading = [];
+
+	/**
+	 * Create a round from the given node, or from the held-over leading nodes
+	 * plus it.
+	 *
+	 * @param descriptor - the node opening the round.
+	 * @param held - nodes to prepend, if any.
+	 * @returns the new round.
+	 */
+	const openRound = (descriptor, held) => {
+		const nodes = [...held, descriptor];
+		const round = {
+			index: rounds.length,
+			startPosition: nodes[0].position,
+			endPosition: descriptor.position,
+			startSeq: nodes[0].seq,
+			endSeq: descriptor.seq,
+			tokens: nodes.reduce((sum, node) => sum + node.tokens, 0),
+			nodes,
+			opener: descriptor,
+			// The node shown as this round's heading. A round that opens with
+			// injected context must still be titled by the human message, or the
+			// listing presents scaffolding as "what was said".
+			title: descriptor.opensRound ? descriptor : null,
+			// Machine notices folded in, so the listing can disclose how much of
+			// a span is scaffolding rather than conversation. Only user-role
+			// messages the classifier rejected are notices: a leading
+			// `system/message` is not a harness notice, and counting every held
+			// node reported `(+3 notices)` for a round holding one.
+			injected: [...held, descriptor].filter(
+				(node) => node.role === "user" && !node.opensRound
+			).length
+		};
+		rounds.push(round);
+		return round;
+	};
+
+	for (const descriptor of descriptors) {
+		if (current === null) {
+			if (descriptor.opensRound) {
+				current = openRound(descriptor, leading);
+				leading = [];
+			} else {
+				// Hold it: whether it deserves its own round is not known until a
+				// human turn decides.
+				leading.push(descriptor);
+			}
+			continue;
+		}
+
+		if (descriptor.opensRound) {
+			current = openRound(descriptor, []);
+			continue;
+		}
+
+		current.endPosition = descriptor.position;
+		current.endSeq = descriptor.seq;
+		current.tokens += descriptor.tokens;
+		if (descriptor.role === "user" && !descriptor.opensRound) current.injected += 1;
+		current.nodes.push(descriptor);
+	}
+
+	// A session with no human turn at all (a bare system prompt, or scaffolding
+	// only) still has to render: emit every held node as one round. The nodes
+	// are passed as `held` with no opener, so their surface order is preserved —
+	// calling `openRound(leading[0], leading.slice(1))` instead put the tail
+	// BEFORE the head and reversed the round.
+	if (current === null && leading.length > 0) openRound(leading[leading.length - 1], leading.slice(0, -1));
+
+	return rounds;
+}
+
+/**
+ * Render a compact token count, e.g. `12.3k`.
+ *
+ * @param tokens - raw token count.
+ * @returns a short human-readable string.
+ */
+export function formatTokens(tokens) {
+	if (tokens >= 1000) {
+		const thousands = tokens / 1000;
+		return `${thousands >= 10 ? Math.round(thousands) : thousands.toFixed(1)}k`;
+	}
+	return String(tokens);
+}
+
+/**
+ * Render a list of rounds as an aligned table.
+ *
+ * @param rounds - rounds from {@link groupRounds}.
+ * @param selected - optional predicate choosing which rounds to render.
+ * @returns the rendered lines.
+ */
+export function renderRounds(rounds, selected = () => true) {
+	const chosen = rounds.filter(selected);
+	if (chosen.length === 0) return ["  (no rounds to show)"];
+
+	const widest = Math.max(...chosen.map((round) => formatTokens(round.tokens).length));
+	const lines = [];
+
+	for (const round of chosen) {
+		const size = formatTokens(round.tokens).padStart(widest);
+		const span =
+			round.startPosition === round.endPosition
+				? `#${round.startPosition}`
+				: `#${round.startPosition}-${round.endPosition}`;
+		// The heading is the round's HUMAN message, not its first node. A round
+		// can open with injected context, and titling it with that notice is what
+		// produced rows reading `background job pwsh-20 (...)`.
+		const heading = round.title ?? round.opener;
+		const notices =
+			round.injected > 0 ? `  (+${round.injected} notice${round.injected === 1 ? "" : "s"})` : "";
+		lines.push(
+			`  ${String(round.index).padStart(3)}  ${size} tok  ${span.padEnd(12)} ${heading.preview}${notices}`
+		);
+
+		// Show a short reaction line for substantial rounds so the listing
+		// conveys the actual exchange, not just the opening question.
+		const reply = round.nodes.find((node) => node.role === "assistant");
+		if (reply !== undefined && round.nodes.length > 1) {
+			lines.push(`                              └ ${reply.preview}`);
+		}
+	}
+
+	return lines;
+}

package/lib/rounds.js

@@ -0,0 +1,160 @@
+/**
+ * Round classification for dsh-context-pruner — the single source of truth.
+ *
+ * ## Why this module exists
+ *
+ * The harness delivers machine notices through the SAME `user/message` surface
+ * type as real conversation. Verified in the DSH checkout, every one of these
+ * is built with `createUserMessage({ ..., source: { kind, form } })`:
+ *
+ *   | source.kind          | form           | what it is                        |
+ *   |----------------------|----------------|-----------------------------------|
+ *   | `tool-jobs`          | `notice`       | "background job ... completed"    |
+ *   | `runtime-context`    | `snapshot`     | cwd / time / tmux snapshot        |
+ *   | `agent-instructions` | `instructions` | `<system-reminder>` and skill body|
+ *   | `agent-message`      | —              | teammate message delivery         |
+ *   | `session-reference`  | —              | `@file` reference expansion       |
+ *   | `skill-invocation`   | —              | slash-skill body                  |
+ *   | `model-selection`    | —              | "[model changed: ...]"            |
+ *
+ * Treating those as conversation openers is not cosmetic. On the session the
+ * README measured (31 `user/message`, of which 16 were human), an opener-per-
+ * user-message rule reports **31 rounds where the truth is 16** — and because
+ * the extra openers are sprinkled BETWEEN the human turns, the mapping is not a
+ * constant offset: host round 9 is a different round from reality's round 9.
+ *
+ * That matters most for `/prune drop <a>-<b>`, which resolves a round range
+ * through this same numbering: a hand-typed range lands on the wrong span, and
+ * the preview echoes the same wrong numbering, so nothing reveals the mistake.
+ *
+ * ## Why the classifier is shared rather than duplicated
+ *
+ * The browser panel has no access to the host's module graph, so it carries its
+ * own copy of this logic inside the bundle. Duplicating the rule is what let
+ * the two sides drift apart in the first place (the panel counted human turns
+ * while the host counted every user message). `test/rounds.mjs` pins the two
+ * copies together by extracting the shipped classifier from `lib/client.js` and
+ * running it against the same table this module is tested with, so a change to
+ * one side that is not mirrored fails the suite.
+ *
+ * ## Why `source` is preferred over text matching
+ *
+ * The structured marker survives copy changes; a text prefix does not. The five
+ * prefixes below are heuristics kept only as a fallback for messages whose
+ * `source` is absent — notably the browser panel, whose event window may not
+ * carry `source` on every entry. `/^Current runtime context\./` in particular
+ * would silently stop matching if the system-prompt plugin reworded its header.
+ *
+ * @module dsh-context-pruner/rounds
+ */
+
+/**
+ * `source.kind` values that never represent a human turn.
+ *
+ * Every one is a harness-injected message delivered through `user/message`.
+ * `model-selection` is the "[model changed: ...]" notice.
+ */
+const MACHINE_SOURCE_KINDS = new Set([
+	"tool-jobs",
+	"runtime-context",
+	"agent-instructions",
+	"agent-message",
+	"session-reference",
+	"skill-invocation",
+	"model-selection"
+]);
+
+/**
+ * `source.form` values that mark a message as injected rather than typed.
+ *
+ * `form` is the more precise signal where it is present: it distinguishes a
+ * `notice`/`snapshot`/`instructions` injection from a user-authored message
+ * that happens to share a `kind`.
+ */
+const MACHINE_SOURCE_FORMS = new Set(["notice", "snapshot", "instructions"]);
+
+/**
+ * Command names that are known to be dispatched as commands rather than chat.
+ *
+ * Only used to disambiguate a slash-leading line when no `source` marker is
+ * available. A name here means "this is an echo, not a prompt"; anything else
+ * that merely starts with a slash is treated as human, so a pasted absolute
+ * path is never silently folded into the previous round.
+ */
+const KNOWN_COMMANDS = new Set([
+	"prune",
+	"compact",
+	"clear",
+	"help",
+	"init",
+	"model",
+	"new",
+	"resume",
+	"review",
+	"status",
+	"quit",
+	"exit"
+]);
+
+/**
+ * Decide whether a message is a genuine human turn.
+ *
+ * @param text - the message's own text, flattened. Only the head is inspected.
+ * @param source - the optional structured `source` marker from the message.
+ * @returns true when this message should open a conversation round.
+ */
+export function isHumanTurn(text, source) {
+	if (isMachineSource(source)) return false;
+
+	const head = String(text ?? "").trimStart().slice(0, 120);
+
+	// An empty message is not a turn. Falling through to `true` let a
+	// contentless `user/message` open a round.
+	if (head.length === 0) return false;
+
+	// Slash-command echoes are an action, not a turn.
+	//
+	// Verified in the DSH checkout, a submitted `/line` does NOT become a chat
+	// message: the composer routes it to `adjudicate` and the command domain
+	// records a `command/run` LIFECYCLE event, not a `user/message`. So this
+	// branch is defence-in-depth for a composition that echoes the line, and it
+	// is deliberately NARROW because a bare leading slash would swallow real
+	// prompts that begin with a path ("/tmp cleanup needed", "/home/u/x") and
+	// silently fold them into the previous round — the wrong-span failure this
+	// classifier exists to prevent.
+	//
+	// A registered command name is a single token that either ends the line or
+	// is followed by an argument. Requiring the argument form to look like
+	// flags/known-command arguments keeps prose starting with a path as human.
+	const commandish = /^\/([a-z][\w-]*)(?::([\w-]+))?(\s|$)/i.exec(head);
+	if (commandish !== null) {
+		const rest = head.slice(commandish[0].length).trim();
+		// `/name` alone, or `/name <args>` where the name is a known plugin
+		// command, is an echo. A path-like first word followed by prose is not.
+		if (rest.length === 0) return false;
+		if (KNOWN_COMMANDS.has(commandish[1].toLowerCase())) return false;
+	}
+
+	// Text fallbacks, for messages carrying no `source`.
+	if (/^background job /i.test(head)) return false;
+	if (/^<system-reminder>/.test(head)) return false;
+	if (/^\[model changed:/.test(head)) return false;
+	if (/^Current runtime context\./.test(head)) return false;
+	if (/^This session is being continued from/.test(head)) return false;
+	return true;
+}
+
+/**
+ * Whether a `source` marker identifies a harness injection.
+ *
+ * @param source - a message's `source` field, when present.
+ * @returns true when the marker names a machine delivery.
+ */
+export function isMachineSource(source) {
+	if (source === null || source === undefined || typeof source !== "object") return false;
+	if (typeof source.kind === "string" && MACHINE_SOURCE_KINDS.has(source.kind)) return true;
+	if (typeof source.form === "string" && MACHINE_SOURCE_FORMS.has(source.form)) return true;
+	return false;
+}
+
+export { MACHINE_SOURCE_KINDS, MACHINE_SOURCE_FORMS };

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "dsh-context-pruner",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "DSH 插件：纠错式上下文裁剪。用 /prune 把已经走错方向的旧对话压成一条「结论修正」摘要，让模型忘掉错误答案 X、只记住正确结论 Y，而不是把 10 轮试错原样留在上下文里继续误导。",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./backend": "./lib/backend.js",
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-ui-sidebar-right",
+        "@deepseek-ai/dsh-client-ui-primitives",
+        "@deepseek-ai/dsh-client-ui-session"
+      ],
+      "platform": "web"
+    }
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node test/run.mjs"
+  },
+  "keywords": [
+    "deepseek",
+    "harness",
+    "dsh",
+    "dsh-plugin",
+    "compaction",
+    "context",
+    "prune"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@deepseek-ai/schemastery": "~3.18.4"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.5",
+    "@deepseek-ai/dsh-commands": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-compaction": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-compaction-basic": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-llm": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-util-values": "0.2.1-rc.2"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}