@outputai/cli 0.9.1-next.6fe398d.0 → 0.9.1

package/dist/assets/docker/docker-compose-dev.yml

@@ -80,7 +80,7 @@ services:
         condition: service_healthy
       worker:
         condition: service_healthy
-    image: outputai/api:${OUTPUT_API_VERSION:-0.9.1-next.6fe398d.0}
+    image: outputai/api:${OUTPUT_API_VERSION:-0.9.1}
     init: true
     networks:
       - main

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

@@ -0,0 +1,19 @@
+import { Command } from '@oclif/core';
+export default class WorkflowHistory extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        workflowId: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        'run-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        format: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        raw: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'include-payloads': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        width: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        color: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+    private buildHeader;
+    catch(error: Error): Promise<void>;
+}

package/dist/commands/workflow/history.js

@@ -0,0 +1,99 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { fetchWorkflowHistory } from '#services/workflow_history.js';
+import buildSpanLabels from '#utils/span_labels.js';
+import renderWaterfall, { formatDurationLabel } from '#utils/waterfall.js';
+import { handleApiError } from '#utils/error_handler.js';
+const DEFAULT_WIDTH = 80;
+const OUTPUT_FORMAT = { JSON: 'json', TEXT: 'text' };
+export default class WorkflowHistory extends Command {
+    static description = 'Show a workflow run\'s step timeline as a waterfall (durations and start times)';
+    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',
+        '<%= config.bin %> <%= command.id %> wf-12345 --raw --include-payloads'
+    ];
+    static args = {
+        workflowId: Args.string({
+            description: 'The workflow ID to show history for',
+            required: true
+        })
+    };
+    static flags = {
+        'run-id': Flags.string({
+            char: 'r',
+            description: 'Show a specific run (defaults to the latest run)'
+        }),
+        format: Flags.string({
+            char: 'f',
+            description: 'Output format',
+            options: [OUTPUT_FORMAT.TEXT, OUTPUT_FORMAT.JSON],
+            default: OUTPUT_FORMAT.TEXT
+        }),
+        raw: Flags.boolean({
+            description: 'Print the history endpoint\'s raw response (workflow + events)',
+            default: false
+        }),
+        'include-payloads': Flags.boolean({
+            description: 'Include decoded step input/output payloads',
+            default: false
+        }),
+        width: Flags.integer({
+            description: 'Override the detected terminal width'
+        }),
+        color: Flags.boolean({
+            description: 'Colorize the waterfall (use --no-color to disable)',
+            default: true,
+            allowNo: true
+        })
+    };
+    async run() {
+        const { args, flags } = await this.parse(WorkflowHistory);
+        const result = await fetchWorkflowHistory({
+            workflowId: args.workflowId,
+            runId: flags['run-id'],
+            includePayloads: flags['include-payloads']
+        });
+        if (flags.raw) {
+            this.log(JSON.stringify({
+                workflow: result.workflow,
+                runId: result.runId,
+                events: result.events
+            }, null, 2));
+            return;
+        }
+        if (flags.format === OUTPUT_FORMAT.JSON) {
+            this.log(JSON.stringify({
+                workflow: result.workflow,
+                runId: result.runId,
+                totalDurationMs: result.totalDurationMs,
+                spans: result.spans
+            }, null, 2));
+            return;
+        }
+        const labels = buildSpanLabels(result.spans);
+        const width = flags.width ?? process.stdout.columns ?? DEFAULT_WIDTH;
+        const color = flags.color && !process.env.NO_COLOR &&
+            (!!process.env.FORCE_COLOR || process.stdout.isTTY === true);
+        this.log(renderWaterfall(result.spans, result.totalDurationMs, {
+            width,
+            color,
+            labels,
+            header: this.buildHeader(args.workflowId, result.runId, result.workflow?.status, result.totalDurationMs)
+        }));
+        // Failure reasons live in the payloads the server strips by default, so a
+        // failed run shows red bars but no messages until payloads are requested.
+        if (!flags['include-payloads'] && result.spans.some(span => span.status === 'failed')) {
+            this.log('\nSome steps failed — re-run with --include-payloads to see their error messages.');
+        }
+    }
+    buildHeader(workflowId, runId, status, totalDurationMs) {
+        const shortRun = runId ? runId.slice(0, 8) : 'unknown';
+        return `${workflowId} · run ${shortRun} · ${status ?? 'unknown'} · ${formatDurationLabel(totalDurationMs)}`;
+    }
+    async catch(error) {
+        return handleApiError(error, (...args) => this.error(...args), {
+            404: 'Workflow not found. Check the workflow ID.'
+        });
+    }
+}

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

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

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

