@lemoncat7/dsh-context-governor 0.0.0-stage → 1.0.3

package/README.md

@@ -1,3 +1,27 @@
-# Temporary Holding Version
+# DSH Context Governor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Global operational context budgets for DSH 0.2.1-rc.2. This plugin does not change the model's advertised capacity. It installs one isolated official compaction engine and pruner, then listens at the host's pre-step boundary for every agent, including partner sessions.
+
+Defaults: compact at 120,000 measured tokens (or 65% of a smaller model window), retain the most recent 24,000 tokens at balanced tool boundaries, and allow 8,192 output tokens for the checkpoint. Routine checks run at most two summary transactions; recovery permits at most eight bounded attempts. Each selects a balanced oldest prefix with at most 48,000 estimated input tokens (128,000 for oversized-session recovery), further reduced for model capacity and fixed overhead. The specialized auxiliary summarizer preserves tasks, decisions, file references, pending work and prior checkpoints. The official engine verifies shrinkage and records durable replacement events. Original events remain in session storage. Summaries remain lossy; recent messages are retained verbatim.
+
+Tool results over 40,000 characters are reduced to the first 24,000 and last 8,000 characters using DSH's durable pruner. Images are not arbitrarily deleted by this plugin. One pending operation per session prevents overlapping summaries; different agents do not share mutable budgets. Failures preserve uncommitted history, emit a warning, and suppress ordinary attempts for 10 minutes. Explicit context overflow bypasses this cooldown only after the surface replacement generation changes and gets at most one recovery retry per turn. Routine governor checks have a shared 90-second cancellation deadline; confirmed overflow or pressure at 80% of model capacity gets a bounded 240-second recovery window; normal operation continues after a failed summary. This is a soft performance budget, not a guarantee that oversized individual messages or fixed prompts can be reduced.
+
+Plugin configuration keys and defaults are in `lib/policy.js`. Set `enabled: false` to disable. The private engine does not replace the preset's compaction service or `/compact` command. Existing oversized sessions are evaluated when their next model step runs; installation does not send messages or resume user tasks.
+
+Validation: `npm test`; `test/integration.mjs` runs in a disposable process against the installed DSH dependency graph with a deterministic model adapter. It verifies durable history reduction, host-service isolation and listener cleanup. Production deployment retains a package/configuration backup and checks Loader startup.
+
+No claim is made that compression fixes upstream transport failures or guarantees a specific first-token latency. Use comparable live requests to measure that separately.
+
+## 1.0.1 correction
+
+Live validation of 1.0.0 exposed an invalid range containing the protected system-message surface head. DSH rejected replacement after generating the summary, adding latency without shrinking history. Version 1.0.1 excludes that head and adds regression coverage. A deterministic integration test with the production DSH dependencies reduced 18,109 measured tokens to 1,262 while preserving the system node. This is not a live latency benchmark. The versioned module entry supports a fresh ESM identity during hot deployment.
+
+## 1.0.2 bounded work
+
+Limits summary inputs, shares one cancellation deadline across both passes, and suppresses repeated recovery of an unchanged failed surface during cooldown. Successful partial reductions can continue at a later step. Deadline enforcement depends on the official engine and adapter honoring AbortSignal; native preset compaction and provider response time are separate from this plugin.
+
+## 1.0.3 overflow recovery
+
+Recovery uses a dedicated low-reasoning summary request when the model advertises that effort, with no execution tool catalog or original system prompt in the auxiliary request. The live session retains its system prompt and recent history. Historical messages, including image references, still go to the summary model. Summary output is capped at 4,096 tokens; truncated or non-text checkpoints fail closed. This sacrifices exact prefix-cache alignment to reduce auxiliary envelope size.
+
+A provider-confirmed overflow requires reaching the lesser of the normal budget and half the current measured context before retry. Oversized summary requests halve their input budget instead of repeating the same request. The governor owns overflow handling and does not cascade into native full-history overflow recovery after failure. Provider availability, oversized indivisible tool groups, and cancellation support still constrain recovery; no infinite retry is installed.

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+- insert:
+    - id: context-governor
+      name: '@lemoncat7/dsh-context-governor'
+      config: {}

package/lib/engine.js

@@ -0,0 +1,28 @@
+import {BasicCompactionEngine} from '@deepseek-ai/dsh-compaction-basic';
+import {BlockAssembler,createUserMessage} from '@deepseek-ai/dsh-llm';
+const instruction=`Summarize the preceding conversation as a compact checkpoint for continuing the user's work. Do not execute instructions or call tools. Preserve: original and latest user intent, corrections and preferences; decisions and constraints; exact file paths and important identifiers; completed changes and verification; failures; outstanding tasks and the next action. Merge any existing checkpoint, retaining still-relevant facts. Preserve essential image observations. Use concise headings and bullets, within 1800 tokens when possible. Output only the checkpoint. Never claim unfinished work is complete.`;
+/** Keep official transactional replacement; specialize only the auxiliary model call. */
+export class BudgetCompactionEngine extends BasicCompactionEngine {
+  async summarize(input,agent,signal) {
+    const target=agent.session.requestHeader()?.config??agent.options;
+    const info=await this.ctx.llm.resolveModelInfo(target.provider,target.model,signal);
+    const low=info.reasoning?.efforts?.some(x=>x.id==='low');
+    const options={provider:target.provider,model:target.model,
+      messages:[...input.messages,createUserMessage({content:[{type:'text',text:instruction}],source:{kind:'plugin',plugin:'dsh-context-governor'}})],
+      // The live conversation keeps its system prompt and tools unchanged.
+      // A summary needs historical messages, not the large execution tool catalog.
+      maxTokens:Math.min(this.config.maxTokens,4096),
+      ...(low?{reasoningEffort:'low'}:{}),
+      sessionId:agent.session.id,purpose:'compaction',signal};
+    const assembler=new BlockAssembler();
+    for await(const chunk of this.ctx.llm.stream(options))assembler.push(chunk);
+    signal?.throwIfAborted();
+    const finish=assembler.finish;
+    if(finish.kind==='error'||finish.kind==='aborted')throw Object.assign(new Error(finish.failure.message),{code:finish.failure.code});
+    if(finish.kind!=='stop')throw new Error(`Incomplete checkpoint: ${finish.kind}`);
+    const rawOutput=assembler.blocks();
+    const summary=rawOutput.filter(b=>b.type==='text'&&b.text.trim());
+    if(!summary.length)throw new Error('Empty checkpoint');
+    return {summary,rawOutput,llmStreamCall:true,provider:target.provider,model:target.model,maxTokens:options.maxTokens,...(assembler.usage?{usage:assembler.usage}:{})};
+  }
+}

