dsh-context-mode 0.3.2 → 0.4.0

package/README.md

@@ -124,6 +124,80 @@ 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 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
+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 replaces the lossy summary with the
+conversation itself, plus a pointer to everything it did not carry:
+
+```ts
+import DshContextModeCompaction from 'dsh-context-mode/compaction'
+```
+
+Each checkpoint it writes carries three parts:
+
+| Part | Content |
+| --- | --- |
+| The shipped summary | The eight-section checkpoint, unchanged |
+| `## Conversation Transcript` | user turns kept whole; assistant replies kept head+tail; tool output reduced to one index line each |
+| `## Archive Index` | The `source` labels to search, and how to query them |
+
+Every region that was clipped or dropped leaves a pointer naming the `source`
+holding the original and the `seq` it came from, so the checkpoint says *which*
+event lost detail rather than merely that an archive exists:
+
+```
+## [assistant 447]
+… first 200 chars …
+[... 1581 of 1981 chars elided from seq 447; retrieve with ctx_search(source: "session/<id>/narrative") ...]
+… last 200 chars …
+
+## [tool ctx_execute seq 3424, 29808 chars → search `session/<id>/finding`]
+```
+
+A prior checkpoint is never transcribed forward: its text is already in the
+summary, and copying it would grow the transcript on every 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
+      config:
+        thresholdRatio: 0.8   # compact at 80% of the window
+        retainRatio: 0.1      # keep the newest 10% verbatim
+
+    - id: command-compact
+      name: '@deepseek-ai/dsh-command-compact'
+```
+
+Only `compactRegion` (to capture the span) and `summarize` (to append) differ:
+trigger policy, retention, the transaction bracket, token metering, and
+prefix-cache-aligned replay all stay on the shipped engine. The appendices are
+added to the returned 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 them returns the superseded summary
+unchanged, and restoring the shipped `name` row disables them entirely.
+
+`TRANSCRIPT` and per-entry clipping are tunable from
+`dsh-context-mode/transcript`: `USER_CLIP_AT` / `USER_CLIP_KEEP` for long user
+turns, `ASSISTANT_KEEP` for assistant head+tail, and `MAX_TRANSCRIPT_CHARS` for
+the whole body.
+
 ## Development
 
 ```sh

package/lib/types/compaction.d.ts

