@moda-ai/cli 1.13.11 → 1.14.0

package/dist/ask-stream.d.ts

@@ -0,0 +1,90 @@
+import type { AgentConfidence } from './output.js';
+/** Mirrors backend `AgentPhase`. */
+export type AskStreamPhase = 'idle' | 'planning' | 'searching' | 'analyzing' | 'writing' | 'done' | 'error' | 'stopped';
+/** Mirrors backend `StreamCitation`. */
+export interface AskStreamCitation {
+    id: string;
+    n: number;
+    label: string;
+    source: string;
+    snippet?: string;
+    href?: string;
+}
+/** Everything the CLI needs from a completed stream to render the final answer. */
+export interface AskStreamOutcome {
+    answer: string;
+    confidence: AgentConfidence;
+    citations: AskStreamCitation[];
+    nextCommands: string[];
+    elapsedMs?: number;
+    /**
+     * Set when the stream terminated with a terminal `error` event (the agent
+     * failed server-side). Transport failures throw `AskStreamError` instead.
+     */
+    errorMessage?: string;
+}
+/** Signals "fall back to the buffered ask endpoint" — never surfaced raw. */
+export declare class AskStreamError extends Error {
+    constructor(message: string);
+}
+/**
+ * Incremental SSE frame parser. Feed decoded text chunks (arbitrarily split —
+ * even mid `data:` line or mid multi-byte frame); complete `data:` payloads
+ * are returned in order. Handles LF and CRLF framing, multi-line `data:`
+ * fields, and ignores comments (`: ...`) and non-data fields (`event:`, `id:`).
+ */
+export declare class SseParser {
+    private buffer;
+    private pendingCr;
+    push(chunk: string): string[];
+    /** Drain a final frame that was not terminated by a blank line. */
+    flush(): string[];
+}
+/**
+ * Consumes parsed stream events: renders live progress lines through
+ * `onProgress` and accumulates the final outcome. `finish()` throws
+ * `AskStreamError` unless a terminal event (`done` or `error`) arrived, so a
+ * connection dropped mid-run triggers the buffered fallback instead of
+ * rendering a truncated answer.
+ */
+export declare class AskStreamCollector {
+    private readonly onProgress;
+    private answer;
+    private confidence;
+    private citations;
+    private nextCommands;
+    private elapsedMs;
+    private errorMessage;
+    private terminal;
+    private lastPhase;
+    private toolNames;
+    constructor(onProgress?: (line: string) => void);
+    handle(raw: unknown): void;
+    isTerminal(): boolean;
+    finish(): AskStreamOutcome;
+}
+/**
+ * Iterate any chunk source (a fetch body, or test fixtures) through the SSE
+ * 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 interface StreamAskOptions {
+    question: string;
+    daysBack: number;
+    profile?: string;
+    harness?: Record<string, unknown> | null;
+    /** Overall wall-clock budget for the run (default 250s, like buffered ask). */
+    timeoutMs?: number;
+    onProgress?: (line: string) => void;
+    /** Test seam. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * POST the question to `/api/cli/ask/stream` and consume the SSE response.
+ * Throws `AskStreamError` on any transport/framing problem (non-2xx, wrong
+ * content type, network drop, truncated stream) so callers can fall back to
+ * the buffered endpoint.
+ */
+export declare function streamAsk(options: StreamAskOptions): Promise<AskStreamOutcome>;
+//# sourceMappingURL=ask-stream.d.ts.map

package/dist/ask-stream.js

