@pugi/cli 0.1.0-beta.1 → 0.1.0-beta.100

package/dist/core/codegraph/install.js

@@ -0,0 +1,134 @@
+/**
+ * Codegraph MCP install helper — .
+ *
+ * Writes the codegraph MCP server config к `.pugi/mcp.json` so the
+ * registry loader picks it up on the next dispatch. Mirrors the
+ * Phase 1 example config at `apps/pugi-cli/docs/examples/codegraph.mcp.json`
+ * — same `codegraph serve --mcp` command + `pending` trust state. The
+ * operator still has to run `pugi mcp trust codegraph` before tools
+ * actually surface; the install path NEVER auto-trusts, by design.
+ *
+ * Idempotent: re-running on a workspace that already has a `codegraph`
+ * entry is a no-op + returns `{ status: 'already-installed' }`. Other
+ * MCP servers in the same file are preserved.
+ *
+ * The function is intentionally NOT bundled into core/mcp/ to keep
+ * the codegraph product (install copy, decision store, language gate)
+ * one cohesive module. The MCP registry is a generic surface; the
+ * codegraph adoption is a feature on top of it.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+/**
+ * Canonical config shape we write into `.pugi/mcp.json` under the
+ * `codegraph` key. Matches `mcpServerConfigSchema` (Zod) in
+ * core/mcp/client.ts and the published example at docs/examples/
+ * codegraph.mcp.json. Drift here MUST land alongside a registry
+ * schema change OR the next dispatch crashes with a validation error.
+ */
+export const CODEGRAPH_MCP_ENTRY = Object.freeze({
+    command: 'codegraph',
+    args: Object.freeze(['serve', '--mcp']),
+    env: Object.freeze({}),
+    trust: 'pending',
+});
+/**
+ * Documentation URL surfaced after a successful install so the operator
+ * knows how to actually run codegraph index commands. Single source of
+ * truth — both the init flow and the /codegraph-status command pull
+ * from this constant.
+ */
+export const CODEGRAPH_DOCS_URL = 'https://github.com/colbymchenry/codegraph';
+/**
+ * Merge the codegraph entry into `.pugi/mcp.json`. Creates the file
+ * (with `{ schema: 1, servers: { codegraph: ... } }`) when it does not
+ * exist. Preserves every other server entry on disk.
+ *
+ * @param workspaceRoot absolute path to the project root that owns the
+ *                     `.pugi/` directory. The caller is responsible for
+ *                     ensuring `.pugi/` exists (the install helper
+ *                     creates it as a defensive fallback).
+ */
+export function installCodegraphMcpEntry(workspaceRoot) {
+    const pugiDir = resolve(workspaceRoot, '.pugi');
+    const configPath = resolve(pugiDir, 'mcp.json');
+    try {
+        if (!existsSync(pugiDir)) {
+            mkdirSync(pugiDir, { recursive: true });
+        }
+        let existing = {};
+        if (existsSync(configPath)) {
+            try {
+                const raw = readFileSync(configPath, 'utf8');
+                if (raw.trim().length > 0) {
+                    const parsed = JSON.parse(raw);
+                    if (parsed && typeof parsed === 'object') {
+                        existing = parsed;
+                    }
+                }
+            }
+            catch (error) {
+                return {
+                    status: 'failed',
+                    reason: `cannot parse existing .pugi/mcp.json: ${error.message}`,
+                };
+            }
+        }
+        const servers = (existing.servers && typeof existing.servers === 'object')
+            ? { ...existing.servers }
+            : {};
+        if (servers['codegraph']) {
+            return { status: 'already-installed', configPath };
+        }
+        servers['codegraph'] = {
+            command: CODEGRAPH_MCP_ENTRY.command,
+            args: [...CODEGRAPH_MCP_ENTRY.args],
+            env: { ...CODEGRAPH_MCP_ENTRY.env },
+            trust: CODEGRAPH_MCP_ENTRY.trust,
+        };
+        const out = {
+            schema: typeof existing.schema === 'number' ? existing.schema : 1,
+            servers,
+        };
+        writeFileSync(configPath, `${JSON.stringify(out, null, 2)}\n`, { mode: 0o600 });
+        return { status: 'installed', configPath };
+    }
+    catch (error) {
+        return { status: 'failed', reason: error.message };
+    }
+}
+/**
+ * Check whether `.pugi/mcp.json` already declares the `codegraph`
+ * server. Pure best-effort — a malformed file returns false (we err
+ * on the side of "not installed" so the operator can re-trigger the
+ * install path instead of being silently locked out).
+ *
+ * Returns the parsed `trust` state when present so callers can render
+ * the right status copy ("declared, awaiting trust" vs "active").
+ */
+export function detectCodegraphInstalled(workspaceRoot) {
+    const configPath = resolve(workspaceRoot, '.pugi/mcp.json');
+    if (!existsSync(configPath)) {
+        return { installed: false, trust: null, configPath };
+    }
+    try {
+        const raw = readFileSync(configPath, 'utf8');
+        if (raw.trim().length === 0) {
+            return { installed: false, trust: null, configPath };
+        }
+        const parsed = JSON.parse(raw);
+        const codegraph = parsed.servers?.['codegraph'];
+        if (!codegraph) {
+            return { installed: false, trust: null, configPath };
+        }
+        return {
+            installed: true,
+            trust: codegraph.trust === 'trusted' || codegraph.trust === 'denied' ? codegraph.trust : 'pending',
+            configPath,
+        };
+    }
+    catch {
+        return { installed: false, trust: null, configPath };
+    }
+}
+//# sourceMappingURL=install.js.map

