dsh-context-core 0.1.1

package/dist/transaction.js

@@ -0,0 +1,122 @@
+/** DSH append protocol, exclusion and surface validation; selection belongs to plugins. */
+import { randomUUID } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import { CompactionId, ManualCompactionError, compactCheckpointSource, toolPairingBalancedBefore, toolPairingBalancedAfter } from '@deepseek-ai/dsh-compaction';
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+/** Inspect current durable ownership, excluding interrupted constructor seeds. */
+export function entryState(session) {
+    let active = false;
+    let turn = null;
+    for (const event of session.snapshotEvents()) {
+        if (event.type === 'session/end-seed') {
+            active = false;
+            turn = null;
+        }
+        if (event.type === 'compaction/start')
+            active = true;
+        if (event.type === 'compaction/end')
+            active = false;
+        if (event.type === 'turn/start')
+            turn = event.data.turn;
+        if (event.type === 'turn/end')
+            turn = null;
+    }
+    return { active, turn };
+}
+/** Reject competing mutation before any surface change. */
+export function assertInactive(session) {
+    if (entryState(session).active)
+        throw new ManualCompactionError('busy', 'A context compaction is already active');
+}
+function validateSpan(session, seqs) {
+    const start = seqs[0];
+    const end = seqs.at(-1);
+    if (start === undefined || end === undefined)
+        throw new Error('Cannot compact an empty range');
+    const position = session.surface.nodes.indexOf(start);
+    if (position < 0 || !isDeepStrictEqual(session.surface.nodes.slice(position, position + seqs.length), [...seqs]))
+        throw new ManualCompactionError('changed', 'The selected history is no longer contiguous on the surface');
+    if (!toolPairingBalancedBefore(session, start) || !toolPairingBalancedAfter(session, end))
+        throw new Error('The selected range splits a tool exchange or unfinished step');
+    for (const seq of seqs) {
+        const event = session.eventAt(seq);
+        const message = event && session.deriveEventMessage(event);
+        if (message?.role === 'system' || message?.role === 'developer')
+            throw new Error('System and developer messages must remain outside the compacted range');
+    }
+}
+/** Commit the chosen range only after its summary and recovery have both succeeded. */
+export async function compactTransaction(options) {
+    const { session, meter, entries, signal, manual, sourceCommandId } = options;
+    signal.throwIfAborted();
+    assertInactive(session);
+    const seqs = entries.map(entry => entry.seq);
+    validateSpan(session, seqs);
+    const turn = entryState(session).turn;
+    if (manual ? turn !== null : turn === null)
+        throw new ManualCompactionError('busy', manual ? 'Manual compaction requires an idle session' : 'Automatic compaction requires an open turn');
+    const before = meter.measure(session).nodes;
+    const priced = before.filter(node => seqs.includes(node.seq));
+    const shadowedRange = { start: seqs[0], end: seqs.at(-1) };
+    const shadowedTokenCount = priced.reduce((sum, node) => sum + node.heuristicTokens, 0);
+    const compactionId = CompactionId(randomUUID());
+    const lifecycle = { compactionId, turn, ...sourceCommandId === undefined ? {} : { sourceCommandId } };
+    const startEvent = session.append('compaction/start', lifecycle);
+    let closing = false;
+    let stage = 'summary';
+    try {
+        const checkpoint = await options.summarize();
+        signal.throwIfAborted();
+        validateSpan(session, seqs);
+        const after = meter.measure(session).nodes;
+        if (!isDeepStrictEqual(manual ? after.filter(node => seqs.includes(node.seq)) : after, manual ? priced : before))
+            throw new ManualCompactionError('changed', 'Session history changed during summarization');
+        const summary = [...checkpoint.beforeSummary ?? [], { type: 'text', text: checkpoint.summary }, ...checkpoint.restored ?? []];
+        const message = createUserMessage({ content: summary, source: compactCheckpointSource(compactionId, sourceCommandId) });
+        if (meter.estimateMessage(message) >= priced.reduce((sum, node) => sum + node.tokens, 0))
+            throw new Error('Summary and recovered context are not smaller than the selected history');
+        const calls = options.calls();
+        const call = calls.at(-1);
+        stage = 'commit';
+        const callRecord = calls.length === 1 && call ? { rawOutput: call.content, llmStreamCall: true } : {};
+        const summaryEvent = session.append('compaction/summary', {
+            compactionId, ...sourceCommandId === undefined ? {} : { sourceCommandId },
+            summary, shadowedRange, shadowedSeqs: seqs, shadowedTokenCount,
+            provider: call?.provider ?? options.target.provider, model: call?.model ?? options.target.model,
+            ...callRecord,
+            ...calls.length !== 1 || call === undefined ? {} : {
+                maxTokens: call.maxTokens,
+                ...call.usage === undefined ? {} : { usage: call.usage },
+            },
+        });
+        // The summary record and its replacement are adjacent in DSH's durable protocol.
+        session.append('user/message', message, {
+            surfaceOp: { op: 'replace', startSeq: shadowedRange.start, endSeq: shadowedRange.end },
+            sourceEventSeqs: [startEvent.seq, summaryEvent.seq, ...seqs],
+        });
+        closing = true;
+        const endEvent = session.append('compaction/end', lifecycle);
+        return {
+            compactionId, ...sourceCommandId === undefined ? {} : { sourceCommandId },
+            startSeq: startEvent.seq, summarySeq: summaryEvent.seq, endSeq: endEvent.seq,
+            summary, shadowedRange, shadowedSeqs: seqs, shadowedTokenCount,
+        };
+    }
+    catch (error) {
+        let failure = error;
+        if (!closing) {
+            try {
+                session.append('compaction/end', { ...lifecycle, error: error instanceof Error ? error.message : String(error) });
+            }
+            catch (closeError) {
+                failure = closeError;
+                stage = 'commit';
+            }
+        }
+        signal.throwIfAborted();
+        if (manual && !(failure instanceof ManualCompactionError))
+            throw new ManualCompactionError(stage, failure instanceof Error ? failure.message : String(failure), { cause: failure });
+        throw failure;
+    }
+}
+//# sourceMappingURL=transaction.js.map