@@ -0,0 +1,26 @@
+import { describe, it, expect, vi } from 'vitest';
+// Isolate the command module from the API/service layer at import time.
+vi.mock('../../services/workflow_history.js', () => ({
+    fetchWorkflowHistory: vi.fn()
+}));
+describe('workflow history command', () => {
+    it('exports a valid OCLIF command with a workflowId arg', async () => {
+        const WorkflowHistory = (await import('./history.js')).default;
+        expect(WorkflowHistory).toBeDefined();
+        expect(WorkflowHistory.description).toContain('waterfall');
+        expect(WorkflowHistory.args).toHaveProperty('workflowId');
+        expect(WorkflowHistory.args.workflowId.required).toBe(true);
+    });
+    it('declares the expected flags and defaults', async () => {
+        const WorkflowHistory = (await import('./history.js')).default;
+        const flags = WorkflowHistory.flags;
+        expect(flags).toHaveProperty('run-id');
+        expect(flags).toHaveProperty('raw');
+        expect(flags).toHaveProperty('include-payloads');
+        expect(flags).toHaveProperty('color');
+        expect(flags).toHaveProperty('width');
+        expect(flags.format.options).toEqual(['text', 'json']);
+        expect(flags.format.default).toBe('text');
+        expect(flags.raw.default).toBe(false);
+    });
+});

package/dist/generated/framework_version.json

@@ -1,3 +1,3 @@
 {
-    "framework": "0.9.1-next.6fe398d.0"
+    "framework": "0.9.1"
 }

package/dist/services/workflow_history/correlator.d.ts

@@ -0,0 +1,26 @@
+export type SpanStatus = 'pending' | 'running' | 'completed' | 'failed';
+export type SpanKind = 'activity' | 'child_workflow';
+export interface Span {
+    id: string;
+    name: string;
+    technicalName: string;
+    description: string | null;
+    status: SpanStatus;
+    kind: SpanKind;
+    attempt: number;
+    startedAt: string | null;
+    scheduledAt: string | null;
+    completedAt: string | null;
+    startOffsetMs: number;
+    endOffsetMs: number;
+    durationMs: number;
+    failureMessage: string | null;
+    input?: unknown;
+    output?: unknown;
+}
+export type HistoryEvent = Record<string, unknown>;
+/**
+ * @param events - flat Temporal history events, in chronological order
+ * @param workflowStartTimeMs - epoch ms used as the timeline origin (0 offset)
+ */
+export declare function correlate(events: HistoryEvent[], workflowStartTimeMs: number | null): Span[];

package/dist/services/workflow_history/correlator.js