package/dist/core/codegraph/offer-hook.js

@@ -0,0 +1,220 @@
+/**
+ * Codegraph offer hook — .
+ *
+ * Single integration point used by both `pugi init` (standalone CLI
+ * entry) AND the REPL's `/init` slash so the decision logic + telemetry
+ * fan-out stays single-sourced. The hook is split into two halves:
+ *
+ *  1. `evaluateOffer({ workspaceRoot, nowIso })` — pure: decides if
+ *     we should prompt, returns the detection result + suggested copy
+ *     so the UI layer can render it however it likes (Y/n prompt in
+ *     a TTY, JSON envelope in --no-tty mode, system pane line in the
+ *     REPL).
+ *  2. `applyOfferDecision({ workspaceRoot, accepted, … })` — side-
+ *     effectful: persists the operator's verdict + runs the install
+ *     if accepted + emits the right telemetry event.
+ *
+ * Telemetry events emitted (when consent allows):
+ *  - `codegraph.offer.shown` — every time we surface the prompt
+ *  - `codegraph.offer.accepted` — operator said yes
+ *  - `codegraph.offer.declined` — operator said no
+ *  - `codegraph.install.success` — mcp.json merge succeeded
+ *  - `codegraph.install.failed` — mcp.json merge failed (rare)
+ *  - `codegraph.reminder.shown` — cold-start nudge surfaced
+ *  - `codegraph.stale-index.shown` — index > STALE_INDEX_DAYS
+ *
+ * All telemetry is best-effort fire-and-forget; emit() never throws.
+ *
+ * The hook NEVER prompts directly — it has no TTY contract. The
+ * caller MUST resolve the operator's verdict OR call `applyOfferDecision`
+ * with `accepted: false` to record a decline.
+ */
+import { detectRepo, buildOfferCopy } from './detect-repo.js';
+import { shouldOfferOnInit, recordDecision, readDecision, shouldNudgeStaleIndex, indexAgeDays, } from './decision-store.js';
+import { installCodegraphMcpEntry, detectCodegraphInstalled, CODEGRAPH_DOCS_URL, } from './install.js';
+import { emit } from '../telemetry/emitter.js';
+/**
+ * Pure evaluation. Reads detection + decision store. NEVER writes.
+ * Reads NEVER throw — corrupt JSON returns "first-run". Tests rely on
+ * this so they can drive `evaluateOffer` repeatedly without setup.
+ */
+export function evaluateOffer(input) {
+    const detection = detectRepo(input.workspaceRoot);
+    if (!detection.isRepo) {
+        return { shouldPrompt: false, reason: detection.reason, detection };
+    }
+    if (!detection.offerCodegraph) {
+        return { shouldPrompt: false, reason: 'size-or-language-gate', detection };
+    }
+    // If codegraph is already declared в mcp.json, skip — the operator
+    // already adopted it (maybe via Phase 1 manual install). Cold-start
+    // hook covers the stale-index nudge separately.
+    const installed = detectCodegraphInstalled(input.workspaceRoot);
+    if (installed.installed) {
+        return { shouldPrompt: false, reason: 'already-installed', detection };
+    }
+    if (!input.ignorePriorDecision) {
+        const cadence = shouldOfferOnInit(input.workspaceRoot, input.nowIso);
+        if (!cadence.shouldOffer) {
+            return { shouldPrompt: false, reason: cadence.reason, detection };
+        }
+    }
+    return {
+        shouldPrompt: true,
+        detection: detection,
+        promptCopy: buildOfferCopy(detection),
+        docsUrl: CODEGRAPH_DOCS_URL,
+        reason: 'first-run',
+    };
+}
+export function applyOfferDecision(input) {
+    const decision = recordDecision(input.workspaceRoot, {
+        accepted: input.accepted,
+        ...(input.nowIso ? { nowIso: input.nowIso } : {}),
+    });
+    emitOfferTelemetry(input.accepted ? 'codegraph.offer.accepted' : 'codegraph.offer.declined', {
+        sizeCategory: input.detection.sizeCategory,
+        primaryLanguage: input.detection.languages[0] ?? 'unknown',
+        primarySymbolCount: input.detection.primarySymbolCount,
+    });
+    if (!input.accepted) {
+        return { kind: 'declined', decision };
+    }
+    const install = installCodegraphMcpEntry(input.workspaceRoot);
+    if (install.status === 'failed') {
+        emitOfferTelemetry('codegraph.install.failed', {
+            reason: install.reason.slice(0, 64),
+        });
+        return { kind: 'accepted-install-failed', decision, install };
+    }
+    emitOfferTelemetry('codegraph.install.success', {
+        sizeCategory: input.detection.sizeCategory,
+        primaryLanguage: input.detection.languages[0] ?? 'unknown',
+        alreadyInstalled: install.status === 'already-installed',
+    });
+    return {
+        kind: 'accepted-installed',
+        decision,
+        install,
+        docsUrl: CODEGRAPH_DOCS_URL,
+        trustCommand: 'pugi mcp trust codegraph',
+    };
+}
+/**
+ * Surface the offer telemetry "shown" event. Called by the init flow
+ * once it has decided to actually render the prompt (so a `--no-tty`
+ * invocation that skipped the prompt does not count as a shown event).
+ */
+export function emitOfferShown(detection) {
+    emitOfferTelemetry('codegraph.offer.shown', {
+        sizeCategory: detection.sizeCategory,
+        primaryLanguage: detection.languages[0] ?? 'unknown',
+        primarySymbolCount: detection.primarySymbolCount,
+    });
+}
+/**
+ * Compute the cold-start nudge. Pure read — never writes. The session
+ * module decides whether to render the message AND whether to call
+ * `markReindexChecked(...)` after the operator dismisses it (so the
+ * once-per-day throttle on `shouldNudgeStaleIndex` works).
+ */
+export function evaluateColdStart(input) {
+    const detection = detectRepo(input.workspaceRoot);
+    if (!detection.isRepo) {
+        return { kind: 'silent', reason: detection.reason };
+    }
+    const decision = readDecision(input.workspaceRoot);
+    // Stale-index path takes priority — an accepted operator should be
+    // nudged about freshness before a never-asked operator is nudged
+    // about installation.
+    if (decision && decision.accepted) {
+        if (shouldNudgeStaleIndex(decision, input.nowIso)) {
+            const age = indexAgeDays(decision, input.nowIso) ?? 0;
+            emitOfferTelemetry('codegraph.stale-index.shown', { ageDays: age });
+            return {
+                kind: 'stale-index',
+                ageDays: age,
+                message: `Codegraph index is ${age} day${age === 1 ? '' : 's'} old. Run /codegraph-status to refresh.`,
+            };
+        }
+        return { kind: 'silent', reason: 'fresh-index' };
+    }
+    if (!detection.offerCodegraph) {
+        return { kind: 'silent', reason: 'size-or-language-gate' };
+    }
+    const cadence = shouldOfferOnInit(input.workspaceRoot, input.nowIso);
+    if (!cadence.shouldOffer) {
+        return { kind: 'silent', reason: cadence.reason };
+    }
+    if (cadence.reason !== 'reminder-due') {
+        // Cold-start path is strictly the "reminder" cadence — first-run
+        // offers land through `pugi init`, not the cold-start hook. The
+        // separation prevents double-prompting in the common "run pugi
+        // init + then pugi code" flow.
+        return { kind: 'silent', reason: 'first-run-handled-by-init' };
+    }
+    emitOfferTelemetry('codegraph.reminder.shown', {
+        sizeCategory: detection.sizeCategory,
+        primaryLanguage: detection.languages[0] ?? 'unknown',
+    });
+    return {
+        kind: 'remind',
+        detection,
+        message: `${buildOfferCopy(detection)} (last declined ${humanAge(decision?.offeredAt, input.nowIso)} ago)`,
+    };
+}
+/**
+ * Fire one telemetry event. Telemetry meta is keyed by the canonical
+ * allowlist (`flagsHash`, `parentCommand`, etc.); we re-purpose
+ * `parentCommand` to carry the offer reason since the codegraph
+ * event-kind taxonomy is not (yet) in the server-side allowlist.
+ *
+ * Best-effort: emit() drops events when consent is off and never
+ * throws.
+ */
+function emitOfferTelemetry(command, meta) {
+    const stringMeta = {};
+    for (const [k, v] of Object.entries(meta)) {
+        // Promote everything через the canonical `parentCommand` slot OR
+        // safe-numeric counters (retryCount). Unknown keys would be
+        // dropped by the emitter's META_ALLOWLIST guard, but routing
+        // through `parentCommand: "<key>=<value>"` keeps the signal
+        // visible на the dashboard.
+        if (typeof v === 'number') {
+            stringMeta.retryCount = v;
+        }
+        else if (typeof v === 'boolean') {
+            stringMeta.cacheHit = v;
+        }
+        else {
+            stringMeta.parentCommand = `${k}=${String(v).slice(0, 32)}`;
+        }
+    }
+    emit({
+        command,
+        kind: 'tool-call',
+        success: true,
+        meta: stringMeta,
+    });
+}
+/**
+ * Format the elapsed time since `priorIso` in human-readable units
+ * (days / weeks). Pure — exposed for spec parity. Falls back to
+ * "earlier" when prior is missing OR unparseable.
+ */
+function humanAge(priorIso, nowIso) {
+    if (!priorIso)
+        return 'earlier';
+    const now = nowIso ? Date.parse(nowIso) : Date.now();
+    const prior = Date.parse(priorIso);
+    if (!Number.isFinite(prior))
+        return 'earlier';
+    const days = Math.max(0, Math.floor((now - prior) / (24 * 60 * 60 * 1000)));
+    if (days < 1)
+        return 'today';
+    if (days < 7)
+        return `${days} day${days === 1 ? '' : 's'}`;
+    const weeks = Math.floor(days / 7);
+    return `${weeks} week${weeks === 1 ? '' : 's'}`;
+}
+//# sourceMappingURL=offer-hook.js.map

