greprag 5.41.0 → 5.42.0

package/dist/commands/archive.js

@@ -0,0 +1,358 @@
+"use strict";
+// adr: adr/governed-compact.md
+/** greprag archive — the governed compact's PNG archive.
+ *
+ *  Before compaction summarizes history away, the PreCompact hook renders
+ *  the transcript's main chain to dense pixel-font PNGs (Snapcompact
+ *  pattern: ~3x token density via the vision path) and indexes every page
+ *  in the CCR store. After compaction, a SessionStart(matcher=compact)
+ *  hook injects a pointer so the post-compact model knows the verbatim
+ *  record exists and can Read the pages back.
+ *
+ *  Verified hook contract (2026-06-12, code.claude.com/docs/en/hooks):
+ *  PreCompact CANNOT inject or modify compaction instructions — so the
+ *  instructions ship as a documented `/compact <snippet>` block
+ *  (`greprag archive snippet`) referenced by the context governor's
+ *  advisory, and the post-compact pointer rides SessionStart(compact),
+ *  whose stdout/additionalContext IS added to context.
+ *
+ *  Surfaces:
+ *    greprag archive render --transcript <path> [--out-dir <dir>] [--session <8hex>]
+ *    greprag archive list [--session <8hex>]
+ *    greprag archive snippet [--session <8hex>]
+ *    hook: runPreCompactArchive (PreCompact), buildArchivePointer (SessionStart)
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ARCHIVE_HELP = exports.SOURCE_TYPE = void 0;
+exports.archiveEnabled = archiveEnabled;
+exports.defaultArchiveDir = defaultArchiveDir;
+exports.renderArchive = renderArchive;
+exports.listArchives = listArchives;
+exports.buildCompactSnippet = buildCompactSnippet;
+exports.runPreCompactArchive = runPreCompactArchive;
+exports.buildArchivePointer = buildArchivePointer;
+exports.runArchive = runArchive;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
+const session_id_1 = require("../session-id");
+const project_anchor_1 = require("../project-anchor");
+const ccr_store_1 = require("../ccr-store");
+const page_renderer_1 = require("../archive/page-renderer");
+const transcript_extract_1 = require("../archive/transcript-extract");
+exports.SOURCE_TYPE = 'png-archive';
+exports.ARCHIVE_HELP = `greprag archive — PNG archive of the pre-compact transcript (governed compact).
+
+  greprag archive render --transcript <path> [--out-dir <dir>] [--session <8hex>]
+      Render the transcript's main chain to 1568x1568 pixel-font PNGs
+      (${page_renderer_1.COLS}x${page_renderer_1.ROWS} grid, ~${Math.round(page_renderer_1.CHARS_PER_PAGE / 1000)}K chars/page), self-test the pixel round-trip,
+      and index every page in the CCR store.
+
+  greprag archive list [--session <8hex>]
+      Show indexed archives with page -> turn ranges, so a model knows
+      which PNG to Read for a given stretch of history.
+
+  greprag archive snippet [--session <8hex>]
+      Print the documented /compact instruction block (preserve-verbatim /
+      compress-aggressively rules + the archive pointer line).
+
+The PreCompact hook runs render automatically before every compaction
+(off-switch: png_archive=false in .greprag/project.json, or
+GREPRAG_PNG_ARCHIVE=off). After compaction, a SessionStart(compact) hook
+injects the archive pointer into the fresh context.
+
+Files: ~/.greprag/png-archive/<session>/archive-<renderId>-pNNN.png
+Index: CCR store (~/.greprag/ccr.db, override GREPRAG_CCR_DB), source_type '${exports.SOURCE_TYPE}'.`;
+// ---------- Config (anchor-settings pattern, governor precedent) --------------
+function archiveEnabled(cwd) {
+    let enabled = true;
+    try {
+        const anchor = (0, project_anchor_1.readAnchor)(cwd);
+        const raw = JSON.parse(fs.readFileSync(anchor.anchorPath, 'utf-8'));
+        if (raw.png_archive === false)
+            enabled = false;
+    }
+    catch { /* no anchor — default stands */ }
+    const env = process.env.GREPRAG_PNG_ARCHIVE;
+    if (env) {
+        if (/^(1|true|yes|on)$/i.test(env))
+            enabled = true;
+        else if (/^(0|false|no|off)$/i.test(env))
+            enabled = false;
+    }
+    return enabled;
+}
+// ---------- Paths + metadata ---------------------------------------------------
+function defaultArchiveDir(session) {
+    return path.join(os.homedir(), '.greprag', 'png-archive', session);
+}
+function sessionFromTranscriptPath(transcriptPath) {
+    return (0, session_id_1.truncateSessionId)(path.basename(transcriptPath).replace(/\.jsonl$/i, ''));
+}
+/** Render a transcript to PNG pages, self-test, write, and index. */
+async function renderArchive(opts) {
+    const extracted = (0, transcript_extract_1.extractTranscriptFile)(opts.transcriptPath);
+    if (!extracted || !extracted.text.trim())
+        return null;
+    const session = (0, session_id_1.truncateSessionId)(opts.session)
+        || sessionFromTranscriptPath(opts.transcriptPath)
+        || 'unknown';
+    const outDir = opts.outDir || defaultArchiveDir(session);
+    const { sanitized, marks } = (0, page_renderer_1.sanitizeWithMarks)(extracted.text, extracted.turnMarks);
+    const renderId = crypto.createHash('sha256').update(sanitized, 'utf8').digest('hex').slice(0, 8);
+    const pages = (0, page_renderer_1.paginate)((0, page_renderer_1.layoutRows)(sanitized));
+    fs.mkdirSync(outDir, { recursive: true });
+    const files = [];
+    const metas = [];
+    let selfTestError = null;
+    for (let i = 0; i < pages.length; i++) {
+        const rendered = (0, page_renderer_1.renderPage)(pages[i]);
+        const err = (0, page_renderer_1.verifyRoundTrip)(rendered);
+        if (err && !selfTestError)
+            selfTestError = `page ${i + 1}: ${err}`;
+        const file = path.join(outDir, `archive-${renderId}-p${String(i + 1).padStart(3, '0')}.png`);
+        fs.writeFileSync(file, rendered.png);
+        files.push(file);
+        const { turnStart, turnEnd } = (0, transcript_extract_1.turnRangeForWindow)(marks, rendered.charStart, rendered.charEnd);
+        metas.push({
+            kind: exports.SOURCE_TYPE,
+            session,
+            renderId,
+            file,
+            page: i + 1,
+            pages: pages.length,
+            charStart: rendered.charStart,
+            charEnd: rendered.charEnd,
+            chars: rendered.charEnd - rendered.charStart,
+            turnStart,
+            turnEnd,
+        });
+    }
+    // Index every page in the CCR store — content is the meta JSON, so
+    // `greprag retrieve <hash>` on a page hash returns the pointer record.
+    const store = await ccr_store_1.CcrStore.open();
+    try {
+        for (const meta of metas)
+            store.put(JSON.stringify(meta), exports.SOURCE_TYPE);
+    }
+    finally {
+        store.close();
+    }
+    return {
+        session,
+        outDir,
+        renderId,
+        pages: pages.length,
+        chars: sanitized.length,
+        turns: extracted.turns,
+        files,
+        selfTestError,
+    };
+}
+async function listArchives(session) {
+    const store = await ccr_store_1.CcrStore.open();
+    let rows;
+    try {
+        rows = store.listBySourceType(exports.SOURCE_TYPE);
+    }
+    finally {
+        store.close();
+    }
+    const groups = new Map();
+    for (const row of rows) {
+        let meta;
+        try {
+            meta = JSON.parse(row.content);
+        }
+        catch {
+            continue;
+        }
+        if (meta.kind !== exports.SOURCE_TYPE || !meta.file)
+            continue;
+        if (session && meta.session !== session)
+            continue;
+        const key = `${meta.session}/${meta.renderId}`;
+        let group = groups.get(key);
+        if (!group) {
+            group = { session: meta.session, renderId: meta.renderId, createdAt: row.createdAt, pages: [] };
+            groups.set(key, group);
+        }
+        group.pages.push(meta);
+        if (row.createdAt > group.createdAt)
+            group.createdAt = row.createdAt;
+    }
+    const out = Array.from(groups.values());
+    for (const g of out)
+        g.pages.sort((a, b) => a.page - b.page);
+    out.sort((a, b) => (a.createdAt < b.createdAt ? 1 : -1));
+    return out;
+}
+// ---------- /compact snippet -------------------------------------------------------
+function buildCompactSnippet(session) {
+    const dir = defaultArchiveDir(session);
+    return `/compact Preserve verbatim: current task state; recent decisions and the WHY behind each; every file path touched; unresolved errors; key identifiers (branch names, session ids, commit hashes). Compress aggressively: tool output bulk, exploratory dead ends. End the summary with this exact pointer line: "Full pre-compact history is archived as pixel-text PNGs at ${dir} (greprag archive list --session ${session}) — Read a page with the Read tool when verbatim detail is needed."`;
+}
+/** PreCompact — render + index, return a user-facing systemMessage (or null
+ *  when disabled/empty/failed). NEVER throws; never blocks compaction. */
+async function runPreCompactArchive(input) {
+    try {
+        const cwd = input.cwd || process.cwd();
+        if (!archiveEnabled(cwd))
+            return null;
+        if (!input.transcript_path)
+            return null;
+        const summary = await renderArchive({
+            transcriptPath: input.transcript_path,
+            session: input.session_id,
+        });
+        if (!summary)
+            return null;
+        const warn = summary.selfTestError
+            ? ` (WARNING: pixel self-test failed — ${summary.selfTestError})`
+            : '';
+        return `GrepRAG governed compact: pre-compact history archived as `
+            + `${summary.pages} PNG page(s) (turns 1-${summary.turns}, ~${Math.round(summary.chars / 1000)}K chars) `
+            + `at ${summary.outDir}${warn}. Post-compact recall: greprag archive list --session ${summary.session}.`;
+    }
+    catch {
+        return null; // fail-open: archiving must never block compaction
+    }
+}
+/** SessionStart(matcher=compact) — pointer for the post-compact model.
+ *  Returns additionalContext text, or null when no archive exists. */
+async function buildArchivePointer(input) {
+    try {
+        const cwd = input.cwd || process.cwd();
+        if (!archiveEnabled(cwd))
+            return null;
+        const session = (0, session_id_1.truncateSessionId)(input.session_id);
+        if (!session)
+            return null;
+        const groups = await listArchives(session);
+        if (groups.length === 0)
+            return null;
+        const latest = groups[0];
+        const last = latest.pages[latest.pages.length - 1];
+        const turnEnd = last ? last.turnEnd : 0;
+        return `[GrepRAG governed compact: the full pre-compact conversation is archived `
+            + `losslessly as pixel-text PNGs (turns 1-${turnEnd}, ${latest.pages.length} page(s), `
+            + `~${Math.round(page_renderer_1.CHARS_PER_PAGE / 1000)}K chars each) at ${defaultArchiveDir(session)}. `
+            + `Page->turn map: \`greprag archive list --session ${session}\`. When the compact `
+            + `summary lacks verbatim detail (exact code, error text, identifiers), Read the `
+            + `relevant PNG with the Read tool — it is conversation text rendered as pixels.]`;
+    }
+    catch {
+        return null;
+    }
+}
+// ---------- CLI ------------------------------------------------------------------
+function getFlag(args, name) {
+    const idx = args.indexOf(name);
+    if (idx === -1 || idx + 1 >= args.length)
+        return null;
+    return args[idx + 1];
+}
+function resolveSessionArg(args) {
+    return (0, session_id_1.truncateSessionId)(getFlag(args, '--session')
+        || process.env.CLAUDE_CODE_SESSION_ID
+        || process.env.CLAUDE_SESSION_ID
+        || process.env.GREPRAG_SESSION_ID
+        || '');
+}
+async function runArchive(args) {
+    const sub = args[0];
+    if (!sub || sub === '--help' || sub === '-h' || sub === 'help') {
+        console.log(exports.ARCHIVE_HELP);
+        return;
+    }
+    if (sub === 'render') {
+        const transcript = getFlag(args, '--transcript');
+        if (!transcript) {
+            console.error('archive render: --transcript <path> is required');
+            process.exit(1);
+        }
+        const summary = await renderArchive({
+            transcriptPath: transcript,
+            outDir: getFlag(args, '--out-dir') || undefined,
+            session: resolveSessionArg(args) || undefined,
+        });
+        if (!summary) {
+            console.error(`archive render: nothing to archive (unreadable or empty transcript: ${transcript})`);
+            process.exit(1);
+        }
+        console.log(`Archived session ${summary.session} -> ${summary.outDir}`);
+        console.log(`  render ${summary.renderId}: ${summary.pages} page(s), `
+            + `${summary.turns} turn(s), ${summary.chars} chars`);
+        for (const f of summary.files)
+            console.log(`  ${f}`);
+        if (summary.selfTestError) {
+            console.error(`SELF-TEST FAILED: ${summary.selfTestError}`);
+            process.exit(1);
+        }
+        console.log('  self-test: PASS (pixel round-trip lossless)');
+        return;
+    }
+    if (sub === 'list') {
+        const groups = await listArchives(resolveSessionArg(args));
+        if (groups.length === 0) {
+            console.log('No PNG archives indexed.'
+                + ' (They are rendered by the PreCompact hook, or: greprag archive render --transcript <path>)');
+            return;
+        }
+        for (const g of groups) {
+            console.log(`Session ${g.session} — render ${g.renderId} (${g.pages.length} page(s), ${g.createdAt})`);
+            for (const p of g.pages) {
+                console.log(`  p${String(p.page).padStart(3, '0')}  turns ${p.turnStart}-${p.turnEnd}  `
+                    + `chars ${p.charStart}-${p.charEnd}  ${p.file}`);
+            }
+        }
+        return;
+    }
+    if (sub === 'snippet') {
+        const session = resolveSessionArg(args);
+        if (!session) {
+            console.error('archive snippet: pass --session <8hex> (or run inside a Claude Code session)');
+            process.exit(1);
+        }
+        console.log(buildCompactSnippet(session));
+        return;
+    }
+    console.error(`Unknown subcommand: archive ${sub}\n`);
+    console.log(exports.ARCHIVE_HELP);
+    process.exit(1);
+}
+//# sourceMappingURL=archive.js.map

