@pugi/cli 0.1.0-beta.3 → 0.1.0-beta.31

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

package/dist/core/compact/summarizer.js

@@ -0,0 +1,208 @@
+import { estimateTokens } from './token-counter.js';
+/**
+ * System prompt for the summarizer. Six closed sections + brand
+ * voice clamp + "no tool calls" sentinel. The headings are stable
+ * markdown so a downstream renderer can split + reformat without
+ * re-parsing the model output.
+ *
+ * Why the explicit `If a section has no content` rule: empty sections
+ * cost zero tokens but their absence is meaningful — the second model
+ * reading the memo learns "no decisions were made yet" from the empty
+ * `## Decisions` header. Without the rule we observed models silently
+ * dropping empty sections and the reader could not distinguish "no
+ * decisions" from "summarizer forgot the section".
+ */
+const SUMMARIZE_SYSTEM_PROMPT = [
+    'You are the Pugi conversation summarizer. Compress the supplied',
+    'transcript into a six-section memo. Operator picks the work back up',
+    'from this memo — accuracy and completeness matter more than brevity.',
+    '',
+    'OUTPUT FORMAT (verbatim section headings, in this order):',
+    '',
+    "## Intent",
+    '(What the operator is trying to accomplish, in one paragraph.)',
+    '',
+    "## Decisions",
+    '(Bullet list of decisions made + the reasoning. Empty section means',
+    'no decisions yet — render the heading anyway.)',
+    '',
+    "## Files",
+    '(Bullet list of file paths touched, with one-line "why".)',
+    '',
+    "## Errors",
+    '(Bullet list of errors encountered + how each was resolved. Empty',
+    'means no errors — still render the heading.)',
+    '',
+    "## Tools",
+    '(Bullet list of notable tool calls and their outcomes. Group similar',
+    'calls; the goal is to surface meaningful state changes, not log',
+    'every Read.)',
+    '',
+    "## Next",
+    '(One paragraph: the immediate next planned action.)',
+    '',
+    'RULES:',
+    '- Do not invent state. Only summarise what is in the transcript.',
+    '- Preserve file paths verbatim.',
+    '- Do not call any tools (you have none).',
+    '- Do not address the operator. Write in third person.',
+    '- No emoji. No em dashes.',
+].join('\n');
+/**
+ * Convert a slice of session events into the user message body the
+ * summarizer ingests. We keep the format simple: one event per line,
+ * prefixed with the kind, so the model can see role boundaries. Tool
+ * outputs are length-capped at 4 KB each so a single 200 KB grep result
+ * does not blow the summarizer's own context budget.
+ */
+const TOOL_PAYLOAD_CAP_BYTES = 4096;
+export function renderEventsForSummary(events) {
+    const lines = [];
+    for (const event of events) {
+        const rendered = renderOneEvent(event);
+        if (rendered !== null)
+            lines.push(rendered);
+    }
+    return lines.join('\n');
+}
+function renderOneEvent(event) {
+    const payload = (event.payload ?? null);
+    switch (event.kind) {
+        case 'user': {
+            const text = stringField(payload, 'brief') ?? stringField(payload, 'text') ?? '';
+            if (text.length === 0)
+                return null;
+            return `[operator] ${text}`;
+        }
+        case 'persona': {
+            const text = stringField(payload, 'text') ?? '';
+            if (text.length === 0)
+                return null;
+            const slug = stringField(payload, 'personaSlug') ?? 'persona';
+            return `[${slug}] ${text}`;
+        }
+        case 'system': {
+            const text = stringField(payload, 'text') ?? '';
+            if (text.length === 0)
+                return null;
+            return `[system] ${text}`;
+        }
+        case 'tool.start': {
+            const toolName = stringField(payload, 'toolName') ?? 'unknown';
+            const args = stringField(payload, 'args') ?? '';
+            return `[tool.start ${toolName}] ${truncate(args, TOOL_PAYLOAD_CAP_BYTES)}`;
+        }
+        case 'tool.result': {
+            const toolName = stringField(payload, 'toolName') ?? 'unknown';
+            const result = stringField(payload, 'result') ?? '';
+            return `[tool.result ${toolName}] ${truncate(result, TOOL_PAYLOAD_CAP_BYTES)}`;
+        }
+        case 'agent.spawned': {
+            const slug = stringField(payload, 'personaSlug') ?? 'unknown';
+            return `[agent.spawned ${slug}]`;
+        }
+        case 'agent.completed': {
+            const slug = stringField(payload, 'personaSlug') ?? 'unknown';
+            return `[agent.completed ${slug}]`;
+        }
+        case 'compaction': {
+            // Pre-existing compact marker — its `summary` payload IS the
+            // condensed form of older history. We pass it through verbatim so
+            // the summarizer treats it as already-summarised state and folds
+            // it into the new memo (rather than re-summarising garbage).
+            const summary = stringField(payload, 'summary') ?? '';
+            if (summary.length === 0)
+                return null;
+            return `[prior compaction]\n${summary}`;
+        }
+        case 'rewind-marker': {
+            // L9 (2026-05-27): rewind tombstones are infrastructure rows that
+            // describe a transcript edit, not conversation content. They
+            // never carry user-visible prose; the summariser drops them so
+            // the produced memo focuses on actual operator/persona turns.
+            // The masked range (events the marker covers) is already elided
+            // by `applyRewindMask` before this function is reached, so the
+            // summariser only sees a marker when it sits OUTSIDE every active
+            // rewind range — in which case the marker has already been
+            // cancelled by an undo-rewind and contributes nothing.
+            return null;
+        }
+        default: {
+            // Forward-compat: unknown kinds get a structural fingerprint so
+            // the summarizer can still represent them.
+            const exhaustive = event.kind;
+            void exhaustive;
+            return null;
+        }
+    }
+}
+function stringField(payload, key) {
+    if (!payload)
+        return undefined;
+    const value = payload[key];
+    return typeof value === 'string' ? value : undefined;
+}
+function truncate(s, capBytes) {
+    if (Buffer.byteLength(s, 'utf8') <= capBytes)
+        return s;
+    // Naive cut on UTF-16 chars — good enough for the summarizer; we
+    // append a marker so the model knows content was elided.
+    return `${s.slice(0, Math.floor(capBytes / 2))}\n... [truncated]`;
+}
+/**
+ * Run one summarisation round. Throws on transport error (the caller
+ * surfaces a one-line message to the operator and aborts the compact).
+ * Returns the structured result on success.
+ */
+export async function summarizeEvents(input) {
+    if (input.events.length === 0) {
+        throw new SummarizerError('refusing-to-summarize-empty-slice', 'No events to summarize.');
+    }
+    const userBody = renderEventsForSummary(input.events);
+    if (userBody.length === 0) {
+        throw new SummarizerError('refusing-to-summarize-empty-slice', 'All events rendered as empty.');
+    }
+    const messages = [
+        { role: 'system', content: SUMMARIZE_SYSTEM_PROMPT },
+        { role: 'user', content: userBody },
+    ];
+    const response = await input.client.send(messages, [], {
+        personaSlug: input.personaSlug,
+        tag: { tag: 'summarize' },
+        maxTokens: 2048,
+        temperature: 0.1,
+        ...(input.model !== undefined ? { model: input.model } : {}),
+        ...(input.signal !== undefined ? { signal: input.signal } : {}),
+    });
+    if (response.stop === 'error') {
+        throw new SummarizerError(response.code, `Summarizer transport failed: ${response.message}`);
+    }
+    if (response.stop === 'tool_use') {
+        // Sanity guard. We pass tools: [] so the model should not be able
+        // to invoke any; if Anvil's prompt template ever leaks tool defs
+        // we want a hard failure rather than a silent dropped summary.
+        throw new SummarizerError('unexpected-tool-call', 'Summarizer returned tool_use despite tools: []. Treating as failure.');
+    }
+    const summary = response.content.trim();
+    if (summary.length === 0) {
+        throw new SummarizerError('empty-summary', 'Summarizer returned an empty body.');
+    }
+    return {
+        summary,
+        tokensSummarised: estimateTokens(userBody),
+        eventsSummarised: input.events.length,
+    };
+}
+/**
+ * Error class so the caller can branch on `error instanceof
+ * SummarizerError` and surface `error.code` to the operator.
+ */
+export class SummarizerError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'SummarizerError';
+        this.code = code;
+    }
+}
+//# sourceMappingURL=summarizer.js.map

