@logictan/dsh-verbatim-compaction 0.1.0 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 # @logictan/dsh-verbatim-compaction
 
-把上下文压缩的**摘要**从「让模型重写一遍」换成「确定性地把正文抄进 checkpoint」：用户与助手的正文逐字保留，工具结果压成一行指针，推理块从不读取，全程零模型调用。
+把上下文压缩的**摘要**从「让模型重写一遍」换成「正文逐字抄进 checkpoint，再用一次模型调用从工具轨迹里补出结论」：用户与助手的正文逐字保留、推理块从不读取；每轮另调一次会话自身的模型，输出「做了什么 / 得到什么结论 / 哪些结论被推翻」。
 
 ## 它解决什么
 
@@ -37,9 +37,33 @@
 
 `turn/start` 不在 surface 上，但它是「这条 user 消息属于第几轮」的唯一记录（user 消息自身不带 turn），所以一并保留。
 
+## 工具轨迹补出的三节
+
+逐字抄正文救不了「正文为空」的轮次。实测一个 13878 事件的会话：1973 条 assistant 消息里只有 317 条带正文，其中一轮跑了 342 次工具调用却一个字没写，逐字摘要把它压成一行 `tools: bash×281`——活干了，记录没了。
+
+所以每轮另发一次模型调用，材料是三段：用户请求（逐字）、助手正文（逐字）、工具轨迹（每条调用的 `description`，失败的调用另记一行首行错误）。模型输出固定的三节：`## Did` / `## Concluded` / `## Overturned`。
+
+模型用的是会话自己的路由（`session.requestHeader()?.config`），和宿主原生压缩同一个取法，不需要单独配置凭据。
+
+三件事刻意做成这样：
+
+- **失败信号只认 `data.isError`**。曾用 `/error/i` 匹配序列化文本，347 条成功结果全部命中（工具输出里常有 "error" 字样），模型据此报告「整轮失败」。测试里有一条专门钉住这个坑。
+- **工具调用从 `assistant/message` 的 block 里取**。日志里没有独立的 `tool/call` 事件类型，按它过滤会一条都取不到。
+- **提取失败就退回纯逐字摘要**。模型不可达、超时、输出为空都返回 null；压缩本身不能因此失败，否则会话死于上下文溢出，比丢细节更糟。
+
+代价是每轮一次模型调用（实测 13 轮合计约 74649 字符材料）。提取块放在摘要**最前面**，与逐字摘要共用同一个预算：截断切的是尾部，因此预算紧时先削正文、保住结论。反过来放（曾经如此）会让「本轮得出了什么」成为第一个被删的东西。
+
 ## 为什么不会触发 shrink 守卫
 
-基类的守卫比较「framed 摘要」与「被替换内容的 route 价」，摘要不小于原内容就整次压缩失败。本插件把预算直接算成 `min(196752, shadowedPrice − 86 − 512)`：上界取守卫自己的那个数，因此这条失败路径按构造不可能发生，而不是靠实测侥幸。实测 8 个会话 0 次触发，最小余量 174387。
+基类的守卫比较「framed 摘要」与「被替换内容的 route 价」，摘要不小于原内容就整次压缩失败。本插件把预算算成 `min(shadowedPrice × 0.5, shadowedPrice − 86 − 512)`，因此这条失败路径按构造不可能发生，而不是靠实测侥幸。
+
+## 为什么会收敛（一条真实事故）
+
+只满足守卫**不等于**收敛。守卫只要求摘要比被替换的内容小，一个占到被替换量 99.3% 的摘要照样通过守卫，而 surface 几乎没变。
+
+会话 `小鹏汽车 App 改造评估` 上真实发生过：一次压缩 shadowed 87733 token，产出摘要 priced 87135——只回收 598 token（0.7%）。压缩后 surface 实测 **256704** token，阈值 **256464**，刚好卡在阈值上方，于是下一步立刻又压；此时 surface 上除 checkpoint 外没别的东西，第二次只 shadowed **1 个 seq**（就是刚写的那条 checkpoint），把同样的 34.8 万字符原样重抄一遍（346555 vs 348539），第三次直接 abort。
+
+预算改成被替换量的一半后，同一份日志实测：257696 → **188120** token（0.73× 阈值），一轮就落到阈值以下。只压一条 checkpoint 时摘要也减半（279048 → 139865 字符），因此是几何衰减而非固定点。
 
 ## 安装
 
@@ -91,7 +115,7 @@ pnpm add @logictan/dsh-verbatim-compaction
 
 ## 已知边界
 
