dsh-context-mode 0.3.2 → 0.3.3

package/README.md

@@ -124,6 +124,48 @@ node node_modules/dsh-context-mode/scripts/cleanup-injected.mjs --db <path>
 node node_modules/dsh-context-mode/scripts/cleanup-injected.mjs --db <path> --apply    # delete
 ```
 
+## Checkpoint archive index
+
+A checkpoint keeps only a summary of the span it replaces, and the shipped
+checkpoint format has no section for tool output — a long tool result survives
+only as whatever the summarizing model chose to keep. `precompact` files that
+same span into the knowledge base beforehand, but nothing told the model so,
+and a summary that omits a detail reads as if the detail never existed.
+
+This package also exports a compaction engine that closes that gap. It extends
+the shipped `BasicCompactionEngine` and overrides only `summarize()`, appending
+an `## Archive Index` that names the archived sources:
+
+```ts
+import DshContextModeCompaction from 'dsh-context-mode/compaction'
+```
+
+Mount it in place of the shipped backend, inside the isolate group the shipped
+one requires:
+
+```yaml
+- id: compaction
+  name: cordis:group
+  group: true
+  isolate:
+    compaction: true
+    toolResultPruner: true
+  config:
+    - id: compaction-basic
+      name: 'dsh-context-mode/compaction'   # was @deepseek-ai/dsh-compaction-basic
+
+    - id: command-compact
+      name: '@deepseek-ai/dsh-command-compact'
+```
+
+Trigger policy, retention, the transaction bracket, token metering, and
+prefix-cache-aligned replay all stay on the shipped engine — only the returned
+summary text differs. The index is appended to the summary rather than injected
+into the summarization instruction, so the shipped output contract is untouched
+and no model has to follow an amended format. Failing to build the index
+returns the superseded summary unchanged, and restoring the shipped `name` row
+disables the index entirely.
+
 ## Development
 
 ```sh

package/lib/types/compaction.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Compaction backend that appends an archive index to every checkpoint.
+ *
+ * DSH's shipped backend condenses an older span of the conversation into a
+ * summary and lets the raw events fall out of the derived history. The summary
+ * is lossy by design: its instruction fixes the sections a checkpoint may
+ * carry, and tool output has no section of its own, so a long tool result
+ * survives only as whatever the summarizing model chose to keep.
+ *
+ * This plugin's `precompact` listener files the same span into the
+ * context-mode knowledge base first, so the detail still exists and
+ * `ctx_search` can reach it. What it cannot do from outside is tell the model
+ * that — the checkpoint text is written here, inside the engine, and the
+ * shipped engine has no reason to mention a knowledge base it does not know
+ * about. That is the gap this subclass closes.
+ *
+ * Two deliberate choices keep the risk low:
+ *
+ *   - Only `summarize()` is overridden. Trigger policy, retention, the
+ *     bracket-first transaction, token metering, and KV-cache-aligned replay
+ *     all stay on the shipped implementation, so this cannot diverge from the
+ *     behavior the rest of DSH expects.
+ *   - The index is appended to the *returned* summary, never injected into the
+ *     summarization instruction. The summarizing model never sees this text,
+ *     so the shipped output contract ("keep every section, in order") stays
+ *     intact and no model has to be trusted to follow an amended format.
+ *
+ * Nothing here is allowed to fail a compaction: if the index cannot be built,
+ * the superseded summary is returned unchanged.
+ *
+ * @module dsh-context-mode/compaction
+ */
+import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+import { BasicCompactionEngine } from '@deepseek-ai/dsh-compaction-basic';
+/**
+ * The shipped summarization input and result types, derived from the base
+ * class rather than restated.
+ *
+ * The package does not re-export them from its root, and deep-importing its
+ * private `lib/types/summarizer.js` path would break on any internal move.
+ * Deriving from the method signature keeps this module aligned with whatever
+ * the installed version declares, and needs no import of its own.
+ */
+type SummarizeArgs = Parameters<BasicCompactionEngine['summarize']>;
+type SummarizedResult = Awaited<ReturnType<BasicCompactionEngine['summarize']>>;
+/** Session-event shapes this module reads. */
+interface SessionEventLike {
+    readonly type: string;
+    readonly seq?: number;
+    readonly data?: unknown;
+}
+interface SessionLike {
+    readonly id?: string;
+    snapshotEvents(): readonly SessionEventLike[];
+}
+interface AgentLike {
+    readonly session?: SessionLike;
+}
+/**
+ * A compaction engine that names the session archive in each checkpoint.
+ *
+ * Constructed by DSH exactly like the shipped engine it extends, so the row
+ * that mounts it needs no additional wiring.
+ */
+export declare class DshContextModeCompaction extends BasicCompactionEngine {
+    /**
+     * Summarize the replayed region, then append the archive index.
+     *
+     * The index is appended after `super.summarize()` resolves, so the shipped
+     * call — and therefore prefix-cache alignment, token accounting, and the
+     * returned `SummaryResult` envelope — are unchanged.
+     */
+    protected summarize(input: SummarizeArgs[0], agent: SummarizeArgs[1], signal?: SummarizeArgs[2]): Promise<SummarizedResult>;
+}
+/**
+ * Build the archive-index block for one agent's session.
+ *
+ * The source labels are derivable without waiting on the archiver: the
+ * `precompact` listener files each layer under `session/<id>/<layer>`, and the
+ * session id is available here. The index therefore states *where* the detail
+ * lives rather than claiming anything about what it contains.
+ *
+ * @param agent - owner of the session being compacted.
+ * @returns the markdown block, or an empty string when no session is reachable.
+ */
+export declare function buildArchiveIndex(agent: AgentLike): string;
+/**
+ * Append an index block to the text of a summary.
+ *
+ * Only text blocks are touched. A summary may also carry non-text blocks, and
+ * rewriting or dropping those is the shipped engine's business, not this
+ * module's; they are copied through untouched.
+ *
+ * @param summary - the superseded summary blocks.
+ * @param index - the block to append.
+ * @returns new blocks with the index appended to the trailing text.
+ */
+export declare function appendToSummary(summary: readonly ContentBlock[], index: string): ContentBlock[];
+export default DshContextModeCompaction;
+//# sourceMappingURL=compaction.d.ts.map

package/lib/types/compaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction.d.ts","sourceRoot":"","sources":["../../src/compaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAA;AAEzE;;;;;;;;GAQG;AACH,KAAK,aAAa,GAAG,UAAU,CAAC,qBAAqB,CAAC,WAAW,CAAC,CAAC,CAAA;AACnE,KAAK,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,qBAAqB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAA;AAQ/E,8CAA8C;AAC9C,UAAU,gBAAgB;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CACxB;AAED,UAAU,WAAW;IACnB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAA;IACpB,cAAc,IAAI,SAAS,gBAAgB,EAAE,CAAA;CAC9C;AAED,UAAU,SAAS;IACjB,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAA;CAC/B;AAED;;;;;GAKG;AACH,qBAAa,wBAAyB,SAAQ,qBAAqB;IACjE;;;;;;OAMG;cACsB,SAAS,CAChC,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,EACvB,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,EACvB,MAAM,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,GACxB,OAAO,CAAC,gBAAgB,CAAC;CAY7B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAuB1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,KAAK,EAAE,MAAM,GACZ,YAAY,EAAE,CAUhB;AAED,eAAe,wBAAwB,CAAA"}

package/lib/types/compaction.js

@@ -0,0 +1,94 @@
+import { BasicCompactionEngine } from '@deepseek-ai/dsh-compaction-basic';
+/** Heading of the appended section. Kept short; it costs context on every later request. */
+const INDEX_HEADING = '## Archive Index';
+/** Upper bound on the appended section, so a checkpoint can never be grown without limit. */
+const MAX_INDEX_CHARS = 1_200;
+/**
+ * A compaction engine that names the session archive in each checkpoint.
+ *
+ * Constructed by DSH exactly like the shipped engine it extends, so the row
+ * that mounts it needs no additional wiring.
+ */
+export class DshContextModeCompaction extends BasicCompactionEngine {
+    /**
+     * Summarize the replayed region, then append the archive index.
+     *
+     * The index is appended after `super.summarize()` resolves, so the shipped
+     * call — and therefore prefix-cache alignment, token accounting, and the
+     * returned `SummaryResult` envelope — are unchanged.
+     */
+    async summarize(input, agent, signal) {
+        const result = await super.summarize(input, agent, signal);
+        try {
+            const index = buildArchiveIndex(agent);
+            if (index.length === 0)
+                return result;
+            return { ...result, summary: appendToSummary(result.summary, index) };
+        }
+        catch {
+            // An index is an improvement, never a requirement: a failure here must
+            // not turn into a failed compaction.
+            return result;
+        }
+    }
+}
+/**
+ * Build the archive-index block for one agent's session.
+ *
+ * The source labels are derivable without waiting on the archiver: the
+ * `precompact` listener files each layer under `session/<id>/<layer>`, and the
+ * session id is available here. The index therefore states *where* the detail
+ * lives rather than claiming anything about what it contains.
+ *
+ * @param agent - owner of the session being compacted.
+ * @returns the markdown block, or an empty string when no session is reachable.
+ */
+export function buildArchiveIndex(agent) {
+    const session = agent.session;
+    if (session === undefined)
+        return '';
+    const id = session.id;
+    if (typeof id !== 'string' || id.length === 0)
+        return '';
+    const base = `session/${id}`;
+    const lines = [
+        INDEX_HEADING,
+        '',
+        'The raw transcript of this span was archived to the context-mode knowledge',
+        'base before it was condensed, so detail the summary above omits is still',
+        'retrievable with `ctx_search`. Scope each query to one layer by `source`:',
+        '',
+        `- \`source: "${base}/constraint"\` — user messages: requirements, decisions, limits`,
+        `- \`source: "${base}/finding"\` — tool results and stated conclusions`,
+        `- \`source: "${base}/narrative"\` — assistant reasoning and plans`,
+        '',
+        'Search for a concrete token you expect in the original (a command, an error',
+        'string, a path, an identifier) rather than a paraphrase of the question.',
+    ];
+    const block = lines.join('\n');
+    return block.length <= MAX_INDEX_CHARS ? block : `${block.slice(0, MAX_INDEX_CHARS - 1)}…`;
+}
+/**
+ * Append an index block to the text of a summary.
+ *
+ * Only text blocks are touched. A summary may also carry non-text blocks, and
+ * rewriting or dropping those is the shipped engine's business, not this
+ * module's; they are copied through untouched.
+ *
+ * @param summary - the superseded summary blocks.
+ * @param index - the block to append.
+ * @returns new blocks with the index appended to the trailing text.
+ */
+export function appendToSummary(summary, index) {
+    const blocks = summary.map(block => ({ ...block }));
+    for (let position = blocks.length - 1; position >= 0; position -= 1) {
+        const block = blocks[position];
+        if (block.type !== 'text' || typeof block.text !== 'string')
+            continue;
+        blocks[position] = { ...block, text: `${block.text}\n\n${index}` };
+        return blocks;
+    }
+    // A summary with no text block at all: add one rather than dropping the index.
+    return [...blocks, { type: 'text', text: index }];
+}
+export default DshContextModeCompaction;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-context-mode",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Expose context-mode MCP tools as native DeepSeek Harness tools",
   "keywords": [
     "dsh",
@@ -24,6 +24,10 @@
       "types": "./lib/types/index.d.ts",
       "import": "./lib/types/index.js"
     },
+    "./compaction": {
+      "types": "./lib/types/compaction.d.ts",
+      "import": "./lib/types/compaction.js"
+    },
     "./package.json": "./package.json",
     "./cordis.patch.yml": "./cordis.patch.yml"
   },
@@ -59,16 +63,24 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-compaction-basic": "^0.1.5-rc.2",
     "@deepseek-ai/dsh-llm": "^0.1.5-rc.2",
     "@deepseek-ai/dsh-system-prompt": "^0.1.5-rc.2",
     "@deepseek-ai/dsh-tools": "^0.1.5-rc.2"
   },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-compaction-basic": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-agent": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-compaction-basic": "0.1.5-rc.2",
     "@deepseek-ai/dsh-llm": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-skill": "^0.1.5-rc.2",
     "@deepseek-ai/dsh-system-prompt": "^0.1.5-rc.2",
     "@deepseek-ai/dsh-tools": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-skill": "^0.1.5-rc.2",
     "@types/node": "^22.0.0",
     "typescript": "^6.0.3"
   }