dsh-context-core 0.1.1

package/dist/pipeline.d.ts

@@ -0,0 +1,104 @@
+import type { ContentBlock, Message, RequestMessage, TokenUsage, ToolSchema } from '@deepseek-ai/dsh-llm';
+import type { CompactionResult } from '@deepseek-ai/dsh-compaction';
+import type { SessionSeq } from '@deepseek-ai/dsh-session';
+import type { ContextConfig } from './types.js';
+/** A durable message with the host's observations; plugins choose their own prices and interpretation. */
+export interface ContextEntry {
+    seq: SessionSeq;
+    message: Message;
+    time: number;
+    tokens: number;
+    usage?: TokenUsage;
+    finish?: string;
+    toolName?: string;
+    toolArguments?: string;
+}
+/** Immutable observations for one admitted operation. */
+export interface ContextSnapshot {
+    entries: readonly ContextEntry[];
+    /** Full durable message history, including content replaced by earlier checkpoints. */
+    archive: readonly ContextEntry[];
+    contextWindow: number;
+    maxOutputTokens: number;
+    inputLimit?: number;
+    provider: string;
+    model: string;
+    tools: readonly ToolSchema[];
+    measuredTokens: number;
+    now: number;
+    /** Stable through failed retries; advances at a new turn or successful assistant response. */
+    requestSeries: string;
+    /** Stable for an entire user turn; absent for hosts without a turn lifecycle. */
+    turnKey?: string;
+    cwd: string;
+    sessionId: string;
+    /** Observed host recovery pointers; absent capabilities must not be claimed. */
+    recovery?: ContextRecovery;
+}
+export type ContextTrigger = 'pressure' | 'manual' | 'context-overflow' | 'request-too-large';
+/** Low-level auxiliary model call. Formatting, clipping, retry and output validation belong to the plugin. */
+export interface SummaryRequest {
+    messages: readonly RequestMessage[];
+    instruction: string;
+    maxTokens: number;
+    includeTools?: boolean;
+    provider?: string;
+    model?: string;
+}
+/** One settled call, preserved even when a plugin later rejects its text. */
+export interface SummaryResponse {
+    text: string;
+    content: ContentBlock[];
+    provider: string;
+    model: string;
+    maxTokens: number;
+    usage?: TokenUsage;
+    finish?: string;
+}
+/** Checkpoint and recovered context that will replace the selected history atomically. */
+export interface Checkpoint {
+    summary: string;
+    beforeSummary?: readonly ContentBlock[];
+    restored?: readonly ContentBlock[];
+}
+/** Explicit replacement selected by a plugin's microcompaction algorithm. */
+export interface ContextReplacement {
+    seq: SessionSeq;
+    content: readonly ContentBlock[];
+}
+/** Observations supplied by an installed host integration. */
+export interface ContextRecovery {
+    approvedPlanPath?: string;
+    transcriptPath?: string;
+    wirePath?: string;
+    windowLines?: string;
+    todos?: string;
+    reminders?: readonly ContentBlock[];
+    replStateCleared?: boolean;
+}
+/** Host primitives contain no source-agent trigger, retention, pruning or retry policy. */
+export interface ContextHost {
+    readonly signal: AbortSignal;
+    snapshot(): Promise<ContextSnapshot>;
+    summarize(request: SummaryRequest): Promise<SummaryResponse>;
+    replace(replacements: readonly ContextReplacement[]): void;
+    compact(entries: readonly ContextEntry[], summarize: () => Promise<Checkpoint>): Promise<CompactionResult>;
+    /** Read through DSH's filesystem provider; null means absent or unavailable, never a fabricated file snapshot. */
+    readFile(path: string, maxChars: number): Promise<string | null>;
+    /** Append plugin state as an ignorable durable event, keeping replay independent of live plugin instances. */
+    record(kind: string, data: Record<string, unknown>): void;
+    records(kind: string): readonly Record<string, unknown>[];
+}
+/** Each package owns the complete sequence of decisions and transformations. */
+export interface ContextPipeline {
+    run(host: ContextHost, trigger: ContextTrigger): Promise<CompactionResult | null>;
+    /** Explicit range requests still use the package's summary and recovery sequence. */
+    summarizeRange(host: ContextHost, entries: readonly ContextEntry[]): Promise<Checkpoint>;
+    /** Optional native branch-navigation integration, invoked explicitly by the host. */
+    summarizeBranch?(host: ContextHost, entries: readonly ContextEntry[]): Promise<string>;
+}
+export interface PipelineDefinition {
+    id: string;
+    create(config?: ContextConfig): ContextPipeline;
+}
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"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"}