-- **正文超预算会被截断。** 预算是硬的，两级依次触发：**先** user 正文超过预算一半时从**最新**往前算、最旧的先丢（用户刚说的话是下一轮唯一依赖的东西，丢它等于丢任务）；**仍不够**才把助手正文按轮均分截断，每轮下限 800 字符。8 个实测会话里两级都没跑过（最大摘要 44542 token，预算 196752），所以这是守卫而不是常态。
+- **正文超预算会被截断。** 预算是硬的，两级依次触发：**先** user 正文超过预算一半时从**最新**往前算、最旧的先丢（用户刚说的话是下一轮唯一依赖的东西，丢它等于丢任务）；**仍不够**才把助手正文按轮均分截断，每轮下限 800 字符。在 122 轮、助手正文 31.6 万字符的真实会话上，第一级触发 104 处、第二级没触发——长会话里这是常态而不是守卫。
 - **`turn/start` 缺失时轮次编号退化为 `turn ?`。** 不会丢正文，只是编号不可读。
 - **注入内容不进摘要。** 判据是 `source.kind !== 'user'`——注入上下文在一个真实会话里占 user 消息字符的 97%，放进摘要会把人的原话淹掉。
 - **不改善首轮之外的工具参数细节。** `bash` 命令本身（占工具参数 84.2%）不保留；需要「当时跑了什么命令」的场景不在本插件的覆盖范围内。

package/lib/index.js

@@ -34,14 +34,22 @@ 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.
+ * Largest share of the shadowed price one digest may occupy.
  *
