@outputai/cli 0.10.1-dev.b7b2fbe.0 → 0.10.1-next.14a191e.0

package/dist/commands/workflow/monitor.js

@@ -0,0 +1,230 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { fetchWorkflowHistory, fetchWorkflowHistoryUpdates } from '#services/workflow_history.js';
+import buildSpanLabels from '#utils/span_labels.js';
+import { formatDurationLabel } from '#utils/waterfall.js';
+import { diffSpanUpdates, formatContinuedAsNew, formatSpanUpdate } from '#utils/monitor_log.js';
+import { ERROR_STATUSES, TERMINAL_STATUSES } from '#utils/format_workflow_result.js';
+import { handleApiError } from '#utils/error_handler.js';
+import { getErrorMessage } from '#utils/error_utils.js';
+import { sleep } from '#utils/sleep.js';
+import { shouldColorize } from '#utils/color.js';
+import { HttpError } from '#api/http_client.js';
+const DEFAULT_INTERVAL_MS = 2500;
+const MAX_CONSECUTIVE_ERRORS = 5;
+const OUTPUT_FORMAT = { JSON: 'json', TEXT: 'text' };
+const SIGINT_EXIT_CODE = 130;
+const TRANSIENT_ERROR_CODES = new Set(['ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'EAI_AGAIN', 'ENOTFOUND']);
+/**
+ * Distinguishes blips worth retrying from errors that will fail identically on
+ * every attempt: network hiccups, a client-side request timeout, and 5xx/408/429
+ * responses are transient. Everything else — a 4xx like a stale/invalid resume
+ * cursor (`InvalidPageTokenError`, surfaced as 400), or a bug in correlate()/
+ * buildResult() re-throwing the same exception — can't self-resolve by waiting,
+ * so it should surface immediately instead of burning the retry budget.
+ */
+function isTransientPollError(error) {
+    if (error instanceof HttpError) {
+        const status = error.response.status;
+        return status >= 500 || status === 408 || status === 429;
+    }
+    const err = error;
+    if (err.name === 'TimeoutError') {
+        return true;
+    }
+    return Boolean((err.code && TRANSIENT_ERROR_CODES.has(err.code)) ||
+        (err.cause?.code && TRANSIENT_ERROR_CODES.has(err.cause.code)));
+}
+/**
+ * Unlike `run`/`status`/`result` (migrated to oclif's native `--json` in
+ * OUT-419, #281), this command deliberately keeps a custom `--format json`
+ * instead of `enableJsonFlag`. Native `--json` suppresses all `this.log()`
+ * calls and prints exactly one JSON object — the command's return value —
+ * after `run()` resolves. `monitor` has no single "return value": it emits a
+ * live stream of discrete events (span status changes, a continue-as-new
+ * notice, a final summary) while the workflow is still in progress, and
+ * `--format json` prints each as its own NDJSON line as it happens. That's
+ * the point — a caller (often another automated/agent process, not a human)
+ * can tail and parse the stream incrementally, which native `--json`'s
+ * "one object at the end" model can't do. See docs/guides/packages/cli.mdx
+ * ("output workflow monitor") for the same rationale written up for users.
+ */
+export default class WorkflowMonitor extends Command {
+    static description = 'Attach to a workflow run and stream status updates until it ends';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> wf-12345',
+        '<%= config.bin %> <%= command.id %> wf-12345 --run-id 2fe0b36b-...',
+        '<%= config.bin %> <%= command.id %> wf-12345 --format json'
+    ];
+    static args = {
+        workflowId: Args.string({
+            description: 'The workflow ID to monitor',
+            required: true
+        })
+    };
+    static flags = {
+        'run-id': Flags.string({
+            char: 'r',
+            description: 'Monitor a specific run (defaults to the latest run; continue-as-new chains are followed regardless)'
+        }),
+        format: Flags.string({
+            char: 'f',
+            description: 'Output format',
+            options: [OUTPUT_FORMAT.TEXT, OUTPUT_FORMAT.JSON],
+            default: OUTPUT_FORMAT.TEXT
+        }),
+        'include-payloads': Flags.boolean({
+            description: 'Include decoded step input/output payloads',
+            default: false
+        }),
+        interval: Flags.integer({
+            description: 'Poll interval in milliseconds. Once a resumed poll is long-polling ' +
+                'server-side for new events, this also bounds how long that block may last (capped ' +
+                'at the server\'s configured max), so an idle workflow\'s update cadence is roughly ' +
+                'twice this value (the long-poll bound, then this sleep) rather than a much longer, ' +
+                'separate server default.',
+            default: DEFAULT_INTERVAL_MS,
+            min: 1
+        }),
+        color: Flags.boolean({
+            description: 'Colorize status output (use --no-color to disable)',
+            default: true,
+            allowNo: true
+        })
+    };
+    async run() {
+        const { args, flags } = await this.parse(WorkflowMonitor);
+        const color = shouldColorize(flags.color);
+        const json = flags.format === OUTPUT_FORMAT.JSON;
+        // Threaded via mutable properties (not `let` reassignment) so state
+        // persists across polls without local variable reassignment.
+        const state = {
+            runId: flags['run-id'],
+            consecutiveErrors: 0,
+            firstTick: true,
+            // Undefined until a resumable cursor is established (see `poll` and
+            // `fetchWorkflowHistoryUpdates`); reset on continue-as-new since a new run's
+            // cursor position is meaningless carried over from the old one.
+            cursor: undefined
+        };
+        const seen = new Map();
+        // Assigned once per span id and never overwritten: `buildSpanLabels` numbers
+        // same-named spans by how many are in the array *at call time*, so recomputing
+        // it fresh every poll could retroactively change a label already printed to
+        // the user (e.g. an unnumbered "Scrape Page" becoming "Scrape Page #1" once a
+        // second instance appears). Freezing on first sight keeps printed labels stable.
+        const labels = new Map();
+        // One emit point for both output formats: json mode wraps `fields` (plus
+        // the ambient workflow/run id) as a line of NDJSON, text mode prints `text`.
+        const emit = (fields, text) => {
+            this.log(json ?
+                JSON.stringify({ workflowId: args.workflowId, runId: state.runId, ...fields }) :
+                text);
+        };
+        emit({ monitoring: true }, `Monitoring ${args.workflowId}${state.runId ? ` (run ${state.runId})` : ''}... (Ctrl+C to detach)`);
+        const sigintHandler = () => {
+            emit({ detached: true }, '\nDetached (the workflow keeps running).');
+            process.exit(SIGINT_EXIT_CODE);
+        };
+        process.on('SIGINT', sigintHandler);
+        try {
+            while (true) {
+                const outcome = await this.poll(args.workflowId, flags, state);
+                if (outcome === null) {
+                    state.consecutiveErrors += 1;
+                    await sleep(flags.interval);
+                    continue;
+                }
+                state.consecutiveErrors = 0;
+                state.firstTick = false;
+                state.cursor = outcome.cursor;
+                const result = outcome.result;
+                state.runId = result.runId ?? state.runId;
+                for (const [id, label] of buildSpanLabels(result.spans)) {
+                    if (!labels.has(id)) {
+                        labels.set(id, label);
+                    }
+                }
+                for (const update of diffSpanUpdates(result.spans, labels, seen)) {
+                    emit({ span: update.span }, formatSpanUpdate(update, color));
+                }
+                const status = result.workflow?.status;
+                if (status === 'continued_as_new') {
+                    if (!result.continuedAsNewRunId) {
+                        this.error('Workflow continued as a new run, but the new run ID could not be determined.', { exit: 1 });
+                    }
+                    emit({ continuedAsNewRunId: result.continuedAsNewRunId }, formatContinuedAsNew(result.continuedAsNewRunId));
+                    state.runId = result.continuedAsNewRunId;
+                    state.cursor = undefined;
+                    seen.clear();
+                    labels.clear();
+                    await sleep(flags.interval);
+                    continue;
+                }
+                if (status && TERMINAL_STATUSES.has(status)) {
+                    const summary = `${status === 'completed' ? '✓' : '✗'} workflow ${status} · ${formatDurationLabel(result.totalDurationMs)}`;
+                    emit({ status }, summary);
+                    if (ERROR_STATUSES.has(status)) {
+                        process.exitCode = 1;
+                    }
+                    return;
+                }
+                await sleep(flags.interval);
+            }
+        }
+        finally {
+            process.removeListener('SIGINT', sigintHandler);
+        }
+    }
+    /**
+     * Wraps a single poll: a failure on the very first tick propagates (there's
+     * nothing to fall back on), but a transient blip (see `isTransientPollError`)
+     * after we've already been monitoring successfully just returns `null` so the
+     * loop can retry — matching the dev TUI's `useStepGraph` behavior of keeping
+     * the last good state on a poll hiccup. A non-transient error (e.g. a stale
+     * resume cursor, or a bug in the parsing pipeline) rethrows immediately since
+     * retrying it cannot succeed. `MAX_CONSECUTIVE_ERRORS` bounds how long we'll
+     * retry transient failures before giving up.
+     *
+     * Fetch strategy is driven by `state.cursor`, not tick count: no cursor yet
+     * (the very first poll, or the first poll of a run chained via continue-as-new)
+     * uses `fetchWorkflowHistory` (fast, no long-poll) so that render isn't delayed;
+     * once a cursor exists, every poll resumes via `fetchWorkflowHistoryUpdates`
+     * instead of re-paging the whole history — see `plan_workflow_monitor_history.md`
+     * for why a full re-fetch every tick is expensive for long-running workflows.
+     */
+    async poll(workflowId, flags, state) {
+        try {
+            // Keeps the resumed long-poll's server-side block roughly aligned with `--interval`
+            // instead of always blocking for the server's full configured deadline regardless of
+            // it (see `plan_workflow_monitor_history.md`'s "Known tradeoff" note). Only takes
+            // effect once resuming (i.e. from the second tick onward); `fetchWorkflowHistory`
+            // ignores it on the initial full walk.
+            const options = { workflowId, runId: state.runId, includePayloads: flags['include-payloads'], longPollTimeoutMs: flags.interval };
+            if (!state.cursor) {
+                const result = await fetchWorkflowHistory(options);
+                return { result, cursor: result.cursor };
+            }
+            return await fetchWorkflowHistoryUpdates(options, state.cursor);
+        }
+        catch (error) {
+            if (state.firstTick || !isTransientPollError(error) || state.consecutiveErrors + 1 >= MAX_CONSECUTIVE_ERRORS) {
+                throw error;
+            }
+            this.warn(`Poll failed (${state.consecutiveErrors + 1}/${MAX_CONSECUTIVE_ERRORS}), retrying: ${getErrorMessage(error)}`);
+            return null;
+        }
+    }
+    async catch(error) {
+        // A 400 is the generic status for several distinct causes (invalid pageToken, a
+        // missing runId, an out-of-range longPollTimeoutMs) — only override it with the stale-cursor
+        // message when the server actually identifies that specific cause; otherwise let
+        // the real validation error surface instead of misdiagnosing an unrelated 400.
+        const response = error.response;
+        const isStaleCursor = response?.status === 400 && response.data?.error === 'InvalidPageTokenError';
+        const overrides = { 404: 'Workflow not found. Check the workflow ID.' };
+        if (isStaleCursor) {
+            overrides[400] = 'Resume cursor is no longer valid for this workflow; restart the monitor.';
+        }
+        return handleApiError(error, (...args) => this.error(...args), overrides);
+    }
+}

package/dist/commands/workflow/monitor.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/workflow/monitor.spec.js

@@ -0,0 +1,243 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { HttpError } from '#api/http_client.js';
+vi.mock('#services/workflow_history.js', () => ({ fetchWorkflowHistory: vi.fn(), fetchWorkflowHistoryUpdates: vi.fn() }));
+vi.mock('#utils/sleep.js', () => ({ sleep: vi.fn().mockResolvedValue(undefined) }));
+const span = (id, status, overrides = {}) => ({
+    id,
+    name: `Step ${id}`,
+    technicalName: `wf#step${id}`,
+    description: null,
+    status,
+    kind: 'activity',
+    attempt: 1,
+    startedAt: null,
+    scheduledAt: null,
+    completedAt: null,
+    startOffsetMs: 0,
+    endOffsetMs: 0,
+    durationMs: 1000,
+    failureMessage: null,
+    ...overrides
+});
+const history = (status, overrides = {}) => ({
+    workflow: { status },
+    runId: 'run-1',
+    events: [],
+    spans: [],
+    totalDurationMs: 0,
+    continuedAsNewRunId: null,
+    // Every result carries a cursor now (see workflow_history.ts) — `poll()` uses its
+    // presence to decide fetchWorkflowHistory vs. fetchWorkflowHistoryUpdates on the next tick.
+    cursor: { pageToken: 'token', lastEventId: 1, meta: null, runId: 'run-1', events: [] },
+    ...overrides
+});
+// `fetchWorkflowHistoryUpdates` (used from the second poll onward) wraps the same result
+// shape with a resume cursor; tests don't care about cursor contents, only that it's threaded.
+const update = (status, overrides = {}) => ({
+    result: history(status, overrides),
+    cursor: { pageToken: 'token', lastEventId: 1, meta: null, runId: 'run-1', events: [] }
+});
+describe('workflow monitor command', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        process.exitCode = undefined;
+    });
+    describe('command definition', () => {
+        it('exports a valid OCLIF command with a required workflowId arg', async () => {
+            const WorkflowMonitor = (await import('./monitor.js')).default;
+            expect(WorkflowMonitor).toBeDefined();
+            expect(WorkflowMonitor.args).toHaveProperty('workflowId');
+            expect(WorkflowMonitor.args.workflowId.required).toBe(true);
+        });
+        it('declares the expected flags and defaults', async () => {
+            const WorkflowMonitor = (await import('./monitor.js')).default;
+            const flags = WorkflowMonitor.flags;
+            expect(flags).toHaveProperty('run-id');
+            expect(flags).toHaveProperty('include-payloads');
+            expect(flags).toHaveProperty('interval');
+            expect(flags).toHaveProperty('color');
+            expect(flags.format.options).toEqual(['text', 'json']);
+            expect(flags.format.default).toBe('text');
+            expect(flags.interval.default).toBe(2500);
+            expect(flags.color.default).toBe(true);
+        });
+    });
+    describe('run()', () => {
+        const createCommand = async (flagOverrides = {}) => {
+            const WorkflowMonitor = (await import('./monitor.js')).default;
+            const { fetchWorkflowHistory, fetchWorkflowHistoryUpdates } = await import('#services/workflow_history.js');
+            const cmd = new WorkflowMonitor(['wf-1'], {});
+            cmd.log = vi.fn();
+            cmd.warn = vi.fn();
+            cmd.error = vi.fn((message) => {
+                throw new Error(message);
+            });
+            cmd.parse = vi.fn().mockResolvedValue({
+                args: { workflowId: 'wf-1' },
+                flags: {
+                    'run-id': undefined,
+                    format: 'text',
+                    'include-payloads': false,
+                    interval: 1,
+                    color: false,
+                    ...flagOverrides
+                }
+            });
+            return {
+                cmd,
+                fetchWorkflowHistory: vi.mocked(fetchWorkflowHistory),
+                fetchWorkflowHistoryUpdates: vi.mocked(fetchWorkflowHistoryUpdates)
+            };
+        };
+        it('prints span updates and exits cleanly when the workflow is already completed on the first poll', async () => {
+            const { cmd, fetchWorkflowHistory } = await createCommand();
+            fetchWorkflowHistory.mockResolvedValueOnce(history('completed', { spans: [span('1', 'completed')], totalDurationMs: 5000 }));
+            await cmd.run();
+            expect(fetchWorkflowHistory).toHaveBeenCalledTimes(1);
+            expect(cmd.log).toHaveBeenCalledWith(expect.stringContaining('Step 1'));
+            expect(cmd.log).toHaveBeenCalledWith(expect.stringContaining('workflow completed'));
+            expect(process.exitCode).toBeUndefined();
+        });
+        it('sets exit code 1 when the workflow ends in a failed status', async () => {
+            const { cmd, fetchWorkflowHistory } = await createCommand();
+            fetchWorkflowHistory.mockResolvedValueOnce(history('failed', {
+                spans: [span('1', 'failed', { failureMessage: 'boom' })], totalDurationMs: 1000
+            }));
+            await cmd.run();
+            expect(process.exitCode).toBe(1);
+        });
+        it('polls again while the workflow is running, then stops once it completes', async () => {
+            const { cmd, fetchWorkflowHistory, fetchWorkflowHistoryUpdates } = await createCommand();
+            fetchWorkflowHistory.mockResolvedValueOnce(history('running', { spans: [span('1', 'running')] }));
+            fetchWorkflowHistoryUpdates.mockResolvedValueOnce(update('completed', {
+                spans: [span('1', 'completed')], totalDurationMs: 2000
+            }));
+            await cmd.run();
+            expect(fetchWorkflowHistory).toHaveBeenCalledTimes(1);
+            expect(fetchWorkflowHistoryUpdates).toHaveBeenCalledTimes(1);
+            expect(cmd.log).toHaveBeenCalledWith(expect.stringContaining('running'));
+            expect(cmd.log).toHaveBeenCalledWith(expect.stringContaining('1s'));
+            expect(process.exitCode).toBeUndefined();
+        });
+        it('keeps a span label stable once printed, even when a same-named span appears on a later poll', async () => {
+            const { cmd, fetchWorkflowHistory, fetchWorkflowHistoryUpdates } = await createCommand();
+            fetchWorkflowHistory.mockResolvedValueOnce(history('running', { spans: [span('1', 'running', { name: 'Scrape Page' })] }));
+            // Span 2 shares span 1's name, only showing up on the second poll — buildSpanLabels
+            // would number both "#1"/"#2" if recomputed fresh, retroactively relabeling span 1's
+            // already-printed "running" line.
+            fetchWorkflowHistoryUpdates.mockResolvedValueOnce(update('completed', {
+                spans: [
+                    span('1', 'completed', { name: 'Scrape Page' }),
+                    span('2', 'completed', { name: 'Scrape Page' })
+                ]
+            }));
+            await cmd.run();
+            const lines = cmd.log.mock.calls.map(([line]) => line);
+            expect(lines.some((line) => line.includes('Scrape Page running'))).toBe(true);
+            // Span 1's completion line keeps its original unnumbered label...
+            expect(lines.some((line) => line.includes('Scrape Page  '))).toBe(true);
+            expect(lines.some((line) => line.includes('Scrape Page #1'))).toBe(false);
+            // ...while span 2, new this tick, is free to be numbered.
+            expect(lines.some((line) => line.includes('Scrape Page #2'))).toBe(true);
+        });
+        it('does not re-print a span whose status has not changed between polls', async () => {
+            const { cmd, fetchWorkflowHistory, fetchWorkflowHistoryUpdates } = await createCommand();
+            fetchWorkflowHistory.mockResolvedValueOnce(history('running', { spans: [span('1', 'running')] }));
+            fetchWorkflowHistoryUpdates.mockResolvedValueOnce(update('completed', {
+                spans: [span('1', 'running'), span('2', 'completed')], totalDurationMs: 1000
+            }));
+            await cmd.run();
+            const runningLines = cmd.log.mock.calls.filter(([line]) => line.includes('Step 1'));
+            expect(runningLines).toHaveLength(1); // span 1 only reported once, not again on the second poll
+        });
+        it('follows a continue-as-new chain by re-polling with the new run id', async () => {
+            const { cmd, fetchWorkflowHistory, fetchWorkflowHistoryUpdates } = await createCommand();
+            fetchWorkflowHistory
+                .mockResolvedValueOnce(history('continued_as_new', { continuedAsNewRunId: 'run-2' }))
+                // The new run's cursor was reset, so its first poll takes the same fast,
+                // non-waiting path as the very first poll of the command — not a resumed one.
+                .mockResolvedValueOnce(history('completed', { runId: 'run-2', totalDurationMs: 500 }));
+            await cmd.run();
+            expect(fetchWorkflowHistory).toHaveBeenCalledTimes(2);
+            expect(fetchWorkflowHistory).toHaveBeenNthCalledWith(2, expect.objectContaining({ runId: 'run-2' }));
+            expect(fetchWorkflowHistoryUpdates).not.toHaveBeenCalled();
+            expect(cmd.log).toHaveBeenCalledWith(expect.stringContaining('continued as new run run-2'));
+            expect(process.exitCode).toBeUndefined();
+        });
+        it('errors when the workflow continues as new but no new run id can be determined', async () => {
+            const { cmd, fetchWorkflowHistory } = await createCommand();
+            fetchWorkflowHistory.mockResolvedValueOnce(history('continued_as_new'));
+            await expect(cmd.run()).rejects.toThrow(/new run ID could not be determined/);
+        });
+        it('propagates a failure on the very first poll', async () => {
+            const { cmd, fetchWorkflowHistory } = await createCommand();
+            fetchWorkflowHistory.mockRejectedValue(new Error('network down'));
+            await expect(cmd.run()).rejects.toThrow('network down');
+            expect(fetchWorkflowHistory).toHaveBeenCalledTimes(1);
+        });
+        it('retries a transient network failure after the first successful poll instead of crashing', async () => {
+            const { cmd, fetchWorkflowHistory, fetchWorkflowHistoryUpdates } = await createCommand();
+            fetchWorkflowHistory.mockResolvedValueOnce(history('running'));
+            fetchWorkflowHistoryUpdates
+                .mockRejectedValueOnce(Object.assign(new Error('blip'), { code: 'ECONNRESET' }))
+                .mockResolvedValueOnce(update('completed', { totalDurationMs: 1000 }));
+            await cmd.run();
+            expect(fetchWorkflowHistory).toHaveBeenCalledTimes(1);
+            expect(fetchWorkflowHistoryUpdates).toHaveBeenCalledTimes(2);
+            expect(cmd.warn).toHaveBeenCalledWith(expect.stringContaining('(1/5)'));
+            expect(process.exitCode).toBeUndefined();
+        });
+        it('retries a transient 503 HttpError after the first successful poll', async () => {
+            const { cmd, fetchWorkflowHistory, fetchWorkflowHistoryUpdates } = await createCommand();
+            fetchWorkflowHistory.mockResolvedValueOnce(history('running'));
+            fetchWorkflowHistoryUpdates
+                .mockRejectedValueOnce(new HttpError('Service unavailable', { status: 503 }))
+                .mockResolvedValueOnce(update('completed', { totalDurationMs: 1000 }));
+            await cmd.run();
+            expect(fetchWorkflowHistoryUpdates).toHaveBeenCalledTimes(2);
+            expect(cmd.warn).toHaveBeenCalledWith(expect.stringContaining('(1/5)'));
+            expect(process.exitCode).toBeUndefined();
+        });
+        it('immediately rethrows a non-transient error (e.g. a stale resume cursor) without retrying', async () => {
+            const { cmd, fetchWorkflowHistory, fetchWorkflowHistoryUpdates } = await createCommand();
+            fetchWorkflowHistory.mockResolvedValueOnce(history('running'));
+            fetchWorkflowHistoryUpdates.mockRejectedValueOnce(new HttpError('Invalid page token', { status: 400 }));
+            await expect(cmd.run()).rejects.toThrow('Invalid page token');
+            expect(fetchWorkflowHistoryUpdates).toHaveBeenCalledTimes(1);
+            expect(cmd.warn).not.toHaveBeenCalled();
+        });
+        it('registers a SIGINT handler that detaches and exits 130 without affecting the workflow', async () => {
+            const { cmd, fetchWorkflowHistory } = await createCommand();
+            fetchWorkflowHistory.mockResolvedValueOnce(history('completed'));
+            const onSpy = vi.spyOn(process, 'on');
+            const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined));
+            await cmd.run();
+            const sigintCall = onSpy.mock.calls.find(([event]) => event === 'SIGINT');
+            expect(sigintCall).toBeDefined();
+            const handler = sigintCall[1];
+            handler();
+            expect(exitSpy).toHaveBeenCalledWith(130);
+            expect(cmd.log).toHaveBeenCalledWith(expect.stringContaining('Detached'));
+            onSpy.mockRestore();
+            exitSpy.mockRestore();
+        });
+        it('emits NDJSON lines under --format json', async () => {
+            const { cmd, fetchWorkflowHistory } = await createCommand({ format: 'json' });
+            fetchWorkflowHistory.mockResolvedValueOnce(history('completed', { spans: [span('1', 'completed')], totalDurationMs: 1000 }));
+            await cmd.run();
+            const lines = cmd.log.mock.calls.map(([line]) => line);
+            expect(lines.every((line) => {
+                try {
+                    JSON.parse(line);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            })).toBe(true);
+            expect(lines.some((line) => JSON.parse(line).span?.id === '1')).toBe(true);
+            expect(lines.some((line) => JSON.parse(line).monitoring === true)).toBe(true);
+        });
+    });
+});

