@moda-ai/cli 1.9.6 → 1.10.1

package/README.md

@@ -58,12 +58,6 @@ moda tool-failures                               # Tool failure overview
 moda tool-failure-detail <tool_name>             # Per-tool failure detail
 moda tool-failure-detail <tool_name> --include-window --window=1
 
-# Agent runs runtime (workflows = recurring class, run = one execution)
-moda workflows --time-range=7d                   # Recurring workflow catalog with health
-moda runs                                        # Last 7d of workflow executions
-moda runs --time-range=24h --outcome=partial     # Last 24h, partial completions only
-moda runs --class-id=cron:helpscout-triage-hourly # Scoped to one workflow class
-moda run <run_id>                                # One execution + its side-effect receipts
 moda loops                                       # Currently-active loop detections
 moda loop <detection_id>                         # One loop detail (signature + blast radius)
 
@@ -81,9 +75,7 @@ All commands output JSON. Pipe to `jq` for filtering:
 ```bash
 moda overview | jq '.frustrations'
 moda frustrations | jq '.frustrations[].primary_cause'
-moda runs --outcome=partial | jq '.runs[] | {job_id, intent_summary, outcome_reason}'
 moda loops | jq '.loops | sort_by(-.cycle_visits) | .[0:5] | .[].loop_signature_human'
-moda workflows | jq '.workflows | sort_by(.health) | .[] | select(.health < 0.8)'
 ```
 
 ## Prompt Management

package/dist/agent-schemas.d.ts

@@ -0,0 +1,3 @@
+export declare const AGENT_JSON_SCHEMAS: Record<string, unknown>;
+export declare function renderJsonSchemas(): string;
+//# sourceMappingURL=agent-schemas.d.ts.map

package/dist/agent-schemas.js

