@pugi/cli 0.1.0-beta.99 → 1.0.0-alpha.1

package/dist/core/repl/cap-warning.js

@@ -1,91 +0,0 @@
-/**
- * Client-side concurrent-subagent cap - Sprint (
- * acceptance #6, Mac safety memo
- * `feedback_max_3_parallel_agents_mac_safety.md`).
- *
- * Mac-safety memo caps interactive concurrency at 3 active subagents
- * per workstation. The REPL has its own client-side gate that mirrors
- * the global rule for one workstation worth of dispatches:
- *
- *  - active count >= 3 → soft warning (operator may still dispatch).
- *  - active count >= 5 → hard block unless the operator opted in via
- *    PUGI_FORCE_PARALLEL=1.
- *
- * The gate is pure: callers pass the current active count and we return
- * a verdict. The REPL session module reads the dispatcher event stream,
- * tracks active dispatches, and consults this function before
- * forwarding `/brief` to the controller.
- *
- * The hard cap matches the absolute ceiling cited in the Mac memo (3
- * brand-recommended, 5 ABSOLUTE max with the env-flag escape hatch).
- * Bumping either threshold is a memo update, not a code-only change.
- */
-/**
- * Soft warning threshold. At this many active subagents the REPL
- * surfaces a non-blocking nudge. The operator can confirm and proceed.
- */
-export const CAP_WARNING_THRESHOLD = 3;
-/**
- * Hard block threshold. At this many active subagents the REPL refuses
- * the new dispatch unless `PUGI_FORCE_PARALLEL=1` is in the environment.
- */
-export const CAP_HARD_BLOCK_THRESHOLD = 5;
-/**
- * Env flag operators set to override the hard cap. Documented in
- * `pugi doctor` output and in the Mac safety memo. Set this to `1`,
- * `true`, or `yes` to bypass. Anything else (including unset) leaves
- * the cap enforced.
- */
-export const FORCE_PARALLEL_ENV_VAR = 'PUGI_FORCE_PARALLEL';
-/**
- * Compute the cap verdict given the current active subagent count and
- * the operator's environment.
- *
- * The function is pure (no global state, no IO). Callers must pass the
- * env they want considered - production callers pass process.env, tests
- * pass a fixture so the gate is deterministic.
- */
-export function evaluateCap(input) {
-    const active = Math.max(0, Math.floor(input.active));
-    const env = input.env ?? {};
-    const forceParallel = isForceParallelSet(env);
-    if (active >= CAP_HARD_BLOCK_THRESHOLD) {
-        if (forceParallel) {
-            return { kind: 'override', active, envVar: FORCE_PARALLEL_ENV_VAR };
-        }
-        return { kind: 'block', active, envVar: FORCE_PARALLEL_ENV_VAR };
-    }
-    if (active >= CAP_WARNING_THRESHOLD) {
-        return { kind: 'warn', active };
-    }
-    return { kind: 'allow' };
-}
-/**
- * Render a one-line operator nudge for a non-allow verdict. The REPL
- * appends this line to the conversation pane on its own row so the
- * cyan colour token survives Ink's whitespace collapsing.
- *
- * Brand voice: power words `on watch`, `workforce`. No em dash, no
- * emoji. Capacity rather than `agents` to avoid colliding with the
- * `/agents` command name in the same frame.
- */
-export function describeVerdict(verdict) {
-    switch (verdict.kind) {
-        case 'allow':
-            return '';
-        case 'warn':
-            return `Capacity nudge: ${verdict.active} agents already on watch - keep an eye on workstation load.`;
-        case 'block':
-            return `Capacity block: ${verdict.active} agents on watch is the absolute ceiling. Set ${verdict.envVar}=1 to override.`;
-        case 'override':
-            return `Capacity cap bypassed (${verdict.envVar}=1) - ${verdict.active} agents already on watch.`;
-    }
-}
-function isForceParallelSet(env) {
-    const raw = env[FORCE_PARALLEL_ENV_VAR];
-    if (typeof raw !== 'string')
-        return false;
-    const normalized = raw.trim().toLowerCase();
-    return normalized === '1' || normalized === 'true' || normalized === 'yes';
-}
-//# sourceMappingURL=cap-warning.js.map

package/dist/core/repl/clipboard-read.js

