@moda-ai/cli 1.9.6 → 1.10.0

package/dist/production-intelligence.d.ts

@@ -1,5 +1,6 @@
 import type { CommandContext } from './command-context.js';
 import type { AgentConfidence } from './output.js';
+import { type ModaIntelligenceV1 } from './intelligence-schema.js';
 declare const INVESTIGATION_SCHEMA_VERSION = "production_investigation.v0.1";
 declare const OVERVIEW_SCHEMA_VERSION = "production_overview.v0.1";
 declare const ASK_SCHEMA_VERSION = "production_ask.v0.1";
@@ -99,6 +100,13 @@ export interface ProductionAskResult {
     schemaVersion: typeof ASK_SCHEMA_VERSION;
     generatedAt: string;
     source: 'cloud' | 'local_fallback';
+    /**
+     * True when the answer did NOT come from Moda Cloud intelligence and was
+     * instead synthesized locally (cloud unreachable / unavailable / empty). This
+     * is the canonical in-payload signal of a degraded answer, mirrored by exit
+     * code 3 and envelope status `degraded`. Always `false` on the cloud path.
+     */
+    degraded: boolean;
     question: string;
     answer: string;
     confidence: AgentConfidence;
@@ -106,6 +114,17 @@ export interface ProductionAskResult {
     findings: ProductionFinding[];
     nextCommands: string[];
     warnings: string[];
+    /** Why the cloud path was not used (set only when `degraded` is true). */
+    fallbackReason?: string;
+    /**
+     * The canonical `moda.intelligence.v1` projection of this answer (MODA-388).
+     * This is what `moda ask --json`/`--agent` surface as the agent envelope's
+     * `data`, so every surface reads one versioned, snake_case payload (carrying
+     * per-evidence `grounding`/`anchor` and per-claim grounding verdicts). On the
+     * cloud path it is taken from `response.intelligence` when present, else
+     * synthesized from the legacy snake_case fields for back-compat.
+     */
+    intelligence: ModaIntelligenceV1;
 }
 export declare function runProductionCommand(context: CommandContext): Promise<{
     exitCode: number;

package/dist/production-intelligence.js

@@ -2,7 +2,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 { asNumber, asRecord, asString } from './transforms.js';
+import { INTELLIGENCE_SCHEMA_VERSION, } from './intelligence-schema.js';
 const INVESTIGATION_SCHEMA_VERSION = 'production_investigation.v0.1';
 const OVERVIEW_SCHEMA_VERSION = 'production_overview.v0.1';
 const ASK_SCHEMA_VERSION = 'production_ask.v0.1';
@@ -36,9 +38,17 @@ export async function runProductionCommand(context) {
                 console.log(renderAskHuman(result));
         }
         else {
-            context.output.writeData(result, askAgentOptions(result));
+            // The agent/JSON `data` payload is the canonical moda.intelligence.v1
+            // value (carrying evidence grounding + per-claim verdicts). The
+            // moda.agent.v1 envelope still wraps it; only the inner `data` is v1.
+            context.output.writeData(result.intelligence, {
+                ...askAgentOptions(result),
+                status: result.degraded ? 'degraded' : 'success',
+            });
         }
-        return { exitCode: 0 };
+        // Exit 3 on a degraded/local-fallback answer so a scripted agent can detect
+        // it from the exit code alone (in addition to `data.degraded` / status).
+        return { exitCode: result.degraded ? EXIT_DEGRADED : EXIT_OK };
     }
     if (context.command === 'why-failed') {
         const runId = context.positional;
@@ -184,6 +194,10 @@ export async function investigateProduction(options) {
     };
 }
 export async function askModa(options) {
+    // Capture *why* the cloud path was not used so the caller (human or agent)
+    // can see it, instead of silently swallowing the error and masquerading the
+    // local fallback as a normal answer.
+    let fallbackReason = 'Moda Cloud ask endpoint returned no answer.';
     try {
         const response = await callControlAPI('/cli/ask', {
             method: 'POST',
@@ -193,14 +207,14 @@ export async function askModa(options) {
                 profile: options.profile,
                 harness: localHarnessSummary(options.cwd),
             }),
-        });
+        }, options.profile ? { profile: options.profile } : {}, { timeoutMs: askTimeoutMs(), retries: 0 });
         const cloud = normalizeCloudAsk(response, options.question);
         if (cloud)
             return cloud;