@@ -0,0 +1,298 @@
+// agent-schemas.ts
+//
+// Machine-readable JSON Schemas (JSON Schema draft-07) for the moda CLI's
+// agent output contract. It is consumed by `moda --json-schemas`, which prints
+// the document produced by `renderJsonSchemas()` so an external coding agent can
+// introspect the exact shape of moda's agent-mode output.
+//
+// The canonical `moda.intelligence.v1` schema is imported from its
+// single-source-of-truth module rather than re-declared here, so the published
+// contract can never drift from the runtime payload.
+//
+// Keep these schemas in sync with:
+//   - AgentEnvelope / AgentEvent in ./output.ts          (moda.agent.v1 / moda.agent_event.v1)
+//   - ProductionAskResult in ./production-intelligence.ts (production_ask.v0.1)
+//   - ModaIntelligenceV1 in ./intelligence-schema.ts      (moda.intelligence.v1)
+import { MODA_INTELLIGENCE_V1_JSON_SCHEMA } from './intelligence-schema.js';
+const agentSummarySchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['text', 'confidence'],
+    properties: {
+        text: { type: 'string' },
+        confidence: { type: 'string', enum: ['high', 'medium', 'low', 'unknown'] },
+    },
+};
+const agentFindingSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['id', 'title'],
+    properties: {
+        id: { type: 'string' },
+        title: { type: 'string' },
+        status: { type: 'string' },
+        severity: { type: 'string' },
+        description: { type: 'string' },
+        evidence_ref_ids: { type: 'array', items: { type: 'string' } },
+    },
+};
+const agentEvidenceRefSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['id', 'kind', 'label'],
+    properties: {
+        id: { type: 'string' },
+        kind: { type: 'string' },
+        label: { type: 'string' },
+        path: { type: 'string' },
+        line: { type: 'number' },
+        status: { type: 'string' },
+    },
+};
+const agentRecommendedActionSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['id', 'title', 'mutability', 'requires_approval'],
+    properties: {
+        id: { type: 'string' },
+        title: { type: 'string' },
+        rationale: { type: 'string' },
+        command: { type: 'string' },
+        mutability: { type: 'string', enum: ['read', 'write', 'sync', 'unknown'] },
+        requires_approval: { type: 'boolean' },
+    },
+};
+const agentNextCommandSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['command', 'purpose', 'mutability', 'requires_approval'],
+    properties: {
+        command: { type: 'string' },
+        purpose: { type: 'string' },
+        mutability: { type: 'string', enum: ['read', 'write', 'sync', 'unknown'] },
+        requires_approval: { type: 'boolean' },
+    },
+};
+const agentArtifactSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['kind', 'path'],
+    properties: {
+        kind: { type: 'string' },
+        path: { type: 'string' },
+        description: { type: 'string' },
+    },
+};
+const agentErrorSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['code', 'message', 'blocking'],
+    properties: {
+        code: { type: 'string' },
+        message: { type: 'string' },
+        cause: { type: 'string' },
+        suggested_commands: { type: 'array', items: { type: 'string' } },
+        blocking: { type: 'boolean' },
+    },
+};
+const agentEnvelopeSchema = {
+    $id: 'moda.agent.v1',
+    title: 'AgentEnvelope',
+    description: 'Top-level agent-mode output envelope emitted by the moda CLI.',
+    type: 'object',
+    additionalProperties: false,
+    required: [
+        'schema_version',
+        'command',
+        'status',
+        'generated_at',
+        'summary',
+        'findings',
+        'evidence_refs',
+        'recommended_actions',
+        'next_commands',
+        'artifacts',
+        'warnings',
+        'errors',
+        'data',
+    ],
+    properties: {
+        schema_version: { type: 'string', const: 'moda.agent.v1' },
+        command: { type: 'string' },
+        status: { type: 'string', enum: ['ok', 'degraded', 'error'] },
+        generated_at: { type: 'string', format: 'date-time' },
+        profile: { type: 'string' },
+        summary: agentSummarySchema,
+        findings: { type: 'array', items: agentFindingSchema },
+        evidence_refs: { type: 'array', items: agentEvidenceRefSchema },
+        recommended_actions: { type: 'array', items: agentRecommendedActionSchema },
+        next_commands: { type: 'array', items: agentNextCommandSchema },
+        artifacts: { type: 'array', items: agentArtifactSchema },
+        warnings: { type: 'array', items: { type: 'string' } },
+        errors: { type: 'array', items: agentErrorSchema },
+        data: { description: 'Command-specific payload. Shape varies by command.', additionalProperties: true },
+        meta: { type: 'object', additionalProperties: true },
+        truncation: { type: 'object', additionalProperties: true },
+    },
+};
+const agentEventSchema = {
+    $id: 'moda.agent_event.v1',
+    title: 'AgentEvent',
+    description: 'Streaming NDJSON event emitted in agent-stream mode by the moda CLI.',
+    type: 'object',
+    additionalProperties: false,
+    required: ['schema_version', 'event', 'command', 'generated_at'],
+    properties: {
+        schema_version: { type: 'string', const: 'moda.agent_event.v1' },
+        event: {
+            type: 'string',
+            enum: ['started', 'progress', 'artifact', 'approval_required', 'completed', 'error'],
+        },
+        command: { type: 'string' },
+        generated_at: { type: 'string', format: 'date-time' },
+        status: { type: 'string', enum: ['ok', 'degraded', 'error'] },
+        phase: { type: 'string' },
+        message: { type: 'string' },
+        elapsed_ms: { type: 'number' },
+        artifact: agentArtifactSchema,
+        result: agentEnvelopeSchema,
+        error: agentErrorSchema,
+    },
+};
+const productionEvidenceRefSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['id', 'kind', 'label'],
+    properties: {
+        id: { type: 'string' },
+        kind: {
+            type: 'string',
+            enum: ['data_api', 'tool_failure', 'frustration', 'loop', 'run', 'harness', 'ask'],
+        },
+        label: { type: 'string' },
+        endpoint: { type: 'string' },
+        conversationId: { type: 'string' },
+        runId: { type: 'string' },
+        detectionId: { type: 'string' },
+        toolName: { type: 'string' },
+        path: { type: 'string' },
+        line: { type: 'number' },
+        value: { description: 'Arbitrary evidence payload.', additionalProperties: true },
+    },
+};
+const likelyLocationSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['kind', 'label', 'confidence', 'reason'],
+    properties: {
+        kind: { type: 'string', enum: ['tool', 'prompt', 'skill', 'entrypoint', 'harness', 'unknown'] },
+        path: { type: 'string' },
+        label: { type: 'string' },
+        confidence: { type: 'string', enum: ['high', 'medium', 'low', 'unknown'] },
+        reason: { type: 'string' },
+    },
+};
+const productionActionSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['id', 'title', 'rationale', 'command', 'mutability', 'requiresApproval'],
+    properties: {
+        id: { type: 'string' },
+        title: { type: 'string' },
+        rationale: { type: 'string' },
+        command: { type: 'string' },
+        mutability: { type: 'string', enum: ['read', 'write', 'sync', 'unknown'] },
+        requiresApproval: { type: 'boolean' },
+    },
+};
+const productionFindingSchema = {
+    type: 'object',
+    additionalProperties: false,
+    required: [
+        'id',
+        'kind',
+        'title',
+        'severity',
+        'confidence',
+        'impactScore',
+        'rankReason',
+        'summary',
+        'evidenceRefIds',
+        'likelyLocations',
+        'recommendedActions',
+    ],
+    properties: {
+        id: { type: 'string' },
+        kind: {
+            type: 'string',
+            enum: [
+                'tool_failure',
+                'loop',
+                'frustration',
+                'partial_run',
+                'prompt_regression',
+                'skill_gap',
+                'insufficient_data',
+            ],
+        },
+        title: { type: 'string' },
+        severity: { type: 'string', enum: ['critical', 'high', 'medium', 'low', 'info'] },
+        confidence: { type: 'string', enum: ['high', 'medium', 'low', 'unknown'] },
+        impactScore: { type: 'number' },
+        rankReason: { type: 'string' },
+        summary: { type: 'string' },
+        evidenceRefIds: { type: 'array', items: { type: 'string' } },
+        likelyLocations: { type: 'array', items: likelyLocationSchema },
+        recommendedActions: { type: 'array', items: productionActionSchema },
+    },
+};
+const productionAskResultSchema = {
+    $id: 'production_ask.v0.1',
+    title: 'ProductionAskResult',
+    description: 'Result payload for `moda ask`, sourced from cloud intelligence or local fallback.',
+    type: 'object',
+    additionalProperties: false,
+    required: [
+        'schemaVersion',
+        'generatedAt',
+        'source',
+        'question',
+        'answer',
+        'confidence',
+        'evidenceRefs',
+        'findings',
+        'nextCommands',
+        'warnings',
+        'degraded',
+    ],
+    properties: {
+        schemaVersion: { type: 'string', const: 'production_ask.v0.1' },
+        generatedAt: { type: 'string', format: 'date-time' },
+        source: { type: 'string', enum: ['cloud', 'local_fallback'] },
+        question: { type: 'string' },
+        answer: { type: 'string' },
+        confidence: { type: 'string', enum: ['high', 'medium', 'low', 'unknown'] },
+        evidenceRefs: { type: 'array', items: productionEvidenceRefSchema },
+        findings: { type: 'array', items: productionFindingSchema },
+        nextCommands: { type: 'array', items: { type: 'string' } },
+        warnings: { type: 'array', items: { type: 'string' } },
+        degraded: { type: 'boolean' },
+    },
+};
+export const AGENT_JSON_SCHEMAS = {
+    'moda.agent.v1': agentEnvelopeSchema,
+    'moda.agent_event.v1': agentEventSchema,
+    // Canonical unified payload (MODA-388). Now the shape of the ask command's
+    // agent `data`. The legacy `production_ask.v0.1` schema is kept for
+    // back-compat with older agent integrations.
+    'moda.intelligence.v1': MODA_INTELLIGENCE_V1_JSON_SCHEMA,
+    'production_ask.v0.1': productionAskResultSchema,
+};
+export function renderJsonSchemas() {
+    return JSON.stringify({
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        generated_by: 'moda-cli',
+        schemas: AGENT_JSON_SCHEMAS,
+    }, null, 2);
+}
+//# sourceMappingURL=agent-schemas.js.map