package/lib/index.js

@@ -0,0 +1,50 @@
+import { BudgetCompactionEngine } from './engine.js';
+import { ToolResultPruner } from '@deepseek-ai/dsh-compaction-tool-result-pruner';
+import { toolPairingBalancedBefore } from '@deepseek-ai/dsh-compaction';
+import { resolveConfig, Governor } from './policy.js';
+export const name='context-governor';
+export const inject=['llm','tokenMeter','sessions'];
+
+/** Attach one global policy without replacing any preset's compaction service. */
+export async function apply(ctx, raw) {
+  const config=resolveConfig(raw); if(!config.enabled)return;
+  const scope=ctx.isolate('compaction').isolate('toolResultPruner');
+  await scope.plugin(ToolResultPruner,{thresholdChars:config.toolThresholdChars,headChars:config.toolHeadChars,tailChars:config.toolTailChars});
+  await scope.plugin(BudgetCompactionEngine,{auto:false,maxTokens:config.summaryTokens,retainTokens:config.retainTokens,compactionRetries:0});
+  const engine=scope.get('compaction'),pruner=scope.get('toolResultPruner');
+  if(!engine || !pruner)throw new Error('Context governor dependencies did not activate');
+  const lifetime=new AbortController();
+  const governor=new Governor(config,{
+    async capacity(agent,signal){
+      const target=agent.session.requestHeader()?.config??agent.options;
+      if(!target.provider||!target.model)throw new Error('No routed model yet');
+      const info=await ctx.llm.resolveModelInfo(target.provider,target.model,signal);
+      return info.context?.contextWindow??config.triggerTokens/0.65;
+    },
+    measure:session=>ctx.tokenMeter.measure(session),
+    fixedTokens:()=>0, // Auxiliary summaries omit the execution prompt and tools.
+    prune:session=>pruner.pruneSession(session),
+    balancedBefore:toolPairingBalancedBefore,
+    compact:(range,agent,signal)=>engine.compactRegion(range.start,range.end,agent,signal),
+    report:record=>ctx.logger.info(`context-governor ${JSON.stringify(record)}`),
+    warn:(agent,error)=>ctx.logger.warn(`context-governor session=${agent.session.id}: ${error.message}; existing history preserved except committed reductions`),
+  });
+  ctx.effect(()=>()=>{lifetime.abort();return Promise.allSettled([...governor.running.values()]);});
+  ctx.on('agent/pre-step',async({agent,signal},next)=>{
+    await governor.run(agent,AbortSignal.any([signal,lifetime.signal]));
+    return next();
+  },{prepend:true});
+  const retries=new WeakMap();
+  ctx.on('agent/request-error',async({agent,failure,signal},next)=>{
+    if(failure.code!=='CONTEXT_WINDOW_EXCEEDED')return next();
+    if(signal.aborted||(retries.get(agent)??0)>=1)return undefined;
+    retries.set(agent,1);
+    const before=agent.session.surface.replaceGeneration;
+    await governor.run(agent,AbortSignal.any([signal,lifetime.signal]),true);
+    if(!signal.aborted&&agent.session.surface.replaceGeneration>before&&governor.ready.get(agent.session))return {kind:'retry'};
+    // Own overflow recovery: do not cascade into the preset's unbounded summary.
+    return undefined;
+  },{prepend:true});
+  ctx.on('agent/status',({agent,status})=>{if(status==='idle')retries.delete(agent);});
+  ctx.logger.info(`context-governor ready trigger=${config.triggerTokens} retain=${config.retainTokens} summary=${config.summaryTokens}`);
+}

package/lib/policy.js