@@ -0,0 +1,261 @@
+/**
+ * Correlates a flat list of Temporal history events into per-activity spans.
+ *
+ * Each ACTIVITY_TASK_SCHEDULED event opens a span (its eventId IS the
+ * scheduledEventId every subsequent ACTIVITY_TASK_* event for the same activity
+ * references). STARTED, COMPLETED, FAILED, TIMED_OUT, and CANCELED events extend
+ * that span. Spans without a terminal event are 'running' (if STARTED was seen)
+ * or 'pending'.
+ *
+ * Child workflows follow the same pattern but with their own event family:
+ * START_CHILD_WORKFLOW_EXECUTION_INITIATED opens the span, then
+ * CHILD_WORKFLOW_EXECUTION_STARTED / _COMPLETED / _FAILED / _TIMED_OUT /
+ * _CANCELED / _TERMINATED reference it via `initiatedEventId`.
+ *
+ * Pure function — no I/O. A TypeScript port of Atlas's
+ * `OutputWorkflows::WorkflowHistory::Correlator` (Ruby). Kept structurally
+ * faithful so the two stay easy to diff. The CLI has no step catalog, so a
+ * span's display name is the humanized step name rather than a catalog label.
+ */
+import { capitalCase } from 'change-case';
+// Framework-level activities the user doesn't care about — Output's own trace
+// destination resolution and the lifecycle webhook back to Atlas.
+const NOISE_STEP_PREFIXES = ['__internal#'];
+const NOISE_STEP_EXACT = ['$shared#callWebhook'];
+const ACTIVITY_TERMINAL_TYPES = [
+    'ACTIVITY_TASK_COMPLETED', 'ACTIVITY_TASK_FAILED',
+    'ACTIVITY_TASK_TIMED_OUT', 'ACTIVITY_TASK_CANCELED'
+];
+const CHILD_TERMINAL_TYPES = [
+    'CHILD_WORKFLOW_EXECUTION_COMPLETED', 'CHILD_WORKFLOW_EXECUTION_FAILED',
+    'CHILD_WORKFLOW_EXECUTION_TIMED_OUT', 'CHILD_WORKFLOW_EXECUTION_CANCELED',
+    'CHILD_WORKFLOW_EXECUTION_TERMINATED', 'START_CHILD_WORKFLOW_EXECUTION_FAILED'
+];
+function eventTypeName(event) {
+    return event.eventTypeName ?? '';
+}
+function eventId(event) {
+    return String(event.eventId);
+}
+function eventAttributes(event) {
+    const key = event && Object.keys(event).find(k => k.endsWith('EventAttributes'));
+    return key ? event[key] : undefined;
+}
+// Temporal's int64 fields arrive as either a String (the API serializer
+// stringifies scheduledEventId / startedEventId) or a raw protobuf Long struct
+// `{ low, high, unsigned }` (initiatedEventId, etc). Normalize to a String key
+// so both shapes match the opener event's stringified eventId.
+function normalizeEventId(value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    if (typeof value === 'string') {
+        return value || null;
+    }
+    if (typeof value === 'object' && 'low' in value) {
+        const low = value.low;
+        return low === null || low === undefined ? null : String(low);
+    }
+    return String(value) || null;
+}
+function scheduledEventIdFor(event) {
+    return normalizeEventId(eventAttributes(event)?.scheduledEventId);
+}
+function initiatedEventIdFor(event) {
+    return normalizeEventId(eventAttributes(event)?.initiatedEventId);
+}
+// For the noise filter: the full `workflow#step` name (prefixes/exacts match it).
+function fullStepName(scheduled) {
+    const attrs = eventAttributes(scheduled) ?? {};
+    return attrs.activityType?.name ??
+        attrs.stepName ??
+        'unknown';
+}
+// For display: the bare step name (segment after `#`). The API serializer
+// already exposes this as `stepName`; fall back to splitting `activityType.name`.
+function cleanStepName(scheduled) {
+    const attrs = eventAttributes(scheduled) ?? {};
+    const explicit = attrs.stepName;
+    if (explicit) {
+        return explicit;
+    }
+    const full = attrs.activityType?.name;
+    if (full) {
+        return full.includes('#') ? full.split('#').pop() : full;
+    }
+    return 'unknown';
+}
+function isNoise(stepName) {
+    return NOISE_STEP_EXACT.includes(stepName) ||
+        NOISE_STEP_PREFIXES.some(prefix => stepName.startsWith(prefix));
+}
+function failureMessageOf(attrs) {
+    const failure = attrs.failure;
+    return failure?.message ?? null;
+}
+function attemptFor(started) {
+    return eventAttributes(started ?? undefined)?.attempt ?? 1;
+}
+function statusFor(started, terminalStatus) {
+    if (terminalStatus) {
+        return terminalStatus;
+    }
+    return started ? 'running' : 'pending';
+}
+function parseTime(value) {
+    if (value === null || value === undefined || value === '') {
+        return null;
+    }
+    return String(value);
+}
+function toMs(iso) {
+    if (!iso) {
+        return null;
+    }
+    const ms = Date.parse(iso);
+    return Number.isNaN(ms) ? null : ms;
+}
+// Offset math relative to the workflow start (timeline origin). Mirrors
+// Atlas's Span#start_offset_ms / #end_offset_ms / #duration_ms.
+function withOffsets(span, startMs) {
+    const startAnchor = toMs(span.startedAt) ?? toMs(span.scheduledAt);
+    const startOffsetMs = startMs !== null && startAnchor !== null ? Math.round(startAnchor - startMs) : 0;
+    const endAnchor = toMs(span.completedAt) ?? toMs(span.startedAt);
+    const endOffsetMs = startMs !== null && endAnchor !== null ? Math.round(endAnchor - startMs) : startOffsetMs;
+    return { ...span, startOffsetMs, endOffsetMs, durationMs: endOffsetMs - startOffsetMs };
+}
+function resolveActivityTerminal(terminal) {
+    if (!terminal) {
+        return {};
+    }
+    const attrs = eventAttributes(terminal) ?? {};
+    const completedAt = parseTime(terminal.eventTime);
+    switch (eventTypeName(terminal)) {
+        case 'ACTIVITY_TASK_COMPLETED':
+            return { status: 'completed', completedAt, output: attrs.result };
+        case 'ACTIVITY_TASK_FAILED':
+            return { status: 'failed', completedAt, failureMessage: failureMessageOf(attrs) };
+        case 'ACTIVITY_TASK_TIMED_OUT':
+            return { status: 'failed', completedAt, failureMessage: 'Timed out' };
+        case 'ACTIVITY_TASK_CANCELED':
+            return { status: 'failed', completedAt, failureMessage: 'Canceled' };
+        default:
+            return {};
+    }
+}
+function resolveChildTerminal(terminal) {
+    if (!terminal) {
+        return {};
+    }
+    const attrs = eventAttributes(terminal) ?? {};
+    const completedAt = parseTime(terminal.eventTime);
+    switch (eventTypeName(terminal)) {
+        case 'CHILD_WORKFLOW_EXECUTION_COMPLETED':
+            return { status: 'completed', completedAt, output: attrs.result };
+        case 'CHILD_WORKFLOW_EXECUTION_FAILED':
+            return { status: 'failed', completedAt, failureMessage: failureMessageOf(attrs) };
+        case 'CHILD_WORKFLOW_EXECUTION_TIMED_OUT':
+            return { status: 'failed', completedAt, failureMessage: 'Timed out' };
+        case 'CHILD_WORKFLOW_EXECUTION_CANCELED':
+            return { status: 'failed', completedAt, failureMessage: 'Canceled' };
+        case 'CHILD_WORKFLOW_EXECUTION_TERMINATED':
+            return { status: 'failed', completedAt, failureMessage: 'Terminated' };
+        case 'START_CHILD_WORKFLOW_EXECUTION_FAILED':
+            return { status: 'failed', completedAt, failureMessage: attrs.cause || 'Failed to start' };
+        default:
+            return {};
+    }
+}
+function buildActivitySpan(id, slot, startMs) {
+    const { scheduled, started, terminal } = slot;
+    const scheduledAttrs = eventAttributes(scheduled) ?? {};
+    const terminalFields = resolveActivityTerminal(terminal);
+    return withOffsets({
+        id,
+        name: capitalCase(cleanStepName(scheduled)),
+        technicalName: fullStepName(scheduled),
+        description: null,
+        status: statusFor(started, terminalFields.status),
+        kind: 'activity',
+        attempt: attemptFor(started),
+        input: scheduledAttrs.input,
+        output: terminalFields.output,
+        startedAt: parseTime(started?.eventTime),
+        scheduledAt: parseTime(scheduled.eventTime),
+        completedAt: terminalFields.completedAt ?? null,
+        failureMessage: terminalFields.failureMessage ?? null
+    }, startMs);
+}
+// Child workflow spans render from the initiated event time so the full child
+// duration is visible (matching Temporal's own UI). Pending children anchor at
+// initiated time rather than null, else they'd all stack at offset 0.
+function buildChildSpan(id, slot, startMs) {
+    const { scheduled, started, terminal } = slot;
+    const scheduledAttrs = eventAttributes(scheduled) ?? {};
+    const workflowType = scheduledAttrs.workflowType?.name ??
+        'child_workflow';
+    const terminalFields = resolveChildTerminal(terminal);
+    return withOffsets({
+        id: `child-${id}`,
+        name: capitalCase(workflowType),
+        technicalName: workflowType,
+        description: null,
+        status: statusFor(started, terminalFields.status),
+        kind: 'child_workflow',
+        attempt: 1,
+        input: scheduledAttrs.input,
+        output: terminalFields.output,
+        startedAt: parseTime(scheduled.eventTime),
+        scheduledAt: parseTime(scheduled.eventTime),
+        completedAt: terminalFields.completedAt ?? null,
+        failureMessage: terminalFields.failureMessage ?? null
+    }, startMs);
+}
+function emptySlot(opener) {
+    return { scheduled: opener, started: null, terminal: null };
+}
+function attach(slots, event, key) {
+    if (!key) {
+        return;
+    }
+    const slot = slots.get(key);
+    if (!slot) {
+        return;
+    }
+    if (eventTypeName(event).endsWith('_STARTED')) {
+        slot.started = event;
+    }
+    else {
+        slot.terminal = event;
+    }
+}
+/**
+ * @param events - flat Temporal history events, in chronological order
+ * @param workflowStartTimeMs - epoch ms used as the timeline origin (0 offset)
+ */
+export function correlate(events, workflowStartTimeMs) {
+    const activities = new Map();
+    const children = new Map();
+    for (const event of events) {
+        const type = eventTypeName(event);
+        if (type === 'ACTIVITY_TASK_SCHEDULED') {
+            activities.set(eventId(event), emptySlot(event));
+        }
+        else if (type === 'ACTIVITY_TASK_STARTED' || ACTIVITY_TERMINAL_TYPES.includes(type)) {
+            attach(activities, event, scheduledEventIdFor(event));
+        }
+        else if (type === 'START_CHILD_WORKFLOW_EXECUTION_INITIATED') {
+            children.set(eventId(event), emptySlot(event));
+        }
+        else if (type === 'CHILD_WORKFLOW_EXECUTION_STARTED' || CHILD_TERMINAL_TYPES.includes(type)) {
+            attach(children, event, initiatedEventIdFor(event));
+        }
+    }
+    const activitySpans = [...activities.entries()]
+        .filter(([, slot]) => !isNoise(fullStepName(slot.scheduled)))
+        .map(([id, slot]) => buildActivitySpan(id, slot, workflowStartTimeMs));
+    const childSpans = [...children.entries()]
+        .map(([id, slot]) => buildChildSpan(id, slot, workflowStartTimeMs))
+        .filter(span => !isNoise(span.technicalName));
+    return [...activitySpans, ...childSpans].sort((a, b) => a.startOffsetMs - b.startOffsetMs);
+}