@@ -0,0 +1,330 @@
+// src/ask-stream.ts
+//
+// SSE consumer for `POST /api/cli/ask/stream` (the backend's streaming ask
+// endpoint). Mirrors the `AgentStreamEvent` wire protocol defined in
+// apps/moda-backend/src/data-agent/agent/stream-events.ts: SSE frames of
+// `data: <json>` carrying phase / thinking / tool_start / tool_end / sources /
+// text / done / error events.
+//
+// Design contract: ANY transport, framing, or protocol problem throws
+// `AskStreamError` so the caller can transparently fall back to the buffered
+// `POST /api/cli/ask` path — a user must never get a worse outcome than the
+// buffered request. A terminal `error` event from the agent is NOT a transport
+// failure: it is returned as an outcome (`errorMessage`) and rendered the same
+// way buffered agent errors render.
+import { resolveApiKey, resolveModaBaseUrl } from './config.js';
+/** Signals "fall back to the buffered ask endpoint" — never surfaced raw. */
+export class AskStreamError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AskStreamError';
+    }
+}
+/**
+ * Incremental SSE frame parser. Feed decoded text chunks (arbitrarily split —
+ * even mid `data:` line or mid multi-byte frame); complete `data:` payloads
+ * are returned in order. Handles LF and CRLF framing, multi-line `data:`
+ * fields, and ignores comments (`: ...`) and non-data fields (`event:`, `id:`).
+ */
+export class SseParser {
+    buffer = '';
+    pendingCr = false;
+    push(chunk) {
+        let text = (this.pendingCr ? '\r' : '') + chunk;
+        this.pendingCr = false;
+        // Hold back a trailing '\r' — it may be half of a CRLF split across chunks.
+        if (text.endsWith('\r')) {
+            this.pendingCr = true;
+            text = text.slice(0, -1);
+        }
+        this.buffer += text.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+        const payloads = [];
+        let boundary = this.buffer.indexOf('\n\n');
+        while (boundary !== -1) {
+            const frame = this.buffer.slice(0, boundary);
+            this.buffer = this.buffer.slice(boundary + 2);
+            const payload = dataPayloadOf(frame);
+            if (payload !== null)
+                payloads.push(payload);
+            boundary = this.buffer.indexOf('\n\n');
+        }
+        return payloads;
+    }
+    /** Drain a final frame that was not terminated by a blank line. */
+    flush() {
+        const remaining = this.buffer + (this.pendingCr ? '\r' : '');
+        this.buffer = '';
+        this.pendingCr = false;
+        const payload = dataPayloadOf(remaining.replace(/\r\n/g, '\n').replace(/\r/g, '\n'));
+        return payload !== null ? [payload] : [];
+    }
+}
+function dataPayloadOf(frame) {
+    const dataLines = [];
+    for (const line of frame.split('\n')) {
+        if (line.startsWith('data:')) {
+            dataLines.push(line.slice(5).replace(/^ /, ''));
+        }
+    }
+    if (dataLines.length === 0)
+        return null;
+    const payload = dataLines.join('\n');
+    return payload.trim().length > 0 ? payload : null;
+}
+/** Phases worth a human status line (terminal/idle phases are omitted). */
+const RENDERED_PHASES = new Set(['planning', 'searching', 'analyzing', 'writing']);
+/**
+ * Consumes parsed stream events: renders live progress lines through
+ * `onProgress` and accumulates the final outcome. `finish()` throws
+ * `AskStreamError` unless a terminal event (`done` or `error`) arrived, so a
+ * connection dropped mid-run triggers the buffered fallback instead of
+ * rendering a truncated answer.
+ */
+export class AskStreamCollector {
+    onProgress;
+    answer = '';
+    confidence = 'medium';
+    citations = [];
+    nextCommands = [];
+    elapsedMs;
+    errorMessage;
+    terminal = false;
+    lastPhase;
+    toolNames = new Map();
+    constructor(onProgress = () => { }) {
+        this.onProgress = onProgress;
+    }
+    handle(raw) {
+        if (this.terminal)
+            return;
+        const event = raw;
+        if (!event || typeof event !== 'object' || typeof event.type !== 'string') {
+            throw new AskStreamError('stream emitted a frame without an event type');
+        }
+        switch (event.type) {
+            case 'phase': {
+                const phase = typeof event.phase === 'string' ? event.phase : '';
+                if (RENDERED_PHASES.has(phase) && phase !== this.lastPhase) {
+                    this.lastPhase = phase;
+                    this.onProgress(`▸ ${phase}…`);
+                }
+                break;
+            }
+            case 'thinking':
+                // Model narration is too chatty for one-line terminal progress; skip.
+                break;
+            case 'tool_start': {
+                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;
+                if (id)
+                    this.toolNames.set(id, name);
+                this.onProgress(`• ${name} — ${title}…`);
+                break;
+            }
+            case 'tool_end': {
+                const id = typeof event.id === 'string' ? event.id : '';
+                const name = this.toolNames.get(id) ?? 'tool';
+                this.onProgress(`• ${name} — ${toolEndDetail(event)}`);
+                break;
+            }
+            case 'sources': {
+                this.citations = Array.isArray(event.citations)
+                    ? event.citations.flatMap(normalizeCitation)
+                    : [];
+                break;
+            }
+            case 'text': {
+                if (typeof event.delta === 'string')
+                    this.answer += event.delta;
+                break;
+            }
+            case 'done': {
+                this.terminal = true;
+                this.confidence = normalizeStreamConfidence(event.confidence);
+                if (typeof event.elapsedMs === 'number')
+                    this.elapsedMs = event.elapsedMs;
+                this.nextCommands = Array.isArray(event.nextCommands)
+                    ? event.nextCommands.filter((item) => typeof item === 'string')
+                    : [];
+                break;
+            }
+            case 'error': {
+                this.terminal = true;
+                this.errorMessage = typeof event.message === 'string' && event.message.trim().length > 0
+                    ? event.message
+                    : 'The analysis agent hit an error and could not complete the request.';
+                break;
+            }
+            default:
+                // Forward-compatible: unknown event types are ignored, not fatal.
+                break;
+        }
+    }
+    isTerminal() {
+        return this.terminal;
+    }
+    finish() {
+        if (!this.terminal) {
+            throw new AskStreamError('stream ended before a terminal done/error event');
+        }
+        if (!this.errorMessage && this.answer.trim().length === 0) {
+            // Mirror the buffered contract: an empty answer means "no usable cloud
+            // answer" and must trigger the fallback path, not render as blank prose.
+            throw new AskStreamError('stream completed with an empty answer');
+        }
+        return {
+            answer: this.answer,
+            confidence: this.confidence,
+            citations: this.citations,
+            nextCommands: this.nextCommands,
+            ...(this.elapsedMs !== undefined ? { elapsedMs: this.elapsedMs } : {}),
+            ...(this.errorMessage ? { errorMessage: this.errorMessage } : {}),
+        };
+    }
+}
+/**
+ * Tool cards must stay one line: backend summaries can be multi-line prose
+ * (e.g. get_timeseries emits a day-by-day breakdown), which would spill the
+ * whole table into the progress area. Collapse whitespace and truncate.
+ */
+const TOOL_CARD_DETAIL_MAX = 100;
+function oneLine(text) {
+    const collapsed = text.replace(/\s+/g, ' ').trim();
+    return collapsed.length > TOOL_CARD_DETAIL_MAX
+        ? `${collapsed.slice(0, TOOL_CARD_DETAIL_MAX - 1)}…`
+        : collapsed;
+}
+function toolEndDetail(event) {
+    const summary = typeof event.summary === 'string' ? event.summary : '';
+    const secs = typeof event.ms === 'number' ? `${(event.ms / 1000).toFixed(1)}s` : undefined;
+    if (event.status === 'error') {
+        const reason = typeof event.error === 'string' && event.error ? event.error : summary || 'failed';
+        return joinDetail(`failed: ${oneLine(reason)}`, secs);
+    }
+    const detail = summary ||
+        (typeof event.hits === 'number'
+            ? `${event.hits} hits`
+            : typeof event.rows === 'number'
+                ? `${event.rows} rows`
+                : 'done');
+    return joinDetail(oneLine(detail), secs);
+}
+function joinDetail(detail, secs) {
+    return secs ? `${detail}, ${secs}` : detail;
+}
+function normalizeCitation(item) {
+    const record = item;
+    if (!record || typeof record !== 'object')
+        return [];
+    const label = typeof record.label === 'string' ? record.label : undefined;
+    const id = typeof record.id === 'string' ? record.id : undefined;
+    if (!label && !id)
+        return [];
+    return [{
+            id: id ?? `ref-${typeof record.n === 'number' ? record.n : 0}`,
+            n: typeof record.n === 'number' ? record.n : 0,
+            label: label ?? id ?? 'Cloud evidence',
+            source: typeof record.source === 'string' ? record.source : 'evidence',
+            ...(typeof record.snippet === 'string' ? { snippet: record.snippet } : {}),
+            ...(typeof record.href === 'string' ? { href: record.href } : {}),
+        }];
+}
+function normalizeStreamConfidence(value) {
+    return value === 'high' || value === 'medium' || value === 'low' || value === 'unknown'
+        ? value
+        : 'medium';
+}
+/**
+ * Iterate any chunk source (a fetch body, or test fixtures) through the SSE
+ * 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) {
+    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));
+            if (collector.isTerminal())
+                return collector.finish();
+        }
+    }
+    for (const payload of parser.flush()) {
+        collector.handle(parsePayload(payload));
+        if (collector.isTerminal())
+            return collector.finish();
+    }
+    return collector.finish();
+}
+function parsePayload(payload) {
+    try {
+        return JSON.parse(payload);
+    }
+    catch {
+        throw new AskStreamError('stream emitted an unparseable frame');
+    }
+}
+const DEFAULT_STREAM_TIMEOUT_MS = 250_000;
+/**
+ * POST the question to `/api/cli/ask/stream` and consume the SSE response.
+ * Throws `AskStreamError` on any transport/framing problem (non-2xx, wrong
+ * content type, network drop, truncated stream) so callers can fall back to
+ * the buffered endpoint.
+ */
+export async function streamAsk(options) {
+    const profileOptions = options.profile ? { profile: options.profile } : {};
+    const url = `${resolveModaBaseUrl(profileOptions)}/api/cli/ask/stream`;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? DEFAULT_STREAM_TIMEOUT_MS);
+    try {
+        const fetchImpl = options.fetchImpl ?? fetch;
+        let response;
+        try {
+            response = await fetchImpl(url, {
+                method: 'POST',
+                headers: {
+                    'x-api-key': resolveApiKey(profileOptions) ?? '',
+                    'Content-Type': 'application/json',
+                    Accept: 'text/event-stream',
+                },
+                body: JSON.stringify({
+                    question: options.question,
+                    daysBack: options.daysBack,
+                    profile: options.profile,
+                    harness: options.harness,
+                }),
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            throw new AskStreamError(`stream request failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (!response.ok) {
+            throw new AskStreamError(`stream endpoint returned HTTP ${response.status}`);
+        }
+        const contentType = response.headers.get('content-type') ?? '';
+        if (!contentType.includes('text/event-stream')) {
+            // An old frontend deploy without the stream proxy can 200 with JSON/HTML.
+            throw new AskStreamError(`stream endpoint returned unexpected content type '${contentType || 'unknown'}'`);
+        }
+        if (!response.body) {
+            throw new AskStreamError('stream response had no body');
+        }
+        const collector = new AskStreamCollector(options.onProgress);
+        try {
+            return await consumeAskSse(response.body, collector);
+        }
+        catch (error) {
+            if (error instanceof AskStreamError)
+                throw error;
+            throw new AskStreamError(`stream read failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+//# sourceMappingURL=ask-stream.js.map

package/dist/cli.js

@@ -203,6 +203,7 @@ Common flags:
   --agent                          Emit schema-versioned agent JSON
   --stream                         With --agent, emit NDJSON agent events
   --human                          Force human prose (overrides auto-detection)
+  --no-stream                      Disable live ask progress (buffered request)
 
 Output auto-detection (no flags needed):
   Piped/redirected stdout, CI, or an agent env (CLAUDECODE/CURSOR/MODA_AGENT)
@@ -940,7 +941,11 @@ export const commandRegistry = createCommandRegistry([
     legacyCommand({
         name: 'ask',
         description: 'Ask Moda a production intelligence question',
-        examples: ['moda ask "what should I fix first?"', 'moda --agent ask "why did this run fail?"'],
+        examples: [
+            'moda ask "what should I fix first?"',
+            'moda ask "what should I fix first?" --no-stream',
+            'moda --agent ask "why did this run fail?"',
+        ],
         ...dataApiDefaults,
     }),
     legacyCommand({

package/dist/production-intelligence.d.ts

@@ -1,3 +1,4 @@
+import { type AskStreamOutcome } from './ask-stream.js';
 import type { CommandContext } from './command-context.js';
 import type { AgentConfidence } from './output.js';
 import { type ModaIntelligenceV1 } from './intelligence-schema.js';
@@ -145,5 +146,20 @@ export declare function askModa(options: {
     cwd: string;
     profile?: string;
 }): Promise<ProductionAskResult>;
+/**
+ * Whether `moda ask` should use the live SSE endpoint: only for a human
+ * watching a TTY, and only when not explicitly opted out via `--no-stream`
+ * (or `--stream=false`). `--json`/`--agent`/piped/quiet callers always take
+ * the buffered path so machine-readable contracts are untouched.
+ */
+export declare function shouldStreamAsk(context: Pick<CommandContext, 'outputMode' | 'quiet' | 'flags'>, isTTY?: boolean): boolean;
+/**
+ * Project a completed stream into the same `ProductionAskResult` the buffered
+ * path produces, so the final human render is identical. A terminal `error`
+ * event mirrors the buffered error contract (a generic answer with `unknown`
+ * 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 {};
 //# sourceMappingURL=production-intelligence.d.ts.map

package/dist/production-intelligence.js

@@ -1,8 +1,9 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { callControlAPI, callDataAPI } from './api-client.js';
-import { CliInputError } from './errors.js';
-import { EXIT_DEGRADED, EXIT_OK } from './output.js';
+import { streamAsk } from './ask-stream.js';
+import { CliAuthError, CliInputError } from './errors.js';
+import { EXIT_DEGRADED, EXIT_OK, safeWriteStderr } from './output.js';
 import { asNumber, asRecord, asString } from './transforms.js';
 import { INTELLIGENCE_SCHEMA_VERSION, } from './intelligence-schema.js';
 const INVESTIGATION_SCHEMA_VERSION = 'production_investigation.v0.1';
@@ -32,7 +33,7 @@ export async function runProductionCommand(context) {
         if (!question) {
             throw new CliInputError('<question> is required', 'Usage: moda ask "what should I fix first?" [--days-back=N]');
         }
-        const result = await askModa({ question, daysBack, cwd: context.cwd, profile: context.profile });
+        const result = await askModaForContext(context, question, daysBack);
         if (context.outputMode === 'human') {
             if (!context.quiet)
                 console.log(renderAskHuman(result));
@@ -236,6 +237,98 @@ export async function askModa(options) {
         }),
     };
 }
+/**
+ * Whether `moda ask` should use the live SSE endpoint: only for a human
+ * watching a TTY, and only when not explicitly opted out via `--no-stream`
+ * (or `--stream=false`). `--json`/`--agent`/piped/quiet callers always take
+ * the buffered path so machine-readable contracts are untouched.
+ */
+export function shouldStreamAsk(context, isTTY = process.stdout.isTTY === true) {
+    if (context.outputMode !== 'human' || context.quiet)
+        return false;
+    if ('no-stream' in context.flags)
+        return false;
+    if (context.flags.stream === 'false')
+        return false;
+    return isTTY;
+}
+/**
+ * Human-TTY ask entrypoint: try the streaming endpoint for live progress and
+ * fall back to the buffered `askModa` on ANY stream problem (endpoint missing,
+ * connection dropped mid-run, framing error). The fallback is transparent —
+ * a note is printed only in verbose mode — so the outcome is never worse than
+ * the buffered path.
+ */
+async function askModaForContext(context, question, daysBack) {
+    if (shouldStreamAsk(context)) {
+        try {
+            const outcome = await streamAsk({
+                question,
+                daysBack,
+                profile: context.profile,
+                harness: localHarnessSummary(context.cwd),
+                timeoutMs: askTimeoutMs(),
+                onProgress: (line) => safeWriteStderr(`${line}\n`),
+            });
+            return askResultFromStreamOutcome(outcome, question);
+        }
+        catch (error) {
+            // Auth problems must keep their structured exit-4 handling.
+            if (error instanceof CliAuthError)
+                throw error;
+            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 });
+}
+/**
+ * Project a completed stream into the same `ProductionAskResult` the buffered
+ * path produces, so the final human render is identical. A terminal `error`
+ * event mirrors the buffered error contract (a generic answer with `unknown`
+ * confidence — the buffered endpoint also returns HTTP 200 in that case).
+ */
+export function askResultFromStreamOutcome(outcome, question) {
+    const answer = outcome.errorMessage ?? outcome.answer;
+    const confidence = outcome.errorMessage
+        ? 'unknown'
+        : normalizeConfidence(outcome.confidence);
+    const evidenceRefs = outcome.errorMessage
+        ? []
+        : outcome.citations.map((citation) => ({
+            id: citation.id,
+            kind: evidenceKind(citation.source),
+            label: citation.label,
+        }));
+    const nextCommands = outcome.errorMessage ? [] : outcome.nextCommands;
+    const warnings = outcome.errorMessage
+        ? ['The analysis agent failed; returning a generic message.']
+        : [];
+    return {
+        schemaVersion: ASK_SCHEMA_VERSION,
+        generatedAt: new Date().toISOString(),
+        source: 'cloud',
+        degraded: false,
+        question,
+        answer,
+        confidence,
+        evidenceRefs,
+        findings: [],
+        nextCommands,
+        warnings,
+        intelligence: synthesizeIntelligenceV1({
+            question,
+            answer,
+            confidence,
+            evidenceRefs,
+            nextCommands,
+            warnings,
+            source: 'cloud',
+            degraded: false,
+        }),
+    };
+}
 /**
  * Timeout (ms) for the cloud `ask` POST. The backend enforces its own ~240s run
  * deadline under a 300s function limit, so the client waits long enough to
@@ -926,7 +1019,7 @@ function renderInvestigationHuman(investigation) {
     }
     return lines.join('\n');
 }
-function renderAskHuman(result) {
+export function renderAskHuman(result) {
     const lines = [];
     lines.push('Moda ask');
     lines.push(`Question: ${result.question}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moda-ai/cli",
-  "version": "1.13.11",
+  "version": "1.14.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-08T07:05:48.702Z",
-  "cli_version": "1.13.11",
+  "bundled_at": "2026-07-08T09:14:05.529Z",
+  "cli_version": "1.14.0",
   "skills": [
     {
       "id": "integration-node-anthropic",