@outputai/cli 0.10.1-next.6deba0f.0 → 0.10.1-next.74e6a3d.0

package/dist/services/monitor_stream.spec.js

@@ -0,0 +1,285 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { HttpError } from '#api/http_client.js';
+import { commandStreamIo, monitorErrorOverrides, streamWorkflowUpdates } from './monitor_stream.js';
+vi.mock('#services/workflow_history.js', () => ({ fetchWorkflowHistory: vi.fn(), fetchWorkflowHistoryUpdates: vi.fn() }));
+vi.mock('#utils/sleep.js', () => ({ sleep: vi.fn().mockResolvedValue(undefined) }));
+/**
+ * Direct coverage of the loop now that two commands share it. `monitor.spec.ts`
+ * exercises it end-to-end through `workflow monitor`, and `start.spec.ts` stubs
+ * it out entirely — so what's here is the behavior neither reaches: the return
+ * value both callers branch on, the pre-cursor retry cap, the detach guards, and
+ * the error classification at its edges.
+ */
+const cursor = { pageToken: 'token', lastEventId: 1, meta: null, runId: 'run-1', events: [] };
+const history = (status, overrides = {}) => ({
+    workflow: { status },
+    runId: 'run-1',
+    events: [],
+    spans: [],
+    totalDurationMs: 0,
+    continuedAsNewRunId: null,
+    cursor,
+    ...overrides
+});
+const update = (status, overrides = {}) => ({ result: history(status, overrides), cursor });
+const createIo = (errorReturns = false) => ({
+    log: vi.fn(),
+    warn: vi.fn(),
+    // Typed `never` in the interface but nothing enforces that at runtime, which is
+    // exactly what the continue-as-new guard defends against — so both shapes are
+    // constructible here.
+    error: (errorReturns ?
+        vi.fn() :
+        vi.fn((message) => {
+            throw new Error(message);
+        }))
+});
+const options = (overrides = {}) => ({
+    workflowId: 'wf-1',
+    runId: undefined,
+    includePayloads: false,
+    interval: 5000,
+    json: false,
+    color: false,
+    ...overrides
+});
+const flush = () => new Promise(resolve => setImmediate(resolve));
+describe('monitor_stream service', () => {
+    beforeEach(async () => {
+        vi.clearAllMocks();
+        process.exitCode = undefined;
+        const { sleep } = await import('#utils/sleep.js');
+        vi.mocked(sleep).mockResolvedValue(undefined);
+    });
+    afterEach(() => {
+        process.exitCode = undefined;
+    });
+    const histories = async () => {
+        const { fetchWorkflowHistory, fetchWorkflowHistoryUpdates } = await import('#services/workflow_history.js');
+        return {
+            fetchWorkflowHistory: vi.mocked(fetchWorkflowHistory),
+            fetchWorkflowHistoryUpdates: vi.mocked(fetchWorkflowHistoryUpdates)
+        };
+    };
+    describe('streamWorkflowUpdates() return value', () => {
+        it('returns the terminal status it stopped on so the caller can name a follow-up', async () => {
+            const { fetchWorkflowHistory } = await histories();
+            fetchWorkflowHistory.mockResolvedValueOnce(history('completed'));
+            // `start --monitor` branches on this to print "workflow result" vs
+            // "workflow debug"; a boolean or a throw wouldn't carry enough.
+            expect(await streamWorkflowUpdates(options(), createIo())).toBe('completed');
+            expect(process.exitCode).toBeUndefined();
+        });
+        it('returns a failed status and records exit 1 without throwing', async () => {
+            const { fetchWorkflowHistory } = await histories();
+            fetchWorkflowHistory.mockResolvedValueOnce(history('failed'));
+            // Not thrown: the caller's own output stays the command's primary result.
+            expect(await streamWorkflowUpdates(options(), createIo())).toBe('failed');
+            expect(process.exitCode).toBe(1);
+        });
+        it('returns undefined when the user detached, so no follow-up is printed', async () => {
+            const { fetchWorkflowHistory } = await histories();
+            const { sleep } = await import('#utils/sleep.js');
+            fetchWorkflowHistory.mockResolvedValue(history('running'));
+            const onSpy = vi.spyOn(process, 'on');
+            const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined));
+            vi.mocked(sleep).mockImplementation(async () => {
+                onSpy.mock.calls.find(([event]) => event === 'SIGINT')[1]();
+            });
+            expect(await streamWorkflowUpdates(options(), createIo())).toBeUndefined();
+            await flush();
+            onSpy.mockRestore();
+            exitSpy.mockRestore();
+        });
+    });
+    describe('retry pacing', () => {
+        it('caps the retry sleep while no cursor is established, ignoring a long --interval', async () => {
+            const { fetchWorkflowHistory } = await histories();
+            const { sleep } = await import('#utils/sleep.js');
+            fetchWorkflowHistory
+                .mockRejectedValueOnce(new HttpError('Service unavailable', { status: 503 }))
+                .mockResolvedValueOnce(history('completed'));
+            await streamWorkflowUpdates(options({ interval: 5000 }), createIo());
+            // Otherwise "the API is down" takes interval x budget to surface — minutes,
+            // for a `workflow monitor` against a server that was never reachable.
+            expect(vi.mocked(sleep)).toHaveBeenCalledWith(1000);
+        });
+        it('honors an --interval shorter than the cap rather than slowing the retry down', async () => {
+            const { fetchWorkflowHistory } = await histories();
+            const { sleep } = await import('#utils/sleep.js');
+            fetchWorkflowHistory
+                .mockRejectedValueOnce(new HttpError('Service unavailable', { status: 503 }))
+                .mockResolvedValueOnce(history('completed'));
+            await streamWorkflowUpdates(options({ interval: 250 }), createIo());
+            expect(vi.mocked(sleep)).toHaveBeenCalledWith(250);
+        });
+        it('sleeps the full --interval on a retry once a cursor exists', async () => {
+            const { fetchWorkflowHistory, fetchWorkflowHistoryUpdates } = await histories();
+            const { sleep } = await import('#utils/sleep.js');
+            fetchWorkflowHistory.mockResolvedValueOnce(history('running'));
+            fetchWorkflowHistoryUpdates
+                .mockRejectedValueOnce(new HttpError('Service unavailable', { status: 503 }))
+                .mockResolvedValueOnce(update('completed'));
+            await streamWorkflowUpdates(options({ interval: 5000 }), createIo());
+            expect(vi.mocked(sleep)).not.toHaveBeenCalledWith(1000);
+            expect(vi.mocked(sleep)).toHaveBeenCalledWith(5000);
+        });
+    });
+    describe('transient error classification', () => {
+        const retried = async (error) => {
+            const { fetchWorkflowHistory } = await histories();
+            fetchWorkflowHistory.mockRejectedValueOnce(error).mockResolvedValueOnce(history('completed'));
+            const io = createIo();
+            await streamWorkflowUpdates(options(), io);
+            return { calls: fetchWorkflowHistory.mock.calls.length, io };
+        };
+        it.each([
+            ['a 503', new HttpError('Service unavailable', { status: 503 })],
+            ['a 429 rate limit', new HttpError('Too many requests', { status: 429 })],
+            ['a 408 request timeout', new HttpError('Request timeout', { status: 408 })],
+            ['a client-side TimeoutError', Object.assign(new Error('timed out'), { name: 'TimeoutError' })],
+            ['a nested ECONNREFUSED cause', Object.assign(new Error('fetch failed'), { cause: { code: 'ECONNREFUSED' } })],
+            ['a top-level EAI_AGAIN', Object.assign(new Error('dns'), { code: 'EAI_AGAIN' })]
+        ])('retries %s', async (_label, error) => {
+            const { calls, io } = await retried(error);
+            expect(calls).toBe(2);
+            expect(io.warn).toHaveBeenCalledWith(expect.stringContaining('(1/5)'));
+        });
+        it.each([
+            ['a 404 for a mistyped workflow id', new HttpError('Not found', { status: 404 })],
+            ['a 400 stale resume cursor', new HttpError('Invalid page token', { status: 400 })],
+            ['a bug in the parsing pipeline', new TypeError('spans is not iterable')]
+        ])('surfaces %s immediately instead of burning the retry budget', async (_label, error) => {
+            const { fetchWorkflowHistory } = await histories();
+            fetchWorkflowHistory.mockRejectedValue(error);
+            const io = createIo();
+            await expect(streamWorkflowUpdates(options(), io)).rejects.toThrow();
+            expect(fetchWorkflowHistory).toHaveBeenCalledTimes(1);
+            expect(io.warn).not.toHaveBeenCalled();
+        });
+    });
+    describe('detaching', () => {
+        const detachDuring = async () => {
+            const onSpy = vi.spyOn(process, 'on');
+            const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined));
+            const sigint = () => onSpy.mock.calls.find(([event]) => event === 'SIGINT')[1]();
+            return { onSpy, exitSpy, sigint };
+        };
+        it('swallows a poll failure raised after the user detached instead of racing the exit code', async () => {
+            const { fetchWorkflowHistory } = await histories();
+            const { onSpy, exitSpy, sigint } = await detachDuring();
+            // The in-flight poll dies because the process is on its way out. Rethrowing
+            // would unwind into `start`'s "monitoring stopped" handler and race exit 3
+            // against the 130 the detach already recorded.
+            fetchWorkflowHistory.mockImplementation(async () => {
+                sigint();
+                throw new Error('socket hang up');
+            });
+            const io = createIo();
+            expect(await streamWorkflowUpdates(options(), io)).toBeUndefined();
+            expect(process.exitCode).toBe(130);
+            expect(io.warn).not.toHaveBeenCalled();
+            expect(fetchWorkflowHistory).toHaveBeenCalledTimes(1);
+            await flush();
+            onSpy.mockRestore();
+            exitSpy.mockRestore();
+        });
+        it('ignores a second Ctrl+C while the first is still draining stdout', async () => {
+            const { fetchWorkflowHistory } = await histories();
+            fetchWorkflowHistory.mockResolvedValueOnce(history('completed'));
+            const { onSpy, exitSpy, sigint } = await detachDuring();
+            const io = createIo();
+            await streamWorkflowUpdates(options(), io);
+            sigint();
+            // The exit is deferred behind a flush and the listener is still registered,
+            // so an impatient user lands here again before the process is gone.
+            sigint();
+            await flush();
+            const detached = io.log.mock.calls.filter((call) => String(call[0]).includes('Detached'));
+            expect(detached).toHaveLength(1);
+            expect(exitSpy).toHaveBeenCalledTimes(1);
+            onSpy.mockRestore();
+            exitSpy.mockRestore();
+        });
+        it('removes its SIGINT listener once the loop ends', async () => {
+            const { fetchWorkflowHistory } = await histories();
+            fetchWorkflowHistory.mockResolvedValueOnce(history('completed'));
+            const before = process.listenerCount('SIGINT');
+            await streamWorkflowUpdates(options(), createIo());
+            expect(process.listenerCount('SIGINT')).toBe(before);
+        });
+        it('removes its SIGINT listener even when the loop unwinds on an error', async () => {
+            const { fetchWorkflowHistory } = await histories();
+            fetchWorkflowHistory.mockRejectedValue(new HttpError('Not found', { status: 404 }));
+            const before = process.listenerCount('SIGINT');
+            await expect(streamWorkflowUpdates(options(), createIo())).rejects.toThrow();
+            expect(process.listenerCount('SIGINT')).toBe(before);
+        });
+    });
+    describe('continue-as-new', () => {
+        it('breaks instead of re-polling forever when the new run id is missing and io.error returns', async () => {
+            const { fetchWorkflowHistory } = await histories();
+            fetchWorkflowHistory.mockResolvedValue(history('continued_as_new'));
+            // `io.error` is typed `never`, but an io whose error returns would otherwise
+            // fall through and replay the whole history every interval, forever, with a
+            // zero exit code.
+            const io = createIo(true);
+            expect(await streamWorkflowUpdates(options(), io)).toBeUndefined();
+            expect(io.error).toHaveBeenCalledWith(expect.stringContaining('new run ID could not be determined'));
+            expect(fetchWorkflowHistory).toHaveBeenCalledTimes(1);
+        });
+        it('reports the chained run under the new run id in json mode', async () => {
+            const { fetchWorkflowHistory } = await histories();
+            fetchWorkflowHistory
+                .mockResolvedValueOnce(history('continued_as_new', { continuedAsNewRunId: 'run-2' }))
+                .mockResolvedValueOnce(history('completed', { runId: 'run-2' }));
+            const io = createIo();
+            await streamWorkflowUpdates(options({ json: true }), io);
+            const lines = io.log.mock.calls.map((call) => JSON.parse(call[0]));
+            expect(lines.some((line) => line.continuedAsNewRunId === 'run-2')).toBe(true);
+            // Every subsequent line carries the run actually being polled, not the one
+            // the stream attached to.
+            expect(lines.at(-1)).toMatchObject({ workflowId: 'wf-1', runId: 'run-2', status: 'completed' });
+        });
+    });
+    describe('commandStreamIo()', () => {
+        it('resolves log/warn at call time so a replaced command method still receives output', async () => {
+            const command = { log: vi.fn(), warn: vi.fn(), error: vi.fn() };
+            const io = commandStreamIo(command);
+            // oclif (and the command specs) swap these in as own properties after the
+            // adapter exists, which a `.bind()` at construction time would miss.
+            const replacement = vi.fn();
+            command.log = replacement;
+            io.log('hello');
+            expect(replacement).toHaveBeenCalledWith('hello');
+        });
+        it('raises command errors with an explicit exit 1', () => {
+            const command = { log: vi.fn(), warn: vi.fn(), error: vi.fn() };
+            commandStreamIo(command).error('boom');
+            expect(command.error).toHaveBeenCalledWith('boom', { exit: 1 });
+        });
+    });
+    describe('monitorErrorOverrides()', () => {
+        const withResponse = (status, data) => Object.assign(new Error('failed'), { response: { status, data } });
+        it('overrides a 400 the server identifies as a stale resume cursor', () => {
+            expect(monitorErrorOverrides(withResponse(400, { error: 'InvalidPageTokenError' }))).toEqual({
+                400: expect.stringContaining('Resume cursor is no longer valid')
+            });
+        });
+        it('leaves an unrelated 400 alone rather than misdiagnosing it as a stale cursor', () => {
+            // 400 also covers a missing runId and an out-of-range longPollTimeoutMs, whose
+            // real validation messages are more useful than a cursor guess.
+            expect(monitorErrorOverrides(withResponse(400, { error: 'ValidationError' }))).toEqual({});
+            expect(monitorErrorOverrides(withResponse(400))).toEqual({});
+        });
+        it('does not override a 404, which only reads correctly where the user typed the id', () => {
+            // `workflow monitor` adds its own; under `start --monitor` the id came back
+            // from the API, so "check the workflow ID" would misdirect the user.
+            expect(monitorErrorOverrides(withResponse(404))).toEqual({});
+        });
+        it('tolerates an error with no response at all', () => {
+            expect(monitorErrorOverrides(new Error('fetch failed'))).toEqual({});
+        });
+    });
+});