@@ -1,174 +0,0 @@
-/**
- * Best-effort clipboard READ helper - Sprint .
- *
- * Mirror of the clipboard WRITE helper but for the opposite
- * direction. Powers Ctrl+V paste in the REPL input box: when the
- * operator presses Ctrl+V we spawn the platform's paste binary
- * (pbpaste / wl-paste / xclip -o / PowerShell Get-Clipboard) and
- * insert the result at the cursor.
- *
- * Contract:
- *  - Returns `{ text }` when the helper exited 0 with non-empty
- *    stdout. Trailing single newline is stripped (clipboard
- *    contents authored by the operator rarely include the trailing
- *    LF the paste helpers append).
- *  - Returns `{ text: null }` on any failure: missing binary,
- *    non-zero exit, no $DISPLAY on headless Linux, EAGAIN.
- *  - Never throws. Caller falls back to "Ctrl+V not available -
- *    try right-click paste" hint.
- *  - Targets node >= 20.
- *
- * Implementation note: we do NOT optimistically run all three Linux
- * helpers in parallel - the cost of spawning xclip when wl-copy
- * already produced text is small but visible (50ms+ each on cold
- * cache). Ordering: WAYLAND_DISPLAY → wl-paste; otherwise xclip first.
- */
-import { spawn } from 'node:child_process';
-export async function readClipboard(deps = {}) {
-    const platform = deps.platform ?? process.platform;
-    const spawnRead = deps.spawnRead ?? defaultSpawnRead;
-    const env = deps.env ?? process.env;
-    if (platform === 'darwin') {
-        const text = await spawnRead('pbpaste', []);
-        return { text: normalise(text) };
-    }
-    if (platform === 'win32') {
-        // PowerShell is the universally available path. Get-Clipboard
-        // emits UTF-16 by default; the -Raw flag preserves newlines and
-        // returns one string.
-        const text = await spawnRead('powershell', ['-NoProfile', '-Command', 'Get-Clipboard -Raw']);
-        return { text: normalise(text) };
-    }
-    if (platform === 'linux' || platform === 'freebsd' || platform === 'openbsd') {
-        const order = env.WAYLAND_DISPLAY
-            ? ['wl-paste', 'xclip', 'xsel']
-            : ['xclip', 'wl-paste', 'xsel'];
-        for (const tool of order) {
-            const args = tool === 'xclip'
-                ? ['-selection', 'clipboard', '-o']
-                : tool === 'xsel'
-                    ? ['--clipboard', '--output']
-                    : ['--no-newline'];
-            const text = await spawnRead(tool, args);
-            if (text !== null && text.length > 0) {
-                return { text: normalise(text) };
-            }
-        }
-        return { text: null };
-    }
-    return { text: null };
-}
-function normalise(raw) {
-    if (raw === null)
-        return null;
-    if (raw.length === 0)
-        return null;
-    // Strip a single trailing LF the helpers often append. Multi-line
-    // pastes preserve interior newlines.
-    return raw.endsWith('\n') ? raw.slice(0, -1) : raw;
-}
-/**
- * Hard cap on clipboard payload size. The paste helper streams stdout
- * with no upper bound by default, so a pathologically large clipboard
- * (e.g. a hostile actor's 500 MiB file URL list, or an accidental copy
- * of a large binary) would OOM the CLI process if we kept appending.
- * 1 MiB is plenty for any realistic prompt + code snippet paste and
- * still leaves room in V8's default young-generation heap.
- */
-const MAX_CLIPBOARD_BYTES = 1024 * 1024; // 1 MiB
-function defaultSpawnRead(cmd, args) {
-    return new Promise((resolve) => {
-        let settled = false;
-        let overflow = false;
-        let totalBytes = 0;
-        const chunks = [];
-        const settle = (value) => {
-            if (settled)
-                return;
-            settled = true;
-            resolve(value);
-        };
-        try {
-            const options = {
-                stdio: ['ignore', 'pipe', 'ignore'],
-                shell: false,
-            };
-            const child = spawn(cmd, args.slice(), options);
-            child.on('error', () => settle(null));
-            child.stdout?.on('data', (b) => {
-                if (overflow)
-                    return;
-                totalBytes += b.length;
-                if (totalBytes > MAX_CLIPBOARD_BYTES) {
-                    overflow = true;
-                    try {
-                        child.kill('SIGTERM');
-                    }
-                    catch {
-                        // Best effort; close handler still settles below.
-                    }
-                    return;
-                }
-                chunks.push(b);
-            });
-            child.on('close', (code) => {
-                if (overflow)
-                    return settle(null);
-                if (code !== 0)
-                    return settle(null);
-                const buf = Buffer.concat(chunks);
-                settle(buf.toString('utf8'));
-            });
-        }
-        catch {
-            settle(null);
-        }
-    });
-}
-/* ------------------------------------------------------------------ */
-/* Bracketed-paste mode helpers                                      */
-/* ------------------------------------------------------------------ */
-/**
- * Modern terminals (iTerm2, Alacritty, GNOME Terminal, kitty,
- * Windows Terminal) bracket pasted text with `ESC[200~ ... ESC[201~`
- * when bracketed-paste mode is enabled. The input box can detect
- * these markers and disable newline-as-submit during the paste burst
- * so a multi-line paste does not fire `onSubmit` mid-paste.
- *
- * The constants here are exported so the input box and the unit
- * test can share the byte sequences without re-implementing them.
- */
-export const PASTE_START = '\x1b[200~';
-export const PASTE_END = '\x1b[201~';
-export const CTRL_V = '\x16';
-export function classifyChunk(chunk, inPaste) {
-    if (inPaste) {
-        const endIdx = chunk.indexOf(PASTE_END);
-        if (endIdx === -1) {
-            return { kind: 'paste-cont', textInPaste: chunk };
-        }
-        return {
-            kind: 'paste-end',
-            textInPaste: chunk.slice(0, endIdx),
-            textAfter: chunk.slice(endIdx + PASTE_END.length),
-        };
-    }
-    const startIdx = chunk.indexOf(PASTE_START);
-    if (startIdx === -1) {
-        return { kind: 'plain', text: chunk };
-    }
-    const afterStart = chunk.slice(startIdx + PASTE_START.length);
-    const endIdx = afterStart.indexOf(PASTE_END);
-    if (endIdx === -1) {
-        return {
-            kind: 'paste-start',
-            textBefore: chunk.slice(0, startIdx),
-            textInPaste: afterStart,
-        };
-    }
-    return {
-        kind: 'paste-only',
-        text: afterStart.slice(0, endIdx),
-    };
-}
-//# sourceMappingURL=clipboard-read.js.map

