@pugi/cli 0.1.0-alpha.9 → 0.1.0-beta.2

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

@@ -0,0 +1,220 @@
+/**
+ * Dispatch FSM — Sprint α6.9 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 2026-05-25): 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

package/dist/core/repl/privacy-banner.js

@@ -0,0 +1,71 @@
+/**
+ * Privacy mode REPL surface - alpha 6.13 (Phase 1).
+ *
+ * Two surfaces:
+ *
+ *   1. `renderPrivacyBanner(mode)` - one-line banner shown on REPL
+ *      bootstrap (mirrors `apps/admin-api/src/privacy/privacy-mode.ts`
+ *      `PRIVACY_MODE_BANNER` verbatim - keep in sync, the unit spec
+ *      asserts they match).
+ *
+ *   2. `renderPrivacyContractDoc(mode)` - multi-line contract doc the
+ *      `/privacy` slash command prints. Shows the active mode header
+ *      + the full 3-mode contract so the operator can compare their
+ *      current posture to the alternatives without leaving the REPL.
+ *
+ * The strings are pinned client-side so the contract doc is
+ * available even when the operator is offline / has not authenticated
+ * yet. The mode value itself is server-side authoritative (resolved
+ * via /api/admin/privacy/mode); the banner falls back to "(unknown)"
+ * when the round-trip fails.
+ *
+ * Brand voice: ASCII hyphens only, no em-dashes, no emoji decoration.
+ */
+export const PRIVACY_MODES = ['strict', 'balanced', 'permissive'];
+export function isPrivacyMode(value) {
+    return (typeof value === 'string' && PRIVACY_MODES.includes(value));
+}
+/**
+ * One-line banner. Mirrors `PRIVACY_MODE_BANNER` on the server.
+ */
+const BANNERS = Object.freeze({
+    strict: 'Privacy: strict (no upstream LLM, no external tool egress)',
+    balanced: 'Privacy: balanced (PII scrubbed before upstream LLM)',
+    permissive: 'Privacy: permissive (raw prompts forwarded upstream)',
+});
+export function renderPrivacyBanner(mode) {
+    if (!mode || !isPrivacyMode(mode)) {
+        return 'Privacy: (unknown - mode lookup pending)';
+    }
+    return BANNERS[mode];
+}
+/**
+ * Full mode contract doc. Printed by the `/privacy` slash command.
+ * Keep in sync with `PRIVACY_MODE_CONTRACT_DOC` on the server.
+ */
+const CONTRACT_DOC = `
+Pugi privacy mode contract (alpha 6.13):
+
+  strict      Maximum privacy. Nothing leaves tenant infra.
+              - Upstream LLM calls REFUSED (use self-hosted Ollama / llama.cpp).
+              - External tool calls require per-call confirm.
+              - Session.db, blobs, transcripts stay on operator disk.
+              - No telemetry. No error reporting.
+
+  balanced    Default. PII-scrubbed content goes to the upstream LLM.
+              - 3-layer PII scrubber runs before egress (regex + NER + LLM).
+              - Tool calls to external services allowed (logged).
+              - Anonymized telemetry only (counts + error categories).
+
+  permissive  Verbatim. Power-user mode.
+              - Raw prompts forwarded to upstream provider (no scrubbing).
+              - Tool calls to external services allowed.
+              - Full error reporting (may include prompt fragments).
+              - Accepts the upstream provider's data retention policy.
+
+Switch with: pugi config set privacy=strict|balanced|permissive
+`.trim();
+export function renderPrivacyContractDoc(currentMode) {
+    return `${renderPrivacyBanner(currentMode)}\n\n${CONTRACT_DOC}`;
+}
+//# sourceMappingURL=privacy-banner.js.map