@moda-ai/cli 1.15.1 → 1.17.0

package/dist/api-client.d.ts

@@ -4,6 +4,16 @@ export declare class ApiError extends Error {
     readonly responseBody: string;
     constructor(message: string, statusCode: number, responseBody: string);
 }
+/**
+ * Transport-level failure: the socket died before any HTTP response existed
+ * (`fetch failed`, ECONNRESET, …). Distinct from `ApiError` (an HTTP status)
+ * and from the per-attempt timeout so callers can retry ONLY genuine network
+ * faults — e.g. undici handing out a pooled connection poisoned by a
+ * just-dropped SSE stream on the same origin.
+ */
+export declare class NetworkError extends Error {
+    constructor(message: string);
+}
 export declare function callDataAPI(endpoint: string): Promise<unknown>;
 /**
  * Per-call transport overrides. Used by expensive, long-running, non-idempotent
@@ -15,6 +25,20 @@ export interface ModaRequestOptions {
     timeoutMs?: number;
     /** Max retries (default MAX_RETRIES). Set 0 to disable retries entirely. */
     retries?: number;
+    /**
+     * Retry exactly once more on a NETWORK-level failure, even with `retries: 0`.
+     * After a streamed SSE connection dies, undici's per-origin pool can hand
+     * the very next fetch the same dead socket — the buffered fallback then
+     * fails instantly ("fetch failed") against a healthy backend. The retry
+     * waits ~1s and sends `Connection: close` so it cannot reuse a pooled
+     * connection. HTTP errors (`ApiError`) and the per-attempt timeout NEVER
+     * consume this retry.
+     */
+    retryOnceOnNetworkError?: boolean;
+    /** Delay before the network retry (default 1s; test seam). */
+    networkRetryDelayMs?: number;
+    /** Invoked when the network retry is consumed (callers may log a note). */
+    onNetworkRetry?: () => void;
 }
 export declare function callControlAPI(endpoint: string, options?: RequestInit, profileOptions?: ProfileIOOptions, requestOptions?: ModaRequestOptions): Promise<unknown>;
 export declare function getApiRequestCount(): number;

package/dist/api-client.js

@@ -3,6 +3,7 @@ import { resolveApiKey, resolveModaBaseUrl } from './config.js';
 const REQUEST_TIMEOUT_MS = 30_000;
 const MAX_RETRIES = 3;
 const INITIAL_BACKOFF_MS = 500;
+const NETWORK_RETRY_DELAY_MS = 1_000;
 let apiRequestCount = 0;
 export class ApiError extends Error {
     statusCode;
@@ -14,6 +15,19 @@ export class ApiError extends Error {
         this.name = 'ApiError';
     }
 }
+/**
+ * Transport-level failure: the socket died before any HTTP response existed
+ * (`fetch failed`, ECONNRESET, …). Distinct from `ApiError` (an HTTP status)
+ * and from the per-attempt timeout so callers can retry ONLY genuine network
+ * faults — e.g. undici handing out a pooled connection poisoned by a
+ * just-dropped SSE stream on the same origin.
+ */
+export class NetworkError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NetworkError';
+    }
+}
 function isRetryable(status) {
     return status === 429 || status >= 500;
 }