package/dist/api-client.d.ts

@@ -5,7 +5,18 @@ export declare class ApiError extends Error {
     constructor(message: string, statusCode: number, responseBody: string);
 }
 export declare function callDataAPI(endpoint: string): Promise<unknown>;
-export declare function callControlAPI(endpoint: string, options?: RequestInit, profileOptions?: ProfileIOOptions): Promise<unknown>;
+/**
+ * Per-call transport overrides. Used by expensive, long-running, non-idempotent
+ * endpoints (e.g. the agent `ask` POST) that need a longer timeout than the
+ * default and must NOT be retried on timeout.
+ */
+export interface ModaRequestOptions {
+    /** Abort timeout in ms for each attempt (default REQUEST_TIMEOUT_MS). */
+    timeoutMs?: number;
+    /** Max retries (default MAX_RETRIES). Set 0 to disable retries entirely. */
+    retries?: number;
+}
+export declare function callControlAPI(endpoint: string, options?: RequestInit, profileOptions?: ProfileIOOptions, requestOptions?: ModaRequestOptions): Promise<unknown>;
 export declare function getApiRequestCount(): number;
 export declare function resetApiRequestCount(): void;
 //# sourceMappingURL=api-client.d.ts.map

package/dist/api-client.js

@@ -22,19 +22,21 @@ export async function callDataAPI(endpoint) {
     const url = `${resolveModaBaseUrl()}/api/v1/data${endpoint}`;
     return callModaAPI(url, { method: 'GET' });
 }
