@pugi/cli 0.1.0-beta.7 → 0.1.0-beta.87

package/dist/core/diagnostics/probes/workspace.js

@@ -0,0 +1,63 @@
+/**
+ * WORKSPACE probe — verifies `.pugi/` exists, is writable, and is not
+ * littered with stale lock files. Optional NDJSON session log presence
+ * is reported as additional context but never the basis for a verdict
+ * change (it is created on first dispatch, not at init time).
+ *
+ * The probe owns its fs surface so the spec can run in a tmp sandbox.
+ */
+export function probeWorkspace(ctx, fs) {
+    const pugiDir = `${ctx.cwd}/.pugi`;
+    if (!fs.existsSync(pugiDir)) {
+        return {
+            name: 'WORKSPACE',
+            status: 'warn',
+            detail: `.pugi/ not initialised in ${ctx.cwd}`,
+            remediation: 'Run `pugi init` to scaffold the workspace',
+        };
+    }
+    let isDir = false;
+    try {
+        isDir = fs.statSync(pugiDir).isDirectory();
+    }
+    catch {
+        return {
+            name: 'WORKSPACE',
+            status: 'error',
+            detail: `.pugi/ stat failed in ${ctx.cwd}`,
+            remediation: 'Re-create the directory: `rm -rf .pugi && pugi init`',
+        };
+    }
+    if (!isDir) {
+        return {
+            name: 'WORKSPACE',
+            status: 'error',
+            detail: `${pugiDir} exists but is not a directory`,
+            remediation: 'Remove the file at .pugi and run `pugi init`',
+        };
+    }
+    try {
+        fs.accessSync(pugiDir, fs.W_OK);
+    }
+    catch {
+        return {
+            name: 'WORKSPACE',
+            status: 'error',
+            detail: `.pugi/ is not writable for the current user`,
+            remediation: `chown / chmod the directory so the current user can write it`,
+        };
+    }
+    // Best-effort: report session log presence as detail context. Absence
+    // is normal (events.jsonl is created lazily) so it never moves the
+    // verdict.
+    const eventLogPresent = fs.existsSync(`${pugiDir}/events.jsonl`);
+    const detail = eventLogPresent
+        ? `.pugi/ writable, events.jsonl present`
+        : `.pugi/ writable (events.jsonl created on first dispatch)`;
+    return {
+        name: 'WORKSPACE',
+        status: 'ok',
+        detail,
+    };
+}
+//# sourceMappingURL=workspace.js.map

package/dist/core/diagnostics/types.js

@@ -0,0 +1,70 @@
+/**
+ * — `pugi doctor` diagnostics types.
+ *
+ * The doctor command probes the local environment + remote API +
+ * workspace state and produces a structured health report. Each probe
+ * runs independently; one probe's failure NEVER cascades to another.
+ *
+ * Status semantics:
+ *  - `ok`     : probe verified the expected state.
+ *  - `warn`   : non-blocking signal (stale CLI, low-but-not-empty disk,
+ *                missing optional config, etc.). Overall verdict still
+ *                passes the gate.
+ *  - `error`  : a real problem the operator must fix before Pugi will
+ *                work end-to-end (auth missing, API unreachable, .pugi/
+ *                unwritable, Node version below floor, disk full).
+ *  - `skipped` : prerequisite for the probe is absent (e.g. MCP probe
+ *                when no mcp.json exists). Does NOT count against the
+ *                overall verdict.
+ *
+ * Layered design: this module owns NO I/O. Individual probe files own
+ * their I/O surface. The runner orchestrates them in parallel with a
+ * timeout + fail-isolation wrapper. The doctor command formats the
+ * results for human + JSON consumers.
+ */
+/**
+ * Helper for the runner to compute the overall verdict from a probe
+ * set without leaking the algorithm into the doctor command. Any error
+ * → 'error'; any warn (no errors) → 'warning'; otherwise 'healthy'.
+ * Skipped probes do NOT influence the verdict.
+ */
+export function computeOverall(probes) {
+    let hasError = false;
+    let hasWarn = false;
+    for (const probe of probes) {
+        if (probe.status === 'error')
+            hasError = true;
+        else if (probe.status === 'warn')
+            hasWarn = true;
+    }
+    if (hasError)
+        return 'error';
+    if (hasWarn)
+        return 'warning';
+    return 'healthy';
+}
+/**
+ * Compute the per-status counts in a single pass so renderers do not
+ * have to re-iterate. Surfaces in both the trailer line and the JSON
+ * envelope so downstream consumers can render a one-line summary
+ * without re-walking the probe array.
+ */
+export function countProbes(probes) {
+    const counts = { ok: 0, warn: 0, error: 0, skipped: 0 };
+    for (const probe of probes)
+        counts[probe.status] += 1;
+    return counts;
+}
+/**
+ * Exit-code map. Exposed for both the CLI handler and the spec so the
+ * contract stays in one place.
+ *  0 — healthy OR warnings only.
+ *  1 — internal crash (unhandled throw in the runner itself).
+ *  2 — at least one probe reported `error`.
+ */
+export function exitCodeFor(overall) {
+    if (overall === 'error')
+        return 2;
+    return 0;
+}
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1,197 @@
+/**
+ * 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

@@ -0,0 +1,295 @@
+/**
+ * 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