package/dist/pipeline.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pipeline.js.map

package/dist/pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":""}

package/dist/plugin.d.ts

@@ -0,0 +1,38 @@
+/** Cordis registration and lifecycle delegation, without agent-specific decisions. */
+import { Context } from '@deepseek-ai/cordis';
+import type { CompactionAgentContext, ManualCompactAgentContext } from '@deepseek-ai/dsh-compaction';
+import type { SessionSeq } from '@deepseek-ai/dsh-session';
+import type { ContextConfig } from './types.js';
+import type { PipelineDefinition } from './pipeline.js';
+/** Cordis plugin providing one context engine. */
+export interface ContextPlugin {
+    name: string;
+    inject: string[];
+    apply(ctx: Context, config?: ContextConfig): void;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Events {
+        /**
+         * Summarize an explicit abandoned branch under the caller's maintenance lock.
+         * @param agent - idle session owner whose durable log contains the selected events.
+         * @param seqs - branch message events in conversation order.
+         * @param signal - cancellation forwarded to the summary provider.
+         * @param next - delegate if this context plugin has no branch workflow.
+         * @mode waterfall
+         */
+        'context-zoo/summarize-branch'(agent: CompactionAgentContext, seqs: readonly SessionSeq[], signal: AbortSignal, next: () => Promise<string | undefined>): Promise<string | undefined>;
+    }
+}
+/**
+ * Run a plugin's explicit branch workflow and flush its durable summary metadata.
+ * The navigation integration inserts the returned text in its new branch as a logged message.
+ * @param ctx - Cordis context with the selected plugin.
+ * @param agent - idle agent containing the abandoned branch events.
+ * @param seqs - message sequence numbers in branch order.
+ * @param signal - caller cancellation.
+ * @returns the branch summary, or undefined when the plugin has no branch workflow.
+ */
+export declare function summarizeBranch(ctx: Context, agent: ManualCompactAgentContext, seqs: readonly SessionSeq[], signal: AbortSignal): Promise<string | undefined>;
+/** Register a source-owned pipeline using the common DSH service and event protocols. */
+export declare function createContextPlugin(definition: PipelineDefinition): ContextPlugin;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAG9C,OAAO,KAAK,EAAE,sBAAsB,EAAuC,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AAI1I,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAI3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAmC,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAEzF,kDAAkD;AAClD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;CACnD;AAED,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,MAAM;QACd;;;;;;;WAOG;QACH,8BAA8B,CAAC,KAAK,EAAE,sBAAsB,EAAE,IAAI,EAAE,SAAS,UAAU,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;KACvL;CACF;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,yBAAyB,EAAE,IAAI,EAAE,SAAS,UAAU,EAAE,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAe7J;AAED,yFAAyF;AACzF,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,kBAAkB,GAAG,aAAa,CAgGjF"}

package/dist/plugin.js

