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

package/dist/core/repl/history.js

@@ -0,0 +1,172 @@
+/**
+ * Persistent REPL history (per-workspace) - Sprint α6.14.
+ *
+ * Stores submitted briefs in `~/.pugi/history/<workspace-slug>.jsonl`,
+ * one JSON object per line. The format is line-delimited JSON so the
+ * file can be appended to atomically (single `write(2)` per entry on
+ * Linux/macOS for entries < PIPE_BUF) and tailed by humans without a
+ * parser. Per-workspace separation lets the operator switch repos and
+ * keep brief history contextual: `brief: fix the cabinet sidebar 401`
+ * does not bleed into the agents repo.
+ *
+ * Contract:
+ *
+ *   - `append({ home, workspaceSlug, brief })` writes one line. Dedups
+ *     a brief that is identical to the immediately preceding entry
+ *     (most common operator pattern: Up + Enter to re-run).
+ *   - `read({ home, workspaceSlug })` returns entries oldest-first so
+ *     the caller can navigate with `index = entries.length - 1` for
+ *     "most recent" semantics.
+ *   - The file is capped at MAX_ENTRIES; on overflow we keep the most
+ *     recent slice and rewrite. Cheap because briefs are short text
+ *     and the cap is 1000.
+ *   - `slugForCwd(cwd)` normalises a working directory into a safe
+ *     filename component (alphanumerics + `-`, lowercase, slashes
+ *     collapsed). Empty cwd resolves to `default`.
+ *   - Failures (missing $HOME, disk full, EACCES) NEVER throw. History
+ *     is operator comfort, not a contract surface; degrading to "no
+ *     history this session" is correct.
+ *
+ * Brand voice: file is operator-facing if they `cat` it, so the JSON
+ * keys stay readable English (`brief`, `ts`). No forbidden words.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync, renameSync, unlinkSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/** Cap on stored entries per workspace. Drops oldest on overflow. */
+export const MAX_HISTORY_ENTRIES = 1000;
+/**
+ * Compute the on-disk path for a given workspace slug. Tests rely on
+ * this to assert per-workspace isolation without re-implementing the
+ * directory math.
+ */
+export function historyPath(io) {
+    const home = io.home ?? homedir();
+    const safe = sanitiseSlug(io.workspaceSlug);
+    return join(home, '.pugi', 'history', `${safe}.jsonl`);
+}
+/**
+ * Append a brief to history. Dedups consecutive identical entries.
+ * Returns the entry that was written, or `null` when the entry was
+ * deduped or the brief was empty.
+ */
+export function append(input) {
+    const brief = input.brief.trim();
+    if (brief.length === 0)
+        return null;
+    const path = historyPath(input);
+    try {
+        ensureDir(dirname(path));
+    }
+    catch {
+        return null;
+    }
+    const existing = read({ home: input.home, workspaceSlug: input.workspaceSlug });
+    const last = existing[existing.length - 1];
+    if (last && last.brief === brief) {
+        return null;
+    }
+    const ts = (input.now ?? (() => new Date()))().toISOString();
+    const entry = { ts, brief };
+    // Overflow path: combined length > cap means we trim before rewrite.
+    // Write to a sibling tmp file and renameSync over the target so
+    // concurrent CLI instances in the same workspace cannot observe a
+    // half-written file or race a parallel appendFileSync into oblivion.
+    // POSIX renameSync is atomic within a directory; on Windows fs.rename
+    // is atomic too as long as both paths are on the same volume (the tmp
+    // sibling guarantees that). P2 fix from PR #335 triple-review.
+    if (existing.length + 1 > MAX_HISTORY_ENTRIES) {
+        const trimmed = [...existing.slice(existing.length + 1 - MAX_HISTORY_ENTRIES), entry];
+        const tmpPath = `${path}.tmp`;
+        try {
+            writeFileSync(tmpPath, trimmed.map(serialize).join('\n') + '\n', { mode: 0o600 });
+            renameSync(tmpPath, path);
+        }
+        catch {
+            // Best-effort cleanup of the orphan tmp file; never throw out.
+            try {
+                unlinkSync(tmpPath);
+            }
+            catch {
+                /* ignore — tmp file may not exist yet */
+            }
+            return null;
+        }
+        return entry;
+    }
+    try {
+        appendFileSync(path, serialize(entry) + '\n', { mode: 0o600 });
+    }
+    catch {
+        return null;
+    }
+    return entry;
+}
+/**
+ * Read history for a workspace, oldest-first. Returns `[]` when the
+ * file is missing, unreadable, or empty. Malformed lines are dropped
+ * silently - one bad line should not nuke the whole history.
+ */
+export function read(io) {
+    const path = historyPath(io);
+    if (!existsSync(path))
+        return [];
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (typeof parsed === 'object' &&
+                parsed !== null &&
+                typeof parsed.brief === 'string' &&
+                typeof parsed.ts === 'string') {
+                out.push({
+                    ts: parsed.ts,
+                    brief: parsed.brief,
+                });
+            }
+        }
+        catch {
+            // Drop malformed line.
+        }
+    }
+    return out;
+}
+/**
+ * Normalise a cwd or workspace name into a safe filename component.
+ * Lowercase, alphanumerics + `-` only. Slashes become `-`. Empty input
+ * resolves to `default` so we never produce an empty filename.
+ */
+export function slugForCwd(cwd) {
+    if (!cwd || cwd.trim().length === 0)
+        return 'default';
+    // Strip leading slash so `/Users/foo` becomes `users-foo`.
+    const normalised = cwd
+        .replace(/^[/\\]+/, '')
+        .replace(/[/\\]+/g, '-')
+        .toLowerCase();
+    return sanitiseSlug(normalised);
+}
+function sanitiseSlug(raw) {
+    const cleaned = raw.replace(/[^a-z0-9-]/gi, '-').toLowerCase().replace(/-+/g, '-');
+    const trimmed = cleaned.replace(/^-+|-+$/g, '');
+    return trimmed.length === 0 ? 'default' : trimmed;
+}
+function serialize(entry) {
+    return JSON.stringify(entry);
+}
+function ensureDir(dir) {
+    if (existsSync(dir))
+        return;
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+//# sourceMappingURL=history.js.map

package/dist/core/repl/kill-ring.js

@@ -0,0 +1,138 @@
+/**
+ * Kill ring for the REPL input - Sprint α6.14.
+ *
+ * Tiny LIFO buffer that backs the readline-style kill commands:
+ *
+ *   Ctrl+U  - kill from cursor to line start
+ *   Ctrl+K  - kill from cursor to line end
+ *   Ctrl+W  - kill word backwards (whitespace + punctuation delimiter)
+ *   Ctrl+Y  - yank the most recent kill at the cursor
+ *
+ * The ring is bounded (MAX_RING_ENTRIES = 10) so the operator's
+ * recent kills are reachable without leaking memory across long
+ * sessions. We do NOT implement Meta+Y (cycle yanks) at this layer -
+ * sticking to the most-recent-yank keeps the input box logic small
+ * and matches the bash default for new operators.
+ *
+ * The module is pure functional: every operation returns a NEW ring,
+ * so the input box can stash one in `useState` without mutation
+ * worries. Empty slices are no-ops (we do not push empty strings) so
+ * Ctrl+U at column 0 does not pollute the ring with `""`.
+ */
+export const MAX_RING_ENTRIES = 10;
+export const EMPTY_KILL_RING = { entries: [] };
+/**
+ * Push a slice into the ring. Returns a new ring with the slice at
+ * the front; older entries shift right and the tail is dropped if
+ * the cap is exceeded. Empty / whitespace-only slices are a no-op so
+ * the ring stays meaningful.
+ */
+export function push(ring, slice) {
+    if (slice.length === 0)
+        return ring;
+    const next = [slice, ...ring.entries];
+    return { entries: next.slice(0, MAX_RING_ENTRIES) };
+}
+/**
+ * Read the most-recent entry without mutating the ring. Returns
+ * `null` when the ring is empty so the caller can decide whether to
+ * beep, no-op, or fall through to plain insert.
+ */
+export function yank(ring) {
+    return ring.entries.length > 0 ? ring.entries[0] : null;
+}
+/**
+ * Word delimiter used by Ctrl+W. Whitespace + ASCII punctuation,
+ * matching the readline default. We treat `_` and `-` as part of the
+ * word so kebab-case and snake_case identifiers behave as one token
+ * (the brief frequently mentions filenames + symbols).
+ */
+const WORD_DELIMITERS = new Set([
+    ' ', '\t', '\n',
+    '.', ',', ';', ':',
+    '/', '\\',
+    '!', '?', '@', '#', '$', '%', '^', '&', '*',
+    '(', ')', '[', ']', '{', '}', '<', '>',
+    '"', "'", '`',
+    '=', '+', '|', '~',
+]);
+/**
+ * Compute the start of the previous word given a cursor position.
+ * Walks LEFT from `cursor - 1`, skipping any delimiters that
+ * immediately precede the cursor (so Ctrl+W at the end of `foo `
+ * still kills `foo`), then continues left until it hits the next
+ * delimiter or the start of the line.
+ *
+ * Returns the offset BEFORE which the kill should start (i.e. the
+ * slice to remove is `line.slice(start, cursor)`).
+ */
+export function previousWordStart(line, cursor) {
+    let i = Math.min(cursor, line.length) - 1;
+    // Skip trailing delimiters.
+    while (i >= 0 && WORD_DELIMITERS.has(line[i]))
+        i -= 1;
+    // Walk through the word.
+    while (i >= 0 && !WORD_DELIMITERS.has(line[i]))
+        i -= 1;
+    return i + 1;
+}
+/**
+ * Apply a Ctrl+U kill: from cursor to line start. Returns the new
+ * line + cursor + ring. No-op when cursor is already at column 0.
+ */
+export function killToLineStart(line, cursor, ring) {
+    if (cursor === 0)
+        return { line, cursor, ring };
+    const slice = line.slice(0, cursor);
+    return {
+        line: line.slice(cursor),
+        cursor: 0,
+        ring: push(ring, slice),
+    };
+}
+/**
+ * Apply a Ctrl+K kill: from cursor to line end. Returns the new
+ * line + cursor + ring. No-op when cursor is already past the last
+ * character.
+ */
+export function killToLineEnd(line, cursor, ring) {
+    if (cursor >= line.length)
+        return { line, cursor, ring };
+    const slice = line.slice(cursor);
+    return {
+        line: line.slice(0, cursor),
+        cursor,
+        ring: push(ring, slice),
+    };
+}
+/**
+ * Apply a Ctrl+W kill: from cursor back to the start of the previous
+ * word. Returns the new line + cursor + ring. No-op when cursor is
+ * at column 0.
+ */
+export function killWordBackward(line, cursor, ring) {
+    if (cursor === 0)
+        return { line, cursor, ring };
+    const start = previousWordStart(line, cursor);
+    const slice = line.slice(start, cursor);
+    return {
+        line: line.slice(0, start) + line.slice(cursor),
+        cursor: start,
+        ring: push(ring, slice),
+    };
+}
+/**
+ * Apply a Ctrl+Y yank: insert the most-recent entry at the cursor.
+ * Returns the new line + cursor unchanged when the ring is empty
+ * (the caller decides whether to surface a visual cue).
+ */
+export function yankAtCursor(line, cursor, ring) {
+    const entry = yank(ring);
+    if (entry === null)
+        return { line, cursor };
+    return {
+        line: line.slice(0, cursor) + entry + line.slice(cursor),
+        cursor: cursor + entry.length,
+    };
+}
+//# sourceMappingURL=kill-ring.js.map

package/dist/core/repl/session.js

@@ -30,6 +30,11 @@ 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;
@@ -43,6 +48,18 @@ export class ReplSession {
     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 = {
@@ -133,8 +150,154 @@ export class ReplSession {
                 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;
@@ -263,6 +426,12 @@ export class ReplSession {
                 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 }
@@ -286,18 +455,41 @@ export class ReplSession {
             }
             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) {
-                    this.appendPersonaLine(target.personaSlug, 'shipped.');
+                    // 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 }
@@ -310,6 +502,7 @@ export class ReplSession {
             }
             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 }