@moda-ai/cli 1.9.6 → 1.10.1

package/dist/intelligence-schema.js

@@ -0,0 +1,174 @@
+/**
+ * moda.intelligence.v1 — the unified Moda intelligence wire format (MODA-388).
+ *
+ * ONE versioned payload that every surface projects from:
+ *   - CLI `moda ask --json` / `--agent` (the agent-facing contract),
+ *   - the backend `POST /api/cli/ask` response,
+ *   - the (future) MCP server's `structuredContent`,
+ *   - the dashboard UI.
+ *
+ * Design rules:
+ *   - snake_case everywhere (no mixed casing — the prior split between the
+ *     snake_case envelope and the camelCase `production_ask.v0.1` data payload
+ *     was the main source of agent-integration pain).
+ *   - It is a SUPERSET. Differentiation between a human reader and an agent is a
+ *     RENDERING concern at the edge, not a forked schema:
+ *       · human projection  → narrative `answer_markdown`, `summary.confidence`
+ *                             as a word, raw ids/anchors hidden.
+ *       · agent projection  → full `evidence_refs` (with `anchor` + `grounding`),
+ *                             `answer_claims` (claim → evidence), structured
+ *                             `next_commands`.
+ *   - Additive evolution only within v1; breaking changes bump the version.
+ *
+ * This module is the SINGLE SOURCE OF TRUTH for the shape. The backend mirrors
+ * these field names on the wire and the contract tests validate real CLI output
+ * against {@link MODA_INTELLIGENCE_V1_JSON_SCHEMA}.
+ */
+export const INTELLIGENCE_SCHEMA_VERSION = 'moda.intelligence.v1';
+// ───────────────────────────── JSON Schema (draft-07) ─────────────────────────
+const provenanceSchema = { type: 'string', enum: ['measured', 'inferred'] };
+const mutabilitySchema = {
+    type: 'string',
+    enum: ['read', 'write', 'sync', 'unknown'],
+};
+const confidenceSchema = {
+    type: 'string',
+    enum: ['high', 'medium', 'low', 'unknown'],
+};
+/**
+ * Published draft-07 JSON Schema for {@link ModaIntelligenceV1}. This is what
+ * `moda --json-schemas` emits and what the contract tests validate CLI/backend
+ * output against. Keep in lockstep with the interfaces above.
+ */
+export const MODA_INTELLIGENCE_V1_JSON_SCHEMA = {
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    $id: 'moda.intelligence.v1',
+    title: 'Moda Intelligence v1',
+    type: 'object',
+    additionalProperties: false,
+    required: [
+        'schema_version',
+        'generated_at',
+        'command',
+        'source',
+        'degraded',
+        'question',
+        'summary',
+        'answer_markdown',
+        'answer_claims',
+        'findings',
+        'evidence_refs',
+        'next_commands',
+        'warnings',
+    ],
+    properties: {
+        schema_version: { const: 'moda.intelligence.v1' },
+        generated_at: { type: 'string', format: 'date-time' },
+        command: { type: 'string' },
+        source: { type: 'string', enum: ['cloud', 'local_fallback'] },
+        degraded: { type: 'boolean' },
+        question: { type: 'string' },
+        summary: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['text', 'confidence'],
+            properties: { text: { type: 'string' }, confidence: confidenceSchema },
+        },
+        answer_markdown: { type: 'string' },
+        answer_claims: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['text', 'kind', 'status', 'evidence_ref_ids'],
+                properties: {
+                    text: { type: 'string' },
+                    value: { type: 'number' },
+                    kind: { type: 'string', enum: ['percentage', 'count', 'qualitative'] },
+                    status: {
+                        type: 'string',
+                        enum: ['grounded', 'ungrounded', 'unverifiable'],
+                    },
+                    evidence_ref_ids: { type: 'array', items: { type: 'string' } },
+                    matched_path: { type: 'string' },
+                },
+            },
+        },
+        findings: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['id', 'title', 'evidence_ref_ids', 'recommended_actions'],
+                properties: {
+                    id: { type: 'string' },
+                    title: { type: 'string' },
+                    severity: {
+                        type: 'string',
+                        enum: ['critical', 'high', 'medium', 'low', 'info'],
+                    },
+                    description: { type: 'string' },
+                    evidence_ref_ids: { type: 'array', items: { type: 'string' } },
+                    recommended_actions: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            required: ['id', 'title', 'mutability', 'requires_approval'],
+                            properties: {
+                                id: { type: 'string' },
+                                title: { type: 'string' },
+                                rationale: { type: 'string' },
+                                command: { type: 'string' },
+                                mutability: mutabilitySchema,
+                                requires_approval: { type: 'boolean' },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+        evidence_refs: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['id', 'kind', 'label', 'grounding'],
+                properties: {
+                    id: { type: 'string' },
+                    kind: { type: 'string' },
+                    label: { type: 'string' },
+                    anchor: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            conversation_id: { type: 'string' },
+                            message_index: { type: 'number' },
+                            run_id: { type: 'string' },
+                            tool_name: { type: 'string' },
+                        },
+                    },
+                    snippet: { type: 'string' },
+                    grounding: provenanceSchema,
+                },
+            },
+        },
+        next_commands: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['command', 'mutability', 'requires_approval'],
+                properties: {
+                    command: { type: 'string' },
+                    purpose: { type: 'string' },
+                    mutability: mutabilitySchema,
+                    requires_approval: { type: 'boolean' },
+                },
+            },
+        },
+        warnings: { type: 'array', items: { type: 'string' } },
+        meta: { type: 'object' },
+    },
+};
+//# sourceMappingURL=intelligence-schema.js.map

