@xdelivered/emberflow 0.2.0

package/dist/server/operationResult.js

@@ -0,0 +1,26 @@
+import { runOutput } from '../src/engine/index.js';
+/** Map a finished operation run to an HTTP response. A flow can have more than
+ *  one `Response` node (e.g. a success branch and an error branch) — only one
+ *  of them actually ran. Among the `Response`-type nodes, pick the one whose
+ *  run state actually succeeded (first such node by array order if somehow
+ *  more than one did); its output (already `{ status, body }`) wins.
+ *  Otherwise — no Response node, or none of them succeeded — fall back to
+ *  200 + the run's Result output. */
+export function extractResponse(run, flow) {
+    const responseNodes = flow.nodes.filter((n) => n.type === 'Response');
+    const succeeded = responseNodes.find((n) => run.nodeStates[n.id]?.status === 'succeeded');
+    const out = succeeded ? run.nodeStates[succeeded.id]?.output : undefined;
+    if (out && typeof out === 'object') {
+        const o = out;
+        return { status: typeof o.status === 'number' ? o.status : 200, body: o.body };
+    }
+    // No Response node succeeded. If the run itself failed, a 200 fallback would
+    // silently mask the failure (runOutput returns undefined → 200 + null). Surface
+    // it as a 500, preferring the first failed node's error string (a stable shape,
+    // no stack traces) so the caller sees why.
+    if (run.status === 'failed') {
+        const nodeError = Object.values(run.nodeStates).find((s) => s?.status === 'failed')?.error;
+        return { status: 500, body: nodeError ? { error: 'run failed', detail: nodeError } : { error: 'run failed' } };
+    }
+    return { status: 200, body: runOutput(run, flow) };
+}

package/dist/server/pathGuard.d.ts

@@ -0,0 +1 @@
+export declare function isMountablePath(path: string | undefined | null): path is string;

package/dist/server/pathGuard.js

@@ -0,0 +1,16 @@
+// A mountable operation `http.path` must be a real sub-path — never bare
+// root ('/' or '') and never missing. Operation routes are registered
+// before the studio SPA catch-all, so an op mounted at '/' would shadow the
+// studio entirely (GET / would return the op's output, not the studio
+// HTML). Roughly `^/[^/].*`.
+export function isMountablePath(path) {
+    if (!path)
+        return false;
+    if (path.length < 2)
+        return false; // '/' or ''
+    if (path[0] !== '/')
+        return false;
+    if (path[1] === '/')
+        return false; // '//x'
+    return true;
+}

package/dist/server/pathSafety.d.ts

@@ -0,0 +1,20 @@
+/**
+ * True when `relPath` is a safe POSIX-style relative path that, once joined
+ * onto `baseDir`, resolves to somewhere *inside* `baseDir`.
+ *
+ * Rejects:
+ *  - empty strings
+ *  - a leading `/` (absolute)
+ *  - a backslash anywhere (the Windows separator — letting it through would
+ *    let a segment like `a\..\b` smuggle a traversal past the POSIX-only
+ *    `'/'.split` checks below, and still resolve outside `baseDir` via
+ *    `path.join`'s platform-specific behavior)
+ *  - any `.`/`..`/empty segment (so `a//b`, `./x`, `../x` are all rejected)
+ *  - anything that, after resolution, doesn't stay under `baseDir` (defense
+ *    in depth beyond the segment checks above)
+ *
+ * Shared by `isSafeApiPath` (server/index.ts, POST /operations and future
+ * path-taking endpoints) and `isSafeFlowId` (server/agents/runManager.ts) —
+ * one robust implementation instead of two ad hoc string checks.
+ */
+export declare function isPathWithin(baseDir: string, relPath: string): boolean;

package/dist/server/pathSafety.js