package/dist/commands/archive.js.map

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

package/dist/commands/context-governor.d.ts

@@ -0,0 +1,82 @@
+/** Context governor — tracks the session's live context size every turn and,
+ *  past a configurable crossover threshold (default 400K tokens), injects a
+ *  one-line advisory recommending a governed compact.
+ *
+ *  Why 400K: per-turn cache-read overhead is linear in context size N and
+ *  overtakes the productive cost of a turn at roughly N ≈ 400-425K tokens.
+ *  Past that, most of each turn's cost is re-reading frozen history — the
+ *  economically right moment to compact, BEFORE the window forces it.
+ *  See docs/pre-llm-compression.md (§ cache cost model).
+ *
+ *  Three surfaces, all local (no API, no LLM):
+ *    - Stop probe (`greprag-hook context-probe`): read the transcript TAIL
+ *      (last ~64KB, never the whole multi-MB file), compute context size from
+ *      the most recent main-chain assistant entry's `message.usage`, write
+ *      ~/.greprag/context-state/<8hex>.json.
+ *    - UserPromptSubmit check (`greprag-hook context-check`): state over
+ *      threshold → emit ONE advisory line, at most once per 25-turn window.
+ *    - CLI (`greprag context status`): debugging/demo readout.
+ *
+ *  Config follows the anchor-settings pattern (email_autosave precedent):
+ *  `.greprag/project.json` keys `context_governor` (bool) + `context_threshold`
+ *  (number), env overrides GREPRAG_CONTEXT_GOVERNOR / GREPRAG_CONTEXT_THRESHOLD.
+ */
+export declare const DEFAULT_CONTEXT_THRESHOLD = 400000;
+/** Advisory fires at most once per this many turns — never nag every turn. */
+export declare const FIRE_WINDOW_TURNS = 25;
+/** Tail window read from the transcript. The latest assistant entry always
+ *  lives in the last few KB; 64KB gives slack for huge tool_result lines. */
+export declare const TAIL_BYTES: number;
+export interface ContextUsage {
+    /** Live context size ≈ input + cache_read + cache_creation of the most
+     *  recent main-chain assistant entry. */
+    tokens: number;
+    /** Entry timestamp (ISO) if present. */
+    timestamp: string | null;
+}
+/** Compute the live context size from a chunk of transcript-tail text.
+ *  Walks the JSONL lines BACKWARDS for the most recent main-chain assistant
+ *  entry carrying `message.usage` — sidechain (subagent) entries are skipped,
+ *  as are unparseable lines (the tail cut can land mid-line). Returns null
+ *  when no qualifying entry is in the window. */
+export declare function computeContextSizeFromTail(tailText: string): ContextUsage | null;
+/** Read the last `maxBytes` of a file. Never parses the whole transcript —
+ *  a marathon session's JSONL runs to tens of MB. Returns null on any error. */
+export declare function readTranscriptTail(transcriptPath: string, maxBytes?: number): string | null;
+export interface GovernorState {
+    /** Live context size at the last probe. */
+    tokens: number;
+    /** Probe counter — increments once per Stop event. */
+    turn: number;
+    /** ISO timestamp of the last probe. */
+    ts: string;
+    /** Sentinel: turn number when the advisory last fired. Absent = never. */
+    lastFiredTurn?: number;
+}
+/** State dir — env override (tests) > ~/.greprag/context-state. */
+export declare function contextStateDir(): string;
+export declare function contextStatePath(shortSessionId: string): string;
+export declare function readGovernorState(shortSessionId: string): GovernorState | null;
+export declare function writeGovernorState(shortSessionId: string, state: GovernorState): void;
+export interface GovernorConfig {
+    enabled: boolean;
+    threshold: number;
+}
+/** Resolve governor config. Precedence: env > anchor file > defaults.
+ *  Reads the anchor file raw for the context_* keys so the governor stays
+ *  self-contained (no ProjectAnchor type change — additive for the chip seam). */
+export declare function readGovernorConfig(cwd: string): GovernorConfig;
+/** Fire when over threshold AND outside the once-per-window sentinel. */
+export declare function shouldFire(state: GovernorState, threshold: number, windowTurns?: number): boolean;
+export declare function buildAdvisory(tokens: number, threshold: number): string;
+export interface GovernorHookInput {
+    session_id?: string;
+    transcript_path?: string;
+    cwd?: string;
+}
+/** Stop probe — measure + record. Silent; never blocks the turn. */
+export declare function runContextProbe(input: GovernorHookInput): void;
+/** UserPromptSubmit check — returns the advisory line when it should fire
+ *  (and stamps the sentinel), else null. Caller wraps it in hook JSON. */
+export declare function runContextCheck(input: GovernorHookInput): string | null;
+export declare function runContext(args: string[]): void;