@pugi/cli 0.1.0-alpha.3 → 0.1.0-alpha.6

package/dist/core/repl/session.js

@@ -0,0 +1,399 @@
+/**
+ * REPL session lifecycle - Sprint α5.7 (ADR-0056 PR-PUGI-CLI-REPL-DEFAULT).
+ *
+ * Owns the state machine that the REPL UI subscribes to:
+ *
+ *   1. Open a server-side Pugi session via POST /api/pugi/sessions.
+ *      The CLI keeps a sessionId; reconnect uses it.
+ *   2. Subscribe to GET /api/pugi/sessions/:id/stream (SSE). Each event
+ *      pushes one of: agent.spawned, agent.step, agent.tokens,
+ *      agent.completed, agent.blocked, agent.failed.
+ *   3. Dispatch a brief via POST /api/pugi/sessions/:id/brief.
+ *   4. Track active dispatches so the cap-warning gate has a number.
+ *   5. Reconnect with Last-Event-ID on transient failure (10 retries,
+ *      exponential backoff capped at 5s) so the operator sees a stable
+ *      stream even on flaky connections.
+ *
+ * The module is environment-agnostic: callers inject `fetch` (Node 22
+ * native or a stub from a test) and `EventSource` (a polyfill or
+ * a fake). The REPL UI passes the production singletons in
+ * `runtime/cli.ts`; tests pass in-memory stand-ins so the contract
+ * surface is exercisable without a network.
+ *
+ * Brand voice: the conversation transcript is line-based, persona-
+ * prefixed (Mira / Marcus / Hiroshi / Vera / Anika / Olivia / Diego /
+ * Sofia per @pugi/personas). Forbidden words gate applies to every
+ * line we synthesize client-side; server-side events are passed through
+ * verbatim - the brand gate on those happens at the controller.
+ */
+import { randomUUID } from 'node:crypto';
+import { listRoles, getPersonaForRole } from '../agents/registry.js';
+import { evaluateCap, describeVerdict } from './cap-warning.js';
+import { parseSlashCommand } from './slash-commands.js';
+const MAX_TRANSCRIPT_ROWS = 500;
+const MAX_RECONNECT_ATTEMPTS = 10;
+const RECONNECT_BASE_MS = 250;
+const RECONNECT_MAX_MS = 5_000;
+export class ReplSession {
+    options;
+    subscribers = new Set();
+    state;
+    streamHandle;
+    lastEventId;
+    reconnectAttempt = 0;
+    reconnectTimer;
+    closed = false;
+    constructor(options) {
+        this.options = options;
+        this.state = {
+            sessionId: undefined,
+            workspaceLabel: options.workspaceLabel,
+            cliVersion: options.cliVersion,
+            connection: 'connecting',
+            agents: [],
+            transcript: [],
+            tokensDownstreamTotal: 0,
+            briefStartedAtEpochMs: undefined,
+        };
+    }
+    /* ------------- subscribe / state -------------- */
+    subscribe(callback) {
+        this.subscribers.add(callback);
+        callback(this.state);
+        return () => {
+            this.subscribers.delete(callback);
+        };
+    }
+    getState() {
+        return this.state;
+    }
+    /* ------------- lifecycle -------------- */
+    /**
+     * Create the server-side session and open the SSE stream. Idempotent;
+     * a second call after `close()` resurrects the connection but
+     * issues a fresh server session id.
+     */
+    async start() {
+        this.closed = false;
+        try {
+            const { sessionId } = await this.options.transport.createSession({
+                apiUrl: this.options.apiUrl,
+                apiKey: this.options.apiKey,
+            });
+            this.patch({ sessionId, connection: 'connecting' });
+            this.openStream();
+        }
+        catch (error) {
+            this.appendSystemLine(`Could not open Pugi session: ${this.errorMessage(error)}`);
+            this.patch({ connection: 'offline' });
+        }
+    }
+    /**
+     * Tear down the SSE stream and stop the reconnect timer. The session
+     * id stays valid server-side; `pugi resume <id>` reopens later.
+     */
+    close() {
+        this.closed = true;
+        if (this.streamHandle) {
+            this.streamHandle.close();
+            this.streamHandle = undefined;
+        }
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = undefined;
+        }
+    }
+    /* ------------- input handling -------------- */
+    /**
+     * Run one line of operator input through the slash command parser
+     * and the cap gate, then forward to the transport. Returns the
+     * parser verdict so the REPL UI can clear the input box, focus
+     * pointer, etc.
+     */
+    async handleInput(input) {
+        const verdict = parseSlashCommand(input);
+        switch (verdict.kind) {
+            case 'noop':
+                return verdict;
+            case 'help':
+            case 'roster':
+                // UI overlays - no transport interaction.
+                return verdict;
+            case 'quit':
+                this.appendSystemLine('Brief it. It ships.');
+                return verdict;
+            case 'error':
+                this.appendSystemLine(verdict.message);
+                return verdict;
+            case 'stop': {
+                await this.dispatchStop(verdict.persona);
+                return verdict;
+            }
+            case 'dispatch': {
+                await this.dispatchBrief(verdict.brief);
+                return verdict;
+            }
+        }
+    }
+    /* ------------- dispatch -------------- */
+    async dispatchBrief(brief) {
+        const sessionId = this.state.sessionId;
+        if (!sessionId) {
+            this.appendSystemLine('No server session yet - try again in a moment.');
+            return;
+        }
+        const capVerdict = evaluateCap({
+            active: this.activeAgentCount(),
+            env: this.options.env ?? process.env,
+        });
+        const capLine = describeVerdict(capVerdict);
+        if (capVerdict.kind === 'block') {
+            this.appendSystemLine(capLine);
+            return;
+        }
+        if (capLine.length > 0) {
+            this.appendSystemLine(capLine);
+        }
+        this.appendOperatorLine(brief);
+        this.patch({ briefStartedAtEpochMs: this.now() });
+        try {
+            await this.options.transport.postBrief({
+                apiUrl: this.options.apiUrl,
+                apiKey: this.options.apiKey,
+                sessionId,
+                brief,
+            });
+        }
+        catch (error) {
+            this.appendSystemLine(`Brief dispatch refused: ${this.errorMessage(error)}`);
+        }
+    }
+    async dispatchStop(persona) {
+        const sessionId = this.state.sessionId;
+        if (!sessionId) {
+            this.appendSystemLine('No server session yet - nothing to stop.');
+            return;
+        }
+        try {
+            const { stopped } = await this.options.transport.postStop({
+                apiUrl: this.options.apiUrl,
+                apiKey: this.options.apiKey,
+                sessionId,
+                persona,
+            });
+            this.appendSystemLine(stopped
+                ? `Stopped persona '${persona}'.`
+                : `No active dispatch matched persona '${persona}'.`);
+        }
+        catch (error) {
+            this.appendSystemLine(`Stop refused: ${this.errorMessage(error)}`);
+        }
+    }
+    /* ------------- SSE consumer + reconnect -------------- */
+    openStream() {
+        const sessionId = this.state.sessionId;
+        if (!sessionId)
+            return;
+        if (this.streamHandle) {
+            this.streamHandle.close();
+            this.streamHandle = undefined;
+        }
+        this.streamHandle = this.options.transport.subscribe({
+            apiUrl: this.options.apiUrl,
+            apiKey: this.options.apiKey,
+            sessionId,
+            lastEventId: this.lastEventId,
+            onOpen: () => {
+                this.reconnectAttempt = 0;
+                this.patch({ connection: 'on_watch' });
+            },
+            onEvent: (event, eventId) => {
+                this.lastEventId = eventId;
+                this.handleServerEvent(event);
+            },
+            onError: (error) => {
+                if (this.closed)
+                    return;
+                this.patch({ connection: 'reconnecting' });
+                this.appendSystemLine(`Stream interrupted (${this.errorMessage(error)}). Reconnecting.`);
+                this.scheduleReconnect();
+            },
+        });
+    }
+    scheduleReconnect() {
+        if (this.closed)
+            return;
+        if (this.reconnectAttempt >= MAX_RECONNECT_ATTEMPTS) {
+            this.appendSystemLine('Gave up reconnecting - type /quit and `pugi resume` to retry.');
+            this.patch({ connection: 'offline' });
+            return;
+        }
+        const delay = Math.min(RECONNECT_BASE_MS * 2 ** this.reconnectAttempt, RECONNECT_MAX_MS);
+        this.reconnectAttempt += 1;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = undefined;
+            this.openStream();
+        }, delay);
+    }
+    /* ------------- event reducer -------------- */
+    handleServerEvent(event) {
+        switch (event.type) {
+            case 'agent.spawned': {
+                const persona = safePersonaName(event.role);
+                const node = {
+                    taskId: event.taskId,
+                    role: event.role,
+                    personaSlug: event.personaSlug,
+                    personaName: persona,
+                    status: 'queued',
+                    detail: 'queued for dispatch',
+                    startedAtEpochMs: this.now(),
+                    tokensIn: 0,
+                    tokensOut: 0,
+                };
+                this.patch({ agents: [node, ...this.state.agents] });
+                // The conversation pane already prefixes persona rows with the
+                // persona name in the persona's hue colour. Skip embedding the
+                // name in the body text to avoid the `Marcus Marcus dispatched`
+                // double-print. `void persona` keeps the resolved name in scope
+                // for the agent tree node above without leaking it into the
+                // transcript body.
+                void persona;
+                this.appendPersonaLine(event.personaSlug, `dispatched (${event.role}).`);
+                return;
+            }
+            case 'agent.step': {
+                this.patch({
+                    agents: this.state.agents.map((a) => a.taskId === event.taskId
+                        ? { ...a, status: 'thinking', detail: event.detail }
+                        : a),
+                });
+                return;
+            }
+            case 'agent.tokens': {
+                const delta = event.tokensIn + event.tokensOut;
+                this.patch({
+                    tokensDownstreamTotal: this.state.tokensDownstreamTotal + delta,
+                    agents: this.state.agents.map((a) => a.taskId === event.taskId
+                        ? {
+                            ...a,
+                            tokensIn: a.tokensIn + event.tokensIn,
+                            tokensOut: a.tokensOut + event.tokensOut,
+                        }
+                        : a),
+                });
+                return;
+            }
+            case 'agent.completed': {
+                const target = this.state.agents.find((a) => a.taskId === event.taskId);
+                this.patch({
+                    agents: this.state.agents.map((a) => a.taskId === event.taskId
+                        ? { ...a, status: 'shipped', detail: 'shipped' }
+                        : a),
+                });
+                if (target) {
+                    this.appendPersonaLine(target.personaSlug, 'shipped.');
+                }
+                return;
+            }
+            case 'agent.blocked': {
+                const target = this.state.agents.find((a) => a.taskId === event.taskId);
+                this.patch({
+                    agents: this.state.agents.map((a) => a.taskId === event.taskId
+                        ? { ...a, status: 'blocked', detail: event.detail }
+                        : a),
+                });
+                if (target) {
+                    this.appendPersonaLine(target.personaSlug, `blocked: ${event.detail}`);
+                }
+                return;
+            }
+            case 'agent.failed': {
+                const target = this.state.agents.find((a) => a.taskId === event.taskId);
+                this.patch({
+                    agents: this.state.agents.map((a) => a.taskId === event.taskId
+                        ? { ...a, status: 'failed', detail: event.error }
+                        : a),
+                });
+                if (target) {
+                    this.appendPersonaLine(target.personaSlug, `failed: ${event.error}`);
+                }
+                return;
+            }
+        }
+    }
+    /* ------------- transcript helpers -------------- */
+    appendOperatorLine(text) {
+        this.appendRow({ source: 'operator', text });
+    }
+    appendSystemLine(text) {
+        this.appendRow({ source: 'system', text });
+    }
+    appendPersonaLine(personaSlug, text) {
+        this.appendRow({ source: 'persona', text, personaSlug });
+    }
+    appendRow(input) {
+        if (input.text.length === 0)
+            return;
+        const row = {
+            id: randomUUID(),
+            source: input.source,
+            text: input.text,
+            personaSlug: input.personaSlug,
+            timestampEpochMs: this.now(),
+        };
+        const next = this.state.transcript.concat(row).slice(-MAX_TRANSCRIPT_ROWS);
+        this.patch({ transcript: next });
+    }
+    /* ------------- agent count + clock -------------- */
+    activeAgentCount() {
+        return this.state.agents.filter((a) => a.status === 'queued' || a.status === 'thinking').length;
+    }
+    /** Exported so the cap-warning gate can be exercised in isolation. */
+    activeRoles() {
+        return this.state.agents
+            .filter((a) => a.status === 'queued' || a.status === 'thinking')
+            .map((a) => a.role);
+    }
+    now() {
+        return (this.options.now ?? Date.now)();
+    }
+    patch(partial) {
+        this.state = { ...this.state, ...partial };
+        for (const subscriber of this.subscribers) {
+            subscriber(this.state);
+        }
+    }
+    errorMessage(error) {
+        if (error instanceof Error)
+            return error.message;
+        return String(error);
+    }
+}
+/* ------------------------------------------------------------------ */
+/* Helpers                                                            */
+/* ------------------------------------------------------------------ */
+/**
+ * Resolve role → display name without throwing on unknown roles. The
+ * dispatcher always passes a known role, but the SSE wire format is
+ * forward-compatible - if a future server pushes a role the client
+ * does not recognise, the REPL still renders something usable rather
+ * than crashing mid-frame.
+ */
+function safePersonaName(role) {
+    try {
+        return getPersonaForRole(role).name;
+    }
+    catch {
+        return role;
+    }
+}
+/**
+ * Convenience: list the legal role slugs the operator can target with
+ * `/stop`. Surfaced in the slash command help overlay and in the
+ * cap-warning helper when the operator types an unrecognised slug.
+ */
+export function knownRoles() {
+    return listRoles();
+}
+//# sourceMappingURL=session.js.map