package/dist/output.d.ts

@@ -1,7 +1,18 @@
 export type CliOutputMode = 'human' | 'json' | 'agent' | 'agent-stream';
 export declare const AGENT_SCHEMA_VERSION = "moda.agent.v1";
 export declare const AGENT_EVENT_SCHEMA_VERSION = "moda.agent_event.v1";
-export type AgentStatus = 'ok' | 'error';
+/**
+ * Stable process exit codes that an external agent can branch on:
+ *   0  ok        — grounded answer from Moda Cloud intelligence.
+ *   3  degraded  — answer produced from a local/degraded fallback (lower trust).
+ *   1  error     — command/input/unexpected failure (see envelope `errors[]`).
+ * `EXIT_DEGRADED` is intentionally distinct so a caller can tell a degraded
+ * answer apart from both success and hard failure without parsing the payload.
+ */
+export declare const EXIT_OK = 0;
+export declare const EXIT_ERROR = 1;
+export declare const EXIT_DEGRADED = 3;
+export type AgentStatus = 'ok' | 'degraded' | 'error';
 export type AgentConfidence = 'high' | 'medium' | 'low' | 'unknown';
 export interface AgentSummary {
     text: string;
@@ -94,12 +105,24 @@ export interface CliOutput {
     mode: CliOutputMode;
     quiet: boolean;
     writeData(data: unknown, options?: {
-        status?: 'success' | 'error';
+        status?: 'success' | 'degraded' | 'error';
         meta?: Record<string, unknown>;
     } & AgentWriteOptions): void;
     writeEvent(event: Omit<AgentEvent, 'schema_version' | 'command' | 'generated_at'>): void;
 }
+/** Flag-only resolution (default human). Kept for callers that only have flags. */
 export declare function outputModeFromFlags(flags: Record<string, string>): CliOutputMode;
+/**
+ * Resolve the effective output mode for a real CLI invocation, in priority
+ * order: explicit flags -> `MODA_FORMAT` -> agent-environment detection ->
+ * TTY detection (piped/redirected => agent JSON) -> human prose. This is what
+ * makes the CLI agent-safe: a piped/automated caller gets structured output
+ * with zero flags, while a human at a terminal still gets prose.
+ */
+export declare function resolveOutputMode(flags: Record<string, string>, opts?: {
+    isTTY?: boolean;
+    env?: NodeJS.ProcessEnv;
+}): CliOutputMode;
 export declare function createCliOutput(options: {
     command: string;
     mode: CliOutputMode;

package/dist/output.js

@@ -1,12 +1,77 @@
 export const AGENT_SCHEMA_VERSION = 'moda.agent.v1';
 export const AGENT_EVENT_SCHEMA_VERSION = 'moda.agent_event.v1';
-export function outputModeFromFlags(flags) {
+/**
+ * Stable process exit codes that an external agent can branch on:
+ *   0  ok        — grounded answer from Moda Cloud intelligence.
+ *   3  degraded  — answer produced from a local/degraded fallback (lower trust).
+ *   1  error     — command/input/unexpected failure (see envelope `errors[]`).
+ * `EXIT_DEGRADED` is intentionally distinct so a caller can tell a degraded
+ * answer apart from both success and hard failure without parsing the payload.
+ */
+export const EXIT_OK = 0;
+export const EXIT_ERROR = 1;
+export const EXIT_DEGRADED = 3;
+/**
+ * Output mode requested by explicit flags only, or `undefined` when the caller
+ * did not pick one. Explicit flags always win over auto-detection.
+ */
+function explicitModeFromFlags(flags) {
     if (flags.agent === 'true' && (flags.stream === 'true' || flags.format === 'ndjson'))
         return 'agent-stream';
     if (flags.agent === 'true')
         return 'agent';
     if (flags.json === 'true')
         return 'json';
+    if (flags.human === 'true' || flags.prose === 'true')
+        return 'human';
+    return undefined;
+}
+/** Flag-only resolution (default human). Kept for callers that only have flags. */
+export function outputModeFromFlags(flags) {
+    return explicitModeFromFlags(flags) ?? 'human';
+}
+function outputModeFromEnv(env) {
+    const fmt = (env.MODA_FORMAT ?? '').trim().toLowerCase();
+    if (fmt === 'human' || fmt === 'json' || fmt === 'agent')
+        return fmt;
+    if (fmt === 'agent-stream' || fmt === 'ndjson')
+        return 'agent-stream';
+    return undefined;
+}
+function truthyEnv(value) {
+    return value != null && value !== '' && value !== '0' && value.toLowerCase() !== 'false';
+}
+/**
+ * True when the process appears to be driven by an agent / automation rather
+ * than an interactive human (Claude Code, Cursor, generic CI, or an explicit
+ * `MODA_AGENT` opt-in). Such callers get machine-parseable output by default.
+ */
+function isAgentEnvironment(env) {
+    return (truthyEnv(env.CLAUDECODE) ||
+        truthyEnv(env.CURSOR) ||
+        truthyEnv(env.CI) ||
+        truthyEnv(env.MODA_AGENT));
+}
+/**
+ * Resolve the effective output mode for a real CLI invocation, in priority
+ * order: explicit flags -> `MODA_FORMAT` -> agent-environment detection ->
+ * TTY detection (piped/redirected => agent JSON) -> human prose. This is what
+ * makes the CLI agent-safe: a piped/automated caller gets structured output
+ * with zero flags, while a human at a terminal still gets prose.
+ */
+export function resolveOutputMode(flags, opts = {}) {
+    const explicit = explicitModeFromFlags(flags);
+    if (explicit)
+        return explicit;
+    const env = opts.env ?? process.env;
+    const fromEnv = outputModeFromEnv(env);
+    if (fromEnv)
+        return fromEnv;
+    if (isAgentEnvironment(env))
+        return 'agent';
+    const isTTY = opts.isTTY ?? Boolean(process.stdout.isTTY);
+    if (!isTTY)
+        return 'agent';
     return 'human';
 }
 export function createCliOutput(options) {
@@ -19,7 +84,11 @@ export function createCliOutput(options) {
             if (options.mode === 'agent' || options.mode === 'agent-stream') {
                 const envelope = createAgentEnvelope({
                     command: options.command,
-                    status: writeOptions.status === 'error' ? 'error' : 'ok',
+                    status: writeOptions.status === 'error'
+                        ? 'error'
+                        : writeOptions.status === 'degraded'
+                            ? 'degraded'
+                            : 'ok',
                     data,
                     meta: writeOptions.meta,
                     summary: writeOptions.summary,

package/dist/production-intelligence.d.ts

@@ -1,13 +1,14 @@
 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";
 type Severity = 'critical' | 'high' | 'medium' | 'low' | 'info';
-type FindingKind = 'tool_failure' | 'loop' | 'frustration' | 'partial_run' | 'prompt_regression' | 'skill_gap' | 'insufficient_data';
+type FindingKind = 'tool_failure' | 'loop' | 'frustration' | 'prompt_regression' | 'skill_gap' | 'insufficient_data';
 export interface ProductionEvidenceRef {
     id: string;
-    kind: 'data_api' | 'tool_failure' | 'frustration' | 'loop' | 'run' | 'harness' | 'ask';
+    kind: 'data_api' | 'tool_failure' | 'frustration' | 'loop' | 'harness' | 'ask';
     label: string;
     endpoint?: string;
     conversationId?: string;
@@ -51,7 +52,6 @@ export interface ProductionInvestigation {
     generatedAt: string;
     daysBack: number;
     scope: {
-        runId?: string;
         conversationId?: string;
         toolName?: string;
         loopId?: string;
@@ -99,6 +99,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 +113,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;
@@ -117,7 +135,6 @@ export declare function loadOverviewBriefing(options: {
 export declare function investigateProduction(options: {
     daysBack: number;
     cwd: string;
-    runId?: string;
     conversationId?: string;
     toolName?: string;
     loopId?: string;