package/dist/commands/workflow/run.js

@@ -63,7 +63,14 @@ export default class WorkflowRun extends Command {
     };
     async run() {
         const { args, flags } = await this.parse(WorkflowRun);
-        const input = await resolveInput(args.workflowName, args.scenario, flags.input, 'run', flags.catalog);
+        const input = await resolveInput({
+            workflowName: args.workflowName,
+            scenario: args.scenario,
+            inputFlag: flags.input,
+            commandName: 'run',
+            catalog: flags.catalog,
+            json: this.jsonEnabled()
+        });
         this.log(`Executing workflow: ${args.workflowName}...`);
         const response = await executeWorkflow({
             body: {

package/dist/commands/workflow/run.spec.js

@@ -64,7 +64,12 @@ describe('workflow run command', () => {
                 headers: new Headers()
             });
             await cmd.run();
-            expect(resolveInput).toHaveBeenCalledWith('my_workflow', undefined, undefined, 'run', undefined);
+            expect(resolveInput).toHaveBeenCalledWith(expect.objectContaining({
+                workflowName: 'my_workflow',
+                commandName: 'run',
+                catalog: undefined,
+                json: false
+            }));
             expect(postWorkflowRun).toHaveBeenCalledTimes(1);
             expect(postWorkflowRun).toHaveBeenCalledWith({ workflowName: 'my_workflow', input: { key: 'value' }, catalog: undefined }, expect.objectContaining({ config: { timeout: 600000 } }));
             expect(cmd.log).toHaveBeenCalledWith('Executing workflow: my_workflow...');
@@ -83,7 +88,12 @@ describe('workflow run command', () => {
                 headers: new Headers()
             });
             await cmd.run();
-            expect(resolveInput).toHaveBeenCalledWith('my_workflow', 'basic', undefined, 'run', 'my-catalog');
+            expect(resolveInput).toHaveBeenCalledWith(expect.objectContaining({
+                workflowName: 'my_workflow',
+                scenario: 'basic',
+                commandName: 'run',
+                catalog: 'my-catalog'
+            }));
             expect(postWorkflowRun).toHaveBeenCalledWith(expect.objectContaining({ catalog: 'my-catalog' }), expect.anything());
         });
         it('retries when response has Retry-After and succeeds on second attempt', async () => {

package/dist/commands/workflow/start.d.ts

@@ -1,6 +1,8 @@
 import { Command } from '@oclif/core';
+import { type PostWorkflowStart200 } from '#api/generated/api.js';
 export default class WorkflowStart extends Command {
     static description: string;
+    static enableJsonFlag: boolean;
     static examples: string[];
     static args: {
         workflowName: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
@@ -10,6 +12,6 @@ export default class WorkflowStart extends Command {
         input: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         catalog: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
-    run(): Promise<void>;
+    run(): Promise<PostWorkflowStart200>;
     catch(error: Error): Promise<void>;
 }

package/dist/commands/workflow/start.js

@@ -4,11 +4,13 @@ import { handleApiError } from '#utils/error_handler.js';
 import { resolveInput } from '#utils/resolve_input.js';
 export default class WorkflowStart extends Command {
     static description = 'Start a workflow asynchronously without waiting for completion';
+    static enableJsonFlag = true;
     static examples = [
         '<%= config.bin %> <%= command.id %> simple basic_input',
         '<%= config.bin %> <%= command.id %> simple --input \'{"values":[1,2,3]}\'',
         '<%= config.bin %> <%= command.id %> simple --input input.json',
-        '<%= config.bin %> <%= command.id %> simple --input \'{"key":"value"}\' --catalog my-catalog'
+        '<%= config.bin %> <%= command.id %> simple --input \'{"key":"value"}\' --catalog my-catalog',
+        '<%= config.bin %> <%= command.id %> simple --json'
     ];
     static args = {
         workflowName: Args.string({
@@ -37,7 +39,14 @@ export default class WorkflowStart extends Command {
     };
     async run() {
         const { args, flags } = await this.parse(WorkflowStart);
-        const input = await resolveInput(args.workflowName, args.scenario, flags.input, 'start', flags.catalog);
+        const input = await resolveInput({
+            workflowName: args.workflowName,
+            scenario: args.scenario,
+            inputFlag: flags.input,
+            commandName: 'start',
+            catalog: flags.catalog,
+            json: this.jsonEnabled()
+        });
         this.log(`Starting workflow: ${args.workflowName}...`);
         const response = await postWorkflowStart({
             workflowName: args.workflowName,
@@ -57,6 +66,7 @@ export default class WorkflowStart extends Command {
             `Use "workflow result ${result.workflowId || '<workflow-id>'}" to get the workflow result when complete`
         ].join('\n');
         this.log(`\n${output}`);
+        return result;
     }
     async catch(error) {
         return handleApiError(error, (...args) => this.error(...args), {

package/dist/commands/workflow/start.spec.js

@@ -36,13 +36,17 @@ describe('workflow start command', () => {
             expect(WorkflowStart.flags.catalog.env).toBe('OUTPUT_CATALOG_ID');
             expect(WorkflowStart.flags.catalog.char).toBe('c');
         });
+        it('enables the built-in --json flag', async () => {
+            const WorkflowStart = (await import('./start.js')).default;
+            expect(WorkflowStart.enableJsonFlag).toBe(true);
+        });
     });
     describe('run()', () => {
-        const createCommand = async (flagOverrides = {}) => {
+        const createCommand = async (flagOverrides = {}, argv = ['my_workflow']) => {
             const WorkflowStart = (await import('./start.js')).default;
             const { postWorkflowStart } = await import('#api/generated/api.js');
             const { resolveInput } = await import('#utils/resolve_input.js');
-            const cmd = new WorkflowStart(['my_workflow'], {});
+            const cmd = new WorkflowStart(argv, {});
             cmd.log = vi.fn();
             cmd.error = vi.fn(() => {
                 throw new Error('error called');
@@ -61,9 +65,15 @@ describe('workflow start command', () => {
                 status: 200,
                 headers: new Headers()
             });
-            await cmd.run();
-            expect(resolveInput).toHaveBeenCalledWith('my_workflow', undefined, undefined, 'start', 'my-catalog');
+            const result = await cmd.run();
+            expect(resolveInput).toHaveBeenCalledWith(expect.objectContaining({
+                workflowName: 'my_workflow',
+                commandName: 'start',
+                catalog: 'my-catalog',
+                json: false
+            }));
             expect(postWorkflowStart).toHaveBeenCalledWith(expect.objectContaining({ workflowName: 'my_workflow', catalog: 'my-catalog' }));
+            expect(result).toEqual({ workflowId: 'wf-123' });
         });
         it('passes undefined catalog through when none is set', async () => {
             const { cmd, postWorkflowStart, resolveInput } = await createCommand();
@@ -74,7 +84,22 @@ describe('workflow start command', () => {
                 headers: new Headers()
             });
             await cmd.run();
-            expect(resolveInput).toHaveBeenCalledWith('my_workflow', undefined, undefined, 'start', undefined);
+            expect(resolveInput).toHaveBeenCalledWith(expect.objectContaining({
+                workflowName: 'my_workflow',
+                commandName: 'start',
+                catalog: undefined
+            }));
+        });
+        it('tells resolveInput to stay quiet when --json is set', async () => {
+            const { cmd, postWorkflowStart, resolveInput } = await createCommand({}, ['my_workflow', 'basic', '--json']);
+            resolveInput.mockResolvedValue({});
+            postWorkflowStart.mockResolvedValue({
+                data: { workflowId: 'wf-123' },
+                status: 200,
+                headers: new Headers()
+            });
+            await cmd.run();
+            expect(resolveInput).toHaveBeenCalledWith(expect.objectContaining({ json: true }));
         });
     });
 });

package/dist/generated/framework_version.json

@@ -1,3 +1,3 @@
 {
-    "framework": "0.10.1-dev.b7b2fbe.0"
+    "framework": "0.10.1-next.14a191e.0"
 }