package/dist/core/repl/slash-commands.js

@@ -0,0 +1,116 @@
+/**
+ * REPL slash command registry - Sprint α5.7 (ADR-0056 PR-PUGI-CLI-REPL-DEFAULT).
+ *
+ * The REPL input box surfaces a small palette of slash commands that the
+ * operator can run from inside a persistent session: dispatch a brief,
+ * inspect the agent roster, stop a running persona, open the help
+ * overlay, or quit. The registry is intentionally narrow at M1 -
+ * complementary surfaces (`/sync`, `/handoff`, `/budget`) ship as proper
+ * subcommands in α5.8+ and stay reachable from a non-REPL `pugi
+ * <command>` invocation.
+ *
+ * The registry is pure: each entry returns a `SlashCommandResult`
+ * describing what the REPL session should do next. The session module
+ * owns the side effects (network calls, dispatcher invocation, exit).
+ * Keeping the surface pure lets the unit test exercise every shape
+ * without standing up an Ink runtime or an Anvil endpoint.
+ *
+ * Brand voice (brandbook §08): power words `brief / dispatch / stop /
+ * agents / quit`. Tagline `Brief it. It ships.` reserved for `/quit`
+ * confirmation and `/help` footer - never inline.
+ */
+import { listRoles } from '../agents/registry.js';
+export const SLASH_COMMAND_HELP = Object.freeze([
+    { name: 'brief', args: '<text>', gloss: 'Dispatch a brief to the workforce' },
+    { name: 'agents', args: '', gloss: 'List the on-watch agent roster' },
+    { name: 'stop', args: '<persona>', gloss: 'Stop one agent by persona slug' },
+    { name: 'help', args: '', gloss: 'Show this help overlay' },
+    { name: 'quit', args: '', gloss: 'Exit the REPL (session resumes via pugi resume)' },
+]);
+/**
+ * Parse one line of input from the REPL. The contract:
+ *
+ *   - Empty / whitespace-only input returns `noop` with the original
+ *     text so the REPL can ignore it without printing anything.
+ *   - Input that does not start with `/` is treated as an implicit
+ *     `/brief <text>` - the most-common operator action.
+ *   - `/<name> [args]` resolves the name against the registry; unknown
+ *     names return `error` so the REPL can render a one-line tip
+ *     instead of silently dropping the input.
+ *
+ * The function never throws. Bad input maps to a structured result the
+ * REPL can render - the alternative (throwing from a keystroke handler)
+ * would unmount Ink mid-frame.
+ */
+export function parseSlashCommand(input) {
+    const trimmed = input.trim();
+    if (trimmed.length === 0) {
+        return { kind: 'noop', text: '' };
+    }
+    if (!trimmed.startsWith('/')) {
+        return { kind: 'dispatch', brief: trimmed };
+    }
+    // `/` with no name → render help overlay so the operator discovers
+    // the command palette without typing `/help`.
+    if (trimmed === '/') {
+        return { kind: 'help' };
+    }
+    const space = trimmed.indexOf(' ');
+    const head = space === -1 ? trimmed.slice(1) : trimmed.slice(1, space);
+    const tail = space === -1 ? '' : trimmed.slice(space + 1).trim();
+    const name = head.toLowerCase();
+    switch (name) {
+        case 'brief': {
+            if (tail.length === 0) {
+                return { kind: 'error', message: 'Usage: /brief <text>' };
+            }
+            return { kind: 'dispatch', brief: tail };
+        }
+        case 'agents':
+        case 'agent':
+        case 'roster': {
+            return { kind: 'roster' };
+        }
+        case 'stop':
+        case 'kill': {
+            if (tail.length === 0) {
+                return {
+                    kind: 'error',
+                    message: `Usage: /stop <persona> (try one of: ${listRoles().join(', ')})`,
+                };
+            }
+            return { kind: 'stop', persona: tail.toLowerCase() };
+        }
+        case 'help':
+        case '?': {
+            return { kind: 'help' };
+        }
+        case 'quit':
+        case 'exit':
+        case 'q': {
+            return { kind: 'quit' };
+        }
+        default: {
+            return {
+                kind: 'error',
+                message: `Unknown command /${head}. Try /help for the palette.`,
+            };
+        }
+    }
+}
+/**
+ * Filter SLASH_COMMAND_HELP rows whose name starts with the typed
+ * prefix. The REPL input box uses this to render an inline palette
+ * after the operator types `/`.
+ *
+ * Matching is case-insensitive; the prefix is normalized to lowercase
+ * before comparison so the operator can type `/HELP` and still see
+ * suggestions.
+ */
+export function matchSlashPrefix(prefix) {
+    const normalized = prefix.toLowerCase().replace(/^\//, '');
+    if (normalized.length === 0)
+        return SLASH_COMMAND_HELP;
+    return SLASH_COMMAND_HELP.filter((row) => row.name.startsWith(normalized));
+}
+//# sourceMappingURL=slash-commands.js.map

package/dist/core/session.js

@@ -81,6 +81,174 @@ export function recordFileMutation(session, input) {
         ...input,
     }, session.eventsPath);
 }