package/dist/core/compact/token-counter.js

@@ -0,0 +1,108 @@
+/**
+ * Approximate token counter for the `/compact` auto-trigger gate.
+ *
+ * Pugi does not bundle tiktoken — adding a 3 MB native module for a
+ * single heuristic check after every turn is the wrong trade. We instead
+ * use the OpenAI rule-of-thumb that 1 token ≈ 4 characters of English
+ * (≈ ¾ of a word). For mixed-language conversations the approximation
+ * skews high by 10-20% which is the safe direction — the auto-compact
+ * threshold trips slightly EARLY, never LATE. A late trigger would
+ * exceed the model's actual context window and crash the next turn.
+ *
+ * Per-model context windows are exported from `MODEL_CONTEXT_WINDOW` so
+ * the caller can resolve the budget from the active model slug without
+ * round-tripping to the server. New models added in Anvil should grow
+ * this table in lockstep; the fall-back is the conservative 32k window.
+ *
+ * Override hook: when `PUGI_TOKEN_COUNTER_OVERRIDE` is set the function
+ * parses it as a JSON object `{"text": <n>}` (number of tokens to claim
+ * per char). Used only by the integration spec — never by production.
+ */
+/** Default chars-per-token ratio for the OpenAI rule-of-thumb. */
+const DEFAULT_CHARS_PER_TOKEN = 4;
+/**
+ * Conservative fallback window when the model slug is unknown. 32k is
+ * the smallest window any current Anvil-served model exposes; using it
+ * as a fall-back guarantees we never overestimate budget and skip a
+ * compaction that should have fired.
+ */
+const FALLBACK_WINDOW = 32_000;
+/**
+ * Known context windows for models Anvil exposes today. Keep in sync
+ * with `apps/admin-api/src/pugi/model-registry.ts` — when a new model
+ * lands there, add it here. The table is intentionally narrow: only
+ * models we have actually validated.
+ */
+export const MODEL_CONTEXT_WINDOW = Object.freeze({
+    'sonnet-4.6': 200_000,
+    'sonnet-4.5': 200_000,
+    'opus-4.7': 1_000_000,
+    'opus-4.6': 200_000,
+    'haiku-4.5': 200_000,
+    'deepseek-chat-v3.1': 128_000,
+    'gpt-5': 200_000,
+    'gemini-2.5-pro': 1_000_000,
+});
+/**
+ * Estimate the token count of a single string. Returns a positive
+ * integer for non-empty input and zero for empty input. The function is
+ * pure — same input always yields the same output.
+ *
+ * The approximation is `ceil(byteLength / chars-per-token)`. We use
+ * `Buffer.byteLength` so multi-byte UTF-8 sequences count proportionally
+ * to their on-the-wire size, not their char count — this matches the
+ * tokenizer's behaviour on CJK / cyrillic / emoji where one char often
+ * eats 3-4 tokens.
+ */
+export function estimateTokens(text) {
+    if (text.length === 0)
+        return 0;
+    const ratio = readCharsPerTokenOverride() ?? DEFAULT_CHARS_PER_TOKEN;
+    const bytes = Buffer.byteLength(text, 'utf8');
+    return Math.max(1, Math.ceil(bytes / ratio));
+}
+/**
+ * Resolve the context window in tokens for the given model slug. Falls
+ * back to the conservative 32k window when the slug is unknown.
+ */
+export function contextWindowForModel(model) {
+    if (!model)
+        return FALLBACK_WINDOW;
+    const known = MODEL_CONTEXT_WINDOW[model];
+    return known ?? FALLBACK_WINDOW;
+}
+/**
+ * Sum the token estimates of an arbitrary list of strings. Convenience
+ * for the auto-trigger which has to count across N transcript turns.
+ */
+export function estimateTokensInMany(parts) {
+    let total = 0;
+    for (const part of parts) {
+        total += estimateTokens(part);
+    }
+    return total;
+}
+/**
+ * Read the test override env. Returns the parsed chars-per-token ratio
+ * when set, or undefined when absent / malformed. Never throws.
+ */
+function readCharsPerTokenOverride() {
+    const raw = process.env['PUGI_TOKEN_COUNTER_OVERRIDE'];
+    if (!raw)
+        return undefined;
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === 'object'
+            && parsed !== null
+            && typeof parsed.charsPerToken === 'number') {
+            const ratio = parsed.charsPerToken;
+            if (Number.isFinite(ratio) && ratio > 0)
+                return ratio;
+        }
+    }
+    catch {
+        /* malformed env, fall through */
+    }
+    return undefined;
+}
+//# sourceMappingURL=token-counter.js.map

