@pugi/cli 0.1.0-beta.8 → 0.1.0-beta.88

package/dist/runtime/commands/delegate.js

@@ -6,13 +6,20 @@
  * handlers table) does not need a try/catch wrapper.
  */
 export async function runDelegateCommand(args, ctx) {
-    const slug = args[0];
-    const brief = args.slice(1).join(' ').trim();
+    // Extract the optional `--wait` flag from positional args. Accept it
+    // in any position so `pugi delegate --wait dev "..."` and
+    // `pugi delegate dev "..." --wait` both work; positional ordering of
+    // slug + brief is preserved by filtering the flag out before the
+    // slug/brief split (Claude P2 fix).
+    const wait = args.some((a) => a === '--wait');
+    const positional = args.filter((a) => a !== '--wait');
+    const slug = positional[0];
+    const brief = positional.slice(1).join(' ').trim();
     if (!slug || !brief) {
         ctx.writeOutput({
             ok: false,
-            error: 'Usage: pugi delegate <persona-slug> "<one-sentence brief>"',
-        }, 'Usage: pugi delegate <persona-slug> "<one-sentence brief>"');
+            error: 'Usage: pugi delegate [--wait] <persona-slug> "<one-sentence brief>"',
+        }, 'Usage: pugi delegate [--wait] <persona-slug> "<one-sentence brief>"');
         process.exitCode = 2;
         return;
     }
@@ -47,14 +54,66 @@ export async function runDelegateCommand(args, ctx) {
         brief,
     });
     switch (result.status) {
-        case 'ok':
-            ctx.writeOutput({
-                ok: true,
-                sessionId: opened.sessionId,
-                dispatchId: result.response.dispatchId,
-                personaSlug: result.response.personaSlug,
-            }, `dispatched ${result.response.personaSlug} (dispatchId=${result.response.dispatchId}); stream via GET /sessions/${opened.sessionId}/stream.`);
+        case 'ok': {
+            const ok = result.response;
+            if (!wait) {
+                ctx.writeOutput({
+                    ok: true,
+                    sessionId: opened.sessionId,
+                    dispatchId: ok.dispatchId,
+                    personaSlug: ok.personaSlug,
+                }, `dispatched ${ok.personaSlug} (dispatchId=${ok.dispatchId}); stream via GET /sessions/${opened.sessionId}/stream.`);
+                return;
+            }
+            // --wait: subscribe to SSE until the persona reaches a terminal
+            // event. The waiter contract is provider-shaped so tests can pass
+            // a fake without standing up fetch.
+            const waiter = ctx.waitForTerminal ?? waitForDelegateTerminal;
+            const outcome = await waiter(config, opened.sessionId, ok.personaSlug);
+            switch (outcome.kind) {
+                case 'completed':
+                    ctx.writeOutput({
+                        ok: true,
+                        sessionId: opened.sessionId,
+                        dispatchId: ok.dispatchId,
+                        personaSlug: outcome.personaSlug,
+                        status: 'completed',
+                    }, `completed ${outcome.personaSlug} (dispatchId=${ok.dispatchId}).`);
+                    return;
+                case 'blocked':
+                    ctx.writeOutput({
+                        ok: false,
+                        sessionId: opened.sessionId,
+                        dispatchId: ok.dispatchId,
+                        personaSlug: outcome.personaSlug,
+                        status: 'blocked',
+                        detail: outcome.detail,
+                    }, `blocked ${outcome.personaSlug}: ${outcome.detail}`);
+                    process.exitCode = 5;
+                    return;
+                case 'failed':
+                    ctx.writeOutput({
+                        ok: false,
+                        sessionId: opened.sessionId,
+                        dispatchId: ok.dispatchId,
+                        personaSlug: outcome.personaSlug,
+                        status: 'failed',
+                        error: outcome.error,
+                    }, `failed ${outcome.personaSlug}: ${outcome.error}`);
+                    process.exitCode = 5;
+                    return;
+                case 'stream_error':
+                    ctx.writeOutput({
+                        ok: false,
+                        sessionId: opened.sessionId,
+                        dispatchId: ok.dispatchId,
+                        error: outcome.error,
+                    }, `pugi delegate --wait: ${outcome.error}`);
+                    process.exitCode = 1;
+                    return;
+            }
             return;
+        }
         case 'unknown_persona':
             ctx.writeOutput({ ok: false, error: result.message, code: result.code }, `pugi delegate: ${result.message}`);
             process.exitCode = 3;
@@ -66,9 +125,9 @@ export async function runDelegateCommand(args, ctx) {
         case 'endpoint_missing':
             ctx.writeOutput({
                 ok: false,
-                error: 'runtime does not expose POST /api/pugi/sessions/:id/delegate (upgrade admin-api to α7.5+)',
+                error: 'runtime does not expose POST /api/pugi/sessions/:id/delegate (upgrade admin-api to +)',
                 code: result.code,
-            }, 'pugi delegate: runtime does not expose the delegate endpoint. Upgrade admin-api to α7.5+.');
+            }, 'pugi delegate: runtime does not expose the delegate endpoint. Upgrade admin-api to +.');
             process.exitCode = 1;
             return;
         case 'unauthenticated':
