@moda-ai/cli 1.9.6 → 1.10.0

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;

package/dist/cli.js

@@ -2,7 +2,7 @@
 import { z } from 'zod';
 import { validateConfig, VERSION, resolveApiKey } from './config.js';
 import { callDataAPI, ApiError, getApiRequestCount, resetApiRequestCount, } from './api-client.js';
-import { OverviewSchema, ClustersSchema, ClusterConversationsSchema, ConversationsSchema, SearchSchema, WorldStateSchema, ContextSchema, FrustrationsSchema, ToolFailuresSchema, ToolFailureDetailSchema, WorkflowsSchema, RunsSchema, RunDetailSchema, LoopsSchema, LoopDetailSchema, } from './schemas.js';
+import { OverviewSchema, ClustersSchema, ClusterConversationsSchema, ConversationsSchema, SearchSchema, WorldStateSchema, ContextSchema, AuditSchema, FrustrationsSchema, ToolFailuresSchema, ToolFailureDetailSchema, WorkflowsSchema, RunsSchema, RunDetailSchema, LoopsSchema, LoopDetailSchema, } from './schemas.js';
 import { withFrustrationAnchors, withToolFailureAnchors, embeddedWindowSize, asRecord, asString, asNumber } from './transforms.js';
 import { runPromptsCommand } from './prompts.js';
 // Coding-agent capture (shadow workspace / Shadow Spark / trace hooks) is temporarily