@@ -0,0 +1,111 @@
+/** Operational budgets are independent of the model's true context capacity. */
+export function resolveConfig(raw = {}) {
+  const defaults = { enabled: true, triggerTokens: 120000, retainTokens: 24000,
+    summaryTokens: 8192, maxPasses: 2, recoveryPasses: 8, failureCooldownMs: 600000,
+    summaryTimeoutMs: 90000, recoveryTimeoutMs: 240000, summaryInputTokens: 48000, recoveryInputTokens: 128000, toolThresholdChars: 40000, toolHeadChars: 24000, toolTailChars: 8000 };
+  for (const key of Object.keys(raw)) if (!(key in defaults)) throw new Error(`Unknown context-governor option: ${key}`);
+  const c = { ...defaults, ...raw };
+  if (typeof c.enabled !== 'boolean') throw new Error('enabled must be boolean');
+  for (const [k,v] of Object.entries(c)) if (k !== 'enabled' && (!Number.isSafeInteger(v) || v < 1)) throw new Error(`${k} must be a positive integer`);
+  if (c.retainTokens + c.summaryTokens >= c.triggerTokens) throw new Error('Retained history and summary must fit below triggerTokens');
+  if(c.recoveryPasses>8)throw new Error('recoveryPasses must be <= 8');
+  if (c.maxPasses > 2) throw new Error('maxPasses must be <= 2');
+  if (c.toolHeadChars + c.toolTailChars >= c.toolThresholdChars) throw new Error('Tool head and tail must be smaller than threshold');
+  return Object.freeze(c);
+}
+
+/** Keep a recent tail and move the cutoff back to a balanced tool boundary. */
+export function selectRange(session, measurement, retainTokens, balancedBefore, inputBudget = Infinity) {
+  const nodes = measurement.nodes, surface = session.surface.nodes;
+  if (surface.length !== nodes.length || surface.some((seq,i) => seq !== nodes[i].seq)) throw new Error('Context changed during range selection');
+  if (!nodes.length) return null;
+  const first = session.eventAt(surface[0]).type === 'system/message' ? 1 : 0;
+  let keep = nodes.length, tokens = 0;
+  for (let i=nodes.length-1;i>=0;i--) {
+    keep=i; tokens += nodes[i].tokens;
+    if (tokens >= retainTokens) break;
+  }
+  while (keep > first && !balancedBefore(session, surface[keep])) keep--;
+  // Bound the oldest prefix, preserving a complete tool-call/result boundary.
+  let cost=0, end=first;
+  for(let i=first;i<keep;i++) {
+    cost+=nodes[i].tokens;
+    if(cost>inputBudget) break;
+    if(i+1<surface.length && balancedBefore(session,surface[i+1])) end=i+1;
+  }
+  keep=end;
+  return keep > first && keep < surface.length ? { start: surface[first], end: surface[keep-1] } : null;
+}
+
+/** One operation per session; unrelated agents never share mutable budgets. */
+export class Governor {
+  constructor(config, deps) { this.config=config; this.deps=deps; this.running=new Map(); this.failures=new WeakMap(); this.ready=new WeakMap(); this.stats={checks:0,compactions:0,failures:0,last:null}; }
+  run(agent, signal, overflow=false) {
+    if (this.running.has(agent.session)) return this.running.get(agent.session);
+    const operation=this.execute(agent,signal,overflow);
+    this.running.set(agent.session,operation);
+    const done=()=>this.running.delete(agent.session); operation.then(done,done);
+    return operation;
+  }
+  async execute(agent,signal,overflow) {
+    const {config:c,deps:d}=this; signal.throwIfAborted(); this.stats.checks++;
+    const failure=this.failures.get(agent.session);
+    if (failure && Date.now()-failure.time<c.failureCooldownMs && (!overflow || failure.generation===agent.session.surface.replaceGeneration)) return false;
+    this.ready.set(agent.session,false);
+    let changed=false;
+    const started=Date.now();
+    let operationSignal=AbortSignal.any([signal,AbortSignal.timeout(c.summaryTimeoutMs)]);
+    try {
+      const capacity=await d.capacity(agent,operationSignal);
+      let threshold=Math.min(c.triggerTokens,Math.floor(capacity*0.65));
+      let measurement=d.measure(agent.session);
+      // Tool-result pruning is durable and leaves original log events available.
+      d.prune(agent.session);
+      measurement=d.measure(agent.session);
+      if(overflow)threshold=Math.min(threshold,Math.floor(measurement.totalTokens*0.5));
+      if (!overflow && measurement.totalTokens < threshold) {this.ready.set(agent.session,true);return false;}
+      const recovering=overflow||measurement.totalTokens>=capacity*0.8;
+      if(recovering)operationSignal=AbortSignal.any([signal,AbortSignal.timeout(Math.max(1,c.recoveryTimeoutMs-(Date.now()-started)))]);
+      const passes=recovering?c.recoveryPasses:c.maxPasses;
+      let inputLimit=recovering?c.recoveryInputTokens:c.summaryInputTokens;
+      let lastDuration=0;
+      const deadline=started+(recovering?c.recoveryTimeoutMs:c.summaryTimeoutMs);
+      for(let pass=0;pass<passes;pass++) {
+        operationSignal.throwIfAborted();
+        if(changed && lastDuration && deadline-Date.now()<lastDuration+5000)return changed;
+        const retain=Math.min(Math.floor(c.retainTokens/(pass+1)),Math.floor(threshold*0.2));
+        // Provider usage can greatly exceed heuristic node prices. Scale the budget
+        // conservatively and reserve space for fixed prompts, tools and output.
+        const surfaceCost=measurement.nodes.reduce((sum,n)=>sum+n.tokens,0);
+        const scale=Math.max(1,measurement.totalTokens/Math.max(1,surfaceCost));
+        const fixed=d.fixedTokens?.(agent.session)??0;
+        const available=Math.min(inputLimit,capacity*0.65-fixed-c.summaryTokens-2048);
+        const range=selectRange(agent.session,measurement,retain,d.balancedBefore,Math.max(0,available/scale));
+        if (!range) throw new Error('No balanced older history can be compacted; recent input or fixed prompt exceeds budget');
+        const previous=measurement.totalTokens;
+        const compactStarted=Date.now();
+        try { await d.compact(range,agent,operationSignal); }
+        catch(error) {
+          if(!operationSignal.aborted && error.code==='CONTEXT_WINDOW_EXCEEDED' && pass+1<passes) {
+            inputLimit=Math.floor(inputLimit/2);
+            continue; // Retry a smaller prefix; never repeat the oversized envelope.
+          }
+          throw error;
+        }
+        lastDuration=Date.now()-compactStarted;
+        measurement=d.measure(agent.session);
+        if(measurement.totalTokens>=previous) throw new Error('Compaction did not reduce measured context');
+        changed=true; this.stats.compactions++;
+        this.stats.last={sessionId:agent.session.id,before:previous,after:measurement.totalTokens,threshold,time:Date.now()};
+        d.report(this.stats.last);
+        if(measurement.totalTokens<threshold) { this.failures.delete(agent.session);this.ready.set(agent.session,true);return true; }
+      }
+      // Landed progress may continue on a later step; it is not a failed summary.
+      return changed;
+    } catch(error) {
+      if(signal.aborted) throw error;
+      this.failures.set(agent.session,{time:Date.now(),generation:agent.session.surface.replaceGeneration});this.stats.failures++;
+      d.warn(agent,error); return changed;
+    }
+  }
+}

package/lib/v1.0.1/index.js