package/dist/transaction.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,82 @@
+/** Inputs shared by the source-specific budget functions. */
+export interface BudgetInput {
+    contextWindow: number;
+    maxOutputTokens: number;
+    reserveTokens?: number;
+    thresholdRatio?: number;
+    keepRecentTokens?: number;
+}
+/** Source-specific budget metadata; the pipeline owns its token estimator and retention semantics. */
+export interface ContextBudget {
+    triggerTokens: number;
+    retainTokens: number;
+    strict?: boolean;
+    /** Minimum recent messages, subject to retainTokens when tailMode is maximum. */
+    minRecentMessages?: number;
+    tailMode?: 'minimum' | 'maximum';
+    retainLastRound?: boolean;
+}
+/** Optional model-free removal of old textual tool results. */
+export interface PrunePolicy {
+    enabled: boolean;
+    keepRecentTools: number;
+    protectTokens: number;
+    minSavingsTokens: number;
+    strictSavings?: boolean;
+    keepRecentTurns?: number;
+    protectedTools?: readonly string[];
+    eligibleTools?: readonly string[];
+    groupByAssistant?: boolean;
+    triggerRatio?: number;
+    triggerBufferTokens?: number;
+}
+/** One independently implemented adaptation of a pinned agent strategy. */
+export interface ContextStrategy {
+    id: string;
+    name: string;
+    /** Original project URL; revision and license describe the inspected local fork or source reference. */
+    source: {
+        url: string;
+        revision: string;
+        license: string;
+    };
+    /** What this adaptation deliberately leaves to the host or upstream product. */
+    limitations: readonly string[];
+    budget(input: BudgetInput): ContextBudget;
+    summaryInstructions: string;
+    maxSummaryTokens: number;
+    /** Maximum tool-result characters in the auxiliary summary request; zero leaves them intact. */
+    summaryToolChars: number;
+    prune: PrunePolicy;
+}
+/** User overrides for a strategy plugin. All token values are integers. */
+export interface ContextConfig {
+    auto?: boolean;
+    reserveTokens?: number;
+    thresholdRatio?: number;
+    keepRecentTokens?: number;
+    maxSummaryTokens?: number;
+    summaryToolChars?: number;
+    summarizationProvider?: string;
+    summarizationModel?: string;
+    maxOverflowRetries?: number;
+    maxConsecutiveFailures?: number;
+    prune?: boolean;
+    keepRecentTools?: number;
+    protectToolTokens?: number;
+    minPruneTokens?: number;
+    screenshotTriggerImages?: number;
+    tailTurns?: number;
+    summaryRetryDelayMs?: number;
+    idleMinutes?: number;
+    toolHighWaterChars?: number;
+    toolLowWaterChars?: number;
+    maxSummaryAttempts?: number;
+    maxRestoredFiles?: number;
+    maxFileTokens?: number;
+    maxRestoreTokens?: number;
+    maxRestoredImages?: number;
+    maxSkillTokens?: number;
+    restoreContext?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

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

package/dist/types.js.map

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

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "dsh-context-core",
+  "version": "0.1.1",
+  "type": "module",
+  "license": "MIT",
+  "description": "DSH host primitives and durable context transactions for independent agent pipelines.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zonemeen/dsh-context-zoo.git",
+    "directory": "packages/core"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json",
+    "./compat/*": "./dist/compat/*"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.js.map",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "README.md",
+    "README.zh-CN.md",
+    "src",
+    "LICENSE",
+    "dist/tools",
+    "dist/compat"
+  ],
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "yaml": "^2.8.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-commands": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-compaction": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-llm": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-session": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-token-meter": "0.1.7-rc.2",
+    "@deepseek-ai/cordis": "~4.0.4",
+    "@deepseek-ai/dsh-fs": "0.1.7-rc.2"
+  },
+  "homepage": "https://github.com/zonemeen/dsh-context-zoo/tree/main/packages/core#readme",
+  "bugs": {
+    "url": "https://github.com/zonemeen/dsh-context-zoo/issues"
+  },
+  "bin": {
+    "dsh-context-patch": "./dist/tools/create-profile-patch.mjs"
+  }
+}

