@pugi/cli 0.1.0-beta.25 → 0.1.0-beta.27

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

@@ -0,0 +1,295 @@
+/**
+ * Fork-subagent prompt-cache inheritance (Leak L10 — 2026-05-27).
+ *
+ * Claude Code'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 (Claude Code sub-agent spawn fork pattern):
+ * docs/research/2026-05-27-leak-parity-sprint.md (research memo).
+ */
+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/memory-sync/queue.js

@@ -0,0 +1,158 @@
+/**
+ * Pugi memory sync queue (ADR-0063 Day 4).
+ *
+ * Local pending-write queue for `pugi memory` commands when the
+ * operator is offline or the admin-api is unreachable. Each pending
+ * mutation lands on disk as one JSONL line; `pugi memory sync` reads
+ * the queue, fires them to the admin-api in order, and rewrites the
+ * file with only the entries that still failed.
+ *
+ * Storage:
+ *
+ *   ~/.pugi/memory-queue.jsonl          (mode 0600)
+ *
+ * Each line is a fully-typed `PendingMemoryOperation` envelope. The
+ * envelope is forward-compatible: an older CLI reading a JSONL file
+ * written by a newer CLI silently skips lines whose `op` field is
+ * not in its known set (so a partial-rollback scenario doesn't crash
+ * the queue).
+ *
+ * Design intent:
+ *   - Append-only on disk for the hot path (`pugi memory write` /
+ *     `pugi memory forget` queue when offline). Rewrites only on
+ *     successful sync.
+ *   - One file per operator (PUGI_HOME-aware). Queue is local to the
+ *     machine — no cross-host coordination. Multi-device sync is
+ *     deferred to Phase 6 (server-side outbox).
+ *   - No fsync / atomic rename ceremony in v1 — best effort. The
+ *     queue is a convenience surface, not a durability primitive;
+ *     the source of truth is the admin-api row.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+import { z } from 'zod';
+/** Six canonical kinds — must mirror `apps/admin-api/src/persona-memory/persona-memory.types.ts`. */
+export const PERSONA_MEMORY_KINDS = [
+    'pattern',
+    'preference',
+    'architecture',
+    'bug',
+    'workflow',
+    'fact',
+];
+const writeOpSchema = z.object({
+    op: z.literal('write'),
+    enqueuedAt: z.string().datetime(),
+    personaSlug: z.string().min(1).max(64),
+    kind: z.enum(PERSONA_MEMORY_KINDS),
+    content: z.string().min(1).max(4000),
+    forgetAfter: z.string().datetime().nullable().optional(),
+});
+const forgetOpSchema = z.object({
+    op: z.literal('forget'),
+    enqueuedAt: z.string().datetime(),
+    id: z.string().min(1),
+});
+const pendingMemoryOpSchema = z.discriminatedUnion('op', [
+    writeOpSchema,
+    forgetOpSchema,
+]);
+/** Default storage path. Override via `PUGI_HOME` for tests / multi-account. */
+export function defaultQueuePath() {
+    const root = process.env.PUGI_HOME ?? resolve(homedir(), '.pugi');
+    return resolve(root, 'memory-queue.jsonl');
+}
+/**
+ * Append one pending operation to the queue file. Creates the parent
+ * directory + file with mode 0600 if missing. Pure-disk, no network.
+ *
+ * Returns the count of pending ops after the append (1-based) so the
+ * CLI command can render "queued (3 pending) — run `pugi memory sync`".
+ */
+export function enqueueMemoryOp(op, pathOverride) {
+    const fullOp = {
+        ...op,
+        enqueuedAt: new Date().toISOString(),
+    };
+    pendingMemoryOpSchema.parse(fullOp);
+    const queuePath = pathOverride ?? defaultQueuePath();
+    ensureQueueFile(queuePath);
+    const existing = readFileSync(queuePath, 'utf-8');
+    const line = `${JSON.stringify(fullOp)}\n`;
+    writeFileSync(queuePath, `${existing}${line}`, { encoding: 'utf-8', mode: 0o600 });
+    // Best-effort chmod (in case the file existed already at the wrong mode).
+    try {
+        chmodSync(queuePath, 0o600);
+    }
+    catch {
+        // ignore — the file was just written above, mode might be platform-dependent.
+    }
+    return countPending(queuePath);
+}
+/** Read the queue file and return parsed entries. Skips unknown / malformed lines. */
+export function readMemoryQueue(pathOverride) {
+    const queuePath = pathOverride ?? defaultQueuePath();
+    if (!existsSync(queuePath))
+        return [];
+    const raw = readFileSync(queuePath, 'utf-8');
+    const out = [];
+    for (const line of raw.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const parsed = pendingMemoryOpSchema.parse(JSON.parse(trimmed));
+            out.push(parsed);
+        }
+        catch {
+            // forward-compat: a future op kind we don't recognise should not
+            // crash the queue; just drop the line during this read.
+            continue;
+        }
+    }
+    return out;
+}
+/** Rewrite the queue file with `remaining` entries only. Empty array clears the file. */
+export function rewriteMemoryQueue(remaining, pathOverride) {
+    const queuePath = pathOverride ?? defaultQueuePath();
+    ensureQueueFile(queuePath);
+    if (remaining.length === 0) {
+        writeFileSync(queuePath, '', { encoding: 'utf-8', mode: 0o600 });
+        return;
+    }
+    const body = remaining.map((op) => JSON.stringify(op)).join('\n') + '\n';
+    writeFileSync(queuePath, body, { encoding: 'utf-8', mode: 0o600 });
+}
+/** Count pending ops without re-parsing every line individually for the typed shape. */
+export function countPending(pathOverride) {
+    const queuePath = pathOverride ?? defaultQueuePath();
+    if (!existsSync(queuePath))
+        return 0;
+    const raw = readFileSync(queuePath, 'utf-8');
+    let n = 0;
+    for (const line of raw.split(/\r?\n/)) {
+        if (line.trim().length > 0)
+            n++;
+    }
+    return n;
+}
+/** Quick predicate — was anything ever queued? */
+export function hasPendingOps(pathOverride) {
+    return countPending(pathOverride) > 0;
+}
+function ensureQueueFile(queuePath) {
+    const dir = dirname(queuePath);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    if (!existsSync(queuePath)) {
+        writeFileSync(queuePath, '', { encoding: 'utf-8', mode: 0o600 });
+        try {
+            chmodSync(queuePath, 0o600);
+        }
+        catch {
+            // ignore
+        }
+    }
+}
+//# sourceMappingURL=queue.js.map