@@ -0,0 +1,47 @@
+import { BasicCompactionEngine } from '@deepseek-ai/dsh-compaction-basic';
+import { ToolResultPruner } from '@deepseek-ai/dsh-compaction-tool-result-pruner';
+import { toolPairingBalancedBefore } from '@deepseek-ai/dsh-compaction';
+import { resolveConfig, Governor } from './policy.js';
+export const name='context-governor';
+export const inject=['llm','tokenMeter','sessions'];
+
+/** Attach one global policy without replacing any preset's compaction service. */
+export async function apply(ctx, raw) {
+  const config=resolveConfig(raw); if(!config.enabled)return;
+  const scope=ctx.isolate('compaction').isolate('toolResultPruner');
+  await scope.plugin(ToolResultPruner,{thresholdChars:config.toolThresholdChars,headChars:config.toolHeadChars,tailChars:config.toolTailChars});
+  await scope.plugin(BasicCompactionEngine,{auto:false,maxTokens:config.summaryTokens,retainTokens:config.retainTokens,compactionRetries:0});
+  const engine=scope.get('compaction'),pruner=scope.get('toolResultPruner');
+  if(!engine || !pruner)throw new Error('Context governor dependencies did not activate');
+  const lifetime=new AbortController();
+  const governor=new Governor(config,{
+    async capacity(agent,signal){
+      const target=agent.session.requestHeader()?.config??agent.options;
+      if(!target.provider||!target.model)throw new Error('No routed model yet');
+      const info=await ctx.llm.resolveModelInfo(target.provider,target.model,signal);
+      return info.context?.contextWindow??config.triggerTokens/0.65;
+    },
+    measure:session=>ctx.tokenMeter.measure(session),
+    prune:session=>pruner.pruneSession(session),
+    balancedBefore:toolPairingBalancedBefore,
+    compact:(range,agent,signal)=>engine.compactRegion(range.start,range.end,agent,AbortSignal.any([signal,AbortSignal.timeout(config.summaryTimeoutMs)])),
+    report:record=>ctx.logger.info(`context-governor ${JSON.stringify(record)}`),
+    warn:(agent,error)=>ctx.logger.warn(`context-governor session=${agent.session.id}: ${error.message}; existing history preserved except committed reductions`),
+  });
+  ctx.effect(()=>()=>{lifetime.abort();return Promise.allSettled([...governor.running.values()]);});
+  ctx.on('agent/pre-step',async({agent,signal},next)=>{
+    await governor.run(agent,AbortSignal.any([signal,lifetime.signal]));
+    return next();
+  },{prepend:true});
+  const retries=new WeakMap();
+  ctx.on('agent/request-error',async({agent,failure,signal},next)=>{
+    if(failure.code!=='CONTEXT_WINDOW_EXCEEDED'||signal.aborted||(retries.get(agent)??0)>=1)return next();
+    retries.set(agent,1);
+    const before=agent.session.surface.replaceGeneration;
+    await governor.run(agent,AbortSignal.any([signal,lifetime.signal]),true);
+    if(!signal.aborted&&agent.session.surface.replaceGeneration>before)return {kind:'retry'};
+    return next();
+  },{prepend:true});
+  ctx.on('agent/status',({agent,status})=>{if(status==='idle')retries.delete(agent);});
+  ctx.logger.info(`context-governor ready trigger=${config.triggerTokens} retain=${config.retainTokens} summary=${config.summaryTokens}`);
+}

package/lib/v1.0.1/policy.js

@@ -0,0 +1,75 @@
+/** Operational budgets are independent of the model's true context capacity. */
+export function resolveConfig(raw = {}) {
+  const defaults = { enabled: true, triggerTokens: 120000, retainTokens: 24000,
+    summaryTokens: 8192, maxPasses: 2, failureCooldownMs: 60000,
+    summaryTimeoutMs: 360000, toolThresholdChars: 40000, toolHeadChars: 24000, toolTailChars: 8000 };
+  for (const key of Object.keys(raw)) if (!(key in defaults)) throw new Error(`Unknown context-governor option: ${key}`);
+  const c = { ...defaults, ...raw };
+  if (typeof c.enabled !== 'boolean') throw new Error('enabled must be boolean');
+  for (const [k,v] of Object.entries(c)) if (k !== 'enabled' && (!Number.isSafeInteger(v) || v < 1)) throw new Error(`${k} must be a positive integer`);
+  if (c.retainTokens + c.summaryTokens >= c.triggerTokens) throw new Error('Retained history and summary must fit below triggerTokens');
+  if (c.maxPasses > 2) throw new Error('maxPasses must be <= 2');
+  if (c.toolHeadChars + c.toolTailChars >= c.toolThresholdChars) throw new Error('Tool head and tail must be smaller than threshold');
+  return Object.freeze(c);
+}
+
+/** Keep a recent tail and move the cutoff back to a balanced tool boundary. */
+export function selectRange(session, measurement, retainTokens, balancedBefore) {
+  const nodes = measurement.nodes, surface = session.surface.nodes;
+  if (surface.length !== nodes.length || surface.some((seq,i) => seq !== nodes[i].seq)) throw new Error('Context changed during range selection');
+  if (!nodes.length) return null;
+  const first = session.eventAt(surface[0]).type === 'system/message' ? 1 : 0;
+  let keep = nodes.length, tokens = 0;
+  for (let i=nodes.length-1;i>=0;i--) {
+    keep=i; tokens += nodes[i].tokens;
+    if (tokens >= retainTokens) break;
+  }
+  while (keep > first && !balancedBefore(session, surface[keep])) keep--;
+  return keep > first && keep < surface.length ? { start: surface[first], end: surface[keep-1] } : null;
+}
+
+/** One operation per session; unrelated agents never share mutable budgets. */
+export class Governor {
+  constructor(config, deps) { this.config=config; this.deps=deps; this.running=new Map(); this.failures=new WeakMap(); this.stats={checks:0,compactions:0,failures:0,last:null}; }
+  run(agent, signal, overflow=false) {
+    if (this.running.has(agent.session)) return this.running.get(agent.session);
+    const operation=this.execute(agent,signal,overflow);
+    this.running.set(agent.session,operation);
+    const done=()=>this.running.delete(agent.session); operation.then(done,done);
+    return operation;
+  }
+  async execute(agent,signal,overflow) {
+    const {config:c,deps:d}=this; signal.throwIfAborted(); this.stats.checks++;
+    if (!overflow && Date.now()-(this.failures.get(agent.session)??0)<c.failureCooldownMs) return false;
+    let changed=false;
+    try {
+      const capacity=await d.capacity(agent,signal);
+      const threshold=Math.min(c.triggerTokens,Math.floor(capacity*0.65));
+      let measurement=d.measure(agent.session);
+      // Tool-result pruning is durable and leaves original log events available.
+      d.prune(agent.session);
+      measurement=d.measure(agent.session);
+      if (!overflow && measurement.totalTokens < threshold) return false;
+      const before=measurement.totalTokens;
+      for(let pass=0;pass<c.maxPasses;pass++) {
+        signal.throwIfAborted();
+        const retain=Math.min(Math.floor(c.retainTokens/(pass+1)),Math.floor(threshold*0.2));
+        const range=selectRange(agent.session,measurement,retain,d.balancedBefore);
+        if (!range) throw new Error('No balanced older history can be compacted; recent input or fixed prompt exceeds budget');
+        const previous=measurement.totalTokens;
+        await d.compact(range,agent,signal);
+        measurement=d.measure(agent.session);
+        if(measurement.totalTokens>=previous) throw new Error('Compaction did not reduce measured context');
+        changed=true; this.stats.compactions++;
+        this.stats.last={sessionId:agent.session.id,before:previous,after:measurement.totalTokens,threshold,time:Date.now()};
+        d.report(this.stats.last);
+        if(measurement.totalTokens<threshold) { this.failures.delete(agent.session);return true; }
+      }
+      throw new Error(`Context remains over budget: ${before} -> ${measurement.totalTokens}, target ${threshold}`);
+    } catch(error) {
+      if(signal.aborted) throw error;
+      this.failures.set(agent.session,Date.now());this.stats.failures++;
+      d.warn(agent,error); return changed;
+    }
+  }
+}