@@ -0,0 +1,180 @@
+/** Cordis registration and lifecycle delegation, without agent-specific decisions. */
+import { Context } from '@deepseek-ai/cordis';
+import { CompactionEngine, ManualCompactionError } from '@deepseek-ai/dsh-compaction';
+import { CONTEXT_WINDOW_EXCEEDED_CODE } from '@deepseek-ai/dsh-llm';
+import { Session, SessionId } from '@deepseek-ai/dsh-session';
+import { validateConfig } from './config.js';
+import { createHost } from './host.js';
+import { assertInactive } from './transaction.js';
+/**
+ * Run a plugin's explicit branch workflow and flush its durable summary metadata.
+ * The navigation integration inserts the returned text in its new branch as a logged message.
+ * @param ctx - Cordis context with the selected plugin.
+ * @param agent - idle agent containing the abandoned branch events.
+ * @param seqs - message sequence numbers in branch order.
+ * @param signal - caller cancellation.
+ * @returns the branch summary, or undefined when the plugin has no branch workflow.
+ */
+export function summarizeBranch(ctx, agent, seqs, signal) {
+    signal.throwIfAborted();
+    return agent.runMaintenance(async (agentSignal) => {
+        const operationSignal = AbortSignal.any([agentSignal, signal]);
+        let summary;
+        let failed = false;
+        let failure;
+        try {
+            summary = await ctx.waterfall('context-zoo/summarize-branch', agent, seqs, operationSignal, async () => undefined);
+        }
+        catch (error) {
+            failed = true;
+            failure = error;
+        }
+        try {
+            await ctx.sessions.flush(agent.session);
+        }
+        catch (error) {
+            if (!failed) {
+                failed = true;
+                failure = error;
+            }
+        }
+        operationSignal.throwIfAborted();
+        if (failed)
+            throw failure;
+        return summary;
+    });
+}
+/** Register a source-owned pipeline using the common DSH service and event protocols. */
+export function createContextPlugin(definition) {
+    return {
+        name: `context-${definition.id}`,
+        inject: ['llm', 'tokenMeter', 'sessions'],
+        apply(ctx, config = {}) {
+            validateConfig(config);
+            const probe = Session.create(SessionId('context-zoo-capability-probe'));
+            const marker = probe.append('context-zoo/state', { plugin: definition.id, kind: 'probe', data: {} }, { ignorable: true });
+            if (marker.ignorable !== true)
+                throw new Error('DSH Session.append needs the supplied ignorable-event patch; see dsh-context-core/dist/compat/README.md');
+            const settings = Object.freeze({ ...config });
+            const pipelines = new WeakMap();
+            const pipelineFor = (session) => {
+                let pipeline = pipelines.get(session);
+                if (!pipeline) {
+                    pipeline = definition.create(settings);
+                    pipelines.set(session, pipeline);
+                }
+                return pipeline;
+            };
+            const run = async (agent, trigger, signal, manual = false, sourceCommandId) => {
+                signal.throwIfAborted();
+                assertInactive(agent.session);
+                return pipelineFor(agent.session).run(createHost(ctx, agent, definition.id, settings, signal, manual, sourceCommandId), trigger);
+            };
+            class PipelineEngine extends CompactionEngine {
+                compactIfNeeded(agent, trigger, signal) {
+                    return run(agent, trigger, signal);
+                }
+                async compactRegion(start, end, agent, signal = new AbortController().signal) {
+                    const host = createHost(ctx, agent, definition.id, settings, signal);
+                    const snapshot = await host.snapshot();
+                    const first = snapshot.entries.findIndex(entry => entry.seq === start);
+                    const last = snapshot.entries.findIndex(entry => entry.seq === end);
+                    if (first < 0 || last < first)
+                        throw new Error('Invalid context range');
+                    const entries = snapshot.entries.slice(first, last + 1);
+                    return host.compact(entries, () => pipelineFor(agent.session).summarizeRange(host, entries));
+                }
+                compactNow(agent, signal, sourceCommandId) {
+                    signal.throwIfAborted();
+                    try {
+                        return agent.runMaintenance(async (agentSignal) => {
+                            const operationSignal = AbortSignal.any([agentSignal, signal]);
+                            const before = agent.session.seq;
+                            let result = null;
+                            let failed = false;
+                            let failure;
+                            try {
+                                result = await run(agent, 'manual', operationSignal, true, sourceCommandId);
+                            }
+                            catch (error) {
+                                failed = true;
+                                failure = error;
+                            }
+                            if (agent.session.seq !== before) {
+                                try {
+                                    await ctx.sessions.flush(agent.session);
+                                }
+                                catch (error) {
+                                    if (!failed) {
+                                        failed = true;
+                                        failure = new ManualCompactionError('persistence', 'Manual compaction could not be flushed', { cause: error });
+                                    }
+                                }
+                            }
+                            signal.throwIfAborted();
+                            if (agentSignal.aborted)
+                                throw new ManualCompactionError('cancelled', 'Manual compaction was cancelled', { cause: operationSignal.reason });
+                            if (failed)
+                                throw failure;
+                            return result;
+                        });
+                    }
+                    catch (error) {
+                        throw new ManualCompactionError('busy', 'Manual compaction requires an idle agent', { cause: error });
+                    }
+                }
+            }
+            ctx.plugin(PipelineEngine);
+            ctx.on('context-zoo/summarize-branch', async (agent, seqs, signal, next) => {
+                const pipeline = pipelineFor(agent.session);
+                if (!pipeline.summarizeBranch)
+                    return next();
+                assertInactive(agent.session);
+                const host = createHost(ctx, agent, definition.id, settings, signal, true);
+                const snapshot = await host.snapshot();
+                const bySeq = new Map(snapshot.archive.map(entry => [entry.seq, entry]));
+                const entries = seqs.map(seq => {
+                    const entry = bySeq.get(seq);
+                    if (!entry)
+                        throw new Error(`Missing branch message ${seq}`);
+                    return entry;
+                });
+                const summary = await pipeline.summarizeBranch(host, entries);
+                signal.throwIfAborted();
+                host.record('branch-summary', { seqs: [...seqs], summary });
+                return summary;
+            });
+            if (settings.auto === false)
+                return;
+            ctx.on('agent/pre-step', async ({ agent, signal }, next) => {
+                if (!signal.aborted) {
+                    try {
+                        await run(agent, 'pressure', signal);
+                    }
+                    catch (error) {
+                        if (!signal.aborted)
+                            ctx.logger.warn(`${definition.id} context preparation failed: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                }
+                return next();
+            });
+            ctx.on('agent/request-error', async ({ agent, failure, signal }, next) => {
+                const trigger = failure.status === 413 ? 'request-too-large' : failure.code === CONTEXT_WINDOW_EXCEEDED_CODE ? 'context-overflow' : undefined;
+                if (!trigger || signal.aborted)
+                    return next();
+                const generation = agent.session.surface.replaceGeneration;
+                try {
+                    await run(agent, trigger, signal);
+                }
+                catch (error) {
+                    if (!signal.aborted)
+                        ctx.logger.warn(`${definition.id} context recovery failed: ${error instanceof Error ? error.message : String(error)}`);
+                }
+                if (!signal.aborted && agent.session.surface.replaceGeneration > generation)
+                    return { kind: 'retry' };
+                return next();
+            });
+        },
+    };
+}
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"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"}

package/dist/tools/create-profile-patch.mjs

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+/** Generate a loader overlay from a resolved DSH profile without editing that profile. */
+import { readFileSync, realpathSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { parse, stringify } from 'yaml';
+
+const agentIds = ['claude-code', 'codex', 'opencode', 'pi', 'qwen-code', 'zcode', 'kimi-code', 'cline'];
+const managedNames = new Set(agentIds.map(id => `dsh-context-${id}`));
+const nativeEngine = '@deepseek-ai/dsh-compaction-basic';
+const nativePruner = '@deepseek-ai/dsh-compaction-tool-result-pruner';
+const presetName = '@deepseek-ai/dsh-agent-preset';
+const rootGroupId = 'context-zoo';
+
+const jsTag = {
+  tag: 'tag:yaml.org,2002:js',
+  identify: value => isRecord(value) && typeof value.__jsExpr === 'string' && Object.keys(value).length === 1,
+  resolve: value => ({ __jsExpr: value }),
+  stringify: item => JSON.stringify(item.value.__jsExpr),
+};
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function assertRows(rows) {
+  if (!Array.isArray(rows) || !rows.every(isRecord)) throw new Error('Expected a resolved DSH profile entry list');
+}
+
+/** Parse a DSH config dump while preserving its unevaluated !!js expressions. */
+export function parseProfileDump(source) {
+  const entries = parse(source, { customTags: [jsTag] });
+  assertRows(entries);
+  return entries;
+}
+
+/** Print a loader overlay using DSH's !!js YAML tag for preserved expressions. */
+export function stringifyProfilePatch(patches) {
+  return stringify(patches, { customTags: [jsTag], lineWidth: 0 });
+}
+
+function isEngine(entry) {
+  return entry.name === nativeEngine || managedNames.has(entry.name);
+}
+
+function activeEngine(entry) {
+  if (!isEngine(entry) || entry.disabled === true) return false;
+  if (entry.disabled !== undefined && entry.disabled !== null && entry.disabled !== false) {
+    throw new Error(`Cannot select a conditionally disabled context engine: ${entry.id ?? entry.name}`);
+  }
+  return true;
+}
+
+function requireId(entry) {
+  if (typeof entry.id !== 'string' || entry.id.length === 0) throw new Error(`The profile entry needs an id: ${entry.name}`);
+  return entry.id;
+}
+
+function replaceEngine(entry, packageName) {
+  return { ...entry, name: packageName, config: entry.name === nativeEngine ? {} : (entry.config ?? {}) };
+}
+
+/** Resolve the compaction realms declared by groups; ordinary groups share their parent's services. */
+function inspectComposition(entries) {
+  const rootRealm = {};
+  const namedRealms = new Map();
+  const engineRealms = new Map();
+  const engines = new Set();
+  const pruners = new Map();
+  const rootIds = new Set();
+  const checkIds = (rows, ids) => {
+    assertRows(rows);
+    for (const entry of rows) {
+      if (entry.id !== undefined) {
+        if (ids.has(entry.id)) throw new Error(`Duplicate loader entry id: ${entry.id}`);
+        ids.add(entry.id);
+      }
+      if (entry.group === true && Array.isArray(entry.config)) checkIds(entry.config, ids);
+      if (entry.name === presetName && isRecord(entry.config)) checkIds(entry.config.plugins, new Set());
+    }
+  };
+  checkIds(entries, rootIds);
+  const visit = (rows, parentRealm, conditional = false, inPreset = false) => {
+    for (const entry of rows) {
+      if (entry.disabled === true) continue;
+      let realm = parentRealm;
+      const label = entry.isolate?.compaction;
+      if (label === true) realm = {};
+      else if (typeof label === 'string' && label.length > 0) {
+        if (!namedRealms.has(label)) namedRealms.set(label, {});
+        realm = namedRealms.get(label);
+      } else if (label !== undefined) throw new Error(`Invalid compaction isolation on ${entry.id ?? entry.name}`);
+      const uncertain = conditional || (entry.disabled !== undefined && entry.disabled !== null && entry.disabled !== false);
+      if (activeEngine(entry)) {
+        if (uncertain) throw new Error(`Cannot replace a context engine under a conditionally disabled entry: ${entry.id ?? entry.name}`);
+        if (inPreset && realm === rootRealm) throw new Error(`Preset context engines require compaction isolation: ${entry.id ?? entry.name}`);
+        if (engineRealms.has(realm)) throw new Error('A compaction realm contains more than one active compaction engine');
+        engineRealms.set(realm, entry);
+        engines.add(entry);
+      }
+      if (entry.name === nativePruner) pruners.set(entry, realm);
+      if (entry.group === true && Array.isArray(entry.config)) visit(entry.config, realm, uncertain, inPreset);
+      // The registry mounts each preset from its host owner; a declaration's local services are not inherited.
+      if (entry.name === presetName && isRecord(entry.config)) visit(entry.config.plugins, rootRealm, uncertain, true);
+    }
+  };
+  visit(entries, rootRealm);
+  return { engines, pruners: new Set([...pruners].filter(([, realm]) => engineRealms.has(realm)).map(([entry]) => entry)), rootIds };
+}
+
+/**
+ * Replace active native or zoo engines in a resolved profile and preserve every other setting.
+ * Group and preset config overrides contain their full original config because DSH replaces it.
+ * @param entries - The entry list printed by dsh --dump-config.
+ * @param agentId - One of the supported context strategy ids.
+ * @returns A loader patch list to apply after the profile's existing layers.
+ */
+export function createProfilePatch(entries, agentId) {
+  assertRows(entries);
+  if (!agentIds.includes(agentId)) throw new Error(`Unknown context strategy ${JSON.stringify(agentId)}; choose ${agentIds.join(', ')}`);
+  const packageName = `dsh-context-${agentId}`;
+  const copied = structuredClone(entries);
+  const { engines, pruners, rootIds } = inspectComposition(copied);
+  let changes = 0;
+
+  const rewriteRows = (rows) => {
+    assertRows(rows);
+    return rows.map(entry => {
+      if (entry.disabled === true) return entry;
+      if (engines.has(entry)) {
+        changes++;
+        return replaceEngine(entry, packageName);
+      }
+      if (pruners.has(entry)) { changes++; return { ...entry, disabled: true }; }
+      if (entry.group === true && Array.isArray(entry.config)) return { ...entry, config: rewriteRows(entry.config) };
+      if (entry.name === presetName && isRecord(entry.config)) {
+        return { ...entry, config: { ...entry.config, plugins: rewriteRows(entry.config.plugins) } };
+      }
+      return entry;
+    });
+  };
+
+  const patches = [];
+  const direct = copied.filter(entry => engines.has(entry));
+  if (direct.length > 1) throw new Error('Replacing multiple separately isolated host engines requires a group configuration');
+  for (const entry of copied) {
+    if (entry.disabled === true) continue;
+    if (engines.has(entry)) {
+      patches.push({ id: requireId(entry), name: entry.name, disabled: true });
+      continue;
+    }
+    if (pruners.has(entry)) {
+      patches.push({ id: requireId(entry), name: entry.name, disabled: true });
+      continue;
+    }
+    const before = changes;
+    let config;
+    if (entry.group === true && Array.isArray(entry.config)) config = rewriteRows(entry.config);
+    else if (entry.name === presetName && isRecord(entry.config)) {
+      config = { ...entry.config, plugins: rewriteRows(entry.config.plugins) };
+    }
+    if (changes !== before) patches.push({ id: requireId(entry), name: entry.name, config });
+  }
+  if (direct.length > 0) {
+    for (const id of [rootGroupId, 'context-zoo-engine']) {
+      if (rootIds.has(id)) throw new Error(`Cannot insert context engine: profile id ${id} is already in use`);
+    }
+    patches.push({ insert: [{
+      id: rootGroupId,
+      name: 'cordis:group',
+      group: true,
+      config: [{ ...replaceEngine(direct[0], packageName), id: 'context-zoo-engine' }],
+    }] });
+  }
+  if (engines.size === 0) throw new Error('No active native or zoo compaction engine was found in the resolved profile');
+  return patches;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+  try {
+    const [agentId, filename, ...extra] = process.argv.slice(2);
+    if (!agentId || !filename || extra.length > 0) throw new Error('Usage: dsh-context-patch <agent-id> <resolved-profile.yml>');
+    process.stdout.write(stringifyProfilePatch(createProfilePatch(parseProfileDump(readFileSync(filename, 'utf8')), agentId)));
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  }
+}

package/dist/transaction.d.ts

@@ -0,0 +1,29 @@
+import type { CompactionResult } from '@deepseek-ai/dsh-compaction';
+import type { CommandId } from '@deepseek-ai/dsh-commands/brand';
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { TokenMeter } from '@deepseek-ai/dsh-token-meter';
+import type { Checkpoint, ContextEntry, SummaryResponse } from './pipeline.js';
+/** Inspect current durable ownership, excluding interrupted constructor seeds. */
+export declare function entryState(session: Session): {
+    active: boolean;
+    turn: number | null;
+};
+/** Reject competing mutation before any surface change. */
+export declare function assertInactive(session: Session): void;
+export interface TransactionOptions {
+    session: Session;
+    meter: TokenMeter;
+    entries: readonly ContextEntry[];
+    signal: AbortSignal;
+    manual: boolean;
+    sourceCommandId?: CommandId;
+    summarize(): Promise<Checkpoint>;
+    calls(): readonly (SummaryResponse | undefined)[];
+    target: {
+        provider: string;
+        model: string;
+    };
+}
+/** Commit the chosen range only after its summary and recovery have both succeeded. */
+export declare function compactTransaction(options: TransactionOptions): Promise<CompactionResult>;
+//# sourceMappingURL=transaction.d.ts.map

package/dist/transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../src/transaction.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iCAAiC,CAAC;AAGjE,OAAO,KAAK,EAAE,OAAO,EAAc,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAE/E,kFAAkF;AAClF,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAWrF;AAED,2DAA2D;AAC3D,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAErD;AAgBD,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,UAAU,CAAC;IAClB,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IACjC,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;IAChB,eAAe,CAAC,EAAE,SAAS,CAAC;IAC5B,SAAS,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;IACjC,KAAK,IAAI,SAAS,CAAC,eAAe,GAAG,SAAS,CAAC,EAAE,CAAC;IAClD,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C;AAED,uFAAuF;AACvF,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA8D/F"}