package/dist/core/memory-sync/queue.spec.js

@@ -0,0 +1,105 @@
+import { strict as assert } from 'node:assert';
+import { afterEach, beforeEach, describe, it } from 'node:test';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { resolve } from 'node:path';
+import { countPending, enqueueMemoryOp, hasPendingOps, readMemoryQueue, rewriteMemoryQueue, } from './queue.js';
+let tmpRoot = '';
+let queuePath = '';
+beforeEach(() => {
+    tmpRoot = mkdtempSync(resolve(tmpdir(), 'pugi-memory-queue-'));
+    queuePath = resolve(tmpRoot, 'memory-queue.jsonl');
+});
+afterEach(() => {
+    try {
+        rmSync(tmpRoot, { recursive: true, force: true });
+    }
+    catch {
+        // ignore
+    }
+});
+describe('memory-sync queue', () => {
+    it('countPending returns 0 for missing file', () => {
+        assert.equal(countPending(queuePath), 0);
+        assert.equal(hasPendingOps(queuePath), false);
+    });
+    it('enqueueMemoryOp appends a write op and returns 1', () => {
+        const n = enqueueMemoryOp({
+            op: 'write',
+            personaSlug: 'mira',
+            kind: 'preference',
+            content: 'operator prefers pnpm',
+        }, queuePath);
+        assert.equal(n, 1);
+        assert.equal(hasPendingOps(queuePath), true);
+    });
+    it('enqueueMemoryOp appends multiple ops sequentially', () => {
+        enqueueMemoryOp({ op: 'write', personaSlug: 'mira', kind: 'fact', content: 'a' }, queuePath);
+        enqueueMemoryOp({ op: 'forget', id: 'mem-abc' }, queuePath);
+        assert.equal(countPending(queuePath), 2);
+    });
+    it('readMemoryQueue returns parsed entries in order', () => {
+        enqueueMemoryOp({ op: 'write', personaSlug: 'mira', kind: 'workflow', content: 'first' }, queuePath);
+        enqueueMemoryOp({ op: 'forget', id: 'mem-1' }, queuePath);
+        const ops = readMemoryQueue(queuePath);
+        assert.equal(ops.length, 2);
+        assert.equal(ops[0]?.op, 'write');
+        if (ops[0]?.op === 'write')
+            assert.equal(ops[0].content, 'first');
+        assert.equal(ops[1]?.op, 'forget');
+    });
+    it('readMemoryQueue skips malformed lines without crashing', () => {
+        writeFileSync(queuePath, [
+            JSON.stringify({
+                op: 'write',
+                personaSlug: 'mira',
+                kind: 'fact',
+                content: 'a',
+                enqueuedAt: new Date().toISOString(),
+            }),
+            '{not valid json',
+            JSON.stringify({ op: 'future_op', whatever: true }),
+        ].join('\n'));
+        const ops = readMemoryQueue(queuePath);
+        assert.equal(ops.length, 1);
+    });
+    it('rewriteMemoryQueue with empty array clears the file', () => {
+        enqueueMemoryOp({ op: 'write', personaSlug: 'mira', kind: 'fact', content: 'a' }, queuePath);
+        rewriteMemoryQueue([], queuePath);
+        assert.equal(countPending(queuePath), 0);
+        const raw = readFileSync(queuePath, 'utf-8');
+        assert.equal(raw, '');
+    });
+    it('rewriteMemoryQueue with remaining entries persists them', () => {
+        enqueueMemoryOp({ op: 'write', personaSlug: 'mira', kind: 'fact', content: 'a' }, queuePath);
+        enqueueMemoryOp({ op: 'write', personaSlug: 'mira', kind: 'fact', content: 'b' }, queuePath);
+        const all = readMemoryQueue(queuePath);
+        rewriteMemoryQueue([all[1]], queuePath);
+        const after = readMemoryQueue(queuePath);
+        assert.equal(after.length, 1);
+        if (after[0]?.op === 'write')
+            assert.equal(after[0].content, 'b');
+    });
+    it('enqueueMemoryOp rejects an invalid kind via Zod', () => {
+        assert.throws(() => enqueueMemoryOp({
+            op: 'write',
+            personaSlug: 'mira',
+            // @ts-expect-error — intentional bad value
+            kind: 'whatever',
+            content: 'a',
+        }, queuePath));
+    });
+    it('enqueueMemoryOp rejects oversized content (>4000 chars)', () => {
+        assert.throws(() => enqueueMemoryOp({
+            op: 'write',
+            personaSlug: 'mira',
+            kind: 'fact',
+            content: 'x'.repeat(4001),
+        }, queuePath));
+    });
+    it('countPending counts non-empty lines only', () => {
+        writeFileSync(queuePath, 'line1\n\n\nline2\n');
+        assert.equal(countPending(queuePath), 2);
+    });
+});
+//# sourceMappingURL=queue.spec.js.map