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

package/dist/utils/port_collision.js

@@ -3,20 +3,25 @@
  * an actionable hint that names the conflicting port and the env var to
  * override.
  *
- * Docker compose surfaces port collisions through two common error shapes:
- *   - "Bind for 0.0.0.0:3001 failed: port is already allocated"
- *   - "failed to bind host port for 0.0.0.0:7233:.../tcp: address already in use"
+ * Docker wraps the same failure differently across versions and platforms —
+ * Docker 29 on macOS nests it three deep:
  *
- * We match both, extract the host port, then map it back to the env var that
- * sets it. The map prefers a runtime lookup of resolved ports (so a user who
- * already set OUTPUT_API_HOST_PORT=3050 sees that var named when 3050
- * collides) and falls back to a default-port table for the unresolved case.
+ *   Error response from daemon: failed to set up container networking: driver
+ *   failed programming external connectivity on endpoint out-api-1 (a1b2…):
+ *   Bind for 0.0.0.0:3001 failed: port is already allocated
+ *
+ * Matching whole message shapes means a new wrapper silently drops the hint, so
+ * we anchor on the terminal phrase instead and take the host port nearest to it.
+ * That survives wrappers we haven't seen.
+ *
+ * The port is then mapped back to the env var that sets it. The map prefers a
+ * runtime lookup of resolved ports (so a user who already set
+ * OUTPUT_API_HOST_PORT=3050 sees that var named when 3050 collides) and falls
+ * back to a default-port table for the unresolved case.
  */