-export async function callControlAPI(endpoint, options = {}, profileOptions = {}) {
+export async function callControlAPI(endpoint, options = {}, profileOptions = {}, requestOptions = {}) {
     const url = `${resolveModaBaseUrl(profileOptions)}/api${endpoint}`;
-    return callModaAPI(url, options, profileOptions);
+    return callModaAPI(url, options, profileOptions, requestOptions);
 }
-async function callModaAPI(url, options, profileOptions = {}) {
+async function callModaAPI(url, options, profileOptions = {}, requestOptions = {}) {
+    const timeoutMs = requestOptions.timeoutMs ?? REQUEST_TIMEOUT_MS;
+    const maxRetries = requestOptions.retries ?? MAX_RETRIES;
     let lastError;
-    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
         if (attempt > 0) {
             const backoff = INITIAL_BACKOFF_MS * Math.pow(2, attempt - 1);
             await new Promise((resolve) => setTimeout(resolve, backoff));
         }
         const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
         try {
             const response = await fetch(url, {
                 ...options,
@@ -48,7 +50,7 @@ async function callModaAPI(url, options, profileOptions = {}) {
             if (!response.ok) {
                 const errorText = await response.text();
                 const error = new ApiError(`API error (${response.status}): ${errorText}`, response.status, errorText);
-                if (isRetryable(response.status) && attempt < MAX_RETRIES) {
+                if (isRetryable(response.status) && attempt < maxRetries) {
                     lastError = error;
                     continue;
                 }
@@ -61,9 +63,9 @@ async function callModaAPI(url, options, profileOptions = {}) {
                 throw error;
             const isAbort = error instanceof DOMException && error.name === 'AbortError';
             const wrapped = new Error(isAbort
-                ? `Request timed out after ${REQUEST_TIMEOUT_MS}ms: ${url}`
+                ? `Request timed out after ${timeoutMs}ms: ${url}`
                 : `Network error: ${error instanceof Error ? error.message : String(error)}`);
-            if (attempt < MAX_RETRIES) {
+            if (attempt < maxRetries) {
                 lastError = wrapped;
                 continue;
             }

package/dist/cli.d.ts

@@ -11,7 +11,7 @@ export interface ParsedArgs {
 }
 export declare function parseArgs(argv: string[]): ParsedArgs;
 export declare function flagsToArgs(flags: Record<string, string>, positionalKey?: string, positionalValue?: string): Record<string, unknown>;
-export declare function runCommand(command: string, positional: string | undefined, flags: Record<string, string>, positionals?: string[], context?: CommandContext): Promise<void>;
+export declare function runCommand(command: string, positional: string | undefined, flags: Record<string, string>, positionals?: string[], context?: CommandContext): Promise<number>;
 interface CommandDispatchResult {
     exitCode: number;
     apiKey?: string;