package/dist/core/codegraph/parser.js

@@ -0,0 +1,71 @@
+/**
+ * Pugi local symbol index - tree-sitter parser stub.
+ *
+ * This file is intentionally a stub. Real tree-sitter integration ships
+ * in follow-up PR L1, which adds:
+ *
+ *  - `tree-sitter` runtime dependency
+ *  - per-language grammar deps: `tree-sitter-typescript` (covers TS+TSX),
+ *    `tree-sitter-javascript` (covers JS+JSX), `tree-sitter-python`,
+ *    `tree-sitter-go`, `tree-sitter-rust`
+ *  - per-language extractor modules under `./parsers/<lang>.ts` that
+ *    walk the parsed CST and emit `Symbol[]` + `Edge[]`
+ *  - file fingerprint (sha256) computation
+ *  - extension routing (`.ts` / `.tsx` → typescript, `.py` → python, etc.)
+ *
+ * Keeping the stub deliberately broken (returns empty arrays + a flag)
+ * lets the rest of the scaffold ship in this PR without smuggling in
+ * tree-sitter native modules. tree-sitter has a prebuilt-binary
+ * distribution but it is one more wheel-per-platform surface that
+ * compounds the install-time risk the session-store memo warned about
+ * (see `core/repl/store/session-store.ts` lines 20-36).
+ *
+ * The `parseFile` signature is the long-term contract - PR L1 fills
+ * the body without changing the type. Other modules (`db.ts`, the
+ * future watcher in PR L2) wire against this signature today; the
+ * unit tests in `test/codegraph-db.spec.ts` exercise `db.ts` directly
+ * via hand-built symbol arrays so they pass without a real parser.
+ */
+/**
+ * Parse one source file and return its symbol + edge contribution.
+ *
+ * TODO(PR L1): replace this body with a real tree-sitter extraction
+ * pipeline. The signature is frozen - db.ts + the watcher + the MCP
+ * tool layer wire against it as-is today.
+ *
+ * @param path Absolute or workspace-relative path. The real impl will
+ *             read the file, sha256 it, route by extension to the right
+ *             tree-sitter grammar, and walk the resulting CST.
+ */
+export async function parseFile(path) {
+    // Touch the parameter so TS strict noUnusedParameters doesn't fire.
+    // The real impl in PR L1 reads the file at this path.
+    void path;
+    return {
+        symbols: [],
+        edges: [],
+        stub: true,
+    };
+}
+/**
+ * Stable list of file extensions the v1 parser will support. Exported
+ * so the watcher (PR L2) and the CLI command (`pugi index`) can
+ * pre-filter the file walk without instantiating a parser. The set
+ * mirrors `INDEXED_LANGUAGES` in `./types.ts`.
+ *
+ * `.cjs` and `.mjs` map to javascript; `.tsx` and `.jsx` map to
+ * typescript / javascript respectively (tree-sitter-typescript ships
+ * a TSX grammar variant; same for JSX in tree-sitter-javascript).
+ */
+export const PARSEABLE_EXTENSIONS = Object.freeze([
+    '.ts',
+    '.tsx',
+    '.js',
+    '.jsx',
+    '.mjs',
+    '.cjs',
+    '.py',
+    '.go',
+    '.rs',
+]);
+//# sourceMappingURL=parser.js.map

