@moda-ai/cli 1.9.6 → 1.10.0

package/dist/intelligence-schema.d.ts

@@ -0,0 +1,349 @@
+/**
+ * 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 declare const INTELLIGENCE_SCHEMA_VERSION: "moda.intelligence.v1";
+export type IntelligenceConfidence = 'high' | 'medium' | 'low' | 'unknown';
+/** Where the answer came from. `local_fallback` ⇒ degraded (lower trust). */
+export type IntelligenceSource = 'cloud' | 'local_fallback';
+/** How a signal was derived — a measured fact vs a model/heuristic estimate. */
+export type Provenance = 'measured' | 'inferred';
+/** Whether a suggested command reads, writes, or syncs state. */
+export type CommandMutability = 'read' | 'write' | 'sync' | 'unknown';
+/** Classification of a single quantitative/factual claim in the answer. */
+export type ClaimKind = 'percentage' | 'count' | 'qualitative';
+/**
+ * Verdict for one claim made in the answer, checked against the structured tool
+ * data the agent actually saw (MODA-377/378). `unverifiable` means the claim is
+ * not a checkable figure (or there was no tool data to check it against).
+ */
+export type ClaimStatus = 'grounded' | 'ungrounded' | 'unverifiable';
+export interface IntelligenceSummary {
+    text: string;
+    confidence: IntelligenceConfidence;
+}
+/**
+ * A structured locator so a surface can deep-link a piece of evidence. All
+ * fields optional — different evidence kinds populate different anchors.
+ */
+export interface EvidenceAnchor {
+    conversation_id?: string;
+    message_index?: number;
+    run_id?: string;
+    tool_name?: string;
+}
+export interface IntelligenceEvidenceRef {
+    /** Stable id, referenced by `findings[].evidence_ref_ids` and `answer_claims[].evidence_ref_ids`. */
+    id: string;
+    /** 'overview' | 'conversation' | 'message' | 'tool_failure' | 'run' | 'frustration' | 'cluster' | ... */
+    kind: string;
+    label: string;
+    anchor?: EvidenceAnchor;
+    /** Short human-readable excerpt of the underlying value. */
+    snippet?: string;
+    /** measured (exact) vs inferred (model-derived estimate) — MODA-379. */
+    grounding: Provenance;
+}
+/**
+ * A claim extracted from the answer with its grounding verdict. `value` is set
+ * for numeric claims; `evidence_ref_ids` links to the evidence that supports it
+ * (empty when ungrounded/unverifiable).
+ */
+export interface IntelligenceClaim {
+    text: string;
+    value?: number;
+    kind: ClaimKind;
+    status: ClaimStatus;
+    evidence_ref_ids: string[];
+    /** Path into the structured tool data where the value matched, when grounded. */
+    matched_path?: string;
+}
+export interface IntelligenceRecommendedAction {
+    id: string;
+    title: string;
+    rationale?: string;
+    command?: string;
+    mutability: CommandMutability;
+    requires_approval: boolean;
+}
+export interface IntelligenceFinding {
+    id: string;
+    title: string;
+    severity?: 'critical' | 'high' | 'medium' | 'low' | 'info';
+    description?: string;
+    evidence_ref_ids: string[];
+    recommended_actions: IntelligenceRecommendedAction[];
+}
+export interface IntelligenceNextCommand {
+    command: string;
+    purpose?: string;
+    mutability: CommandMutability;
+    requires_approval: boolean;
+}
+/**
+ * The canonical `moda.intelligence.v1` payload. Emitted by the backend ask
+ * endpoint and surfaced as the CLI agent envelope's `data` (and by `--json`).
+ */
+export interface ModaIntelligenceV1 {
+    schema_version: typeof INTELLIGENCE_SCHEMA_VERSION;
+    generated_at: string;
+    /** The originating command, e.g. "ask". */
+    command: string;
+    source: IntelligenceSource;
+    /** True when the answer was NOT produced by Moda Cloud intelligence. */
+    degraded: boolean;
+    question: string;
+    summary: IntelligenceSummary;
+    /** Full markdown answer (the human-facing narrative). */
+    answer_markdown: string;
+    /** Per-claim grounding verdicts (agent projection). */
+    answer_claims: IntelligenceClaim[];
+    /** Ranked findings; may be empty for a plain `ask`. */
+    findings: IntelligenceFinding[];
+    evidence_refs: IntelligenceEvidenceRef[];
+    next_commands: IntelligenceNextCommand[];
+    warnings: string[];
+    meta?: Record<string, 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 declare const MODA_INTELLIGENCE_V1_JSON_SCHEMA: {
+    readonly $schema: "http://json-schema.org/draft-07/schema#";
+    readonly $id: "moda.intelligence.v1";
+    readonly title: "Moda Intelligence v1";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["schema_version", "generated_at", "command", "source", "degraded", "question", "summary", "answer_markdown", "answer_claims", "findings", "evidence_refs", "next_commands", "warnings"];
+    readonly properties: {
+        readonly schema_version: {
+            readonly const: "moda.intelligence.v1";
+        };
+        readonly generated_at: {
+            readonly type: "string";
+            readonly format: "date-time";
+        };
+        readonly command: {
+            readonly type: "string";
+        };
+        readonly source: {
+            readonly type: "string";
+            readonly enum: readonly ["cloud", "local_fallback"];
+        };
+        readonly degraded: {
+            readonly type: "boolean";
+        };
+        readonly question: {
+            readonly type: "string";
+        };
+        readonly summary: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["text", "confidence"];
+            readonly properties: {
+                readonly text: {
+                    readonly type: "string";
+                };
+                readonly confidence: {
+                    readonly type: "string";
+                    readonly enum: readonly ["high", "medium", "low", "unknown"];
+                };
+            };
+        };
+        readonly answer_markdown: {
+            readonly type: "string";
+        };
+        readonly answer_claims: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["text", "kind", "status", "evidence_ref_ids"];
+                readonly properties: {
+                    readonly text: {
+                        readonly type: "string";
+                    };
+                    readonly value: {
+                        readonly type: "number";
+                    };
+                    readonly kind: {
+                        readonly type: "string";
+                        readonly enum: readonly ["percentage", "count", "qualitative"];
+                    };
+                    readonly status: {
+                        readonly type: "string";
+                        readonly enum: readonly ["grounded", "ungrounded", "unverifiable"];
+                    };
+                    readonly evidence_ref_ids: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly matched_path: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+        readonly findings: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["id", "title", "evidence_ref_ids", "recommended_actions"];
+                readonly properties: {
+                    readonly id: {
+                        readonly type: "string";
+                    };
+                    readonly title: {
+                        readonly type: "string";
+                    };
+                    readonly severity: {
+                        readonly type: "string";
+                        readonly enum: readonly ["critical", "high", "medium", "low", "info"];
+                    };
+                    readonly description: {
+                        readonly type: "string";
+                    };
+                    readonly evidence_ref_ids: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly recommended_actions: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly required: readonly ["id", "title", "mutability", "requires_approval"];
+                            readonly properties: {
+                                readonly id: {
+                                    readonly type: "string";
+                                };
+                                readonly title: {
+                                    readonly type: "string";
+                                };
+                                readonly rationale: {
+                                    readonly type: "string";
+                                };
+                                readonly command: {
+                                    readonly type: "string";
+                                };
+                                readonly mutability: {
+                                    readonly type: "string";
+                                    readonly enum: readonly ["read", "write", "sync", "unknown"];
+                                };
+                                readonly requires_approval: {
+                                    readonly type: "boolean";
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
+        readonly evidence_refs: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["id", "kind", "label", "grounding"];
+                readonly properties: {
+                    readonly id: {
+                        readonly type: "string";
+                    };
+                    readonly kind: {
+                        readonly type: "string";
+                    };
+                    readonly label: {
+                        readonly type: "string";
+                    };
+                    readonly anchor: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly properties: {
+                            readonly conversation_id: {
+                                readonly type: "string";
+                            };
+                            readonly message_index: {
+                                readonly type: "number";
+                            };
+                            readonly run_id: {
+                                readonly type: "string";
+                            };
+                            readonly tool_name: {
+                                readonly type: "string";
+                            };
+                        };
+                    };
+                    readonly snippet: {
+                        readonly type: "string";
+                    };
+                    readonly grounding: {
+                        readonly type: "string";
+                        readonly enum: readonly ["measured", "inferred"];
+                    };
+                };
+            };
+        };
+        readonly next_commands: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["command", "mutability", "requires_approval"];
+                readonly properties: {
+                    readonly command: {
+                        readonly type: "string";
+                    };
+                    readonly purpose: {
+                        readonly type: "string";
+                    };
+                    readonly mutability: {
+                        readonly type: "string";
+                        readonly enum: readonly ["read", "write", "sync", "unknown"];
+                    };
+                    readonly requires_approval: {
+                        readonly type: "boolean";
+                    };
+                };
+            };
+        };
+        readonly warnings: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly meta: {
+            readonly type: "object";
+        };
+    };
+};
+//# sourceMappingURL=intelligence-schema.d.ts.map

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,