@@ -78,4 +137,176 @@ export async function runDelegateCommand(args, ctx) {
             return;
     }
 }
+/* ------------------------------------------------------------------ */
+/* --wait waiter                                                     */
+/* ------------------------------------------------------------------ */
+/**
+ * Subscribe to the session SSE stream and resolve when the named
+ * persona reaches a terminal event (agent.completed / agent.blocked /
+ * agent.failed). Falls back to a `stream_error` outcome when the
+ * stream closes before any terminal event arrives or when the
+ * underlying fetch fails.
+ *
+ * The waiter is intentionally a single-call helper (not a long-lived
+ * subscriber) - the scripted `pugi delegate --wait` caller wants to
+ * exit on the first terminal event for THIS persona, not maintain a
+ * persistent connection.
+ *
+ * Why we parse the lifecycle in this file (not via the repl-render
+ * subscribe helper): repl-render carries Ink/React deps the
+ * non-interactive delegate path does not want to load. Duplicating the
+ * minimal SSE-line parser here keeps the command lean (this is the same
+ * shape `apps/admin-api/src/pugi/sessions.controller.ts` writes to the
+ * wire).
+ */
+export async function waitForDelegateTerminal(config, sessionId, targetPersonaSlug) {
+    const url = `${config.apiUrl.replace(/\/+$/, '')}/api/pugi/sessions/${encodeURIComponent(sessionId)}/stream`;
+    const controller = new AbortController();
+    // Hard-cap the waiter at 5 minutes so a stalled server cannot keep
+    // a scripted caller hanging forever; the dispatcher's per-turn budget
+    // is well under this.
+    const timeout = setTimeout(() => controller.abort(), 5 * 60 * 1000);
+    try {
+        const response = await fetch(url, {
+            method: 'GET',
+            headers: {
+                Accept: 'text/event-stream',
+                Authorization: `Bearer ${config.apiKey}`,
+            },
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            return { kind: 'stream_error', error: `HTTP ${response.status}` };
+        }
+        if (!response.body) {
+            return { kind: 'stream_error', error: 'no response body' };
+        }
+        // Track the most-recent persona slug seen on agent.spawned so the
+        // terminal event (which carries only taskId) can be matched to the
+        // delegate target without parsing the random nonce suffix.
+        const taskToPersona = new Map();
+        // Buffer `agent.message` frames per taskId so the terminal event can
+        // surface the persona's full reply (Gemini P1 fix, PR). Keyed by
+        // taskId so a session producing multiple parallel persona dispatches
+        // does not cross-contaminate transcripts.
+        const transcriptByTask = new Map();
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder('utf-8');
+        let buffer = '';
+        let currentData = '';
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done) {
+                return { kind: 'stream_error', error: 'stream ended without terminal event' };
+            }
+            buffer += decoder.decode(value, { stream: true });
+            let newlineIndex;
+            while ((newlineIndex = buffer.indexOf('\n')) !== -1) {
+                const rawLine = buffer.slice(0, newlineIndex).replace(/\r$/, '');
+                buffer = buffer.slice(newlineIndex + 1);
+                if (rawLine.length === 0) {
+                    if (currentData.length > 0) {
+                        const parsed = parseDelegateFrame(currentData);
+                        if (parsed) {
+                            if (parsed.type === 'agent.spawned') {
+                                taskToPersona.set(parsed.taskId, parsed.personaSlug);
+                            }
+                            else if (parsed.type === 'agent.message') {
+                                // Buffer the unfiltered reply by taskId. The terminal
+                                // event below joins these into the `transcript` field
+                                // when the matched persona reaches `agent.completed`.
+                                const existing = transcriptByTask.get(parsed.taskId);
+                                if (existing) {
+                                    existing.push(parsed.content);
+                                }
+                                else {
+                                    transcriptByTask.set(parsed.taskId, [parsed.content]);
+                                }
+                            }
+                            else if (parsed.type === 'agent.completed' ||
+                                parsed.type === 'agent.blocked' ||
+                                parsed.type === 'agent.failed') {
+                                const slug = taskToPersona.get(parsed.taskId) ?? targetPersonaSlug;
+                                if (slug === targetPersonaSlug) {
+                                    controller.abort();
+                                    if (parsed.type === 'agent.completed') {
+                                        const frames = transcriptByTask.get(parsed.taskId) ?? [];
+                                        const transcript = frames.join('\n\n');
+                                        return {
+                                            kind: 'completed',
+                                            personaSlug: slug,
+                                            taskId: parsed.taskId,
+                                            transcript,
+                                        };
+                                    }
+                                    if (parsed.type === 'agent.blocked') {
+                                        return {
+                                            kind: 'blocked',
+                                            personaSlug: slug,
+                                            taskId: parsed.taskId,
+                                            detail: parsed.detail,
+                                        };
+                                    }
+                                    return {
+                                        kind: 'failed',
+                                        personaSlug: slug,
+                                        taskId: parsed.taskId,
+                                        error: parsed.error,
+                                    };
+                                }
+                            }
+                        }
+                    }
+                    currentData = '';
+                    continue;
+                }
+                if (rawLine.startsWith(':'))
+                    continue;
+                const colonIndex = rawLine.indexOf(':');
+                const field = colonIndex === -1 ? rawLine : rawLine.slice(0, colonIndex);
+                const value = colonIndex === -1 ? '' : rawLine.slice(colonIndex + 1).replace(/^ /, '');
+                if (field === 'data') {
+                    currentData = currentData.length === 0 ? value : `${currentData}\n${value}`;
+                }
+            }
+        }
+    }
+    catch (err) {
+        if (controller.signal.aborted) {
+            return { kind: 'stream_error', error: 'wait timed out' };
+        }
+        return { kind: 'stream_error', error: err.message };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function parseDelegateFrame(data) {
+    try {
+        const raw = JSON.parse(data);
+        const type = raw.type;
+        const taskId = typeof raw.taskId === 'string' ? raw.taskId : null;
+        if (!taskId)
+            return null;
+        if (type === 'agent.spawned' && typeof raw.personaSlug === 'string') {
+            return { type, taskId, personaSlug: raw.personaSlug };
+        }
+        if (type === 'agent.message' && typeof raw.content === 'string') {
+            return { type, taskId, content: raw.content };
+        }
+        if (type === 'agent.completed') {
+            return { type, taskId };
+        }
+        if (type === 'agent.blocked') {
+            return { type, taskId, detail: typeof raw.detail === 'string' ? raw.detail : '' };
+        }
+        if (type === 'agent.failed') {
+            return { type, taskId, error: typeof raw.error === 'string' ? raw.error : '' };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
 //# sourceMappingURL=delegate.js.map

package/dist/runtime/commands/dispatch.js

@@ -0,0 +1,126 @@
+/**
+ * `pugi dispatch <sub>` — fork-subagent cache-handoff surface (—).
+ *
+ * Sub-commands:
+ *
+ *  - `pugi dispatch list-cache-refs` — show active cache-inherit refs
+ *    persisted under `.pugi/cache-refs/`. Renders an aligned table or
+ *    JSON depending on `--json`.
+ *
+ *  - `pugi dispatch clear-cache-refs [--older-than 1h] [-v]` — GC stale
+ *    refs. Without `--older-than`, defaults to 24h (the same cutoff
+ *    the REPL boot-time auto-sweep uses). The flag accepts duration
+ *    strings the `parseDuration` helper recognises (`1h`, `30m`,
+ *    `7d`, `500ms`, ...).
+ *
+ * The command lives in its own module (not inline in cli.ts) so the
+ * dispatch table stays narrow and tests can drive it without spinning
+ * up the full CLI.
+ */
+import { cleanupStaleCacheRefs, parseDuration, } from '../../core/dispatch/cache-cleanup.js';
+import { listCacheRefs } from '../../core/dispatch/cache-handoff.js';
+const USAGE = [
+    'Usage:',
+    ' pugi dispatch list-cache-refs',
+    '                                      Show every active subagent cache-inherit',
+    '                                      reference persisted under .pugi/cache-refs/.',
+    '',
+    ' pugi dispatch clear-cache-refs [--older-than <duration>] [-v]',
+    '                                      Evict stale refs. Accepts 500ms / 30s / 5m /',
+    '                                      1h / 7d. Default --older-than 24h.',
+].join('\n');
+export async function runDispatchCommand(args, ctx) {
+    const sub = args[0];
+    if (!sub || sub === '--help' || sub === '-h') {
+        ctx.writeOutput({ command: 'dispatch', usage: USAGE.split('\n') }, USAGE);
+        return;
+    }
+    switch (sub) {
+        case 'list-cache-refs':
+            return runListCacheRefs(ctx);
+        case 'clear-cache-refs':
+            return runClearCacheRefs(args.slice(1), ctx);
+        default:
+            ctx.writeOutput({
+                ok: false,
+                error: `unknown subcommand: ${sub}`,
+                usage: USAGE.split('\n'),
+            }, `pugi dispatch: unknown subcommand '${sub}'\n\n${USAGE}`);
+            process.exitCode = 2;
+            return;
+    }
+}
+function runListCacheRefs(ctx) {
+    const refs = listCacheRefs(ctx.workspaceRoot);
+    if (ctx.json) {
+        ctx.writeOutput({ ok: true, count: refs.length, refs }, '');
+        return;
+    }
+    if (refs.length === 0) {
+        ctx.writeOutput({ ok: true, count: 0, refs: [] }, 'No active cache-inherit refs under .pugi/cache-refs/.');
+        return;
+    }
+    // Aligned column table. Widths derived from the data — no hardcoded
+    // sizes so a long childAgentId does not overflow the layout.
+    const header = ['CHILD AGENT', 'CACHE ID', 'PARENT SESSION', 'CREATED'];
+    const rows = refs.map((r) => [
+        r.childAgentId,
+        r.cacheId,
+        r.parentSessionId,
+        r.createdAt,
+    ]);
+    const widths = header.map((h, i) => Math.max(h.length, ...rows.map((row) => (row[i] ?? '').length)));
+    const lines = [];
+    lines.push(header.map((h, i) => h.padEnd(widths[i] ?? 0)).join(' '));
+    lines.push(widths.map((w) => '-'.repeat(w)).join(' '));
+    for (const row of rows) {
+        lines.push(row.map((cell, i) => (cell ?? '').padEnd(widths[i] ?? 0)).join(' '));
+    }
+    ctx.writeOutput({ ok: true, count: refs.length, refs }, lines.join('\n'));
+}
+function runClearCacheRefs(args, ctx) {
+    let olderThanArg;
+    let verbose = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--older-than') {
+            olderThanArg = args[i + 1];
+            i++;
+            continue;
+        }
+        if (arg && arg.startsWith('--older-than=')) {
+            olderThanArg = arg.slice('--older-than='.length);
+            continue;
+        }
+        if (arg === '-v' || arg === '--verbose') {
+            verbose = true;
+            continue;
+        }
+    }
+    // Default 24h matches the REPL boot-time auto-sweep cutoff.
+    const olderThanMs = olderThanArg ? parseDuration(olderThanArg) : 24 * 60 * 60 * 1000;
+    if (olderThanMs === null) {
+        ctx.writeOutput({
+            ok: false,
+            error: `invalid --older-than value: ${olderThanArg ?? '(missing)'}`,
+            usage: USAGE.split('\n'),
+        }, `pugi dispatch clear-cache-refs: invalid --older-than '${olderThanArg ?? '(missing)'}'\n\n${USAGE}`);
+        process.exitCode = 2;
+        return;
+    }
+    const result = cleanupStaleCacheRefs(ctx.workspaceRoot, {
+        olderThanMs,
+        verbose,
+    });
+    const summary = `Removed ${result.removedCount} ref(s) (${result.corruptCount} corrupt), kept ${result.keptCount}.`;
+    ctx.writeOutput({
+        ok: true,
+        olderThanMs,
+        removedCount: result.removedCount,
+        keptCount: result.keptCount,
+        corruptCount: result.corruptCount,
+        removed: result.removed,
+        corrupt: result.corrupt,
+    }, summary);
+}
+//# sourceMappingURL=dispatch.js.map