package/dist/core/codegraph/types.js

@@ -0,0 +1,34 @@
+/**
+ * Pugi local symbol index - type definitions.
+ *
+ * Companion to `db.ts` (SQLite + FTS5 wrapper) and `parser.ts` (tree-sitter
+ * extractor, stub today, real impl in follow-up PR L1). These types are the
+ * cross-module contract: the parser produces `Symbol[]` + `Edge[]`, the db
+ * layer inserts them, the MCP tools consume the query result types.
+ *
+ * Distinct from the third-party CodeGraph install scaffold that already
+ * lives in the same directory (`detect-repo.ts`, `offer-hook.ts`,
+ * `install.ts`, `decision-store.ts`). Those manage adoption of the upstream
+ * colbymchenry/codegraph MCP server. This file is the Pugi-native index.
+ * See the design memo at
+ * `docs/research/2026-06-05-pugi-index-codegraph-design.md` for the full
+ * architecture rationale.
+ *
+ * Naming convention: every type defined here is `Symbol` / `Edge` /
+ * `IndexedFile` / `*Result` / `*Options`. The interface is intentionally
+ * narrow - five v1 languages, four MCP tools, one SQLite database file.
+ */
+/**
+ * Schema version tracked in the `_migrations` table. v1 ships with this
+ * PR (files + symbols + edges + FTS5 virtual + triggers). Bumping this
+ * MUST land a matching `applyMigration(N, db)` branch in `db.ts`.
+ */
+export const INDEX_SCHEMA_VERSION = 1;
+export const INDEXED_LANGUAGES = Object.freeze([
+    'typescript',
+    'javascript',
+    'python',
+    'go',
+    'rust',
+]);
+//# sourceMappingURL=types.js.map

