@pugi/cli 0.1.0-beta.93 → 0.1.0-beta.94

package/dist/core/repl/session.js

@@ -40,6 +40,7 @@ import { applyRewindMask } from '../checkpoint/rewinder.js';
 import { evaluateAutoCompact } from '../compact/auto-trigger.js';
 import { estimateTokensInMany } from '../compact/token-counter.js';
 import { extractAskTags, extractPlanReviewTags, signatureForAsk, } from './ask.js';
+import { extractToolRouteTags, } from './tool-route.js';
 import { existsSync, readdirSync, statSync } from 'node:fs';
 import { resolve as resolvePath } from 'node:path';
 import { CancellationToken } from './cancellation.js';
@@ -314,6 +315,30 @@ export class ReplSession {
      * cleaned body). Codex triple-review P2 (PR).
      */
     askBufferPending = new Set();
+    /**
+     * PUGI-538b () — pending `<pugi-tool-route>` envelope per
+     * coordinator taskId. Captured by `consumePugiToolRouteTag` when the
+     * envelope's close (or self-close) arrives in the running
+     * `agent.step.detail` buffer. The `agent.completed` handler reads
+     * the entry to decide whether to fire the engine bridge — firing
+     * mid-stream would race with the still-streaming coordinator turn.
+     * Cleared on terminal events (`completed` / `blocked` / `failed`).
+     *
+     * Only one envelope per coordinator turn is honoured (the prompt
+     * grammar refuses more than one); a second envelope on the same
+     * turn is dropped via the seen-signature rolling set so the dedupe
+     * lives in one place.
+     */
+    pendingToolRoutes = new Map();
+    /**
+     * PUGI-538b () — abort controllers for in-flight engine
+     * bridges, keyed by `bridgeId`. When the REPL operator hits stop,
+     * `cancel()` walks this map and aborts every active bridge so the
+     * engine HTTP request closes promptly (the engine loop already
+     * honours `AbortSignal` via `EngineContext.signal`). Entries are
+     * deleted on bridge completion regardless of outcome.
+     */
+    bridgeAborts = new Map();
     constructor(options) {
         this.options = options;
         this.store = options.store ?? null;
@@ -533,6 +558,21 @@ export class ReplSession {
             this.currentDispatchToken.abort();
             this.currentDispatchToken = null;
         }
+        // PUGI-538b () — abort every in-flight engine bridge on
+        // close() so the engine HTTP request closes promptly when the
+        // REPL itself shuts down (operator quit, process exit). Same
+        // defensive-try block as cancel() above; already-aborted
+        // controllers throw on some Node builds and close() must never
+        // crash the caller.
+        for (const controller of this.bridgeAborts.values()) {
+            try {
+                controller.abort();
+            }
+            catch {
+                // Best-effort.
+            }
+        }
+        this.bridgeAborts.clear();
         if (this.streamHandle) {
             this.streamHandle.close();
             this.streamHandle = undefined;
@@ -583,13 +623,39 @@ export class ReplSession {
      */
     cancel() {
         const current = this.fsm.current;
-        if (this.fsm.isTerminal || current === 'idle')
-            return false;
+        const hasActiveBridge = this.bridgeAborts.size > 0;
+        // PUGI-538b () step 4 — bridge cancellation is allowed even
+        // when the FSM is terminal. The bridge runs ASYNC after the
+        // coordinator turn completes, so by the time the operator hits stop
+        // the FSM has already transitioned to `completed` and the legacy
+        // guard would short-circuit before the bridge-abort fan-out ran.
+        // Without this branch, Esc after the coordinator turn settles would
+        // not cancel an in-flight engine call.
+        if (this.fsm.isTerminal || current === 'idle') {
+            if (!hasActiveBridge)
+                return false;
+            // Fan out abort to every active bridge, then short-circuit before
+            // the FSM transitions (the FSM is already terminal; there is no
+            // dispatch token to fire, no SSE stream to tear down for the
+            // current dispatch). Map entries are cleared by the bridge
+            // promise's then/catch handlers when they unwind.
+            for (const controller of this.bridgeAborts.values()) {
+                try {
+                    controller.abort();
+                }
+                catch {
+                    // Defensive: already-aborted controllers throw on some Node
+                    // builds. cancel() must never crash the caller.
+                }
+            }
+            this.appendSystemLine('Bridge aborted.');
+            return true;
+        }
         // Step 2: transient state (UI sees `aborting` between abort signal
         // and full shutdown).
         this.fsm.transition('aborting', 'operator_abort');
         // Step 3: fire the token so any mid-flight tool executor that
-        // polled `isAborted` shuts down. Token is single-use — clear the
+        // polled `isAborted` shuts down. Token is single-use; clear the
         // ref AFTER both the abort fan-out AND the stream teardown so any
         // onAbort listener calling getCurrentDispatchToken() during the
         // teardown observes the (now-aborted) token rather than null.
@@ -618,6 +684,23 @@ export class ReplSession {
         this.lastEventId = undefined;
         // Null the token AFTER stream teardown (see step 3 comment).
         this.currentDispatchToken = null;
+        // PUGI-538b () step 4 — abort every in-flight engine
+        // bridge. The bridge's AbortController is threaded through into
+        // the engine loop via EngineContext.signal (runEngineLoop already
+        // honours AbortSignal; see packages/pugi-sdk/src/engine-loop.ts
+        // around line 405). Aborting closes the engine HTTP request
+        // promptly so REPL stop cancels the bridge end-to-end, not just
+        // the local coordinator turn. Map entries are cleared by the
+        // bridge promise's then/catch handlers when they unwind.
+        for (const controller of this.bridgeAborts.values()) {
+            try {
+                controller.abort();
+            }
+            catch {
+                // Defensive: already-aborted controllers throw on some Node
+                // builds. cancel() must never crash the caller.
+            }
+        }
         // Mark any agents that are still "running" as failed/aborted so
         // the agent-tree pane reflects reality. We use the existing
         // `failed` status (the tree pane already knows how to render it)
@@ -3222,6 +3305,20 @@ export class ReplSession {
                         // the green check + duration.
                     }
                 }
+                // PUGI-538b () — after Pugi's coordinator turn settles,
+                // fire the engine bridge for any pending `<pugi-tool-route>`
+                // envelope stashed by `consumeAskAndPlanReviewTags`. The bridge
+                // runs ASYNCHRONOUSLY (we deliberately do not await — the SSE
+                // event handler must stay fast so the next frame is not
+                // delayed). `runEngineBridge` is wrapped in its own try/catch
+                // so a bridge failure cannot crash the REPL.
+                const pendingRoute = this.pendingToolRoutes.get(event.taskId);
+                if (pendingRoute) {
+                    this.pendingToolRoutes.delete(event.taskId);
+                    void this.runEngineBridge(pendingRoute).catch((err) => {
+                        this.appendSystemLine(`engine bridge crashed: ${this.errorMessage(err)}`);
+                    });
+                }
                 return;
             }
             case 'agent.blocked': {
@@ -3232,6 +3329,11 @@ export class ReplSession {
                 }
                 this.askBuffer.delete(event.taskId);
                 this.askBufferPending.delete(event.taskId);
+                // PUGI-538b () — drop any pending tool-route envelope on
+                // an aborted coordinator turn. Firing the bridge after the
+                // operator already stopped the dispatch would silently burn
+                // engine tokens for work they cancelled.
+                this.pendingToolRoutes.delete(event.taskId);
                 this.patch({
                     agents: this.state.agents.map((a) => a.taskId === event.taskId
                         ? { ...a, status: 'blocked', detail: event.detail }
@@ -3259,6 +3361,9 @@ export class ReplSession {
                 }
                 this.askBuffer.delete(event.taskId);
                 this.askBufferPending.delete(event.taskId);
+                // PUGI-538b () — drop any pending tool-route envelope on
+                // an aborted/failed coordinator turn. See agent.blocked rationale.
+                this.pendingToolRoutes.delete(event.taskId);
                 this.patch({
                     agents: this.state.agents.map((a) => a.taskId === event.taskId
                         ? { ...a, status: 'failed', detail: event.error }
@@ -3776,12 +3881,39 @@ export class ReplSession {
         if (planResult.hadMalformedTag) {
             this.appendSystemLine('Malformed <pugi-plan-review> dropped (parser refusal).');
         }
+        // PUGI-538b () — third envelope family: `<pugi-tool-route>`.
+        // Pugi emits it on the coordinator turn when the operator's brief
+        // requires workspace tool use. We strip the raw XML from the
+        // operator-visible body, dedupe via the seen-tag rolling set, and
+        // STASH the parsed envelope keyed by taskId. The `agent.completed`
+        // handler reads the stash and fires `bridgeToEngine` — firing
+        // mid-stream would race with the still-streaming coordinator turn.
+        const routeResult = extractToolRouteTags(working);
+        working = routeResult.cleaned;
+        for (const tag of routeResult.tags) {
+            if (this.seenTagSignatures.includes(tag.signature))
+                continue;
+            this.recordSeenTag(tag.signature);
+            if (this.pendingToolRoutes.has(taskId)) {
+                // Grammar says one envelope per turn. A second on the same
+                // taskId is dropped to a system line so the operator can see
+                // why the bridge did not fire twice.
+                this.appendSystemLine('Persona emitted a second <pugi-tool-route> while one was already pending. Dropped.');
+                continue;
+            }
+            this.pendingToolRoutes.set(taskId, tag);
+        }
+        if (routeResult.hadMalformedTag) {
+            this.appendSystemLine('Malformed <pugi-tool-route> dropped (parser refusal).');
+        }
         // Record / clear the "pending open tag" flag so agent.completed can
         // emit a warning if the persona ends the turn with an unfinished
-        // envelope. The flag flips OFF when both parsers report no
-        // outstanding open tag - if either is still pending, we keep it on
+        // envelope. The flag flips OFF when ALL parsers report no
+        // outstanding open tag - if any is still pending, we keep it on
         // so the warning fires once at turn end.
-        if (askResult.pendingOpenTag || planResult.pendingOpenTag) {
+        if (askResult.pendingOpenTag
+            || planResult.pendingOpenTag
+            || routeResult.pendingOpenTag) {
             this.askBufferPending.add(taskId);
         }
         else {
@@ -3789,6 +3921,240 @@ export class ReplSession {
         }
         return working;
     }
+    /**
+     * PUGI-538b () — public alias for the buffer-and-strip
+     * routine, kept for test ergonomics and external callers that want
+     * to invoke the parser without driving a full SSE replay. Mirrors
+     * the per-task buffering contract the private method already obeys.
+     *
+     * Exposed for the new `repl-tool-route-bridge.spec.ts` so the spec
+     * can assert that a streamed envelope is parsed and stripped without
+     * needing to fabricate a full agent.step / agent.completed sequence.
+     */
+    consumePugiToolRouteTag(taskId, detail) {
+        return this.consumeAskAndPlanReviewTags(taskId, detail);
+    }
+    /**
+     * PUGI-538b () — test-only inspector for the pending-tool-
+     * route stash. Spec asserts that an envelope captured mid-stream
+     * lands here and is cleared once the coordinator turn completes
+     * (which fires the bridge).
+     */
+    pendingToolRouteForTest(taskId) {
+        return this.pendingToolRoutes.get(taskId);
+    }
+    /**
+     * PUGI-538b () — fire the engine bridge for a parsed
+     * `<pugi-tool-route>` envelope. This is the CLI half of
+     * Path A: the coordinator turn's envelope routes the operational
+     * brief through the production engine path (NativePugiEngineAdapter
+     * → runEngineLoop → POST /api/pugi/engine) so workspace tool calls
+     * actually write files instead of dumping prose-only heredocs.
+     *
+     * The actual engine adapter wiring lives in the REPL bootstrap
+     * (`repl-render.tsx`); this method only:
+     *   1. surfaces a "Routing to engine" system line so the operator
+     *      sees the handoff,
+     *   2. mints a fresh AbortController and registers it in
+     *      `bridgeAborts` so REPL stop can cancel the bridge,
+     *   3. inserts a synthetic `agent` row keyed off a `bridge-<uuid>`
+     *      taskId so the agent-tree pane renders the engine turn the
+     *      same way it renders a sub-agent,
+     *   4. invokes `engineBridge` (the injected callback) and translates
+     *      every `BridgedEngineEvent` into a state patch on the synthetic
+     *      row,
+     *   5. flips the synthetic row to its terminal status when the
+     *      bridge resolves, surfacing the engine's final reply text (if
+     *      any) on a persona row so the operator sees it in the
+     *      transcript.
+     *
+     * When no `engineBridge` is provided in `ReplSessionOptions` (e.g. a
+     * test that opts out, or a CLI build that has not wired the adapter
+     * yet) we surface a single system-line warning explaining why the
+     * brief did not write files. This degradation preserves the pre-PR
+     * "see code, no file" UX without adding the "see envelope, no file"
+     * surprise on top.
+     */
+    async runEngineBridge(tag) {
+        const bridge = this.options.engineBridge;
+        if (!bridge) {
+            // No bridge wired — fall back to the pre-PR behaviour with one
+            // additional honest sentence so the operator can see WHY no
+            // files appeared. Triple-review surface: makes it obvious that
+            // the regression mode is "bridge not wired in this build", not
+            // "engine call failed". The brief is bounded by the parser at
+            // 400 chars so this line cannot blow up the transcript.
+            this.appendSystemLine(`Engine bridge not configured. Brief would have routed to ${tag.command}: "${tag.brief}".`);
+            return;
+        }
+        const bridgeId = `bridge-${randomUUID()}`;
+        const abort = new AbortController();
+        this.bridgeAborts.set(bridgeId, abort);
+        // Surface a system line so the operator sees the handoff before
+        // engine events start flowing. The wording mirrors the prompt's
+        // "Routing to engine" sentence so prompt + transcript stay in
+        // lockstep.
+        this.appendSystemLine(`Routing to engine (${tag.command} | ${tag.persona}): ${tag.brief}`);
+        // PUGI-538b — insert a synthetic agent-tree node so the existing
+        // pane renders the engine turn the same way it renders a
+        // sub-agent. Role is `coder` because the engine path is the write
+        // surface; the slug is the parsed persona hint so the pane shows
+        // "Hiroshi" (or whichever Tier-1 the envelope asked for) instead
+        // of a generic label.
+        const startedAt = this.now();
+        const personaName = this.resolveBridgePersonaName(tag.persona);
+        const syntheticNode = {
+            taskId: bridgeId,
+            role: 'coder',
+            personaSlug: tag.persona,
+            personaName,
+            status: 'thinking',
+            detail: tag.brief,
+            startedAtEpochMs: startedAt,
+            tokensIn: 0,
+            tokensOut: 0,
+        };
+        this.patch({ agents: [syntheticNode, ...this.state.agents] });
+        const onEvent = (event) => {
+            // Translate the bridge's typed events onto the synthetic
+            // agent-tree node. We deliberately mirror the existing
+            // agent.step / agent.tool / agent.tokens consumers above so the
+            // UI surface stays uniform across delegate and bridge sub-agents.
+            if (event.type === 'step') {
+                this.patch({
+                    agents: this.state.agents.map((a) => a.taskId === bridgeId
+                        ? { ...a, status: 'thinking', detail: event.detail }
+                        : a),
+                });
+            }
+            else if (event.type === 'tool.start') {
+                const mapped = normaliseBridgedToolName(event.tool);
+                if (mapped !== null) {
+                    this.appendToolCall({
+                        id: `${bridgeId}-${mapped}-${this.now()}`,
+                        tool: mapped,
+                        args: (event.args ?? '').slice(0, 80),
+                        agent: tag.persona,
+                        status: 'running',
+                        startedAtEpochMs: this.now(),
+                    });
+                }
+            }
+            else if (event.type === 'tool.result') {
+                const mapped = normaliseBridgedToolName(event.tool);
+                if (mapped !== null) {
+                    this.appendToolCall({
+                        id: `${bridgeId}-${mapped}-${this.now()}`,
+                        tool: mapped,
+                        args: '',
+                        agent: tag.persona,
+                        status: event.ok ? 'ok' : 'error',
+                        startedAtEpochMs: this.now(),
+                        resultPreview: (event.preview ?? '').slice(0, RESULT_PREVIEW_MAX_CHARS),
+                    });
+                }
+            }
+            else if (event.type === 'tokens') {
+                const deltaCostUsd = computeCostUsd(event.tokensIn, event.tokensOut, undefined);
+                this.patch({
+                    tokensDownstreamTotal: this.state.tokensDownstreamTotal + event.tokensIn + event.tokensOut,
+                    sessionTokensIn: this.state.sessionTokensIn + event.tokensIn,
+                    sessionTokensOut: this.state.sessionTokensOut + event.tokensOut,
+                    sessionCostUsd: this.state.sessionCostUsd + deltaCostUsd,
+                    turnTokensIn: this.state.turnTokensIn + event.tokensIn,
+                    turnTokensOut: this.state.turnTokensOut + event.tokensOut,
+                    turnCostUsd: this.state.turnCostUsd + deltaCostUsd,
+                    agents: this.state.agents.map((a) => a.taskId === bridgeId
+                        ? {
+                            ...a,
+                            tokensIn: a.tokensIn + event.tokensIn,
+                            tokensOut: a.tokensOut + event.tokensOut,
+                        }
+                        : a),
+                });
+            }
+        };
+        let result;
+        try {
+            result = await bridge({
+                command: tag.command,
+                persona: tag.persona,
+                brief: tag.brief,
+                bridgeId,
+                signal: abort.signal,
+                onEvent,
+            });
+        }
+        catch (err) {
+            this.bridgeAborts.delete(bridgeId);
+            const message = this.errorMessage(err);
+            this.patch({
+                agents: this.state.agents.map((a) => a.taskId === bridgeId
+                    ? { ...a, status: 'failed', detail: message }
+                    : a),
+            });
+            this.appendSystemLine(`Engine bridge failed: ${message}`);
+            return;
+        }
+        this.bridgeAborts.delete(bridgeId);
+        // PUGI-538c-FU-OUTCOME (2026-06-05): the bridge outcome union now
+        // carries `unverified`, which maps to the same-named agent-tree
+        // status so a fresh customer repo with no test infra no longer
+        // false-fails on the agent-tree pane. The verify-gate contract is
+        // preserved: real `verification_command_failed` runs still surface
+        // as `failed`; only `needs_verification` (no command detected)
+        // downgrades to advisory.
+        const terminalStatus = result.outcome === 'shipped'
+            ? 'shipped'
+            : result.outcome === 'unverified'
+                ? 'unverified'
+                : result.outcome === 'blocked'
+                    ? 'blocked'
+                    : 'failed';
+        this.patch({
+            agents: this.state.agents.map((a) => a.taskId === bridgeId
+                ? { ...a, status: terminalStatus, detail: result.detail ?? terminalStatus }
+                : a),
+        });
+        if (result.outcome === 'unverified') {
+            // Operator-visible advisory: explain why the agent-tree node
+            // landed in `unverified` rather than `shipped`. Files DID write
+            // (the bridge proved that) but the gate could not certify the
+            // run. Keep the wording neutral and actionable: avoid the word
+            // "failed" so the operator does not lose trust in the engine.
+            this.appendSystemLine('Pugi shipped files. No verification command detected; run your tests manually to confirm.');
+        }
+        if (result.finalText && result.finalText.trim().length > 0) {
+            this.appendPersonaLine(tag.persona, result.finalText.trim());
+        }
+    }
+    /**
+     * PUGI-538b () — best-effort display-name lookup for a
+     * bridge persona slug. The local frontend roster has the names; we
+     * keep the resolver narrow (Tier-1 slugs only) so this method does
+     * not pull in the full roster cycle. Unknown slugs fall back to a
+     * title-cased version of the slug, which is the same fallback the
+     * agent-tree pane uses for unrecognised persona slugs.
+     */
+    resolveBridgePersonaName(slug) {
+        const tier1 = {
+            dev: 'Hiroshi',
+            qa: 'Vera',
+            pm: 'Olivia',
+            devops: 'Diego',
+            researcher: 'Anika',
+            analyst: 'Liam',
+            designer: 'Sofia',
+            frontend: 'Mia',
+            architect: 'Marcus',
+        };
+        const known = tier1[slug];
+        if (known)
+            return known;
+        if (slug.length === 0)
+            return 'Engine';
+        return slug.charAt(0).toUpperCase() + slug.slice(1);
+    }
     recordSeenTag(signature) {
         this.seenTagSignatures.push(signature);
         while (this.seenTagSignatures.length > 32) {
@@ -3976,6 +4342,29 @@ function looksLikeMarkdown(text) {
     // 2+ bullets OR 2+ numbered OR any heading = group atomically.
     return bulletCount >= 2 || numberedCount >= 2 || headingCount >= 1;
 }
+/**
+ * PUGI-538b () — normalise a bridge-reported tool name onto
+ * the REPL's closed `ToolCallEntry['tool']` set. The engine surface
+ * has a wider tool registry (symbols.*, mcp_*, agent, …); the REPL
+ * pane only renders the seven canonical names. Unknown names return
+ * null so the bridge-event consumer skips the row instead of
+ * crashing on an out-of-set string.
+ */
+function normaliseBridgedToolName(name) {
+    const normalised = name.trim().toLowerCase();
+    switch (normalised) {
+        case 'read':
+        case 'write':
+        case 'edit':
+        case 'bash':
+        case 'grep':
+        case 'glob':
+        case 'web_fetch':
+            return normalised;
+        default:
+            return null;
+    }
+}
 function safePersonaName(role) {
     try {
         return getPersonaForRole(role).name;