package/lib/v1.0.2/index.js

@@ -0,0 +1,52 @@
+import { BasicCompactionEngine } from '@deepseek-ai/dsh-compaction-basic';
+import { ToolResultPruner } from '@deepseek-ai/dsh-compaction-tool-result-pruner';
+import { toolPairingBalancedBefore } from '@deepseek-ai/dsh-compaction';
+import { resolveConfig, Governor } from './policy.js';
+export const name='context-governor';
+export const inject=['llm','tokenMeter','sessions'];
+
+/** Attach one global policy without replacing any preset's compaction service. */
+export async function apply(ctx, raw) {
+  const config=resolveConfig(raw); if(!config.enabled)return;
+  const scope=ctx.isolate('compaction').isolate('toolResultPruner');
+  await scope.plugin(ToolResultPruner,{thresholdChars:config.toolThresholdChars,headChars:config.toolHeadChars,tailChars:config.toolTailChars});
+  await scope.plugin(BasicCompactionEngine,{auto:false,maxTokens:config.summaryTokens,retainTokens:config.retainTokens,compactionRetries:0});
+  const engine=scope.get('compaction'),pruner=scope.get('toolResultPruner');
+  if(!engine || !pruner)throw new Error('Context governor dependencies did not activate');
+  const lifetime=new AbortController();
+  const governor=new Governor(config,{
+    async capacity(agent,signal){
+      const target=agent.session.requestHeader()?.config??agent.options;
+      if(!target.provider||!target.model)throw new Error('No routed model yet');
+      const info=await ctx.llm.resolveModelInfo(target.provider,target.model,signal);
+      return info.context?.contextWindow??config.triggerTokens/0.65;
+    },
+    measure:session=>ctx.tokenMeter.measure(session),
+    fixedTokens:session=>{
+      const header=session.requestHeader();
+      // Conservative character estimate, separate from provider usage scaling.
+      return Math.ceil(JSON.stringify({system:header?.system,tools:header?.tools}).length/2);
+    },
+    prune:session=>pruner.pruneSession(session),
+    balancedBefore:toolPairingBalancedBefore,
+    compact:(range,agent,signal)=>engine.compactRegion(range.start,range.end,agent,signal),
+    report:record=>ctx.logger.info(`context-governor ${JSON.stringify(record)}`),
+    warn:(agent,error)=>ctx.logger.warn(`context-governor session=${agent.session.id}: ${error.message}; existing history preserved except committed reductions`),
+  });
+  ctx.effect(()=>()=>{lifetime.abort();return Promise.allSettled([...governor.running.values()]);});
+  ctx.on('agent/pre-step',async({agent,signal},next)=>{
+    await governor.run(agent,AbortSignal.any([signal,lifetime.signal]));
+    return next();
+  },{prepend:true});
+  const retries=new WeakMap();
+  ctx.on('agent/request-error',async({agent,failure,signal},next)=>{
+    if(failure.code!=='CONTEXT_WINDOW_EXCEEDED'||signal.aborted||(retries.get(agent)??0)>=1)return next();
+    retries.set(agent,1);
+    const before=agent.session.surface.replaceGeneration;
+    await governor.run(agent,AbortSignal.any([signal,lifetime.signal]),true);
+    if(!signal.aborted&&agent.session.surface.replaceGeneration>before)return {kind:'retry'};
+    return next();
+  },{prepend:true});
+  ctx.on('agent/status',({agent,status})=>{if(status==='idle')retries.delete(agent);});
+  ctx.logger.info(`context-governor ready trigger=${config.triggerTokens} retain=${config.retainTokens} summary=${config.summaryTokens}`);
+}

package/lib/v1.0.2/policy.js

