@pugi/cli 0.1.0-alpha.10

package/dist/core/repl/session.js

@@ -0,0 +1,618 @@
+/**
+ * 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';
+import { webFetchTool } from '../../tools/web-fetch.js';
+import { loadSettings } from '../settings.js';
+import { getJobRegistry } from '../jobs/registry.js';
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { resolve as resolvePath } from 'node:path';
+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;
+    /**
+     * Last non-trivial step.detail recorded per taskId. The server streams
+     * the persona reply incrementally via `agent.step` events whose
+     * `detail` field carries the cumulative model output. `agent.completed`
+     * arrives last and previously overwrote the visible detail to the
+     * literal string `'shipped'` while the transcript line said only
+     * `shipped.` — the actual reply text was lost. By caching the last
+     * non-trivial detail here, we can flush it into the transcript when
+     * the agent completes so the operator sees what the persona actually
+     * said. CEO wave-2 fix 2026-05-25.
+     */
+    lastStepDetail = new Map();
+    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,
+                workspace: this.options.workspace,
+            });
+            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':
+                // UI Designer audit 2026-05-25: "Brief it. It ships." is reserved
+                // for identity intro + landing per wave-4 prompt rule. Drop the
+                // tagline drift here; tell the operator what happened and how to
+                // resume.
+                this.appendSystemLine('On watch ended. pugi resume to come back.');
+                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;
+            }
+            case 'web': {
+                await this.dispatchWebFetch(verdict.url);
+                return verdict;
+            }
+            case 'clear': {
+                this.clearTranscript();
+                return verdict;
+            }
+            case 'version': {
+                this.appendSystemLine(`pugi ${this.options.cliVersion}`);
+                return verdict;
+            }
+            case 'jobs': {
+                await this.dispatchJobs();
+                return verdict;
+            }
+            case 'diff': {
+                this.dispatchDiff();
+                return verdict;
+            }
+            case 'cost': {
+                this.dispatchCost();
+                return verdict;
+            }
+            case 'status': {
+                this.dispatchStatus();
+                return verdict;
+            }
+            case 'stub': {
+                this.appendSystemLine(verdict.message);
+                return verdict;
+            }
+        }
+    }
+    /**
+     * Reset the conversation transcript. The agent registry stays intact
+     * so the operator can `/clear` to declutter the chat pane without
+     * losing visibility into running dispatches.
+     */
+    clearTranscript() {
+        this.patch({ transcript: [] });
+    }
+    /* ------------- Tier 1 / Tier 2 wired handlers -------------- */
+    async dispatchJobs() {
+        try {
+            const registry = getJobRegistry();
+            const entries = await registry.list();
+            if (entries.length === 0) {
+                this.appendSystemLine('No background jobs tracked.');
+                return;
+            }
+            this.appendSystemLine(`Background jobs (${entries.length}):`);
+            for (const entry of entries) {
+                const id = entry.id.replace(/^pj-/, '').slice(0, 8);
+                const status = entry.status;
+                const cmd = entry.command.length > 48 ? `${entry.command.slice(0, 47)}…` : entry.command;
+                this.appendSystemLine(`  ${id}  ${status.padEnd(10)}  ${cmd}`);
+            }
+        }
+        catch (error) {
+            this.appendSystemLine(`/jobs failed: ${this.errorMessage(error)}`);
+        }
+    }
+    dispatchDiff() {
+        try {
+            const artifactsRoot = resolvePath(process.cwd(), '.pugi', 'artifacts');
+            if (!existsSync(artifactsRoot)) {
+                this.appendSystemLine('No pending diffs (.pugi/artifacts/ not found).');
+                return;
+            }
+            const subdirs = readdirSync(artifactsRoot, { withFileTypes: true })
+                .filter((d) => d.isDirectory())
+                .map((d) => d.name);
+            const diffs = [];
+            for (const name of subdirs) {
+                const candidate = resolvePath(artifactsRoot, name, 'diff.patch');
+                if (existsSync(candidate)) {
+                    const size = statSync(candidate).size;
+                    diffs.push(`  ${name}/diff.patch (${size} bytes)`);
+                }
+            }
+            if (diffs.length === 0) {
+                this.appendSystemLine('No pending diffs.');
+                return;
+            }
+            this.appendSystemLine(`Pending diffs (${diffs.length}):`);
+            for (const line of diffs)
+                this.appendSystemLine(line);
+        }
+        catch (error) {
+            this.appendSystemLine(`/diff failed: ${this.errorMessage(error)}`);
+        }
+    }
+    dispatchCost() {
+        const { tokensDownstreamTotal, agents } = this.state;
+        const active = agents.filter((a) => a.status === 'queued' || a.status === 'thinking').length;
+        const lineTokens = `Tokens this session: ${tokensDownstreamTotal.toLocaleString()} (in+out).`;
+        const lineAgents = `Active dispatches: ${active} of cap.`;
+        this.appendSystemLine(lineTokens);
+        this.appendSystemLine(lineAgents);
+        this.appendSystemLine('Full per-persona budget breakdown lands in α6.5.');
+    }
+    dispatchStatus() {
+        const sessionId = this.state.sessionId ?? '(unbound)';
+        const reach = this.state.connection;
+        this.appendSystemLine(`Backend: ${this.options.apiUrl} (${reach}).`);
+        this.appendSystemLine(`Session: ${sessionId}.`);
+        this.appendSystemLine(`Workspace: ${this.state.workspaceLabel}.`);
+        this.appendSystemLine(`CLI: pugi ${this.state.cliVersion}.`);
+    }
+    /**
+     * Fetch one URL via the web_fetch tool and inject the resulting
+     * Markdown into the transcript as an operator-attributed brief. The
+     * `<untrusted-content>` sentinel travels with the body so the Mira
+     * system prompt can refuse to follow instructions inside it.
+     *
+     * Gating: the dispatcher reads PugiSettings from disk on every
+     * call so the operator can flip `web.fetch.enabled` mid-session
+     * without restarting the REPL. The CLI's bare `--allow-fetch` flag
+     * is honored by the runtime entry point and propagates through
+     * env to keep the session module transport-free.
+     */
+    async dispatchWebFetch(url) {
+        // Malformed `.pugi/settings.json` must not crash the REPL —
+        // surface the error to the operator and treat fetch as disabled
+        // (fail-safe). The session keeps running.
+        let settings;
+        try {
+            settings = loadSettings(process.cwd());
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            this.appendSystemLine(`web_fetch refused: failed to load .pugi/settings.json (${msg}).`);
+            return;
+        }
+        const allowFetch = (this.options.env ?? process.env).PUGI_ALLOW_FETCH === '1';
+        const result = await webFetchTool({ url }, { settings, allowFetch });
+        if (!result.ok) {
+            this.appendSystemLine(`web_fetch refused: ${result.error}`);
+            return;
+        }
+        this.appendOperatorLine(`/web ${result.url}`);
+        this.appendSystemLine(`Fetched ${result.title} (${result.fetched_at}).`);
+        // Surface the Markdown body so the operator sees what landed in
+        // the brief; downstream the body is the actual dispatch payload.
+        this.appendSystemLine(result.content_md);
+        await this.dispatchBrief(`Brief from fetched page:\n\n${result.content_md}`);
+    }
+    /* ------------- 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);
+                // Wave 4 fix 2026-05-25: the roster collapses to one row per
+                // persona slug. The α5.7 reducer pushed a fresh row on every
+                // spawn, so after three turns the bottom panel stacked
+                // "Mira orchestrator shipped" three times. The new contract:
+                //   - If a row already exists for this personaSlug, REUSE it.
+                //     Replace its taskId, reset status to 'queued', clear the
+                //     detail line, restart the duration clock, zero the token
+                //     counters. The persona name + slug + role stay stable
+                //     (they are the row identity).
+                //   - If no row exists yet, push a new one.
+                // Per-task lifecycle (step/tokens/completed/blocked/failed) is
+                // keyed off `taskId` everywhere, so the reused row still folds
+                // the latest task's events correctly.
+                const existing = this.state.agents.find((a) => a.personaSlug === event.personaSlug);
+                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,
+                };
+                if (existing) {
+                    this.patch({
+                        agents: this.state.agents.map((a) => a.personaSlug === event.personaSlug ? node : a),
+                    });
+                }
+                else {
+                    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': {
+                // Cache the running detail per task so we can surface the
+                // model's actual reply when agent.completed lands (otherwise
+                // the reply disappears under the literal 'shipped' patch).
+                if (event.detail && event.detail.trim().length > 0) {
+                    this.lastStepDetail.set(event.taskId, event.detail);
+                }
+                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);
+                const finalDetail = this.lastStepDetail.get(event.taskId);
+                this.lastStepDetail.delete(event.taskId);
+                this.patch({
+                    agents: this.state.agents.map((a) => a.taskId === event.taskId
+                        ? { ...a, status: 'shipped', detail: 'shipped' }
+                        : a),
+                });
+                if (target) {
+                    // If the persona actually produced a reply via incremental
+                    // agent.step events, render that reply in the transcript so
+                    // the operator sees the full answer. The threshold (>4 chars
+                    // + not the queued placeholder) filters out the no-op
+                    // "shipped"/"queued for dispatch" placeholders the dispatcher
+                    // emits before the model speaks. Multi-line replies are
+                    // emitted line by line so the conversation pane wraps each
+                    // sentence on its own row.
+                    if (finalDetail
+                        && finalDetail !== 'queued for dispatch'
+                        && finalDetail.trim().length > 4) {
+                        for (const line of finalDetail.split('\n')) {
+                            const trimmed = line.trim();
+                            if (trimmed.length > 0) {
+                                this.appendPersonaLine(target.personaSlug, trimmed);
+                            }
+                        }
+                    }
+                    else {
+                        this.appendPersonaLine(target.personaSlug, 'shipped.');
+                    }
+                }
+                return;
+            }
+            case 'agent.blocked': {
+                const target = this.state.agents.find((a) => a.taskId === event.taskId);
+                this.lastStepDetail.delete(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.lastStepDetail.delete(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