@better-than-coca/dsh-session-handoff 0.0.0-stage → 0.5.5

package/lib/pressure.js

@@ -0,0 +1,46 @@
+/**
+ * Context pressure reading.
+ *
+ * The host already folds prompt-side pressure into the `contextPressure`
+ * session projection (see @deepseek-ai/dsh-token-meter), so this plugin reads
+ * that projection instead of re-pricing the surface itself. When the
+ * projection is unavailable the plugin stays silent rather than guessing.
+ */
+
+/**
+ * Read the current pressure of one session.
+ * @param ctx - host context exposing `sessionProjections`.
+ * @param session - session to measure.
+ * @returns `{ used, window, ratio }` or `null` when unmeasurable.
+ */
+export function readPressure(ctx, session) {
+    if (session === undefined || session === null) return null;
+    const projections = ctx.get('sessionProjections');
+    if (projections === undefined || typeof projections.snapshot !== 'function') return null;
+    let snapshot;
+    try {
+        snapshot = projections.snapshot(session);
+    } catch {
+        return null;
+    }
+    const pressure = snapshot?.values?.contextPressure;
+    if (pressure === undefined || pressure === null) return null;
+    const window = pressure.contextWindow;
+    if (!Number.isFinite(window) || window <= 0) return null;
+    const used = Number.isFinite(pressure.projectedTokens)
+        ? pressure.projectedTokens
+        : pressure.pressureTokens;
+    if (!Number.isFinite(used) || used <= 0) return null;
+    return { used, window, ratio: used / window };
+}
+
+/**
+ * Human-readable pressure line used by tool output and notices.
+ * @param reading - result of {@link readPressure}.
+ * @returns compact text such as `62.4% (624k / 1000k)`.
+ */
+export function formatPressure(reading) {
+    if (reading === null) return 'unavailable';
+    const percent = (reading.ratio * 100).toFixed(1);
+    return percent + '% (' + Math.round(reading.used / 1000) + 'k / ' + Math.round(reading.window / 1000) + 'k)';
+}

package/lib/route-card.js