-const PORT_BIND_PATTERNS = [
-    /Bind for [^:\s]+:(\d+) failed: port is already allocated/,
-    /failed to bind host port for [^:\s]+:(\d+)[^]*?address already in use/,
-    /listen tcp [^:\s]+:(\d+):\s*bind: address already in use/
-];
+const COLLISION_PHRASES = ['port is already allocated', 'address already in use'];
+/** Trailing `:<port>` in a fragment — the host port a bind failure names. */
+const TRAILING_PORT = /:(\d+)(?!.*:\d)/s;
 const DEFAULT_PORT_TO_ENV_VAR = {
     3001: 'OUTPUT_API_HOST_PORT',
     8080: 'OUTPUT_TEMPORAL_UI_HOST_PORT',
@@ -35,8 +40,15 @@ export function extractCollidedPort(stderr) {
     if (!stderr) {
         return null;
     }
-    for (const pattern of PORT_BIND_PATTERNS) {
-        const match = stderr.match(pattern);
+    for (const phrase of COLLISION_PHRASES) {
+        const phraseIndex = stderr.indexOf(phrase);
+        if (phraseIndex === -1) {
+            continue;
+        }
+        // The host port is the last one named before the phrase — every shape puts
+        // it there ("Bind for 0.0.0.0:3001 failed: port is already allocated",
+        // "listen tcp 0.0.0.0:3001: bind: address already in use").
+        const match = stderr.slice(0, phraseIndex).match(TRAILING_PORT);
         if (match) {
             return parseInt(match[1], 10);
         }
@@ -87,6 +99,19 @@ export function formatPortCollisionHint(stderr, resolvedPorts) {
     }
     return formatSingleCollision(port, resolvedPorts);
 }
+/**
+ * Compose a docker-failure message from a caller-supplied core sentence and the
+ * process's recent output: an actionable port-collision hint (when one is
+ * detected) is prepended, and the raw recent output is appended. Shared by the
+ * foreground exit handler and the detached/reconcile path so both surface the
+ * same failure shape.
+ */
+export function formatComposeFailure(reason, output, resolvedPorts) {
+    const hint = formatPortCollisionHint(output, resolvedPorts);
+    const prefix = hint ? `${hint}\n\n` : '';
+    const detail = output ? `\n\nRecent Docker output:\n${output}` : '';
+    return `${prefix}${reason}${detail}`;
+}
 /**
  * Build a hint from a known list of colliding ports. For a single collision
  * the output matches `formatPortCollisionHint` exactly so callers stay

package/dist/utils/port_collision.spec.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { extractCollidedPort, formatPortCollisionHint, formatPortCollisionsHint } from './port_collision.js';
+import { extractCollidedPort, formatPortCollisionHint, formatPortCollisionsHint, formatComposeFailure } from './port_collision.js';
 const DEFAULT_PORTS = { api: 3001, temporalUi: 8080, temporal: 7233 };
 describe('extractCollidedPort', () => {
     it('matches the "Bind for ... port is already allocated" shape', () => {
@@ -22,6 +22,24 @@ describe('extractCollidedPort', () => {
     it('returns null when no bind failure is present', () => {
         expect(extractCollidedPort('some unrelated stderr line')).toBeNull();
     });
+    // Captured verbatim from Docker 29.4.0 on macOS. The bind failure is nested
+    // three wrappers deep; matching whole message shapes missed it.
+    it('extracts the port from Docker 29\'s nested container-networking wrapper', () => {
+        const stderr = 'Error response from daemon: failed to set up container networking: ' +
+            'driver failed programming external connectivity on endpoint out-api-1 ' +
+            '(e72baf85643fb5dc19000acf62c1ad0d11bffc653cabe1fc8861387ec1ebd629): ' +
+            'Bind for 0.0.0.0:3001 failed: port is already allocated';
+        expect(extractCollidedPort(stderr)).toBe(3001);
+    });
+    it('extracts the port from the "ports are not available" wrapper', () => {
+        const stderr = 'Error: ports are not available: exposing port TCP 0.0.0.0:3001 -> 0.0.0.0:0: ' +
+            'listen tcp 0.0.0.0:3001: bind: address already in use';
+        expect(extractCollidedPort(stderr)).toBe(3001);
+    });
+    it('ignores an IP-like prefix and takes the port nearest the failure phrase', () => {
+        const stderr = 'container 172.17.0.2:5432 started\nBind for 0.0.0.0:8080 failed: port is already allocated';
+        expect(extractCollidedPort(stderr)).toBe(8080);
+    });
     it('returns null for empty input', () => {
         expect(extractCollidedPort('')).toBeNull();
     });
@@ -80,3 +98,24 @@ describe('formatPortCollisionsHint', () => {
         expect(hint).toContain('• Port 5432 — stop the process holding it');
     });
 });
+describe('formatComposeFailure', () => {
+    const reason = 'Docker compose failed to start services (exit code 1).';
+    it('prepends the actionable hint when the output names a collision', () => {
+        const message = formatComposeFailure(reason, 'Bind for 0.0.0.0:3001 failed: port is already allocated', DEFAULT_PORTS);
+        expect(message.startsWith('Port 3001 is already in use.')).toBe(true);
+        expect(message).toContain('OUTPUT_API_HOST_PORT=<other port>');
+        expect(message).toContain(reason);
+        expect(message).toContain('Recent Docker output:');
+    });
+    it('omits the output section entirely when nothing was captured', () => {
+        const message = formatComposeFailure(reason, '', DEFAULT_PORTS);
+        expect(message).toBe(reason);
+        expect(message).not.toContain('Recent Docker output:');
+    });
+    it('returns reason plus raw output, with no hint, for an unrecognized failure', () => {
+        const message = formatComposeFailure(reason, 'no such image: outputai/api:dev', DEFAULT_PORTS);
+        expect(message.startsWith(reason)).toBe(true);
+        expect(message).toContain('Recent Docker output:\nno such image');
+        expect(message).not.toContain('is already in use');
+    });
+});

package/dist/utils/resolve_input.d.ts

@@ -1 +1,9 @@
-export declare function resolveInput(workflowName: string, scenario: string | undefined, inputFlag: string | undefined, commandName: string, catalog?: string): Promise<unknown>;
+export type ResolveInputOptions = {
+    workflowName: string;
+    scenario?: string;
+    inputFlag?: string;
+    commandName: string;
+    catalog?: string;
+    json?: boolean;
+};
+export declare function resolveInput(options: ResolveInputOptions): Promise<unknown>;

package/dist/utils/resolve_input.js

@@ -1,7 +1,8 @@
 import { ux } from '@oclif/core';
 import { parseInputFlag } from '#utils/input_parser.js';
 import { resolveScenarioPath, getScenarioNotFoundMessage } from '#utils/scenario_resolver.js';
-export async function resolveInput(workflowName, scenario, inputFlag, commandName, catalog) {
+export async function resolveInput(options) {
+    const { workflowName, scenario, inputFlag, commandName, catalog, json } = options;
     if (inputFlag && scenario) {
         return ux.error('Cannot use both scenario argument and --input flag. Choose one.', { exit: 1 });
     }
@@ -13,7 +14,12 @@ export async function resolveInput(workflowName, scenario, inputFlag, commandNam
         if (!resolution.found) {
             return ux.error(getScenarioNotFoundMessage(workflowName, scenario, resolution.searchedPaths), { exit: 1 });
         }
-        ux.stdout(`Using scenario: ${resolution.path}\n`);
+        // Advisory notice goes to stderr so stdout stays clean for piping, and is
+        // skipped entirely under --json where even stderr is noise to a script
+        // consuming the structured output (same rule as the init hook's banner).
+        if (!json) {
+            ux.stderr(`Using scenario: ${resolution.path}`);
+        }
         return parseInputFlag(resolution.path);
     }
     return ux.error('Input required. Provide either:\n' +

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

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

package/dist/utils/resolve_input.spec.js

@@ -0,0 +1,75 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+vi.mock('@oclif/core', () => ({
+    ux: {
+        stdout: vi.fn(),
+        stderr: vi.fn(),
+        error: vi.fn(() => {
+            throw new Error('ux.error called');
+        })
+    }
+}));
+vi.mock('#utils/input_parser.js', () => ({
+    parseInputFlag: vi.fn()
+}));
+vi.mock('#utils/scenario_resolver.js', () => ({
+    resolveScenarioPath: vi.fn(),
+    getScenarioNotFoundMessage: vi.fn()
+}));
+describe('resolveInput', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    it('emits the scenario notice on stderr so --json stdout stays clean', async () => {
+        const { ux } = await import('@oclif/core');
+        const { parseInputFlag } = await import('#utils/input_parser.js');
+        const { resolveScenarioPath } = await import('#utils/scenario_resolver.js');
+        const { resolveInput } = await import('./resolve_input.js');
+        vi.mocked(resolveScenarioPath).mockResolvedValue({
+            found: true,
+            path: '/scenarios/happy_path.json'
+        });
+        vi.mocked(parseInputFlag).mockReturnValue({ key: 'value' });
+        const result = await resolveInput({
+            workflowName: 'web_search',
+            scenario: 'happy_path',
+            commandName: 'start'
+        });
+        expect(result).toEqual({ key: 'value' });
+        expect(ux.stderr).toHaveBeenCalledWith('Using scenario: /scenarios/happy_path.json');
+        expect(ux.stdout).not.toHaveBeenCalled();
+    });
+    it('suppresses the scenario notice entirely under --json', async () => {
+        const { ux } = await import('@oclif/core');
+        const { parseInputFlag } = await import('#utils/input_parser.js');
+        const { resolveScenarioPath } = await import('#utils/scenario_resolver.js');
+        const { resolveInput } = await import('./resolve_input.js');
+        vi.mocked(resolveScenarioPath).mockResolvedValue({
+            found: true,
+            path: '/scenarios/happy_path.json'
+        });
+        vi.mocked(parseInputFlag).mockReturnValue({ key: 'value' });
+        const result = await resolveInput({
+            workflowName: 'web_search',
+            scenario: 'happy_path',
+            commandName: 'start',
+            json: true
+        });
+        expect(result).toEqual({ key: 'value' });
+        expect(ux.stderr).not.toHaveBeenCalled();
+        expect(ux.stdout).not.toHaveBeenCalled();
+    });
+    it('does not emit the scenario notice when input comes from --input', async () => {
+        const { ux } = await import('@oclif/core');
+        const { parseInputFlag } = await import('#utils/input_parser.js');
+        const { resolveInput } = await import('./resolve_input.js');
+        vi.mocked(parseInputFlag).mockReturnValue({ key: 'value' });
+        await resolveInput({
+            workflowName: 'web_search',
+            inputFlag: '{"key":"value"}',
+            commandName: 'start'
+        });
+        expect(ux.stderr).not.toHaveBeenCalled();
+        expect(ux.stdout).not.toHaveBeenCalled();
+    });
+});

package/dist/utils/waterfall.d.ts

@@ -8,7 +8,7 @@
  * Atlas's `StepGantt`; the bar geometry mirrors its leftPct/widthPct as integer
  * terminal columns.
  */
-import type { Span } from '#services/workflow_history/correlator.js';
+import type { Span, SpanStatus } from '#services/workflow_history/correlator.js';
 export interface WaterfallOptions {
     width: number;
     color: boolean;
@@ -22,6 +22,8 @@ export interface BarGeometry {
 }
 export declare const FULL_BLOCK = "\u2588";
 export declare const THIN_BLOCK = "\u258F";
+export declare const ANSI: Record<SpanStatus | 'dim' | 'reset', string>;
+export declare function makeTint(color: boolean): (text: string, code: string) => string;
 export declare function pickTickStep(totalMs: number): number;
 export declare function buildTicks(totalMs: number): number[];
 export declare function formatTickLabel(ms: number): string;

package/dist/utils/waterfall.js

@@ -12,7 +12,7 @@ const TICK_STEPS_MS = [
     60 * 60_000, 2 * 60 * 60_000, 6 * 60 * 60_000, 12 * 60 * 60_000, 24 * 60 * 60_000
 ];
 const TARGET_TICKS = 8;
-const ANSI = {
+export const ANSI = {
     completed: '',
     running: '',
     failed: '',
@@ -20,6 +20,12 @@ const ANSI = {
     dim: '',
     reset: ''
 };
+// Shared by renderWaterfall and monitor_log's live status lines so there's one
+// place that knows how to wrap text in an ANSI code (and reset it) -- or not,
+// when color is disabled.
+export function makeTint(color) {
+    return (text, code) => (color ? `${code}${text}${ANSI.reset}` : text);
+}
 function clamp(value, lo, hi) {
     return Math.min(Math.max(value, lo), hi);
 }
@@ -162,7 +168,7 @@ export default function renderWaterfall(spans, totalDurationMs, options) {
     if (spans.length === 0) {
         return [header, 'No steps found for this run.'].filter(Boolean).join('\n\n');
     }
-    const tint = (text, code) => (color ? `${code}${text}${ANSI.reset}` : text);
+    const tint = makeTint(color);
     const labelFor = (span) => labels?.get(span.id) ?? span.name;
     const durationFor = (span) => formatDurationLabel(Math.max(0, span.durationMs));
     const longestLabel = Math.max(...spans.map(s => labelFor(s).length));

package/dist/views/dev/chrome/footer.d.ts

@@ -8,5 +8,7 @@ export interface FooterState {
     hints?: CommandHint[];
     itemCount?: number;
     itemLabel?: string;
+    /** Attached to a pre-existing stack — quitting leaves services running. */
+    attached?: boolean;
 }
 export declare const Footer: React.FC<FooterState>;

package/dist/views/dev/chrome/footer.js

@@ -5,16 +5,16 @@ import packageJson from '../../../../package.json' with { type: 'json' };
 const GLOBAL_HINT_ROWS = 1;
 const LOCAL_HINT_ROWS = 1;
 export const getHeight = () => GLOBAL_HINT_ROWS + LOCAL_HINT_ROWS;
-const GLOBAL_HINTS = [
+const globalHints = (attached) => [
     { key: 'tab', label: 'next tab' },
     { key: 'shift-tab', label: 'prev tab' },
     { key: '1-4', label: 'tabs' },
     { key: '/', label: 'search' },
     { key: '?', label: 'help' },
-    { key: 'ctrl+c', label: 'quit' }
+    { key: 'ctrl+c', label: attached ? 'detach (keeps running)' : 'quit' }
 ];
 const VERSION = packageJson.version;
 const HintRow = ({ hints }) => (_jsx(Box, { flexDirection: "row", children: hints.length === 0 ? (_jsx(Text, { children: " " })) : hints.map((hint, i) => (_jsxs(React.Fragment, { children: [i > 0 && _jsx(Text, { dimColor: true, children: '  ' }), _jsx(Text, { bold: true, children: hint.key }), _jsx(Text, { dimColor: true, children: ` ${hint.label}` })] }, hint.key))) }));
-export const Footer = ({ hints = [], itemCount, itemLabel }) => {
-    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { flexDirection: "row", justifyContent: "space-between", children: [_jsx(HintRow, { hints: GLOBAL_HINTS }), typeof itemCount === 'number' && itemLabel && (_jsx(Box, { children: _jsxs(Text, { dimColor: true, children: [itemCount, " ", itemLabel] }) }))] }), _jsxs(Box, { flexDirection: "row", justifyContent: "space-between", children: [_jsx(HintRow, { hints: hints }), _jsxs(Text, { color: "blackBright", children: ["v", VERSION] })] })] }));
+export const Footer = ({ hints = [], itemCount, itemLabel, attached = false }) => {
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { flexDirection: "row", justifyContent: "space-between", children: [_jsx(HintRow, { hints: globalHints(attached) }), typeof itemCount === 'number' && itemLabel && (_jsx(Box, { children: _jsxs(Text, { dimColor: true, children: [itemCount, " ", itemLabel] }) }))] }), _jsxs(Box, { flexDirection: "row", justifyContent: "space-between", children: [_jsx(HintRow, { hints: hints }), _jsxs(Text, { color: "blackBright", children: ["v", VERSION] })] })] }));
 };