package/src/config.ts

@@ -0,0 +1,18 @@
+import type { ContextConfig } from './types.js';
+
+const integerKeys = ['reserveTokens', 'keepRecentTokens', 'maxSummaryTokens', 'summaryToolChars', 'maxOverflowRetries', 'maxConsecutiveFailures', 'keepRecentTools', 'protectToolTokens', 'minPruneTokens', 'screenshotTriggerImages', 'tailTurns', 'summaryRetryDelayMs', 'idleMinutes', 'toolHighWaterChars', 'toolLowWaterChars', 'maxSummaryAttempts', 'maxRestoredFiles', 'maxFileTokens', 'maxRestoreTokens', 'maxRestoredImages', 'maxSkillTokens'] as const;
+const keys = new Set<string>([...integerKeys, 'auto', 'thresholdRatio', 'summarizationProvider', 'summarizationModel', 'prune', 'restoreContext']);
+
+/** Validate YAML/JSON plugin settings before registering any listeners. */
+export function validateConfig(config: ContextConfig): void {
+  for (const key of Object.keys(config)) if (!keys.has(key)) throw new Error(`Unknown context setting: ${key}`);
+  for (const key of integerKeys) {
+    const value = config[key];
+    if (value !== undefined && (!Number.isSafeInteger(value) || value < 0)) throw new Error(`${key} must be a non-negative safe integer`);
+  }
+  for (const key of ['maxSummaryTokens', 'maxConsecutiveFailures', 'maxSummaryAttempts'] as const) if (config[key] === 0) throw new Error(`${key} must be positive`);
+  for (const key of ['auto', 'prune', 'restoreContext'] as const) if (config[key] !== undefined && typeof config[key] !== 'boolean') throw new Error(`${key} must be a boolean`);
+  if (config.thresholdRatio !== undefined && (!Number.isFinite(config.thresholdRatio) || config.thresholdRatio <= 0 || config.thresholdRatio > 1)) throw new Error('thresholdRatio must be greater than 0 and at most 1');
+  for (const key of ['summarizationProvider', 'summarizationModel'] as const) if (config[key] !== undefined && (typeof config[key] !== 'string' || config[key].trim().length === 0)) throw new Error(`${key} must be a non-empty string`);
+  if ((config.summarizationProvider === undefined) !== (config.summarizationModel === undefined)) throw new Error('Set summarizationProvider and summarizationModel together');
+}