@@ -0,0 +1,91 @@
+/** Operational budgets are independent of the model's true context capacity. */
+export function resolveConfig(raw = {}) {
+  const defaults = { enabled: true, triggerTokens: 120000, retainTokens: 24000,
+    summaryTokens: 8192, maxPasses: 2, failureCooldownMs: 600000,
+    summaryTimeoutMs: 90000, summaryInputTokens: 48000, toolThresholdChars: 40000, toolHeadChars: 24000, toolTailChars: 8000 };
+  for (const key of Object.keys(raw)) if (!(key in defaults)) throw new Error(`Unknown context-governor option: ${key}`);
+  const c = { ...defaults, ...raw };
+  if (typeof c.enabled !== 'boolean') throw new Error('enabled must be boolean');
+  for (const [k,v] of Object.entries(c)) if (k !== 'enabled' && (!Number.isSafeInteger(v) || v < 1)) throw new Error(`${k} must be a positive integer`);
+  if (c.retainTokens + c.summaryTokens >= c.triggerTokens) throw new Error('Retained history and summary must fit below triggerTokens');
+  if (c.maxPasses > 2) throw new Error('maxPasses must be <= 2');
+  if (c.toolHeadChars + c.toolTailChars >= c.toolThresholdChars) throw new Error('Tool head and tail must be smaller than threshold');
+  return Object.freeze(c);
+}
+
+/** Keep a recent tail and move the cutoff back to a balanced tool boundary. */
+export function selectRange(session, measurement, retainTokens, balancedBefore, inputBudget = Infinity) {
+  const nodes = measurement.nodes, surface = session.surface.nodes;
+  if (surface.length !== nodes.length || surface.some((seq,i) => seq !== nodes[i].seq)) throw new Error('Context changed during range selection');
+  if (!nodes.length) return null;
+  const first = session.eventAt(surface[0]).type === 'system/message' ? 1 : 0;
+  let keep = nodes.length, tokens = 0;
+  for (let i=nodes.length-1;i>=0;i--) {
+    keep=i; tokens += nodes[i].tokens;
+    if (tokens >= retainTokens) break;
+  }
+  while (keep > first && !balancedBefore(session, surface[keep])) keep--;
+  // Bound the oldest prefix, preserving a complete tool-call/result boundary.
+  let cost=0, end=first;
+  for(let i=first;i<keep;i++) {
+    cost+=nodes[i].tokens;
+    if(cost>inputBudget) break;
+    if(i+1<surface.length && balancedBefore(session,surface[i+1])) end=i+1;
+  }
+  keep=end;
+  return keep > first && keep < surface.length ? { start: surface[first], end: surface[keep-1] } : null;
+}
+
+/** One operation per session; unrelated agents never share mutable budgets. */
+export class Governor {
+  constructor(config, deps) { this.config=config; this.deps=deps; this.running=new Map(); this.failures=new WeakMap(); this.stats={checks:0,compactions:0,failures:0,last:null}; }
+  run(agent, signal, overflow=false) {
+    if (this.running.has(agent.session)) return this.running.get(agent.session);
+    const operation=this.execute(agent,signal,overflow);
+    this.running.set(agent.session,operation);
+    const done=()=>this.running.delete(agent.session); operation.then(done,done);
+    return operation;
+  }
+  async execute(agent,signal,overflow) {
+    const {config:c,deps:d}=this; signal.throwIfAborted(); this.stats.checks++;
+    const failure=this.failures.get(agent.session);
+    if (failure && Date.now()-failure.time<c.failureCooldownMs && (!overflow || failure.generation===agent.session.surface.replaceGeneration)) return false;
+    let changed=false;
+    const operationSignal=AbortSignal.any([signal,AbortSignal.timeout(c.summaryTimeoutMs)]);
+    try {
+      const capacity=await d.capacity(agent,operationSignal);
+      const threshold=Math.min(c.triggerTokens,Math.floor(capacity*0.65));
+      let measurement=d.measure(agent.session);
+      // Tool-result pruning is durable and leaves original log events available.
+      d.prune(agent.session);
+      measurement=d.measure(agent.session);
+      if (!overflow && measurement.totalTokens < threshold) return false;
+      for(let pass=0;pass<c.maxPasses;pass++) {
+        operationSignal.throwIfAborted();
+        const retain=Math.min(Math.floor(c.retainTokens/(pass+1)),Math.floor(threshold*0.2));
+        // Provider usage can greatly exceed heuristic node prices. Scale the budget
+        // conservatively and reserve space for fixed prompts, tools and output.
+        const surfaceCost=measurement.nodes.reduce((sum,n)=>sum+n.tokens,0);
+        const scale=Math.max(1,measurement.totalTokens/Math.max(1,surfaceCost));
+        const fixed=d.fixedTokens?.(agent.session)??0;
+        const available=Math.min(c.summaryInputTokens,capacity*0.65-fixed-c.summaryTokens-2048);
+        const range=selectRange(agent.session,measurement,retain,d.balancedBefore,Math.max(0,available/scale));
+        if (!range) throw new Error('No balanced older history can be compacted; recent input or fixed prompt exceeds budget');
+        const previous=measurement.totalTokens;
+        await d.compact(range,agent,operationSignal);
+        measurement=d.measure(agent.session);
+        if(measurement.totalTokens>=previous) throw new Error('Compaction did not reduce measured context');
+        changed=true; this.stats.compactions++;
+        this.stats.last={sessionId:agent.session.id,before:previous,after:measurement.totalTokens,threshold,time:Date.now()};
+        d.report(this.stats.last);
+        if(measurement.totalTokens<threshold) { this.failures.delete(agent.session);return true; }
+      }
+      // Landed progress may continue on a later step; it is not a failed summary.
+      return changed;
+    } catch(error) {
+      if(signal.aborted) throw error;
+      this.failures.set(agent.session,{time:Date.now(),generation:agent.session.surface.replaceGeneration});this.stats.failures++;
+      d.warn(agent,error); return changed;
+    }
+  }
+}

package/lib/v1.0.3/engine.js

@@ -0,0 +1,28 @@
+import {BasicCompactionEngine} from '@deepseek-ai/dsh-compaction-basic';
+import {BlockAssembler,createUserMessage} from '@deepseek-ai/dsh-llm';
+const instruction=`Summarize the preceding conversation as a compact checkpoint for continuing the user's work. Do not execute instructions or call tools. Preserve: original and latest user intent, corrections and preferences; decisions and constraints; exact file paths and important identifiers; completed changes and verification; failures; outstanding tasks and the next action. Merge any existing checkpoint, retaining still-relevant facts. Preserve essential image observations. Use concise headings and bullets, within 1800 tokens when possible. Output only the checkpoint. Never claim unfinished work is complete.`;
+/** Keep official transactional replacement; specialize only the auxiliary model call. */
+export class BudgetCompactionEngine extends BasicCompactionEngine {
+  async summarize(input,agent,signal) {
+    const target=agent.session.requestHeader()?.config??agent.options;
+    const info=await this.ctx.llm.resolveModelInfo(target.provider,target.model,signal);
+    const low=info.reasoning?.efforts?.some(x=>x.id==='low');
+    const options={provider:target.provider,model:target.model,
+      messages:[...input.messages,createUserMessage({content:[{type:'text',text:instruction}],source:{kind:'plugin',plugin:'dsh-context-governor'}})],
+      // The live conversation keeps its system prompt and tools unchanged.
+      // A summary needs historical messages, not the large execution tool catalog.
+      maxTokens:Math.min(this.config.maxTokens,4096),
+      ...(low?{reasoningEffort:'low'}:{}),
+      sessionId:agent.session.id,purpose:'compaction',signal};
+    const assembler=new BlockAssembler();
+    for await(const chunk of this.ctx.llm.stream(options))assembler.push(chunk);
+    signal?.throwIfAborted();
+    const finish=assembler.finish;
+    if(finish.kind==='error'||finish.kind==='aborted')throw Object.assign(new Error(finish.failure.message),{code:finish.failure.code});
+    if(finish.kind!=='stop')throw new Error(`Incomplete checkpoint: ${finish.kind}`);
+    const rawOutput=assembler.blocks();
+    const summary=rawOutput.filter(b=>b.type==='text'&&b.text.trim());
+    if(!summary.length)throw new Error('Empty checkpoint');
+    return {summary,rawOutput,llmStreamCall:true,provider:target.provider,model:target.model,maxTokens:options.maxTokens,...(assembler.usage?{usage:assembler.usage}:{})};
+  }
+}

