@pugi/cli 0.1.0-beta.98 → 1.0.0-alpha.1

package/dist/core/dispatch/cache-cleanup.js

@@ -1,197 +0,0 @@
-/**
- * Fork-subagent cache-ref cleanup (—).
- *
- * GC pass for `.pugi/cache-refs/`. Two surfaces use this:
- *
- *  1. `pugi dispatch clear-cache-refs --older-than <duration>` — operator
- *     runs this after a long session to evict stale handles. The flag
- *     accepts an `--older-than` window (e.g. `1h`, `24h`, `7d`); refs
- *     whose `createdAt` falls outside the window are removed.
- *
- *  2. Background sweep on REPL boot — when `cleanupStaleCacheRefs` is
- *     called on session start with a default 24h window, the dispatcher
- *     auto-prunes refs left over from crashed processes. Idempotent
- *     and silent (no logs unless `verbose: true`).
- *
- * Design notes:
- *
- *  - Cleanup is path-scoped to `.pugi/cache-refs/` only. The function
- *    refuses to traverse outside that directory; a malicious symlink
- *    pointing at `~/.ssh/` would not cause damage because we only
- *    unlink files directly under cacheRefDir().
- *
- *  - Cleanup is best-effort. A ref file with a corrupted JSON body
- *    has no `createdAt` to compare against — the policy is to treat
- *    such files as "stale" because they cannot be reused anyway.
- *    They get evicted alongside out-of-window refs.
- *
- *  - The function returns a structured summary (counts + paths) so
- *    the CLI can render a deterministic report (`X refs removed,
- *    Y refs kept`).
- */
-import { readdirSync, readFileSync, statSync, rmSync } from 'node:fs';
-import { join } from 'node:path';
-import { cacheRefDir, cacheRefSchema } from './cache-handoff.js';
-const DEFAULT_OLDER_THAN_MS = 24 * 60 * 60 * 1000;
-/**
- * Sweep `.pugi/cache-refs/` for stale refs.
- *
- * Returns a CleanupResult with three buckets:
- *  - `removed`: refs that were unlinked (either older than window
- *    OR corrupt + therefore unusable).
- *  - `kept`:   refs that remain on disk after the sweep.
- *  - `corrupt`: refs that failed schema validation; these are also
- *    present in `removed` (the corrupt array is a sub-view for
- *    diagnostic surfaces).
- *
- * The function does not throw on individual file errors — it tracks
- * the failure (silent skip for unreadable files) and continues so a
- * single broken ref cannot block the rest of the sweep.
- */
-export function cleanupStaleCacheRefs(workspaceRoot, options = {}) {
-    const dir = cacheRefDir(workspaceRoot);
-    const now = options.now ?? Date.now;
-    const olderThanMs = options.olderThanMs ?? DEFAULT_OLDER_THAN_MS;
-    const verbose = options.verbose ?? false;
-    const cutoff = now() - olderThanMs;
-    let entries;
-    try {
-        entries = readdirSync(dir).filter((name) => name.endsWith('.json')).sort();
-    }
-    catch {
-        // No directory yet — nothing to clean. Return empty buckets so the
-        // caller's report says "0 refs removed" cleanly.
-        return {
-            removed: [],
-            kept: [],
-            corrupt: [],
-            removedCount: 0,
-            keptCount: 0,
-            corruptCount: 0,
-        };
-    }
-    const removed = [];
-    const kept = [];
-    const corrupt = [];
-    for (const name of entries) {
-        const full = join(dir, name);
-        let raw;
-        try {
-            raw = readFileSync(full, 'utf8');
-        }
-        catch {
-            // Unreadable — treat as corrupt and remove. mtime fallback path
-            // would be unreliable since we already failed to read the file.
-            removed.push(full);
-            corrupt.push(full);
-            tryUnlink(full, verbose);
-            continue;
-        }
-        let parsed;
-        try {
-            parsed = JSON.parse(raw);
-        }
-        catch {
-            removed.push(full);
-            corrupt.push(full);
-            tryUnlink(full, verbose);
-            continue;
-        }
-        const validated = cacheRefSchema.safeParse(parsed);
-        if (!validated.success) {
-            removed.push(full);
-            corrupt.push(full);
-            tryUnlink(full, verbose);
-            continue;
-        }
-        const createdAtMs = Date.parse(validated.data.createdAt);
-        // Date.parse returns NaN on invalid strings. Treat as stale.
-        const ageMs = Number.isFinite(createdAtMs)
-            ? createdAtMs
-            : tryStatMtime(full);
-        if (ageMs < cutoff) {
-            removed.push(full);
-            tryUnlink(full, verbose);
-        }
-        else {
-            kept.push(full);
-        }
-    }
-    return {
-        removed,
-        kept,
-        corrupt,
-        removedCount: removed.length,
-        keptCount: kept.length,
-        corruptCount: corrupt.length,
-    };
-}
-/* ------------------------------------------------------------------ */
-/* Duration parsing                                                  */
-/* ------------------------------------------------------------------ */
-/**
- * Parse a human-readable duration string (e.g. `1h`, `30m`, `7d`) into
- * milliseconds. Used by the `--older-than` CLI flag handler. Returns
- * null on parse failure so the CLI can surface a usage error.
- *
- * Accepted suffixes:
- *  - `ms` — milliseconds
- *  - `s` — seconds
- *  - `m` — minutes
- *  - `h` — hours
- *  - `d` — days
- *
- * A bare number with no suffix is rejected (the CLI requires explicit
- * units to avoid the "is 60 seconds or 60 minutes?" trap).
- */
-export function parseDuration(input) {
-    const trimmed = input.trim().toLowerCase();
-    if (!trimmed)
-        return null;
-    const match = trimmed.match(/^([0-9]+(?:\.[0-9]+)?)(ms|s|m|h|d)$/);
-    if (!match)
-        return null;
-    const value = Number(match[1]);
-    if (!Number.isFinite(value) || value < 0)
-        return null;
-    switch (match[2]) {
-        case 'ms':
-            return value;
-        case 's':
-            return value * 1000;
-        case 'm':
-            return value * 60 * 1000;
-        case 'h':
-            return value * 60 * 60 * 1000;
-        case 'd':
-            return value * 24 * 60 * 60 * 1000;
-        default:
-            return null;
-    }
-}
-/* ------------------------------------------------------------------ */
-/* Internals                                                         */
-/* ------------------------------------------------------------------ */
-function tryUnlink(path, verbose) {
-    try {
-        rmSync(path, { force: false });
-        if (verbose) {
-            process.stderr.write(`pugi-cache-cleanup: removed ${path}\n`);
-        }
-    }
-    catch {
-        // Concurrent cleanup raced us. Treat as success — the file is
-        // gone, which is what we wanted.
-    }
-}
-function tryStatMtime(path) {
-    try {
-        return statSync(path).mtimeMs;
-    }
-    catch {
-        // If we can't stat either, treat the ref as ancient so it gets
-        // evicted in the same pass.
-        return 0;
-    }
-}
-//# sourceMappingURL=cache-cleanup.js.map