@@ -17,7 +17,8 @@ import { buildSearchAdoptionTelemetry, isTelemetryDisabled, SEARCH_MODES, sendCl
 import { isUpdateCheckDisabled, printUpdateNotice, startUpdateCheck, stripUpdateCheckFlag, } from './update-check.js';
 import { createCommandContext } from './command-context.js';
 import { createCommandRegistry } from './command-registry.js';
-import { createAgentErrorEnvelope, errorToAgentError, outputModeFromFlags, } from './output.js';
+import { createAgentErrorEnvelope, errorToAgentError, resolveOutputMode, } from './output.js';
+import { renderJsonSchemas } from './agent-schemas.js';
 import { runAuthCommand, runConfigCommand, runKeysCommand, runProfilesCommand } from './profile-commands.js';
 import { runAgentCommand } from './agent.js';
 import { runProductionCommand } from './production-intelligence.js';
@@ -51,6 +52,9 @@ export function parseArgs(argv) {
 const GLOBAL_BOOLEAN_FLAGS = new Set([
     'agent',
     'json',
+    'human',
+    'prose',
+    'json-schemas',
     'help',
     'version',
     'quiet',
@@ -140,6 +144,7 @@ Commands:
   search "<query>"                 Search conversation messages (keyword/semantic/hybrid)
   world-state <conversation_id>    Get a conversation's world state (slots/threads/events)
   context <conversation_id>        Get windowed conversation context
+  audit <conversation_id|trace_id> Raw span/trace audit (spans, hierarchy, orphans, duplicates)
   frustrations                     Get user frustration detections
   tool-failures                    Get tool failure overview
   tool-failure-detail <tool_name>  Get per-tool failure detail
@@ -169,6 +174,7 @@ Commands:
 Options:
   --help                           Show this help message
   --version                        Show version number
+  --json-schemas                   Print JSON Schemas for the agent output contract
 
 Common flags:
   --days-back=N                    Number of days to look back (1-90)
@@ -179,6 +185,13 @@ Common flags:
   --json                           Emit machine-readable JSON
   --agent                          Emit schema-versioned agent JSON
   --stream                         With --agent, emit NDJSON agent events
+  --human                          Force human prose (overrides auto-detection)
+
+Output auto-detection (no flags needed):
+  Piped/redirected stdout, CI, or an agent env (CLAUDECODE/CURSOR/MODA_AGENT)
+  => schema-versioned agent JSON. An interactive terminal => human prose.
+  Override with the flags above or MODA_FORMAT=human|json|agent|agent-stream.
+  Exit codes: 0 ok, 3 degraded (local fallback), 1 error.
   --dry-run                        Show the planned mutation when supported
   --yes                            Accept explicit automation defaults
   --tui                            Force the human analyst dashboard when supported
@@ -261,6 +274,8 @@ Examples:
   moda world-state <conversation_id> --summary-only
   moda frustrations --days-back=14 --limit=20
   moda context <conversation_id> --window=3
+  moda audit <conversation_id|trace_id>
+  moda audit <trace_id> --kind=trace --json
   moda workflows --time-range=7d
   moda runs --time-range=24h --outcome=partial
   moda runs --class-id=cron:helpscout-triage-hourly --limit=20
@@ -386,15 +401,13 @@ export async function runCommand(command, positional, flags, positionals = posit
         case 'overview': {
             const args = flagsToArgs(flags);
             OverviewSchema.parse(args);
-            await runProductionCommand(context);
-            break;
+            return (await runProductionCommand(context)).exitCode;
         }
         case 'investigate':
         case 'failures':
         case 'why-failed':
         case 'ask': {
-            await runProductionCommand(context);
-            break;
+            return (await runProductionCommand(context)).exitCode;
         }
         case 'clusters': {
             const args = flagsToArgs(flags);
@@ -519,6 +532,25 @@ export async function runCommand(command, positional, flags, positionals = posit
             context.output.writeData(data);
             break;
         }
+        case 'audit':
+        case 'trace': {
+            if (!positional) {
+                throw new CliInputError('<conversation_id|trace_id> is required', 'Usage: moda audit <conversation_id|trace_id> [--kind=auto|trace|conversation] [--include-raw] [--limit=N]');
+            }
+            const args = flagsToArgs(flags, 'id', positional);
+            const params = AuditSchema.parse(args);
+            const query = new URLSearchParams();
+            if (params.kind && params.kind !== 'auto')
+                query.set('kind', params.kind);
+            if (params.include_raw === true)
+                query.set('include_raw', '1');
+            if (params.limit)
+                query.set('limit', params.limit.toString());
+            const queryString = query.toString() ? `?${query.toString()}` : '';
+            const data = await callDataAPI(`/audit/${encodeURIComponent(params.id)}${queryString}`);
+            context.output.writeData(data);
+            break;
+        }
         case 'frustrations': {
             const args = flagsToArgs(flags);
             const params = FrustrationsSchema.parse(args);
@@ -631,13 +663,14 @@ export async function runCommand(command, positional, flags, positionals = posit
         default:
             throw new CliInputError(`Unknown command '${command}'`, 'Run "moda --help" for usage information.');
     }
+    return 0;
 }
 function legacyCommand(metadata) {
     return {
         ...metadata,
         handler: async (context) => {
-            await runCommand(context.command, context.positional, context.flags, context.positionals, context);
-            return { exitCode: 0 };
+            const exitCode = await runCommand(context.command, context.positional, context.flags, context.positionals, context);
+            return { exitCode };
         },
     };
 }
@@ -952,6 +985,17 @@ export const commandRegistry = createCommandRegistry([
         examples: ['moda context <conversation_id> --window=3'],
         ...dataApiDefaults,
     }),
+    legacyCommand({
+        name: 'audit',
+        aliases: ['trace'],
+        description: 'Raw non-deduped span/trace audit (hierarchy, tool spans, orphans, duplicates)',
+        examples: [
+            'moda audit <conversation_id|trace_id>',
+            'moda audit <trace_id> --kind=trace --json',
+            'moda audit <conversation_id> --include-raw',
+        ],
+        ...dataApiDefaults,
+    }),
     legacyCommand({
         name: 'frustrations',
         description: 'Get user frustration detections',
@@ -1139,6 +1183,10 @@ export async function dispatchParsedCommand(parsed, startedAt = Date.now()) {
         printHelp();
         return 0;
     }
+    if (command === '--json-schemas' || flags['json-schemas'] === 'true') {
+        console.log(renderJsonSchemas());
+        return 0;
+    }
     if (!command) {
         printHelp();
         return 1;
@@ -1146,7 +1194,11 @@ export async function dispatchParsedCommand(parsed, startedAt = Date.now()) {
     const definition = commandRegistry.find(command);
     if (!definition) {
         const error = new CliInputError(`Unknown command '${command}'`, 'Run "moda --help" for usage information.');
-        if (outputModeFromFlags(commandFlags) === 'agent' || outputModeFromFlags(commandFlags) === 'agent-stream') {
+        const mode = resolveOutputMode(commandFlags, {
+            isTTY: process.stdout.isTTY,
+            env: process.env,
+        });
+        if (mode === 'agent' || mode === 'agent-stream') {
             printAgentCliError(command, error);
         }
         else {
@@ -1173,6 +1225,13 @@ export async function dispatchParsedCommand(parsed, startedAt = Date.now()) {
         commandFlags,
         rawFlags: flags,
         startedAt,
+        // Agent-safe output auto-selection happens here (not in createCommandContext)
+        // so direct callers/tests keep flag-only behavior. We resolve from the real
+        // stdout TTY + environment, leaving `commandFlags` (and telemetry) untouched.
+        outputMode: resolveOutputMode(commandFlags, {
+            isTTY: process.stdout.isTTY,
+            env: process.env,
+        }),
     });
     try {
         const result = await definition.handler(context);

package/dist/command-context.d.ts

@@ -45,5 +45,11 @@ export declare function createCommandContext(input: CommandContextInput, options
     startedAt?: number;
     cwd?: string;
     env?: NodeJS.ProcessEnv;
+    /**
+     * Pre-resolved output mode from the dispatcher (TTY/env auto-detection).
+     * When omitted we fall back to flag-only resolution so direct callers
+     * (tests, internal helpers) keep their explicit behavior.
+     */
+    outputMode?: CliOutputMode;
 }): CommandContext;
 //# sourceMappingURL=command-context.d.ts.map

package/dist/command-context.js

@@ -5,7 +5,7 @@ function flagEnabled(flags, key) {
 export function createCommandContext(input, options = {}) {
     const flags = options.commandFlags ?? input.flags;
     const rawFlags = options.rawFlags ?? input.flags;
-    const outputMode = outputModeFromFlags(flags);
+    const outputMode = options.outputMode ?? outputModeFromFlags(flags);
     const quiet = flagEnabled(flags, 'quiet');
     const interactive = outputMode === 'human' &&
         !quiet &&