package/dist/services/workflow_history.js

@@ -10,13 +10,13 @@
 import { getWorkflowIdHistory } from '#api/generated/api.js';
 import { correlate, eventAttributes, eventTypeName } from '#services/workflow_history/correlator.js';
 import { normalizeWorkflowStatus } from '#utils/normalize_workflow_status.js';
-import { TERMINAL_STATUSES } from '#utils/format_workflow_result.js';
+import { isTerminalStatus } from '#utils/format_workflow_result.js';
 const PAGE_SIZE = 50;
 // The status here comes from the request's own describe (fresh whenever `wait` is
 // set), so it can report the run closed before the closing event has been paged in.
 function isRunClosed(meta) {
     const status = normalizeWorkflowStatus(meta?.status);
-    return status === 'continued_as_new' || (status !== undefined && TERMINAL_STATUSES.has(status));
+    return status === 'continued_as_new' || isTerminalStatus(status) !== undefined;
 }
 function numericEventId(event) {
     const id = Number(event.eventId);

package/dist/templates/agent_instructions/CLAUDE.md.template

@@ -17,10 +17,12 @@ claude plugin install outputai@outputai --scope project
 npm run output:dev           # Start dev environment (worker + Temporal)
 npm run output:worker:build  # Build TypeScript to dist/
 npm run output:worker:check  # Optional: bundle-check workflows for bad imports (node: built-ins)
-npm run output:worker:watch  # Build + restart on file changes
-npm run output:worker        # Install, build, and start worker
+npm run output:worker:watch  # Build + restart on src/ file changes
+npm run output:worker        # Build and start worker
 ```
 
+Hot-reload watches `src/` only. After changing dependencies (`package.json` / lockfile), run `npm install`, then `npx output dev down` and `npm run output:dev` again so the worker container reinstalls. A hot-reload alone is not enough; if the stack is still running, `npx output dev down` is required.
+
 ## Project Structure
 
 ```

package/dist/templates/project/README.md.template

@@ -79,7 +79,9 @@ This starts:
 - Temporal server and UI (http://localhost:8080)
 - PostgreSQL and Redis databases
 - Output.ai API server (http://localhost:3001)
-- Worker process for executing workflows
+- Worker process for executing workflows (auto-reloads on `src/` changes)
+
+Dependency changes (`package.json` / lockfile) are not picked up by hot-reload. Run `npm install`, then `npx output dev down` and `npm run output:dev` again so the worker container reinstalls. A hot-reload alone is not enough; if the stack is still running, `npx output dev down` is required.
 
 ### 4. Run a workflow
 

package/dist/templates/project/package.json.template

@@ -9,8 +9,8 @@
     "output:worker:build": "rm -rf dist/* && tsc -p ./ && output-copy-assets",
     "output:worker:start": "output-worker",
     "output:worker:check": "output-worker --check",
-    "output:worker": "npm run output:worker:install && npm run output:worker:build && npm run output:worker:start",
-    "output:worker:watch": "npx nodemon --watch src --watch package.json --ext ts,js,json,prompt,md --ignore 'dist/**' --ignore '**/*.spec.*' --ignore '**/*.test.*' --exec 'npm run output:worker'",
+    "output:worker": "npm run output:worker:build && npm run output:worker:start",
+    "output:worker:watch": "npx nodemon --watch src --ext ts,js,json,prompt,md --ignore 'dist/**' --ignore '**/*.spec.*' --ignore '**/*.test.*' --exec 'npm run output:worker'",
     "output:dev": "output dev"
   },
   "dependencies": {

package/dist/utils/error_handler.d.ts

@@ -5,4 +5,14 @@ type ErrorOverrides = {
 export declare function handleApiError(error: unknown, errorFn: (...args: [message: string, options: {
     exit: number;
 }]) => never, overrides?: ErrorOverrides): never;
+/**
+ * `catch()` handling for a command that raises oclif errors of its own. Flag
+ * relationship failures and every `this.error( ..., { exit } )` already carry an
+ * exit code and formatted output, and `handleApiError` would flatten all of it
+ * to a bare exit 1 — so pass those straight through and only map what actually
+ * came back from the API.
+ */
+export declare function handleCommandError(error: Error, errorFn: (...args: [message: string, options: {
+    exit: number;
+}]) => never, overrides?: ErrorOverrides): never;
 export {};

package/dist/utils/error_handler.js

@@ -1,3 +1,4 @@
+import { CLIError } from '@oclif/core/errors';
 import { config } from '#config.js';
 function getDefaultMessages() {
     return {
@@ -79,3 +80,16 @@ export function handleApiError(error, errorFn, overrides = {}) {
     const detailedMessage = getDetailedErrorMessage(error);
     errorFn(detailedMessage, { exit: 1 });
 }
+/**
+ * `catch()` handling for a command that raises oclif errors of its own. Flag
+ * relationship failures and every `this.error( ..., { exit } )` already carry an
+ * exit code and formatted output, and `handleApiError` would flatten all of it
+ * to a bare exit 1 — so pass those straight through and only map what actually
+ * came back from the API.
+ */
+export function handleCommandError(error, errorFn, overrides = {}) {
+    if (error instanceof CLIError) {
+        throw error;
+    }
+    return handleApiError(error, errorFn, overrides);
+}

package/dist/utils/error_handler.spec.d.ts

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

package/dist/utils/error_handler.spec.js

@@ -0,0 +1,62 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { describe, it, expect, vi } from 'vitest';
+import { CLIError } from '@oclif/core/errors';
+import { handleApiError, handleCommandError } from './error_handler.js';
+const errorFn = () => vi.fn((message) => {
+    throw new Error(message);
+});
+const apiError = (status, data) => Object.assign(new Error('request failed'), { response: { status, data } });
+describe('handleApiError()', () => {
+    it('prefers a caller override over the server body for the same status', () => {
+        const fn = errorFn();
+        expect(() => handleApiError(apiError(404, { error: 'WorkflowNotFoundError', message: 'Workflow "wf-1" not found' }), fn, { 404: 'Workflow not found. Check the workflow ID.' })).toThrow('Workflow not found. Check the workflow ID.');
+    });
+    it('surfaces the server body when no override covers the status', () => {
+        const fn = errorFn();
+        // What `start --monitor` relies on now that it passes no 404 override: the
+        // API's own words, rather than advice about an id the user never typed.
+        expect(() => handleApiError(apiError(404, { error: 'WorkflowNotFoundError', message: 'Workflow "wf-1" not found' }), fn)).toThrow('WorkflowNotFoundError: Workflow "wf-1" not found.');
+    });
+    it('appends a root cause to the server message when the API reports one', () => {
+        const fn = errorFn();
+        expect(() => handleApiError(apiError(500, { error: 'StepFailure', message: 'Step failed', rootCause: { error: 'TypeError', message: 'x is not a function' } }), fn)).toThrow(/TypeError: x is not a function/);
+    });
+    it('falls back to the status default when the body carries no detail', () => {
+        const fn = errorFn();
+        expect(() => handleApiError(apiError(401), fn)).toThrow(/OUTPUT_API_AUTH_TOKEN/);
+    });
+    it.each([
+        ['a top-level code', Object.assign(new Error('connect'), { code: 'ECONNREFUSED' })],
+        ['a nested cause', Object.assign(new Error('fetch failed'), { cause: { code: 'ECONNREFUSED' } })]
+    ])('reports a refused connection from %s before looking at any status', (_label, error) => {
+        const fn = errorFn();
+        expect(() => handleApiError(error, fn)).toThrow(/Is the API server running\?/);
+    });
+    it('assembles a detailed message when there is no response at all', () => {
+        const fn = errorFn();
+        const error = Object.assign(new Error('fetch failed'), {
+            cause: Object.assign(new Error('getaddrinfo EAI_AGAIN api'), { code: 'EAI_AGAIN', hostname: 'api', port: 3001 })
+        });
+        expect(() => handleApiError(error, fn)).toThrow(/fetch failed \| Cause: getaddrinfo EAI_AGAIN api \| Code: EAI_AGAIN \| Host: api:3001/);
+    });
+    it('always exits 1, leaving a command\'s own exit codes to the command', () => {
+        const fn = errorFn();
+        expect(() => handleApiError(apiError(500), fn)).toThrow();
+        expect(fn).toHaveBeenCalledWith(expect.any(String), { exit: 1 });
+    });
+});
+describe('handleCommandError()', () => {
+    it('rethrows an oclif error untouched so its exit code and formatting survive', () => {
+        const fn = errorFn();
+        // `workflow start --monitor` raises exit 2 (bad flag combination) and exit 3
+        // (started but unmonitorable); flattening those to exit 1 would let a CI job
+        // retrying on a failed workflow re-submit one that is already running.
+        const cliError = new CLIError('Cannot combine --monitor with --json', { exit: 2 });
+        expect(() => handleCommandError(cliError, fn)).toThrow(cliError);
+        expect(fn).not.toHaveBeenCalled();
+    });
+    it('maps anything that came back from the API the same way handleApiError does', () => {
+        const fn = errorFn();
+        expect(() => handleCommandError(apiError(404), fn, { 404: 'Workflow not found. Check the workflow name.' })).toThrow('Workflow not found. Check the workflow name.');
+    });
+});

package/dist/utils/format_workflow_result.d.ts

@@ -1,6 +1,18 @@
-import type { WorkflowResultResponse, WorkflowResultResponseStatus } from '../api/generated/api.js';
+import type { WorkflowResultResponse } from '../api/generated/api.js';
 type WorkflowResult = Pick<WorkflowResultResponse, 'workflowId' | 'output' | 'status' | 'error'>;
-export declare const ERROR_STATUSES: ReadonlySet<WorkflowResultResponseStatus | undefined>;
-export declare const TERMINAL_STATUSES: ReadonlySet<string>;
+declare const ERROR_STATUS_VALUES: readonly ["failed", "cancelled", "terminated", "timed_out"];
+export type ErrorStatus = typeof ERROR_STATUS_VALUES[number];
+export type TerminalStatus = 'completed' | ErrorStatus;
+/**
+ * Maps a raw status to a canonical error status, or `undefined` if it is not one.
+ * Legacy spellings (`canceled`) are normalized so callers only ever see the
+ * current API vocabulary — until `normalizeWorkflowStatus` is removed.
+ */
+export declare function isErrorStatus(status: string | null | undefined): ErrorStatus | undefined;
+/**
+ * Maps a raw status to a canonical terminal status, or `undefined` if it is not
+ * one. Same normalization contract as `isErrorStatus`.
+ */
+export declare function isTerminalStatus(status: string | null | undefined): TerminalStatus | undefined;
 export declare function formatWorkflowResult(result: WorkflowResult): string;
 export {};

package/dist/utils/format_workflow_result.js

@@ -1,9 +1,39 @@
 import { normalizeWorkflowStatus } from './normalize_workflow_status.js';
-export const ERROR_STATUSES = new Set(['failed', 'canceled', 'terminated', 'timed_out']);
-// Every error status plus the one success status — derived so the two sets can't
-// silently drift apart as error statuses evolve. Shared by `workflow monitor` and
-// the dev TUI's `useRunDetail`/`useStepGraph` so both agree on what "done" means.
-export const TERMINAL_STATUSES = new Set(['completed', ...ERROR_STATUSES]);
+// `satisfies` rather than a plain annotation: it pins these to the generated API
+// union without widening them, so regenerating the API with a renamed status
+// breaks the build instead of silently making that status non-terminal.
+const ERROR_STATUS_VALUES = [
+    'failed', 'cancelled', 'terminated', 'timed_out'
+];
+const ERROR_STATUSES = new Set(ERROR_STATUS_VALUES);
+const TERMINAL_STATUSES = new Set(['completed', ...ERROR_STATUS_VALUES]);
+/**
+ * Maps a raw status to a canonical error status, or `undefined` if it is not one.
+ * Legacy spellings (`canceled`) are normalized so callers only ever see the
+ * current API vocabulary — until `normalizeWorkflowStatus` is removed.
+ */
+/* eslint-disable consistent-return -- returns ErrorStatus | undefined via early exit */
+export function isErrorStatus(status) {
+    if (typeof status !== 'string') {
+        return undefined;
+    }
+    const normalized = normalizeWorkflowStatus(status);
+    return ERROR_STATUSES.has(normalized) ? normalized : undefined;
+}
+/* eslint-enable consistent-return */
+/**
+ * Maps a raw status to a canonical terminal status, or `undefined` if it is not
+ * one. Same normalization contract as `isErrorStatus`.
+ */
+/* eslint-disable consistent-return -- returns TerminalStatus | undefined via early exit */
+export function isTerminalStatus(status) {
+    if (typeof status !== 'string') {
+        return undefined;
+    }
+    const normalized = normalizeWorkflowStatus(status);
+    return TERMINAL_STATUSES.has(normalized) ? normalized : undefined;
+}
+/* eslint-enable consistent-return */
 export function formatWorkflowResult(result) {
     const status = normalizeWorkflowStatus(result.status);
     const lines = [
@@ -17,7 +47,10 @@ export function formatWorkflowResult(result) {
     else {
         lines.push(`Status: ${status || 'unknown'}`);
         if (result.error) {
-            lines.push(`Error: ${result.error}`);
+            const error = typeof result.error === 'string' ?
+                result.error :
+                result.error.message ?? JSON.stringify(result.error, null, 2);
+            lines.push(`Error: ${error}`);
         }
     }
     return lines.join('\n');

package/dist/utils/format_workflow_result.spec.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { formatWorkflowResult } from './format_workflow_result.js';
+import { formatWorkflowResult, isErrorStatus } from './format_workflow_result.js';
 describe('formatWorkflowResult', () => {
     it('should display output for completed workflows', () => {
         const result = formatWorkflowResult({
@@ -13,7 +13,7 @@ describe('formatWorkflowResult', () => {
         expect(result).toContain('"values"');
         expect(result).not.toContain('Status:');
     });
-    it('should display error details for failed workflows', () => {
+    it('should display legacy string errors for failed workflows', () => {
         const result = formatWorkflowResult({
             workflowId: 'wf-456',
             status: 'failed',
@@ -25,6 +25,29 @@ describe('formatWorkflowResult', () => {
         expect(result).toContain('Error: Activity task failed');
         expect(result).not.toContain('Output:');
     });
+    it('should display the message from structured errors', () => {
+        const result = formatWorkflowResult({
+            workflowId: 'wf-v2',
+            status: 'failed',
+            output: null,
+            error: {
+                name: 'ValidationError',
+                message: 'Input is invalid',
+                code: 'INVALID_INPUT'
+            }
+        });
+        expect(result).toContain('Error: Input is invalid');
+        expect(result).not.toContain('[object Object]');
+    });
+    it('should serialize structured errors without a message', () => {
+        const result = formatWorkflowResult({
+            workflowId: 'wf-v2',
+            status: 'failed',
+            output: null,
+            error: { code: 'UNKNOWN' }
+        });
+        expect(result).toContain('"code": "UNKNOWN"');
+    });
     it('should display status for terminated workflows', () => {
         const result = formatWorkflowResult({
             workflowId: 'wf-term',
@@ -35,15 +58,25 @@ describe('formatWorkflowResult', () => {
         expect(result).toContain('Status: terminated');
         expect(result).toContain('Error: Workflow terminated by user');
     });
-    it('should display status for canceled workflows', () => {
+    it('should display status for cancelled workflows', () => {
         const result = formatWorkflowResult({
+            workflowId: 'wf-cancel',
+            status: 'cancelled',
+            output: null,
+            error: 'Workflow was cancelled'
+        });
+        expect(result).toContain('Status: cancelled');
+        expect(result).toContain('Error: Workflow was cancelled');
+    });
+    it('normalizes canceled responses without changing the current status type', () => {
+        const legacyResult = {
             workflowId: 'wf-cancel',
             status: 'canceled',
             output: null,
             error: 'Workflow was canceled'
-        });
-        expect(result).toContain('Status: canceled');
-        expect(result).toContain('Error: Workflow was canceled');
+        };
+        expect(formatWorkflowResult(legacyResult)).toContain('Status: cancelled');
+        expect(isErrorStatus('canceled')).toBe('cancelled');
     });
     it('should display status without error line for continued_as_new workflows', () => {
         const result = formatWorkflowResult({

package/dist/utils/monitor_flags.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The stream's defaults when the tuning flags are not given. Caller-side, not a
+ * property of the loop: `streamWorkflowUpdates` takes all three as required
+ * options and never falls back. Single-sourced because only `workflow monitor`
+ * can hand them to oclif — `workflow start --monitor` has to apply them itself
+ * (see `gatedMonitorStreamFlags`), and a literal repeated on that side would
+ * drift the moment one of these changes.
+ */
+export declare const MONITOR_DEFAULTS: {
+    readonly interval: 2500;
+    readonly color: true;
+    readonly includePayloads: false;
+};
+/** For a command that always monitors, where oclif can apply the defaults itself. */
+export declare function monitorStreamFlags(): {
+    'include-payloads': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    interval: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+    color: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+};
+/**
+ * For a command where monitoring is opt-in (`workflow start --monitor`).
+ *
+ * These carry no oclif `default` on purpose: a defaulted flag counts as present
+ * (`validateFlags` runs a relationship check whenever the parsed value is not
+ * `undefined`, and `validateDependsOn` has no `setFromDefault` exemption the way
+ * `validateExclusive` does), which triggers its own `dependsOn` check and fails
+ * every invocation that omits `--monitor` — including a plain `workflow start`.
+ * The caller applies the defaults in `run()`, so the interval's default is
+ * spelled out in the help text rather than rendered by oclif.
+ */
+export declare function gatedMonitorStreamFlags(gatedBy: string): {
+    'include-payloads': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    interval: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    color: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+};