@@ -0,0 +1,130 @@
+/**
+ * Route card for a handed-off session.
+ *
+ * The child starts from one checkpoint and nothing else: the parent's raw
+ * conversation is not copied into it. Whether the model may answer from the
+ * checkpoint alone depends on how much was compressed into how little text, so
+ * the card is graded by the measured compression ratio.
+ */
+
+import { sessionEvents } from './history.js';
+
+/**
+ * Trust line: at or below this ratio the checkpoint carried every fact the quiz
+ * asked for (measured 28.6:1).
+ */
+export const TRUST_RATIO = 30;
+/**
+ * Hard line: above this ratio concrete values start colliding or vanishing
+ * (measured 177:1 / 231:1 kept only topic words).
+ */
+export const STRONG_RATIO = 80;
+
+/**
+ * Count the checkpoint's own tokens, never the invisible ones.
+ *
+ * `usage.outputTokens` includes the reasoning block that never reaches the
+ * checkpoint (a measured run reported 3312 while the text was 3041), so using it
+ * raw understates the ratio and makes the card over-trust a skeleton summary.
+ * The character fallback deliberately errs towards a HIGHER ratio: under-counting
+ * tokens can only make the card more cautious.
+ * @param text - checkpoint text.
+ * @param usage - provider usage report, when available.
+ * @returns estimated checkpoint token count, at least 1.
+ */
+export function summaryTokensOf(text, usage) {
+    const chars = typeof text === 'string' ? text.length : 0;
+    const reported = Number(usage?.outputTokens);
+    const reasoning = Number(usage?.reasoningTokens);
+    const textTokens = Number.isFinite(reported) && reported > 0
+        ? reported - (Number.isFinite(reasoning) && reasoning > 0 ? reasoning : 0)
+        : 0;
+    if (textTokens > 0) return Math.round(textTokens);
+    return Math.max(1, Math.round(chars / 2.6));
+}
+
+function summaryText(data) {
+    const summary = data?.summary;
+    if (Array.isArray(summary)) {
+        return summary.map((block) => (typeof block?.text === 'string' ? block.text : '')).join('\n');
+    }
+    return typeof summary === 'string' ? summary : '';
+}
+
+/**
+ * Measure the newest checkpoint in a session log.
+ * Kept for sessions compacted in place (the pre-0.3 fork path); a genuine
+ * handoff child has no checkpoint of its own and passes stats in instead.
+ * @param session - session whose own log is inspected.
+ * @returns tokens/text of the summary and the input it replaced, or null.
+ */
+export function compressionStats(session) {
+    const events = sessionEvents(session);
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+        const event = events[index];
+        if (event?.type !== 'compaction/summary') continue;
+        const text = summaryText(event.data).trim();
+        if (text === '') return null;
+        const summaryTokens = summaryTokensOf(text, event.data?.usage);
+        const shadowed = Number(event.data?.shadowedTokenCount ?? 0);
+        return { chars: text.length, summaryTokens, shadowed, ratio: shadowed / summaryTokens };
+    }
+    return null;
+}
+
+/**
+ * Build the first-turn route card for a legacy fork child.
+ *
+ * Sessions created by the pre-0.3 fork path copied the parent's events into
+ * themselves, so their own log IS the archive. Telling such a session to read a
+ * parent record would send it to a file that does not exist.
+ * @param session - the forked session.
+ * @returns Markdown-ish text for a plugin message.
+ */
+export function forkCard(session) {
+    const stats = compressionStats(session);
+    const lines = [
+        '[dsh-session-handoff] 本会话是旧版 fork 出来的会话：父会话的原始事件已经复制进本会话自己的日志。'
+    ];
+    if (stats !== null) {
+        lines.push('交接压缩比 ' + Math.round(stats.ratio) + ':1（' + stats.shadowed + ' tokens 压成 ' + stats.summaryTokens + ' tokens）；上下文里只有摘要 + 近期原文。');
+    }
+    lines.push('需要旧细节时调用 handoff_history({ query: "关键词" })——默认 source 就是本会话，原文在这里。');
+    return lines.join('\n');
+}
+
+/**
+ * Build the first-turn route card for a handed-off session.
+ * @param session - the handed-off session.
+ * @param stats - handoff measurement from the child's record; falls back to a
+ *   checkpoint found in the session's own log.
+ * @returns Markdown-ish text for a plugin message.
+ */
+export function routeCard(session, stats) {
+    const resolved = stats === undefined || stats === null ? compressionStats(session) : stats;
+    const parent = typeof resolved?.parentSession === 'string'
+        ? resolved.parentSession
+        : typeof session?.header?.parentSession === 'string' ? session.header.parentSession : undefined;
+    const lines = [
+        parent === undefined
+            ? '[dsh-session-handoff] 本会话是从旧会话交接出来的新会话，上下文只有下面这份摘要。'
+            : '[dsh-session-handoff] 本会话是从 session ' + parent + ' 交接出来的新会话，上下文只有下面这份摘要。',
+        '旧会话的完整对话不在本会话里，仍原样保存在它的日志中，可以只读检索。'
+    ];
+    if (resolved === null) {
+        lines.push('需要旧细节时调用 handoff_history({ query: "关键词", source: "parent" }) 检索原文。');
+        return lines.join('\n');
+    }
+    const detail = Math.round(resolved.ratio) + ':1（' + resolved.shadowed + ' tokens 压成 ' + resolved.summaryTokens + ' tokens）';
+    if (resolved.ratio > STRONG_RATIO) {
+        lines.push('交接压缩比 ' + detail + '，摘要只剩骨架。');
+        lines.push('硬性要求：函数名、常量值、错误码、文件路径这类具体事实，必须先 handoff_history({ query, source: "parent" }) 查到原文再回答，禁止凭记忆。');
+    } else if (resolved.ratio > TRUST_RATIO) {
+        lines.push('交接压缩比 ' + detail + '，摘要保住了大部分事实，但丢掉了「事实属于哪一条/哪一份」这类归属信息。');
+        lines.push('具体事实可以照摘要直接回答；涉及出处归属、逐字引用、编号对应时，先用 handoff_history({ query, source: "parent" }) 核对。');
+    } else {
+        lines.push('交接压缩比 ' + detail + '，摘要保留了主要细节。');
+        lines.push('摘要能直接回答的先答；只有涉及具体数值或原文措辞且不确定时，才用 handoff_history({ query, source: "parent" }) 核对。');
+    }
+    return lines.join('\n');
+}

