billion-context-dsh 0.1.5 → 0.1.7

package/dist/region.d.ts

@@ -39,21 +39,49 @@ export interface AcpBlockLedgerEntry {
 export declare function findOpenTurn(events: readonly SessionEvent[]): number | null;
 /** Reject a second concurrent compaction for the same session. */
 export declare function assertNoActiveCompaction(events: readonly SessionEvent[]): void;
+/**
+ * A requested range whose EVERY live message was already shadowed by one or
+ * more blocks. The compress tool catches this and reports the range as already
+ * compressed (with the covering block ids) instead of folding block summary
+ * nodes as plain messages or erroring out. Distillation stays an explicit act:
+ * target a LIVE checkpoint seq directly to distill (tier 2/3).
+ */
+export declare class AlreadyCompressedRangeError extends Error {
+    readonly start: number;
+    readonly end: number;
+    readonly coveringBlockIds: readonly string[];
+    constructor(start: number, end: number, coveringBlockIds: readonly string[]);
+}
+export interface ResolvedSurfaceRange {
+    readonly start: number;
+    readonly end: number;
+    /**
+     * True when the requested edges were not on the current surface and were
+     * remapped to the still-live content of the requested span (an earlier
+     * compression shadowed them). Callers surface this so the model sees what
+     * was actually compressed instead of silently shadowing a different span.
+     */
+    readonly recovered?: boolean;
+}
 /**
  * Validate one inclusive surface span and adjust its edges to a
- * tool-pairing-balanced range whose boundaries carry a bare-seq ref. Missing
- * or reversed ranges still throw. An edge that sits inside a tool-call/result
- * pair — or on a multi-tool-call assistant message that has no bare-seq ref —
- * is first nudged inward to the nearest clean cut; if that collapses the range
- * (e.g. the model asked for a SINGLE tool result, which can never be balanced
- * alone), the range EXPANDS outward to the enclosing clean pair instead — a
- * lone tool message is almost always a "consumed output" the model genuinely
- * wants to compress. The returned range is what a caller should actually shadow.
+ * tool-pairing-balanced range whose boundaries carry a bare-seq ref. Reversed
+ * ranges throw. An edge that sits inside a tool-call/result pair — or on a
+ * multi-tool-call assistant message that has no bare-seq ref — is first nudged
+ * inward to the nearest clean cut; if that collapses the range (e.g. the model
+ * asked for a SINGLE tool result, which can never be balanced alone), the
+ * range EXPANDS outward to the enclosing clean pair instead — a lone tool
+ * message is almost always a "consumed output" the model genuinely wants to
+ * compress. The returned range is what a caller should actually shadow.
+ *
+ * Missing edges are NOT an immediate error: the seqs were probably shadowed by
+ * an earlier compression (stale nudge table / old compress result). The span
+ * is rebuilt from its still-live remainder via recoverStaleRange — a fully
+ * shadowed span throws AlreadyCompressedRangeError, a genuinely unknown edge
+ * throws the not-in-surface guidance error. The returned range is what a
+ * caller should actually shadow.
  */
-export declare function resolveSurfaceRange(session: Session, start: number, end: number): {
-    start: number;
-    end: number;
-};
+export declare function resolveSurfaceRange(session: Session, start: number, end: number): ResolvedSurfaceRange;
 /** The surface seqs shadowed by the inclusive positional span. */
 export declare function shadowedSeqsOf(session: Session, start: number, end: number): number[];
 export interface CompactionTransactionInput {

package/dist/system-prompt.d.ts

@@ -6,6 +6,6 @@
  * to compress (never "compress now").
  * @module billion-context-dsh/system-prompt
  */
-export declare const ACP_SYSTEM_PROMPT = "Active Context Pruning \u2014 model-driven context management\n\nYOU decide whether and when to compress context. Nothing forces you: the injected \"nudge\" is a suggestion, not an order, and you may ignore it when compression would not help. Compress only ranges you have genuinely consumed (read tool outputs, finished explorations, superseded steps) that the current work no longer needs verbatim.\n\nCompression Philosophy:\n- All compression serves the primary task, but be frugal.\n- Context capacity is precious. Save context by compressing consumed outputs, not by avoiding tools.\n- Compress by need, not by percentage.\n- Work from summaries, not raw tool outputs. All listed ranges (user prompts, tool outputs, code, logs, exploration, intermediate steps) should be compressed to summary format \u2014 the ONLY exceptions are protected content, content the current step is actively using, or critical content you cannot reconstruct.\n\nCompression tools (refs are SURFACE SEQS, not ids):\n- compress: replace one or more seq ranges, each with your own dense summary. Single range: compress({ content: [{ startSeq, endSeq, summary }] }). Batch multiple unrelated segments in one call (each entry becomes its own block): compress({ content: [{ startSeq: 1, endSeq: 5, summary: '...' }, { startSeq: 12, endSeq: 18, summary: '...' }] }). Keep ranges disjoint \u2014 overlapping entries in one batch are skipped. Edges are auto-balanced to tool-call/result boundaries; a trailing #callId fragment in a seq is ignored. Ranges must be on the current surface \u2014 stale seqs fail with guidance.\n- decompress: recover a compressed block's original content, read-only. decompress({ blockId }).\n- search_context: find information inside compressed blocks BEFORE decompressing. search_context({ query }).\n- acp_status: current context usage and the live compressible-range list. Run it before compressing when in doubt.\n\nTiered compression: each compressed block appears on the surface as one summary node. Compressing that node again DISTILLS the block (tier 2): the parent summary folds into your new summary and the original messages are freed. Distilling a tier-2 block yields tier 3. Distill when a summary itself is consumed \u2014 decompress on the tier-2 block recovers the full originals.\n\nWhen you write a summary, it becomes the ONLY record of that range: keep file paths, signatures, exact values, decisions, and error strings verbatim so a later reader (or you, after decompress) can continue without the original. Never reuse historical seqs \u2014 the surface moves as messages land and compress; verify with acp_status.";
+export declare const ACP_SYSTEM_PROMPT = "Active Context Pruning \u2014 model-driven context management\n\nYOU decide whether and when to compress context. Nothing forces you: the injected \"nudge\" is a suggestion, not an order, and you may ignore it when compression would not help. Compress only ranges you have genuinely consumed (read tool outputs, finished explorations, superseded steps) that the current work no longer needs verbatim.\n\nCompression Philosophy:\n- All compression serves the primary task, but be frugal.\n- Context capacity is precious. Save context by compressing consumed outputs, not by avoiding tools.\n- Compress by need, not by percentage.\n- Work from summaries, not raw tool outputs. All listed ranges (user prompts, tool outputs, code, logs, exploration, intermediate steps) should be compressed to summary format \u2014 the ONLY exceptions are protected content, content the current step is actively using, or critical content you cannot reconstruct.\n\nCompression tools (refs are SURFACE SEQS, not ids):\n- compress: replace one or more seq ranges, each with your own dense summary. Single range: compress({ content: [{ startSeq, endSeq, summary }] }). Batch multiple unrelated segments in one call (each entry becomes its own block): compress({ content: [{ startSeq: 1, endSeq: 5, summary: '...' }, { startSeq: 12, endSeq: 18, summary: '...' }] }). Keep ranges disjoint \u2014 overlapping entries in one batch are skipped. Edges are auto-balanced to tool-call/result boundaries; a trailing #callId fragment in a seq is ignored. Seq refs must be on the current surface: seqs from older nudges or earlier compresses go stale as the surface moves, so a stale span is auto-remapped to its still-live remainder (the result reports the adjusted span), a fully compressed span is reported as already compressed, and invented/other-session seqs fail with guidance.\n- decompress: recover a compressed block's original content, read-only. decompress({ blockId }).\n- search_context: find information inside compressed blocks BEFORE decompressing. search_context({ query }).\n- acp_status: current context usage and the live compressible-range list. Run it right before compressing \u2014 the only seqs that never go stale are the ones you just read.\n\nTiered compression: each compressed block appears on the surface as one summary node. Compressing that node again DISTILLS the block (tier 2): the parent summary folds into your new summary and the original messages are freed. Distilling a tier-2 block yields tier 3. Distill when a summary itself is consumed \u2014 decompress on the tier-2 block recovers the full originals.\n\nWhen you write a summary, it becomes the ONLY record of that range: keep file paths, signatures, exact values, decisions, and error strings verbatim so a later reader (or you, after decompress) can continue without the original. Never reuse historical seqs \u2014 the surface moves as messages land and compress; verify with acp_status.";
 /** System-prompt section order: tool guidance lives in 100–199. */
 export declare const ACP_SYSTEM_PROMPT_ORDER = 150;

package/dist/tools.d.ts

@@ -11,11 +11,15 @@
  */
 import { type ToolDefinition } from '@deepseek-ai/dsh-tools';
 import { type CompressionCore } from 'acp-kernel';
+import type { Agent } from '@deepseek-ai/dsh-agent';
 import type { AcpStateStore } from './state.ts';
 import { type KernelConfigInput } from './config.ts';
+import { type AcpWindow } from './window.ts';
 export interface ToolEnvironment extends KernelConfigInput {
     readonly kernel: CompressionCore;
     readonly store: AcpStateStore;
+    /** Resolve the effective context window for an agent (optional: status falls back to modelContextLimit). */
+    readonly windowFor?: (agent: Agent) => Promise<AcpWindow>;
 }
 /** Build the four ACP model tools bound to one engine. */
 export declare function makeTools(env: ToolEnvironment): ToolDefinition[];

package/dist/window.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Auto context-window detection — resolve the model's real context window
+ * from the host LLM runtime instead of trusting a hardcoded config default.
+ *
+ * `agent.ctx.llm` (the cordis `LlmRuntime` service) exposes
+ * `resolveModelInfo(provider, model)` → `{ context: { contextWindow } }`, the
+ * exact-route capacity the adapter learned from the provider API (pi-ai reads
+ * `context_window`/`context_length` during discovery). Probing is a standalone
+ * capability query — no request is sent.
+ * @module billion-context-dsh/window
+ */
+import type { Agent } from '@deepseek-ai/dsh-agent';
+/** Fallback window when auto-detection is unavailable. Same default as acp-kernel's `defaultConfig`. */
+export declare const DEFAULT_CONTEXT_WINDOW = 128000;
+/** The effective context window plus where it came from. */
+export interface AcpWindow {
+    /** Effective context window in tokens. */
+    readonly limit: number;
+    /** Where the limit came from. */
+    readonly source: 'explicit' | 'auto' | 'default';
+    /** Route the auto window was resolved for (auto source only). */
+    readonly provider?: string;
+    readonly model?: string;
+}
+/** Human label for an AcpWindow's source (used by acp_status). */
+export declare function windowSourceLabel(window: AcpWindow): string;
+/**
+ * Probe the model's real context window. Returns null when the host provides
+ * no llm service, the adapter discloses no window, or the probe throws —
+ * callers fall back to DEFAULT_CONTEXT_WINDOW. Never throws.
+ */
+export declare function detectContextWindow(agent: Agent, provider: string, model: string): Promise<number | null>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "billion-context-dsh",
-	"version": "0.1.5",
+	"version": "0.1.7",
 	"description": "Active Context Pruning (ACP) for the DeepSeek Harness — model-driven context management as a CompactionEngine backend.",
 	"type": "module",
 	"main": "dist/index.js",