@@ -0,0 +1,35 @@
+import { isAbsolute, relative, resolve } from 'node:path';
+/**
+ * True when `relPath` is a safe POSIX-style relative path that, once joined
+ * onto `baseDir`, resolves to somewhere *inside* `baseDir`.
+ *
+ * Rejects:
+ *  - empty strings
+ *  - a leading `/` (absolute)
+ *  - a backslash anywhere (the Windows separator — letting it through would
+ *    let a segment like `a\..\b` smuggle a traversal past the POSIX-only
+ *    `'/'.split` checks below, and still resolve outside `baseDir` via
+ *    `path.join`'s platform-specific behavior)
+ *  - any `.`/`..`/empty segment (so `a//b`, `./x`, `../x` are all rejected)
+ *  - anything that, after resolution, doesn't stay under `baseDir` (defense
+ *    in depth beyond the segment checks above)
+ *
+ * Shared by `isSafeApiPath` (server/index.ts, POST /operations and future
+ * path-taking endpoints) and `isSafeFlowId` (server/agents/runManager.ts) —
+ * one robust implementation instead of two ad hoc string checks.
+ */
+export function isPathWithin(baseDir, relPath) {
+    if (typeof relPath !== 'string' || relPath.length === 0)
+        return false;
+    if (relPath.includes('\\'))
+        return false;
+    if (relPath.startsWith('/'))
+        return false;
+    const segments = relPath.split('/');
+    if (segments.some((seg) => seg === '' || seg === '.' || seg === '..'))
+        return false;
+    const resolvedBase = resolve(baseDir);
+    const resolved = resolve(baseDir, relPath);
+    const rel = relative(resolvedBase, resolved);
+    return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+}

package/dist/server/projectConfig.d.ts

@@ -0,0 +1,47 @@
+import type { NodeRegistry } from '../src/engine/index.js';
+import type { VerifierRegistry } from './auth/verifiers.js';
+export interface EmberflowUserConfig {
+    /** Directory holding <flowId>.json flow files (+ <flowId>.scenarios.json sidecars). Relative to the config file. */
+    flowsDir?: string;
+    /** Register the project's own node types. */
+    registerNodes?: (registry: NodeRegistry) => void;
+    /** Register custom auth verifiers (e.g. real JWT) alongside the default bearer/apiKey ones. */
+    registerVerifiers?: (registry: VerifierRegistry) => void;
+    /** Op id to run when any run finishes with status 'failed' (best-effort; never blocks the failed run). */
+    errorOperation?: string;
+    /** Authoritative signal for agents/tooling about which language this project's
+     *  APIs/nodes are authored in. When absent, it's inferred from the config file's
+     *  own extension (`emberflow.config.ts` → 'typescript', else 'javascript'). */
+    language?: 'javascript' | 'typescript';
+}
+/** Identity helper so consumer configs get typing: `export default defineConfig({...})`. */
+export declare function defineConfig(config: EmberflowUserConfig): EmberflowUserConfig;
+export interface ProjectConfig {
+    root: string;
+    flowsDir: string;
+    language: 'javascript' | 'typescript';
+    /** Present only when the config's `language` field was EXPLICIT and
+     *  disagrees with the config file's own extension (e.g. `language:
+     *  'javascript'` in an `emberflow.config.ts`). Inference makes language and
+     *  extension agree by construction, so this is the only detectable drift —
+     *  see src/engine/diagnostics.ts's `language-drift` check, which callers
+     *  (server/index.ts's diagnostics route, `doctor`) feed this into. */
+    languageDrift?: {
+        projectLanguage: 'javascript' | 'typescript';
+        configPathExtension: string;
+    };
+    registerNodes?: (registry: NodeRegistry) => void;
+    registerVerifiers?: (registry: VerifierRegistry) => void;
+    errorOperation?: string;
+}
+/** The resolved emberflow.config.* path for a project dir, or undefined. */
+export declare function configPathFor(dir: string): string | undefined;
+/**
+ * Loads a project's config. `fresh: true` cache-busts the dynamic import so an
+ * edited config re-imports (the module loader caches by URL) — used by the
+ * in-process node hot-reload so editing registerNodes takes effect without a
+ * process restart (which would kill in-flight agent runs).
+ */
+export declare function loadProjectConfig(dir: string, opts?: {
+    fresh?: boolean;
+}): Promise<ProjectConfig | null>;

