@pugi/cli 0.1.0-alpha.17 → 0.1.0-alpha.19

package/dist/core/repl/cancellation.js

@@ -0,0 +1,98 @@
+/**
+ * Cancellation token — Sprint α6.9 Phase 1 (agent loop FSM + cancellation).
+ *
+ * A pure-JS one-shot signal that fans out to N listeners. One token is
+ * minted per dispatch turn (fresh on each operator brief); when the
+ * operator hits Ctrl+C, the REPL calls `abort()` which:
+ *
+ *   1. Latches `aborted = true` so any future `isAborted` check returns
+ *      true (a tool that observes the flag mid-execution can short-circuit
+ *      its loop without waiting for an explicit signal-handler callback).
+ *   2. Drains the listener set, firing each callback exactly once. The
+ *      set is cleared after the drain so a late `onAbort` listener
+ *      attached AFTER abort does NOT fire — that is the documented
+ *      contract; late listeners are expected to check `isAborted`
+ *      explicitly at registration time if they need to know whether the
+ *      token already tripped.
+ *
+ * Design choices:
+ *
+ *   - No coupling to `AbortController` / `AbortSignal`. The session +
+ *     tool path are wrapped around this token; where a Web platform
+ *     primitive is needed (fetch signal, MCP call), the wrapper bridges
+ *     `onAbort` → `controller.abort()` at the seam.
+ *   - Idempotent `abort()`. Calling twice is safe and the second call is
+ *     a no-op (the listener set is already empty). This matters because
+ *     two code paths can race to cancel — the Ctrl+C handler and a
+ *     downstream tool that observed `isAborted` and threw — and both
+ *     end up calling `dispatch.cancel()` which transitively calls
+ *     `token.abort()`.
+ *   - Listener errors do NOT block the drain. A throwing listener
+ *     stops itself but the next listener still fires. The error is
+ *     swallowed because the cancellation path is best-effort and
+ *     surfacing the error mid-drain would leak through the abort
+ *     pathway into the REPL state (a UI rerender on a half-aborted
+ *     session is worse than a silent listener crash).
+ *
+ * Brand voice: no forbidden words. ASCII only. No emoji.
+ */
+export class CancellationToken {
+    aborted = false;
+    listeners = new Set();
+    /**
+     * Latch the token to aborted and fire every currently-attached
+     * listener exactly once. Subsequent `abort()` calls are no-ops
+     * (idempotent — the listener set was already cleared on first abort).
+     * Listener callbacks that throw are swallowed; the next listener
+     * still fires.
+     */
+    abort() {
+        if (this.aborted)
+            return;
+        this.aborted = true;
+        // Snapshot the listener set so a listener that mutates the set
+        // (e.g. detaches itself via the returned unsubscribe handle while
+        // its own callback is running) does not corrupt the iteration.
+        const snapshot = Array.from(this.listeners);
+        this.listeners.clear();
+        for (const listener of snapshot) {
+            try {
+                listener();
+            }
+            catch {
+                // Swallow listener errors — see header comment for rationale.
+            }
+        }
+    }
+    /**
+     * True after `abort()` has been called. Mutation observers and tool
+     * inner loops should read this BEFORE each potentially-expensive
+     * iteration so they can short-circuit on cancel.
+     */
+    get isAborted() {
+        return this.aborted;
+    }
+    /**
+     * Register a callback that fires on the FIRST `abort()` call. If the
+     * token has already aborted at registration time, the callback is
+     * NOT auto-fired — the caller is responsible for checking
+     * `isAborted` first.
+     *
+     * Returns an unsubscribe handle. Calling it before abort detaches the
+     * listener so it never fires; calling it after abort is a no-op (the
+     * set was already drained).
+     */
+    onAbort(listener) {
+        if (this.aborted) {
+            // Document the contract by returning a no-op unsubscribe handle.
+            // The listener does NOT fire — late subscribers must check
+            // isAborted at registration time.
+            return () => undefined;
+        }
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+}
+//# sourceMappingURL=cancellation.js.map

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

@@ -0,0 +1,204 @@
+/**
+ * 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 {
+            this.commit(next, reason);
+            while (this.pending.length > 0) {
+                const queued = this.pending.shift();
+                if (!queued)
+                    break;
+                this.commit(queued.next, queued.reason);
+            }
+        }
+        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

@@ -1,14 +1,14 @@
 /**
- * Privacy mode REPL surface — α6.13 (Phase 1).
+ * Privacy mode REPL surface - alpha 6.13 (Phase 1).
  *
  * Two surfaces:
  *
- *   1. `renderPrivacyBanner(mode)` — one-line banner shown on REPL
+ *   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
+ *      `PRIVACY_MODE_BANNER` verbatim - keep in sync, the unit spec
  *      asserts they match).
  *
- *   2. `renderPrivacyContractDoc(mode)` — multi-line contract doc the
+ *   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.