package/dist/core/consensus/diff-capture.js

@@ -6,6 +6,10 @@
  *
  *   1. `--pr <number>`    — uses `gh pr diff <num>` (gh CLI required).
  *   2. `--commit <sha>`   — diff of that commit vs its first parent.
+ *                           When `--base <ref>` is ALSO provided, the
+ *                           diff is the range `<base>..<commit>` instead
+ *                           (mirrors `git diff base..commit` — covers the
+ *                           full PR-style payload, not just the tip).
  *   3. `--branch <name>`  — diff of HEAD vs `origin/<name>` merge-base.
  *   4. (default)          — diff of HEAD vs `origin/main` merge-base
  *                           covering BOTH committed-since-base AND
@@ -95,6 +99,16 @@ export function captureDiff(spec) {
         return captureFromPr(cwd, spec.pr);
     }
     if (typeof spec.commit === 'string' && spec.commit.length > 0) {
+        // When `--base` is supplied alongside `--commit`, callers want the
+        // full PR-style range diff (`base..commit`), not just the tip
+        // commit's parent diff. This matches the convention used by
+        // `git diff <base>..<commit>` everywhere else in the toolchain and
+        // is the verified-correct mode for reviewing a PR head ref. Without
+        // this branch, `--base` was silently ignored when `--commit` was
+        // present — see feedback_pugi_review_use_range_diff_not_worktree.
+        if (typeof spec.baseRef === 'string' && spec.baseRef.length > 0) {
+            return captureFromRange(cwd, spec.baseRef, spec.commit);
+        }
         return captureFromCommit(cwd, spec.commit);
     }
     if (typeof spec.branch === 'string' && spec.branch.length > 0) {
@@ -192,6 +206,65 @@ function captureFromCommit(cwd, commit) {
         },
     };
 }
