@llm-dev-ops/agentics-cli 2.7.25 → 2.7.27

package/dist/cli/ui/heartbeat.js

@@ -0,0 +1,275 @@
+/**
+ * ADR-PIPELINE-099 D3 + D4 — Process-wide pipeline heartbeat.
+ *
+ * Singleton that emits a continuous "still alive" signal for the entire
+ * `agentics ask` lifecycle, not just Phase 1. Replaces the per-call heartbeat
+ * inside `executeNaturalLanguageRoute` which died as soon as auto-chain
+ * took over Phases 2–7, leaving the user staring at a silent terminal for
+ * minutes at a stretch.
+ *
+ * Two render modes:
+ *
+ *  - **TTY** (`stderr.isTTY` and not opted out): a single status line is
+ *    repainted in place every 250ms at the cursor position using a four-frame
+ *    spinner (`◐ ◓ ◑ ◒`). The line shows the current phase, total elapsed
+ *    time, time-since-phase-entry, and the most recent activity hint set by
+ *    the pipeline. Other writers (`console.error`, `process.stderr.write`)
+ *    print above the status line via cursor save/restore.
+ *
+ *  - **Non-TTY** (CI, piped output, `AGENTICS_NO_HEARTBEAT=1`): the spinner
+ *    is suppressed; instead a plain `[agentics] ⏳ still working — Phase X
+ *    (MM:SS) — <activity>` line prints every 10 seconds, throttled to skip
+ *    any tick that happened within 9s of another stderr write.
+ *
+ * The singleton is crash-safe: `process.on('exit' | 'SIGINT' | 'SIGTERM')`
+ * handlers call `stop()` to clear the live status line so it doesn't leave a
+ * stale frame on the user's terminal after Ctrl-C.
+ *
+ * Usage:
+ *   ```ts
+ *   import { pipelineHeartbeat } from './cli/ui/heartbeat.js';
+ *   pipelineHeartbeat.start('agentics ask');
+ *   pipelineHeartbeat.setPhase('Phase 4 — ADRs + DDDs');
+ *   pipelineHeartbeat.setActivity('ruflo: writing adr-007');
+ *   // ... long-running work ...
+ *   pipelineHeartbeat.stop();
+ *   ```
+ */
+const FRAMES = ['◐', '◓', '◑', '◒'];
+const TTY_FRAME_MS = 250;
+const PLAIN_TICK_MS = 10_000;
+const PLAIN_QUIET_THRESHOLD_MS = 9_000;
+const COLOR = {
+    reset: '\x1b[0m',
+    dim: '\x1b[2m',
+    cyan: '\x1b[36m',
+    gray: '\x1b[90m',
+};
+/** True when stderr is a TTY and the user has not opted out. */
+function isTtyEnabled() {
+    if (process.env['AGENTICS_NO_HEARTBEAT'] === '1')
+        return false;
+    if (process.env['AGENTICS_NO_LIVE'] === '1')
+        return false;
+    if (process.env['CI'])
+        return false;
+    if (process.env['NO_COLOR'])
+        return false;
+    return Boolean(process.stderr.isTTY);
+}
+function fmtElapsed(ms) {
+    const totalSec = Math.floor(ms / 1000);
+    const m = Math.floor(totalSec / 60);
+    const s = totalSec % 60;
+    return `${String(m).padStart(2, '0')}:${String(s).padStart(2, '0')}`;
+}
+class PipelineHeartbeat {
+    started = Date.now();
+    label = 'agentics';
+    phase = 'starting';
+    phaseStartedAt = Date.now();
+    activity = '';
+    activitySetAt = 0;
+    frameIndex = 0;
+    timer = null;
+    mode = 'off';
+    lastStderrWriteAt = Date.now();
+    statusLineRendered = false;
+    originalStderrWrite = null;
+    exitHandlersInstalled = false;
+    /**
+     * Begin emitting heartbeat ticks. Idempotent — repeated `start()` calls
+     * with a different label update the label but do not restart the timer.
+     */
+    start(label) {
+        this.label = label;
+        if (this.timer)
+            return;
+        // AGENTICS_HEARTBEAT_OFF=1 disables the singleton entirely (e.g. for
+        // tests or for users who pipe stderr to a file and don't want the
+        // periodic chatter). Default behaviour: tty mode if stderr is a tty,
+        // plain mode otherwise.
+        if (process.env['AGENTICS_HEARTBEAT_OFF'] === '1')
+            return;
+        this.mode = isTtyEnabled() ? 'tty' : 'plain';
+        this.installStderrInterceptor();
+        this.installExitHandlers();
+        if (this.mode === 'tty') {
+            this.timer = setInterval(() => this.tickTty(), TTY_FRAME_MS);
+        }
+        else {
+            this.timer = setInterval(() => this.tickPlain(), PLAIN_TICK_MS);
+        }
+        this.timer.unref();
+    }
+    /**
+     * Update the current phase label. Resets the per-phase timer. Called at
+     * every `[BEGIN]` boundary in auto-chain so the user can see which phase
+     * the pipeline is currently inside.
+     */
+    setPhase(phase) {
+        this.phase = phase;
+        this.phaseStartedAt = Date.now();
+        this.activity = '';
+        this.activitySetAt = 0;
+        if (this.mode === 'tty')
+            this.repaintTtyNow();
+    }
+    /**
+     * Update the latest activity hint. Examples: "ruflo: dispatching task adr-007",
+     * "fleet: 47/109 agents complete", "phase7: rendering decision-memo.md".
+     * Recent sets (within ~750ms) suppress the next TTY tick to avoid flicker.
+     */
+    setActivity(activity) {
+        this.activity = activity;
+        this.activitySetAt = Date.now();
+        if (this.mode === 'tty')
+            this.repaintTtyNow();
+    }
+    /** Stop the timer, clear the live status line, restore stderr. */
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        if (this.mode === 'tty' && this.statusLineRendered) {
+            this.clearStatusLine();
+        }
+        this.uninstallStderrInterceptor();
+        this.mode = 'off';
+    }
+    // ── Internal ─────────────────────────────────────────────────────────────
+    tickTty() {
+        // Auto-suppress flicker: if setActivity fired within the last 750ms, skip
+        // this tick — the activity-driven repaint already happened.
+        if (Date.now() - this.activitySetAt < 750 && this.activitySetAt > 0)
+            return;
+        this.frameIndex = (this.frameIndex + 1) % FRAMES.length;
+        this.paintStatusLine();
+    }
+    repaintTtyNow() {
+        this.frameIndex = (this.frameIndex + 1) % FRAMES.length;
+        this.paintStatusLine();
+    }
+    tickPlain() {
+        // Skip if some other writer just printed something — the user already
+        // has a fresh signal that we're alive.
+        if (Date.now() - this.lastStderrWriteAt < PLAIN_QUIET_THRESHOLD_MS)
+            return;
+        const elapsed = fmtElapsed(Date.now() - this.started);
+        const phaseSegment = this.phase ? `${this.phase} (${fmtElapsed(Date.now() - this.phaseStartedAt)})` : '';
+        const activitySegment = this.activity ? ` — ${this.activity}` : '';
+        const line = `[agentics] ⏳ still working — ${elapsed} — ${phaseSegment}${activitySegment}\n`;
+        this.writeRaw(line);
+    }
+    paintStatusLine() {
+        const frame = FRAMES[this.frameIndex];
+        const elapsedTotal = fmtElapsed(Date.now() - this.started);
+        const elapsedPhase = fmtElapsed(Date.now() - this.phaseStartedAt);
+        const phaseStr = `${COLOR.cyan}${this.phase}${COLOR.reset}`;
+        const elapsedStr = `${COLOR.dim}${elapsedTotal} total · ${elapsedPhase} phase${COLOR.reset}`;
+        const activityStr = this.activity ? ` ${COLOR.gray}·${COLOR.reset} ${this.activity}` : '';
+        const line = ` ${COLOR.cyan}${frame}${COLOR.reset} [${this.label}] ${phaseStr} ${COLOR.gray}·${COLOR.reset} ${elapsedStr}${activityStr}`;
+        this.clearStatusLine();
+        this.writeRaw(line);
+        this.statusLineRendered = true;
+    }
+    clearStatusLine() {
+        if (!this.statusLineRendered)
+            return;
+        // \r returns to column 0; \x1b[2K clears the entire line.
+        this.writeRaw('\r\x1b[2K');
+        this.statusLineRendered = false;
+    }
+    /**
+     * Wrap process.stderr.write so other writers (`console.error` etc.) clear
+     * the status line before printing, then we repaint after. This prevents
+     * the status line from being interleaved with normal log output in TTY
+     * mode. In plain mode the wrapper just records the timestamp so the 10s
+     * tick can self-suppress when other writes are happening.
+     */
+    installStderrInterceptor() {
+        if (this.originalStderrWrite)
+            return;
+        const stderr = process.stderr;
+        this.originalStderrWrite = stderr.write.bind(stderr);
+        const orig = this.originalStderrWrite;
+        const self = this;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        stderr.write = function (chunk, ...rest) {
+            self.lastStderrWriteAt = Date.now();
+            // If our own paint is in flight, just pass through.
+            if (self.mode !== 'tty') {
+                return orig(chunk, ...rest);
+            }
+            // For TTY: clear the status line, write the foreign output, repaint.
+            // We detect "our own writes" by a sentinel prefix — calls to writeRaw
+            // bypass this interceptor entirely.
+            if (self.statusLineRendered) {
+                orig('\r\x1b[2K');
+                self.statusLineRendered = false;
+            }
+            const ok = orig(chunk, ...rest);
+            // Defer repaint by one tick so chained writes (multi-line console.error)
+            // don't repaint between every line.
+            queueMicrotask(() => {
+                if (self.mode === 'tty' && !self.statusLineRendered && self.timer) {
+                    self.paintStatusLine();
+                }
+            });
+            return ok;
+        };
+    }
+    uninstallStderrInterceptor() {
+        if (!this.originalStderrWrite)
+            return;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        process.stderr.write = this.originalStderrWrite;
+        this.originalStderrWrite = null;
+    }
+    /** Bypass the interceptor — used for our own status-line paint/clear. */
+    writeRaw(s) {
+        const w = this.originalStderrWrite ?? process.stderr.write.bind(process.stderr);
+        w(s);
+    }
+    installExitHandlers() {
+        if (this.exitHandlersInstalled)
+            return;
+        this.exitHandlersInstalled = true;
+        const cleanup = () => this.stop();
+        process.on('exit', cleanup);
+        process.on('SIGINT', () => { cleanup(); process.exit(130); });
+        process.on('SIGTERM', () => { cleanup(); process.exit(143); });
+        process.on('uncaughtException', (err) => {
+            cleanup();
+            // Re-throw on next tick so default handler still prints + exits non-zero.
+            setImmediate(() => { throw err; });
+        });
+    }
+}
+/** Process-wide singleton. */
+export const pipelineHeartbeat = new PipelineHeartbeat();
+/**
+ * Bracket a phase with `[BEGIN]` / `[END]` log markers and update the
+ * heartbeat's phase label. Call at the top of each phase in auto-chain.
+ *
+ * Returns a `done()` closure that emits the matching `[END]` line when the
+ * phase finishes. Always pair `phaseBoundary` with its returned `done` to
+ * keep the trace greppable.
+ */
+export function phaseBoundary(phaseLabel, totalElapsedFromStart) {
+    const tStart = Date.now();
+    const t = fmtElapsed(totalElapsedFromStart);
+    pipelineHeartbeat.setPhase(phaseLabel);
+    // ANSI bold for the [BEGIN] marker so it stands out in scrollback.
+    process.stderr.write(`\n${'='.repeat(72)}\n` +
+        `  ▶ ${phaseLabel}                 [BEGIN]  T+${t}\n` +
+        `${'='.repeat(72)}\n`);
+    return () => {
+        const dur = fmtElapsed(Date.now() - tStart);
+        process.stderr.write(`${'='.repeat(72)}\n` +
+            `  ▼ ${phaseLabel}   ✓ completed (${dur})  [END]\n` +
+            `${'='.repeat(72)}\n\n`);
+    };
+}
+//# sourceMappingURL=heartbeat.js.map