package/dist/core/repl/dispatch-fsm.js

@@ -1,220 +0,0 @@
-/**
- * Dispatch FSM — Sprint Phase 1 (agent loop FSM + cancellation).
- *
- * Tracks the lifecycle of a single operator-issued brief from the moment
- * `POST /api/pugi/sessions/:id/brief` fires until the persona returns a
- * final reply (or the operator aborts). The Ctrl+C handler and the
- * status-bar surface both subscribe to state transitions so the UX is
- * predictable: the operator can always tell where the dispatch is in
- * its lifecycle and the abort signal lands at a deterministic seam.
- *
- * State graph:
- *
- *     idle
- *      │ (brief posted)
- *      ▼
- *  awaiting_response ←──────────┐
- *      │                       │ (next turn)
- *      ▼                       │
- *  tool_running ────────────────┘
- *      │
- *      ▼
- *  completed
- *
- * Terminal states: `completed`, `failed`, `aborted`. The FSM does not
- * transition out of a terminal state; a fresh brief mints a new FSM
- * instance. `aborting` is transient — any non-terminal state can
- * transition to `aborting`, which then transitions to `aborted` once
- * the SSE stream + in-flight tool acknowledge the abort.
- *
- * Illegal transitions are rejected by throwing a typed error. This is
- * load-bearing: a bug that tries to walk `completed → tool_running`
- * would otherwise silently corrupt the agent tree. Throwing fails
- * loud at the call site so the integration bug surfaces immediately.
- *
- * onEnter listeners fire AFTER the state transition is committed.
- * Subscribers can call `transition()` from inside a listener; the FSM
- * uses a small re-entrancy guard so nested transitions are processed
- * in order (the inner transition fires its own listeners before the
- * outer transition returns).
- *
- * Brand voice: no forbidden words. ASCII only. No emoji.
- */
-/**
- * Legal transitions per state. Building the matrix at module scope
- * keeps the FSM declarative and exhaustive — adding a new state forces
- * the matrix update at typecheck time.
- *
- * `idle` is the start state. Posting a brief moves to
- * `awaiting_response`. The model's first turn either returns a final
- * text (`completed`), requests tools (`tool_running`), or fails
- * (`failed`). After tools execute the model gets another turn
- * (`awaiting_response`); the cycle repeats until a final text or a
- * terminal outcome.
- *
- * `aborting` is reachable from every non-terminal state. From
- * `aborting` we always end at `aborted` (no rollback — once the
- * operator aborts, the dispatch is dead). Terminal states have no
- * outgoing transitions.
- */
-const LEGAL_TRANSITIONS = {
-    idle: new Set(['awaiting_response', 'aborting']),
-    awaiting_response: new Set([
-        'tool_running',
-        'completed',
-        'failed',
-        'aborting',
-    ]),
-    tool_running: new Set([
-        'awaiting_response',
-        'completed',
-        'failed',
-        'aborting',
-    ]),
-    aborting: new Set(['aborted']),
-    aborted: new Set(),
-    completed: new Set(),
-    failed: new Set(),
-};
-/**
- * Thrown when `transition()` is called with a state that is not in the
- * current state's legal outgoing set. Carries enough context that a log
- * line can be reconstructed at the call site.
- */
-export class IllegalDispatchTransitionError extends Error {
-    from;
-    to;
-    constructor(from, to) {
-        super(`Illegal dispatch FSM transition: ${from} -> ${to}`);
-        this.name = 'IllegalDispatchTransitionError';
-        this.from = from;
-        this.to = to;
-    }
-}
-export class DispatchFSM {
-    state = 'idle';
-    listeners = new Map();
-    /**
-     * Re-entrancy guard. While `firing === true` we are draining the
-     * listener fan-out for an in-progress transition. A nested
-     * `transition()` call from inside a listener queues into `pending`
-     * instead of recursing, so the legality check + state mutation +
-     * listener drain happen sequentially in commit order. Without this,
-     * a listener that immediately fired another transition would mutate
-     * `this.state` mid-iteration of the outer listener snapshot, which
-     * (a) could turn a legal outer transition into a thrown illegal
-     * inner one (the legality check reads `this.state` already mutated),
-     * (b) could ship `onEnter(B)` reasons under state A's snapshot.
-     * Queueing keeps the transition log linear.
-     */
-    firing = false;
-    pending = [];
-    /**
-     * Current state. Read-only — mutate via `transition()`.
-     */
-    get current() {
-        return this.state;
-    }
-    /**
-     * True when the current state is one of `completed`, `failed`,
-     * `aborted`. Terminal states cannot transition further.
-     */
-    get isTerminal() {
-        return this.state === 'completed' || this.state === 'failed' || this.state === 'aborted';
-    }
-    /**
-     * Transition the FSM to `next`, optionally carrying a `reason` string
-     * that is forwarded to `onEnter` listeners. Throws
-     * `IllegalDispatchTransitionError` when the transition is not in the
-     * current state's legal outgoing set.
-     *
-     * Listener errors do NOT block the transition. A throwing listener
-     * stops itself but the transition is already committed; the next
-     * listener still fires.
-     *
-     * Re-entrant calls (a listener calls `transition()` again) are
-     * queued - the inner transition runs after the outer listener drain
-     * completes, in FIFO order. See `firing` field comment.
-     */
-    transition(next, reason) {
-        if (this.firing) {
-            this.pending.push({ next, reason });
-            return;
-        }
-        this.firing = true;
-        try {
-            // R2 P2 fix (Codex triple-review): if `commit` throws -
-            // either the first move or any queued nested move - we MUST flush
-            // the pending queue before propagating the error. Otherwise a
-            // later `transition()` call would drain stale entries left over
-            // from the failed turn, firing onEnter listeners under a wholly
-            // different state context. The queue is "poisoned" the moment any
-            // entry throws; the safest move is to drop the rest and surface
-            // the failure to the caller.
-            try {
-                this.commit(next, reason);
-                while (this.pending.length > 0) {
-                    const queued = this.pending.shift();
-                    if (!queued)
-                        break;
-                    this.commit(queued.next, queued.reason);
-                }
-            }
-            catch (err) {
-                // Drop every still-queued entry so the next external transition
-                // starts on a clean queue. See the inline rationale above.
-                this.pending.length = 0;
-                throw err;
-            }
-        }
-        finally {
-            this.firing = false;
-        }
-    }
-    /**
-     * Inner commit step - legality check + state mutation + listener
-     * drain. Called by `transition()` directly for the first move and
-     * for every queued nested move thereafter. Errors propagate to the
-     * outer `transition()` caller (illegal transitions still throw).
-     */
-    commit(next, reason) {
-        const legal = LEGAL_TRANSITIONS[this.state];
-        if (!legal.has(next)) {
-            throw new IllegalDispatchTransitionError(this.state, next);
-        }
-        this.state = next;
-        const set = this.listeners.get(next);
-        if (!set || set.size === 0)
-            return;
-        // Snapshot the listener set so a listener that detaches itself
-        // (via the returned unsubscribe handle) does not corrupt iteration.
-        const snapshot = Array.from(set);
-        for (const listener of snapshot) {
-            try {
-                listener(reason);
-            }
-            catch {
-                // Swallow listener errors — see header comment for rationale.
-            }
-        }
-    }
-    /**
-     * Register a listener that fires whenever the FSM ENTERS `state`. The
-     * listener does NOT fire if the FSM is already in `state` at
-     * registration time — onEnter is edge-triggered, not level-triggered.
-     *
-     * Returns an unsubscribe handle.
-     */
-    onEnter(state, listener) {
-        let set = this.listeners.get(state);
-        if (!set) {
-            set = new Set();
-            this.listeners.set(state, set);
-        }
-        set.add(listener);
-        return () => {
-            set?.delete(listener);
-        };
-    }
-}
-//# sourceMappingURL=dispatch-fsm.js.map