@logictan/dsh-verbatim-compaction 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Logic Tan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+# @logictan/dsh-verbatim-compaction
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+把上下文压缩的**摘要**从「让模型重写一遍」换成「确定性地把正文抄进 checkpoint」：用户与助手的正文逐字保留，工具结果压成一行指针，推理块从不读取，全程零模型调用。
+
+## 它解决什么
+
+`@deepseek-ai/dsh-compaction-basic` 每次压缩都发起一次 `ctx.llm.stream()`，要求模型按九节模板（Primary Request / Key Technical Concepts / Errors and Fixes …）重写被阴影的区间。在 8 个真实会话上实测（403 MiB、145 次压缩、24.5M 被丢弃 token）：
+
+- 模板只保住被丢弃内容的 **2.38%**；
+- 被丢弃内容里真正的「人写的正文」只占 **0.67%** —— 其余是推理 63.8%、工具结果 25.2%、工具调用参数 10.4%；
+- 侥幸保住的正文，下一次压缩会被**再摘要一遍**：`selectCompactableRange` 总是从 `surfaceNodes[firstIdx]` 开始，而上一份 checkpoint 正好坐在 index 1。
+
+本插件只覆盖基类的 `summarize()`（基类文档里点名的唯一子类钩子），重放、区间选择、durable 事务与 shrink 守卫全部沿用基类，因此不可能与宿主的事务语义分叉。
+
+## 摘要长什么样
+
+```
+## user (turn 37)
+（用户原话，逐字）
+
+### assistant (turn 37)
+（助手正文，逐字）
+  tools: bash×280 ssh_exec×44 web_search×6 (408830 bytes)
+  errors: 1: Error: 命令超过 600 秒未结束，已断开连接
+  wrote: /Volumes/LogicExt/Git/BookReader/src/video.js
+```
+
+- 正文逐字，不重写、不改写。
+- 工具结果只留「工具名 × 次数 + 字节数」，内容丢弃。
+- 错误只留首行（100 字符），足以知道「这里失败过、失败原因是什么」。
+- `wrote` 记录本轮写过的路径，重建「改了哪些文件」。
+- 推理块从不进入摘要，也不读取。
+
+## 摘要源是日志，不是被阴影的区间
+
+上一份 checkpoint 每次都被一起阴影掉，所以「只摘要被阴影区间」会把上一份摘要承载的全部历史再丢一次。本插件扫描会话日志里 `surfaceOp === 'append'` 的事件，减去本次压缩后仍留在 surface 上的尾部，重建整段历史——不需要任何累积状态，摘要源集合逐次单调增长（122 次压缩实测 0 次非单调）。
+
+`turn/start` 不在 surface 上，但它是「这条 user 消息属于第几轮」的唯一记录（user 消息自身不带 turn），所以一并保留。
+
+## 为什么不会触发 shrink 守卫
+
+基类的守卫比较「framed 摘要」与「被替换内容的 route 价」，摘要不小于原内容就整次压缩失败。本插件把预算直接算成 `min(196752, shadowedPrice − 86 − 512)`：上界取守卫自己的那个数，因此这条失败路径按构造不可能发生，而不是靠实测侥幸。实测 8 个会话 0 次触发，最小余量 174387。
+
+## 安装
+
+```bash
+pnpm add @logictan/dsh-verbatim-compaction
+```
+
+## 激活：必须改 profile patch，本包的行不生效
+
+**这是本插件唯一不直观的地方。** 真正在用的 `compaction` 组嵌在 4 个 agent preset（`preset-standard` / `preset-ptc` / `preset-minimal` / `preset-cordis`）的 `config.plugins` 里，带 `isolate: {compaction: true}`，每个 preset 各持一个 `compaction` 服务实例，根上下文看不到它们。因此：
+
+- 顶层新增一行 `compaction` 服务**不会被任何 agent 用到**；
+- 往 preset 的 `config.plugins` 里 `insert` 会报 `patch insert: entry "compaction" not found`（`applyEntryPatches` 的 `entryMap` 只收录顶层条目与 `group: true` 条目）；
+- 新行也不能与 `compaction-basic` 并存在同一组：`provide('compaction')` 重复注册会抛 `service "compaction" has been registered at <...>`。
+
+本包自带的 `cordis.patch.yml` 因此只插入一行 `disabled: true` 的占位（让聚合包能带上它），真正激活靠**按 Loader row id override 整份 preset `config`**——宿主指南 `dsh-agent-preset/skills/editing-cordis-compositions/SKILL.md`「Change a shipped preset」的官方路径。在 `~/.dsh/cordis.patch.yml` 里给每个要改的 preset 写一份完整 config，只把 `compaction` 组里的 `compaction-basic` 换成 `verbatim-compaction`：
+
+```yaml
+- id: preset-standard
+  name: '@deepseek-ai/dsh-agent-preset'
+  config:
+    id: standard
+    order: 1
+    plugins:
+      # 其余插件原样重述，只改 compaction 组
+      - id: compaction
+        name: cordis:group
+        group: true
+        isolate:
+          compaction: true
+          toolResultPruner: true
+        config:
+          - id: verbatim-compaction
+            name: '@logictan/dsh-verbatim-compaction'
+          - id: command-compact
+            name: '@deepseek-ai/dsh-command-compact'
+          - id: tool-result-pruner
+            name: '@deepseek-ai/dsh-compaction-tool-result-pruner'
+            config: { … }
+```
+
+代价是每个要改的 preset 都要重述一遍 `plugins`；换来的是确定性——不依赖任何监听器顺序。
+
+`cordis.patch.yml` 里那行占位必须保留，且 `id` 与本包宿主半边的 `export const name`（`verbatim-compaction`）一致，否则 `check:host` 会报 patch 行 id 不一致。
+
+## 配置
+
+无需配置。预算、注入折叠、错误首行长度都是内部常量；唯一的可调项是基类自己的 `thresholdRatio` / `retainRatio`，它们照旧从 `compaction-basic` 的配置读。
+
+## 已知边界
+
+- **正文超预算会被截断。** 预算是硬的，两级依次触发：**先** user 正文超过预算一半时从**最新**往前算、最旧的先丢（用户刚说的话是下一轮唯一依赖的东西，丢它等于丢任务）；**仍不够**才把助手正文按轮均分截断，每轮下限 800 字符。8 个实测会话里两级都没跑过（最大摘要 44542 token，预算 196752），所以这是守卫而不是常态。
+- **`turn/start` 缺失时轮次编号退化为 `turn ?`。** 不会丢正文，只是编号不可读。
+- **注入内容不进摘要。** 判据是 `source.kind !== 'user'`——注入上下文在一个真实会话里占 user 消息字符的 97%，放进摘要会把人的原话淹掉。
+- **不改善首轮之外的工具参数细节。** `bash` 命令本身（占工具参数 84.2%）不保留；需要「当时跑了什么命令」的场景不在本插件的覆盖范围内。
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,13 @@
+# dsh-verbatim-compaction bundle patch layer.
+#
+# This row is NOT inserted into the top-level composition: the compaction
+# backend lives inside each agent preset's `compaction` group, behind
+# `isolate: {compaction: true}`, so a top-level row could not serve it.
+# The profile patch overrides each preset row instead — see the README.
+#
+# The id must stay equal to the host half's `export const name`, because
+# cordis-plugin-loader keys mounted rows by id.
+- insert:
+    - id: verbatim-compaction
+      name: '@logictan/dsh-verbatim-compaction'
+      disabled: true