@@ -29,10 +43,23 @@ export async function callControlAPI(endpoint, options = {}, profileOptions = {}
 async function callModaAPI(url, options, profileOptions = {}, requestOptions = {}) {
     const timeoutMs = requestOptions.timeoutMs ?? REQUEST_TIMEOUT_MS;
     const maxRetries = requestOptions.retries ?? MAX_RETRIES;
-    let lastError;
-    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const initialNetworkRetryBudget = requestOptions.retryOnceOnNetworkError
+        ? 1
+        : 0;
+    let networkRetryBudget = initialNetworkRetryBudget;
+    // Set once the network-retry budget is consumed: the retry attempt (and any
+    // later ones) must not reuse a possibly-poisoned pooled connection.
+    let connectionClose = false;
+    // Structural termination bound: (maxRetries + 1) normal attempts plus at most
+    // one extra network-retry attempt. Every path inside returns, throws, or
+    // `continue`s, so the trailing throw is unreachable — but the bound makes the
+    // contract hold by construction rather than by manual path analysis.
+    const maxAttempts = maxRetries + initialNetworkRetryBudget + 1;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
         if (attempt > 0) {
-            const backoff = INITIAL_BACKOFF_MS * Math.pow(2, attempt - 1);
+            const backoff = connectionClose
+                ? requestOptions.networkRetryDelayMs ?? NETWORK_RETRY_DELAY_MS
+                : INITIAL_BACKOFF_MS * Math.pow(2, attempt - 1);
             await new Promise((resolve) => setTimeout(resolve, backoff));
         }
         const controller = new AbortController();
@@ -44,6 +71,7 @@ async function callModaAPI(url, options, profileOptions = {}, requestOptions = {
                     'x-api-key': resolveApiKey(profileOptions) ?? '',
                     'Content-Type': 'application/json',
                     ...(options.headers ?? {}),
+                    ...(connectionClose ? { Connection: 'close' } : {}),
                 },
                 signal: controller.signal,
             });
@@ -51,7 +79,6 @@ async function callModaAPI(url, options, profileOptions = {}, requestOptions = {
                 const errorText = await response.text();
                 const error = new ApiError(`API error (${response.status}): ${errorText}`, response.status, errorText);
                 if (isRetryable(response.status) && attempt < maxRetries) {
-                    lastError = error;
                     continue;
                 }
                 throw error;
@@ -62,11 +89,16 @@ async function callModaAPI(url, options, profileOptions = {}, requestOptions = {
             if (error instanceof ApiError)
                 throw error;
             const isAbort = error instanceof DOMException && error.name === 'AbortError';
-            const wrapped = new Error(isAbort
-                ? `Request timed out after ${timeoutMs}ms: ${url}`
-                : `Network error: ${error instanceof Error ? error.message : String(error)}`);
+            const wrapped = isAbort
+                ? new Error(`Request timed out after ${timeoutMs}ms: ${url}`)
+                : new NetworkError(`Network error: ${error instanceof Error ? error.message : String(error)}`);
             if (attempt < maxRetries) {
-                lastError = wrapped;
+                continue;
+            }
+            if (!isAbort && networkRetryBudget > 0) {
+                networkRetryBudget -= 1;
+                connectionClose = true;
+                requestOptions.onNetworkRetry?.();
                 continue;
             }
             throw wrapped;
@@ -75,7 +107,9 @@ async function callModaAPI(url, options, profileOptions = {}, requestOptions = {
             clearTimeout(timeout);
         }
     }
-    throw lastError ?? new Error('Request failed after retries');
+    // Unreachable: the loop above always returns or throws within maxAttempts.
+    // Present so the bound is enforced by construction, not just documented.
+    throw new NetworkError(`Request retries exhausted: ${url}`);
 }
 export function getApiRequestCount() {
     return apiRequestCount;

package/dist/ask-stream.d.ts

@@ -25,8 +25,29 @@ export interface AskStreamOutcome {
 }
 /** Signals "fall back to the buffered ask endpoint" — never surfaced raw. */
 export declare class AskStreamError extends Error {
+    /** Wall-clock ms the stream ran before failing (annotated by `streamAsk`). */
+    elapsedMs?: number;
+    /** tool_start/tool_end events seen before failing (annotated by `streamAsk`). */
+    toolEvents?: number;
     constructor(message: string);
 }
+/**
+ * Thresholds for "substantial progress": a stream that ran at least this long,
+ * or produced more tool events than this, did real work before dropping —
+ * the buffered fallback then re-runs the WHOLE question, roughly doubling
+ * total latency, so the user deserves a notice instead of silence. The elapsed
+ * check is inclusive (`>=`) so a drop landing exactly on the boundary — where
+ * the doubled wait is felt most acutely — still gets the notice.
+ */
+export declare const SUBSTANTIAL_STREAM_PROGRESS_MS = 60000;
+export declare const SUBSTANTIAL_STREAM_TOOL_EVENTS = 5;
+/**
+ * One-line stderr notice for a stream that died after substantial progress.
+ * Returns null for early failures (they keep today's silent fallback) and for
+ * non-stream errors. The caller still falls back either way — the user must
+ * still get an answer, just an informed wait instead of an apparent hang.
+ */
+export declare function streamFallbackNotice(error: unknown): string | null;
 /**
  * Incremental SSE frame parser. Feed decoded text chunks (arbitrarily split —
  * even mid `data:` line or mid multi-byte frame); complete `data:` payloads
@@ -40,6 +61,33 @@ export declare class SseParser {
     /** Drain a final frame that was not terminated by a blank line. */
     flush(): string[];
 }
+/** Quiet period before the first liveness line is printed. */
+export declare const IDLE_TICKER_THRESHOLD_MS = 10000;
+/** Minimum spacing between liveness lines. */
+export declare const IDLE_TICKER_MIN_UPDATE_MS = 15000;
+/**
+ * Client-side liveness for quiet stream periods: long tool-less LLM turns
+ * (coverage gate, synthesis) emit no events for 30–90s, which reads as a
+ * hang. Once no event has arrived for IDLE_TICKER_THRESHOLD_MS this prints an
+ * unobtrusive "… still working (Ns)" line (at most every
+ * IDLE_TICKER_MIN_UPDATE_MS) through the same progress channel as tool cards —
+ * stderr only, never interleaved into the final answer.
+ */
+export declare class IdleTicker {
+    private readonly write;
+    private readonly now;
+    private startedAt;
+    private lastEventAt;
+    private lastPrintAt;
+    private timer;
+    constructor(write: (line: string) => void, now?: () => number);
+    start(): void;
+    /** Reset the idle clock — call on every real stream event. */
+    touch(): void;
+    stop(): void;
+    /** One liveness check; driven by the interval (public for tests). */
+    poll(): void;
+}
 /**
  * Consumes parsed stream events: renders live progress lines through
  * `onProgress` and accumulates the final outcome. `finish()` throws
@@ -58,9 +106,12 @@ export declare class AskStreamCollector {
     private terminal;
     private lastPhase;
     private toolNames;
+    private toolEvents;
     constructor(onProgress?: (line: string) => void);
     handle(raw: unknown): void;
     isTerminal(): boolean;
+    /** tool_start/tool_end events seen so far (fallback-heuristic input). */
+    get toolEventCount(): number;
     finish(): AskStreamOutcome;
 }
 /**
@@ -68,7 +119,12 @@ export declare class AskStreamCollector {
  * parser into the collector. Exported separately from `streamAsk` so tests can
  * exercise chunk-splitting behavior without a network layer.
  */
-export declare function consumeAskSse(chunks: AsyncIterable<Uint8Array | string>, collector: AskStreamCollector): Promise<AskStreamOutcome>;
+export declare function consumeAskSse(chunks: AsyncIterable<Uint8Array | string>, collector: AskStreamCollector, 
+/**
+ * Fires once per parsed `data:` event (keepalive comment frames never reach
+ * it). Used to reset the idle liveness ticker on real progress.
+ */
+onEvent?: () => void): Promise<AskStreamOutcome>;
 export interface StreamAskOptions {
     question: string;
     daysBack: number;

package/dist/ask-stream.js

@@ -13,13 +13,46 @@
 // failure: it is returned as an outcome (`errorMessage`) and rendered the same
 // way buffered agent errors render.
 import { resolveApiKey, resolveModaBaseUrl } from './config.js';
+import { stripAnsi } from './markdown-terminal.js';
 /** Signals "fall back to the buffered ask endpoint" — never surfaced raw. */
 export class AskStreamError extends Error {
+    /** Wall-clock ms the stream ran before failing (annotated by `streamAsk`). */
+    elapsedMs;
+    /** tool_start/tool_end events seen before failing (annotated by `streamAsk`). */
+    toolEvents;
     constructor(message) {
         super(message);
         this.name = 'AskStreamError';
     }
 }
+/**
+ * Thresholds for "substantial progress": a stream that ran at least this long,
+ * or produced more tool events than this, did real work before dropping —
+ * the buffered fallback then re-runs the WHOLE question, roughly doubling
+ * total latency, so the user deserves a notice instead of silence. The elapsed
+ * check is inclusive (`>=`) so a drop landing exactly on the boundary — where
+ * the doubled wait is felt most acutely — still gets the notice.
+ */
+export const SUBSTANTIAL_STREAM_PROGRESS_MS = 60_000;
+export const SUBSTANTIAL_STREAM_TOOL_EVENTS = 5;
+/**
+ * One-line stderr notice for a stream that died after substantial progress.
+ * Returns null for early failures (they keep today's silent fallback) and for
+ * non-stream errors. The caller still falls back either way — the user must
+ * still get an answer, just an informed wait instead of an apparent hang.
+ */
+export function streamFallbackNotice(error) {
+    if (!(error instanceof AskStreamError))
+        return null;
+    const elapsedMs = error.elapsedMs ?? 0;
+    const toolEvents = error.toolEvents ?? 0;
+    if (elapsedMs < SUBSTANTIAL_STREAM_PROGRESS_MS &&
+        toolEvents <= SUBSTANTIAL_STREAM_TOOL_EVENTS) {
+        return null;
+    }
+    return (`stream interrupted after ${Math.round(elapsedMs / 1000)}s; ` +
+        'retrying via buffered request — this may take another minute or two.');
+}
 /**
  * Incremental SSE frame parser. Feed decoded text chunks (arbitrarily split —
  * even mid `data:` line or mid multi-byte frame); complete `data:` payloads
@@ -73,6 +106,68 @@ function dataPayloadOf(frame) {
 }
 /** Phases worth a human status line (terminal/idle phases are omitted). */
 const RENDERED_PHASES = new Set(['planning', 'searching', 'analyzing', 'writing']);
+// ─── Idle liveness ticker ────────────────────────────────────
+/** Quiet period before the first liveness line is printed. */
+export const IDLE_TICKER_THRESHOLD_MS = 10_000;
+/** Minimum spacing between liveness lines. */
+export const IDLE_TICKER_MIN_UPDATE_MS = 15_000;
+const IDLE_TICKER_POLL_MS = 1_000;
+/**
+ * Client-side liveness for quiet stream periods: long tool-less LLM turns
+ * (coverage gate, synthesis) emit no events for 30–90s, which reads as a
+ * hang. Once no event has arrived for IDLE_TICKER_THRESHOLD_MS this prints an
+ * unobtrusive "… still working (Ns)" line (at most every
+ * IDLE_TICKER_MIN_UPDATE_MS) through the same progress channel as tool cards —
+ * stderr only, never interleaved into the final answer.
+ */
+export class IdleTicker {
+    write;
+    now;
+    startedAt;
+    lastEventAt;
+    lastPrintAt = 0;
+    timer;
+    constructor(write, now = Date.now) {
+        this.write = write;
+        this.now = now;
+        this.startedAt = this.now();
+        this.lastEventAt = this.startedAt;
+    }
+    start() {
+        if (this.timer)
+            return;
+        this.startedAt = this.now();
+        this.lastEventAt = this.startedAt;
+        this.timer = setInterval(() => this.poll(), IDLE_TICKER_POLL_MS);
+        // Never hold the process open for a liveness timer.
+        this.timer.unref?.();
+    }
+    /** Reset the idle clock — call on every real stream event. */
+    touch() {
+        this.lastEventAt = this.now();
+    }
+    stop() {
+        if (this.timer !== undefined)
+            clearInterval(this.timer);
+        this.timer = undefined;
+    }
+    /** One liveness check; driven by the interval (public for tests). */
+    poll() {
+        const at = this.now();
+        if (at - this.lastEventAt < IDLE_TICKER_THRESHOLD_MS)
+            return;
+        if (this.lastPrintAt !== 0 && at - this.lastPrintAt < IDLE_TICKER_MIN_UPDATE_MS)
+            return;
+        this.lastPrintAt = at;
+        const secs = Math.round((at - this.startedAt) / 1000);
+        try {
+            this.write(`… still working (${secs}s)`);
+        }
+        catch {
+            /* a liveness line must never break the stream */
+        }
+    }
+}
 /**
  * Consumes parsed stream events: renders live progress lines through
  * `onProgress` and accumulates the final outcome. `finish()` throws
@@ -91,6 +186,7 @@ export class AskStreamCollector {
     terminal = false;
     lastPhase;
     toolNames = new Map();
+    toolEvents = 0;
     constructor(onProgress = () => { }) {
         this.onProgress = onProgress;
     }
@@ -110,20 +206,35 @@ export class AskStreamCollector {
                 }
                 break;
             }
-            case 'thinking':
-                // Model narration is too chatty for one-line terminal progress; skip.
+            case 'thinking': {
+                // Model narration (`t<N>` ids) is too chatty for one-line terminal
+                // progress and stays hidden. Deliberation status lines the backend
+                // emits on purpose ('plan', 'gate-*': multi-part plan, coverage
+                // checks, nudge cycles) are concise and cover otherwise-silent LLM
+                // calls — render them like tool cards so the gate never reads as a hang.
+                const id = typeof event.id === 'string' ? event.id : '';
+                if (id === 'plan' || id.startsWith('gate-')) {
+                    const delta = typeof event.delta === 'string' ? event.delta : '';
+                    if (delta.trim().length > 0)
+                        this.onProgress(`◦ ${oneLine(delta)}`);
+                }
                 break;
+            }
             case 'tool_start': {
+                this.toolEvents += 1;
                 const tool = event.tool;
                 const id = typeof tool?.id === 'string' ? tool.id : '';
-                const name = typeof tool?.tool === 'string' ? tool.tool : 'tool';
-                const title = typeof tool?.title === 'string' ? tool.title : name;
+                // Backend-controlled strings — strip ANSI so a rogue/compromised backend
+                // (or prompt-injected LLM output) can't inject terminal control sequences.
+                const name = stripAnsi(typeof tool?.tool === 'string' ? tool.tool : 'tool');
+                const title = stripAnsi(typeof tool?.title === 'string' ? tool.title : name);
                 if (id)
                     this.toolNames.set(id, name);
                 this.onProgress(`• ${name} — ${title}…`);
                 break;
             }
             case 'tool_end': {
+                this.toolEvents += 1;
                 const id = typeof event.id === 'string' ? event.id : '';
                 const name = this.toolNames.get(id) ?? 'tool';
                 this.onProgress(`• ${name} — ${toolEndDetail(event)}`);
@@ -165,6 +276,10 @@ export class AskStreamCollector {
     isTerminal() {
         return this.terminal;
     }
+    /** tool_start/tool_end events seen so far (fallback-heuristic input). */
+    get toolEventCount() {
+        return this.toolEvents;
+    }
     finish() {
         if (!this.terminal) {
             throw new AskStreamError('stream ended before a terminal done/error event');
@@ -191,7 +306,9 @@ export class AskStreamCollector {
  */
 const TOOL_CARD_DETAIL_MAX = 100;
 function oneLine(text) {
-    const collapsed = text.replace(/\s+/g, ' ').trim();
+    // Strip ANSI first: the source is backend-controlled tool summaries/errors,
+    // and ESC bytes survive the whitespace collapse below.
+    const collapsed = stripAnsi(text).replace(/\s+/g, ' ').trim();
     return collapsed.length > TOOL_CARD_DETAIL_MAX
         ? `${collapsed.slice(0, TOOL_CARD_DETAIL_MAX - 1)}…`
         : collapsed;
@@ -241,19 +358,26 @@ function normalizeStreamConfidence(value) {
  * parser into the collector. Exported separately from `streamAsk` so tests can
  * exercise chunk-splitting behavior without a network layer.
  */
-export async function consumeAskSse(chunks, collector) {
+export async function consumeAskSse(chunks, collector, 
+/**
+ * Fires once per parsed `data:` event (keepalive comment frames never reach
+ * it). Used to reset the idle liveness ticker on real progress.
+ */
+onEvent) {
     const parser = new SseParser();
     const decoder = new TextDecoder();
     for await (const chunk of chunks) {
         const text = typeof chunk === 'string' ? chunk : decoder.decode(chunk, { stream: true });
         for (const payload of parser.push(text)) {
             collector.handle(parsePayload(payload));
+            onEvent?.();
             if (collector.isTerminal())
                 return collector.finish();
         }
     }
     for (const payload of parser.flush()) {
         collector.handle(parsePayload(payload));
+        onEvent?.();
         if (collector.isTerminal())
             return collector.finish();
     }
@@ -279,6 +403,13 @@ export async function streamAsk(options) {
     const url = `${resolveModaBaseUrl(profileOptions)}/api/cli/ask/stream`;
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? DEFAULT_STREAM_TIMEOUT_MS);
+    const startedAt = Date.now();
+    const onProgress = options.onProgress ?? (() => { });
+    const collector = new AskStreamCollector(onProgress);
+    // Liveness lines share the progress channel (stderr in the CLI), so they
+    // can never interleave into the final stdout answer.
+    const ticker = new IdleTicker(onProgress);
+    ticker.start();
     try {
         const fetchImpl = options.fetchImpl ?? fetch;
         let response;
@@ -313,9 +444,8 @@ export async function streamAsk(options) {
         if (!response.body) {
             throw new AskStreamError('stream response had no body');
         }
-        const collector = new AskStreamCollector(options.onProgress);
         try {
-            return await consumeAskSse(response.body, collector);
+            return await consumeAskSse(response.body, collector, () => ticker.touch());
         }
         catch (error) {
             if (error instanceof AskStreamError)
@@ -323,7 +453,20 @@ export async function streamAsk(options) {
             throw new AskStreamError(`stream read failed: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
+    catch (error) {
+        // Annotate stream failures with how far the run got, so the caller can
+        // decide between today's silent fallback (early drop) and an informed
+        // one (drop after substantial progress). See `streamFallbackNotice`.
+        if (error instanceof AskStreamError) {
+            if (error.elapsedMs === undefined)
+                error.elapsedMs = Date.now() - startedAt;
+            if (error.toolEvents === undefined)
+                error.toolEvents = collector.toolEventCount;
+        }
+        throw error;
+    }
     finally {
+        ticker.stop();
         clearTimeout(timeout);
     }
 }

package/dist/markdown-terminal.d.ts

@@ -0,0 +1,49 @@
+export interface MarkdownTerminalOptions {
+    /** When false, all structural fixes still apply but zero ANSI codes are emitted. */
+    color: boolean;
+}
+/** Minimal ANSI styling helpers shared by the renderer and ask chrome. */
+export interface TerminalStyles {
+    bold(text: string): string;
+    italic(text: string): string;
+    dim(text: string): string;
+    code(text: string): string;
+    /** Section heading: bold + underline. */
+    heading(text: string): string;
+}
+/**
+ * The CLI's color convention (mirrors `src/tui.ts` / `src/analyst-tui.ts`):
+ * color only for a human at a TTY, honoring `NO_COLOR` (present with ANY value,
+ * including the empty string, disables — per the no-color.org spec) and
+ * `TERM=dumb`.
+ */
+export declare function shouldColorTerminalOutput(opts?: {
+    isTTY?: boolean;
+    env?: NodeJS.ProcessEnv;
+}): boolean;
+/**
+ * ANSI style constructors. Closers restore the specific attribute (22/23/39)
+ * rather than a full reset so nested styles (code inside bold, bold inside a
+ * heading) survive. When `color` is false every helper is the identity.
+ */
+export declare function terminalStyles(color: boolean): TerminalStyles;
+/** Remove ANSI/OSC control sequences from untrusted content. */
+export declare function stripAnsi(text: string): string;
+/**
+ * Render an agent markdown answer for direct terminal display.
+ *
+ * - Headers lose their `#` sigils; h1/h2 render bold+underlined, h3+ bold,
+ *   with a blank line before.
+ * - `**bold**`, `*italic*`/`_italic_`, and backtick `code` spans lose their
+ *   sigils and gain ANSI styling (bold / italic / cyan) when `color` is on.
+ * - List items are re-indented to consistent 2-space-per-level steps based on
+ *   their original RELATIVE nesting (odd indents round to the nearest level; a
+ *   top-level-looking item after deeper items stays top-level). Bullets render
+ *   `•` at level 0 and `-` deeper; ordered items keep their numbers.
+ * - `|` table rows and fenced code blocks pass through untouched (only ANSI
+ *   control sequences are stripped, since that content is backend-controlled).
+ * - Runs of 3+ blank lines collapse to a single blank line.
+ * - Prose is never reflowed or wrapped.
+ */
+export declare function renderMarkdownForTerminal(markdown: string, opts: MarkdownTerminalOptions): string;
+//# sourceMappingURL=markdown-terminal.d.ts.map

package/dist/markdown-terminal.js

@@ -0,0 +1,212 @@
+// src/markdown-terminal.ts
+//
+// Pure markdown -> terminal renderer for human-mode output (`moda ask`).
+// The cloud agent answers in markdown; printing it raw leaves literal `##`
+// header sigils, `**bold**` asterisks, and the model's erratic list
+// indentation on screen. This module strips the sigils, applies ANSI styling
+// when the terminal supports it, and normalizes list nesting to consistent
+// 2-space steps — WITHOUT reflowing prose (terminals wrap themselves) and
+// WITHOUT touching `|` tables or fenced code blocks.
+//
+// No dependencies: raw ANSI escape constants only (the CLI has no color lib).
+/**
+ * The CLI's color convention (mirrors `src/tui.ts` / `src/analyst-tui.ts`):
+ * color only for a human at a TTY, honoring `NO_COLOR` (present with ANY value,
+ * including the empty string, disables — per the no-color.org spec) and
+ * `TERM=dumb`.
+ */
+export function shouldColorTerminalOutput(opts = {}) {
+    const env = opts.env ?? process.env;
+    const isTTY = opts.isTTY ?? process.stdout.isTTY === true;
+    if (!isTTY)
+        return false;
+    if (env.NO_COLOR !== undefined)
+        return false;
+    if (env.TERM === 'dumb')
+        return false;
+    return true;
+}
+/**
+ * ANSI style constructors. Closers restore the specific attribute (22/23/39)
+ * rather than a full reset so nested styles (code inside bold, bold inside a
+ * heading) survive. When `color` is false every helper is the identity.
+ */
+export function terminalStyles(color) {
+    const paint = (open, close) => (text) => color ? `\u001b[${open}m${text}\u001b[${close}m` : text;
+    return {
+        bold: paint('1', '22'),
+        italic: paint('3', '23'),
+        dim: paint('2', '22'),
+        code: paint('36', '39'),
+        heading: paint('1;4', '22;24'),
+    };
+}
+const FENCE_RE = /^\s*(`{3,}|~{3,})/;
+const FENCE_CLOSE_RE = /^\s*(`{3,}|~{3,})\s*$/;
+const TABLE_ROW_RE = /^\s*\|.*\S/;
+// Matches ANSI/OSC control sequences: CSI (ESC [ … final byte), OSC (ESC ] …
+// BEL or ST), and other two-byte escapes. Backend-controlled content (table
+// cells, code-fence bodies, streamed tool names/titles) is passed through
+// verbatim, so any escape sequences an LLM or a compromised backend emits must
+// be stripped before they reach the terminal — otherwise they could clear the
+// screen, spoof UI, or trigger OSC side-effects in some emulators.
+const ANSI_RE = /\u001b(?:\[[0-9;?]*[ -/]*[@-~]|\][^\u0007\u001b]*(?:\u0007|\u001b\\)|[@-Z\\-_])/g;
+/** Remove ANSI/OSC control sequences from untrusted content. */
+export function stripAnsi(text) {
+    return text.replace(ANSI_RE, '');
+}
+/**
+ * A fenced code block's opening marker: the fence character (`` ` `` or `~`)
+ * and its length. CommonMark closes a fence only with the same character and at
+ * least as many markers, so tracking these prevents a `~~~` line from closing a
+ * ` ``` ` block (and a 3-backtick line from closing a 4-backtick opener).
+ */
+function parseFenceOpen(line) {
+    const match = FENCE_RE.exec(line);
+    if (!match)
+        return null;
+    return { char: match[1][0], len: match[1].length };
+}
+/** Whether `line` closes an open fence per the CommonMark same-char/length rule. */
+function isFenceClose(line, fence) {
+    const match = FENCE_CLOSE_RE.exec(line);
+    return match !== null && match[1][0] === fence.char && match[1].length >= fence.len;
+}
+const HEADER_RE = /^(#{1,6})\s+(.*?)\s*#*\s*$/;
+const BULLET_RE = /^(\s*)([-*+])\s+(.*)$/;
+const ORDERED_RE = /^(\s*)(\d+)[.)]\s+(.*)$/;
+/**
+ * Render an agent markdown answer for direct terminal display.
+ *
+ * - Headers lose their `#` sigils; h1/h2 render bold+underlined, h3+ bold,
+ *   with a blank line before.
+ * - `**bold**`, `*italic*`/`_italic_`, and backtick `code` spans lose their
+ *   sigils and gain ANSI styling (bold / italic / cyan) when `color` is on.
+ * - List items are re-indented to consistent 2-space-per-level steps based on
+ *   their original RELATIVE nesting (odd indents round to the nearest level; a
+ *   top-level-looking item after deeper items stays top-level). Bullets render
+ *   `•` at level 0 and `-` deeper; ordered items keep their numbers.
+ * - `|` table rows and fenced code blocks pass through untouched (only ANSI
+ *   control sequences are stripped, since that content is backend-controlled).
+ * - Runs of 3+ blank lines collapse to a single blank line.
+ * - Prose is never reflowed or wrapped.
+ */
+export function renderMarkdownForTerminal(markdown, opts) {
+    const style = terminalStyles(opts.color);
+    const out = [];
+    // Original indent width backing each active list level; index == level.
+    const listStack = [];
+    // The open fence's char + length, or null outside a fenced code block.
+    let fence = null;
+    for (const raw of markdown.replace(/\r\n/g, '\n').split('\n')) {
+        if (fence) {
+            out.push(stripAnsi(raw));
+            if (isFenceClose(raw, fence))
+                fence = null;
+            continue;
+        }
+        const opened = parseFenceOpen(raw);
+        if (opened) {
+            fence = opened;
+            listStack.length = 0;
+            out.push(stripAnsi(raw));
+            continue;
+        }
+        if (TABLE_ROW_RE.test(raw)) {
+            // Tables depend on exact column spacing — pass through monospaced.
+            out.push(stripAnsi(raw));
+            continue;
+        }
+        const line = raw.replace(/\s+$/, '');
+        if (line === '') {
+            out.push('');
+            continue;
+        }
+        const header = HEADER_RE.exec(line);
+        if (header) {
+            listStack.length = 0;
+            // Strip inline sigils inside the header text (plain), then style the
+            // whole line so nested `**bold**` can't fight the heading attributes.
+            const text = renderInline(header[2], terminalStyles(false));
+            if (out.length > 0 && out[out.length - 1] !== '')
+                out.push('');
+            out.push(header[1].length <= 2 ? style.heading(text) : style.bold(text));
+            continue;
+        }
+        const bullet = BULLET_RE.exec(line);
+        const ordered = bullet ? null : ORDERED_RE.exec(line);
+        if (bullet || ordered) {
+            const match = (bullet ?? ordered);
+            const level = resolveListLevel(match[1].length, listStack);
+            const indent = '  '.repeat(level);
+            const text = renderInline(match[3], style);
+            if (bullet) {
+                out.push(`${indent}${level === 0 ? '•' : '-'} ${text}`);
+            }
+            else {
+                out.push(`${indent}${match[2]}. ${text}`);
+            }
+            continue;
+        }
+        // Unindented prose ends any open list; indented non-list lines are treated
+        // as continuations and keep the current nesting context.
+        if (!/^\s{2,}/.test(line))
+            listStack.length = 0;
+        out.push(renderInline(line, style));
+    }
+    return collapseBlankRuns(out).join('\n');
+}
+/**
+ * Map an item's original indent width onto a consistent nesting level.
+ * `stack[level]` remembers the original indent that opened that level:
+ * meaningfully shallower indents pop back out, meaningfully deeper indents
+ * open a new level, and anything within +/-1 space sticks to the current
+ * level (rounding the model's odd 3/5/7-space indents to the nearest level).
+ */
+function resolveListLevel(indent, stack) {
+    while (stack.length > 0 && indent < stack[stack.length - 1] - 1)
+        stack.pop();
+    if (stack.length === 0 || indent > stack[stack.length - 1] + 1)
+        stack.push(indent);
+    return stack.length - 1;
+}
+/**
+ * Strip/style inline markdown sigils: `code` spans first (protected via
+ * placeholders so asterisks/underscores inside them are never re-parsed),
+ * then `**bold**`/`__bold__`, then word-boundary `*italic*`/`_italic_`
+ * (mid-word underscores as in `silent_empty_result` never match).
+ */
+function renderInline(text, style) {
+    const codeSpans = [];
+    // Strip any ANSI escapes already in the (backend-controlled) text BEFORE we
+    // add our own styling, so this only removes injected sequences — never the
+    // codes the style helpers emit below.
+    let result = stripAnsi(text).replace(/`([^`]+)`/g, (_, code) => {
+        codeSpans.push(code);
+        return `\u0000${codeSpans.length - 1}\u0000`;
+    });
+    result = result.replace(/\*\*([^\s*](?:[^*]*[^\s*])?)\*\*/g, (_, inner) => style.bold(inner));
+    result = result.replace(/__([^\s_](?:[^_]*[^\s_])?)__/g, (_, inner) => style.bold(inner));
+    result = result.replace(/(?<![\w*])\*([^\s*](?:[^*\n]*[^\s*])?)\*(?![\w*])/g, (_, inner) => style.italic(inner));
+    result = result.replace(/(?<![\w_])_([^\s_](?:[^_\n]*[^\s_])?)_(?![\w_])/g, (_, inner) => style.italic(inner));
+    return result.replace(/\u0000(\d+)\u0000/g, (_, index) => style.code(codeSpans[Number(index)]));
+}
+/** Collapse runs of 3+ blank lines down to a single blank line. */
+function collapseBlankRuns(lines) {
+    const collapsed = [];
+    let blanks = 0;
+    for (const line of lines) {
+        if (line === '') {
+            blanks += 1;
+            continue;
+        }
+        if (blanks > 0)
+            collapsed.push('', ...(blanks === 2 ? [''] : []));
+        blanks = 0;
+        collapsed.push(line);
+    }
+    if (blanks > 0)
+        collapsed.push('', ...(blanks === 2 ? [''] : []));
+    return collapsed;
+}
+//# sourceMappingURL=markdown-terminal.js.map

package/dist/production-intelligence.d.ts

@@ -151,6 +151,8 @@ export declare function askModa(options: {
     daysBack: number;
     cwd: string;
     profile?: string;
+    /** Invoked if the POST hits a network fault and the one retry is used. */
+    onNetworkRetry?: () => void;
 }): Promise<ProductionAskResult>;
 /**
  * Whether `moda ask` should use the live SSE endpoint: only for a human
@@ -166,6 +168,8 @@ export declare function shouldStreamAsk(context: Pick<CommandContext, 'outputMod
  * confidence — the buffered endpoint also returns HTTP 200 in that case).
  */
 export declare function askResultFromStreamOutcome(outcome: AskStreamOutcome, question: string): ProductionAskResult;
-export declare function renderAskHuman(result: ProductionAskResult): string;
+export declare function renderAskHuman(result: ProductionAskResult, options?: {
+    color?: boolean;
+}): string;
 export {};
 //# sourceMappingURL=production-intelligence.d.ts.map

package/dist/production-intelligence.js

@@ -1,10 +1,11 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { callControlAPI, callDataAPI } from './api-client.js';
-import { streamAsk } from './ask-stream.js';
+import { streamAsk, streamFallbackNotice } from './ask-stream.js';
 import { resolveModaBaseUrl } from './config.js';
 import { CliAuthError, CliInputError } from './errors.js';
 import { EXIT_DEGRADED, EXIT_OK, safeWriteStderr } from './output.js';
+import { renderMarkdownForTerminal, shouldColorTerminalOutput, stripAnsi, terminalStyles, } from './markdown-terminal.js';
 import { asNumber, asRecord, asString } from './transforms.js';
 import { INTELLIGENCE_SCHEMA_VERSION, } from './intelligence-schema.js';
 const INVESTIGATION_SCHEMA_VERSION = 'production_investigation.v0.1';
@@ -182,7 +183,16 @@ export async function askModa(options) {
                 profile: options.profile,
                 harness: localHarnessSummary(options.cwd),
             }),
-        }, options.profile ? { profile: options.profile } : {}, { timeoutMs: askTimeoutMs(), retries: 0 });
+        }, options.profile ? { profile: options.profile } : {}, {
+            timeoutMs: askTimeoutMs(),
+            retries: 0,
+            // A stream that just dropped can poison undici's pooled connection to
+            // this origin; without this the buffered fallback fails instantly at
+            // the transport level against a healthy backend. One retry, network
+            // faults only — HTTP errors and the run timeout still never retry.
+            retryOnceOnNetworkError: true,
+            onNetworkRetry: options.onNetworkRetry,
+        });
         const cloud = normalizeCloudAsk(response, options.question);
         if (cloud)
             return cloud;
@@ -262,6 +272,11 @@ export function shouldStreamAsk(context, isTTY = process.stdout.isTTY === true)
  */
 async function askModaForContext(context, question, daysBack) {
     if (shouldStreamAsk(context)) {
+        // Progress lines go to stderr, so key color off the stderr TTY. Tool cards
+        // (`• …`), deliberation lines (`◦ …`), and liveness ticks (`… …`) are
+        // dimmed subtly; phase lines (`▸ …`) stay at full strength.
+        const progressStyle = terminalStyles(shouldColorTerminalOutput({ isTTY: process.stderr.isTTY === true }));
+        const dimmed = (line) => line.startsWith('•') || line.startsWith('◦') || line.startsWith('…');
         try {
             const outcome = await streamAsk({
                 question,
@@ -269,7 +284,7 @@ async function askModaForContext(context, question, daysBack) {
                 profile: context.profile,
                 harness: localHarnessSummary(context.cwd),
                 timeoutMs: askTimeoutMs(),
-                onProgress: (line) => safeWriteStderr(`${line}\n`),
+                onProgress: (line) => safeWriteStderr(`${dimmed(line) ? progressStyle.dim(line) : line}\n`),
             });
             return askResultFromStreamOutcome(outcome, question);
         }
@@ -277,12 +292,26 @@ async function askModaForContext(context, question, daysBack) {
             // Auth problems must keep their structured exit-4 handling.
             if (error instanceof CliAuthError)
                 throw error;
-            if (context.verbose) {
+            const notice = streamFallbackNotice(error);
+            if (notice) {
+                // The stream died AFTER substantial visible progress: the buffered
+                // re-run roughly doubles the wait, so say so instead of going silent.
+                safeWriteStderr(`[moda] ${notice}\n`);
+            }
+            else if (context.verbose) {
                 safeWriteStderr(`[moda] live progress unavailable (${error instanceof Error ? error.message : String(error)}); using buffered ask.\n`);
             }
         }
     }
-    return askModa({ question, daysBack, cwd: context.cwd, profile: context.profile });
+    return askModa({
+        question,
+        daysBack,
+        cwd: context.cwd,
+        profile: context.profile,
+        onNetworkRetry: context.verbose
+            ? () => safeWriteStderr('[moda] network hiccup reaching Moda Cloud; retrying the buffered ask once…\n')
+            : undefined,
+    });
 }
 /**
  * Project a completed stream into the same `ProductionAskResult` the buffered
@@ -1023,22 +1052,26 @@ function renderInvestigationHuman(investigation) {
     }
     return lines.join('\n');
 }
-export function renderAskHuman(result) {
+export function renderAskHuman(result, options = {}) {
+    // Same convention as the rest of the CLI: color only for a human at a TTY,
+    // honoring NO_COLOR and TERM=dumb. All information is identical either way.
+    const color = options.color ?? shouldColorTerminalOutput();
+    const style = terminalStyles(color);
     const lines = [];
-    lines.push('Moda ask');
-    lines.push(`Question: ${result.question}`);
+    lines.push(style.heading('Moda ask'));
+    lines.push(`${style.dim('Question:')} ${result.question}`);
     if (result.degraded) {
         lines.push('');
         lines.push('[degraded] Moda Cloud was unavailable — this answer is synthesized from local Data API evidence (lower trust).');
     }
     lines.push('');
-    lines.push(result.answer);
+    lines.push(renderMarkdownForTerminal(result.answer, { color }));
     lines.push('');
-    lines.push(`Confidence: ${result.confidence}`);
+    lines.push(`Confidence: ${style.bold(result.confidence)}`);
     lines.push(`Source: ${result.source}${result.degraded ? ' (degraded)' : ''}`);
     if (result.evidenceRefs.length > 0) {
         lines.push('');
-        lines.push('Evidence');
+        lines.push(style.bold('Evidence'));
         // Subtle grounding marker: flag model-inferred evidence so a human reader
         // can weight it. Ids/anchors stay hidden in the human projection.
         const grounding = new Map(result.intelligence.evidence_refs.map((ref) => [ref.id, ref.grounding]));
@@ -1047,8 +1080,11 @@ export function renderAskHuman(result) {
             const marker = grounding.get(ref.id) === 'inferred' ? ' (inferred)' : '';
             // Backend hrefs are root-relative dashboard paths; print the absolute
             // URL so terminals auto-linkify it and the reader can click through.
-            const link = ref.href ? `\n    ${dashboardBase}${ref.href}` : '';
-            lines.push(`  - ${ref.label}${ref.path ? ` (${ref.path})` : ''}${marker}${link}`);
+            // Strip ANSI from all backend-controlled fields before printing.
+            const label = stripAnsi(ref.label);
+            const path = ref.path ? ` (${stripAnsi(ref.path)})` : '';
+            const link = ref.href ? `\n    ${style.dim(`${dashboardBase}${stripAnsi(ref.href)}`)}` : '';
+            lines.push(`  - ${label}${path}${marker}${link}`);
         }
     }
     const unverifiedClaims = result.intelligence.answer_claims.filter((claim) => claim.status !== 'grounded').length;
@@ -1058,15 +1094,15 @@ export function renderAskHuman(result) {
     }
     if (result.nextCommands.length > 0) {
         lines.push('');
-        lines.push('Next commands');
+        lines.push(style.bold('Next commands'));
         for (const command of result.nextCommands.slice(0, 5))
-            lines.push(`  ${command}`);
+            lines.push(`  ${stripAnsi(command)}`);
     }
     if (result.warnings.length > 0) {
         lines.push('');
-        lines.push('Warnings');
+        lines.push(style.bold('Warnings'));
         for (const warning of result.warnings.slice(0, 3))
-            lines.push(`  - ${warning}`);
+            lines.push(`  - ${stripAnsi(warning)}`);
     }
     return lines.join('\n');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moda-ai/cli",
-  "version": "1.15.1",
+  "version": "1.17.0",
   "description": "CLI for Moda - AI agent analytics and observability",
   "type": "module",
   "bin": {

package/skills/integration/index.json

@@ -1,7 +1,7 @@
 {
   "schema_version": "moda.skill_index.v1",
-  "bundled_at": "2026-07-08T14:31:50.320Z",
-  "cli_version": "1.15.1",
+  "bundled_at": "2026-07-08T22:14:49.889Z",
+  "cli_version": "1.17.0",
   "skills": [
     {
       "id": "integration-node-anthropic",