+        fallbackReason = 'Moda Cloud ask endpoint returned an empty answer.';
     }
-    catch {
-        // The endpoint is intentionally future-facing. Until cloud intelligence is
-        // deployed everywhere, the CLI keeps answering from bounded Data API evidence.
+    catch (error) {
+        fallbackReason = `Moda Cloud ask endpoint unavailable: ${error instanceof Error ? error.message : String(error)}`;
     }
     const investigation = await investigateProduction({
         daysBack: options.daysBack,
@@ -209,24 +223,56 @@ export async function askModa(options) {
     });
     const top = investigation.findings[0];
     const answer = top
-        ? `Moda Cloud intelligence is not available yet, so I synthesized this from production evidence. The strongest signal is: ${top.title}. ${top.summary}`
-        : 'Moda Cloud intelligence is not available yet, and the local Data API evidence did not contain a strong production signal.';
+        ? `Moda Cloud intelligence is not available, so I synthesized this from production evidence. The strongest signal is: ${top.title}. ${top.summary}`
+        : 'Moda Cloud intelligence is not available, and the local Data API evidence did not contain a strong production signal.';
+    const confidence = capFallbackConfidence(investigation.summary.confidence);
+    const evidenceRefs = investigation.evidenceRefs.slice(0, 12);
+    const findings = investigation.findings.slice(0, 5);
+    const nextCommands = investigation.nextCommands;
+    const warnings = [
+        'Cloud ask endpoint unavailable; synthesized answer from local Data API evidence.',
+        fallbackReason,
+        ...investigation.warnings,
+    ];
     return {
         schemaVersion: ASK_SCHEMA_VERSION,
         generatedAt: new Date().toISOString(),
         source: 'local_fallback',
+        degraded: true,
+        fallbackReason,
         question: options.question,
         answer,
-        confidence: capFallbackConfidence(investigation.summary.confidence),
-        evidenceRefs: investigation.evidenceRefs.slice(0, 12),
-        findings: investigation.findings.slice(0, 5),
-        nextCommands: investigation.nextCommands,
-        warnings: [
-            'Cloud ask endpoint unavailable; synthesized answer from local Data API evidence.',
-            ...investigation.warnings,
-        ],
+        confidence,
+        evidenceRefs,
+        findings,
+        nextCommands,
+        warnings,
+        // Degraded answers still carry a v1-shaped payload so every surface reads
+        // one contract; `source`/`degraded` flag the lower trust (preserving exit
+        // code 3 + status 'degraded').
+        intelligence: synthesizeIntelligenceV1({
+            question: options.question,
+            answer,
+            confidence,
+            evidenceRefs,
+            nextCommands,
+            warnings,
+            source: 'local_fallback',
+            degraded: true,
+            findings,
+        }),
     };
 }
+/**
+ * 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
+ * receive a real answer rather than aborting a healthy run at 30s and silently
+ * falling back. Override with `MODA_ASK_TIMEOUT_MS`.
+ */
+function askTimeoutMs() {
+    const raw = Number(process.env.MODA_ASK_TIMEOUT_MS);
+    return Number.isFinite(raw) && raw > 0 ? raw : 250_000;
+}
 function writeInvestigation(context, investigation) {
     if (context.outputMode === 'human') {
         if (!context.quiet)
@@ -547,10 +593,27 @@ function normalizeCloudAsk(response, question) {
         ? record.next_commands.filter((item) => typeof item === 'string')
         : ['moda investigate'];
     const confidence = normalizeConfidence(record?.confidence);
+    // Prefer the backend's canonical v1 payload when it ships one; otherwise
+    // synthesize a v1 projection from the legacy snake_case fields so older
+    // backends still produce a valid moda.intelligence.v1 `data`.
+    const intelligenceRecord = asRecord(record?.intelligence);
+    const intelligence = looksLikeIntelligenceV1(intelligenceRecord)
+        ? coerceIntelligenceV1(intelligenceRecord, { question, answer, confidence })
+        : synthesizeIntelligenceV1({
+            question,
+            answer,
+            confidence,
+            evidenceRefs,
+            nextCommands,
+            warnings: [],
+            source: 'cloud',
+            degraded: false,
+        });
     return {
         schemaVersion: ASK_SCHEMA_VERSION,
         generatedAt: new Date().toISOString(),
         source: 'cloud',
+        degraded: false,
         question,
         answer,
         confidence,
@@ -558,8 +621,260 @@ function normalizeCloudAsk(response, question) {
         findings: [],
         nextCommands,
         warnings: [],
+        intelligence,
+    };
+}
+/**
+ * Heuristic "is this the canonical v1 payload?" guard. We accept an object that
+ * either declares the matching `schema_version` or carries the core v1 fields
+ * (`answer_markdown` / `summary`). A present-but-wrong `schema_version` is
+ * rejected so a future breaking version falls back to synthesis rather than
+ * being mis-projected.
+ */
+function looksLikeIntelligenceV1(record) {
+    if (!record)
+        return false;
+    const version = asString(record.schema_version);
+    if (version && version !== INTELLIGENCE_SCHEMA_VERSION)
+        return false;
+    return (version === INTELLIGENCE_SCHEMA_VERSION ||
+        typeof record.answer_markdown === 'string' ||
+        asRecord(record.summary) !== null);
+}
+/**
+ * Defensively project a backend `intelligence` object into a schema-valid
+ * {@link ModaIntelligenceV1}. Every field is coerced and defaulted so the CLI
+ * never emits a malformed payload even if the backend is partially shaped.
+ */
+function coerceIntelligenceV1(record, context) {
+    const summaryRecord = asRecord(record.summary);
+    const summary = {
+        text: asString(summaryRecord?.text) ?? context.answer,
+        confidence: confidenceValue(summaryRecord?.confidence) ?? context.confidence,
+    };
+    const evidenceRefs = Array.isArray(record.evidence_refs)
+        ? record.evidence_refs.flatMap(coerceV1EvidenceRef)
+        : [];
+    const answerClaims = Array.isArray(record.answer_claims)
+        ? record.answer_claims.flatMap(coerceV1Claim)
+        : [];
+    const findings = Array.isArray(record.findings)
+        ? record.findings.flatMap(coerceV1Finding)
+        : [];
+    const nextCommands = Array.isArray(record.next_commands)
+        ? record.next_commands.flatMap(coerceV1NextCommand)
+        : [];
+    const warnings = stringArray(record.warnings);
+    const meta = asRecord(record.meta);
+    return {
+        schema_version: INTELLIGENCE_SCHEMA_VERSION,
+        generated_at: asString(record.generated_at) ?? new Date().toISOString(),
+        command: asString(record.command) ?? 'ask',
+        source: record.source === 'local_fallback' ? 'local_fallback' : 'cloud',
+        degraded: record.degraded === true,
+        question: asString(record.question) ?? context.question,
+        summary,
+        answer_markdown: asString(record.answer_markdown) ?? context.answer,
+        answer_claims: answerClaims,
+        findings,
+        evidence_refs: evidenceRefs,
+        next_commands: nextCommands,
+        warnings,
+        ...(meta ? { meta } : {}),
+    };
+}
+/**
+ * Build a v1 payload from legacy snake_case fields (or local-fallback evidence).
+ * `evidence_refs` default to `grounding: 'measured'` and `answer_claims` is
+ * empty because the legacy contract has no per-claim grounding verdicts.
+ */
+function synthesizeIntelligenceV1(options) {
+    return {
+        schema_version: INTELLIGENCE_SCHEMA_VERSION,
+        generated_at: new Date().toISOString(),
+        command: 'ask',
+        source: options.source,
+        degraded: options.degraded,
+        question: options.question,
+        summary: { text: options.answer, confidence: options.confidence },
+        answer_markdown: options.answer,
+        answer_claims: [],
+        findings: (options.findings ?? []).map(productionFindingToV1),
+        evidence_refs: options.evidenceRefs.map(productionEvidenceToV1),
+        next_commands: options.nextCommands.map(commandStringToV1),
+        warnings: options.warnings,
+    };
+}
+function coerceV1EvidenceRef(item) {
+    const ref = asRecord(item);
+    if (!ref)
+        return [];
+    const label = asString(ref.label);
+    const anchor = coerceV1Anchor(asRecord(ref.anchor));
+    const snippet = asString(ref.snippet);
+    return [{
+            id: asString(ref.id) ?? `ask:evidence:${slug(label ?? 'ref')}`,
+            kind: asString(ref.kind) ?? 'ask',
+            label: label ?? asString(ref.id) ?? 'Cloud evidence',
+            ...(anchor ? { anchor } : {}),
+            ...(snippet ? { snippet } : {}),
+            grounding: provenanceValue(ref.grounding) ?? 'measured',
+        }];
+}
+function coerceV1Anchor(record) {
+    if (!record)
+        return undefined;
+    const anchor = {
+        ...(asString(record.conversation_id) ? { conversation_id: asString(record.conversation_id) } : {}),
+        ...(asNumber(record.message_index) !== null ? { message_index: asNumber(record.message_index) } : {}),
+        ...(asString(record.run_id) ? { run_id: asString(record.run_id) } : {}),
+        ...(asString(record.tool_name) ? { tool_name: asString(record.tool_name) } : {}),
+    };
+    return Object.keys(anchor).length > 0 ? anchor : undefined;
+}
+function coerceV1Claim(item) {
+    const claim = asRecord(item);
+    if (!claim)
+        return [];
+    const text = asString(claim.text);
+    if (!text)
+        return [];
+    const value = asNumber(claim.value);
+    const matchedPath = asString(claim.matched_path);
+    return [{
+            text,
+            ...(value !== null ? { value } : {}),
+            kind: claim.kind === 'percentage' || claim.kind === 'count' ? claim.kind : 'qualitative',
+            status: claim.status === 'grounded' || claim.status === 'ungrounded'
+                ? claim.status
+                : 'unverifiable',
+            evidence_ref_ids: stringArray(claim.evidence_ref_ids),
+            ...(matchedPath ? { matched_path: matchedPath } : {}),
+        }];
+}
+function coerceV1Finding(item) {
+    const finding = asRecord(item);
+    if (!finding)
+        return [];
+    const id = asString(finding.id);
+    const title = asString(finding.title);
+    if (!id || !title)
+        return [];
+    const severity = finding.severity;
+    const description = asString(finding.description);
+    return [{
+            id,
+            title,
+            ...(severity === 'critical' || severity === 'high' || severity === 'medium' ||
+                severity === 'low' || severity === 'info'
+                ? { severity }
+                : {}),
+            ...(description ? { description } : {}),
+            evidence_ref_ids: stringArray(finding.evidence_ref_ids),
+            recommended_actions: Array.isArray(finding.recommended_actions)
+                ? finding.recommended_actions.flatMap(coerceV1RecommendedAction)
+                : [],
+        }];
+}
+function coerceV1RecommendedAction(item) {
+    const action = asRecord(item);
+    if (!action)
+        return [];
+    const id = asString(action.id);
+    const title = asString(action.title);
+    if (!id || !title)
+        return [];
+    const rationale = asString(action.rationale);
+    const command = asString(action.command);
+    return [{
+            id,
+            title,
+            ...(rationale ? { rationale } : {}),
+            ...(command ? { command } : {}),
+            mutability: mutabilityValue(action.mutability) ?? 'unknown',
+            requires_approval: action.requires_approval === true,
+        }];
+}
+function coerceV1NextCommand(item) {
+    if (typeof item === 'string')
+        return [commandStringToV1(item)];
+    const record = asRecord(item);
+    if (!record)
+        return [];
+    const command = asString(record.command);
+    if (!command)
+        return [];
+    const purpose = asString(record.purpose);
+    return [{
+            command,
+            ...(purpose ? { purpose } : {}),
+            mutability: mutabilityValue(record.mutability) ?? mutabilityForCommand(command),
+            requires_approval: typeof record.requires_approval === 'boolean'
+                ? record.requires_approval
+                : requiresApprovalForCommand(command),
+        }];
+}
+function productionEvidenceToV1(ref) {
+    const anchor = {
+        ...(ref.conversationId ? { conversation_id: ref.conversationId } : {}),
+        ...(ref.runId ? { run_id: ref.runId } : {}),
+        ...(ref.toolName ? { tool_name: ref.toolName } : {}),
+    };
+    return {
+        id: ref.id,
+        kind: ref.kind,
+        label: ref.label,
+        ...(Object.keys(anchor).length > 0 ? { anchor } : {}),
+        grounding: 'measured',
     };
 }
+function productionFindingToV1(finding) {
+    return {
+        id: finding.id,
+        title: finding.title,
+        severity: finding.severity,
+        description: `${finding.summary} ${finding.rankReason}`.trim(),
+        evidence_ref_ids: finding.evidenceRefIds,
+        recommended_actions: finding.recommendedActions.map((action) => ({
+            id: action.id,
+            title: action.title,
+            rationale: action.rationale,
+            command: action.command,
+            mutability: action.mutability,
+            requires_approval: action.requiresApproval,
+        })),
+    };
+}
+function commandStringToV1(command) {
+    return {
+        command,
+        purpose: purposeForCommand(command),
+        mutability: mutabilityForCommand(command),
+        requires_approval: requiresApprovalForCommand(command),
+    };
+}
+function mutabilityForCommand(command) {
+    return command.includes(' sync') ? 'sync' : 'read';
+}
+function requiresApprovalForCommand(command) {
+    return command.includes(' sync') || command.includes(' --yes');
+}
+function stringArray(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
+}
+function confidenceValue(value) {
+    return value === 'high' || value === 'medium' || value === 'low' || value === 'unknown'
+        ? value
+        : null;
+}
+function provenanceValue(value) {
+    return value === 'measured' || value === 'inferred' ? value : null;
+}
+function mutabilityValue(value) {
+    return value === 'read' || value === 'write' || value === 'sync' || value === 'unknown'
+        ? value
+        : null;
+}
 function investigationAgentOptions(investigation) {
     return {
         summary: investigation.summary,
@@ -585,6 +900,17 @@ function overviewAgentOptions(briefing) {
     };
 }
 function askAgentOptions(result) {
+    const errors = result.degraded
+        ? [{
+                code: 'cloud_unavailable',
+                message: result.fallbackReason ??
+                    'Moda Cloud intelligence was unavailable; answer synthesized from local Data API evidence.',
+                // Non-blocking: an answer WAS produced, just from a degraded source. The
+                // agent should still treat it as lower-trust (see exit code 3 / status).
+                blocking: false,
+                suggested_commands: ['moda doctor --online'],
+            }]
+        : [];
     return {
         summary: { text: result.answer, confidence: result.confidence },
         findings: result.findings.map(agentFinding),
@@ -592,6 +918,7 @@ function askAgentOptions(result) {
         recommendedActions: result.findings.flatMap((finding) => finding.recommendedActions.map(agentAction)),
         nextCommands: result.nextCommands.map(nextCommand),
         warnings: result.warnings,
+        errors,
     };
 }
 function agentFinding(finding) {
@@ -707,17 +1034,31 @@ function renderAskHuman(result) {
     const lines = [];
     lines.push('Moda ask');
     lines.push(`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('');
     lines.push(`Confidence: ${result.confidence}`);
+    lines.push(`Source: ${result.source}${result.degraded ? ' (degraded)' : ''}`);
     if (result.evidenceRefs.length > 0) {
         lines.push('');
         lines.push('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]));
         for (const ref of result.evidenceRefs.slice(0, 8)) {
-            lines.push(`  - ${ref.label}${ref.path ? ` (${ref.path})` : ''}`);
+            const marker = grounding.get(ref.id) === 'inferred' ? ' (inferred)' : '';
+            lines.push(`  - ${ref.label}${ref.path ? ` (${ref.path})` : ''}${marker}`);
         }
     }
+    const unverifiedClaims = result.intelligence.answer_claims.filter((claim) => claim.status !== 'grounded').length;
+    if (unverifiedClaims > 0) {
+        lines.push('');
+        lines.push(`Note: ${unverifiedClaims} claim(s) could not be grounded against tool data.`);
+    }
     if (result.nextCommands.length > 0) {
         lines.push('');
         lines.push('Next commands');

package/dist/schemas.d.ts

@@ -141,6 +141,26 @@ export declare const ToolFailureDetailSchema: z.ZodObject<{
     include_window?: unknown;
     subtype?: string | undefined;
 }>;
+/**
+ * moda audit <conversation_id|trace_id> — raw, non-deduped span/trace read.
+ * `kind=auto` (default) lets the backend try trace first, then conversation.
+ */
+export declare const AuditSchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodOptional<z.ZodDefault<z.ZodEnum<["auto", "trace", "conversation"]>>>;
+    include_raw: z.ZodOptional<z.ZodEffects<z.ZodBoolean, boolean, unknown>>;
+    limit: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    kind?: "auto" | "trace" | "conversation" | undefined;
+    limit?: number | undefined;
+    include_raw?: boolean | undefined;
+}, {
+    id: string;
+    kind?: "auto" | "trace" | "conversation" | undefined;
+    limit?: number | undefined;
+    include_raw?: unknown;
+}>;
 /**
  * moda search "<query>" — keyword/semantic/hybrid search across conversation
  * messages. `q` arrives as a positional arg; the runCommand handler rejects an
@@ -190,14 +210,14 @@ export declare const RunsSchema: z.ZodObject<{
     limit?: number | undefined;
     offset?: number | undefined;
     user_id?: string | undefined;
-    outcome?: "unknown" | "running" | "failed" | "succeeded" | "partial" | "loop" | "abandoned" | undefined;
+    outcome?: "unknown" | "loop" | "running" | "failed" | "succeeded" | "partial" | "abandoned" | undefined;
     class_id?: string | undefined;
 }, {
     time_range?: "all" | "1h" | "3d" | "7d" | "24h" | "30d" | "90d" | undefined;
     limit?: number | undefined;
     offset?: number | undefined;
     user_id?: string | undefined;
-    outcome?: "unknown" | "running" | "failed" | "succeeded" | "partial" | "loop" | "abandoned" | undefined;
+    outcome?: "unknown" | "loop" | "running" | "failed" | "succeeded" | "partial" | "abandoned" | undefined;
     class_id?: string | undefined;
 }>;
 /** moda run <runId> — single execution detail with side-effect receipts. */

package/dist/schemas.js

@@ -68,6 +68,16 @@ export const ToolFailureDetailSchema = z.object({
     include_window: boolFlag(),
     window: z.number().min(1).max(5).default(1).optional(),
 });
+/**
+ * moda audit <conversation_id|trace_id> — raw, non-deduped span/trace read.
+ * `kind=auto` (default) lets the backend try trace first, then conversation.
+ */
+export const AuditSchema = z.object({
+    id: z.string().min(1),
+    kind: z.enum(['auto', 'trace', 'conversation']).default('auto').optional(),
+    include_raw: boolFlag(),
+    limit: z.number().min(1).max(1000).default(200).optional(),
+});
 // ─── Workflows + Runs (agent runs runtime) ──────────────────
 //
 // Naming model:

package/package.json

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