@dsh-cc/context-crusher 0.7.1 → 0.8.0-rc.2

package/lib/defer/pass.js

@@ -0,0 +1,288 @@
+/**
+ * Deferred-mode orchestration (design §3): the `llm/stream` first-chunk
+ * counter, the `agent/pre-step` swap pass, resume-by-fingerprint, and the
+ * per-session ledger plumbing. Extracted from the crusher service to keep
+ * `index.ts` inside the file-size budget; the crusher wires one instance
+ * and forwards its post-execute hooks.
+ *
+ * @module @dsh-cc/context-crusher/defer/pass
+ */
+import { getSessionCwd } from '@dsh-cc/session-cwd';
+import { buildMarker } from "../marker.js";
+import { route } from "../router.js";
+import { shortHash } from "../store.js";
+import { shouldCountRequest, toolResultFingerprints, wrapStreamWithCounting } from "./counter.js";
+import { DeferLedger, ResidentTable, parseTodoCounts, readDeferLedger, rebuildResidents, } from "./residents.js";
+import { attemptSwap } from "./swap.js";
+/**
+ * Owns all deferred-externalization state and listeners. Every failure
+ * degrades to a log line: observation must never break a request or a turn.
+ */
+export class Deferral {
+    deps;
+    table = new ResidentTable();
+    ledgers = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Deferred-mode seams (design §3): an `llm/stream` first-chunk counter
+     * (`{ global: true, prepend: true }` — the crusher runs in its own realm),
+     * an `agent/pre-step` swap pass, and state cleanup on session disposal.
+     */
+    registerListeners() {
+        const { ctx } = this.deps;
+        ctx.on('llm/stream', (options, next) => wrapStreamWithCounting(options, next(), (opts) => this.observeStreamFirstChunk(opts)), { global: true, prepend: true });
+        ctx.on('agent/pre-step', async ({ agent, signal }, next) => {
+            try {
+                await this.preStepPass(agent, signal);
+            }
+            catch (error) {
+                // Never break the turn over observability/compaction bookkeeping.
+                ctx.logger.warn(`context-crusher: deferred pre-step pass failed: ${String(error)}`);
+            }
+            return next();
+        });
+        ctx.on('session/disposed', (session) => {
+            this.table.delete(String(session.id));
+        });
+    }
+    /**
+     * First-chunk send counter (§3.2): one send per resident whose stored full
+     * text fingerprint appears in the outbound prompt. Main-loop purpose
+     * allowlist + owning-session guard live in {@link shouldCountRequest}.
+     */
+    observeStreamFirstChunk(options) {
+        try {
+            if (!shouldCountRequest(options, this.table.sessionIds()))
+                return;
+            const state = this.table.get(String(options.sessionId));
+            if (state === undefined)
+                return;
+            state.streamRequestCount += 1;
+            const fingerprints = toolResultFingerprints(options.messages);
+            for (const entry of state.residents.values()) {
+                if (fingerprints.has(entry.hash))
+                    entry.sentCount += 1;
+            }
+        }
+        catch (error) {
+            this.deps.ctx.logger.warn(`context-crusher: deferred send counting failed: ${String(error)}`);
+        }
+    }
+    /**
+     * One pre-step pass (§3.3): sweep aged residents, then evaluate every
+     * entry whose sent count crossed the residency threshold in one
+     * non-awaiting critical section per entry. No timers exist — eligibility
+     * is recomputed at this boundary. A failing entry never aborts the others
+     * (microcompact failure ordering).
+     */
+    async preStepPass(agent, signal) {
+        if (signal.aborted)
+            return;
+        const cfg = this.deps.effectiveConfig();
+        const store = this.deps.store();
+        const home = this.deps.home();
+        if (!cfg.enabled || cfg.deferRequests <= 0 || store === undefined || home === undefined)
+            return;
+        const session = agent.session;
+        const sessionId = String(session.id);
+        await this.ensureLoaded(sessionId, agent);
+        const state = this.table.get(sessionId);
+        if (state === undefined || state.residents.size === 0)
+            return;
+        const ledger = this.ledgerFor(sessionId);
+        const pendingRows = [];
+        const swapRow = (entry, outcome, applied, gate) => {
+            const row = ledger?.append({
+                ts: new Date().toISOString(),
+                type: 'swap',
+                hash: entry.hash,
+                callId: String(entry.callId),
+                outcome,
+                applied,
+                ...(gate === undefined ? {} : { gate }),
+            });
+            if (row !== undefined)
+                pendingRows.push(row);
+        };
+        const now = Date.now();
+        // Age sweep first: decks of stale residents cannot accumulate unboundedly.
+        for (const entry of [...state.residents.values()]) {
+            if (now - entry.createdAt > cfg.deferMaxAgeMs) {
+                state.residents.delete(entry.hash);
+                swapRow(entry, 'abandoned', false, { sentCount: entry.sentCount });
+            }
+        }
+        let projectKey;
+        try {
+            projectKey = shortHash(getSessionCwd(agent));
+        }
+        catch {
+            return;
+        }
+        // Window-pressure inputs are resolved once per pass and only when the
+        // override key is set (measure is O(surface)); without a window source
+        // the override stays inactive.
+        let sessionTokens;
+        let contextWindow;
+        if (cfg.deferUrgencyTokens !== undefined) {
+            sessionTokens = this.deps.ctx.tokenMeter.measure(session).totalTokens;
+            contextWindow = this.contextWindowOf(session);
+        }
+        for (const entry of [...state.residents.values()]) {
+            // Deviation flagged in review: doc §3.3 says `sentCount > residency`,
+            // but the title/§5 ("send twice, swap on the third request") and the
+            // approved test plan require `>=` — implemented as `>=`.
+            if (entry.sentCount < cfg.deferRequests)
+                continue;
+            try {
+                // All I/O happens BEFORE the synchronous critical section.
+                const stored = await store.get(projectKey, entry.hash);
+                const candidate = stored.ok ? route(stored.text) : null;
+                if (!stored.ok || candidate === null) {
+                    state.residents.delete(entry.hash);
+                    swapRow(entry, 'stale', false, { sentCount: entry.sentCount });
+                    continue;
+                }
+                const tokensBefore = this.estimate(stored.text);
+                const tokensAfter = this.estimate(candidate.text);
+                const stubText = `${candidate.text}\n${buildMarker(tokensBefore, tokensAfter, entry.hash)}`;
+                // ↓ synchronous critical section (staleness re-check + two appends,
+                // no yields — an in-flight request cannot interleave with a swap).
+                const result = attemptSwap({
+                    session,
+                    entry,
+                    fullText: stored.text,
+                    stubText,
+                    apply: cfg.mode === 'on',
+                    margin: cfg.deferMargin,
+                    remainingRequestsEstimate: this.table.remainingRequestsEstimate(state),
+                    ...(cfg.deferUrgencyTokens !== undefined ? { urgencyTokens: cfg.deferUrgencyTokens } : {}),
+                    ...(sessionTokens !== undefined ? { sessionTokens } : {}),
+                    ...(contextWindow !== undefined ? { contextWindow } : {}),
+                    estimateMessage: (message) => this.deps.ctx.tokenMeter.estimateMessage(message),
+                });
+                if (result.outcome === 'applied') {
+                    state.residents.delete(entry.hash);
+                    swapRow(entry, 'applied', true, result.gate);
+                }
+                else if (result.outcome === 'stale') {
+                    state.residents.delete(entry.hash);
+                    swapRow(entry, 'stale', false, { sentCount: entry.sentCount });
+                }
+                else if (result.outcome === 'dry-run') {
+                    // §3.6: intent row carries applied:false; the entry stays resident.
+                    swapRow(entry, 'dry-run', false, result.gate);
+                }
+                // gate-failed: the entry stays resident; re-evaluation is cheap and
+                // happens at every pre-step.
+            }
+            catch (error) {
+                this.deps.ctx.logger.warn(`context-crusher: deferred swap failed for ${entry.hash}: ${String(error)}`);
+            }
+        }
+        // Ledger rows are best-effort but awaited here so the pass is durable
+        // before the turn's request fires (still never throws — DeferLedger
+        // swallows I/O errors internally).
+        await Promise.all(pendingRows);
+    }
+    /** Record one resident entry (post-execute, deferral applies). */
+    async recordResident(exec, hash, tokensSaved) {
+        const agent = exec.agent;
+        const home = this.deps.home();
+        if (agent === undefined || home === undefined)
+            return;
+        const sessionId = String(agent.session.id);
+        const entry = {
+            hash,
+            callId: exec.callId,
+            sentCount: 0,
+            tokensSaved,
+            createdAt: Date.now(),
+        };
+        this.table.ensure(sessionId).residents.set(hash, entry);
+        await this.ledgerFor(sessionId)?.append({
+            ts: new Date().toISOString(),
+            type: 'resident',
+            hash,
+            callId: String(exec.callId),
+            tokensSaved,
+            createdAt: entry.createdAt,
+        });
+    }
+    /** Latest `todo_write` snapshot → the remaining-requests estimate inputs. */
+    observeTodoSnapshot(exec) {
+        if (exec.agent === undefined)
+            return;
+        const counts = parseTodoCounts(exec.arguments);
+        if (counts === undefined)
+            return;
+        const state = this.table.ensure(String(exec.agent.session.id));
+        state.todoCompleted = counts.completed;
+        state.todoPending = counts.pending;
+    }
+    /**
+     * Resume rebuild (§3.5), once per session: replay the per-session ledger
+     * and re-adopt entries whose stored text fingerprints the live surface.
+     * Session-id keying alone would strand residents across resume/fork, so
+     * the fingerprint — not the row — is the identity.
+     */
+    async ensureLoaded(sessionId, agent) {
+        const state = this.table.ensure(sessionId);
+        const store = this.deps.store();
+        const home = this.deps.home();
+        if (state.loaded || store === undefined || home === undefined)
+            return;
+        state.loaded = true;
+        try {
+            const rows = await readDeferLedger(home('ccr', 'defer', `${sessionId}.jsonl`));
+            if (rows.length === 0)
+                return;
+            const rebuilt = await rebuildResidents({
+                rows,
+                store,
+                projectKey: shortHash(getSessionCwd(agent)),
+                session: agent.session,
+            });
+            for (const [hash, entry] of rebuilt)
+                state.residents.set(hash, entry);
+        }
+        catch (error) {
+            this.deps.ctx.logger.warn(`context-crusher: deferred resume rebuild failed: ${String(error)}`);
+        }
+    }
+    /** Per-session defer ledger (constructed lazily; all writes never throw). */
+    ledgerFor(sessionId) {
+        const home = this.deps.home();
+        if (home === undefined)
+            return undefined;
+        let ledger = this.ledgers.get(sessionId);
+        if (ledger === undefined) {
+            ledger = new DeferLedger(home('ccr', 'defer', `${sessionId}.jsonl`));
+            this.ledgers.set(sessionId, ledger);
+        }
+        return ledger;
+    }
+    /** Routed model context window via the token-meter pressure projection; absent = no window source. */
+    contextWindowOf(session) {
+        try {
+            const projections = this.deps.ctx.get('sessionProjections');
+            const state = projections?.stateOf(session, 'contextPressure');
+            return typeof state?.contextWindow === 'number' && state.contextWindow > 0
+                ? state.contextWindow
+                : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Token-based sizing, same estimator as the crusher's gates and markers. */
+    estimate(text) {
+        return this.deps.ctx.tokenMeter.estimateMessage({
+            role: 'tool',
+            content: [{ type: 'text', text }],
+        });
+    }
+}
+//# sourceMappingURL=pass.js.map

package/lib/defer/pass.js.map

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

package/lib/defer/residents.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Deferred-resident bookkeeping: the in-memory per-session table, the
+ * append-only per-session JSONL ledger (`<dshHome>/ccr/defer/<sessionId>.jsonl`),
+ * and resume-by-fingerprint rebuild (design §3.1/§3.5).
+ *
+ * Rows carry NO session id — the store hash is the identity, which matches
+ * the store's own keying rule and keeps rows meaningful across resume/fork.
+ * Ledger failures are swallowed per the CCR ledger precedent: durability is
+ * best-effort, correctness never depends on it.
+ *
+ * @module @dsh-cc/context-crusher/defer/residents
+ */
+import { ToolCallId } from '@deepseek-ai/dsh-llm';
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { CrusherStore } from '../store.ts';
+/** One resident: stored immediately, sent unmodified, swapped after residency. */
+export interface ResidentEntry {
+    readonly hash: string;
+    /** Sole locator — the surface event is resolved by callId at pre-step time. */
+    readonly callId: ToolCallId;
+    /** Counted main-loop sends that included the full text (first-chunk rule). */
+    sentCount: number;
+    /** tokensBefore − tokensAfter, measured at store time. */
+    readonly tokensSaved: number;
+    /** Epoch ms when the resident was recorded (sweep reference). */
+    readonly createdAt: number;
+}
+/** Row recording that the original was stored and the result sent unmodified. */
+export interface DeferResidentRow {
+    readonly ts: string;
+    readonly type: 'resident';
+    readonly hash: string;
+    readonly callId: string;
+    readonly tokensSaved: number;
+    readonly createdAt: number;
+}
+/** Gate inputs at decision time, recorded with every swap row for the dogfood study. */
+export interface DeferGateFacts {
+    readonly sentCount: number;
+    readonly suffixTokens?: number;
+    readonly projectedSavings?: number;
+    readonly margin?: number;
+    readonly remainingRequestsEstimate?: number;
+    readonly urgencyOverride?: boolean;
+}
+/** Row recording a swap decision: applied, stale drop, age sweep, or dry-run intent. */
+export interface DeferSwapRow {
+    readonly ts: string;
+    readonly type: 'swap';
+    readonly hash: string;
+    readonly callId: string;
+    readonly outcome: 'applied' | 'stale' | 'abandoned' | 'dry-run';
+    /** §3.6: dry-run intent rows carry `applied: false`. */
+    readonly applied: boolean;
+    readonly gate?: DeferGateFacts;
+}
+export type DeferLedgerRow = DeferResidentRow | DeferSwapRow;
+/** Append-only per-session defer ledger; never throws. */
+export declare class DeferLedger {
+    private readonly filePath;
+    constructor(filePath: string);
+    /** Append one row; never throws (best-effort observability). */
+    append(row: DeferLedgerRow): Promise<void>;
+}
+/** Read every ledger row; absent/corrupt files degrade to an empty list. */
+export declare function readDeferLedger(filePath: string): Promise<DeferLedgerRow[]>;
+/**
+ * Replay ledger rows into resident candidates: resident rows add, swap rows
+ * with a committed outcome (applied/stale/abandoned) remove, dry-run intent
+ * rows leave the resident in place (nothing was applied). Candidates always
+ * resume at `sentCount: 0` (§3.5: deliberately conservative).
+ */
+export declare function foldDeferRows(rows: readonly DeferLedgerRow[]): Map<string, ResidentEntry>;
+export interface RebuildDeps {
+    readonly rows: readonly DeferLedgerRow[];
+    readonly store: CrusherStore;
+    readonly projectKey: string;
+    readonly session: Session;
+}
+/**
+ * Rebuild residents after a restart by FINGERPRINT MATCH against the live
+ * surface (§3.5): for each recorded hash the stored full text is searched
+ * among current `tool/result` events (by callId, then byte-equality); found
+ * → resume at `sentCount: 0`; not found → drop.
+ */
+export declare function rebuildResidents(deps: RebuildDeps): Promise<Map<string, ResidentEntry>>;
+/** Latest `todo_write` snapshot counts for the remaining-requests estimate. */
+export interface TodoCounts {
+    readonly completed: number;
+    readonly pending: number;
+}
+/**
+ * Parse the `todos` array out of `todo_write` arguments (observe-only; the
+ * same argument shape the compaction cost gate reads).
+ */
+export declare function parseTodoCounts(args: unknown): TodoCounts | undefined;
+/** Per-session defer state (in memory only; never ledgered). */
+export interface DeferSessionState {
+    /** Resume rebuild ran (or was attempted) for this session. */
+    loaded: boolean;
+    readonly residents: Map<string, ResidentEntry>;
+    /** Main-loop first-chunk requests observed for this session. */
+    streamRequestCount: number;
+    /** Latest `todo_write` snapshot counts (cold start: zeroes). */
+    todoCompleted: number;
+    todoPending: number;
+}
+/**
+ * In-memory per-session resident table. The map key IS the owning session id
+ * the stream listener's sessionId guard checks against (§3.2).
+ */
+export declare class ResidentTable {
+    private readonly states;
+    get(sessionId: string): DeferSessionState | undefined;
+    ensure(sessionId: string): DeferSessionState;
+    delete(sessionId: string): void;
+    /** Every session id currently holding defer state (stream-listener guard). */
+    sessionIds(): Set<string>;
+    /**
+     * `remainingRequestsEstimate` per the compaction cost-gate doc: observed
+     * requests-per-step × pending todo steps, floored at 1. With no todo
+     * snapshot ever seen the estimate is 1 — conservative against swapping.
+     */
+    remainingRequestsEstimate(state: DeferSessionState): number;
+}
+//# sourceMappingURL=residents.d.ts.map

package/lib/defer/residents.d.ts.map

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

package/lib/defer/residents.js

@@ -0,0 +1,171 @@
+/**
+ * Deferred-resident bookkeeping: the in-memory per-session table, the
+ * append-only per-session JSONL ledger (`<dshHome>/ccr/defer/<sessionId>.jsonl`),
+ * and resume-by-fingerprint rebuild (design §3.1/§3.5).
+ *
+ * Rows carry NO session id — the store hash is the identity, which matches
+ * the store's own keying rule and keeps rows meaningful across resume/fork.
+ * Ledger failures are swallowed per the CCR ledger precedent: durability is
+ * best-effort, correctness never depends on it.
+ *
+ * @module @dsh-cc/context-crusher/defer/residents
+ */
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { ToolCallId } from '@deepseek-ai/dsh-llm';
+import { joinTextBlocks } from "./counter.js";
+/** Append-only per-session defer ledger; never throws. */
+export class DeferLedger {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    /** Append one row; never throws (best-effort observability). */
+    async append(row) {
+        try {
+            await mkdir(dirname(this.filePath), { recursive: true });
+            await appendFile(this.filePath, `${JSON.stringify(row)}\n`, 'utf8');
+        }
+        catch {
+            // Best-effort observability; never surface into the agent loop.
+        }
+    }
+}
+/** Read every ledger row; absent/corrupt files degrade to an empty list. */
+export async function readDeferLedger(filePath) {
+    let body;
+    try {
+        body = await readFile(filePath, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const rows = [];
+    for (const line of body.split('\n')) {
+        if (line.trim().length === 0)
+            continue;
+        try {
+            rows.push(JSON.parse(line));
+        }
+        catch {
+            // Skip a torn tail line; the ledger is append-only and best-effort.
+        }
+    }
+    return rows;
+}
+/**
+ * Replay ledger rows into resident candidates: resident rows add, swap rows
+ * with a committed outcome (applied/stale/abandoned) remove, dry-run intent
+ * rows leave the resident in place (nothing was applied). Candidates always
+ * resume at `sentCount: 0` (§3.5: deliberately conservative).
+ */
+export function foldDeferRows(rows) {
+    const out = new Map();
+    for (const row of rows) {
+        if (row.type === 'resident') {
+            out.set(row.hash, {
+                hash: row.hash,
+                callId: ToolCallId(row.callId),
+                sentCount: 0,
+                tokensSaved: row.tokensSaved,
+                createdAt: row.createdAt,
+            });
+        }
+        else if (row.outcome !== 'dry-run') {
+            out.delete(row.hash);
+        }
+    }
+    return out;
+}
+/**
+ * Rebuild residents after a restart by FINGERPRINT MATCH against the live
+ * surface (§3.5): for each recorded hash the stored full text is searched
+ * among current `tool/result` events (by callId, then byte-equality); found
+ * → resume at `sentCount: 0`; not found → drop.
+ */
+export async function rebuildResidents(deps) {
+    const out = new Map();
+    for (const candidate of foldDeferRows(deps.rows).values()) {
+        const stored = await deps.store.get(deps.projectKey, candidate.hash);
+        if (!stored.ok)
+            continue;
+        for (const seq of deps.session.surface.nodes) {
+            const event = deps.session.eventAt(seq);
+            if (event?.type !== 'tool/result')
+                continue;
+            const message = event.data.message;
+            if (String(message.source.callId) !== String(candidate.callId))
+                continue;
+            const block = message.content[0];
+            if (block?.type !== 'tool-result')
+                continue;
+            if (joinTextBlocks(block.content) === stored.text) {
+                out.set(candidate.hash, candidate);
+                break;
+            }
+        }
+    }
+    return out;
+}
+const TODO_STATUSES = ['pending', 'in_progress', 'completed'];
+/**
+ * Parse the `todos` array out of `todo_write` arguments (observe-only; the
+ * same argument shape the compaction cost gate reads).
+ */
+export function parseTodoCounts(args) {
+    if (typeof args !== 'object' || args === null)
+        return undefined;
+    const todos = args.todos;
+    if (!Array.isArray(todos))
+        return undefined;
+    let completed = 0;
+    let pending = 0;
+    for (const todo of todos) {
+        if (typeof todo !== 'object' || todo === null)
+            return undefined;
+        const item = todo;
+        if (typeof item.content !== 'string' || typeof item.status !== 'string'
+            || !TODO_STATUSES.includes(item.status))
+            return undefined;
+        if (item.status === 'completed')
+            completed += 1;
+        else
+            pending += 1;
+    }
+    return { completed, pending };
+}
+/**
+ * In-memory per-session resident table. The map key IS the owning session id
+ * the stream listener's sessionId guard checks against (§3.2).
+ */
+export class ResidentTable {
+    states = new Map();
+    get(sessionId) {
+        return this.states.get(sessionId);
+    }
+    ensure(sessionId) {
+        let state = this.states.get(sessionId);
+        if (state === undefined) {
+            state = { loaded: false, residents: new Map(), streamRequestCount: 0, todoCompleted: 0, todoPending: 0 };
+            this.states.set(sessionId, state);
+        }
+        return state;
+    }
+    delete(sessionId) {
+        this.states.delete(sessionId);
+    }
+    /** Every session id currently holding defer state (stream-listener guard). */
+    sessionIds() {
+        return new Set(this.states.keys());
+    }
+    /**
+     * `remainingRequestsEstimate` per the compaction cost-gate doc: observed
+     * requests-per-step × pending todo steps, floored at 1. With no todo
+     * snapshot ever seen the estimate is 1 — conservative against swapping.
+     */
+    remainingRequestsEstimate(state) {
+        const requestsPerStep = Math.max(1, state.streamRequestCount / Math.max(state.todoCompleted, 1));
+        return Math.max(1, requestsPerStep * state.todoPending);
+    }
+}
+//# sourceMappingURL=residents.js.map

package/lib/defer/residents.js.map

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