package/dist/services/workflow_history/correlator.spec.d.ts

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

package/dist/services/workflow_history/correlator.spec.js

@@ -0,0 +1,116 @@
+import { describe, it, expect } from 'vitest';
+import { correlate } from './correlator.js';
+const T0 = Date.parse('2026-06-22T12:00:00.000Z');
+const at = (seconds) => new Date(T0 + (seconds * 1000)).toISOString();
+// Minimal Temporal-shaped event builders.
+const scheduled = (id, name, sec, input) => ({
+    eventId: id,
+    eventTypeName: 'ACTIVITY_TASK_SCHEDULED',
+    eventTime: at(sec),
+    activityTaskScheduledEventAttributes: { activityType: { name }, activityId: `act-${id}`, input }
+});
+const started = (id, scheduledEventId, sec) => ({
+    eventId: id,
+    eventTypeName: 'ACTIVITY_TASK_STARTED',
+    eventTime: at(sec),
+    activityTaskStartedEventAttributes: { scheduledEventId, attempt: 1 }
+});
+const completed = (id, scheduledEventId, sec) => ({
+    eventId: id,
+    eventTypeName: 'ACTIVITY_TASK_COMPLETED',
+    eventTime: at(sec),
+    activityTaskCompletedEventAttributes: { scheduledEventId, result: { ok: true } }
+});
+const failed = (id, scheduledEventId, sec, message) => ({
+    eventId: id,
+    eventTypeName: 'ACTIVITY_TASK_FAILED',
+    eventTime: at(sec),
+    activityTaskFailedEventAttributes: { scheduledEventId, failure: { message } }
+});
+function buildEvents() {
+    return [
+        { eventId: '1', eventTypeName: 'WORKFLOW_EXECUTION_STARTED', eventTime: at(0), workflowExecutionStartedEventAttributes: {} },
+        // Sequential completed activity (0s → 27s)
+        scheduled('2', 'contentBrief#compressText', 0, { text: 'x' }),
+        started('3', '2', 0),
+        completed('4', '2', 27),
+        // Parallel fan-out of the same step: one completes (1s), one fails (8s)
+        scheduled('5', 'contentBrief#scrapeSerpPage', 30),
+        scheduled('6', 'contentBrief#scrapeSerpPage', 30),
+        started('7', '5', 30),
+        started('8', '6', 30),
+        completed('9', '5', 31),
+        failed('10', '6', 38, 'boom'),
+        // Noise steps — must be filtered out
+        scheduled('11', '$shared#callWebhook', 35),
+        started('11s', '11', 35),
+        scheduled('12', '__internal#resolveTrace', 35),
+        // Pending activity (scheduled, never started)
+        scheduled('13', 'contentBrief#generateBrief', 40),
+        // Child workflow (initiatedEventId arrives as a protobuf Long struct)
+        {
+            eventId: '20', eventTypeName: 'START_CHILD_WORKFLOW_EXECUTION_INITIATED', eventTime: at(50),
+            startChildWorkflowExecutionInitiatedEventAttributes: { workflowType: { name: 'subWorkflow' } }
+        },
+        {
+            eventId: '21', eventTypeName: 'CHILD_WORKFLOW_EXECUTION_STARTED', eventTime: at(50),
+            childWorkflowExecutionStartedEventAttributes: { initiatedEventId: { low: 20, high: 0, unsigned: false } }
+        },
+        {
+            eventId: '22', eventTypeName: 'CHILD_WORKFLOW_EXECUTION_COMPLETED', eventTime: at(60),
+            childWorkflowExecutionCompletedEventAttributes: { initiatedEventId: { low: 20, high: 0, unsigned: false }, result: { done: true } }
+        }
+    ];
+}
+describe('correlate', () => {
+    const spans = correlate(buildEvents(), T0);
+    const byId = (id) => spans.find(s => s.id === id);
+    it('filters framework noise steps', () => {
+        expect(spans.every(s => !s.technicalName.startsWith('__internal#'))).toBe(true);
+        expect(spans.some(s => s.technicalName === '$shared#callWebhook')).toBe(false);
+    });
+    it('produces one span per real activity plus the child workflow', () => {
+        expect(spans).toHaveLength(5);
+    });
+    it('returns spans sorted by start offset', () => {
+        const offsets = spans.map(s => s.startOffsetMs);
+        expect(offsets).toEqual([...offsets].sort((a, b) => a - b));
+    });
+    it('correlates a completed activity with humanized name, offset, and duration', () => {
+        const compress = byId('2');
+        expect(compress.name).toBe('Compress Text');
+        expect(compress.status).toBe('completed');
+        expect(compress.startOffsetMs).toBe(0);
+        expect(compress.durationMs).toBe(27_000);
+        expect(compress.attempt).toBe(1);
+        expect(compress.kind).toBe('activity');
+    });
+    it('distinguishes parallel instances of the same step', () => {
+        const ok = byId('5');
+        const bad = byId('6');
+        expect(ok.name).toBe('Scrape Serp Page');
+        expect(ok.status).toBe('completed');
+        expect(ok.startOffsetMs).toBe(30_000);
+        expect(ok.durationMs).toBe(1_000);
+        expect(bad.status).toBe('failed');
+        expect(bad.failureMessage).toBe('boom');
+        expect(bad.durationMs).toBe(8_000);
+    });
+    it('marks a scheduled-only activity pending with a zero-duration span at its scheduled offset', () => {
+        const pending = byId('13');
+        expect(pending.status).toBe('pending');
+        expect(pending.startOffsetMs).toBe(40_000);
+        expect(pending.durationMs).toBe(0);
+    });
+    it('correlates a child workflow via a Long-struct initiatedEventId', () => {
+        const child = byId('child-20');
+        expect(child.name).toBe('Sub Workflow');
+        expect(child.kind).toBe('child_workflow');
+        expect(child.status).toBe('completed');
+        expect(child.startOffsetMs).toBe(50_000);
+        expect(child.durationMs).toBe(10_000);
+    });
+    it('is robust to an empty event list', () => {
+        expect(correlate([], T0)).toEqual([]);
+    });
+});