package/dist/core/compact/auto-trigger.js

@@ -0,0 +1,96 @@
+/**
+ * Auto-compact threshold gate.
+ *
+ * Decides whether the conversation buffer has crossed the threshold
+ * percent of the active model's context window. The check runs after
+ * every operator/persona turn before the NEXT operator input lands so
+ * the compaction completes BEFORE the model would have rejected the
+ * request with a context-overflow error.
+ *
+ * Design choices:
+ *
+ *  - Pure function. The caller passes (tokenCount, windowSize, env).
+ *    The gate returns a verdict; the session module owns the side
+ *    effect of invoking the summariser. Pure-function shape keeps the
+ *    spec exhaustive and the call site readable.
+ *
+ *  - Hysteresis: once a compaction lands, the marker resets the
+ *    baseline token count to "summary + tail" — the gate looks at the
+ *    POST-marker tokens only. This is enforced upstream by the caller
+ *    passing the post-marker count; the gate itself has no memory.
+ *
+ *  - Two env knobs:
+ *      PUGI_AUTOCOMPACT_DISABLED=1 — kill switch
+ *      PUGI_AUTOCOMPACT_THRESHOLD=N — float in (0, 1] (default 0.75)
+ *    Anything outside (0, 1] is rejected and the gate falls back to
+ *    the default. Bad input never crashes the REPL.
+ */
+/** Default trip point as a fraction of the context window. */
+export const DEFAULT_THRESHOLD = 0.75;
+/**
+ * Decide whether to fire `/compact` automatically. Pure; safe to call
+ * after every turn.
+ */
+export function evaluateAutoCompact(input) {
+    const env = input.env ?? process.env;
+    const threshold = resolveThreshold(env);
+    if (input.windowSize <= 0 || !Number.isFinite(input.windowSize)) {
+        return {
+            kind: 'skip',
+            reason: 'invalid-window',
+            tokenCount: input.tokenCount,
+            windowSize: input.windowSize,
+            threshold,
+            pressure: 0,
+        };
+    }
+    if (env['PUGI_AUTOCOMPACT_DISABLED'] === '1') {
+        return {
+            kind: 'skip',
+            reason: 'disabled',
+            tokenCount: input.tokenCount,
+            windowSize: input.windowSize,
+            threshold,
+            pressure: roundPressure(input.tokenCount / input.windowSize),
+        };
+    }
+    const pressure = roundPressure(input.tokenCount / input.windowSize);
+    if (pressure >= threshold) {
+        return {
+            kind: 'fire',
+            tokenCount: input.tokenCount,
+            windowSize: input.windowSize,
+            threshold,
+            pressure,
+        };
+    }
+    return {
+        kind: 'skip',
+        reason: 'below-threshold',
+        tokenCount: input.tokenCount,
+        windowSize: input.windowSize,
+        threshold,
+        pressure,
+    };
+}
+/**
+ * Resolve the threshold from env, clamping to the (0, 1] open-closed
+ * interval. Bad input silently falls back to DEFAULT_THRESHOLD so the
+ * REPL never crashes on a malformed environment variable.
+ */
+function resolveThreshold(env) {
+    const raw = env['PUGI_AUTOCOMPACT_THRESHOLD'];
+    if (!raw)
+        return DEFAULT_THRESHOLD;
+    const parsed = Number.parseFloat(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0 || parsed > 1) {
+        return DEFAULT_THRESHOLD;
+    }
+    return parsed;
+}
+function roundPressure(raw) {
+    if (!Number.isFinite(raw) || raw < 0)
+        return 0;
+    return Math.round(raw * 1000) / 1000;
+}
+//# sourceMappingURL=auto-trigger.js.map

