dsh-auto-compaction 0.1.2 → 0.1.3

package/lib/index.js

@@ -22,8 +22,19 @@ import { join } from "node:path";
 import { BlockAssembler, LlmError, contentHasImage } from "@deepseek-ai/dsh-llm";
 import BasicCompactionEngine from "@deepseek-ai/dsh-compaction-basic";
 import { decideTrigger, shouldAttempt } from "./plan.js";
+import { writeStatus } from "./status.js";
+import {
+  continuationInstruction,
+  expectedSections,
+  looksTruncated,
+  mergeSummary,
+  rewriteInstruction,
+  stripTruncationMarkers,
+  validateSummary,
+} from "./summary.js";
 
 const LOG = "[handoff]";
+const MAX_SUMMARY_ATTEMPTS = 3;
 
 const SETTINGS_DIR = join(homedir(), ".dsh-handoff-compaction");
 // Test harnesses point this at a missing file so the live sidecar cannot leak
@@ -126,6 +137,22 @@ function finishError(finish) {
   }
 }
 
+function mergeUsage(left, right) {
+  if (left === undefined) return right;
+  if (right === undefined) return left;
+  const merged = { ...left };
+  for (const key of Object.keys(right)) {
+    const value = right[key];
+    if (typeof value === "number" && typeof merged[key] === "number") merged[key] += value;
+    else if (merged[key] === undefined) merged[key] = value;
+  }
+  return merged;
+}
+
+function errorCodeOf(error) {
+  return error !== null && typeof error === "object" && typeof error.code === "string" ? error.code : "";
+}
+
 export default class HandoffCompaction extends BasicCompactionEngine {
   static inject = ["llm", "tokenMeter", "sessions"];
 
@@ -171,9 +198,10 @@ export default class HandoffCompaction extends BasicCompactionEngine {
       autoCreateTemplate,
       ...base
     } = config;
-    // auto:false keeps the stock between-step pressure trigger out of the way;
-    // this backend decides on idle instead.
-    super(ctx, { ...base, auto: false });
+    // The stock trigger is registered so the plugin switch can hand compaction
+    // back to the native engine live; compactIfNeeded() suppresses it while the
+    // handoff path is enabled.
+    super(ctx, { ...base, auto: true });
     this.handoff = {
       instruction: typeof handoffInstruction === "string" && handoffInstruction.trim().length > 0 ? handoffInstruction : undefined,
       contextWindowOverride: contextWindowOverride ?? 0,
@@ -213,6 +241,26 @@ export default class HandoffCompaction extends BasicCompactionEngine {
     return `${Math.round((this.config.thresholdRatio ?? 0.9) * 100)}%`;
   }
 
+  /**
+   * Settings switch. Missing settings or a missing field keeps the plugin on;
+   * only an explicit `enabled: false` hands compaction back to the stock engine.
+   */
+  handoffEnabled() {
+    const live = readSettings();
+    return !(live !== undefined && live.enabled === false);
+  }
+
+  /**
+   * The base registers its between-step pressure / overflow triggers whenever
+   * `auto` is on. While the handoff path is enabled they must stay inert, so
+   * the plugin still only compacts from its idle gate. Disabled: delegate, and
+   * DSH's native compaction behaves exactly as without the plugin.
+   */
+  async compactIfNeeded(agent, trigger, signal) {
+    if (this.handoffEnabled()) return null;
+    return super.compactIfNeeded(agent, trigger, signal);
+  }
+
   log(message, level = "info") {
     const line = `${new Date().toISOString()} ${LOG} ${message}`;
     if (this.handoff?.traceConsole === true) {
@@ -248,6 +296,7 @@ export default class HandoffCompaction extends BasicCompactionEngine {
 
   async checkAndHandoff(agent, why = "idle") {
     if (this.running.has(agent)) return;
+    if (!this.handoffEnabled()) return;
     try {
       const session = agent.session;
       if (!session) return;
@@ -303,24 +352,123 @@ export default class HandoffCompaction extends BasicCompactionEngine {
       }
 
       this.running.add(agent);
+      writeStatus(session.id, {
+        phase: "running",
+        step: "prepare",
+        startedAt: Date.now(),
+        totalTokens: measurement.totalTokens,
+        thresholdTokens: decision.thresholdTokens,
+        contextWindow,
+        timeoutMs: this.handoff.timeoutMs,
+        provider: target.provider,
+        model: target.model,
+      });
       try {
         const result = await this.compactNow(agent, AbortSignal.timeout(this.handoff.timeoutMs));
         if (result === null || result === undefined) {
+          writeStatus(session.id, {
+            phase: "done",
+            step: "done",
+            completedAt: Date.now(),
+            shadowedNodes: 0,
+            shadowedTokens: 0,
+            note: "no compactable range",
+          });
           this.log("idle: no compactable range; nothing replaced", "warn");
           return;
         }
+        writeStatus(session.id, {
+          phase: "done",
+          step: "done",
+          completedAt: Date.now(),
+          shadowedNodes: result.shadowedSeqs.length,
+          shadowedTokens: result.shadowedTokenCount,
+          missingSections: [],
+          retrying: false,
+        });
         this.log(`committed: replaced ${result.shadowedSeqs.length} node(s) (~${result.shadowedTokenCount} tokens) with the handoff checkpoint`);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        writeStatus(agent.session?.id, {
+          phase: "failed",
+          step: "failed",
+          failedAt: Date.now(),
+          error: message,
+          errorCode: errorCodeOf(error),
+        });
+        throw error;
       } finally {
         this.running.delete(agent);
       }
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
+      writeStatus(agent.session?.id, {
+        phase: "failed",
+        step: "failed",
+        failedAt: Date.now(),
+        error: message,
+        errorCode: errorCodeOf(error),
+      });
       this.log(`failed: ${message}`, "warn");
     }
   }
 
+  /**
+   * Wrap the stock transaction so manual /compact and automatic idle
+   * compaction share the same status sidecar. The base method still owns the
+   * surface lock, summarization and commit.
+   */
+  async compactNow(agent, signal, sourceCommandId) {
+    // Manual /compact while the plugin is off stays a stock native compaction:
+    // no handoff template, no plugin status sidecar.
+    if (!this.handoffEnabled()) return super.compactNow(agent, signal, sourceCommandId);
+    const sessionId = agent?.session?.id;
+    let totalTokens;
+    try { totalTokens = this.ctx.tokenMeter.measure(agent.session).totalTokens; } catch { totalTokens = undefined; }
+    writeStatus(sessionId, {
+      phase: "running",
+      step: "prepare",
+      startedAt: Date.now(),
+      timeoutMs: this.handoff.timeoutMs,
+      ...(typeof totalTokens === "number" ? { totalTokens } : {}),
+      retrying: false,
+      writing: false,
+      missingSections: [],
+      error: "",
+      errorCode: "",
+    });
+    try {
+      const result = await super.compactNow(agent, signal, sourceCommandId);
+      writeStatus(sessionId, {
+        phase: "done",
+        step: "done",
+        completedAt: Date.now(),
+        shadowedNodes: Array.isArray(result?.shadowedSeqs) ? result.shadowedSeqs.length : 0,
+        shadowedTokens: typeof result?.shadowedTokenCount === "number" ? result.shadowedTokenCount : 0,
+        missingSections: [],
+        retrying: false,
+        writing: false,
+        ...(result === null || result === undefined ? { note: "no compactable range" } : {}),
+      });
+      return result;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      writeStatus(sessionId, {
+        phase: "failed",
+        step: "failed",
+        failedAt: Date.now(),
+        error: message,
+        errorCode: errorCodeOf(error),
+      });
+      throw error;
+    }
+  }
+
   /** Handoff template instead of the stock compaction instruction. */
   async summarize(input, agent, signal) {
+    // Native pressure/overflow compaction runs through this same hook, so the
+    // stock prompt must come back the moment the plugin is switched off.
+    if (!this.handoffEnabled()) return super.summarize(input, agent, signal);
     const latest = agent.session.requestHeader?.()?.config;
     const configured = this.config.summarizationProvider && this.config.summarizationModel
       ? { provider: this.config.summarizationProvider, model: this.config.summarizationModel }
@@ -346,15 +494,14 @@ export default class HandoffCompaction extends BasicCompactionEngine {
       : BUILTIN_INSTRUCTION;
     this.log(`template: ${resolved.source}${resolved.text === undefined ? " (fallback)" : ""}`);
 
-    const assembler = new BlockAssembler();
-    const messages = [
+    const expected = expectedSections(instruction);
+    const baseMessages = [
       ...input.messages,
       Object.freeze({ role: "user", content: [{ type: "text", text: instruction }] }),
     ];
-    const options = {
+    const baseOptions = {
       provider: target.provider,
       model: target.model,
-      messages,
       toolHistory: agent.session.toolHistory(),
       ...(input.tools === undefined ? {} : { tools: [...input.tools] }),
       maxTokens: this.config.maxTokens,
@@ -363,24 +510,141 @@ export default class HandoffCompaction extends BasicCompactionEngine {
       purpose: "compaction",
       ...(signal === undefined ? {} : { signal }),
     };
+    const sessionId = agent.session?.id;
 
-    for await (const chunk of this.ctx.llm.stream(options)) assembler.push(chunk);
-    const error = finishError(assembler.finish);
-    if (error !== undefined) throw error;
+    let combined = "";
+    let rawOutput = [];
+    let usage;
+    let validation = {
+      ok: expected.length === 0,
+      missing: [...expected],
+      truncated: false,
+      endsWithHeading: false,
+      reason: "not attempted",
+    };
+    const attempts = [];
 
-    const rawOutput = assembler.blocks();
-    if (contentHasImage(rawOutput)) throw new LlmError("handoff summary cannot contain image output", "UNSUPPORTED_CONTENT");
-    const summary = rawOutput.filter((block) => block.type === "text");
-    if (!summary.some((block) => block.text.trim().length > 0)) throw new Error("handoff summary produced no text content");
+    let liveTotalTokens;
+    try { liveTotalTokens = this.ctx.tokenMeter.measure(agent.session).totalTokens; } catch { liveTotalTokens = undefined; }
+    writeStatus(sessionId, {
+      phase: "running",
+      step: "summary",
+      summaryAttempt: 1,
+      retrying: false,
+      writing: false,
+      missingSections: [],
+      ...(typeof liveTotalTokens === "number" ? { totalTokens: liveTotalTokens } : {}),
+    });
+
+    for (let attempt = 1; attempt <= MAX_SUMMARY_ATTEMPTS; attempt += 1) {
+      signal?.throwIfAborted?.();
+      const messages = attempt === 1
+        ? baseMessages
+        : attempt === 2
+          ? [
+            ...baseMessages,
+            Object.freeze({ role: "assistant", content: [{ type: "text", text: combined }] }),
+            Object.freeze({ role: "user", content: [{ type: "text", text: continuationInstruction(validation) }] }),
+          ]
+          : [
+            ...baseMessages,
+            Object.freeze({
+              role: "user",
+              content: [{ type: "text", text: rewriteInstruction(validation, this.config.maxTokens) }],
+            }),
+          ];
+
+      const result = await this.runSummaryRequest(baseOptions, messages);
+      const truncatedNow = looksTruncated(result.text);
+      const clean = stripTruncationMarkers(result.text);
+      combined = attempt === 1
+        ? clean
+        : attempt === 2
+          ? mergeSummary(combined, clean)
+          : clean;
+      rawOutput = result.rawOutput;
+      usage = mergeUsage(usage, result.usage);
+      validation = validateSummary(combined, expected);
+      if (truncatedNow) {
+        validation = {
+          ...validation,
+          ok: false,
+          truncated: true,
+          reason: validation.reason.length > 0 ? `${validation.reason}; truncation marker` : "truncation marker",
+        };
+      }
+      attempts.push({
+        attempt,
+        finish: result.finishKind,
+        chars: result.text.length,
+        ok: validation.ok,
+      });
+      if (validation.ok) break;
+      if (attempt < MAX_SUMMARY_ATTEMPTS) {
+        const next = attempt + 1;
+        this.log(`summary incomplete after attempt ${attempt}: ${validation.reason}; ${attempt === 1 ? "continuing" : "rewriting"}`);
+        writeStatus(sessionId, {
+          phase: "running",
+          step: "summary",
+          summaryAttempt: next,
+          retrying: true,
+          writing: next === MAX_SUMMARY_ATTEMPTS,
+          missingSections: validation.missing,
+          summaryChars: combined.length,
+          summaryAttempts: attempts,
+        });
+      }
+    }
+
+    if (!validation.ok) {
+      const error = new Error(`handoff summary incomplete after ${attempts.length} attempt(s): ${validation.reason}`);
+      error.code = "INCOMPLETE_SUMMARY";
+      error.attempts = attempts;
+      throw error;
+    }
+
+    const finalText = combined.trim();
+    if (finalText.length === 0) throw new Error("handoff summary produced no text content");
+    writeStatus(sessionId, {
+      phase: "running",
+      step: "commit",
+      summaryAttempt: attempts.length,
+      retrying: false,
+      writing: false,
+      missingSections: [],
+      summaryChars: finalText.length,
+      summaryAttempts: attempts,
+    });
 
     return {
-      summary,
+      summary: [{ type: "text", text: finalText }],
       rawOutput,
       llmStreamCall: true,
       provider: target.provider,
       model: target.model,
       maxTokens: this.config.maxTokens,
-      ...(assembler.usage === undefined ? {} : { usage: assembler.usage }),
+      ...(usage === undefined ? {} : { usage }),
+    };
+  }
+
+  /** One summary LLM call; max-tokens is returned as a partial, not thrown. */
+  async runSummaryRequest(baseOptions, messages) {
+    const assembler = new BlockAssembler();
+    for await (const chunk of this.ctx.llm.stream({ ...baseOptions, messages })) assembler.push(chunk);
+    const finish = assembler.finish ?? { kind: "stop" };
+    if (finish.kind === "error" || finish.kind === "aborted") {
+      const error = finishError(finish);
+      if (error !== undefined) throw error;
+    }
+    const rawOutput = assembler.blocks();
+    if (contentHasImage(rawOutput)) throw new LlmError("handoff summary cannot contain image output", "UNSUPPORTED_CONTENT");
+    const text = rawOutput.filter((block) => block.type === "text").map((block) => block.text).join("");
+    if (text.trim().length === 0) throw new Error("handoff summary produced no text content");
+    return {
+      rawOutput,
+      text,
+      finishKind: finish.kind,
+      usage: assembler.usage,
     };
   }
 }

package/lib/status.js

@@ -0,0 +1,52 @@
+/**
+ * Per-session compaction status sidecar.
+ *
+ * The engine writes one small JSON file while it prepares, summarizes and
+ * commits a handoff; the UI dock polls it through the companion package's RPC
+ * channel. Kept free of DSH imports so the UI's node half can reuse it.
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const STATUS_DIR = process.env.DSH_HANDOFF_STATUS_DIR || join(homedir(), ".dsh-handoff-compaction", "status");
+const SESSION_ID = /^[A-Za-z0-9_-]{1,128}$/;
+
+/** Absolute status file for a session id, or undefined when the id is unsafe. */
+export function statusFileFor(sessionId) {
+  if (typeof sessionId !== "string" || !SESSION_ID.test(sessionId)) return undefined;
+  return join(STATUS_DIR, `${sessionId}.json`);
+}
+
+/** Latest status for a session, or undefined when absent/unreadable. */
+export function readStatus(sessionId) {
+  const file = statusFileFor(sessionId);
+  if (file === undefined) return undefined;
+  try {
+    const parsed = JSON.parse(readFileSync(file, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Merge one patch into the session status and replace the file atomically.
+ * Returns false when the session id is unsafe or the write failed; status
+ * writes must never break a compaction.
+ */
+export function writeStatus(sessionId, patch) {
+  const file = statusFileFor(sessionId);
+  if (file === undefined || patch === undefined || patch === null) return false;
+  try {
+    mkdirSync(STATUS_DIR, { recursive: true });
+    const previous = readStatus(sessionId) ?? {};
+    const next = { ...previous, ...patch, sessionId, updatedAt: Date.now() };
+    const temp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+    writeFileSync(temp, JSON.stringify(next), "utf8");
+    renameSync(temp, file);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/lib/summary.js

@@ -0,0 +1,147 @@
+/**
+ * Pure completeness checks for the generated handoff document.
+ *
+ * The local models used with DSH sometimes stop early and append a literal
+ * "（截断）" marker (or stop right after a heading) instead of failing the
+ * request. These helpers let the engine treat such output as incomplete,
+ * continue it, or rewrite it before the checkpoint is committed.
+ */
+
+const FENCE = /^\s*(```|~~~)/;
+const HEADING = /^\s*(#{2,3})\s+(.+?)\s*$/;
+
+function normalizeHeading(text) {
+  return String(text ?? "")
+    .replace(/^#{2,3}\s*/, "")
+    .replace(/^\s*\d+[.、)]\s*/, "")
+    .replace(/[*_`]/g, "")
+    .replace(/[\s：:]+$/g, "")
+    .trim();
+}
+
+function headingsIn(text) {
+  const out = [];
+  let fenced = false;
+  for (const line of String(text ?? "").split(/\r?\n/)) {
+    if (FENCE.test(line)) {
+      fenced = !fenced;
+      continue;
+    }
+    if (fenced) continue;
+    const match = HEADING.exec(line);
+    if (match === null) continue;
+    const heading = normalizeHeading(match[2]);
+    if (heading.length > 0 && !out.includes(heading)) out.push(heading);
+  }
+  return out;
+}
+
+/** Section headings the template asks the model to produce. */
+export function expectedSections(templateText) {
+  return headingsIn(templateText);
+}
+
+/** Section headings actually present in a generated summary. */
+export function summarySections(summaryText) {
+  return headingsIn(summaryText);
+}
+
+/** Whether the text ends with a model-generated truncation marker. */
+export function looksTruncated(text) {
+  const tail = String(text ?? "").trimEnd();
+  if (tail.length === 0) return false;
+  if (/[（(]\s*截断\s*[)）]\s*$/.test(tail)) return true;
+  if (/[\[【]\s*截断\s*[\]】]\s*$/.test(tail)) return true;
+  const last = tail.slice(-48);
+  return /(?:输出|回答|摘要|文档|内容|响应)\s*(?:已|被)?\s*截断\s*$/.test(last);
+}
+
+/** Remove literal truncation markers the model wrote about its own output. */
+export function stripTruncationMarkers(text) {
+  return String(text ?? "")
+    .replace(/[…\.]{0,3}\s*[（(]\s*截断\s*[)）]/g, "")
+    .replace(/[…\.]{0,3}\s*[\[【]\s*截断\s*[\]】]/g, "")
+    .trimEnd();
+}
+
+/**
+ * Validate one generated handoff document against the template sections.
+ * `ok` is false when a section is missing, the text ends on a bare heading,
+ * or the model marked its own output as truncated.
+ */
+export function validateSummary(text, expected = []) {
+  const headings = headingsIn(text);
+  const missing = expected.filter(
+    (section) => !headings.some((heading) => heading.includes(section) || section.includes(heading)),
+  );
+  const truncated = looksTruncated(text);
+  const endsWithHeading = /(?:^|\n)\s*#{2,3}\s+[^\n]*\s*$/.test(String(text ?? "").trimEnd());
+  const reasons = [];
+  if (missing.length > 0) reasons.push(`missing sections: ${missing.join(", ")}`);
+  if (truncated) reasons.push("truncation marker");
+  if (endsWithHeading) reasons.push("ends on a heading");
+  return {
+    ok: missing.length === 0 && !truncated && !endsWithHeading,
+    missing,
+    truncated,
+    endsWithHeading,
+    reason: reasons.join("; "),
+  };
+}
+
+function lastHeading(text) {
+  const headings = headingsIn(text);
+  return headings.length === 0 ? undefined : headings[headings.length - 1];
+}
+
+function startsWithHeading(text) {
+  const first = String(text ?? "").trimStart().split(/\r?\n/, 1)[0] ?? "";
+  const match = HEADING.exec(first);
+  return match === null ? undefined : normalizeHeading(match[2]);
+}
+
+/** Join a partial summary and a continuation without duplicating its heading. */
+export function mergeSummary(partial, tail) {
+  const head = String(partial ?? "").trimEnd();
+  const rest = String(tail ?? "").trim();
+  if (head.length === 0) return rest;
+  if (rest.length === 0) return head;
+  const repeated = lastHeading(head);
+  const first = startsWithHeading(rest);
+  if (repeated !== undefined && first !== undefined && repeated === first) {
+    const newline = rest.indexOf("\n");
+    const body = newline === -1 ? "" : rest.slice(newline + 1).trim();
+    return body.length === 0 ? head : `${head}\n${body}`;
+  }
+  if (first !== undefined) return `${head}\n\n${rest}`;
+  const safeBreak = /[。！？.!?；;：:)\]）】]$/.test(head);
+  return safeBreak ? `${head}\n\n${rest}` : `${head}${rest}`;
+}
+
+/** User turn appended after the partial assistant document. */
+export function continuationInstruction(validation) {
+  const missing = validation?.missing ?? [];
+  const lines = [
+    "你刚才写到一半中断了。请从断点继续这份交接文档：",
+    "- 先补完断点处的句子，不要重复已经写过的内容或标题；",
+  ];
+  if (missing.length > 0) {
+    lines.push(`- 然后按模板顺序补完这些缺失小节：${missing.join("、")}；`);
+  } else {
+    lines.push("- 并完成文档剩余部分；");
+  }
+  lines.push("- 只输出 Markdown 正文，不要解释，不要写「（截断）」。");
+  return lines.join("\n");
+}
+
+/** User turn appended when a continuation still does not pass validation. */
+export function rewriteInstruction(validation, maxTokens) {
+  const missing = validation?.missing ?? [];
+  const why = missing.length > 0 ? `缺少这些小节：${missing.join("、")}` : "输出在末尾被截断";
+  return [
+    `上一次的交接文档不完整（${why}）。`,
+    "请重新完整输出整份交接文档，必须包含模板要求的全部小节；",
+    `不要因为长度自行截断，不要写「（截断）」；本任务允许输出到 ${String(maxTokens)} tokens。`,
+    "只输出 Markdown 正文。",
+  ].join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-auto-compaction",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "main": "lib/index.js",
   "exports": {

package/scripts/preset-scope.mjs

@@ -360,7 +360,10 @@ for (const entry of plan) {
       : current === "@deepseek-ai/dsh-compaction-basic" ? "DSH 原生压缩"
       : "未知";
     const selected = entry.selected === undefined ? "" : `\n  勾选: ${entry.selected ? "是（插件）" : "否（原生）"}`;
-    console.log(`${file}\n  当前: ${current}\n  含义: ${kind}${selected}\n  YAML: ${validatePreset(original)}`);
+    const switchLine = readSettings()?.enabled === false
+      ? "\n  开关: 已停用（设置页关闭，运行时压缩交回原生行为）"
+      : "\n  开关: 启用";
+    console.log(`${file}\n  当前: ${current}\n  含义: ${kind}${selected}${switchLine}\n  YAML: ${validatePreset(original)}`);
     continue;
   }
 

package/scripts/row-plugin.yml

@@ -3,7 +3,7 @@
   config:
     thresholdRatio: 0.9
     headroomTokens: 10000
-    maxTokens: 8192
+    maxTokens: 12288
     idleDelayMs: 1500
     dryRun: false
     presetId: lightweight-local