package/dist/server/projectConfig.js

@@ -0,0 +1,61 @@
+import { existsSync } from 'node:fs';
+import { extname, isAbsolute, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+/**
+ * Project mode: a consumer repo drops an emberflow.config file at its root
+ * and Emberflow serves THEIR flows and nodes. This loader finds and imports
+ * that config. The runner runs under tsx, so dynamic import handles .ts
+ * configs as well as .js/.mjs.
+ */
+const CONFIG_BASENAMES = ['emberflow.config.mjs', 'emberflow.config.js', 'emberflow.config.ts'];
+/** Identity helper so consumer configs get typing: `export default defineConfig({...})`. */
+export function defineConfig(config) {
+    return config;
+}
+/** The resolved emberflow.config.* path for a project dir, or undefined. */
+export function configPathFor(dir) {
+    const root = resolve(dir);
+    return CONFIG_BASENAMES.map((b) => join(root, b)).find(existsSync);
+}
+/**
+ * Loads a project's config. `fresh: true` cache-busts the dynamic import so an
+ * edited config re-imports (the module loader caches by URL) — used by the
+ * in-process node hot-reload so editing registerNodes takes effect without a
+ * process restart (which would kill in-flight agent runs).
+ */
+export async function loadProjectConfig(dir, opts = {}) {
+    const root = resolve(dir);
+    const file = CONFIG_BASENAMES.map((b) => join(root, b)).find(existsSync);
+    if (!file)
+        return null;
+    let raw;
+    try {
+        const url = pathToFileURL(file).href + (opts.fresh ? `?t=${Date.now()}` : '');
+        const mod = (await import(url));
+        raw = mod.default ?? {};
+    }
+    catch (err) {
+        throw new Error(`Failed to load ${file}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const flowsDir = raw.flowsDir
+        ? isAbsolute(raw.flowsDir) ? raw.flowsDir : join(root, raw.flowsDir)
+        : join(root, 'emberflow', 'flows');
+    // Explicit `language` wins; otherwise infer from the config file's own
+    // extension — a .ts config implies a TypeScript project, everything else JS.
+    const inferredLanguage = file.endsWith('.ts') ? 'typescript' : 'javascript';
+    const language = raw.language ?? inferredLanguage;
+    // Drift is only detectable when the field is EXPLICIT: inferred language
+    // agrees with the extension by construction, so there's nothing to flag.
+    const languageDrift = raw.language && raw.language !== inferredLanguage
+        ? { projectLanguage: raw.language, configPathExtension: extname(file) }
+        : undefined;
+    return {
+        root,
+        flowsDir,
+        language,
+        ...(languageDrift ? { languageDrift } : {}),
+        ...(raw.registerNodes ? { registerNodes: raw.registerNodes } : {}),
+        ...(raw.registerVerifiers ? { registerVerifiers: raw.registerVerifiers } : {}),
+        ...(raw.errorOperation ? { errorOperation: raw.errorOperation } : {}),
+    };
+}

package/dist/server/projectMode.d.ts

@@ -0,0 +1,26 @@
+import { FlowStore } from './flowStore.js';
+import { ApiStore } from './apiStore.js';
+import type { NodeRegistry } from '../src/engine/index.js';
+import type { ProjectConfig } from './projectConfig.js';
+/**
+ * Project-mode wiring, kept Express-free so tests exercise exactly what the
+ * runner boots with. Two registries because validation and execution are
+ * separate instances in the runner — the consumer's nodes must exist in both.
+ */
+/**
+ * Boot-time guard: an explicit EMBERFLOW_PROJECT env var must fail loudly
+ * when no config was found there, mirroring the environments-file stance.
+ * Implicit cwd detection stays lenient (silent fallback to default mode).
+ */
+export declare function requireProjectWhenExplicit(project: ProjectConfig | null, explicitPath: string | undefined, resolvedDir: string): ProjectConfig | null;
+export declare function buildFlowStore(project: ProjectConfig | null): FlowStore;
+/**
+ * The `apis/` tree replaces the flat `flows/` layout. Runs the one-time
+ * migration before constructing the store so a legacy project boots straight
+ * into the new layout.
+ */
+export declare function buildApiStore(project: ProjectConfig | null): ApiStore;
+export declare function buildRegistries(project: ProjectConfig | null): {
+    validation: NodeRegistry;
+    execution: NodeRegistry;
+};

package/dist/server/projectMode.js

@@ -0,0 +1,44 @@
+import { dirname, join, resolve } from 'node:path';
+import { FlowStore } from './flowStore.js';
+import { ApiStore } from './apiStore.js';
+import { migrateFlowsToApis } from './migrateFlows.js';
+import { createDefaultRegistry } from '../src/nodes/index.js';
+/**
+ * Project-mode wiring, kept Express-free so tests exercise exactly what the
+ * runner boots with. Two registries because validation and execution are
+ * separate instances in the runner — the consumer's nodes must exist in both.
+ */
+/**
+ * Boot-time guard: an explicit EMBERFLOW_PROJECT env var must fail loudly
+ * when no config was found there, mirroring the environments-file stance.
+ * Implicit cwd detection stays lenient (silent fallback to default mode).
+ */
+export function requireProjectWhenExplicit(project, explicitPath, resolvedDir) {
+    if (explicitPath !== undefined && project === null) {
+        throw new Error(`EMBERFLOW_PROJECT points at ${resolvedDir} but no emberflow.config.(mjs|js|ts) was found there`);
+    }
+    return project;
+}
+export function buildFlowStore(project) {
+    return project ? new FlowStore(project.flowsDir, { scenarioSidecars: true }) : new FlowStore();
+}
+/**
+ * The `apis/` tree replaces the flat `flows/` layout. Runs the one-time
+ * migration before constructing the store so a legacy project boots straight
+ * into the new layout.
+ */
+export function buildApiStore(project) {
+    const flowsDir = project ? project.flowsDir : resolve(process.cwd(), 'workflows', 'flows');
+    const apisDir = join(dirname(flowsDir), 'apis');
+    migrateFlowsToApis(flowsDir, apisDir);
+    return new ApiStore(apisDir);
+}
+export function buildRegistries(project) {
+    const validation = createDefaultRegistry();
+    const execution = createDefaultRegistry();
+    if (project?.registerNodes) {
+        project.registerNodes(validation);
+        project.registerNodes(execution);
+    }
+    return { validation, execution };
+}

package/dist/server/redact.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Pure value-based secret redaction. Deep-clones a JSON-safe payload,
+ * replacing every occurrence of each secret VALUE (raw and its
+ * encodeURIComponent form) inside any string leaf with «secret:KEY».
+ */
+export declare function redactSecrets<T>(payload: T, secrets: Record<string, string>): T;

package/dist/server/redact.js

@@ -0,0 +1,37 @@
+/**
+ * Pure value-based secret redaction. Deep-clones a JSON-safe payload,
+ * replacing every occurrence of each secret VALUE (raw and its
+ * encodeURIComponent form) inside any string leaf with «secret:KEY».
+ */
+export function redactSecrets(payload, secrets) {
+    const replacements = [];
+    for (const [key, value] of Object.entries(secrets)) {
+        if (value.length < 6)
+            continue;
+        const token = `«secret:${key}»`;
+        const encoded = encodeURIComponent(value);
+        const base64 = Buffer.from(value).toString('base64');
+        replacements.push([value, token]);
+        if (encoded !== value)
+            replacements.push([encoded, token]);
+        if (base64 !== value && base64 !== encoded)
+            replacements.push([base64, token]);
+    }
+    // Longest value first, so an encoded superstring is replaced before the raw substring it contains.
+    replacements.sort((a, b) => b[0].length - a[0].length);
+    const redactString = (input) => replacements.reduce((acc, [value, token]) => acc.split(value).join(token), input);
+    const walk = (node) => {
+        if (typeof node === 'string')
+            return redactString(node);
+        if (Array.isArray(node))
+            return node.map(walk);
+        if (node !== null && typeof node === 'object') {
+            const out = {};
+            for (const [k, v] of Object.entries(node))
+                out[k] = walk(v);
+            return out;
+        }
+        return node;
+    };
+    return walk(payload);
+}

package/dist/server/runRegistry.d.ts

@@ -0,0 +1,84 @@
+import type { LogLine, NodeExecutionSample, NodeRunState, WorkflowDefinition, WorkflowRun } from '../src/engine/index.js';
+import { InMemoryTraceSink, type FlowRun, type NodeRegistry } from '../src/engine/index.js';
+/** SSE-shaped events, mirroring ExecutorEvents 1:1. */
+export type RunEvent = {
+    type: 'nodeState';
+    nodeId: string;
+    state: NodeRunState;
+} | {
+    type: 'log';
+    line: LogLine;
+} | {
+    type: 'finished';
+    run: WorkflowRun;
+    /** Present only when this run is an error-handler invocation: the
+     *  workflowId of the run whose failure fired it. */
+    errorHandler?: {
+        firedBy: string;
+    };
+};
+type Listener = (event: RunEvent) => void;
+/** Manages live runs: buffers engine events per run and fans them out to SSE subscribers. */
+export declare class RunRegistry {
+    private readonly loadFlow?;
+    private readonly errorOperation?;
+    private readonly registry;
+    private readonly runs;
+    readonly sink: InMemoryTraceSink;
+    /**
+     * @param loadFlow Resolves a workflow by id for Subflow nodes (server hosts
+     *   this via flowStore.load). Absent → Subflow nodes fail with a clear message.
+     * @param registry Execution registry to run against. Defaults to the
+     *   built-in node set; project mode passes one preloaded with consumer nodes.
+     * @param errorOperation Op id (resolved via `loadFlow`, same as Subflow
+     *   nodes) to run whenever a run finishes with status 'failed'. Best-effort:
+     *   never throws, never affects the failed run. Absent → disabled.
+     */
+    constructor(loadFlow?: ((id: string) => WorkflowDefinition | undefined) | undefined, registry?: NodeRegistry, errorOperation?: string | undefined);
+    /** Number of registered node types (for boot logging). */
+    get nodeCount(): number;
+    /** The registry runs execute against — used to verify artifact node hashes. */
+    get executionRegistry(): NodeRegistry;
+    /** Samples recorded for a node across all runs on this registry (newest first, capped). */
+    samplesFor(nodeId: string): NodeExecutionSample[];
+    /** Create a run; wires engine events into a per-run buffer + attached subscribers. */
+    create(flow: WorkflowDefinition, opts: {
+        secrets: Record<string, string>;
+        vars: Record<string, string>;
+        environment: string;
+        safeMode: boolean;
+        pins?: Record<string, unknown>;
+        input?: Record<string, unknown>;
+        /** When true, runs in Mock mode: mocked nodes return their canned
+         *  output, unmocked infra nodes fail loud. See `StartRunOptions.mockRun`. */
+        mockRun?: boolean;
+        /** nodeId -> canned output, consulted only when `mockRun` is true. */
+        mocks?: Record<string, unknown>;
+        /** Internal: marks this run as an error-workflow invocation so it never
+         *  itself triggers `errorOperation` (recursion guard — a flag, not an id
+         *  comparison, since an error op can legitimately fail on its own). */
+        isErrorHandler?: boolean;
+        /** Internal: the workflowId of the run that failed and fired this
+         *  error-handler run — stamped onto this run's `finished` event as
+         *  `errorHandler: { firedBy }`. Only meaningful alongside isErrorHandler. */
+        errorHandlerFiredBy?: string;
+    }): {
+        runId: string;
+        handle: FlowRun;
+    };
+    /**
+     * Best-effort: fires `errorOperation` (resolved via the same `loadFlow`
+     * callback Subflow nodes use) as a new run when `failedRun` finished with
+     * status 'failed'. Never throws and never affects the failed run — any
+     * problem (unset config, unknown op id, the error op itself failing to
+     * start) is logged and swallowed.
+     */
+    private fireErrorWorkflow;
+    get(runId: string): FlowRun | undefined;
+    /** Replay the buffer to the listener, then stream live events. Returns an unsubscribe fn. */
+    subscribe(runId: string, listener: Listener): (() => void) | undefined;
+    private scheduleCleanup;
+    /** Cap live entries: drop the oldest finished run, or the oldest run outright. */
+    private evictIfNeeded;
+}
+export {};

package/dist/server/runRegistry.js

@@ -0,0 +1,200 @@
+import { InMemoryTraceSink, startRun } from '../src/engine/index.js';
+import { createDefaultRegistry } from '../src/nodes/index.js';
+import { redactSecrets } from './redact.js';
+import { makeSubflowRunner } from './subflowRunner.js';
+const RETAIN_FINISHED_MS = 10 * 60 * 1000; // 10 minutes
+const MAX_LIVE_RUNS = 100;
+/** Manages live runs: buffers engine events per run and fans them out to SSE subscribers. */
+export class RunRegistry {
+    loadFlow;
+    errorOperation;
+    registry;
+    runs = new Map();
+    sink = new InMemoryTraceSink();
+    /**
+     * @param loadFlow Resolves a workflow by id for Subflow nodes (server hosts
+     *   this via flowStore.load). Absent → Subflow nodes fail with a clear message.
+     * @param registry Execution registry to run against. Defaults to the
+     *   built-in node set; project mode passes one preloaded with consumer nodes.
+     * @param errorOperation Op id (resolved via `loadFlow`, same as Subflow
+     *   nodes) to run whenever a run finishes with status 'failed'. Best-effort:
+     *   never throws, never affects the failed run. Absent → disabled.
+     */
+    constructor(loadFlow, registry = createDefaultRegistry(), errorOperation) {
+        this.loadFlow = loadFlow;
+        this.errorOperation = errorOperation;
+        this.registry = registry;
+    }
+    /** Number of registered node types (for boot logging). */
+    get nodeCount() {
+        return this.registry.list().length;
+    }
+    /** The registry runs execute against — used to verify artifact node hashes. */
+    get executionRegistry() {
+        return this.registry;
+    }
+    /** Samples recorded for a node across all runs on this registry (newest first, capped). */
+    samplesFor(nodeId) {
+        return this.sink.samplesFor(nodeId).slice(0, 100);
+    }
+    /** Create a run; wires engine events into a per-run buffer + attached subscribers. */
+    create(flow, opts) {
+        this.evictIfNeeded();
+        // Placeholder entry so the ExecutorEvents closures can reach the live run.
+        const entry = { handle: undefined, buffer: [], listeners: new Set(), finished: false };
+        // Redact secret values from every event before it reaches the buffer
+        // (replayed to SSE subscribers) or any listener — internal run state
+        // (`entry.handle`, `handle.run.nodeStates`) is never routed through
+        // `emit` and stays raw.
+        const scrub = (e) => redactSecrets(e, opts.secrets ?? {});
+        const emit = (event) => {
+            const scrubbed = scrub(event);
+            entry.buffer.push(scrubbed);
+            for (const listener of entry.listeners)
+                listener(scrubbed);
+        };
+        // Subflow runner (shared factory — see server/subflowRunner.ts): resolves
+        // the child via loadFlow, runs it to completion on the same registry
+        // sharing the parent's environment, and forwards its (prefixed) logs into
+        // this run's SSE stream via `onLog`.
+        const subflowRunner = makeSubflowRunner({
+            loadFlow: (id) => this.loadFlow?.(id),
+            registry: this.registry,
+            secrets: opts.secrets,
+            vars: opts.vars,
+            environment: opts.environment,
+            safeMode: opts.safeMode,
+            mockRun: opts.mockRun,
+            trace: this.sink,
+            onLog: (line) => emit({ type: 'log', line }),
+        }, [flow.id]);
+        const handle = startRun({
+            flow,
+            registry: this.registry,
+            secrets: opts.secrets,
+            vars: opts.vars,
+            environment: opts.environment,
+            safeMode: opts.safeMode,
+            pins: opts.pins,
+            input: opts.input,
+            mockRun: opts.mockRun,
+            mocks: opts.mocks,
+            trace: this.sink,
+            subflowRunner,
+            events: {
+                onNodeStateChange: (nodeId, state) => emit({ type: 'nodeState', nodeId, state }),
+                onLog: (line) => emit({ type: 'log', line }),
+                onRunFinished: (run) => {
+                    emit({
+                        type: 'finished',
+                        run,
+                        ...(opts.isErrorHandler && opts.errorHandlerFiredBy
+                            ? { errorHandler: { firedBy: opts.errorHandlerFiredBy } }
+                            : {}),
+                    });
+                    entry.finished = true;
+                    this.scheduleCleanup(run.id);
+                    if (run.status === 'failed' && !opts.isErrorHandler)
+                        this.fireErrorWorkflow(run, flow, opts);
+                },
+            },
+        });
+        entry.handle = handle;
+        this.runs.set(handle.run.id, entry);
+        return { runId: handle.run.id, handle };
+    }
+    /**
+     * Best-effort: fires `errorOperation` (resolved via the same `loadFlow`
+     * callback Subflow nodes use) as a new run when `failedRun` finished with
+     * status 'failed'. Never throws and never affects the failed run — any
+     * problem (unset config, unknown op id, the error op itself failing to
+     * start) is logged and swallowed.
+     */
+    fireErrorWorkflow(failedRun, failedFlow, opts) {
+        if (!this.errorOperation)
+            return;
+        try {
+            const errorFlow = this.loadFlow?.(this.errorOperation);
+            if (!errorFlow) {
+                console.error(`[error-workflow] unknown errorOperation "${this.errorOperation}"`);
+                return;
+            }
+            // Report the failure that HALTED the run: an `optional` (fail-soft) node
+            // can fail earlier without aborting, so prefer the first failed state
+            // whose node is not optional. Fall back to the first failed state only
+            // when every failed node is optional.
+            const failedEntries = Object.entries(failedRun.nodeStates).filter(([, s]) => s.status === 'failed');
+            const failedEntry = failedEntries.find(([id]) => !failedFlow.nodes.find((n) => n.id === id)?.optional)
+                ?? failedEntries[0];
+            const failedNodeId = failedEntry?.[0];
+            const error = failedEntry?.[1] && 'error' in failedEntry[1] ? failedEntry[1].error : undefined;
+            const { handle } = this.create(errorFlow, {
+                secrets: opts.secrets,
+                vars: opts.vars,
+                environment: opts.environment,
+                safeMode: opts.safeMode,
+                // Mock mode propagates with the ERROR op's own op-level mocks
+                // (nodeIds are flow-scoped — the failed run's map doesn't apply).
+                mockRun: opts.mockRun,
+                mocks: errorFlow.mocks ?? {},
+                input: {
+                    failedRunId: failedRun.id,
+                    failedWorkflowId: failedRun.workflowId,
+                    failedNodeId,
+                    error,
+                    environment: opts.environment,
+                },
+                isErrorHandler: true,
+                errorHandlerFiredBy: failedRun.workflowId,
+            });
+            handle.runToEnd().catch((err) => {
+                console.error('[error-workflow] error op run failed', err instanceof Error ? err.message : String(err));
+            });
+        }
+        catch (err) {
+            console.error('[error-workflow] failed to fire error operation', err instanceof Error ? err.message : String(err));
+        }
+    }
+    get(runId) {
+        return this.runs.get(runId)?.handle;
+    }
+    /** Replay the buffer to the listener, then stream live events. Returns an unsubscribe fn. */
+    subscribe(runId, listener) {
+        const entry = this.runs.get(runId);
+        if (!entry)
+            return undefined;
+        for (const event of entry.buffer)
+            listener(event);
+        // A run that already finished has its full buffer replayed above; no live events follow.
+        entry.listeners.add(listener);
+        return () => entry.listeners.delete(listener);
+    }
+    scheduleCleanup(runId) {
+        const entry = this.runs.get(runId);
+        if (!entry)
+            return;
+        if (entry.cleanupTimer)
+            clearTimeout(entry.cleanupTimer);
+        entry.cleanupTimer = setTimeout(() => this.runs.delete(runId), RETAIN_FINISHED_MS);
+    }
+    /** Cap live entries: drop the oldest finished run, or the oldest run outright. */
+    evictIfNeeded() {
+        if (this.runs.size < MAX_LIVE_RUNS)
+            return;
+        let victim;
+        for (const [id, entry] of this.runs) {
+            if (entry.finished) {
+                victim = id;
+                break;
+            }
+        }
+        if (!victim)
+            victim = this.runs.keys().next().value;
+        if (victim) {
+            const entry = this.runs.get(victim);
+            if (entry?.cleanupTimer)
+                clearTimeout(entry.cleanupTimer);
+            this.runs.delete(victim);
+        }
+    }
+}

package/dist/server/runtime/RuntimeAdapter.d.ts

@@ -0,0 +1,22 @@
+import type { RequestHandler, Router } from 'express';
+/** A single routed operation's method + path. */
+export interface RegisteredOp {
+    method: string;
+    path: string;
+}
+/**
+ * The seam between the runner and whatever HTTP runtime serves it. Express is
+ * the only implementation today; Deno/Bun adapters can implement this same
+ * interface later without touching the runner.
+ */
+export interface RuntimeAdapter {
+    /** Register a routed operation's handler at `{method, path}`. Throws on a
+     *  duplicate method+path registration. */
+    registerOperation(op: RegisteredOp, handler: RequestHandler): void;
+    /** Mount a sub-router at a base path (used for `/api` + the studio). */
+    mountRouter(basePath: string, router: Router): void;
+    /** Start listening; resolves once the server is up. */
+    listen(port: number, host: string): Promise<void>;
+    /** Stop the server; resolves once fully closed. */
+    close(): Promise<void>;
+}

package/dist/server/runtime/RuntimeAdapter.js

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

package/dist/server/runtime/expressAdapter.d.ts

@@ -0,0 +1,19 @@
+import { type Express, type RequestHandler, type Router } from 'express';
+import type { AddressInfo } from 'node:net';
+import type { RegisteredOp, RuntimeAdapter } from './RuntimeAdapter.js';
+/** Express implementation of the `RuntimeAdapter` seam. Keep it thin — this is
+ *  the seam other runtimes (Deno/Bun) implement later. */
+export declare class ExpressAdapter implements RuntimeAdapter {
+    private readonly _app;
+    private server?;
+    private readonly seen;
+    constructor(app?: Express);
+    get app(): Express;
+    /** The bound address once `listen()` resolves (useful in tests to find an
+     *  ephemeral port). `null` before listening / after close. */
+    get address(): AddressInfo | null;
+    registerOperation(op: RegisteredOp, handler: RequestHandler): void;
+    mountRouter(basePath: string, router: Router): void;
+    listen(port: number, host: string): Promise<void>;
+    close(): Promise<void>;
+}