package/dist/cli/ui/heartbeat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.js","sourceRoot":"","sources":["../../../src/cli/ui/heartbeat.ts"],"names":[],"mappings":"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"}

package/dist/commands/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/commands/agents.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/commands/agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAMxD,OAAO,EAAwB,KAAK,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AA2L/F,UAAU,WAAW;IACnB,WAAW,EAAE,WAAW,CAAC;IACzB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAwIrD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,MAAM,CAGtD,CAAC;AAEH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE9D;AAMD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACtG,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAMD,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,cAAc,GACvB,OAAO,CAAC,gBAAgB,CAAC,CAkB3B;AAED,wBAAsB,0BAA0B,CAC9C,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,kBAAkB,CAAC,CA0B7B;AAED,wBAAsB,0BAA0B,CAC9C,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,kBAAkB,CAAC,CAwgB7B;AA+zCD,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAgB3E;AAED,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAQ9E;AAMD,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,KAAK,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,UAAU,EAAE,kBAAkB,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,oBAAoB,EAAE,CAAC;IAChC,WAAW,EAAE,KAAK,CAAC;QACjB,MAAM,EAAE,oBAAoB,CAAC;QAC7B,MAAM,EAAE,kBAAkB,GAAG;YAAE,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC;KAChD,CAAC,CAAC;IACH;;;;OAIG;IACH,OAAO,CAAC,EAAE;QACR,UAAU,EAAE,sBAAsB,EAAE,CAAC;KACtC,CAAC;IACF;;;;OAIG;IACH,aAAa,CAAC,EAAE,mBAAmB,CAAC;IACpC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,0BAA0B,CAAA;CAAE,GACtD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,qBAAqB,CAAA;CAAE,CAAC;AAqGrD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,GACpB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkjDzB;AAMD,wBAAsB,2BAA2B,CAC/C,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,WAAW,CAAC,CAsoBtB;AAED,wBAAgB,oCAAoC,CAAC,MAAM,EAAE,0BAA0B,GAAG,MAAM,CAY/F;AAED,wBAAgB,+BAA+B,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,CAmDrF;AAED,wBAAgB,2BAA2B,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,CAK5E;AAED,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CA2BlF"}