@@ -0,0 +1,115 @@
+/**
+ * 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[];
+    /** Current surface node sequence; the compacted span is a slice of it. */
+    readonly surface?: {
+        readonly nodes: readonly number[];
+    };
+    /** One event by sequence number, or undefined when absent. */
+    eventAt?(seq: number): SessionEventLike | undefined;
+}
+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 {
+    #private;
+    /** Capture the compacted range for the summarizer, then run the shipped path. */
+    compactRegion(...args: Parameters<BasicCompactionEngine['compactRegion']>): ReturnType<BasicCompactionEngine['compactRegion']>;
+    /**
+     * Summarize the replayed region, then append the transcript and archive index.
+     *
+     * The shipped call runs first and unmodified, so 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;
+/**
+ * Build the archive-index block for one archive source root.
+ *
+ * @param base - archive source root, e.g. `session/<id>`.
+ * @returns the markdown block.
+ */
+export declare function buildArchiveIndexFromBase(base: string): 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;AAQzE;;;;;;;;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;IAC7C,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAA;IACxD,8DAA8D;IAC9D,OAAO,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAAA;CACpD;AAED,UAAU,SAAS;IACjB,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAA;CAC/B;AAQD;;;;;GAKG;AACH,qBAAa,wBAAyB,SAAQ,qBAAqB;;IAWjE,iFAAiF;IAClE,aAAa,CAC1B,GAAG,IAAI,EAAE,UAAU,CAAC,qBAAqB,CAAC,eAAe,CAAC,CAAC,GAC1D,UAAU,CAAC,qBAAqB,CAAC,eAAe,CAAC,CAAC;IAUrD;;;;;OAKG;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;CAe7B;AAqDD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAG1D;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAiB9D;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,169 @@
+import { BasicCompactionEngine } from '@deepseek-ai/dsh-compaction-basic';
+import { MAX_TRANSCRIPT_CHARS, buildTranscript, renderTranscript, } from './transcript.js';
+/** 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 {
+    /**
+     * Surface range of the compaction in flight.
+     *
+     * `summarize()` receives only the replayed messages, not the sequence
+     * numbers behind them, so the range is captured here — at the one seam that
+     * knows it — and read back inside `summarize()`. Only two numbers are
+     * stashed; the shipped transaction, selection, and validation are untouched.
+     */
+    #range;
+    /** Capture the compacted range for the summarizer, then run the shipped path. */
+    async compactRegion(...args) {
+        this.#range = { start: args[0], end: args[1] };
+        try {
+            return await super.compactRegion(...args);
+        }
+        finally {
+            // Cleared unconditionally: a stale range must never label a later summary.
+            this.#range = undefined;
+        }
+    }
+    /**
+     * Summarize the replayed region, then append the transcript and archive index.
+     *
+     * The shipped call runs first and unmodified, so 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 session = agent.session;
+            const base = archiveBase(session);
+            if (base === undefined)
+                return result;
+            const appended = buildAppendices(session, this.#range, base);
+            if (appended.length === 0)
+                return result;
+            return { ...result, summary: appendToSummary(result.summary, appended.join('\n\n')) };
+        }
+        catch {
+            // An appendix is an improvement, never a requirement: a failure here must
+            // not turn into a failed compaction.
+            return result;
+        }
+    }
+}
+/** Archive source root for one session, or undefined when it cannot be named. */
+function archiveBase(session) {
+    const id = session?.id;
+    if (typeof id !== 'string' || id.length === 0)
+        return undefined;
+    return `session/${id}`;
+}
+/**
+ * Build the transcript and index blocks appended below the summary.
+ *
+ * The compacted events are resolved from the captured range against the
+ * session's own surface, so a range that no longer matches yields no
+ * transcript rather than a mislabelled one.
+ */
+function buildAppendices(session, range, base) {
+    const blocks = [];
+    const events = compactedEvents(session, range);
+    if (events.length > 0) {
+        const lines = buildTranscript(events, { base });
+        const body = renderTranscript(lines, MAX_TRANSCRIPT_CHARS);
+        if (body.length > 0)
+            blocks.push(`## Conversation Transcript\n\n${body}`);
+    }
+    const index = buildArchiveIndexFromBase(base);
+    if (index.length > 0)
+        blocks.push(index);
+    return blocks;
+}
+/** Resolve the compacted events for a captured surface range. */
+function compactedEvents(session, range) {
+    if (session === undefined)
+        return [];
+    const eventAt = session.eventAt;
+    const nodes = session.surface?.nodes;
+    // Without a range or a live surface, fall back to nothing rather than
+    // guessing: a transcript of the wrong span is worse than no transcript.
+    if (range === undefined || eventAt === undefined || nodes === undefined)
+        return [];
+    const out = [];
+    for (const seq of nodes) {
+        if (seq < range.start || seq > range.end)
+            continue;
+        const event = eventAt.call(session, seq);
+        if (event !== undefined)
+            out.push(event);
+    }
+    return out;
+}
+/**
+ * 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 base = archiveBase(agent.session);
+    return base === undefined ? '' : buildArchiveIndexFromBase(base);
+}
+/**
+ * Build the archive-index block for one archive source root.
+ *
+ * @param base - archive source root, e.g. `session/<id>`.
+ * @returns the markdown block.
+ */
+export function buildArchiveIndexFromBase(base) {
+    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/lib/types/transcript.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Conversation transcript construction for compaction checkpoints.
+ *
+ * DSH's shipped checkpoint is a lossy summary: its instruction fixes eight
+ * sections, tool output has no section of its own, and the summarizer keeps
+ * whatever prose it chose. In practice a compacted span loses most of what was
+ * actually said.
+ *
+ * This module rebuilds the *conversation* from the compacted events instead of
+ * asking a model to retell it:
+ *
+ *   user/message       kept whole — a requirement is a requirement. A very long
+ *                      one is clipped head+tail with an archive pointer.
+ *   assistant/message  head and tail only; the middle is archived and reachable.
+ *   tool/result        never copied. One index line names the tool, its size,
+ *                      and the archive source that holds the output.
+ *
+ * Every clipped or dropped region leaves a pointer naming the `source` to
+ * search and the `seq` it came from, so the checkpoint says *which* event lost
+ * detail rather than merely that an archive exists.
+ *
+ * A prior checkpoint is never transcribed: its own text is already in the
+ * summary, and copying it forward would make the transcript grow without bound
+ * on every compaction.
+ *
+ * @module dsh-context-mode/transcript
+ */
+/** Event shapes this module reads. Mirrors the session log. */
+export interface TranscriptEventLike {
+    readonly type: string;
+    readonly seq?: number;
+    readonly data?: unknown;
+}
+/** Head and tail kept for a user message above the clip threshold, in characters. */
+export declare const USER_CLIP_AT = 1000;
+export declare const USER_CLIP_KEEP = 500;
+/** Head and tail kept for every assistant message, in characters. */
+export declare const ASSISTANT_KEEP = 200;
+/** Upper bound on the whole transcript, so one checkpoint cannot grow without limit. */
+export declare const MAX_TRANSCRIPT_CHARS = 400000;
+/** One rendered transcript entry. */
+export interface TranscriptLine {
+    readonly kind: 'user' | 'assistant' | 'tool';
+    readonly seq: number;
+    readonly text: string;
+    /** Characters in the source event before any clipping. */
+    readonly sourceChars: number;
+}
+/** Options controlling how much of each event survives into the transcript. */
+export interface TranscriptOptions {
+    /** Archive source root, e.g. `session/<id>`. */
+    readonly base: string;
+    /** Include assistant head/tail entries. Defaults to true. */
+    readonly keepAssistant?: boolean;
+}
+/**
+ * Whether an event is a checkpoint written by a previous compaction.
+ *
+ * Matched on `source` when the event still carries it, and on the checkpoint
+ * preamble otherwise: a compacted replacement message is replayed back through
+ * this module as an ordinary `user/message`, so the structural marker is not
+ * always present by the time the text is read.
+ */
+export declare function isCheckpointEvent(event: TranscriptEventLike): boolean;
+/**
+ * Build the transcript for a compacted span.
+ *
+ * @param events - the compacted events, in session order.
+ * @param options - archive root and assistant policy.
+ * @returns the rendered lines, oldest first.
+ */
+export declare function buildTranscript(events: readonly TranscriptEventLike[], options: TranscriptOptions): TranscriptLine[];
+/**
+ * The archive pointer left where content was clipped.
+ *
+ * @param total - characters in the source event.
+ * @param dropped - characters not carried into the transcript.
+ * @param base - archive source root.
+ * @param layer - archive layer holding the original.
+ * @param seq - the source event's sequence number.
+ * @returns the model-facing notice.
+ */
+export declare function clipNotice(total: string, dropped: string, base: string, layer: string, seq: number): string;
+/**
+ * Render transcript lines into one text body, stopping at the size bound.
+ *
+ * The bound is enforced from the end: the newest entries matter most to a
+ * resuming model, so an over-long transcript keeps its tail and reports how
+ * many older entries were dropped.
+ *
+ * @param lines - transcript lines in session order.
+ * @param maxChars - upper bound on the rendered body.
+ * @returns the rendered body.
+ */
+export declare function renderTranscript(lines: readonly TranscriptLine[], maxChars: number): string;
+//# sourceMappingURL=transcript.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transcript.d.ts","sourceRoot":"","sources":["../../src/transcript.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,+DAA+D;AAC/D,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CACxB;AAMD,qFAAqF;AACrF,eAAO,MAAM,YAAY,OAAQ,CAAA;AACjC,eAAO,MAAM,cAAc,MAAM,CAAA;AAEjC,qEAAqE;AACrE,eAAO,MAAM,cAAc,MAAM,CAAA;AAKjC,wFAAwF;AACxF,eAAO,MAAM,oBAAoB,SAAU,CAAA;AAK3C,qCAAqC;AACrC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,MAAM,CAAA;IAC5C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,0DAA0D;IAC1D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAED,+EAA+E;AAC/E,MAAM,WAAW,iBAAiB;IAChC,gDAAgD;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,6DAA6D;IAC7D,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAA;CACjC;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAIrE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,mBAAmB,EAAE,EACtC,OAAO,EAAE,iBAAiB,GACzB,cAAc,EAAE,CAQlB;AAqID;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,GACV,MAAM,CAKR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAa3F"}

package/lib/types/transcript.js

@@ -0,0 +1,325 @@
+/**
+ * Conversation transcript construction for compaction checkpoints.
+ *
+ * DSH's shipped checkpoint is a lossy summary: its instruction fixes eight
+ * sections, tool output has no section of its own, and the summarizer keeps
+ * whatever prose it chose. In practice a compacted span loses most of what was
+ * actually said.
+ *
+ * This module rebuilds the *conversation* from the compacted events instead of
+ * asking a model to retell it:
+ *
+ *   user/message       kept whole — a requirement is a requirement. A very long
+ *                      one is clipped head+tail with an archive pointer.
+ *   assistant/message  head and tail only; the middle is archived and reachable.
+ *   tool/result        never copied. One index line names the tool, its size,
+ *                      and the archive source that holds the output.
+ *
+ * Every clipped or dropped region leaves a pointer naming the `source` to
+ * search and the `seq` it came from, so the checkpoint says *which* event lost
+ * detail rather than merely that an archive exists.
+ *
+ * A prior checkpoint is never transcribed: its own text is already in the
+ * summary, and copying it forward would make the transcript grow without bound
+ * on every compaction.
+ *
+ * @module dsh-context-mode/transcript
+ */
+/** Layer names used in the archive source label. Mirrors `precompact`'s LAYERS. */
+const LAYER_CONSTRAINT = 'constraint';
+const LAYER_FINDING = 'finding';
+/** Head and tail kept for a user message above the clip threshold, in characters. */
+export const USER_CLIP_AT = 1_000;
+export const USER_CLIP_KEEP = 500;
+/** Head and tail kept for every assistant message, in characters. */
+export const ASSISTANT_KEEP = 200;
+/** Assistant messages shorter than this are kept whole rather than split. */
+const ASSISTANT_MIN_SPLIT = ASSISTANT_KEEP * 2;
+/** Upper bound on the whole transcript, so one checkpoint cannot grow without limit. */
+export const MAX_TRANSCRIPT_CHARS = 400_000;
+/** The tag the shipped engine uses; its presence marks a prior checkpoint. */
+const CHECKPOINT_MARKER = 'This is an automatically generated checkpoint';
+/**
+ * Whether an event is a checkpoint written by a previous compaction.
+ *
+ * Matched on `source` when the event still carries it, and on the checkpoint
+ * preamble otherwise: a compacted replacement message is replayed back through
+ * this module as an ordinary `user/message`, so the structural marker is not
+ * always present by the time the text is read.
+ */
+export function isCheckpointEvent(event) {
+    const source = sourceOf(event);
+    if (source !== undefined && source.kind === 'plugin' && source.plugin === 'compact')
+        return true;
+    return messageText(event).includes(CHECKPOINT_MARKER);
+}
+/**
+ * Build the transcript for a compacted span.
+ *
+ * @param events - the compacted events, in session order.
+ * @param options - archive root and assistant policy.
+ * @returns the rendered lines, oldest first.
+ */
+export function buildTranscript(events, options) {
+    const names = toolNames(events);
+    const lines = [];
+    for (const event of events) {
+        const line = transcriptLine(event, options, names);
+        if (line !== undefined)
+            lines.push(line);
+    }
+    return lines;
+}
+/**
+ * Map each tool-call id to its tool name.
+ *
+ * A tool call is not a surface event of its own: it is a `tool-call` content
+ * block inside an `assistant/message`, which is why the compacted span holds
+ * no `tool/call` events at all. The result answers it by id, so the pairing is
+ * collected from assistant blocks up front and looked up while rendering.
+ */
+function toolNames(events) {
+    const names = new Map();
+    for (const event of events) {
+        if (event.type !== 'assistant/message')
+            continue;
+        const data = asRecord(event.data);
+        const message = asRecord(data?.message) ?? data;
+        const content = message?.content;
+        if (!Array.isArray(content))
+            continue;
+        for (const block of content) {
+            if (block === null || typeof block !== 'object')
+                continue;
+            const record = block;
+            if (record.type !== 'tool-call')
+                continue;
+            // An assistant tool-call block carries `id`; its paired result carries
+            // the same value as `toolCallId`, so both spellings are accepted.
+            const id = typeof record.id === 'string'
+                ? record.id
+                : typeof record.toolCallId === 'string' ? record.toolCallId : undefined;
+            if (id === undefined)
+                continue;
+            const name = typeof record.name === 'string' ? record.name : undefined;
+            if (name !== undefined && name.length > 0)
+                names.set(id, name);
+        }
+    }
+    return names;
+}
+/** Render one event into a transcript line, or undefined when it contributes nothing. */
+function transcriptLine(event, options, names) {
+    const seq = typeof event.seq === 'number' ? event.seq : -1;
+    if (event.type === 'tool/result')
+        return toolLine(event, seq, options, names);
+    // A prior checkpoint carries the previous summary; transcribing it would
+    // duplicate the current summary and grow without bound across compactions.
+    if (event.type === 'user/message') {
+        if (isCheckpointEvent(event))
+            return undefined;
+        if (isInjected(event))
+            return undefined;
+        return userLine(event, seq, options);
+    }
+    if (event.type === 'assistant/message') {
+        if (options.keepAssistant === false)
+            return undefined;
+        return assistantLine(event, seq, options);
+    }
+    return undefined;
+}
+/** A user message is kept whole unless it is long, then clipped head and tail. */
+function userLine(event, seq, options) {
+    const text = messageText(event).replace(/\s+/g, ' ').trim();
+    if (text.length === 0)
+        return undefined;
+    const source = `session/<id>/${LAYER_CONSTRAINT}`;
+    if (text.length <= USER_CLIP_AT) {
+        return { kind: 'user', seq, text: `## [user ${seq}]\n${text}`, sourceChars: text.length };
+    }
+    const head = text.slice(0, USER_CLIP_KEEP);
+    const tail = text.slice(-USER_CLIP_KEEP);
+    const dropped = text.length - head.length - tail.length;
+    return {
+        kind: 'user',
+        seq,
+        sourceChars: text.length,
+        text: [
+            `## [user ${seq}]`,
+            head,
+            clipNotice(`${text.length}`, `${dropped}`, options.base, LAYER_CONSTRAINT, seq),
+            tail,
+        ].join('\n'),
+    };
+}
+/** An assistant message keeps its head and tail; the middle stays in the archive. */
+function assistantLine(event, seq, options) {
+    const text = messageText(event).replace(/\s+/g, ' ').trim();
+    if (text.length === 0)
+        return undefined;
+    if (text.length <= ASSISTANT_MIN_SPLIT) {
+        return { kind: 'assistant', seq, text: `## [assistant ${seq}]\n${text}`, sourceChars: text.length };
+    }
+    const head = text.slice(0, ASSISTANT_KEEP);
+    const tail = text.slice(-ASSISTANT_KEEP);
+    const dropped = text.length - head.length - tail.length;
+    return {
+        kind: 'assistant',
+        seq,
+        sourceChars: text.length,
+        text: [
+            `## [assistant ${seq}]`,
+            head,
+            clipNotice(`${text.length}`, `${dropped}`, options.base, LAYER_FINDING, seq),
+            tail,
+        ].join('\n'),
+    };
+}
+/** Tool output is never copied: one line names the call and where its output lives. */
+function toolLine(event, seq, options, names) {
+    const data = asRecord(event.data);
+    const message = asRecord(data?.message) ?? data;
+    const callId = firstCallId(message?.content);
+    const name = toolNameFor(data, callId, names);
+    const chars = messageText(event).length;
+    return {
+        kind: 'tool',
+        seq,
+        sourceChars: chars,
+        text: `## [tool ${name} seq ${seq}, ${chars} chars \u2192 search \`${options.base}/${LAYER_FINDING}\`]`,
+    };
+}
+/**
+ * The archive pointer left where content was clipped.
+ *
+ * @param total - characters in the source event.
+ * @param dropped - characters not carried into the transcript.
+ * @param base - archive source root.
+ * @param layer - archive layer holding the original.
+ * @param seq - the source event's sequence number.
+ * @returns the model-facing notice.
+ */
+export function clipNotice(total, dropped, base, layer, seq) {
+    return (`[... ${dropped} of ${total} chars elided from seq ${seq}; ` +
+        `retrieve with ctx_search(source: "${base}/${layer}") ...]`);
+}
+/**
+ * Render transcript lines into one text body, stopping at the size bound.
+ *
+ * The bound is enforced from the end: the newest entries matter most to a
+ * resuming model, so an over-long transcript keeps its tail and reports how
+ * many older entries were dropped.
+ *
+ * @param lines - transcript lines in session order.
+ * @param maxChars - upper bound on the rendered body.
+ * @returns the rendered body.
+ */
+export function renderTranscript(lines, maxChars) {
+    const rendered = lines.map(line => line.text);
+    let total = rendered.reduce((sum, text) => sum + text.length + 2, 0);
+    if (total <= maxChars)
+        return rendered.join('\n\n');
+    // Drop from the oldest until the body fits, then say how many were dropped.
+    let first = 0;
+    while (first < rendered.length && total > maxChars) {
+        total -= rendered[first].length + 2;
+        first += 1;
+    }
+    const droppedCount = first;
+    const notice = `[... ${droppedCount} older transcript entries elided; the archived span is searchable via the archive index below ...]`;
+    return [notice, ...rendered.slice(first)].join('\n\n');
+}
+/** Text of a message-shaped event, reading nested tool-result content too. */
+function messageText(event) {
+    const data = asRecord(event.data);
+    if (data === undefined)
+        return '';
+    if (event.type === 'tool/call') {
+        const name = typeof data.name === 'string' ? data.name : '';
+        const args = typeof data.arguments === 'string' ? data.arguments : '';
+        return name.length === 0 ? '' : `${name} ${args}`.trim();
+    }
+    const message = asRecord(data.message) ?? data;
+    return blocksToText(message?.content);
+}
+/** Flatten a content value (string, block array, or tool-result envelope) to text. */
+function blocksToText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    const parts = [];
+    for (const block of content) {
+        if (block === null || typeof block !== 'object')
+            continue;
+        const record = block;
+        if (record.type === 'text' && typeof record.text === 'string') {
+            parts.push(record.text);
+            continue;
+        }
+        // tool/result wraps its payload one level down.
+        if (Array.isArray(record.content)) {
+            const inner = blocksToText(record.content);
+            if (inner.length > 0)
+                parts.push(inner);
+        }
+    }
+    return parts.join('\n');
+}
+/** First tool-call id found in a tool-result content value. */
+function firstCallId(content) {
+    if (!Array.isArray(content))
+        return undefined;
+    for (const block of content) {
+        if (block === null || typeof block !== 'object')
+            continue;
+        const record = block;
+        if (typeof record.toolCallId === 'string')
+            return record.toolCallId;
+    }
+    return undefined;
+}
+/** The tool name a result belongs to, resolved from its paired call. */
+function toolNameFor(data, callId, names) {
+    if (data !== undefined && typeof data.name === 'string' && data.name.length > 0)
+        return data.name;
+    if (callId === undefined)
+        return 'tool';
+    const paired = names.get(callId);
+    if (paired !== undefined)
+        return paired;
+    // The call may sit outside the compacted span; name the result by its leading
+    // id segment rather than silently labelling every such line "tool".
+    const head = callId.split('|')[0];
+    return head.length > 0 ? head : 'tool';
+}
+/** Whether a user message is harness-injected context rather than a real turn. */
+function isInjected(event) {
+    const text = messageText(event).trimStart();
+    return (text.startsWith('<current_runtime_context') ||
+        text.startsWith('<active_memory') ||
+        text.startsWith('<system-reminder') ||
+        text.startsWith('<resume_snapshot') ||
+        text.startsWith('Current runtime context') ||
+        text.startsWith('The available skill catalog changed'));
+}
+/** The `source` record of a message-shaped event, when present. */
+function sourceOf(event) {
+    const data = asRecord(event.data);
+    if (data === undefined)
+        return undefined;
+    const message = asRecord(data.message);
+    const source = asRecord(message?.source) ?? asRecord(data.source);
+    if (source === undefined)
+        return undefined;
+    return {
+        kind: typeof source.kind === 'string' ? source.kind : undefined,
+        plugin: typeof source.plugin === 'string' ? source.plugin : undefined,
+    };
+}
+function asRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-context-mode",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Expose context-mode MCP tools as native DeepSeek Harness tools",
   "keywords": [
     "dsh",
@@ -24,6 +24,14 @@
       "types": "./lib/types/index.d.ts",
       "import": "./lib/types/index.js"
     },
+    "./compaction": {
+      "types": "./lib/types/compaction.d.ts",
+      "import": "./lib/types/compaction.js"
+    },
+    "./transcript": {
+      "types": "./lib/types/transcript.d.ts",
+      "import": "./lib/types/transcript.js"
+    },
     "./package.json": "./package.json",
     "./cordis.patch.yml": "./cordis.patch.yml"
   },
@@ -59,16 +67,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"
   }