- * 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`.
+ * Satisfying the shrink guard is not convergence. The guard only requires the
+ * framed digest to be *smaller* than what it replaces; a digest priced at 99.3%
+ * of its span passes the guard and still leaves the surface where it started.
+ * Measured on session `小鹏汽车 App 改造评估`: one compaction shadowed 87733
+ * tokens and produced a digest priced at 87135 — 598 tokens (0.7%) reclaimed —
+ * and the resulting surface measured 256704 tokens against a 256464 threshold,
+ * so the very next step compacted again, this time shadowing exactly one seq
+ * (the checkpoint it had just written) and reproducing the same 348k characters
+ * until the third attempt was aborted.
+ *
+ * At half, each compaction makes progress however much history has accumulated,
+ * so one pass drops the surface well below the threshold.
  */
-const DIGEST_BUDGET_TOKENS = 196752;
+const DIGEST_SHARE_OF_SHADOWED = 0.5;
 /** Framing overhead `frameSummary` adds: preamble plus both tags, 341 chars = 86 tokens. */
 const FRAME_TOKENS = 86;
 /** Safety margin below the shrink guard, in tokens. */
@@ -115,6 +123,117 @@ function toolCallsOf(event) {
     }
     return calls;
 }
+/**
+ * Whether one tool result is a failure.
+ *
+ * Reads `data.message.isError` and nothing else. Matching the serialized text
+ * for /error/i was tried and is wrong: tool output routinely contains that word
+ * (grep misses, compiler logs, dumps of source files), so it labelled every
+ * result in a 347-result turn as failed and the summarizer reported the whole
+ * turn as a failure.
+ *
+ * @param event - a `tool/result` event.
+ * @returns true only when the log itself marks the result as an error.
+ */
+export function isErrorResult(event) {
+    const message = messageOf(event);
+    return message?.isError === true;
+}
+/** Heading that introduces the extracted section at the top of a digest. */
+const EXTRACTED_HEADING = '# Extracted from tool traces';
+/** Directive appended as the final user message of the extraction call. */
+const EXTRACT_INSTRUCTION = [
+    'You are summarizing ONE turn of a coding session for a compaction checkpoint.',
+    'The material below is the turn\'s user request, its assistant prose (may be empty), and a trace of the tool calls it made (descriptions only) plus any results the log marked as errors.',
+    '',
+    'Output EXACTLY these three Markdown headings, in order. Under each, at most two terse lines. If a section has no real information, write "(none)" — never invent.',
+    '',
+    '## Did',
+    '- what was actually done, concretely',
+    '',
+    '## Concluded',
+    '- findings, decisions, or measurements that a later turn would need',
+    '',
+    '## Overturned',
+    '- earlier conclusions this turn disproved or replaced',
+    '',
+    'Do not describe the tool calls themselves ("ran bash", "explored the repo"). State what came out of them. If the trace is too thin to support a claim, write "(none)".',
+].join('\n');
+/** Most tool calls one turn may contribute to the hint block. */
+const MAX_HINTS_PER_TURN = 120;
+/** Characters kept from one call's description or command head. */
+const HINT_CHARS = 100;
+/** Characters kept from one failing result's first line. */
+const ERROR_CHARS = 140;
+/**
+ * The best short description of what one call was for.
+ *
+ * The description argument wins when present because the agent writes it for
+ * humans; the command body is the fallback and is truncated hard, since a single
+ * `python3 -c` can be hundreds of lines.
+ */
+function hintOf(argumentsJson) {
+    let parsed;
+    try {
+        const value = JSON.parse(argumentsJson);
+        if (typeof value !== 'object' || value === null)
+            return '';
+        parsed = value;
+    }
+    catch {
+        return '';
+    }
+    for (const key of ['description', 'command', 'query', 'file_path', 'path', 'pattern']) {
+        const candidate = parsed[key];
+        if (typeof candidate === 'string' && candidate.trim().length > 0) {
+            return candidate.trim().replace(/\s+/g, ' ').slice(0, HINT_CHARS);
+        }
+    }
+    return '';
+}
+/**
+ * Build the compact per-turn trace fed to the summarizer.
+ *
+ * This is what lets a turn whose assistant prose is empty still leave a record:
+ * in the measured session one turn ran 342 tool calls and emitted zero prose, so
+ * the verbatim digest reduced it to a single `tools:` count line. The trace names
+ * what was attempted and which attempts failed, which is enough for a model to
+ * state the outcome.
+ *
+ * Bounded on purpose — 500 calls would otherwise produce a prompt larger than the
+ * material it summarizes.
+ *
+ * @param events - one turn's events, in log order.
+ * @returns newline-joined hints, or an empty string when the turn has none.
+ */
+export function collectHints(events) {
+    const lines = [];
+    let calls = 0;
+    for (const event of events) {
+        // Tool calls are blocks inside `assistant/message`, not standalone events:
+        // `digestSource` emits no `tool/call` type at all, so selecting on that type
+        // matched nothing and a 342-call turn produced a single hint line.
+        if (event.type === 'assistant/message') {
+            for (const call of toolCallsOf(event)) {
+                if (calls >= MAX_HINTS_PER_TURN)
+                    break;
+                calls += 1;
+                const hint = hintOf(call.arguments);
+                lines.push(hint.length > 0 ? `TOOL ${call.name}: ${hint}` : `TOOL ${call.name}`);
+            }
+            continue;
+        }
+        if (event.type !== 'tool/result')
+            continue;
+        if (!isErrorResult(event))
+            continue;
+        const firstLine = textOf(event).split('\n')[0] ?? '';
+        if (firstLine.trim().length === 0)
+            continue;
+        lines.push(`ERR ${firstLine.trim().slice(0, ERROR_CHARS)}`);
+    }
+    return lines.join('\n');
+}
 /** The `path` argument of one tool call, when the call carries one. */
 function pathArgumentOf(argumentsJson) {
     try {
@@ -397,6 +516,97 @@ export function digestSource(session, retainedSeqs) {
         return !retainedSeqs.has(event.seq);
     });
 }
+/**
+ * Assemble the three-part material one extraction call is given.
+ *
+ * Split out from the call itself so it can be asserted: the first hand-built
+ * version of this silently dropped the user request, because it selected user
+ * messages by `data.turn` and user messages carry no turn of their own. The model
+ * then summarized tool names with no idea what had been asked.
+ *
+ * @param turn - one turn's events, in log order.
+ * @param prose - that turn's assistant prose, already extracted by the caller.
+ * @returns the joined material, or an empty string when the turn has nothing.
+ */
+export function buildExtractionMaterial(turn, prose) {
+    const userRequest = turn
+        .filter((event) => event.type === 'user/message' && !isInjection(event) && !isCheckpoint(event))
+        .map((event) => textOf(event))
+        .filter((text) => text.length > 0)
+        .join('\n');
+    const hints = collectHints(turn);
+    if (userRequest.length === 0 && prose.length === 0 && hints.length === 0)
+        return '';
+    return [
+        `USER REQUEST:\n${userRequest.slice(0, 4000) || '(none)'}`,
+        `ASSISTANT PROSE:\n${prose.slice(0, 6000) || '(none)'}`,
+        `TOOL TRACE:\n${hints || '(none)'}`,
+    ].join('\n\n');
+}
+/**
+ * Per-turn extraction through the host's own LLM service.
+ *
+ * This is the part the verbatim digest cannot do on its own. Measured on a real
+ * 13878-event session: 1973 assistant messages, of which only 317 carried any
+ * prose, and one turn ran 342 tool calls while emitting zero characters of text.
+ * A digest that only copies prose therefore reduced that whole turn to a `tools:`
+ * count line — the work happened, the record did not.
+ *
+ * The call reuses the session's routed model exactly as the host's own
+ * compaction does (`ctx.llm.stream` with the session's provider/model), so no
+ * separate credential or configuration is involved.
+ *
+ * Every failure path returns null and the caller falls back to the plain digest:
+ * a compaction that cannot reach the model must still compact, or the session
+ * dies of context overflow instead of losing detail.
+ *
+ * @param ctx - plugin context carrying the `llm` service.
+ * @param agent - owner of the session being compacted; supplies the routed model.
+ * @param turn - one turn's events.
+ * @param prose - that turn's assistant prose, already extracted.
+ * @param signal - cancellation forwarded to the adapter.
+ * @returns the extracted block, or null when extraction is unavailable.
+ */
+async function extractTurn(ctx, agent, turn, prose, signal) {
+    const llm = ctx.llm;
+    if (llm === undefined)
+        return null;
+    const route = agent.session.requestHeader()?.config;
+    const provider = route?.provider ?? agent.options.provider;
+    const model = route?.model ?? agent.options.model;
+    if (provider === undefined || model === undefined)
+        return null;
+    const material = buildExtractionMaterial(turn, prose);
+    if (material.length === 0)
+        return null;
+    const chunks = [];
+    try {
+        const stream = llm.stream({
+            provider,
+            model,
+            messages: [
+                { role: 'user', content: [{ type: 'text', text: `${material}\n\n${EXTRACT_INSTRUCTION}` }] },
+            ],
+            maxTokens: 400,
+            sessionId: agent.session.id,
+            purpose: 'compaction',
+            ...(signal === undefined ? {} : { signal }),
+        });
+        for await (const chunk of stream) {
+            // Chunk kinds come from `@deepseek-ai/dsh-llm`'s BlockAssembler: text
+            // arrives as `text-delta`, and `reasoning-delta` is deliberately ignored —
+            // reasoning is 98.8% of a long session's output and is not the record.
+            const delta = chunk;
+            if (delta.type === 'text-delta' && typeof delta.text === 'string')
+                chunks.push(delta.text);
+        }
+    }
+    catch {
+        return null;
+    }
+    const text = chunks.join('').trim();
+    return text.length > 0 ? text : null;
+}
 /**
  * Deterministic compaction backend: verbatim prose, pointerized tools, no model
  * call.
@@ -433,8 +643,23 @@ export default class VerbatimCompactionEngine extends BasicCompactionEngine {
             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 budget = Math.max(0, Math.min(
+        // Half the span is the convergence contract, not the guard's own bound.
+        // See `DIGEST_SHARE_OF_SHADOWED` for the 87733→87135 measurement.
+        Math.floor(shadowedPrice * DIGEST_SHARE_OF_SHADOWED), shadowedPrice - FRAME_TOKENS - SHRINK_MARGIN_TOKENS));
+        const verbatim = renderDigest(source, budget);
+        // Per-turn extraction, prepended rather than appended.
+        //
+        // Order matters under truncation: `slice` cuts the tail, so appending the
+        // extraction put the most reconstructible content first and the least
+        // reconstructible content last — a tight budget deleted exactly the "what
+        // did this turn conclude / what did it overturn" record and kept the prose
+        // it summarised. Leading with the extraction makes the digest degrade the
+        // way the plan intends: conclusions survive, prose thins.
+        const extracted = await this.extractAll(source, agent, _signal);
+        const text = extracted.length === 0
+            ? verbatim
+            : `${EXTRACTED_HEADING}\n${extracted}\n\n${verbatim}`.slice(0, Math.max(verbatim.length, budget * 4));
         const route = session.requestHeader()?.config;
         return {
             summary: [{ type: 'text', text }],
@@ -442,4 +667,54 @@ export default class VerbatimCompactionEngine extends BasicCompactionEngine {
             model: route?.model ?? agent.options.model ?? 'digest',
         };
     }
+    /**
+     * Run the extraction for every turn in the digest source.
+     *
+     * Sequential rather than parallel: these calls share the session's routed
+     * model and the provider's KV cache, and firing a dozen at once would both
+     * multiply the cost and defeat the cache the host's own summarizer relies on.
+     *
+     * A turn that fails is simply absent from the output; one bad turn must not
+     * drop the extraction for the rest.
+     *
+     * @param source - digest source events, in log order.
+     * @param agent - owner of the session being compacted.
+     * @param signal - cancellation forwarded to every call.
+     * @returns the extracted blocks joined by turn heading, or an empty string.
+     */
+    async extractAll(source, agent, signal) {
+        const turns = new Map();
+        let lastTurn;
+        for (const event of source) {
+            if (event.type === 'turn/start') {
+                const turn = turnOf(event);
+                if (turn !== undefined)
+                    lastTurn = turn;
+                continue;
+            }
+            const turn = turnOf(event) ?? lastTurn;
+            if (turn === undefined)
+                continue;
+            const bucket = turns.get(turn);
+            if (bucket === undefined)
+                turns.set(turn, [event]);
+            else
+                bucket.push(event);
+        }
+        const blocks = [];
+        for (const [turn, events] of [...turns.entries()].sort((left, right) => left[0] - right[0])) {
+            if (signal?.aborted === true)
+                break;
+            const prose = events
+                .filter((event) => event.type === 'assistant/message')
+                .map((event) => textOf(event))
+                .filter((text) => text.length > 0)
+                .join('\n');
+            const extracted = await extractTurn(this.ctx, agent, events, prose, signal);
+            if (extracted === null)
+                continue;
+            blocks.push(`\n## turn ${turn}\n${extracted}`);
+        }
+        return blocks.join('\n');
+    }
 }

