@logictan/dsh-verbatim-compaction 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @logictan/dsh-verbatim-compaction
 
-把上下文压缩的**摘要**从「让模型重写一遍」换成「确定性地把正文抄进 checkpoint」：用户与助手的正文逐字保留，工具结果压成一行指针，推理块从不读取，全程零模型调用。
+把上下文压缩的**摘要**从「让模型重写一遍」换成「正文逐字抄进 checkpoint，再用一次模型调用从工具轨迹里补出结论」：用户与助手的正文逐字保留、推理块从不读取；每轮另调一次会话自身的模型，输出「做了什么 / 得到什么结论 / 哪些结论被推翻」。
 
 ## 它解决什么
 
@@ -37,6 +37,22 @@
 
 `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。

package/lib/index.js

@@ -115,6 +115,115 @@ 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;
+}
+/** 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 +506,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.
@@ -434,7 +634,15 @@ export default class VerbatimCompactionEngine extends BasicCompactionEngine {
                 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 verbatim = renderDigest(source, budget);
+        // Per-turn extraction, appended to the verbatim digest. Bounded by the same
+        // budget: if the extracted text would push the digest past it, the digest
+        // alone is kept, because an over-budget checkpoint fails the shrink guard and
+        // loses the whole compaction rather than some detail.
+        const extracted = await this.extractAll(source, agent, _signal);
+        const text = extracted.length === 0
+            ? verbatim
+            : `${verbatim}\n\n# Extracted from tool traces\n${extracted}`.slice(0, Math.max(verbatim.length, budget * 4));
         const route = session.requestHeader()?.config;
         return {
             summary: [{ type: 'text', text }],
@@ -442,4 +650,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.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",