+/**
+ * Range capture for `--commit <X> --base <Y>` — diff equivalent to
+ * `git diff <base>..<commit>`. Used when the operator names BOTH endpoints
+ * (typical PR review against a remote head SHA).
+ *
+ * Critical: this MUST be a pure read-only range diff against named refs.
+ * The previous behavior fell through to `captureFromCommit` which only
+ * showed the tip commit (`commit~1..commit`) — fine for single-commit
+ * review, wrong for multi-commit PRs. Worse, a stale fallback path was
+ * sending the working tree diff (`git diff` with no args), which caused
+ * every review on 2026-05-27 to surface identical noise from uncommitted
+ * `.gitignore` edits instead of the actual PR contents.
+ *
+ * Working tree integrity: only `git diff <ref>..<ref>` and metadata
+ * `log` / `rev-parse` / `name-rev` are used — none of these touch the
+ * index, working tree, or HEAD.
+ */
+function captureFromRange(cwd, baseRef, commit) {
+    // Resolve both endpoints up front so an unknown ref errors with a
+    // clear message before the diff invocation. `rev-parse` is read-only.
+    const fullCommit = safeExec(cwd, 'git', ['rev-parse', commit]).trim();
+    if (!fullCommit)
+        throw new Error(`Unknown commit ref: ${commit}`);
+    // Resolve the base: accept already-qualified refs (`origin/main`,
+    // `refs/heads/foo`) and bare branch names. If the bare name isn't
+    // locally resolvable, retry against `origin/<name>` — the common
+    // CI shape where local main is absent but the remote tracking ref is.
+    let resolvedBase = safeExecOptional(cwd, 'git', ['rev-parse', baseRef]).trim();
+    let effectiveBase = baseRef;
+    if (!resolvedBase && !baseRef.includes('/')) {
+        const remoteBase = `origin/${baseRef}`;
+        resolvedBase = safeExecOptional(cwd, 'git', ['rev-parse', remoteBase]).trim();
+        if (resolvedBase)
+            effectiveBase = remoteBase;
+    }
+    if (!resolvedBase)
+        throw new Error(`Unknown base ref: ${baseRef}`);
+    const diff = safeExec(cwd, 'git', [
+        'diff',
+        `${resolvedBase}..${fullCommit}`,
+        '--',
+        '.',
+        ...PROTECTED_PATHSPEC_EXCLUDES,
+    ]);
+    const cappedDiff = capDiff(diff);
+    const subject = safeExec(cwd, 'git', ['log', '-1', '--pretty=%s', fullCommit]).trim();
+    const branch = safeExec(cwd, 'git', ['name-rev', '--name-only', fullCommit]).trim() || 'detached';
+    const stats = computeStats(cappedDiff);
+    return {
+        diff: cappedDiff,
+        context: {
+            branch,
+            commit: shortSha(fullCommit),
+            title: subject || `commit ${shortSha(fullCommit)}`,
+            ref: `range:${effectiveBase}..${shortSha(fullCommit)}`,
+            stats,
+        },
+    };
+}
 function captureFromBranch(cwd, branch, baseRef) {
     const remoteRef = branch.includes('/') ? branch : `origin/${branch}`;
     const mergeBase = safeExec(cwd, 'git', ['merge-base', baseRef, remoteRef]).trim();

package/dist/core/context/index.js

@@ -18,4 +18,11 @@ export { BASELINE_IGNORE_PATTERNS, SECRET_IGNORE_PATTERNS, globalPugiIgnorePath,
 export { COLLAPSE_DIR_ENTRIES, MAX_README_LINES, MAX_SKELETON_BYTES, MAX_TREE_DEPTH, MAX_WALK_NODES, TOP_LANGUAGES, buildRepoSkeleton, detectPackageManager, languageForExtension, readGitBranch, readPackageJson, readReadme, renderSkeleton, topLanguages, } from './repo-skeleton.js';
 export { DEFAULT_WORKING_SET_CAPACITY, WorkingSet, } from './working-set.js';
 export { MAX_WATCHED_PATHS, PugiWatcher, THROTTLE_WINDOW_MS, } from './watcher.js';
+/**
+ * β5a R4+P5 — per-directory PUGI.md / AGENTS.md / CLAUDE.md / GEMINI.md
+ * traverse-up. Loads agent-context markdown at every directory between
+ * `cwd` and `workspaceRoot` (workspace root file is owned by
+ * `loadMarkdownContext` in `markdown-loader.ts` — no double-load).
+ */
+export { MAX_TRAVERSE_BYTES, MAX_TRAVERSE_PER_FILE_BYTES, MAX_TRAVERSE_DEPTH, TRAVERSE_SOURCES, loadTraversedMarkdown, } from './markdown-traverse.js';
 //# sourceMappingURL=index.js.map