package/lib/settings.js

@@ -0,0 +1,155 @@
+/**
+ * Operator settings written from the browser panel.
+ *
+ * The profile patch (cordis.patch.yml) stays the authoritative installed
+ * configuration; this module owns only the handful of knobs the panel exposes,
+ * and stores them beside the handoff records as one small JSON file.
+ *
+ * Precedence at load time: DEFAULTS < profile patch < settings.json. Deleting
+ * the file therefore restores exactly what the patch says, which is the whole
+ * point of keeping it separate: the plugin still never rewrites a host
+ * configuration file.
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { DEFAULTS } from './config.js';
+import { handoffRoot } from './archive.js';
+
+const MINUTE = 60 * 1000;
+
+/**
+ * The controls the browser panel draws, in display order.
+ *
+ * This array is the single source of truth for the panel: the browser half
+ * renders whatever it receives from the Host instead of hard-coding limits, so
+ * the two halves cannot drift.
+ */
+export const CONTROLS = Object.freeze([
+    Object.freeze({ key: 'mode', kind: 'enum', options: Object.freeze(['ask', 'auto', 'off']), fallback: DEFAULTS.mode }),
+    Object.freeze({ key: 'askRatio', kind: 'ratio', min: 0.3, max: 0.9, step: 0.05, fallback: DEFAULTS.askRatio }),
+    Object.freeze({ key: 'autoRatio', kind: 'ratio', min: 0.5, max: 0.95, step: 0.05, fallback: DEFAULTS.autoRatio }),
+    Object.freeze({ key: 'noticeCooldownMs', kind: 'duration', min: MINUTE, max: 60 * MINUTE, step: MINUTE, fallback: DEFAULTS.noticeCooldownMs }),
+    Object.freeze({ key: 'dryRun', kind: 'boolean', fallback: DEFAULTS.dryRun }),
+    Object.freeze({ key: 'maxHandoffsPerSession', kind: 'count', min: 1, max: 5, fallback: DEFAULTS.maxHandoffsPerSession }),
+    Object.freeze({ key: 'includeHistoryTool', kind: 'boolean', fallback: DEFAULTS.includeHistoryTool }),
+    Object.freeze({ key: 'autoOpenSession', kind: 'boolean', fallback: DEFAULTS.autoOpenSession })
+]);
+
+const CONTROL_KEYS = new Set(CONTROLS.map(control => control.key));
+
+/** The file holding panel edits, beside the handoff records. */
+export function settingsPath() {
+    return join(dirname(handoffRoot()), 'dsh-session-handoff', 'settings.json');
+}
+
+/**
+ * Coerce one incoming value to its control's domain.
+ * @param control - the control declaration.
+ * @param value - raw incoming value.
+ * @returns the accepted value, or undefined when unacceptable.
+ */
+function accept(control, value) {
+    if (control.kind === 'boolean') return typeof value === 'boolean' ? value : undefined;
+    if (control.kind === 'enum') return control.options.includes(value) ? value : undefined;
+    if (typeof value !== 'number' || !Number.isFinite(value)) return undefined;
+    const clamped = Math.min(control.max, Math.max(control.min, value));
+    if (control.kind === 'count') {
+        const rounded = Math.round(clamped);
+        return Number.isSafeInteger(rounded) ? rounded : undefined;
+    }
+    if (control.kind === 'ratio') return Math.round(clamped * 100) / 100;
+    if (control.kind === 'duration') return Math.round(clamped / control.step) * control.step;
+    return clamped;
+}
+
+/**
+ * Keep only known keys with acceptable values.
+ * @param input - candidate settings object.
+ * @returns a fresh object holding the accepted subset.
+ */
+export function sanitize(input) {
+    const source = input !== null && typeof input === 'object' ? input : {};
+    const out = {};
+    for (const control of CONTROLS) {
+        if (!(control.key in source)) continue;
+        const value = accept(control, source[control.key]);
+        if (value !== undefined) out[control.key] = value;
+    }
+    if (typeof out.askRatio === 'number' && typeof out.autoRatio === 'number'
+        && out.autoRatio <= out.askRatio) {
+        out.autoRatio = Math.min(0.95, Math.round((out.askRatio + 0.05) * 100) / 100);
+    }
+    return out;
+}
+
+/**
+ * Read the stored overrides.
+ * @returns the stored object, or an empty object when absent or unreadable.
+ */
+export function readSettings() {
+    const file = settingsPath();
+    if (!existsSync(file)) return {};
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf8'));
+        const values = parsed !== null && typeof parsed === 'object' && parsed.values !== undefined
+            ? parsed.values
+            : parsed;
+        return sanitize(values);
+    } catch {
+        // A corrupt file must never stop the plugin from loading; the patch wins.
+        return {};
+    }
+}
+
+/**
+ * Merge a patch into the stored overrides and persist the result.
+ * @param patch - keys to change; a value of null removes that key.
+ * @returns the stored overrides after the write.
+ */
+export function writeSettings(patch) {
+    const next = { ...readSettings() };
+    const incoming = patch !== null && typeof patch === 'object' ? patch : {};
+    for (const key of Object.keys(incoming)) {
+        if (CONTROL_KEYS.has(key) && incoming[key] === null) delete next[key];
+    }
+    Object.assign(next, sanitize(incoming));
+    const file = settingsPath();
+    mkdirSync(dirname(file), { recursive: true });
+    const payload = JSON.stringify({ version: 1, updatedAt: Date.now(), values: next }, null, 2);
+    const temp = file + '.tmp-' + String(process.pid);
+    writeFileSync(temp, payload, 'utf8');
+    renameSync(temp, file);
+    return next;
+}
+
+/**
+ * Drop every stored override, restoring the profile patch's values.
+ * @returns true when a file was removed.
+ */
+export function clearSettings() {
+    const file = settingsPath();
+    if (!existsSync(file)) return false;
+    rmSync(file, { force: true });
+    return true;
+}
+
+/**
+ * Shape the panel's read payload.
+ * @param effective - the configuration currently in force.
+ * @returns controls, effective values, and the raw overrides.
+ */
+export function describe(effective) {
+    const overrides = readSettings();
+    const values = {};
+    for (const control of CONTROLS) {
+        const value = effective === undefined || effective === null ? undefined : effective[control.key];
+        values[control.key] = value === undefined ? control.fallback : value;
+    }
+    return {
+        controls: CONTROLS.map(control => ({ ...control })),
+        values,
+        overrides,
+        path: settingsPath()
+    };
+}