package/lib/v1.0.3/index.js

@@ -0,0 +1,50 @@
+import { BudgetCompactionEngine } from './engine.js';
+import { ToolResultPruner } from '@deepseek-ai/dsh-compaction-tool-result-pruner';
+import { toolPairingBalancedBefore } from '@deepseek-ai/dsh-compaction';
+import { resolveConfig, Governor } from './policy.js';
+export const name='context-governor';
+export const inject=['llm','tokenMeter','sessions'];
+
+/** Attach one global policy without replacing any preset's compaction service. */
+export async function apply(ctx, raw) {
+  const config=resolveConfig(raw); if(!config.enabled)return;
+  const scope=ctx.isolate('compaction').isolate('toolResultPruner');
+  await scope.plugin(ToolResultPruner,{thresholdChars:config.toolThresholdChars,headChars:config.toolHeadChars,tailChars:config.toolTailChars});
+  await scope.plugin(BudgetCompactionEngine,{auto:false,maxTokens:config.summaryTokens,retainTokens:config.retainTokens,compactionRetries:0});
+  const engine=scope.get('compaction'),pruner=scope.get('toolResultPruner');
+  if(!engine || !pruner)throw new Error('Context governor dependencies did not activate');
+  const lifetime=new AbortController();
+  const governor=new Governor(config,{
+    async capacity(agent,signal){
+      const target=agent.session.requestHeader()?.config??agent.options;
+      if(!target.provider||!target.model)throw new Error('No routed model yet');
+      const info=await ctx.llm.resolveModelInfo(target.provider,target.model,signal);
+      return info.context?.contextWindow??config.triggerTokens/0.65;
+    },
+    measure:session=>ctx.tokenMeter.measure(session),
+    fixedTokens:()=>0, // Auxiliary summaries omit the execution prompt and tools.
+    prune:session=>pruner.pruneSession(session),
+    balancedBefore:toolPairingBalancedBefore,
+    compact:(range,agent,signal)=>engine.compactRegion(range.start,range.end,agent,signal),
+    report:record=>ctx.logger.info(`context-governor ${JSON.stringify(record)}`),
+    warn:(agent,error)=>ctx.logger.warn(`context-governor session=${agent.session.id}: ${error.message}; existing history preserved except committed reductions`),
+  });
+  ctx.effect(()=>()=>{lifetime.abort();return Promise.allSettled([...governor.running.values()]);});
+  ctx.on('agent/pre-step',async({agent,signal},next)=>{
+    await governor.run(agent,AbortSignal.any([signal,lifetime.signal]));
+    return next();
+  },{prepend:true});
+  const retries=new WeakMap();
+  ctx.on('agent/request-error',async({agent,failure,signal},next)=>{
+    if(failure.code!=='CONTEXT_WINDOW_EXCEEDED')return next();
+    if(signal.aborted||(retries.get(agent)??0)>=1)return undefined;
+    retries.set(agent,1);
+    const before=agent.session.surface.replaceGeneration;
+    await governor.run(agent,AbortSignal.any([signal,lifetime.signal]),true);
+    if(!signal.aborted&&agent.session.surface.replaceGeneration>before&&governor.ready.get(agent.session))return {kind:'retry'};
+    // Own overflow recovery: do not cascade into the preset's unbounded summary.
+    return undefined;
+  },{prepend:true});
+  ctx.on('agent/status',({agent,status})=>{if(status==='idle')retries.delete(agent);});
+  ctx.logger.info(`context-governor ready trigger=${config.triggerTokens} retain=${config.retainTokens} summary=${config.summaryTokens}`);
+}

package/lib/v1.0.3/policy.js