package/dist/services/workflow_history.d.ts

@@ -0,0 +1,23 @@
+import { type HistoryEvent, type Span } from '#services/workflow_history/correlator.js';
+export interface WorkflowMeta {
+    workflowId?: string;
+    runId?: string;
+    status?: string;
+    startTime?: string;
+    closeTime?: string | null;
+    historyLength?: number;
+    taskQueue?: string;
+}
+export interface FetchWorkflowHistoryOptions {
+    workflowId: string;
+    runId?: string;
+    includePayloads?: boolean;
+}
+export interface WorkflowHistoryResult {
+    workflow: WorkflowMeta | null;
+    runId: string | null;
+    events: HistoryEvent[];
+    spans: Span[];
+    totalDurationMs: number;
+}
+export declare function fetchWorkflowHistory(options: FetchWorkflowHistoryOptions): Promise<WorkflowHistoryResult>;

package/dist/services/workflow_history.js

@@ -0,0 +1,79 @@
+/**
+ * Fetches a workflow run's full Temporal history from the API and correlates the
+ * flat event stream into spans (one per step) the CLI can render as a waterfall.
+ *
+ * Pages through `GET /workflow/{id}/history` (mirroring Atlas's
+ * OutputWorkflows::WorkflowHistory): the first page carries the workflow
+ * metadata and resolves the run ID; subsequent pages echo that run ID alongside
+ * the `nextPageToken` (the endpoint requires runId once a pageToken is used).
+ */
+import { getWorkflowIdHistory } from '#api/generated/api.js';
+import { correlate } from '#services/workflow_history/correlator.js';
+const PAGE_SIZE = 50;
+function toMs(value) {
+    if (!value) {
+        return null;
+    }
+    const ms = Date.parse(String(value));
+    return Number.isNaN(ms) ? null : ms;
+}
+function earliestEventMs(events) {
+    const times = events
+        .map(e => toMs(e.eventTime))
+        .filter((ms) => ms !== null);
+    return times.length > 0 ? Math.min(...times) : null;
+}
+// Timeline origin (0 offset): the workflow's start time, falling back to the
+// WORKFLOW_EXECUTION_STARTED event, then the earliest event seen.
+function workflowStartMs(meta, events) {
+    const fromMeta = toMs(meta?.startTime);
+    if (fromMeta !== null) {
+        return fromMeta;
+    }
+    const started = events.find(e => e.eventTypeName === 'WORKFLOW_EXECUTION_STARTED');
+    const fromStarted = toMs(started?.eventTime);
+    if (fromStarted !== null) {
+        return fromStarted;
+    }
+    return earliestEventMs(events);
+}
+function totalDuration(meta, spans, startMs) {
+    const closeMs = toMs(meta?.closeTime ?? undefined);
+    if (closeMs !== null && startMs !== null && (closeMs - startMs) > 0) {
+        return closeMs - startMs;
+    }
+    const maxEnd = spans.reduce((max, span) => Math.max(max, span.endOffsetMs), 0);
+    return Math.max(maxEnd, 1);
+}
+async function fetchAllPages(workflowId, includePayloads, runId, pageToken, acc) {
+    const response = await getWorkflowIdHistory(workflowId, { runId, pageSize: PAGE_SIZE, pageToken, includePayloads });
+    if (!response.data) {
+        throw new Error('API returned invalid response (missing data)');
+    }
+    const data = response.data;
+    // The generated `data.workflow` is an opaque `{ [key: string]: unknown }`, so
+    // narrow it to WorkflowMeta via `unknown` (its real fields are validated by
+    // the server, mirroring Atlas's metadata shape).
+    const meta = acc.meta ?? data.workflow ?? null;
+    const resolvedRunId = runId ?? data.runId ?? acc.runId;
+    const events = [...acc.events, ...(data.events ?? [])];
+    const nextToken = data.nextPageToken ?? undefined;
+    const nextAcc = { meta, runId: resolvedRunId, events };
+    if (nextToken) {
+        return fetchAllPages(workflowId, includePayloads, resolvedRunId, nextToken, nextAcc);
+    }
+    return nextAcc;
+}
+export async function fetchWorkflowHistory(options) {
+    const { workflowId, runId, includePayloads = false } = options;
+    const { meta, runId: resolvedRunId, events } = await fetchAllPages(workflowId, includePayloads, runId, undefined, { meta: null, runId, events: [] });
+    const startMs = workflowStartMs(meta, events);
+    const spans = correlate(events, startMs);
+    return {
+        workflow: meta,
+        runId: resolvedRunId ?? meta?.runId ?? null,
+        events,
+        spans,
+        totalDurationMs: totalDuration(meta, spans, startMs)
+    };
+}