package/lib/index.js

@@ -0,0 +1,445 @@
+/**
+ * Deterministic, verbatim-history compaction backend.
+ *
+ * `@deepseek-ai/dsh-compaction-basic` condenses a shadowed span through one
+ * `ctx.llm.stream()` call whose instruction asks for a nine-section template
+ * ("Primary Request / Key Technical Concepts / Errors and Fixes ..."). Measured
+ * over eight real sessions (403 MiB, 145 compactions, 24.5M discarded tokens)
+ * that template retains 2.38% of what it discards, and of everything discarded
+ * only 0.67% is prose a human wrote -- the rest is reasoning (63.8%), tool
+ * results (25.2%) and tool-call arguments (10.4%). The prose that does survive
+ * is then summarized again on the next compaction, because
+ * `selectCompactableRange` always starts at `surfaceNodes[firstIdx]` and the
+ * previous checkpoint sits at index 1.
+ *
+ * This backend keeps the base class's replay, range selection, durable
+ * transaction and shrink guard untouched and overrides only `summarize()`, the
+ * one hook the base class documents for exactly this purpose. The replacement
+ * summary is built deterministically, with no model call:
+ *
+ *   - user and assistant prose verbatim, per turn;
+ *   - tool results reduced to one line (tool names, call counts, bytes);
+ *   - reasoning never read;
+ *   - repeated injections recorded once.
+ *
+ * The digest source is the session log, not the shadowed span: the previous
+ * checkpoint is itself shadowed on every compaction, so a span-only digest
+ * would drop everything the previous digest carried. Reading the log's
+ * append-origin surface events minus the retained tail reconstructs the whole
+ * history without any accumulated state.
+ *
+ * @module @logictan/dsh-verbatim-compaction
+ */
+import { BasicCompactionEngine } from '@deepseek-ai/dsh-compaction-basic';
+/** Cordis companion plugin name. Must equal this plugin's `cordis.patch.yml` row id. */
+export const name = 'verbatim-compaction';
+/**
+ * Ceiling for one digest, in the meter's fixed 4-chars-per-token heuristic.
+ *
+ * The base class's own summary budget is `thresholdTokens - retainTokens -
+ * 8192`, which is 196752 for the route this was measured on. The digest is also
+ * bounded by the shrink guard itself, which is tighter in practice; see
+ * `summarize`.
+ */
+const DIGEST_BUDGET_TOKENS = 196752;
+/** Framing overhead `frameSummary` adds: preamble plus both tags, 341 chars = 86 tokens. */
+const FRAME_TOKENS = 86;
+/** Safety margin below the shrink guard, in tokens. */
+const SHRINK_MARGIN_TOKENS = 512;
+/** Per-turn floor when assistant prose has to be truncated, in characters. */
+const MIN_TURN_CHARS = 800;
+/** Share of the budget user prose may occupy before oldest-first truncation. */
+const USER_BUDGET_SHARE = 0.5;
+/** Tool names whose call arguments name a written path. */
+const WRITE_TOOLS = new Set(['write', 'edit', 'multiedit', 'apply_patch']);
+/** The message an event derives to, or null when it derives to none. */
+function messageOf(event) {
+    switch (event.type) {
+        case 'user/message':
+            return event.data;
+        case 'assistant/message':
+        case 'tool/result':
+        case 'system/message':
+        case 'developer/message':
+            return event.data.message ?? null;
+        default:
+            return null;
+    }
+}
+/** Source kind of a user message, or undefined when it carries none. */
+function sourceKind(event) {
+    if (event.type !== 'user/message')
+        return undefined;
+    const source = event.data.source;
+    return source?.kind;
+}
+/**
+ * Whether this user message was injected by the host rather than typed.
+ *
+ * The rule is `kind !== 'user'` rather than a list of known producers: the
+ * source union is merge-extensible, so a new plugin's kind must not silently
+ * become "user prose the human wrote". Measured on one real session, injected
+ * context is 97% of all user-message characters (161993 of 375 for
+ * `agent-instructions` against the human's own 375), so a leaked kind would
+ * swamp the digest.
+ */
+function isInjection(event) {
+    const kind = sourceKind(event);
+    return kind !== undefined && kind !== 'user';
+}
+/** Whether this user message is a compaction checkpoint written by a backend. */
+function isCheckpoint(event) {
+    return sourceKind(event) === 'compact-checkpoint';
+}
+/** The visible text of a message, with reasoning excluded. */
+function textOf(event) {
+    const message = messageOf(event);
+    if (message === null)
+        return '';
+    const parts = [];
+    for (const block of message.content) {
+        if (block.type === 'text')
+            parts.push(block.text);
+    }
+    return parts.join('\n');
+}
+/** Every tool-call block of one message, in order. */
+function toolCallsOf(event) {
+    const message = messageOf(event);
+    if (message === null)
+        return [];
+    const calls = [];
+    for (const block of message.content) {
+        if (block.type === 'tool-call')
+            calls.push({ name: block.name, arguments: block.arguments });
+    }
+    return calls;
+}
+/** The `path` argument of one tool call, when the call carries one. */
+function pathArgumentOf(argumentsJson) {
+    try {
+        const parsed = JSON.parse(argumentsJson);
+        if (typeof parsed !== 'object' || parsed === null)
+            return undefined;
+        const path = parsed.path;
+        return typeof path === 'string' ? path : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The turn number an event belongs to, when the log records one. */
+function turnOf(event) {
+    const turn = event.data.turn;
+    return typeof turn === 'number' && Number.isInteger(turn) ? turn : undefined;
+}
+/** A fresh, empty turn accumulator. */
+function emptyTurn(turn) {
+    return { turn, user: [], assistant: [], tools: new Map(), resultBytes: 0, errors: [], writes: [] };
+}
+/**
+ * Group append-origin surface events into per-turn digest material.
+ *
+ * A section starts at each non-injected user message; assistant-only runs
+ * before the first user message join the first section. Turn numbers come from
+ * the log: `turn/start` carries `{turn}` and `assistant/message` carries
+ * `data.turn`. A user message carries no turn of its own, so it inherits the
+ * last one seen.
+ *
+ * @param events - the digest source in log order.
+ * @returns one section per non-injected user message.
+ */
+export function buildSections(events) {
+    const sections = [];
+    let current;
+    let currentTurn;
+    let lastTurn;
+    const openTurn = (turn) => {
+        if (current === undefined) {
+            current = { turns: [] };
+            sections.push(current);
+        }
+        const next = emptyTurn(turn);
+        current.turns.push(next);
+        if (turn !== undefined)
+            lastTurn = turn;
+        return next;
+    };
+    for (const event of events) {
+        if (event.type === 'turn/start') {
+            const turn = turnOf(event);
+            if (turn !== undefined)
+                lastTurn = turn;
+            continue;
+        }
+        if (event.type === 'tool/result') {
+            if (currentTurn === undefined)
+                continue;
+            const text = textOf(event);
+            currentTurn.resultBytes += text.length;
+            const message = messageOf(event);
+            if (message?.isError === true) {
+                const firstLine = text.split('\n')[0] ?? '';
+                currentTurn.errors.push(firstLine.slice(0, 100));
+            }
+            continue;
+        }
+        if (event.type !== 'user/message' && event.type !== 'assistant/message')
+            continue;
+        if (isInjection(event) || isCheckpoint(event))
+            continue;
+        const eventTurn = turnOf(event) ?? lastTurn;
+        if (event.type === 'user/message') {
+            // A user message opens a new section, not merely a new turn: sections are
+            // what the digest headings delimit, and one section per user request is
+            // what makes the digest readable after a hundred turns.
+            current = { turns: [] };
+            sections.push(current);
+            currentTurn = openTurn(eventTurn);
+            const text = textOf(event);
+            if (text.length > 0)
+                currentTurn.user.push(text);
+            continue;
+        }
+        if (currentTurn === undefined || (eventTurn !== undefined && currentTurn.turn !== eventTurn)) {
+            currentTurn = openTurn(eventTurn);
+        }
+        const text = textOf(event);
+        if (text.length > 0)
+            currentTurn.assistant.push(text);
+        for (const call of toolCallsOf(event)) {
+            currentTurn.tools.set(call.name, (currentTurn.tools.get(call.name) ?? 0) + 1);
+            if (!WRITE_TOOLS.has(call.name))
+                continue;
+            const path = pathArgumentOf(call.arguments);
+            if (path !== undefined && !currentTurn.writes.includes(path))
+                currentTurn.writes.push(path);
+        }
+    }
+    return sections;
+}
+/** Render one section to digest text, truncating assistant prose to `capChars`. */
+function renderSection(section, capChars) {
+    const lines = [];
+    for (const turn of section.turns) {
+        const label = turn.turn === undefined ? '?' : String(turn.turn);
+        if (turn.user.length > 0)
+            lines.push(`\n## user (turn ${label})\n${turn.user.join('\n')}`);
+        let body = turn.assistant.join('\n');
+        if (capChars !== undefined && body.length > capChars) {
+            body = `${body.slice(0, capChars)}\n…(+${body.length - capChars} chars)`;
+        }
+        if (body.length > 0)
+            lines.push(`### assistant (turn ${label})\n${body}`);
+        if (turn.tools.size > 0) {
+            const names = [...turn.tools.entries()]
+                .sort((left, right) => right[1] - left[1])
+                .map(([tool, count]) => `${tool}×${count}`)
+                .join(' ');
+            lines.push(`  tools: ${names} (${turn.resultBytes} bytes)`);
+        }
+        if (turn.errors.length > 0) {
+            lines.push(`  errors: ${turn.errors.length}: ${turn.errors.slice(0, 3).join(' | ')}`);
+        }
+        if (turn.writes.length > 0)
+            lines.push(`  wrote: ${turn.writes.join(', ')}`);
+    }
+    return lines.join('\n');
+}
+/** Total characters of assistant prose across every section. */
+function assistantChars(sections) {
+    let total = 0;
+    for (const section of sections)
+        for (const turn of section.turns)
+            total += turn.assistant.join('\n').length;
+    return total;
+}
+/**
+ * Render the digest under a hard character budget.
+ *
+ * The two truncation tiers are the plan's T1 and T1', in that order:
+ *
+ * - **T1** user prose is verbatim unless it alone exceeds `USER_BUDGET_SHARE` of
+ *   the budget, then the oldest turns are cut first.
+ * - **T1'** assistant prose is verbatim unless the whole digest overflows, then
+ *   it is cut evenly per turn down to `MIN_TURN_CHARS`.
+ *
+ * T1' runs *after* T1 because a user's own words are the least reconstructible
+ * thing in the log: an assistant's reply can be inferred from its tool calls
+ * and the surrounding turns, a user's request cannot. The 800-character floor
+ * exists so a tight budget thins every turn instead of erasing the last few.
+ *
+ * Neither tier runs in practice: over the eight measured sessions the largest
+ * digest was 44542 tokens against a 196752 budget, and user prose totalled 2591
+ * tokens against a 98376 cap. They are a guard against a pasted file, not the
+ * normal path.
+ *
+ * @param events - the digest source in log order.
+ * @param budgetTokens - hard ceiling in the meter's fixed 4-chars-per-token heuristic.
+ * @returns the digest text, never longer than `budgetTokens * 4` characters.
+ */
+export function renderDigest(events, budgetTokens) {
+    const sections = buildSections(events);
+    const budgetChars = Math.max(0, budgetTokens * 4);
+    const render = (capChars, trimmed) => (trimmed ?? sections).map((section) => renderSection(section, capChars)).join('\n');
+    const verbatim = render(undefined);
+    if (verbatim.length <= budgetChars)
+        return verbatim;
+    // T1: user prose over its share, oldest first. Only the user side changes, so
+    // assistant prose stays verbatim for now. The walk is backwards because the
+    // newest request is the one the next turn depends on: cutting forwards would
+    // keep the opening question and drop what the user just asked for.
+    const userCap = Math.floor(budgetChars * USER_BUDGET_SHARE);
+    let seen = 0;
+    const t1 = sections.map((section) => ({ turns: section.turns.map((turn) => ({ ...turn, user: [...turn.user] })) }));
+    for (let section = t1.length - 1; section >= 0; section -= 1) {
+        const turns = t1[section]?.turns ?? [];
+        for (let turn = turns.length - 1; turn >= 0; turn -= 1) {
+            const texts = turns[turn]?.user ?? [];
+            for (let index = texts.length - 1; index >= 0; index -= 1) {
+                const text = texts[index] ?? '';
+                const room = userCap - seen;
+                if (text.length <= room) {
+                    seen += text.length;
+                    continue;
+                }
+                texts[index] = room <= 0
+                    ? `…(+${text.length} chars, older user prose truncated)`
+                    : `${text.slice(0, room)}\n…(+${text.length - room} chars)`;
+                seen = userCap;
+            }
+        }
+    }
+    const afterT1 = render(undefined, t1);
+    if (afterT1.length <= budgetChars)
+        return afterT1;
+    // T1': assistant prose, evenly per turn. Length is monotone non-decreasing in
+    // the cap, so bisection finds the largest cap that fits exactly, in about
+    // eight renders. The floor is honoured only while it fits; below that the cap
+    // follows the budget down and the final slice guarantees the ceiling.
+    let low = 0;
+    let high = assistantChars(t1);
+    while (low < high) {
+        const mid = Math.ceil((low + high) / 2);
+        if (render(mid, t1).length <= budgetChars)
+            low = mid;
+        else
+            high = mid - 1;
+    }
+    const capped = render(low, t1);
+    if (capped.length <= budgetChars)
+        return capped;
+    // Even cap 0 overflows, so the headings and pointers alone exceed the budget.
+    // Drop the oldest sections instead of slicing the head: a truncated tail would
+    // cut the newest turns, which are exactly the ones the next request needs.
+    let first = 0;
+    let dropped = 0;
+    while (first < t1.length - 1) {
+        dropped += 1;
+        first += 1;
+        const rest = render(0, t1.slice(first));
+        const text = `…(${dropped} earlier turn(s) dropped: over budget)\n${rest}`;
+        if (text.length <= budgetChars)
+            return text;
+    }
+    return render(0, t1.slice(-1)).slice(0, budgetChars);
+}
+/**
+ * The surface seqs this compaction shadows, recovered from the summarization
+ * input's message count.
+ *
+ * `SummarizationInput` carries no seqs, but the base class always builds it as
+ * `[system head?] + shadowed region in surface order`, so the count recovers the
+ * span exactly. Verified against 120 real compactions: the recovered span
+ * matched the shadowed span seq-for-seq every time.
+ *
+ * @param session - session whose surface the input was built from.
+ * @param input - the replayed prefix handed to `summarize`.
+ * @returns the shadowed surface seqs in order.
+ */
+export function shadowedSeqs(session, input) {
+    const nodes = session.surface.nodes;
+    const head = nodes[0] !== undefined && session.eventAt(nodes[0])?.type === 'system/message' ? 1 : 0;
+    const take = Math.max(0, input.messages.length - head);
+    return nodes.slice(head, head + take);
+}
+/**
+ * Pick the log events the digest is built from: every append-origin surface
+ * event, minus the retained tail.
+ *
+ * The retained tail is what stays on the surface after this compaction, so
+ * excluding it keeps the digest and the surviving surface disjoint. Everything
+ * else has either already been shadowed by an earlier checkpoint or is being
+ * shadowed now, and must appear in the digest or it is lost.
+ *
+ * Events a `{op: 'replace'}` copy superseded still qualify, because their own
+ * marker is `'append'`. That is deliberate: tool results become a one-line
+ * pointer either way, so including the pre-replacement original changes the
+ * digest by 19-109 tokens across the measured sessions, and never dropping
+ * content is worth more than that.
+ *
+ * @param session - session whose log supplies the events.
+ * @param retainedSeqs - seqs that remain on the surface after this compaction.
+ * @returns the events the digest is built from, in log order.
+ */
+export function digestSource(session, retainedSeqs) {
+    return session.snapshotEvents().filter((event) => {
+        // `turn/start` is not a surface event, but it is the only record of which
+        // turn a user message belongs to: user messages carry no turn of their own.
+        // Keeping the markers costs a few tokens and makes every heading say
+        // "turn 37" instead of "turn ?".
+        if (event.type === 'turn/start')
+            return true;
+        if (event.surfaceOp !== 'append')
+            return false;
+        if (isCheckpoint(event))
+            return false;
+        return !retainedSeqs.has(event.seq);
+    });
+}
+/**
+ * Deterministic compaction backend: verbatim prose, pointerized tools, no model
+ * call.
+ *
+ * Everything except `summarize()` is inherited. The base class prices pressure,
+ * selects the span, writes the durable `compaction/start` ... `compaction/end`
+ * pair, applies the shrink guard and records `compaction/summary`, so this
+ * subclass cannot diverge from the host's transaction semantics.
+ */
+export default class VerbatimCompactionEngine extends BasicCompactionEngine {
+    /**
+     * Build the replacement checkpoint content from the session log.
+     *
+     * The budget is the shrink guard's own bound rather than only the fixed
+     * ceiling: the guard compares the framed digest against the route price of
+     * the span being replaced, so a digest accumulated over a long history
+     * against a small span is the one case that can fail. Deriving the budget
+     * from that same number makes the failure impossible by construction instead
+     * of relying on measurement.
+     *
+     * @param input - replayed conversation prefix the base class is shadowing.
+     * @param agent - owner of the session being compacted.
+     * @param _signal - unused: the digest is synchronous and cannot be cancelled midway.
+     * @returns text summary blocks, unmarked by any LLM call.
+     */
+    async summarize(input, agent, _signal) {
+        const session = agent.session;
+        const shadowed = shadowedSeqs(session, input);
+        const shadowedSet = new Set(shadowed);
+        const retained = new Set(session.surface.nodes.filter((seq) => !shadowedSet.has(seq)));
+        const source = digestSource(session, retained);
+        let shadowedPrice = 0;
+        for (const node of this.ctx.tokenMeter.measure(session).nodes) {
+            if (shadowedSet.has(node.seq))
+                shadowedPrice += node.tokens;
+        }
+        const budget = Math.max(0, Math.min(DIGEST_BUDGET_TOKENS, shadowedPrice - FRAME_TOKENS - SHRINK_MARGIN_TOKENS));
+        const text = renderDigest(source, budget);
+        const route = session.requestHeader()?.config;
+        return {
+            summary: [{ type: 'text', text }],
+            provider: route?.provider ?? agent.options.provider ?? 'verbatim',
+            model: route?.model ?? agent.options.model ?? 'digest',
+        };
+    }
+}

package/lib/types/index.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Deterministic, verbatim-history compaction backend.
+ *
+ * `@deepseek-ai/dsh-compaction-basic` condenses a shadowed span through one
+ * `ctx.llm.stream()` call whose instruction asks for a nine-section template
+ * ("Primary Request / Key Technical Concepts / Errors and Fixes ..."). Measured
+ * over eight real sessions (403 MiB, 145 compactions, 24.5M discarded tokens)
+ * that template retains 2.38% of what it discards, and of everything discarded
+ * only 0.67% is prose a human wrote -- the rest is reasoning (63.8%), tool
+ * results (25.2%) and tool-call arguments (10.4%). The prose that does survive
+ * is then summarized again on the next compaction, because
+ * `selectCompactableRange` always starts at `surfaceNodes[firstIdx]` and the
+ * previous checkpoint sits at index 1.
+ *
+ * This backend keeps the base class's replay, range selection, durable
+ * transaction and shrink guard untouched and overrides only `summarize()`, the
+ * one hook the base class documents for exactly this purpose. The replacement
+ * summary is built deterministically, with no model call:
+ *
+ *   - user and assistant prose verbatim, per turn;
+ *   - tool results reduced to one line (tool names, call counts, bytes);
+ *   - reasoning never read;
+ *   - repeated injections recorded once.
+ *
+ * The digest source is the session log, not the shadowed span: the previous
+ * checkpoint is itself shadowed on every compaction, so a span-only digest
+ * would drop everything the previous digest carried. Reading the log's
+ * append-origin surface events minus the retained tail reconstructs the whole
+ * history without any accumulated state.
+ *
+ * @module @logictan/dsh-verbatim-compaction
+ */
+import { BasicCompactionEngine } from '@deepseek-ai/dsh-compaction-basic';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { ContentBlock, Message } from '@deepseek-ai/dsh-llm';
+import type { Session, SessionEvent, SessionSeq } from '@deepseek-ai/dsh-session';
+/** Cordis companion plugin name. Must equal this plugin's `cordis.patch.yml` row id. */
+export declare const name = "verbatim-compaction";
+/** The replayed prefix the base class hands to `summarize`. */
+export interface SummarizationInput {
+    /** Tool schemas reused for prefix-cache alignment; absent when the request carried none. */
+    readonly tools?: readonly unknown[];
+    /** The derived system head, when present, followed by the shadowed region in surface order. */
+    readonly messages: readonly Message[];
+}
+/** Safe summary content plus the envelope the base class records with it. */
+export interface SummaryResult {
+    summary: ContentBlock[];
+    provider: string;
+    model: string;
+}
+/** One turn's accumulated digest material. */
+interface Turn {
+    turn: number | undefined;
+    user: string[];
+    assistant: string[];
+    tools: Map<string, number>;
+    resultBytes: number;
+    errors: string[];
+    writes: string[];
+}
+/** One digest section: everything from one non-injected user message to the next. */
+interface Section {
+    turns: Turn[];
+}
+/**
+ * Group append-origin surface events into per-turn digest material.
+ *
+ * A section starts at each non-injected user message; assistant-only runs
+ * before the first user message join the first section. Turn numbers come from
+ * the log: `turn/start` carries `{turn}` and `assistant/message` carries
+ * `data.turn`. A user message carries no turn of its own, so it inherits the
+ * last one seen.
+ *
+ * @param events - the digest source in log order.
+ * @returns one section per non-injected user message.
+ */
+export declare function buildSections(events: readonly SessionEvent[]): Section[];
+/**
+ * Render the digest under a hard character budget.
+ *
+ * The two truncation tiers are the plan's T1 and T1', in that order:
+ *
+ * - **T1** user prose is verbatim unless it alone exceeds `USER_BUDGET_SHARE` of
+ *   the budget, then the oldest turns are cut first.
+ * - **T1'** assistant prose is verbatim unless the whole digest overflows, then
+ *   it is cut evenly per turn down to `MIN_TURN_CHARS`.
+ *
+ * T1' runs *after* T1 because a user's own words are the least reconstructible
+ * thing in the log: an assistant's reply can be inferred from its tool calls
+ * and the surrounding turns, a user's request cannot. The 800-character floor
+ * exists so a tight budget thins every turn instead of erasing the last few.
+ *
+ * Neither tier runs in practice: over the eight measured sessions the largest
+ * digest was 44542 tokens against a 196752 budget, and user prose totalled 2591
+ * tokens against a 98376 cap. They are a guard against a pasted file, not the
+ * normal path.
+ *
+ * @param events - the digest source in log order.
+ * @param budgetTokens - hard ceiling in the meter's fixed 4-chars-per-token heuristic.
+ * @returns the digest text, never longer than `budgetTokens * 4` characters.
+ */
+export declare function renderDigest(events: readonly SessionEvent[], budgetTokens: number): string;
+/**
+ * The surface seqs this compaction shadows, recovered from the summarization
+ * input's message count.
+ *
+ * `SummarizationInput` carries no seqs, but the base class always builds it as
+ * `[system head?] + shadowed region in surface order`, so the count recovers the
+ * span exactly. Verified against 120 real compactions: the recovered span
+ * matched the shadowed span seq-for-seq every time.
+ *
+ * @param session - session whose surface the input was built from.
+ * @param input - the replayed prefix handed to `summarize`.
+ * @returns the shadowed surface seqs in order.
+ */
+export declare function shadowedSeqs(session: Session, input: SummarizationInput): SessionSeq[];
+/**
+ * Pick the log events the digest is built from: every append-origin surface
+ * event, minus the retained tail.
+ *
+ * The retained tail is what stays on the surface after this compaction, so
+ * excluding it keeps the digest and the surviving surface disjoint. Everything
+ * else has either already been shadowed by an earlier checkpoint or is being
+ * shadowed now, and must appear in the digest or it is lost.
+ *
+ * Events a `{op: 'replace'}` copy superseded still qualify, because their own
+ * marker is `'append'`. That is deliberate: tool results become a one-line
+ * pointer either way, so including the pre-replacement original changes the
+ * digest by 19-109 tokens across the measured sessions, and never dropping
+ * content is worth more than that.
+ *
+ * @param session - session whose log supplies the events.
+ * @param retainedSeqs - seqs that remain on the surface after this compaction.
+ * @returns the events the digest is built from, in log order.
+ */
+export declare function digestSource(session: Session, retainedSeqs: ReadonlySet<SessionSeq>): readonly SessionEvent[];
+/**
+ * Deterministic compaction backend: verbatim prose, pointerized tools, no model
+ * call.
+ *
+ * Everything except `summarize()` is inherited. The base class prices pressure,
+ * selects the span, writes the durable `compaction/start` ... `compaction/end`
+ * pair, applies the shrink guard and records `compaction/summary`, so this
+ * subclass cannot diverge from the host's transaction semantics.
+ */
+export default class VerbatimCompactionEngine extends BasicCompactionEngine {
+    /**
+     * Build the replacement checkpoint content from the session log.
+     *
+     * The budget is the shrink guard's own bound rather than only the fixed
+     * ceiling: the guard compares the framed digest against the route price of
+     * the span being replaced, so a digest accumulated over a long history
+     * against a small span is the one case that can fail. Deriving the budget
+     * from that same number makes the failure impossible by construction instead
+     * of relying on measurement.
+     *
+     * @param input - replayed conversation prefix the base class is shadowing.
+     * @param agent - owner of the session being compacted.
+     * @param _signal - unused: the digest is synchronous and cannot be cancelled midway.
+     * @returns text summary blocks, unmarked by any LLM call.
+     */
+    protected summarize(input: SummarizationInput, agent: Agent, _signal?: AbortSignal): Promise<SummaryResult>;
+}
+export {};

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "@logictan/dsh-verbatim-compaction",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Deterministic compaction backend that keeps conversation prose verbatim in the checkpoint instead of re-summarizing it: user and assistant text survive word for word, tool results collapse to one-line pointers, reasoning is never read, and no model call is made.",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node build.mjs",
+    "prepare": "node build.mjs",
+    "prepack": "node build.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "node build.mjs && node --test \"test/*.spec.mjs\""
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "compaction",
+    "context",
+    "checkpoint",
+    "summarization"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dale0525/dsh-plugins.git",
+    "directory": "packages/dsh-verbatim-compaction"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-agent": ">=0.1.6-alpha.1 <0.2.0 || ^0.2.1-rc.2",
+    "@deepseek-ai/dsh-compaction": ">=0.1.6-alpha.1 <0.2.0 || ^0.2.1-rc.2",
+    "@deepseek-ai/dsh-compaction-basic": ">=0.1.6-alpha.1 <0.2.0 || ^0.2.1-rc.2",
+    "@deepseek-ai/dsh-llm": ">=0.1.6-alpha.1 <0.2.0 || ^0.2.1-rc.2",
+    "@deepseek-ai/dsh-session": ">=0.1.6-alpha.1 <0.2.0 || ^0.2.1-rc.2",
+    "@deepseek-ai/dsh-token-meter": ">=0.1.6-alpha.1 <0.2.0 || ^0.2.1-rc.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.5",
+    "@deepseek-ai/dsh-agent": "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-session": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-token-meter": "0.2.1-rc.2",
+    "typescript": "^5.9.0",
+    "@types/node": "^22.20.0"
+  }
+}