dsh-context-core 0.1.1

package/src/plugin.ts

@@ -0,0 +1,160 @@
+/** Cordis registration and lifecycle delegation, without agent-specific decisions. */
+import { Context } from '@deepseek-ai/cordis';
+import type {} from '@deepseek-ai/dsh-agent';
+import { CompactionEngine, ManualCompactionError } from '@deepseek-ai/dsh-compaction';
+import type { CompactionAgentContext, CompactionResult, CompactionTrigger, ManualCompactAgentContext } from '@deepseek-ai/dsh-compaction';
+import type { CommandId } from '@deepseek-ai/dsh-commands/brand';
+import { CONTEXT_WINDOW_EXCEEDED_CODE } from '@deepseek-ai/dsh-llm';
+import { Session, SessionId } from '@deepseek-ai/dsh-session';
+import type { SessionSeq } from '@deepseek-ai/dsh-session';
+import { validateConfig } from './config.js';
+import { createHost } from './host.js';
+import { assertInactive } from './transaction.js';
+import type { ContextConfig } from './types.js';
+import type { ContextPipeline, ContextTrigger, 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 function summarizeBranch(ctx: Context, agent: ManualCompactAgentContext, seqs: readonly SessionSeq[], signal: AbortSignal): Promise<string | undefined> {
+  signal.throwIfAborted();
+  return agent.runMaintenance(async agentSignal => {
+    const operationSignal = AbortSignal.any([agentSignal, signal]);
+    let summary: string | undefined;
+    let failed = false;
+    let failure: unknown;
+    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: PipelineDefinition): ContextPlugin {
+  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<Session, ContextPipeline>();
+      const pipelineFor = (session: Session): ContextPipeline => {
+        let pipeline = pipelines.get(session);
+        if (!pipeline) { pipeline = definition.create(settings); pipelines.set(session, pipeline); }
+        return pipeline;
+      };
+      const run = async (agent: CompactionAgentContext, trigger: ContextTrigger, signal: AbortSignal, manual = false, sourceCommandId?: CommandId): Promise<CompactionResult | null> => {
+        signal.throwIfAborted();
+        assertInactive(agent.session);
+        return pipelineFor(agent.session).run(createHost(ctx, agent, definition.id, settings, signal, manual, sourceCommandId), trigger);
+      };
+      class PipelineEngine extends CompactionEngine {
+        override compactIfNeeded(agent: CompactionAgentContext, trigger: CompactionTrigger, signal: AbortSignal): Promise<CompactionResult | null> {
+          return run(agent, trigger, signal);
+        }
+        override async compactRegion(start: SessionSeq, end: SessionSeq, agent: CompactionAgentContext, signal = new AbortController().signal): Promise<CompactionResult> {
+          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));
+        }
+        override compactNow(agent: ManualCompactAgentContext, signal: AbortSignal, sourceCommandId?: CommandId): Promise<CompactionResult | null> {
+          signal.throwIfAborted();
+          try {
+            return agent.runMaintenance(async agentSignal => {
+              const operationSignal = AbortSignal.any([agentSignal, signal]);
+              const before = agent.session.seq;
+              let result: CompactionResult | null = null;
+              let failed = false;
+              let failure: unknown;
+              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();
+      });
+    },
+  };
+}

package/src/transaction.ts

@@ -0,0 +1,121 @@
+/** 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 type { CompactionResult } from '@deepseek-ai/dsh-compaction';
+import type { CommandId } from '@deepseek-ai/dsh-commands/brand';
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+import type { Session, SessionSeq } 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 function entryState(session: Session): { active: boolean; turn: number | null } {
+  let active = false;
+  let turn: number | null = 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: Session): void {
+  if (entryState(session).active) throw new ManualCompactionError('busy', 'A context compaction is already active');
+}
+
+function validateSpan(session: Session, seqs: readonly SessionSeq[]): void {
+  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');
+  }
+}
+
+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 async function compactTransaction(options: TransactionOptions): Promise<CompactionResult> {
+  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' | 'commit' = '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: ContentBlock[] = [...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 as const } : {};
+    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;
+  }
+}

package/src/types.ts

@@ -0,0 +1,81 @@
+/** 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;
+}