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

package/dist/services/docker.spec.js

@@ -1,11 +1,16 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { execFileSync, spawn } from 'node:child_process';
-import { parseServiceStatus, getServiceStatus, startDockerCompose, startDockerComposeDetached, stopDockerCompose, waitForServicesHealthy, isServiceHealthy, isServiceFailed } from './docker.js';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { parseServiceStatus, getServiceStatus, startDockerCompose, runDockerComposeUpDetached, stopDockerCompose, waitForServicesHealthy, isServiceHealthy, isServiceFailed, classifyStackState, STACK_STATE, resolveDockerComposePath, getDefaultDockerComposePath, DockerComposeConfigNotFoundError } from './docker.js';
 vi.mock('node:child_process', () => ({
     execSync: vi.fn(),
     execFileSync: vi.fn(),
     spawn: vi.fn()
 }));
+vi.mock('node:fs/promises', () => ({
+    default: { access: vi.fn() }
+}));
 const mockChildProcess = (process) => process;
 vi.mock('log-update', () => {
     const fn = vi.fn();
@@ -155,7 +160,7 @@ describe('docker service', () => {
                 onExit
             });
             expect(dockerProcess.on).toHaveBeenCalledWith('error', expect.any(Function));
-            expect(dockerProcess.on).toHaveBeenCalledWith('exit', expect.any(Function));
+            expect(dockerProcess.on).toHaveBeenCalledWith('close', expect.any(Function));
             streamHandlers.stdout?.(Buffer.from('starting services\n'));
             streamHandlers.stderr?.(Buffer.from('compose failed\n'));
             const error = new Error('Docker failed');
@@ -165,26 +170,99 @@ describe('docker service', () => {
             expect(onExit).toHaveBeenCalledWith(1, null, 'starting services\ncompose failed');
         });
     });