package/src/host.ts

@@ -0,0 +1,189 @@
+/** DSH observations and transport for independently implemented context pipelines. */
+import type { Context } from '@deepseek-ai/cordis';
+import type {} from '@deepseek-ai/dsh-fs';
+import type { CommandId } from '@deepseek-ai/dsh-commands/brand';
+import type { CompactionAgentContext } from '@deepseek-ai/dsh-compaction';
+import { assembleAssistantStream, BlockAssembler, freezeMessage, LlmError } from '@deepseek-ai/dsh-llm';
+import type { RequestMessage } from '@deepseek-ai/dsh-llm';
+import { SessionId } from '@deepseek-ai/dsh-session';
+import type { Session, SessionSeq } from '@deepseek-ai/dsh-session';
+import type { ContextConfig } from './types.js';
+import type { ContextEntry, ContextHost, ContextRecovery, SummaryResponse } from './pipeline.js';
+import { assertInactive, compactTransaction } from './transaction.js';
+
+declare module '@deepseek-ai/dsh-session/types' {
+  interface SessionEventMap {
+    'context-zoo/state': { plugin: string; kind: string; data: Record<string, unknown> };
+  }
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Events {
+    /**
+     * Supply observed external runtime state, such as an actual transcript location.
+     * @param agent - session owner requesting recovery observations.
+     * @param signal - operation cancellation.
+     * @param next - delegate when this integration has no observations.
+     * @mode waterfall
+     */
+    'context-zoo/recovery'(agent: CompactionAgentContext, signal: AbortSignal, next: () => Promise<ContextRecovery | undefined>): Promise<ContextRecovery | undefined>;
+  }
+}
+
+const checkedSessionClasses = new WeakSet<Function>();
+
+function checkSessionWriter(session: Session, plugin: string): void {
+  const implementation = session.constructor as typeof Session;
+  if (checkedSessionClasses.has(implementation)) return;
+  const probe = implementation.create(SessionId('context-zoo-runtime-probe'));
+  const marker = probe.append('context-zoo/state', { plugin, kind: 'probe', data: {} }, { ignorable: true });
+  if (marker.ignorable !== true) throw new Error('The active DSH Session implementation needs the supplied ignorable-event patch; see dsh-context-core/dist/compat/README.md');
+  checkedSessionClasses.add(implementation);
+}
+
+/** Build low-level operations scoped to one run and its cancellation signal. */
+export function createHost(ctx: Context, agent: CompactionAgentContext, id: string, config: ContextConfig, signal: AbortSignal, manual = false, sourceCommandId?: CommandId): ContextHost {
+  const session = agent.session;
+  checkSessionWriter(session, id);
+  const calls: Array<SummaryResponse | undefined> = [];
+  const target = () => {
+    const request = session.requestHeader()?.config;
+    const provider = request?.provider ?? agent.options.provider;
+    const model = request?.model ?? agent.options.model;
+    if (!provider || !model) throw new Error('Context management needs a routed provider and model');
+    return { provider, model, maxTokens: request?.maxTokens };
+  };
+  const record: ContextHost['record'] = (kind, data) => {
+    // Durable metadata must contain JSON values, including no undefined properties.
+    const durable: Record<string, unknown> = JSON.parse(JSON.stringify(data));
+    const event = session.append('context-zoo/state', { plugin: id, kind, data: durable }, { ignorable: true });
+    if (event.ignorable !== true) throw new Error('DSH Session.append needs the supplied ignorable-event patch; see dsh-context-core/dist/compat/README.md');
+  };
+  const host: ContextHost = {
+    signal,
+    record,
+    records: kind => session.snapshotEvents().flatMap(event => event.type === 'context-zoo/state' && event.data.plugin === id && event.data.kind === kind ? [event.data.data] : []),
+    async snapshot() {
+      signal.throwIfAborted();
+      const route = target();
+      const info = await ctx.llm.resolveModelInfo(route.provider, route.model, signal);
+      signal.throwIfAborted();
+      if (!info.context) throw new Error(`No context window configured for ${route.provider}/${route.model}`);
+      const recovery = await ctx.waterfall('context-zoo/recovery', agent, signal, async () => undefined);
+      signal.throwIfAborted();
+      const measurement = ctx.tokenMeter.measure(session);
+      const prices = new Map(measurement.nodes.map(node => [node.seq, node.tokens]));
+      const tools = new Map<string, { name: string; arguments: string }>();
+      let requestSeries = 'initial';
+      let turnKey: string | undefined;
+      const archive: ContextEntry[] = [];
+      for (const event of session.snapshotEvents()) {
+        if (event.type === 'turn/start') { turnKey = `turn:${event.seq}`; requestSeries = turnKey; }
+        if (event.type === 'tool/call') tools.set(event.data.callId, event.data);
+        const message = session.deriveEventMessage(event) ?? (event.type === 'system/message' || event.type === 'developer/message' ? event.data.message : null);
+        if (message === null) continue;
+        for (const block of message.content) if (block.type === 'tool-call') tools.set(block.id, { name: block.name, arguments: block.arguments });
+        const assembled = event.type === 'assistant/message' ? assembleAssistantStream(event.data.stream) : undefined;
+        if (event.type === 'assistant/message' && assembled?.finish.kind !== 'error' && assembled?.finish.kind !== 'aborted') requestSeries = `response:${event.seq}`;
+        const usage = event.type === 'assistant/message' ? event.data.usage ?? assembled?.usage : undefined;
+        const tool = message.role === 'tool' ? tools.get(message.toolCallId) : undefined;
+        archive.push({
+          seq: event.seq, message, time: event.time, tokens: prices.get(event.seq) ?? ctx.tokenMeter.estimateMessage(message),
+          ...assembled === undefined ? {} : { finish: assembled.finish.kind, ...usage === undefined ? {} : { usage } },
+          ...tool === undefined ? {} : { toolName: tool.name, toolArguments: tool.arguments },
+        });
+      }
+      const bySeq = new Map(archive.map(entry => [entry.seq, entry]));
+      const entries = session.surface.nodes.map(seq => {
+        const entry = bySeq.get(seq);
+        if (!entry) throw new Error(`Missing message for surface event ${seq}`);
+        return entry;
+      });
+      return {
+        entries, archive, contextWindow: info.context.contextWindow,
+        maxOutputTokens: route.maxTokens ?? info.defaultMaxTokens ?? 32_000,
+        provider: route.provider, model: route.model, tools: session.requestHeader()?.tools ?? [],
+        measuredTokens: measurement.totalTokens, now: Date.now(), cwd: session.header.cwd ?? '', sessionId: session.id, requestSeries, ...turnKey === undefined ? {} : { turnKey },
+        ...recovery === undefined ? {} : { recovery },
+      };
+    },
+    async summarize(request) {
+      signal.throwIfAborted();
+      const route = target();
+      const provider = request.provider ?? config.summarizationProvider ?? route.provider;
+      const model = request.model ?? config.summarizationModel ?? route.model;
+      const messages: RequestMessage[] = [...request.messages, { role: 'user', content: [{ type: 'text', text: request.instruction }] }];
+      const tools = request.includeTools ? session.requestHeader()?.tools : undefined;
+      const requestData = { provider, model, maxTokens: request.maxTokens, messages, ...(tools === undefined ? {} : { tools }) };
+      const callId = `${id}:${session.seq}`;
+      record('model-request', { callId, ...requestData });
+      const callIndex = calls.push(undefined) - 1;
+      try {
+        const assembler = new BlockAssembler();
+        for await (const chunk of ctx.llm.stream({ ...requestData, toolHistory: session.toolHistory(), sessionId: session.id, purpose: 'compaction', signal })) assembler.push(chunk);
+        signal.throwIfAborted();
+        const finish = assembler.finish;
+        const content = assembler.blocks();
+        const response: SummaryResponse = {
+          provider, model, maxTokens: request.maxTokens, content,
+          text: content.filter(block => block.type === 'text').map(block => block.text).join('\n'),
+          finish: finish.kind, ...assembler.usage === undefined ? {} : { usage: assembler.usage },
+        };
+        record('model-result', { callId, ...response, ...(finish.kind === 'error' || finish.kind === 'aborted' ? { failure: finish.failure } : {}) });
+        calls[callIndex] = response;
+        if (finish.kind === 'error' || finish.kind === 'aborted') throw new LlmError(finish.failure.message, finish.failure.code, finish.failure);
+        return response;
+      } catch (error) {
+        record('model-error', { callId, message: error instanceof Error ? error.message : String(error), ...error instanceof LlmError ? { failure: error.failure } : {} });
+        signal.throwIfAborted();
+        throw error;
+      }
+    },
+    replace(replacements) {
+      signal.throwIfAborted();
+      assertInactive(session);
+      const seen = new Set<SessionSeq>();
+      const changes = replacements.map(replacement => {
+        if (seen.has(replacement.seq)) throw new Error('Duplicate tool replacement');
+        seen.add(replacement.seq);
+        const event = session.eventAt(replacement.seq);
+        if (!session.surface.nodes.includes(replacement.seq) || (event?.type !== 'tool/result' && event?.type !== 'user/message')) throw new Error('Replacement must target a current user message or tool result');
+        const original = event.type === 'tool/result' ? event.data.message : event.data;
+        const message = freezeMessage({ ...original, content: [...replacement.content] });
+        return { event, message, price: ctx.tokenMeter.estimateMessage(original) };
+      });
+      for (const { event, message, price } of changes) {
+        session.append('compaction/prune', { shadowedRange: { start: event.seq, end: event.seq }, shadowedSeqs: [event.seq], shadowedTokenCount: price });
+        const options = { surfaceOp: { op: 'replace' as const, startSeq: event.seq, endSeq: event.seq }, sourceEventSeqs: [event.seq] };
+        if (event.type === 'tool/result' && message.role === 'tool') session.append('tool/result', { ...event.data, message }, options);
+        else if (event.type === 'user/message' && message.role === 'user') session.append('user/message', message, options);
+      }
+    },
+    compact(entries, summarize) {
+      const firstCall = calls.length;
+      return compactTransaction({ session, meter: ctx.tokenMeter, entries, signal, manual, sourceCommandId, summarize, calls: () => calls.slice(firstCall), target: target() });
+    },
+    async readFile(path, maxChars) {
+      signal.throwIfAborted();
+      const fs = ctx.get('fs');
+      if (!fs) { record('file-unavailable', { path, reason: 'No DSH filesystem provider is installed' }); return null; }
+      try {
+        const target = await fs.resolve(path, { cwd: session.header.cwd, signal });
+        const chunks = await fs.streamText(target, signal);
+        let text = '';
+        for await (const chunk of chunks) {
+          signal.throwIfAborted();
+          text += chunk.slice(0, Math.max(0, maxChars - text.length));
+          if (text.length >= maxChars) break;
+        }
+        signal.throwIfAborted();
+        return text;
+      } catch (error) {
+        signal.throwIfAborted();
+        record('file-unavailable', { path, reason: error instanceof Error ? error.message : String(error) });
+        return null;
+      }
+    },
+  };
+  return host;
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+/** Independent agent pipelines and their DSH integration. */
+import './host.js';
+export type * from './types.js';
+export { createContextPlugin, summarizeBranch } from './plugin.js';
+export type { ContextPlugin } from './plugin.js';
+export { validateConfig } from './config.js';
+export type * from './pipeline.js';

package/src/pipeline.ts

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