billion-context-dsh 0.1.4 → 0.1.6

package/dist/region.d.ts

@@ -10,7 +10,7 @@
  * decompress/search/status can rebuild everything from the log.
  * @module billion-context-dsh/region
  */
-import type { Session, SessionEvent } from '@deepseek-ai/dsh-session';
+import type { Session, SessionEvent, SessionEventMap } from '@deepseek-ai/dsh-session';
 import { type ContentBlock } from '@deepseek-ai/dsh-llm';
 /** One durable ACP block as rebuilt from the session log. */
 export interface AcpBlockLedgerEntry {
@@ -21,6 +21,19 @@ export interface AcpBlockLedgerEntry {
     readonly shadowedTokenCount: number;
     readonly start: number;
     readonly end: number;
+    /** Compression tier: 1 (message range), 2 (distills tier-1 blocks), 3 (distills tier-2 blocks). Legacy blocks default to 1. */
+    readonly tier: 1 | 2 | 3;
+    /** Compaction ids of the blocks this block distilled (parents). Empty for tier-1 blocks. */
+    readonly parentBlockIds: readonly string[];
+    /** The acp-kernel block id (`bN`) created for this transaction — absent for legacy blocks (synthesised by order). */
+    readonly kernelBlockId?: string;
+    /** The surface seq of this block's checkpoint summary node (derived from the log; null when the node is gone). */
+    readonly summarySeq?: number;
+    /** The kernel block's raw direct/effective message ids at creation (recorded since the tier feature; absent for legacy). */
+    readonly directMessageIds?: readonly string[];
+    readonly effectiveMessageIds?: readonly string[];
+    /** Unix epoch ms of the compaction/summary event. */
+    readonly createdAt: number;
 }
 /** The open turn number, or null when the log ends between turns. */
 export declare function findOpenTurn(events: readonly SessionEvent[]): number | null;
@@ -51,7 +64,40 @@ export interface CompactionTransactionInput {
     readonly shadowedTokenCount: number;
     readonly provider: string;
     readonly model: string;
+    /** Compression tier of this block (default 1). */
+    readonly tier?: 1 | 2 | 3;
+    /** The acp-kernel block id (`bN`) created by the kernel for this transaction. */
+    readonly kernelBlockId?: string;
+    /** Compaction ids of the blocks distilled into this one. */
+    readonly parentBlockIds?: readonly string[];
+    /** The kernel block's direct/effective message ids (raw CoreMessage ids) — recorded for faithful rehydration. */
+    readonly directMessageIds?: readonly string[];
+    readonly effectiveMessageIds?: readonly string[];
 }
+/**
+ * ACP tier extension fields carried on `compaction/summary` events. The
+ * upstream dsh-compaction event type does not know them, so reads and writes
+ * go through this precise intersection (never `any`).
+ */
+export interface AcpCompactionSummaryFields {
+    /** Compression tier (1/2/3) — 1 = message range, 2 = distills tier-1, 3 = distills tier-2. */
+    readonly tier?: 1 | 2 | 3;
+    /** The acp-kernel block id (`bN`) created for this transaction. */
+    readonly kernelBlockId?: string;
+    /** Durable compaction ids of the blocks distilled into this one. */
+    readonly parentBlockIds?: readonly string[];
+    /**
+     * The kernel block's direct message ids (raw CoreMessage ids) at creation —
+     * recorded so a restarted engine rehydrates the SAME coverage (a tier-2
+     * block's coverage is its parents' originals, not the checkpoint node).
+     */
+    readonly directMessageIds?: readonly string[];
+    /** The kernel block's effective message ids (raw CoreMessage ids) at creation. */
+    readonly effectiveMessageIds?: readonly string[];
+}
+type CompactionSummaryData = SessionEventMap['compaction/summary'];
+/** Read a `compaction/summary` event's data including the ACP tier extension fields. */
+export declare function readCompactionSummary(event: SessionEvent): CompactionSummaryData & AcpCompactionSummaryFields;
 /**
  * Run one durable compression transaction. Throws on invalid state; on success
  * the four events are in the log and the surface has one summary node.
@@ -90,3 +136,44 @@ export declare function buildCompressibleSeqRanges(session: Session, opts?: {
  * without blind probing.
  */
 export declare function surfaceSummary(session: Session): string;
+/** One block as seen by the tier machinery: durable id ↔ kernel ref (`bN`). */
+export interface AcpBlockRegistryEntry {
+    /** The durable compaction id. */
+    readonly blockId: string;
+    /** The acp-kernel block ref (`bN`); synthesised by log order for legacy blocks. */
+    readonly kernelBlockId: string;
+    readonly tier: 1 | 2 | 3;
+    /** The surface seq of this block's checkpoint summary node (null when gone). */
+    readonly summarySeq: number | null;
+    /** True until a LATER block distills this one. Only active blocks are distillable. */
+    readonly active: boolean;
+    readonly parentBlockIds: readonly string[];
+}
+/**
+ * Rebuild the compactionId ↔ kernel-block-ref registry from the durable log.
+ * Legacy blocks (pre-tier, no recorded `kernelBlockId`) are synthesised as
+ * `b1`, `b2`, … in log order; recorded ids are kept as-is. A block is active
+ * until a later block lists it as a parent.
+ */
+export declare function blockRegistry(session: Session): AcpBlockRegistryEntry[];
+/**
+ * The kernel block ref (`bN`) for a surface seq, when that seq is the
+ * checkpoint summary node of a block — the edge the model must use to
+ * distill (T2/T3). Active blocks distill; a stale (already-distilled) node
+ * still maps to its `bN` so the kernel reports "already compressed" instead
+ * of silently folding the summary as a plain message. Returns null for
+ * anything else (plain messages, non-checkpoint nodes).
+ */
+export declare function blockRefForSummarySeq(session: Session, seq: number): string | null;
+/** The durable compaction ids distilled by the given kernel block refs (`bN`). */
+export declare function compactionIdsOfKernelBlocks(session: Session, kernelBlockIds: readonly string[]): string[];
+/** The checkpoint summary seq of an ACTIVE kernel block (`bN`), or null. */
+export declare function summarySeqOfKernelBlock(session: Session, kernelBlockId: string): number | null;
+/**
+ * The shadowed seqs of a block, recursing into distilled parent blocks: a
+ * tier-2 block shadows its parent's checkpoint node, so recovering its
+ * originals requires expanding that node into the parent block's own shadowed
+ * seqs. Cycle-safe (a block can never be its own ancestor).
+ */
+export declare function expandShadowedSeqs(session: Session, blockId: string): number[];
+export {};

package/dist/state.d.ts

@@ -7,6 +7,13 @@
  * summary re-derive the block ledger (`rebuildBlockLedger` in region.ts), so a
  * restarted engine can answer decompress/search/status from the session log
  * alone — DSH's "log is the source of truth" model.
+ *
+ * Tier-2/3 distillation additionally requires the kernel state to KNOW the
+ * blocks: `syncBlocks` deactivates a block whose consumed messages are absent
+ * from the message array, and `resolveBoundaries` refuses to anchor a block
+ * ref it cannot find — so on first access for a session that already has
+ * durable blocks (e.g. after a server restart), the kernel blocks are
+ * REHYDRATED from the ledger before use. Live updates continue through `set`.
  * @module billion-context-dsh/state
  */
 import type { Session } from '@deepseek-ai/dsh-session';

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\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. 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.";
 /** 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.4",
+	"version": "0.1.6",
 	"description": "Active Context Pruning (ACP) for the DeepSeek Harness — model-driven context management as a CompactionEngine backend.",
 	"type": "module",
 	"main": "dist/index.js",