-    describe('startDockerComposeDetached', () => {
-        it('should pass --project-name and -d to docker compose up', () => {
-            vi.mocked(execFileSync).mockReturnValue('');
-            startDockerComposeDetached('/path/to/docker-compose.yml');
-            expect(execFileSync).toHaveBeenCalledWith('docker', [
+    describe('runDockerComposeUpDetached', () => {
+        const makeProcess = () => {
+            const handlers = {};
+            const proc = {
+                on: vi.fn((event, handler) => {
+                    if (event === 'error') {
+                        handlers.error = handler;
+                    }
+                    else {
+                        handlers.exit = handler;
+                    }
+                    return proc;
+                }),
+                stdout: {
+                    on: vi.fn((event, handler) => {
+                        handlers.stdout = handler;
+                        return proc.stdout;
+                    })
+                },
+                stderr: {
+                    on: vi.fn((event, handler) => {
+                        handlers.stderr = handler;
+                        return proc.stderr;
+                    })
+                }
+            };
+            return { proc, handlers };
+        };
+        it('passes --project-name and -d, tees output, and resolves with the exit code', async () => {
+            const { proc, handlers } = makeProcess();
+            vi.mocked(spawn).mockReturnValue(mockChildProcess(proc));
+            const stdoutSpy = vi.spyOn(process.stdout, 'write').mockReturnValue(true);
+            const promise = runDockerComposeUpDetached('/path/to/docker-compose.yml');
+            expect(spawn).toHaveBeenCalledWith('docker', [
                 'compose', '-f', '/path/to/docker-compose.yml',
                 '--project-directory', process.cwd(),
                 '--project-name', 'output-sdk',
                 'up', '-d'
-            ], expect.objectContaining({ stdio: 'inherit', cwd: process.cwd() }));
-        });
-        it('should append --pull when pullPolicy is provided', () => {
-            vi.mocked(execFileSync).mockReturnValue('');
-            startDockerComposeDetached('/path/to/docker-compose.yml', 'missing');
-            expect(execFileSync).toHaveBeenCalledWith('docker', [
+            ], expect.objectContaining({ cwd: process.cwd(), stdio: ['ignore', 'pipe', 'pipe'] }));
+            handlers.stdout?.(Buffer.from('pulling images\n'));
+            handlers.exit?.(0);
+            expect(await promise).toEqual({ code: 0, output: 'pulling images' });
+            expect(stdoutSpy).toHaveBeenCalledWith(Buffer.from('pulling images\n'));
+            stdoutSpy.mockRestore();
+        });
+        it('appends --pull when pullPolicy is provided', async () => {
+            const { proc, handlers } = makeProcess();
+            vi.mocked(spawn).mockReturnValue(mockChildProcess(proc));
+            vi.spyOn(process.stdout, 'write').mockReturnValue(true);
+            const promise = runDockerComposeUpDetached('/path/to/docker-compose.yml', 'missing');
+            handlers.exit?.(0);
+            await promise;
+            expect(spawn).toHaveBeenCalledWith('docker', [
                 'compose', '-f', '/path/to/docker-compose.yml',
                 '--project-directory', process.cwd(),
                 '--project-name', 'output-sdk',
                 'up', '-d', '--pull', 'missing'
-            ], expect.objectContaining({ stdio: 'inherit', cwd: process.cwd() }));
+            ], expect.objectContaining({ cwd: process.cwd() }));
+        });
+        it('resolves with a non-zero code and captured stderr so the caller can hint the collision', async () => {
+            const { proc, handlers } = makeProcess();
+            vi.mocked(spawn).mockReturnValue(mockChildProcess(proc));
+            vi.spyOn(process.stderr, 'write').mockReturnValue(true);
+            const promise = runDockerComposeUpDetached('/path/to/docker-compose.yml');
+            handlers.stderr?.(Buffer.from('Error: address already in use\n'));
+            handlers.exit?.(1);
+            expect(await promise).toEqual({ code: 1, output: 'Error: address already in use' });
+        });
+        it('rejects when the docker process fails to spawn', async () => {
+            const { proc, handlers } = makeProcess();
+            vi.mocked(spawn).mockReturnValue(mockChildProcess(proc));
+            const promise = runDockerComposeUpDetached('/path/to/docker-compose.yml');
+            handlers.error?.(new Error('spawn ENOENT'));
+            await expect(promise).rejects.toThrow('spawn ENOENT');
+        });
+    });
+    describe('resolveDockerComposePath', () => {
+        it('resolves a custom path against cwd and returns it when it exists', async () => {
+            vi.mocked(fs.access).mockResolvedValue(undefined);
+            const result = await resolveDockerComposePath('custom/compose.yml');
+            const expected = path.resolve(process.cwd(), 'custom/compose.yml');
+            expect(result).toBe(expected);
+            expect(fs.access).toHaveBeenCalledWith(expected);
+        });
+        it('throws DockerComposeConfigNotFoundError when the path does not exist', async () => {
+            vi.mocked(fs.access).mockRejectedValue(new Error('ENOENT'));
+            await expect(resolveDockerComposePath('missing.yml'))
+                .rejects.toBeInstanceOf(DockerComposeConfigNotFoundError);
+        });
+        it('falls back to the bundled default when no custom path is given', async () => {
+            vi.mocked(fs.access).mockResolvedValue(undefined);
+            const result = await resolveDockerComposePath();
+            expect(result).toBe(getDefaultDockerComposePath());
         });
     });
     describe('DOCKER_SERVICE_NAME wiring', () => {
@@ -259,6 +337,58 @@ describe('docker service', () => {
             expect(isServiceFailed({ name: 'temporal', state: 'running', health: 'starting', ports: [] })).toBe(false);
         });
     });
+    describe('classifyStackState', () => {
+        const svc = (state, health) => ({ name: 's', state, health, ports: [] });
+        it('returns NONE for an empty stack (fresh start)', () => {
+            expect(classifyStackState([])).toBe(STACK_STATE.NONE);
+        });
+        it('returns RUNNING when every service is up and healthy', () => {
+            expect(classifyStackState([
+                svc('running', 'healthy'),
+                svc('running', 'none')
+            ])).toBe(STACK_STATE.RUNNING);
+        });
+        it('returns PARTIAL when any service has failed (orphaned stack)', () => {
+            expect(classifyStackState([
+                svc('running', 'healthy'),
+                svc('exited', 'none')
+            ])).toBe(STACK_STATE.PARTIAL);
+        });
+        it('returns PARTIAL when services exist but some are still coming up', () => {
+            expect(classifyStackState([
+                svc('running', 'healthy'),
+                svc('created', 'none')
+            ])).toBe(STACK_STATE.PARTIAL);
+        });
+        it('treats an unhealthy service as PARTIAL, not RUNNING', () => {
+            expect(classifyStackState([
+                svc('running', 'healthy'),
+                svc('running', 'unhealthy')
+            ])).toBe(STACK_STATE.PARTIAL);
+        });
+        // `ps --all` reports exited containers, so a stack stopped by a reboot, a
+        // `docker compose stop`, or a failed teardown still has rows. Nothing is
+        // live, so this invocation would be the one starting it — that makes it an
+        // owned fresh start, not an attach.
+        it('returns NONE when every service is exited — an owned fresh start, not an attach', () => {
+            expect(classifyStackState([
+                svc('exited', 'none'),
+                svc('exited', 'none')
+            ])).toBe(STACK_STATE.NONE);
+        });
+        it('returns NONE when containers are created but none have started', () => {
+            expect(classifyStackState([
+                svc('created', 'none'),
+                svc('created', 'none')
+            ])).toBe(STACK_STATE.NONE);
+        });
+        it('still returns PARTIAL when at least one service is live', () => {
+            expect(classifyStackState([
+                svc('running', 'healthy'),
+                svc('exited', 'none')
+            ])).toBe(STACK_STATE.PARTIAL);
+        });
+    });
     describe('waitForServicesHealthy', () => {
         it('should resolve when all services are healthy', async () => {
             const mockOutput = `{"Service":"redis","State":"running","Health":"healthy","Publishers":[]}

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

@@ -19,6 +19,8 @@ export interface Span {
     output?: unknown;
 }
 export type HistoryEvent = Record<string, unknown>;
+export declare function eventTypeName(event: HistoryEvent): string;
+export declare function eventAttributes(event?: HistoryEvent): Record<string, unknown> | undefined;
 /**
  * @param events - flat Temporal history events, in chronological order
  * @param workflowStartTimeMs - epoch ms used as the timeline origin (0 offset)

package/dist/services/workflow_history/correlator.js

@@ -24,13 +24,13 @@ const CHILD_TERMINAL_TYPES = [
     'CHILD_WORKFLOW_EXECUTION_TIMED_OUT', 'CHILD_WORKFLOW_EXECUTION_CANCELED',
     'CHILD_WORKFLOW_EXECUTION_TERMINATED', 'START_CHILD_WORKFLOW_EXECUTION_FAILED'
 ];
-function eventTypeName(event) {
+export function eventTypeName(event) {
     return event.eventTypeName ?? '';
 }
 function eventId(event) {
     return String(event.eventId);
 }
-function eventAttributes(event) {
+export function eventAttributes(event) {
     const key = event && Object.keys(event).find(k => k.endsWith('EventAttributes'));
     return key ? event[key] : undefined;
 }

package/dist/services/workflow_history.d.ts

@@ -12,12 +12,40 @@ export interface FetchWorkflowHistoryOptions {
     workflowId: string;
     runId?: string;
     includePayloads?: boolean;
+    longPollTimeoutMs?: number;
 }
 export interface WorkflowHistoryResult {
     workflow: WorkflowMeta | null;
+    rawWorkflow: WorkflowMeta | null;
     runId: string | null;
     events: HistoryEvent[];
     spans: Span[];
     totalDurationMs: number;
+    continuedAsNewRunId: string | null;
+    cursor: WorkflowHistoryCursor;
+}
+/**
+ * Resume state for `fetchWorkflowHistoryUpdates`: the accumulated events (so spans/duration
+ * are always computed over the full history, not just the latest delta), `lastEventId` for
+ * de-duping a replayed page, and `pageToken` — the position that fetched the *current* end of
+ * history, which is itself always a valid resume point (see `fetchPages`) even though the
+ * server's own `nextPageToken` for that position is empty.
+ */
+export interface WorkflowHistoryCursor {
+    pageToken: string | undefined;
+    lastEventId: number;
+    meta: WorkflowMeta | null;
+    runId: string | undefined;
+    events: HistoryEvent[];
 }
 export declare function fetchWorkflowHistory(options: FetchWorkflowHistoryOptions): Promise<WorkflowHistoryResult>;
+/**
+ * Incremental counterpart to `fetchWorkflowHistory`, for a poller (`workflow monitor`) that
+ * calls repeatedly while a workflow is still running. Pass the previous call's `cursor`
+ * (from either function's result) to resume from where it left off instead of re-paging the
+ * whole history; omit it only to start a completely fresh walk.
+ */
+export declare function fetchWorkflowHistoryUpdates(options: FetchWorkflowHistoryOptions, cursor?: WorkflowHistoryCursor): Promise<{
+    result: WorkflowHistoryResult;
+    cursor: WorkflowHistoryCursor;
+}>;

package/dist/services/workflow_history.js

@@ -8,8 +8,20 @@
  * 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';
+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';
 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));
+}
+function numericEventId(event) {
+    const id = Number(event.eventId);
+    return Number.isFinite(id) ? id : 0;
+}
 function toMs(value) {
     if (!value) {
         return null;
@@ -37,6 +49,13 @@ function workflowStartMs(meta, events) {
     }
     return earliestEventMs(events);
 }
+// The paginated history endpoint doesn't surface a resolved `newRunId` the way
+// the SSE stream endpoint does (see `stream_history.js`'s `doneChunk`), so pull
+// it directly off the WORKFLOW_EXECUTION_CONTINUED_AS_NEW event when present.
+function continuedAsNewRunId(events) {
+    const terminal = events.find(e => eventTypeName(e) === 'WORKFLOW_EXECUTION_CONTINUED_AS_NEW');
+    return eventAttributes(terminal)?.newExecutionRunId ?? null;
+}
 function totalDuration(meta, spans, startMs) {
     const closeMs = toMs(meta?.closeTime ?? undefined);
     if (closeMs !== null && startMs !== null && (closeMs - startMs) > 0) {
@@ -45,35 +64,99 @@ function totalDuration(meta, spans, 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 });
+/**
+ * Pages through history starting from `acc` (its `pageToken`/`lastEventId`/`events` carry
+ * the resume position — pass a zeroed cursor for a fresh walk). When `longPollTimeoutMs` is
+ * set, every request asks the server to long-poll (`waitNewEvent`) rather than return
+ * immediately, so the final hop blocks — up to that many milliseconds (clamped to the server's
+ * ceiling) — until either a new event exists or the deadline elapses. `lastEventId` de-dupes:
+ * resuming from a previously-seen page token replays that page's events, which are filtered out
+ * here rather than appended twice.
+ */
+async function fetchPages(workflowId, includePayloads, acc, longPollTimeoutMs) {
+    const wait = longPollTimeoutMs !== undefined && longPollTimeoutMs > 0;
+    const { pageToken, runId } = acc;
+    const response = await getWorkflowIdHistory(workflowId, {
+        runId, pageSize: PAGE_SIZE, pageToken, includePayloads,
+        ...(wait ? { longPollTimeoutMs } : {})
+    });
     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;
+    // the server, mirroring Atlas's metadata shape). Prefer the *fresh* value when the
+    // server sent one — it re-describes on every `wait` call specifically so status
+    // updates (e.g. running -> completed) are seen; falling back to `acc.meta` only
+    // covers the pages within a walk where the server didn't re-describe.
+    const meta = data.workflow ?? acc.meta;
     const resolvedRunId = runId ?? data.runId ?? acc.runId;
-    const events = [...acc.events, ...(data.events ?? [])];
+    const pageEvents = data.events ?? [];
+    const newEvents = pageEvents.filter(event => numericEventId(event) > acc.lastEventId);
+    const events = [...acc.events, ...newEvents];
+    // Events arrive in increasing eventId order, so the last new one is the max — no scan needed.
+    const lastEventId = newEvents.length > 0 ? numericEventId(newEvents[newEvents.length - 1]) : acc.lastEventId;
     const nextToken = data.nextPageToken ?? undefined;
-    const nextAcc = { meta, runId: resolvedRunId, events };
+    const nextAcc = { meta, runId: resolvedRunId, events, lastEventId, pageToken: nextToken ?? pageToken };
+    // While long-polling an open run, stop and hand back the first batch of new events
+    // instead of draining further pages — a poller needs each transition rendered as it
+    // arrives, and the buffered remainder will surface on subsequent ticks. Once the run
+    // is closed, though, no further ticks are coming: the poller acts on the closed
+    // status immediately, so stopping early would strand the trailing pages — including
+    // the terminal or CONTINUED_AS_NEW event — unfetched. Drain to the tip instead.
+    if (wait && newEvents.length > 0 && !isRunClosed(meta)) {
+        return nextAcc;
+    }
+    // The server echoes `pageToken` back unchanged (see `get_history.js`) when a waitNewEvent
+    // call's deadline elapses with nothing new — that's the tip, stop for this tick.
+    const timedOut = wait && nextToken === pageToken;
+    if (timedOut) {
+        return nextAcc;
+    }
     if (nextToken) {
-        return fetchAllPages(workflowId, includePayloads, resolvedRunId, nextToken, nextAcc);
+        return fetchPages(workflowId, includePayloads, nextAcc, longPollTimeoutMs);
     }
+    // Drained: the server has nothing more buffered (`nextToken` is empty), but unlike
+    // `nextToken`, `pageToken` — the position that fetched this now-empty page — is still a
+    // valid resume point: a future waitNewEvent call from here replays this page (de-duped by
+    // `lastEventId`) and then genuinely waits at the tip, instead of restarting from page 1.
     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: [] });
+function buildResult(pages) {
+    const { meta: rawMeta, runId: resolvedRunId, events } = pages;
+    // Normalize once here so every consumer (monitor, history, etc.) sees the
+    // same status vocabulary, matching status.ts/workflow_runs.ts/etc.
+    const status = normalizeWorkflowStatus(rawMeta?.status);
+    const meta = rawMeta ? { ...rawMeta, status } : rawMeta;
     const startMs = workflowStartMs(meta, events);
     const spans = correlate(events, startMs);
     return {
         workflow: meta,
+        rawWorkflow: rawMeta,
         runId: resolvedRunId ?? meta?.runId ?? null,
         events,
         spans,
-        totalDurationMs: totalDuration(meta, spans, startMs)
+        totalDurationMs: totalDuration(meta, spans, startMs),
+        continuedAsNewRunId: continuedAsNewRunId(events),
+        cursor: pages
     };
 }
+export async function fetchWorkflowHistory(options) {
+    const { workflowId, runId, includePayloads = false } = options;
+    const pages = await fetchPages(workflowId, includePayloads, { meta: null, runId, events: [], lastEventId: 0, pageToken: undefined });
+    return buildResult(pages);
+}
+/**
+ * Incremental counterpart to `fetchWorkflowHistory`, for a poller (`workflow monitor`) that
+ * calls repeatedly while a workflow is still running. Pass the previous call's `cursor`
+ * (from either function's result) to resume from where it left off instead of re-paging the
+ * whole history; omit it only to start a completely fresh walk.
+ */
+export async function fetchWorkflowHistoryUpdates(options, cursor) {
+    const { workflowId, includePayloads = false, longPollTimeoutMs } = options;
+    const seed = cursor ??
+        { meta: null, runId: options.runId, events: [], lastEventId: 0, pageToken: undefined };
+    const pages = await fetchPages(workflowId, includePayloads, seed, longPollTimeoutMs);
+    return { result: buildResult(pages), cursor: pages };
+}

package/dist/services/workflow_history.spec.js

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { getWorkflowIdHistory } from '#api/generated/api.js';
-import { fetchWorkflowHistory } from '#services/workflow_history.js';
+import { fetchWorkflowHistory, fetchWorkflowHistoryUpdates } from '#services/workflow_history.js';
 vi.mock('#api/generated/api.js', () => ({ getWorkflowIdHistory: vi.fn() }));
 // The real correlator runs (only the API client is mocked), so spans are derived
 // from the events below — letting us assert duration/offset behaviour end to end.
@@ -48,6 +48,39 @@ describe('fetchWorkflowHistory', () => {
         expect(result.totalDurationMs).toBe(300_000); // closeTime - startTime
         expect(result.spans).toHaveLength(1);
         expect(result.spans[0].durationMs).toBe(27_000);
+        // Even though the server's own nextPageToken for the final page is empty (nothing more
+        // buffered), the cursor keeps the *request* token that reached it — a genuinely resumable
+        // position for a follow-up fetchWorkflowHistoryUpdates call. See fetchPages.
+        expect(result.cursor.pageToken).toBe('token-2');
+    });
+    it('a follow-up fetchWorkflowHistoryUpdates call resumes from fetchWorkflowHistory\'s cursor instead of re-paging from page 1', async () => {
+        mockGet
+            .mockResolvedValueOnce(page({
+            workflow: { workflowId: 'wf-123', runId: 'run-456', status: 'running', startTime: at(0) },
+            runId: 'run-456',
+            events: [workflowStarted(0), scheduled('2', 'wf#step', 0)],
+            nextPageToken: 'token-2'
+        }))
+            .mockResolvedValueOnce(page({
+            workflow: null,
+            runId: 'run-456',
+            events: [started('3', '2', 0)],
+            nextPageToken: null
+        }));
+        const first = await fetchWorkflowHistory({ workflowId: 'wf-123' });
+        expect(mockGet).toHaveBeenCalledTimes(2);
+        // The next tick replays the last page (deduped) then finds nothing new and times out —
+        // one call, not a full re-walk from page 1 through both prior pages again.
+        mockGet.mockResolvedValueOnce(page({
+            workflow: null, runId: 'run-456', events: [], nextPageToken: 'token-2'
+        }));
+        const { result, cursor } = await fetchWorkflowHistoryUpdates({ workflowId: 'wf-123', runId: 'run-456', longPollTimeoutMs: 2500 }, first.cursor);
+        expect(mockGet).toHaveBeenCalledTimes(3);
+        expect(mockGet).toHaveBeenNthCalledWith(3, 'wf-123', {
+            runId: 'run-456', pageSize: 50, pageToken: 'token-2', includePayloads: false, longPollTimeoutMs: 2500
+        });
+        expect(result.events).toHaveLength(3);
+        expect(cursor.pageToken).toBe('token-2');
     });
     it('forwards an explicit runId and includePayloads, stopping after a single page', async () => {
         mockGet.mockResolvedValueOnce(page({
@@ -84,4 +117,153 @@ describe('fetchWorkflowHistory', () => {
         mockGet.mockResolvedValueOnce({ status: 200 });
         await expect(fetchWorkflowHistory({ workflowId: 'wf-x' })).rejects.toThrow(/invalid response/);
     });
+    it('extracts the chained run id from a WORKFLOW_EXECUTION_CONTINUED_AS_NEW event', async () => {
+        mockGet.mockResolvedValueOnce(page({
+            workflow: { workflowId: 'wf-4', runId: 'run-4', status: 'continued_as_new', startTime: at(0) },
+            runId: 'run-4',
+            events: [
+                workflowStarted(0),
+                {
+                    eventId: '9', eventTypeName: 'WORKFLOW_EXECUTION_CONTINUED_AS_NEW', eventTime: at(60),
+                    workflowExecutionContinuedAsNewEventAttributes: { newExecutionRunId: 'run-5' }
+                }
+            ],
+            nextPageToken: null
+        }));
+        const result = await fetchWorkflowHistory({ workflowId: 'wf-4' });
+        expect(result.continuedAsNewRunId).toBe('run-5');
+    });
+    it('returns null continuedAsNewRunId when there is no continue-as-new event', async () => {
+        mockGet.mockResolvedValueOnce(page({
+            workflow: { workflowId: 'wf-5', runId: 'run-5', status: 'completed', startTime: at(0), closeTime: at(1) },
+            runId: 'run-5', events: [workflowStarted(0)], nextPageToken: null
+        }));
+        const result = await fetchWorkflowHistory({ workflowId: 'wf-5' });
+        expect(result.continuedAsNewRunId).toBeNull();
+    });
+});
+describe('fetchWorkflowHistoryUpdates', () => {
+    it('stops as soon as the first hop finds new events, without draining further buffered pages', async () => {
+        // Two pages already exist beyond the resume point; the old behavior kept paging until a
+        // timeout, which could silently merge several transitions (even a terminal one) into a
+        // single delayed render. A poller needs each batch back as soon as it has something new.
+        mockGet.mockResolvedValueOnce(page({
+            workflow: { workflowId: 'wf-7', runId: 'run-7', status: 'running', startTime: at(0) },
+            runId: 'run-7',
+            events: [workflowStarted(0)],
+            nextPageToken: 'page-2'
+        }));
+        const { result, cursor } = await fetchWorkflowHistoryUpdates({ workflowId: 'wf-7', runId: 'run-7', longPollTimeoutMs: 2500 });
+        expect(mockGet).toHaveBeenCalledTimes(1);
+        expect(mockGet).toHaveBeenCalledWith('wf-7', {
+            runId: 'run-7', pageSize: 50, pageToken: undefined, includePayloads: false, longPollTimeoutMs: 2500
+        });
+        expect(result.events).toHaveLength(1);
+        expect(result.workflow?.status).toBe('running');
+        // Resumes from the still-unfetched page 2 next time, not from the start.
+        expect(cursor.pageToken).toBe('page-2');
+        expect(cursor.lastEventId).toBe(1);
+    });
+    it('drains buffered pages when the describe already reports the run closed, so the terminal events are not stranded', async () => {
+        // >1 page of events accumulated between polls, then the run completed: the fresh
+        // describe says 'completed' before the closing events have been paged in. Stopping
+        // after the first batch would make the poller act on the terminal status with the
+        // final steps' events unfetched.
+        mockGet
+            .mockResolvedValueOnce(page({
+            workflow: { workflowId: 'wf-8', runId: 'run-8', status: 'completed', startTime: at(0), closeTime: at(30) },
+            runId: 'run-8',
+            events: [workflowStarted(0), scheduled('2', 'wf#step', 0)],
+            nextPageToken: 'page-2'
+        }))
+            .mockResolvedValueOnce(page({
+            workflow: null,
+            runId: 'run-8',
+            events: [started('3', '2', 1), completed('4', '2', 30)],
+            nextPageToken: null
+        }));
+        const { result } = await fetchWorkflowHistoryUpdates({ workflowId: 'wf-8', runId: 'run-8' });
+        expect(mockGet).toHaveBeenCalledTimes(2);
+        expect(result.events).toHaveLength(4);
+        expect(result.spans).toHaveLength(1);
+        expect(result.spans[0].status).toBe('completed');
+    });
+    it('drains to the CONTINUED_AS_NEW event on a later page when the describe already reports continued_as_new', async () => {
+        mockGet
+            .mockResolvedValueOnce(page({
+            workflow: { workflowId: 'wf-9', runId: 'run-9', status: 'continued_as_new', startTime: at(0) },
+            runId: 'run-9',
+            events: [workflowStarted(0)],
+            nextPageToken: 'page-2'
+        }))
+            .mockResolvedValueOnce(page({
+            workflow: null,
+            runId: 'run-9',
+            events: [{
+                    eventId: '2', eventTypeName: 'WORKFLOW_EXECUTION_CONTINUED_AS_NEW', eventTime: at(60),
+                    workflowExecutionContinuedAsNewEventAttributes: { newExecutionRunId: 'run-10' }
+                }],
+            nextPageToken: null
+        }));
+        const { result } = await fetchWorkflowHistoryUpdates({ workflowId: 'wf-9', runId: 'run-9' });
+        expect(mockGet).toHaveBeenCalledTimes(2);
+        expect(result.continuedAsNewRunId).toBe('run-10');
+    });
+    it('forwards longPollTimeoutMs to the API on a resumed poll', async () => {
+        mockGet.mockResolvedValueOnce(page({
+            workflow: { workflowId: 'wf-7', runId: 'run-7', status: 'running', startTime: at(0) },
+            runId: 'run-7', events: [], nextPageToken: null
+        }));
+        await fetchWorkflowHistoryUpdates({ workflowId: 'wf-7', runId: 'run-7', longPollTimeoutMs: 2500 });
+        expect(mockGet).toHaveBeenCalledWith('wf-7', {
+            runId: 'run-7', pageSize: 50, pageToken: undefined, includePayloads: false, longPollTimeoutMs: 2500
+        });
+    });
+    it('sends no long-poll param when longPollTimeoutMs is not provided', async () => {
+        mockGet.mockResolvedValueOnce(page({
+            workflow: { workflowId: 'wf-7', runId: 'run-7', status: 'running', startTime: at(0) },
+            runId: 'run-7', events: [], nextPageToken: null
+        }));
+        await fetchWorkflowHistoryUpdates({ workflowId: 'wf-7', runId: 'run-7' });
+        expect(mockGet).toHaveBeenCalledWith('wf-7', expect.not.objectContaining({ longPollTimeoutMs: expect.anything() }));
+    });
+    it('times out with the sent token echoed back when there is genuinely nothing new', async () => {
+        mockGet.mockResolvedValueOnce(page({
+            workflow: { workflowId: 'wf-7', runId: 'run-7', status: 'running', startTime: at(0) },
+            runId: 'run-7',
+            events: [],
+            nextPageToken: null
+        }));
+        const { result, cursor } = await fetchWorkflowHistoryUpdates({ workflowId: 'wf-7', runId: 'run-7' });
+        expect(mockGet).toHaveBeenCalledTimes(1);
+        expect(result.events).toHaveLength(0);
+        expect(cursor.pageToken).toBeUndefined();
+    });
+    it('resumes from a prior cursor and picks up the workflow status finishing, not the status frozen on the cursor', async () => {
+        const cursor = {
+            pageToken: 'token-2',
+            lastEventId: 2,
+            meta: { workflowId: 'wf-6', runId: 'run-6', status: 'running', startTime: at(0) },
+            runId: 'run-6',
+            events: [workflowStarted(0), scheduled('2', 'wf#step', 0)]
+        };
+        mockGet.mockResolvedValueOnce(page({
+            // The server re-describes on every `wait` call specifically so a resumed poll can see
+            // status changes — this must win over the (now-stale) status carried on the cursor.
+            workflow: { workflowId: 'wf-6', runId: 'run-6', status: 'completed', startTime: at(0), closeTime: at(5) },
+            runId: 'run-6',
+            events: [started('3', '2', 1), completed('4', '2', 5)],
+            nextPageToken: null
+        }));
+        const { result, cursor: nextCursor } = await fetchWorkflowHistoryUpdates({ workflowId: 'wf-6', runId: 'run-6', longPollTimeoutMs: 2500 }, cursor);
+        expect(mockGet).toHaveBeenCalledTimes(1);
+        expect(mockGet).toHaveBeenCalledWith('wf-6', {
+            runId: 'run-6', pageSize: 50, pageToken: 'token-2', includePayloads: false, longPollTimeoutMs: 2500
+        });
+        expect(result.workflow?.status).toBe('completed');
+        // The events already carried on the cursor (2) plus the genuinely new ones (2).
+        expect(result.events).toHaveLength(4);
+        expect(nextCursor.pageToken).toBe('token-2');
+        expect(nextCursor.lastEventId).toBe(4);
+    });
 });

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
 
 ```
@@ -44,7 +46,7 @@ config/
 ## Key Conventions
 
 - **Workflows are deterministic**: No I/O, no `Date.now()`, no `Math.random()` in `workflow.ts`. All side effects go in steps or evaluators.
-- **HTTP clients**: Always use `httpClient` from `@outputai/http` -- never raw `fetch` or `axios`. This enables automatic tracing and cost tracking.
+- **HTTP clients**: Use `outputFetch` or `createKyClient` from `@outputai/http` instead of raw `fetch` or `axios`. Requests are automatically traced; use `addRequestCost` when cost tracking is needed.
 - **LLM calls**: Use `generateText` from `@outputai/llm` with `.prompt` files. Never call LLM APIs directly.
 
 ---

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