dsh-context-mode 0.3.3 → 0.5.0

package/README.md

@@ -124,7 +124,7 @@ 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
+## Checkpoint transcript and 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
@@ -132,39 +132,20 @@ 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:
+Closing that gap is a **separate product**, not part of this package:
 
-```ts
-import DshContextModeCompaction from 'dsh-context-mode/compaction'
+```sh
+npm install dsh-context-mode-compaction
+npx 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'
-```
+`dsh-context-mode-compaction` supplies the compaction engine that writes the
+transcript and the index; this package supplies the archiver that stores what
+those pointers name, and the `ctx_search` tool that reads it back. The two are
+independent — install both for the full path.
 
-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.
+See [dsh-context-mode-compaction](https://www.npmjs.com/package/dsh-context-mode-compaction)
+for the checkpoint format, the tuning constants, and the preset wiring.
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-context-mode",
-  "version": "0.3.3",
+  "version": "0.5.0",
   "description": "Expose context-mode MCP tools as native DeepSeek Harness tools",
   "keywords": [
     "dsh",
@@ -24,10 +24,6 @@
       "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"
   },
@@ -63,20 +59,13 @@
   },
   "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",

package/lib/types/compaction.d.ts

@@ -1,100 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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

@@ -1,94 +0,0 @@
-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;