package/dist/commands/agents.js

@@ -17,6 +17,7 @@ import { execFileSync } from 'node:child_process';
 import { isTransientFailure, isTerminalFailure } from '../errors/transient.js';
 import { recordDegradation, drainDegradations } from '../observability/degradations.js';
 import { computePhase1Verdict } from '../pipeline/phase1-verdict.js';
+import { pipelineHeartbeat } from '../cli/ui/heartbeat.js';
 // ============================================================================
 // ADR-066: Copilot agents via claude --print (Claude Max — no API key needed)
 // ============================================================================
@@ -3775,6 +3776,18 @@ export function buildDomainPayload(domain, agent, query, correlationId) {
 export async function executeNaturalLanguageRoute(query, options) {
     const start = Date.now();
     const correlationId = options.trace_id ?? crypto.randomUUID();
+    // Top-of-function entry banner — fires within microseconds of dispatch so
+    // the user sees the route is executing even if subsequent operations
+    // (graph load, ruvector simulation, fleet dispatch) take a while.
+    process.stderr.write(`[agentics] route entered — query="${query.slice(0, 100)}${query.length > 100 ? '…' : ''}" depth=${options.depth ?? 'lite'} trace=${correlationId.slice(0, 8)}\n`);
+    // ADR-PIPELINE-099 D3 — process-wide heartbeat. Survives across the
+    // executeNaturalLanguageRoute → executeAutoChain handoff (the previous
+    // per-call heartbeat died at the function boundary, leaving Phases 2–7
+    // silent for minutes at a time). Idempotent — auto-chain calls start()
+    // again with no effect. Stop happens at the end of executeAutoChain or
+    // via the singleton's exit handlers.
+    pipelineHeartbeat.start('agentics ask');
+    pipelineHeartbeat.setPhase('Phase 1 — Fleet Dispatch + Simulation');
     // ========================================================================
     // ADR-030: Capability Graph Routing
     //
@@ -3817,6 +3830,7 @@ export async function executeNaturalLanguageRoute(query, options) {
                 console.error(graphResult.routing.explanation);
                 // Run ruvector simulation first (same as full-fleet path, ADR-016)
                 console.error('  [RUVECTOR] Running simulation before graph-routed dispatch (ADR-016)...');
+                pipelineHeartbeat.setActivity(`ruvector: simulating ${graphResult.routing.totalAgents}-agent graph route`);
                 const simResult = await (async () => {
                     const MAX_RETRIES = 3;
                     let lastErr;
@@ -3855,6 +3869,7 @@ export async function executeNaturalLanguageRoute(query, options) {
                 const REPO_LOCAL_DOMAINS = new Set(['copilot']);
                 const prevLocalAgents = process.env['AGENTICS_LOCAL_AGENTS'];
                 console.error(`  Dispatching ${graphResult.agents.length} graph-routed agents...`);
+                pipelineHeartbeat.setActivity(`fleet: dispatching ${graphResult.agents.length} graph-routed agents`);
                 const agentPromises = [];
                 for (const ref of graphResult.agents) {
                     agentPromises.push((async () => {
@@ -4165,6 +4180,7 @@ export async function executeNaturalLanguageRoute(query, options) {
             { domain: 'platform', agent: 'risk-score' },
         ];
         console.error(`Dispatching ${fleetAgents.length} agents across ALL 27 domains + ruvector simulation`);
+        pipelineHeartbeat.setActivity(`fleet: dispatching ${fleetAgents.length} agents across 27 domains`);
         // ========================================================================
         // ADR-016: Run ruvector simulation BEFORE fleet dispatch (sequential).
         //
@@ -4177,6 +4193,7 @@ export async function executeNaturalLanguageRoute(query, options) {
         // start the fleet. Adds ~5s latency but guarantees simulation success.
         // ========================================================================
         console.error('  [RUVECTOR] Running simulation before fleet dispatch (ADR-016)...');
+        pipelineHeartbeat.setActivity('ruvector: pre-fleet simulation');
         const simResult = await (async () => {
             const MAX_RETRIES = 3;
             let lastErr;