package/dist/core/compact/buffer-rewriter.js

@@ -0,0 +1,115 @@
+/**
+ * Type guard: discriminate a SessionEvent against the `compaction`
+ * kind. Used by replay code so the boundary marker drives a different
+ * code path than `user`/`persona`/`system` transcript rows.
+ */
+export function isCompactBoundary(event) {
+    if (event.kind !== 'compaction')
+        return false;
+    const p = event.payload;
+    if (p === null || typeof p !== 'object')
+        return false;
+    if (p.version !== 1)
+        return false;
+    if (p.trigger !== 'manual' && p.trigger !== 'auto')
+        return false;
+    if (typeof p.summary !== 'string' || p.summary.length === 0)
+        return false;
+    if (typeof p.summaryTokenCount !== 'number')
+        return false;
+    if (typeof p.summaryTurnsBefore !== 'number')
+        return false;
+    if (typeof p.keptTailTurns !== 'number')
+        return false;
+    if (typeof p.coversUntilOffset !== 'number')
+        return false;
+    return true;
+}
+/**
+ * Append one `compaction` boundary marker to the SessionStore. Returns
+ * the SessionEvent we wrote so the caller can echo it into the in-
+ * memory transcript without a re-read. Throws on store error so the
+ * caller surfaces the failure inline.
+ */
+export async function appendCompactBoundary(input) {
+    const ts = (input.now ?? (() => Date.now()))();
+    const payload = {
+        version: 1,
+        trigger: input.trigger,
+        summary: input.summary,
+        summaryTokenCount: input.summaryTokenCount,
+        summaryTurnsBefore: input.summaryTurnsBefore,
+        keptTailTurns: input.keptTailTurns,
+        coversUntilOffset: input.coversUntilOffset,
+    };
+    const event = {
+        t: ts,
+        kind: 'compaction',
+        payload,
+    };
+    await input.store.appendEvent(event);
+    return event;
+}
+/**
+ * Apply replay masking to a chronological event list. Given the full
+ * ordered events.jsonl content, return only the events the caller
+ * should render: every event AFTER the latest `compaction` boundary,
+ * plus the boundary itself (so the renderer can show the banner +
+ * summary), and the K kept-tail events that landed BEFORE the boundary
+ * but were preserved per the marker's `keptTailTurns`.
+ *
+ * Mask logic:
+ *  1. Walk events. Find the LATEST boundary by offset.
+ *  2. Index 0 .. coversUntilOffset-1 are masked, EXCEPT the last
+ *     `keptTailTurns` of that range (which are the verbatim tail).
+ *  3. The boundary event itself + everything after it stays.
+ *
+ * Why we expose this here (and not in session.ts): keeping the mask
+ * logic next to the writer means the wire format is owned by one
+ * module. session.ts depends on this; this depends on nothing in
+ * session.ts. Unidirectional.
+ */
+export function applyCompactMask(events) {
+    // Find latest compaction event.
+    let latestIdx = -1;
+    let latestPayload = null;
+    for (let i = events.length - 1; i >= 0; i -= 1) {
+        const ev = events[i];
+        if (isCompactBoundary(ev)) {
+            latestIdx = i;
+            latestPayload = ev.payload;
+            break;
+        }
+    }
+    if (latestIdx === -1 || latestPayload === null) {
+        return events;
+    }
+    // `coversUntilOffset` is the count of events that existed in the
+    // store immediately before the marker append. Events 0 ..
+    // coversUntilOffset-1 are summarised; events keptTailTurns of them
+    // are surfaced anyway as the verbatim tail.
+    const cap = Math.max(0, Math.min(latestPayload.coversUntilOffset, latestIdx));
+    const tailKeepCount = Math.max(0, Math.min(latestPayload.keptTailTurns, cap));
+    // Take the LAST tailKeepCount events from the masked range, but only
+    // those that represent renderable turns (user/persona/system).
+    // Boundary markers and tool stream events are NOT counted as turns
+    // for the tail-keep window — using them would let the keptTailTurns
+    // budget be consumed by infra events and the operator would lose
+    // the last K real turns. The spec is about "last K human-visible
+    // turns", not "last K events".
+    const tailSlice = [];
+    for (let i = cap - 1; i >= 0 && tailSlice.length < tailKeepCount; i -= 1) {
+        const ev = events[i];
+        if (ev.kind === 'user' || ev.kind === 'persona' || ev.kind === 'system') {
+            tailSlice.push(ev);
+        }
+    }
+    tailSlice.reverse();
+    // After the marker: everything that landed AFTER the boundary
+    // append. These are post-compaction events the user has not yet
+    // seen folded into a summary; they pass through verbatim.
+    const afterMarker = events.slice(latestIdx + 1);
+    const markerEvent = events[latestIdx];
+    return [...tailSlice, markerEvent, ...afterMarker];
+}
+//# sourceMappingURL=buffer-rewriter.js.map