package/lib/types/index.d.ts

@@ -49,6 +49,35 @@ export interface SummaryResult {
     provider: string;
     model: string;
 }
+/**
+ * Whether one tool result is a failure.
+ *
+ * Reads `data.message.isError` and nothing else. Matching the serialized text
+ * for /error/i was tried and is wrong: tool output routinely contains that word
+ * (grep misses, compiler logs, dumps of source files), so it labelled every
+ * result in a 347-result turn as failed and the summarizer reported the whole
+ * turn as a failure.
+ *
+ * @param event - a `tool/result` event.
+ * @returns true only when the log itself marks the result as an error.
+ */
+export declare function isErrorResult(event: SessionEvent): boolean;
+/**
+ * Build the compact per-turn trace fed to the summarizer.
+ *
+ * This is what lets a turn whose assistant prose is empty still leave a record:
+ * in the measured session one turn ran 342 tool calls and emitted zero prose, so
+ * the verbatim digest reduced it to a single `tools:` count line. The trace names
+ * what was attempted and which attempts failed, which is enough for a model to
+ * state the outcome.
+ *
+ * Bounded on purpose — 500 calls would otherwise produce a prompt larger than the
+ * material it summarizes.
+ *
+ * @param events - one turn's events, in log order.
+ * @returns newline-joined hints, or an empty string when the turn has none.
+ */
+export declare function collectHints(events: readonly SessionEvent[]): string;
 /** One turn's accumulated digest material. */
 interface Turn {
     turn: number | undefined;
@@ -135,6 +164,19 @@ export declare function shadowedSeqs(session: Session, input: SummarizationInput
  * @returns the events the digest is built from, in log order.
  */
 export declare function digestSource(session: Session, retainedSeqs: ReadonlySet<SessionSeq>): readonly SessionEvent[];
+/**
+ * Assemble the three-part material one extraction call is given.
+ *
+ * Split out from the call itself so it can be asserted: the first hand-built
+ * version of this silently dropped the user request, because it selected user
+ * messages by `data.turn` and user messages carry no turn of their own. The model
+ * then summarized tool names with no idea what had been asked.
+ *
+ * @param turn - one turn's events, in log order.
+ * @param prose - that turn's assistant prose, already extracted by the caller.
+ * @returns the joined material, or an empty string when the turn has nothing.
+ */
+export declare function buildExtractionMaterial(turn: readonly SessionEvent[], prose: string): string;
 /**
  * Deterministic compaction backend: verbatim prose, pointerized tools, no model
  * call.
@@ -161,5 +203,21 @@ export default class VerbatimCompactionEngine extends BasicCompactionEngine {
      * @returns text summary blocks, unmarked by any LLM call.
      */
     protected summarize(input: SummarizationInput, agent: Agent, _signal?: AbortSignal): Promise<SummaryResult>;
+    /**
+     * Run the extraction for every turn in the digest source.
+     *
+     * Sequential rather than parallel: these calls share the session's routed
+     * model and the provider's KV cache, and firing a dozen at once would both
+     * multiply the cost and defeat the cache the host's own summarizer relies on.
+     *
+     * A turn that fails is simply absent from the output; one bad turn must not
+     * drop the extraction for the rest.
+     *
+     * @param source - digest source events, in log order.
+     * @param agent - owner of the session being compacted.
+     * @param signal - cancellation forwarded to every call.
+     * @returns the extracted blocks joined by turn heading, or an empty string.
+     */
+    private extractAll;
 }
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logictan/dsh-verbatim-compaction",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "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",