+export function recordHookInvoked(session, input) {
+    if (!session.enabled)
+        return;
+    appendEvent({
+        id: randomUUID(),
+        sessionId: session.id,
+        timestamp: now(),
+        type: 'hook.invoked',
+        event: input.event,
+        matchSummary: input.matchSummary,
+        runSummary: input.runSummary,
+    }, session.eventsPath);
+}
+export function recordHookResult(session, input) {
+    if (!session.enabled)
+        return;
+    appendEvent({
+        id: randomUUID(),
+        sessionId: session.id,
+        timestamp: now(),
+        type: 'hook.result',
+        event: input.event,
+        ok: input.ok,
+        exitCode: input.exitCode,
+        elapsedMs: input.elapsedMs,
+        stdoutLen: input.stdoutLen,
+        stderrLen: input.stderrLen,
+    }, session.eventsPath);
+}
+export function recordHookSkipped(session, input) {
+    if (!session.enabled)
+        return;
+    appendEvent({
+        id: randomUUID(),
+        sessionId: session.id,
+        timestamp: now(),
+        type: 'hook.skipped',
+        event: input.event,
+        reason: input.reason,
+    }, session.eventsPath);
+}
+/**
+ * Record a `subagent.spawned` event in the session audit log. Inputs
+ * arrive untyped (the dispatcher emits JSON to stay decoupled from this
+ * module); the recorder validates the role and isolation at the typed
+ * audit-event union boundary, so a malformed role would fail at the
+ * `AuditEvent` cast site rather than silently writing garbage. The cast
+ * itself is the load-bearing check: `assertSubagentRole` and
+ * `assertSubagentIsolation` narrow at runtime.
+ */
+export function recordSubagentSpawned(session, input) {
+    if (!session.enabled)
+        return;
+    appendEvent({
+        id: randomUUID(),
+        sessionId: session.id,
+        timestamp: now(),
+        type: 'subagent.spawned',
+        taskId: input.taskId,
+        role: assertSubagentRole(input.role),
+        personaSlug: input.personaSlug,
+        parentSessionId: input.parentSessionId,
+        isolation: assertSubagentIsolation(input.isolation),
+    }, session.eventsPath);
+}
+export function recordSubagentToolCall(session, input) {
+    if (!session.enabled)
+        return;
+    appendEvent({
+        id: randomUUID(),
+        sessionId: session.id,
+        timestamp: now(),
+        type: 'subagent.tool_call',
+        taskId: input.taskId,
+        role: assertSubagentRole(input.role),
+        personaSlug: input.personaSlug,
+        toolName: input.toolName,
+        toolCallId: input.toolCallId,
+    }, session.eventsPath);
+}
+export function recordSubagentCompleted(session, input) {
+    if (!session.enabled)
+        return;
+    appendEvent({
+        id: randomUUID(),
+        sessionId: session.id,
+        timestamp: now(),
+        type: 'subagent.completed',
+        taskId: input.taskId,
+        role: assertSubagentRole(input.role),
+        personaSlug: input.personaSlug,
+        toolCallCount: input.toolCallCount,
+        tokensIn: input.tokensIn,
+        tokensOut: input.tokensOut,
+        durationMs: input.durationMs,
+    }, session.eventsPath);
+}
+export function recordSubagentBlocked(session, input) {
+    if (!session.enabled)
+        return;
+    appendEvent({
+        id: randomUUID(),
+        sessionId: session.id,
+        timestamp: now(),
+        type: 'subagent.blocked',
+        taskId: input.taskId,
+        role: assertSubagentRole(input.role),
+        personaSlug: input.personaSlug,
+        reason: assertSubagentBlockedReason(input.reason),
+        detail: input.detail,
+    }, session.eventsPath);
+}
+export function recordSubagentFailed(session, input) {
+    if (!session.enabled)
+        return;
+    appendEvent({
+        id: randomUUID(),
+        sessionId: session.id,
+        timestamp: now(),
+        type: 'subagent.failed',
+        taskId: input.taskId,
+        role: assertSubagentRole(input.role),
+        personaSlug: input.personaSlug,
+        error: input.error,
+    }, session.eventsPath);
+}
+const SUBAGENT_ROLES = new Set([
+    'orchestrator',
+    'architect',
+    'coder',
+    'verifier',
+    'reviewer',
+    'researcher',
+    'release',
+    'devops',
+    'design_qa',
+]);
+const SUBAGENT_ISOLATIONS = new Set([
+    'prompt_only',
+    'shared_fs_readonly',
+    'shared_fs_serialized',
+    'worktree',
+    'remote_vm',
+]);
+const SUBAGENT_BLOCKED_REASONS = new Set([
+    'budget_exhausted',
+    'plan_mode_refused',
+    'permission_denied',
+    'tool_unavailable',
+]);
+function assertSubagentRole(value) {
+    if (!SUBAGENT_ROLES.has(value)) {
+        throw new Error(`recordSubagent*: unknown role '${value}'`);
+    }
+    return value;
+}
+function assertSubagentIsolation(value) {
+    if (!SUBAGENT_ISOLATIONS.has(value)) {
+        throw new Error(`recordSubagent*: unknown isolation '${value}'`);
+    }
+    return value;
+}
+function assertSubagentBlockedReason(value) {
+    if (!SUBAGENT_BLOCKED_REASONS.has(value)) {
+        throw new Error(`recordSubagent*: unknown blocked reason '${value}'`);
+    }
+    return value;
+}
 function appendEvent(event, eventsPath) {
     appendFileSync(eventsPath, `${JSON.stringify(event)}\n`, { encoding: 'utf8', mode: 0o600 });
 }