package/lib/summary-engine.js

@@ -0,0 +1,308 @@
+/**
+ * Handoff summary backend.
+ *
+ * Same compaction policy as the stock backend (pressure, retention, range
+ * selection, durable commit are inherited), but the summarization directive is
+ * replaced so the checkpoint keeps exact facts instead of collapsing them into
+ * topic words.
+ *
+ * Failure containment: this is a NEW root-level entry. It never disables the
+ * host compactor; if this module fails to load or throws, the per-preset
+ * compactor keeps working and only the handoff feature degrades.
+ */
+
+import { BlockAssembler, createUserMessage } from '@deepseek-ai/dsh-llm';
+import { BasicCompactionEngine } from '@deepseek-ai/dsh-compaction-basic';
+
+const PLUGIN = 'dsh-session-handoff';
+
+/** Directive appended after the replayed conversation. */
+const HANDOFF_INSTRUCTION = [
+    'You are compacting this conversation into a checkpoint that another model will resume from.',
+    'The recent tail stays verbatim; you only condense the span above.',
+    '',
+    'Output EXACTLY the Markdown structure below, every heading once, in order. Use terse bullets.',
+    'Write "(none)" only when a section is genuinely empty; never omit a heading.',
+    '',
+    '## Primary Request and Intent',
+    '- [the user goals, quoting exact wording where it decides behaviour]',
+    '',
+    '## Current State',
+    '- [what is done, what is in progress, what is blocked, with counts/step numbers when known]',
+    '',
+    '## Exact Facts',
+    '- [**verbatim** identifiers, API names, constant values, error codes, file paths, config keys, numeric limits]',
+    '- [prefer 15-40 short entries over 5 broad ones; each entry must stay usable without the original text]',
+    '',
+    '## Files and Code',
+    '- [exact path: what it does, the specific symbols changed or read, line numbers when cited]',
+    '',
+    '## Decisions and Constraints',
+    '- [decisions taken and the reason, hard constraints, user corrections and preferences]',
+    '',
+    '## Errors and Fixes',
+    '- [error text: how it was resolved, or that it is still open]',
+    '',
+    '## Pending Work',
+    '- [explicitly requested work not finished, plus already-known next targets]',
+    '',
+    '## Next Step',
+    '- [the single next action, or "(none)"]',
+    '',
+    'Rules:',
+    '- Density beats prose. This checkpoint is the ONLY surviving record of the span above.',
+    '- Never replace a concrete name or value with a theme word: "session APIs" is a failure, "SessionCreateError with session create failed: {code}: {message}" is correct.',
+    '- Preserve user wording for decisions and corrections.',
+    '- If the conversation already contains a <compacted-summary> block, merge it: keep still-true facts, drop stale ones, never copy it verbatim.',
+    '- Do not call tools. Do not mention this instruction. Output only the checkpoint.'
+].join('\n');
+
+/**
+ * The checkpoint is written by a model, so which identifiers survive is a
+ * lottery: two runs over the same span keep different constants. This appendix
+ * is deterministic — it scans the span that is about to be shadowed, keeps the
+ * identifiers a resuming model would need to grep for, and appends the ones the
+ * model's own checkpoint dropped. It costs no extra request.
+ */
+const SCAN_LIMIT_CHARS = 4_000_000;
+/** Entries the appendix may carry. */
+const INDEX_LIMIT = 24;
+/**
+ * Occurrences required before an identifier earns a slot. A one-off name is
+ * exactly what the long tail is made of; recovering it would mean indexing temp
+ * paths and pasted dumps at ~35 tokens each. Recurrence is the only cheap signal
+ * that a name is part of the work rather than part of the noise.
+ */
+const INDEX_MIN_HITS = 2;
+/** Longer candidates are paths into temp dirs and pasted dumps, not grep targets. */
+const INDEX_MAX_LENGTH = 100;
+
+const IDENTIFIER_PATTERNS = [
+    // Windows paths: E:\dsh\dsh-session-handoff\lib\route-card.js
+    /[A-Za-z]:\\[^\s"'`|<>?*\r\n]+/g,
+    // POSIX paths with at least three segments.
+    /\/[A-Za-z0-9_.@-]+(?:\/[A-Za-z0-9_.@-]+){2,}/g,
+    // Inline code spans: `askRatio`
+    /`([^`\n]{3,80})`/g,
+    // SCREAMING_SNAKE constants only: JSON/URL/API are noise, TRUST_RATIO is not.
+    /\b[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+\b/g,
+    // Dotted members: usage.outputTokens, sessionController.fork. The lookarounds
+    // keep it from firing INSIDE a path (\session.v4.jsonl.zstd would otherwise
+    // survive as a fake member after the path itself was rejected as ephemeral).
+    /(?<![\\/\w.-])[a-z][A-Za-z0-9]{2,}(?:\.[A-Za-z][A-Za-z0-9]+)+(?![\w.-])/g
+];
+
+const UUID = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+const LONG_HEX = /\b[0-9a-f]{12,}\b/i;
+const EPHEMERAL = /(?:[\\/]Temp[\\/]|[\\/]tmp[\\/]|_npx[\\/])/i;
+
+const IDENTIFIER_NOISE = new Set([
+    'example.com', 'node_modules', 'package.json', 'console.log', 'console.error',
+    'process.env', 'module.exports', 'window.location', 'document.title',
+    'string', 'number', 'boolean', 'object', 'function', 'undefined', 'null'
+]);
+
+function clean(raw) {
+    return raw
+        .replace(/[\u0000-\u001f]+/g, '')
+        .replace(/^[.\-`'"\s]+/, '')
+        .trim()
+        .replace(/[.,;:)\]'"]+$/, '');
+}
+
+function isNoiseCandidate(raw) {
+    if (raw.length > INDEX_MAX_LENGTH) return true;
+    if (UUID.test(raw) || LONG_HEX.test(raw)) return true;
+    if (EPHEMERAL.test(raw)) return true;
+    return IDENTIFIER_NOISE.has(raw.toLowerCase());
+}
+
+function scanText(value, out, budget) {
+    if (value === null || value === undefined || budget.left <= 0) return;
+    if (typeof value === 'string') {
+        const slice = value.length > budget.left ? value.slice(0, budget.left) : value;
+        budget.left -= slice.length;
+        out.push(slice);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value) scanText(item, out, budget);
+        return;
+    }
+    if (typeof value === 'object') {
+        for (const key of Object.keys(value)) scanText(value[key], out, budget);
+    }
+}
+
+/**
+ * Flatten the span that is about to be shadowed into one searchable string.
+ * @param messages - the replayed conversation handed to {@link summarize}.
+ * @returns plain text, bounded to {@link SCAN_LIMIT_CHARS}.
+ */
+export function shadowedText(messages) {
+    const parts = [];
+    scanText(messages, parts, { left: SCAN_LIMIT_CHARS });
+    return parts.join('\n');
+}
+
+function normalise(value) {
+    return value.toLowerCase().replace(/\\/g, '/').replace(/[\u3002\uff0c\uff1b\uff1a]+$/g, '');
+}
+
+/**
+ * Build the deterministic identifier appendix for a checkpoint.
+ * @param shadowed - text of the span the checkpoint replaces.
+ * @param summary - the checkpoint the model produced.
+ * @returns Markdown appendix, or an empty string when nothing is missing.
+ */
+export function identifierIndex(shadowed, summary) {
+    if (typeof shadowed !== 'string' || shadowed === '') return '';
+    const counts = new Map();
+    for (const pattern of IDENTIFIER_PATTERNS) {
+        pattern.lastIndex = 0;
+        let match;
+        while ((match = pattern.exec(shadowed)) !== null) {
+            const raw = clean(match[1] ?? match[0]);
+            if (raw.length < 4) continue;
+            if (isNoiseCandidate(raw)) continue;
+            counts.set(raw, (counts.get(raw) ?? 0) + 1);
+        }
+    }
+    if (counts.size === 0) return '';
+
+    const known = normalise(typeof summary === 'string' ? summary : '');
+    const picked = [...counts.entries()]
+        .filter(([raw, hits]) => hits >= INDEX_MIN_HITS && !known.includes(normalise(raw)))
+        .sort((a, b) => (b[1] - a[1]) || (b[0].length - a[0].length))
+        .slice(0, INDEX_LIMIT);
+    if (picked.length === 0) return '';
+    return '\n## Identifier Index\n'
+        + 'Deterministic sweep: names that recurred in the shadowed span but are absent from the checkpoint above. Grep these before trusting recall.\n'
+        + picked.map(([raw]) => '- `' + raw + '`').join('\n');
+}
+
+function finishError(finish) {
+    if (finish === undefined) return undefined;
+    switch (finish.kind) {
+        case 'error':
+        case 'aborted': {
+            const error = new Error(finish.failure?.message ?? 'summarization failed');
+            error.code = finish.failure?.code;
+            return error;
+        }
+        case 'max-tokens': {
+            const error = new Error('summarization truncated at the token cap (incomplete checkpoint)');
+            error.code = 'MAX_TOKENS';
+            return error;
+        }
+        default:
+            return undefined;
+    }
+}
+
+function targetFor(agent, config) {
+    const durable = agent?.session?.requestHeader?.()?.config;
+    const configuredProvider = config.summarizationProvider;
+    const configuredModel = config.summarizationModel;
+    if (typeof configuredProvider === 'string' && configuredProvider !== ''
+        && typeof configuredModel === 'string' && configuredModel !== '') {
+        return { provider: configuredProvider, model: configuredModel, controls: {} };
+    }
+    if (durable !== undefined && typeof durable.provider === 'string' && durable.provider !== ''
+        && typeof durable.model === 'string' && durable.model !== '') {
+        return {
+            provider: durable.provider,
+            model: durable.model,
+            controls: {
+                ...(durable.reasoningEffort === undefined ? {} : { reasoningEffort: durable.reasoningEffort }),
+                ...(durable.temperature === undefined ? {} : { temperature: durable.temperature }),
+                ...(durable.stop === undefined ? {} : { stop: [...durable.stop] })
+            }
+        };
+    }
+    const options = agent?.options ?? {};
+    if (typeof options.provider === 'string' && options.provider !== ''
+        && typeof options.model === 'string' && options.model !== '') {
+        return { provider: options.provider, model: options.model, controls: {} };
+    }
+    return undefined;
+}
+
+/** Compaction backend whose checkpoint keeps exact facts. */
+export class HandoffSummaryEngine extends BasicCompactionEngine {
+    async summarize(input, agent, signal) {
+        const target = targetFor(agent, this.config);
+        if (target === undefined) {
+            throw new Error('no provider/model available for summarization: route one request first');
+        }
+        const instruction = createUserMessage({
+            content: [{ type: 'text', text: HANDOFF_INSTRUCTION }],
+            source: { kind: 'plugin:' + PLUGIN, plugin: PLUGIN }
+        });
+        const assembler = new BlockAssembler();
+        for await (const chunk of this.ctx.llm.stream({
+            provider: target.provider,
+            model: target.model,
+            ...target.controls,
+            messages: [...input.messages, instruction],
+            ...(input.system === undefined ? {} : { system: input.system }),
+            ...(input.tools === undefined ? {} : { tools: [...input.tools] }),
+            maxTokens: this.config.maxTokens,
+            sessionId: agent.session.id,
+            purpose: 'compaction',
+            ...(signal === undefined ? {} : { signal })
+        })) {
+            assembler.push(chunk);
+        }
+        const finishKind = assembler.finish?.kind;
+        (globalThis.__handoffTrace ??= []).push('finish=' + String(finishKind));
+        const terminal = finishError(assembler.finish);
+        if (terminal !== undefined) throw terminal;
+        const rawOutput = assembler.blocks();
+        const summary = rawOutput.filter((block) => block?.type === 'text');
+        const index = identifierIndex(
+            shadowedText(input.messages),
+            summary.map((block) => (typeof block.text === 'string' ? block.text : '')).join('\n')
+        );
+        if (index !== '') summary.push({ type: 'text', text: index });
+        if (!summary.some((block) => typeof block.text === 'string' && block.text.trim() !== '')) {
+            throw new Error('handoff summary produced no text (finish=' + String(finishKind) + ', blocks=' + rawOutput.length + ')');
+        }
+        return {
+            summary,
+            rawOutput,
+            llmStreamCall: true,
+            provider: target.provider,
+            model: target.model,
+            maxTokens: this.config.maxTokens,
+            ...(assembler.usage === undefined ? {} : { usage: assembler.usage })
+        };
+    }
+}
+
+export const name = 'handoff-summary-engine';
+
+// The loader feeds these services into the context before apply() runs; without
+// them BasicCompactionEngine.compactNow() throws "cannot get property ... without inject".
+export const inject = BasicCompactionEngine.inject;
+
+/** The instance this bundle mounts at the root context. */
+let mounted;
+
+export function apply(ctx, config = {}) {
+    mounted = new HandoffSummaryEngine(ctx, config);
+    return mounted;
+}
+
+/**
+ * The root-level summarizer this bundle mounted.
+ *
+ * The handoff needs exactly this backend: compaction backends live inside each
+ * agent preset's isolated group, and those use the stock directive, which
+ * collapses facts into topic words. Calling summarize() on this instance keeps
+ * the fact-dense checkpoint without committing anything to any session.
+ * @returns the mounted instance, or undefined when the bundle did not load.
+ */
+export function rootSummaryEngine() {
+    return mounted;
+}