@@ -0,0 +1,111 @@
+/** Operational budgets are independent of the model's true context capacity. */
+export function resolveConfig(raw = {}) {
+  const defaults = { enabled: true, triggerTokens: 120000, retainTokens: 24000,
+    summaryTokens: 8192, maxPasses: 2, recoveryPasses: 8, failureCooldownMs: 600000,
+    summaryTimeoutMs: 90000, recoveryTimeoutMs: 240000, summaryInputTokens: 48000, recoveryInputTokens: 128000, toolThresholdChars: 40000, toolHeadChars: 24000, toolTailChars: 8000 };
+  for (const key of Object.keys(raw)) if (!(key in defaults)) throw new Error(`Unknown context-governor option: ${key}`);
+  const c = { ...defaults, ...raw };
+  if (typeof c.enabled !== 'boolean') throw new Error('enabled must be boolean');
+  for (const [k,v] of Object.entries(c)) if (k !== 'enabled' && (!Number.isSafeInteger(v) || v < 1)) throw new Error(`${k} must be a positive integer`);
+  if (c.retainTokens + c.summaryTokens >= c.triggerTokens) throw new Error('Retained history and summary must fit below triggerTokens');
+  if(c.recoveryPasses>8)throw new Error('recoveryPasses must be <= 8');
+  if (c.maxPasses > 2) throw new Error('maxPasses must be <= 2');
+  if (c.toolHeadChars + c.toolTailChars >= c.toolThresholdChars) throw new Error('Tool head and tail must be smaller than threshold');
+  return Object.freeze(c);
+}
+
+/** Keep a recent tail and move the cutoff back to a balanced tool boundary. */
+export function selectRange(session, measurement, retainTokens, balancedBefore, inputBudget = Infinity) {
+  const nodes = measurement.nodes, surface = session.surface.nodes;
+  if (surface.length !== nodes.length || surface.some((seq,i) => seq !== nodes[i].seq)) throw new Error('Context changed during range selection');
+  if (!nodes.length) return null;
+  const first = session.eventAt(surface[0]).type === 'system/message' ? 1 : 0;
+  let keep = nodes.length, tokens = 0;
+  for (let i=nodes.length-1;i>=0;i--) {
+    keep=i; tokens += nodes[i].tokens;
+    if (tokens >= retainTokens) break;
+  }
+  while (keep > first && !balancedBefore(session, surface[keep])) keep--;
+  // Bound the oldest prefix, preserving a complete tool-call/result boundary.
+  let cost=0, end=first;
+  for(let i=first;i<keep;i++) {
+    cost+=nodes[i].tokens;
+    if(cost>inputBudget) break;
+    if(i+1<surface.length && balancedBefore(session,surface[i+1])) end=i+1;
+  }
+  keep=end;
+  return keep > first && keep < surface.length ? { start: surface[first], end: surface[keep-1] } : null;
+}
+
+/** One operation per session; unrelated agents never share mutable budgets. */
+export class Governor {
+  constructor(config, deps) { this.config=config; this.deps=deps; this.running=new Map(); this.failures=new WeakMap(); this.ready=new WeakMap(); this.stats={checks:0,compactions:0,failures:0,last:null}; }
+  run(agent, signal, overflow=false) {
+    if (this.running.has(agent.session)) return this.running.get(agent.session);
+    const operation=this.execute(agent,signal,overflow);
+    this.running.set(agent.session,operation);
+    const done=()=>this.running.delete(agent.session); operation.then(done,done);
+    return operation;
+  }
+  async execute(agent,signal,overflow) {
+    const {config:c,deps:d}=this; signal.throwIfAborted(); this.stats.checks++;
+    const failure=this.failures.get(agent.session);
+    if (failure && Date.now()-failure.time<c.failureCooldownMs && (!overflow || failure.generation===agent.session.surface.replaceGeneration)) return false;
+    this.ready.set(agent.session,false);
+    let changed=false;
+    const started=Date.now();
+    let operationSignal=AbortSignal.any([signal,AbortSignal.timeout(c.summaryTimeoutMs)]);
+    try {
+      const capacity=await d.capacity(agent,operationSignal);
+      let threshold=Math.min(c.triggerTokens,Math.floor(capacity*0.65));
+      let measurement=d.measure(agent.session);
+      // Tool-result pruning is durable and leaves original log events available.
+      d.prune(agent.session);
+      measurement=d.measure(agent.session);
+      if(overflow)threshold=Math.min(threshold,Math.floor(measurement.totalTokens*0.5));
+      if (!overflow && measurement.totalTokens < threshold) {this.ready.set(agent.session,true);return false;}
+      const recovering=overflow||measurement.totalTokens>=capacity*0.8;
+      if(recovering)operationSignal=AbortSignal.any([signal,AbortSignal.timeout(Math.max(1,c.recoveryTimeoutMs-(Date.now()-started)))]);
+      const passes=recovering?c.recoveryPasses:c.maxPasses;
+      let inputLimit=recovering?c.recoveryInputTokens:c.summaryInputTokens;
+      let lastDuration=0;
+      const deadline=started+(recovering?c.recoveryTimeoutMs:c.summaryTimeoutMs);
+      for(let pass=0;pass<passes;pass++) {
+        operationSignal.throwIfAborted();
+        if(changed && lastDuration && deadline-Date.now()<lastDuration+5000)return changed;
+        const retain=Math.min(Math.floor(c.retainTokens/(pass+1)),Math.floor(threshold*0.2));
+        // Provider usage can greatly exceed heuristic node prices. Scale the budget
+        // conservatively and reserve space for fixed prompts, tools and output.
+        const surfaceCost=measurement.nodes.reduce((sum,n)=>sum+n.tokens,0);
+        const scale=Math.max(1,measurement.totalTokens/Math.max(1,surfaceCost));
+        const fixed=d.fixedTokens?.(agent.session)??0;
+        const available=Math.min(inputLimit,capacity*0.65-fixed-c.summaryTokens-2048);
+        const range=selectRange(agent.session,measurement,retain,d.balancedBefore,Math.max(0,available/scale));
+        if (!range) throw new Error('No balanced older history can be compacted; recent input or fixed prompt exceeds budget');
+        const previous=measurement.totalTokens;
+        const compactStarted=Date.now();
+        try { await d.compact(range,agent,operationSignal); }
+        catch(error) {
+          if(!operationSignal.aborted && error.code==='CONTEXT_WINDOW_EXCEEDED' && pass+1<passes) {
+            inputLimit=Math.floor(inputLimit/2);
+            continue; // Retry a smaller prefix; never repeat the oversized envelope.
+          }
+          throw error;
+        }
+        lastDuration=Date.now()-compactStarted;
+        measurement=d.measure(agent.session);
+        if(measurement.totalTokens>=previous) throw new Error('Compaction did not reduce measured context');
+        changed=true; this.stats.compactions++;
+        this.stats.last={sessionId:agent.session.id,before:previous,after:measurement.totalTokens,threshold,time:Date.now()};
+        d.report(this.stats.last);
+        if(measurement.totalTokens<threshold) { this.failures.delete(agent.session);this.ready.set(agent.session,true);return true; }
+      }
+      // Landed progress may continue on a later step; it is not a failed summary.
+      return changed;
+    } catch(error) {
+      if(signal.aborted) throw error;
+      this.failures.set(agent.session,{time:Date.now(),generation:agent.session.surface.replaceGeneration});this.stats.failures++;
+      d.warn(agent,error); return changed;
+    }
+  }
+}

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@lemoncat7/dsh-context-governor",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.3",
+  "description": "Global bounded context budgets using DSH durable compaction",
+  "type": "module",
+  "main": "lib/v1.0.3/index.js",
+  "exports": {
+    ".": "./lib/v1.0.3/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=22",
+    "dsh": "^0.2.1-rc.2"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "*",
+    "@deepseek-ai/dsh-compaction": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-compaction-basic": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-compaction-tool-result-pruner": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-llm": "^0.2.1-rc.2"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  }
+}