package/dist/core/dispatch/cache-handoff.js

@@ -1,295 +0,0 @@
-/**
- * Fork-subagent prompt-cache inheritance (—).
- *
- * the upstream tool's leaked sub-agent spawn pattern: when a parent agent
- * dispatches a child via the Task tool, the child boots with the parent's
- * prompt cache REFERENCE inherited — not the conversation transcript
- * verbatim, but a provider-native cache handle that lets the child reuse
- * the parent's system prompt + cached tool definitions without re-paying
- * the prompt-prefix tokens on the first turn.
- *
- * Anthropic's `cache_control` block in their messages API exposes this
- * directly via cache breakpoints. OpenAI / xAI / Gemini have similar
- * primitives at different granularities; the wire payload our Anvil
- * proxy speaks is provider-agnostic, so we forward a generic
- * `parent_cache_id` hint and Anvil routes it onto the underlying
- * provider's cache primitive (or silently drops it if the provider
- * doesn't support cache inheritance — graceful degrade).
- *
- * What this module does:
- *
- *  1. `inheritCacheContext(parentSessionId, childAgentId)` —
- *     synthesises a cache handle for a child dispatch. Persists the
- *     handle to `.pugi/cache-refs/<child-agent-id>.json` so:
- *
- *       a. The child's own boot path can read it (e.g. a child engine
- *          loop running in a worktree subshell where the in-memory
- *          DispatcherContext isn't reachable).
- *       b. `pugi dispatch list-cache-refs` can surface active refs
- *          for debugging "why is my cache hit rate so low".
- *       c. `pugi dispatch clear-cache-refs --older-than 1h` can
- *          garbage-collect stale refs from crashed/killed children.
- *
- *  2. `readCacheRef(workspaceRoot, childAgentId)` — child-side read.
- *     Returns the persisted handle so the child's first engine loop
- *     turn can include the parent_cache_id hint in its request.
- *
- *  3. `cacheHandoffHookForRequest(handle)` — produces the wire payload
- *     shape that the Anvil bridge can splice into the
- *     `engineLoopServerRequest` body. Lives here (not in the bridge)
- *     so the cache-control schema is in one place.
- *
- * What this module does NOT do:
- *
- *  - It does not replay the parent's conversation transcript into the
- *    child. That would defeat the cyber-zoo isolation contract
- *    (`shared_fs_readonly` etc.). The child gets a CACHE HINT — the
- *    provider may use it to skip re-tokenising shared prompt prefix,
- *    but the LOGICAL conversation always starts fresh from the child's
- *    own system prompt + brief.
- *
- *  - It does not assume any provider honours the hint. Cache-miss is
- *    the default path. If Anvil routes the request to a model whose
- *    provider doesn't expose cache inheritance, the request still
- *    succeeds — just at full prompt-prefix cost.
- *
- *  - It does not rotate or invalidate the parent's cache on the
- *    parent's side. Parent cache lifecycle is owned by the parent
- *    engine loop; the child holds a read-only reference.
- *
- * Cross-reference:
- *  - apps/pugi-cli/src/core/subagents/dispatcher-real.ts — where the
- *    child engine loop is driven; the cache_id from this module is
- *    forwarded onto Anvil via the `extensions` field of the engine
- *    loop server request (β2 forward-compat slot).
- *  - packages/pugi-sdk/src/engine-loop.ts — engineLoopServerRequest
- *    schema; cache-handoff field is OPTIONAL and additive.
- *
- * Leak research §L10 (the upstream tool sub-agent spawn fork pattern):
- * docs/research/2026-05-27-leak-parity-sprint.md.
- */
-import { mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { join, resolve as resolvePath } from 'node:path';
-import { randomUUID } from 'node:crypto';
-import { z } from 'zod';
-/* ------------------------------------------------------------------ */
-/* Types + schema                                                    */
-/* ------------------------------------------------------------------ */
-/**
- * Persisted cache reference. The shape is intentionally minimal —
- * provider-specific cache tokens are opaque strings so the file format
- * does not couple to any one provider's API.
- *
- *  - `cacheId`        — opaque provider hint forwarded to Anvil.
- *                        Synthesized client-side as `pugi-cache-<uuid>`
- *                        so the server has a stable correlation key
- *                        even when the underlying provider's cache
- *                        object is not yet provisioned.
- *  - `contextRef`     — logical reference key the parent uses to tag
- *                        which prompt segments to re-use. Same value
- *                        as cacheId for the v1 wire (single breakpoint
- *                        per parent); reserved for future multi-breakpoint
- *                        schemes (split system + tools + first-user
- *                        segments).
- *  - `parentSessionId` — debugging / GC scoping. `list-cache-refs`
- *                        can group by parent session.
- *  - `childAgentId`   — the dispatch this ref is scoped to.
- *  - `createdAt`      — ISO timestamp for `--older-than` cleanup.
- *  - `schemaVersion`  — pinned to 1; bumped on breaking shape change.
- */
-export const cacheRefSchema = z.object({
-    schemaVersion: z.literal(1),
-    cacheId: z.string().min(1).max(256),
-    contextRef: z.string().min(1).max(256),
-    parentSessionId: z.string().min(1).max(256),
-    childAgentId: z.string().min(1).max(256),
-    createdAt: z.string().min(1),
-});
-/* ------------------------------------------------------------------ */
-/* Path resolution                                                   */
-/* ------------------------------------------------------------------ */
-/**
- * Resolve the directory under `.pugi/` where cache refs live. The
- * directory is created on first write — readers tolerate its absence
- * (no refs = empty list, not an error).
- */
-export function cacheRefDir(workspaceRoot) {
-    return resolvePath(workspaceRoot, '.pugi', 'cache-refs');
-}
-function cacheRefPath(workspaceRoot, childAgentId) {
-    // Sanitise the child id — directory traversal via crafted child id
-    // would let a dispatch target write outside the cache-refs dir. The
-    // child id format is owned by spawn.ts (`subagent-<uuid>`) but we
-    // defend in depth.
-    const safe = childAgentId.replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 200);
-    return join(cacheRefDir(workspaceRoot), `${safe}.json`);
-}
-/**
- * Synthesize a cache handle for a child dispatch and persist it to
- * `.pugi/cache-refs/<childAgentId>.json`. Returns the in-memory handle
- * the dispatcher feeds into the Anvil wire request.
- *
- * Idempotent: calling twice with the same `childAgentId` overwrites
- * the existing ref. The dispatcher's `taskId` is a UUID per dispatch,
- * so collisions are not expected, but the overwrite semantic is safer
- * than failing — a stale ref from a previous run (e.g. process killed
- * between spawn and run) should not block a fresh dispatch.
- */
-export function inheritCacheContext(parentSessionId, childAgentId, options) {
-    if (!parentSessionId) {
-        throw new Error('inheritCacheContext: parentSessionId must be non-empty');
-    }
-    if (!childAgentId) {
-        throw new Error('inheritCacheContext: childAgentId must be non-empty');
-    }
-    const now = options.now ?? defaultNow;
-    const cacheIdFactory = options.cacheIdFactory ?? defaultCacheId;
-    const cacheId = cacheIdFactory();
-    const ref = {
-        schemaVersion: 1,
-        cacheId,
-        contextRef: cacheId,
-        parentSessionId,
-        childAgentId,
-        createdAt: now(),
-    };
-    const dir = cacheRefDir(options.workspaceRoot);
-    mkdirSync(dir, { recursive: true });
-    const path = cacheRefPath(options.workspaceRoot, childAgentId);
-    writeFileSync(path, JSON.stringify(ref, null, 2), 'utf8');
-    return {
-        cacheId: ref.cacheId,
-        contextRef: ref.contextRef,
-        persistedPath: path,
-    };
-}
-/**
- * Child-side read. Returns null when the ref is missing or malformed
- * (the child boots without cache inheritance — degrade is silent so a
- * corrupted ref does not block a dispatch).
- *
- * Malformed ref files are NOT auto-deleted by this read path — that's
- * the cleanup command's job. A failed parse here just returns null so
- * the dispatch proceeds at full prompt-prefix cost.
- */
-export function readCacheRef(workspaceRoot, childAgentId) {
-    const path = cacheRefPath(workspaceRoot, childAgentId);
-    let raw;
-    try {
-        raw = readFileSync(path, 'utf8');
-    }
-    catch {
-        return null;
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        return null;
-    }
-    const validated = cacheRefSchema.safeParse(parsed);
-    if (!validated.success)
-        return null;
-    return validated.data;
-}
-/**
- * List every persisted cache ref under `.pugi/cache-refs/`. Used by
- * `pugi dispatch list-cache-refs` and by GC sweeps in
- * `cache-cleanup.ts`. Returns refs in deterministic
- * (filename-ascending) order so the CLI output is stable.
- *
- * Malformed ref files are silently skipped — the cleanup command can
- * surface them via a separate `--show-corrupt` flag if needed.
- */
-export function listCacheRefs(workspaceRoot) {
-    const dir = cacheRefDir(workspaceRoot);
-    let entries;
-    try {
-        entries = readdirSync(dir).filter((name) => name.endsWith('.json')).sort();
-    }
-    catch {
-        return [];
-    }
-    const refs = [];
-    for (const entry of entries) {
-        const full = join(dir, entry);
-        let raw;
-        try {
-            raw = readFileSync(full, 'utf8');
-        }
-        catch {
-            continue;
-        }
-        let parsed;
-        try {
-            parsed = JSON.parse(raw);
-        }
-        catch {
-            continue;
-        }
-        const validated = cacheRefSchema.safeParse(parsed);
-        if (!validated.success)
-            continue;
-        refs.push(validated.data);
-    }
-    return refs;
-}
-/* ------------------------------------------------------------------ */
-/* Wire-format hook                                                  */
-/* ------------------------------------------------------------------ */
-/**
- * Project the in-memory handle (or persisted ref) onto the wire-format
- * hint object that the Anvil bridge merges into the engine-loop
- * request body. Pulled out so callers (dispatcher-real, future bridge
- * adapters) all speak the same shape.
- */
-export function cacheHandoffHookForRequest(source) {
-    return {
-        parent_cache_id: source.cacheId,
-        cache_context_ref: source.contextRef,
-    };
-}
-/* ------------------------------------------------------------------ */
-/* Internals                                                         */
-/* ------------------------------------------------------------------ */
-function defaultNow() {
-    return new Date().toISOString();
-}
-function defaultCacheId() {
-    return `pugi-cache-${randomUUID()}`;
-}
-/* ------------------------------------------------------------------ */
-/* Stat helper (used by cache-cleanup.ts)                            */
-/* ------------------------------------------------------------------ */
-/**
- * Exposed for cache-cleanup.ts so the GC sweep can read mtime without
- * re-implementing the path-resolution logic. Returns null when the
- * file is gone (a concurrent cleanup may have raced us — silent miss).
- */
-export function cacheRefMtime(workspaceRoot, childAgentId) {
-    try {
-        const stat = statSync(cacheRefPath(workspaceRoot, childAgentId));
-        return stat.mtime;
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Delete a single cache ref. Returns true when the file existed and
- * was removed, false when it was already gone. Used by both the
- * `clear-cache-refs` CLI and by post-dispatch cleanup (a successful
- * subagent run does not need the cache ref to outlive its dispatch).
- */
-export function deleteCacheRef(workspaceRoot, childAgentId) {
-    const path = cacheRefPath(workspaceRoot, childAgentId);
-    try {
-        rmSync(path, { force: false });
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-//# sourceMappingURL=cache-handoff.js.map

package/dist/core/edits/apply-patch-layer-e.js

@@ -1,189 +0,0 @@
-const BEGIN_PATCH = '*** Begin Patch';
-const END_PATCH = '*** End Patch';
-const END_FILE = '*** End File';
-const ADD_FILE_PREFIX = '*** Add File: ';
-const UPDATE_FILE_PREFIX = '*** Update File: ';
-const DELETE_FILE_PREFIX = '*** Delete File: ';
-export function parseApplyPatch(envelope) {
-    const ops = [];
-    const errors = [];
-    const lines = envelope.replace(/\r\n/g, '\n').replace(/\r/g, '\n').split('\n');
-    if (envelope.trim().length === 0) {
-        return { ops, errors };
-    }
-    let foundBlock = false;
-    let index = 0;
-    while (index < lines.length) {
-        const line = lines[index];
-        if (line === undefined) {
-            index += 1;
-            continue;
-        }
-        if (line === BEGIN_PATCH) {
-            foundBlock = true;
-            const parsed = parseBlock(lines, index + 1);
-            ops.push(...parsed.ops);
-            if (parsed.error !== null) {
-                errors.push(parsed.error);
-            }
-            index = parsed.nextIndex;
-            continue;
-        }
-        if (line.trim().length > 0) {
-            errors.push(`Unexpected content outside patch block at line ${index + 1}: ${line}`);
-        }
-        index += 1;
-    }
-    if (!foundBlock) {
-        errors.push('No patch block found: expected *** Begin Patch');
-    }
-    return { ops, errors };
-}
-function parseBlock(lines, startIndex) {
-    const ops = [];
-    const blockErrors = [];
-    let pending = null;
-    let index = startIndex;
-    const flushPending = () => {
-        if (pending === null) {
-            return;
-        }
-        if (pending.kind === 'add') {
-            ops.push({
-                kind: 'add',
-                path: pending.path,
-                content: pending.contentLines.join('\n'),
-            });
-        }
-        else if (pending.kind === 'update') {
-            ops.push({
-                kind: 'update',
-                path: pending.path,
-                oldContent: pending.oldLines.join('\n'),
-                newContent: pending.newLines.join('\n'),
-            });
-        }
-        else {
-            ops.push({
-                kind: 'delete',
-                path: pending.path,
-            });
-        }
-        pending = null;
-    };
-    while (index < lines.length) {
-        const line = lines[index];
-        if (line === undefined) {
-            index += 1;
-            continue;
-        }
-        if (line === END_PATCH) {
-            flushPending();
-            return {
-                ops,
-                error: blockErrors.length > 0 ? blockErrors.join('; ') : null,
-                nextIndex: index + 1,
-            };
-        }
-        if (line === BEGIN_PATCH) {
-            flushPending();
-            blockErrors.push(`Missing ${END_PATCH} before new patch block at line ${index + 1}`);
-            return {
-                ops,
-                error: blockErrors.join('; '),
-                nextIndex: index,
-            };
-        }
-        if (line === END_FILE) {
-            flushPending();
-            index += 1;
-            continue;
-        }
-        if (line.startsWith(ADD_FILE_PREFIX)) {
-            flushPending();
-            const path = parsePath(line.slice(ADD_FILE_PREFIX.length));
-            if (path.length === 0) {
-                blockErrors.push(`Missing add file path at line ${index + 1}`);
-            }
-            pending = { kind: 'add', path, contentLines: [] };
-            index += 1;
-            continue;
-        }
-        if (line.startsWith(UPDATE_FILE_PREFIX)) {
-            flushPending();
-            const path = parsePath(line.slice(UPDATE_FILE_PREFIX.length));
-            if (path.length === 0) {
-                blockErrors.push(`Missing update file path at line ${index + 1}`);
-            }
-            pending = { kind: 'update', path, oldLines: [], newLines: [] };
-            index += 1;
-            continue;
-        }
-        if (line.startsWith(DELETE_FILE_PREFIX)) {
-            flushPending();
-            const path = parsePath(line.slice(DELETE_FILE_PREFIX.length));
-            if (path.length === 0) {
-                blockErrors.push(`Missing delete file path at line ${index + 1}`);
-            }
-            pending = { kind: 'delete', path };
-            index += 1;
-            continue;
-        }
-        if (pending === null) {
-            if (line.trim().length > 0) {
-                blockErrors.push(`Unexpected line without active file operation at line ${index + 1}: ${line}`);
-            }
-            index += 1;
-            continue;
-        }
-        if (pending.kind === 'add') {
-            if (line.startsWith('+')) {
-                pending.contentLines.push(line.slice(1));
-            }
-            else if (line.trim().length > 0) {
-                blockErrors.push(`Unexpected add line at line ${index + 1}: ${line}`);
-            }
-            index += 1;
-            continue;
-        }
-        if (pending.kind === 'update') {
-            if (line.startsWith('-')) {
-                pending.oldLines.push(line.slice(1));
-            }
-            else if (line.startsWith('+')) {
-                pending.newLines.push(line.slice(1));
-            }
-            else if (line.startsWith('@@')) {
-                // Context marker; accepted but not included in structured content.
-            }
-            else if (line.trim().length > 0) {
-                // Unchanged context line; accepted but not included in structured content.
-            }
-            index += 1;
-            continue;
-        }
-        if (line.trim().length > 0) {
-            blockErrors.push(`Unexpected delete content at line ${index + 1}: ${line}`);
-        }
-        index += 1;
-    }
-    flushPending();
-    blockErrors.push(`Missing ${END_PATCH}`);
-    return {
-        ops,
-        error: blockErrors.join('; '),
-        nextIndex: index,
-    };
-}
-function parsePath(rawPath) {
-    const path = rawPath.trim();
-    if (path.length >= 2) {
-        const first = path[0];
-        const last = path[path.length - 1];
-        if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
-            return path.slice(1, -1);
-        }
-    }
-    return path;
-}
-//# sourceMappingURL=apply-patch-layer-e.js.map