package/dist/views/dev/dev_app.d.ts

@@ -3,4 +3,5 @@ export type Phase = 'waiting' | 'running' | 'failed';
 export declare const DevApp: React.FC<{
     dockerComposePath: string;
     onCleanup: () => Promise<void>;
+    attached?: boolean;
 }>;

package/dist/views/dev/dev_app.js

@@ -150,7 +150,7 @@ const overlayFor = (opts) => {
     }
     return null;
 };
-const Shell = ({ dockerComposePath, onCleanup }) => {
+const Shell = ({ dockerComposePath, onCleanup, attached }) => {
     const { exit } = useApp();
     const ui = useUiState();
     const [phase, setPhase] = useState('waiting');
@@ -160,7 +160,16 @@ const Shell = ({ dockerComposePath, onCleanup }) => {
         onServices: setServices,
         onAllHealthy: () => setPhase('running'),
         onFailure: () => setPhase('failed'),
-        onTimeout: () => exit(new Error('Timeout waiting for services to become healthy'))
+        // An attach/reconcile session monitors a stack it doesn't own, so a slow
+        // health check must not be fatal — drop into the dashboard and keep
+        // polling status. Only an owned fresh start treats the timeout as an error.
+        onTimeout: () => {
+            if (attached) {
+                setPhase('running');
+                return;
+            }
+            exit(new Error('Timeout waiting for services to become healthy'));
+        }
     });
     useStatusRefresh(dockerComposePath, phase !== 'waiting', setServices);
     useWorkflowRunsPolling(phase !== 'waiting', setRuns);
@@ -231,6 +240,6 @@ const Shell = ({ dockerComposePath, onCleanup }) => {
     if (overlay) {
         return (_jsx(Box, { flexDirection: "column", height: rows, paddingX: 1, children: overlay }));
     }
-    return (_jsxs(Box, { flexDirection: "column", height: rows, paddingX: 1, children: [_jsx(Header, { counters: counters }), _jsx(TabBar, { active: ui.tab, borderColor: RULE_PURPLE }), _jsx(SearchBar, { active: ui.search.open }), _jsxs(Box, { flexDirection: "column", flexGrow: 1, height: contentRows, overflow: "hidden", children: [ui.tab === 'workflows' && _jsx(WorkflowsPanel, { workflows: workflows, runs: runs }), ui.tab === 'runs' && _jsx(RunsPanel, { runs: runs, height: contentRows }), ui.tab === 'services' && (_jsx(ServicesPanel, { height: contentRows, phase: phase, services: services, dockerComposePath: dockerComposePath })), ui.tab === 'help' && _jsx(HelpPanel, {})] }), _jsx(Toasts, {}), _jsx(Footer, { hints: footer.hints, itemCount: footer.itemCount, itemLabel: footer.itemLabel })] }));
+    return (_jsxs(Box, { flexDirection: "column", height: rows, paddingX: 1, children: [_jsx(Header, { counters: counters }), _jsx(TabBar, { active: ui.tab, borderColor: RULE_PURPLE }), _jsx(SearchBar, { active: ui.search.open }), _jsxs(Box, { flexDirection: "column", flexGrow: 1, height: contentRows, overflow: "hidden", children: [ui.tab === 'workflows' && _jsx(WorkflowsPanel, { workflows: workflows, runs: runs }), ui.tab === 'runs' && _jsx(RunsPanel, { runs: runs, height: contentRows }), ui.tab === 'services' && (_jsx(ServicesPanel, { height: contentRows, phase: phase, services: services, dockerComposePath: dockerComposePath })), ui.tab === 'help' && _jsx(HelpPanel, {})] }), _jsx(Toasts, {}), _jsx(Footer, { hints: footer.hints, itemCount: footer.itemCount, itemLabel: footer.itemLabel, attached: attached })] }));
 };
-export const DevApp = ({ dockerComposePath, onCleanup }) => (_jsx(UiStateProvider, { children: _jsx(Shell, { dockerComposePath: dockerComposePath, onCleanup: onCleanup }) }));
+export const DevApp = ({ dockerComposePath, onCleanup, attached = false }) => (_jsx(UiStateProvider, { children: _jsx(Shell, { dockerComposePath: dockerComposePath, onCleanup: onCleanup, attached: attached }) }));

package/dist/views/dev/hooks/use_run_detail.js

@@ -2,13 +2,16 @@ import { useEffect, useRef, useState } from 'react';
 import { readFile } from 'node:fs/promises';
 import { getWorkflowIdResult, getWorkflowIdRunsRidResult, getWorkflowIdTraceLog, getWorkflowIdRunsRidTraceLog } from '#api/generated/api.js';
 import { normalizeWorkflowStatus } from '#utils/normalize_workflow_status.js';
+import { TERMINAL_STATUSES } from '#utils/format_workflow_result.js';
+import { createBoundedCache } from '#views/dev/utils/bounded_cache.js';
 const EMPTY_DETAIL = {
     result: null,
     trace: null,
     steps: [],
     loading: false
 };
-const runDetailCache = new Map();
+const RUN_DETAIL_CACHE_MAX = 50;
+const runDetailCache = createBoundedCache(RUN_DETAIL_CACHE_MAX);
 const stepNameOf = (node) => {
     if (node.name) {
         return node.name;
@@ -99,13 +102,9 @@ const fetchResult = async (workflowId, runId) => {
         return null;
     }
 };
-/**
- * Statuses that mean the workflow has stopped advancing. The cache is
- * intentionally only populated for these — partial results from a still-
- * running workflow would otherwise stick and stall the UI when the run
- * eventually finishes.
- */
-const TERMINAL_STATUSES = new Set(['completed', 'failed', 'canceled', 'terminated', 'timed_out']);
+// The cache is intentionally only populated for terminal statuses — partial results
+// from a still-running workflow would otherwise stick and stall the UI when the run
+// eventually finishes. `TERMINAL_STATUSES` is shared with `workflow monitor`.
 export const isTerminalRunStatus = (status) => Boolean(status && TERMINAL_STATUSES.has(status));
 export const useRunDetail = (workflowId, runId, status) => {
     const [detail, setDetail] = useState(EMPTY_DETAIL);

package/dist/views/dev/hooks/use_step_graph.js

@@ -3,6 +3,7 @@ import { fetchWorkflowHistory } from '#services/workflow_history.js';
 import buildSpanLabels from '#utils/span_labels.js';
 import { isTerminalRunStatus } from '#views/dev/hooks/use_run_detail.js';
 import { usePoll, POLL_INTERVAL_MS } from '#views/dev/hooks/use_poll.js';
+import { createBoundedCache } from '#views/dev/utils/bounded_cache.js';
 const EMPTY_GRAPH = {
     spans: [],
     totalDurationMs: 0,
@@ -11,7 +12,8 @@ const EMPTY_GRAPH = {
     loading: false,
     error: null
 };
-const stepGraphCache = new Map();
+const STEP_GRAPH_CACHE_MAX = 50;
+const stepGraphCache = createBoundedCache(STEP_GRAPH_CACHE_MAX);
 /**
  * Fetches a run's correlated step spans for the dev TUI's waterfall overlay,
  * reusing the same `fetchWorkflowHistory` path as the `workflow history` CLI

package/dist/views/dev/utils/bounded_cache.d.ts

@@ -0,0 +1,14 @@
+export interface BoundedCache<K, V extends {}> {
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    has(key: K): boolean;
+    clear(): void;
+    size(): number;
+}
+/**
+ * A small LRU cache backed by an insertion-ordered `Map`, capped at `maxSize`
+ * entries. Reading a key refreshes its recency; once the cap is exceeded the
+ * least-recently-used entries are evicted. Drop-in compatible with the
+ * `Map.get` / `Map.set` calls it replaces.
+ */
+export declare const createBoundedCache: <K, V extends {}>(maxSize: number) => BoundedCache<K, V>;

package/dist/views/dev/utils/bounded_cache.js

@@ -0,0 +1,42 @@
+/**
+ * A small LRU cache backed by an insertion-ordered `Map`, capped at `maxSize`
+ * entries. Reading a key refreshes its recency; once the cap is exceeded the
+ * least-recently-used entries are evicted. Drop-in compatible with the
+ * `Map.get` / `Map.set` calls it replaces.
+ */
+export const createBoundedCache = (maxSize) => {
+    if (maxSize < 1) {
+        throw new Error('createBoundedCache: maxSize must be >= 1');
+    }
+    const entries = new Map();
+    return {
+        get(key) {
+            const value = entries.get(key);
+            if (value === undefined) {
+                return value;
+            }
+            entries.delete(key);
+            entries.set(key, value);
+            return value;
+        },
+        set(key, value) {
+            entries.delete(key);
+            entries.set(key, value);
+            if (entries.size > maxSize) {
+                const oldest = entries.keys().next();
+                if (!oldest.done) {
+                    entries.delete(oldest.value);
+                }
+            }
+        },
+        has(key) {
+            return entries.has(key);
+        },
+        clear() {
+            entries.clear();
+        },
+        size() {
+            return entries.size;
+        }
+    };
+};

package/dist/views/dev/utils/bounded_cache.spec.d.ts

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

package/dist/views/dev/utils/bounded_cache.spec.js

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest';
+import { createBoundedCache } from './bounded_cache.js';
+describe('createBoundedCache', () => {
+    it('round-trips set and get', () => {
+        const cache = createBoundedCache(3);
+        cache.set('a', 1);
+        expect(cache.get('a')).toBe(1);
+        expect(cache.get('missing')).toBeUndefined();
+    });
+    it('evicts the oldest entry once maxSize is exceeded', () => {
+        const cache = createBoundedCache(2);
+        cache.set('a', 1);
+        cache.set('b', 2);
+        cache.set('c', 3);
+        expect(cache.has('a')).toBe(false);
+        expect(cache.get('b')).toBe(2);
+        expect(cache.get('c')).toBe(3);
+    });
+    it('refreshes recency on get so the touched entry survives eviction', () => {
+        const cache = createBoundedCache(2);
+        cache.set('a', 1);
+        cache.set('b', 2);
+        // Touch 'a' so 'b' becomes the least-recently-used entry.
+        expect(cache.get('a')).toBe(1);
+        cache.set('c', 3);
+        expect(cache.has('a')).toBe(true);
+        expect(cache.has('b')).toBe(false);
+        expect(cache.has('c')).toBe(true);
+    });
+    it('updates an existing key in place without growing', () => {
+        const cache = createBoundedCache(2);
+        cache.set('a', 1);
+        cache.set('a', 2);
+        expect(cache.get('a')).toBe(2);
+        expect(cache.size()).toBe(1);
+    });
+    it('supports has and clear', () => {
+        const cache = createBoundedCache(2);
+        cache.set('a', 1);
+        expect(cache.has('a')).toBe(true);
+        cache.clear();
+        expect(cache.has('a')).toBe(false);
+        expect(cache.size()).toBe(0);
+    });
+    it('never exceeds maxSize', () => {
+        const cache = createBoundedCache(3);
+        Array.from({ length: 100 }, (_, i) => i).forEach(i => {
+            cache.set(`key-${i}`, i);
+            expect(cache.size()).toBeLessThanOrEqual(3);
+        });
+        expect(cache.size()).toBe(3);
+    });
+});