@xdelivered/emberflow 0.2.0 → 0.4.0

package/dist/server/index.js

@@ -1,4 +1,5 @@
 import { existsSync, watch } from 'node:fs';
+import { randomUUID } from 'node:crypto';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -17,8 +18,9 @@ import { buildApiStore, buildRegistries, requireProjectWhenExplicit } from './pr
 import { nodesPayload } from './nodesPayload.js';
 import { openBrowser } from './openBrowser.js';
 import { AgentRunManager, AgentStartError } from './agents/runManager.js';
+import { isGitRepo } from './agents/gitScope.js';
 import { isMountablePath } from './pathGuard.js';
-import { detectAgents } from './agents/detect.js';
+import { detectAgentsCached } from './agents/detect.js';
 import { ExpressAdapter } from './runtime/expressAdapter.js';
 import { makeOperationHandler } from './httpOperations.js';
 import { mockResponseFor } from './mockHandler.js';
@@ -27,6 +29,7 @@ import { isPathWithin } from './pathSafety.js';
 import { attachCredential } from './authAttach.js';
 import { redactSecrets } from './redact.js';
 import { runScenarioSuiteFor, ScenarioTestUsageError } from './testRunner.js';
+import { checkForUpdate, isLinkedInstall, ownVersion, runNpmInstall } from './updateCheck.js';
 import { diagnoseOperation } from '../src/engine/diagnostics.js';
 import { seedParamDefaults } from './normalizeFlow.js';
 const PORT = Number(process.env.EMBERFLOW_RUNNER_PORT ?? 8092);
@@ -127,7 +130,29 @@ if (!project) {
 const agentRuns = new AgentRunManager(project ? project.root : projectDir, apiStore.dir, apiStore.pathOf.bind(apiStore), () => nodesPayload(validationRegistry).nodes.map(({ type, label, description }) => ({ type, label, description })), project?.language ?? 'typescript', 
 // Fresh per run: re-read emberflow/infrastructure.json so a scout that ran
 // earlier this session primes later prompts. Malformed → null (agent guesses).
-() => loadInfrastructure(project ? project.root : projectDir));
+() => loadInfrastructure(project ? project.root : projectDir), 
+// Runner-verified setup snapshot for guided-setup prompts: the same facts
+// /setup-status reports, computed fresh at run start, so the agent starts
+// from KNOWN state instead of probing for it.
+() => {
+    const root = project ? project.root : process.cwd();
+    let envs = environmentsFile;
+    try {
+        envs = loadEnvironments(root);
+    }
+    catch {
+        /* keep last good */
+    }
+    const ops = apiStore.list();
+    return {
+        gitRepo: isGitRepo(root),
+        skillsInstalled: skillInstalled(root, 'claude') || skillInstalled(root, 'codex'),
+        environmentsConfigured: envs.configured,
+        infrastructurePresent: readInfrastructure() !== null,
+        opCount: ops.length,
+        onlyHello: ops.length === 1 && ops[0]?.id === 'default/hello',
+    };
+});
 // Hot-reload agent-authored nodes: watch the project's config and rebuild the
 // node registries IN-PROCESS (no process restart), so registering a node in
 // `registerNodes` takes effect live. Critically, this survives an in-flight
@@ -660,6 +685,8 @@ api.post('/runs', async (req, res) => {
             input: effectiveInput,
             mockRun,
             mocks: effectiveMocks,
+            // Step-mode runs get drill-in subflow stepping (see RunRegistry.step).
+            stepped: mode === 'step',
         }));
     }
     catch (err) {
@@ -673,22 +700,98 @@ api.post('/runs', async (req, res) => {
     }
     res.status(201).json({ runId });
 });
+// Run a single node in isolation (studio's "Run node" affordance). Executes the
+// node's implementation in-process against the resolved environment's
+// secrets/vars, honouring safe mode via resolveRunSafety, and redacts the
+// output through the same choke point runs use. Unknown type → 404. The studio
+// bundles no implementations, so this is the ONLY path to a lone node run.
+api.post('/node-run', async (req, res) => {
+    const { type, input, config, environment, safeMode, confirm } = req.body ?? {};
+    if (typeof type !== 'string' || type.length === 0) {
+        res.status(400).json({ error: 'Body must include a node "type"' });
+        return;
+    }
+    if (input !== undefined && (typeof input !== 'object' || input === null || Array.isArray(input))) {
+        res.status(400).json({ error: 'input must be a plain object' });
+        return;
+    }
+    if (config !== undefined && (typeof config !== 'object' || config === null || Array.isArray(config))) {
+        res.status(400).json({ error: 'config must be a plain object' });
+        return;
+    }
+    if (environment !== undefined && typeof environment !== 'string') {
+        res.status(400).json({ error: 'environment must be a string' });
+        return;
+    }
+    if (safeMode !== undefined && typeof safeMode !== 'boolean') {
+        res.status(400).json({ error: 'safeMode must be a boolean' });
+        return;
+    }
+    if (!runs.executionRegistry.has(type)) {
+        res.status(404).json({ error: `Unknown node type: ${type}` });
+        return;
+    }
+    const environmentName = environment ?? environmentsFile.defaultEnvironment;
+    const environmentDef = environmentsFile.environments[environmentName];
+    if (!environmentDef) {
+        res.status(400).json({ error: `Unknown environment: '${environmentName}'` });
+        return;
+    }
+    const safety = resolveRunSafety(environmentName, environmentDef, { safeMode, confirm });
+    if (!safety.ok) {
+        res.status(400).json({ error: safety.error });
+        return;
+    }
+    const { implementation } = runs.executionRegistry.get(type);
+    const runId = `node-run-${randomUUID().slice(0, 8)}`;
+    const logs = [];
+    const log = (level, message) => {
+        logs.push({ timestamp: new Date().toISOString(), level, runId, message });
+    };
+    const nodeInput = (input ?? {});
+    let result;
+    try {
+        const output = await implementation({
+            input: nodeInput,
+            config: (config ?? {}),
+            secrets: environmentDef.secrets,
+            vars: environmentDef.vars,
+            environment: environmentName,
+            safeMode: safety.safeMode,
+            runInput: nodeInput,
+            log,
+            // A node run in isolation has no flow context to resolve child workflows.
+            runSubflow: async () => ({
+                status: 'failed',
+                error: 'Subflow nodes cannot be run in isolation — run the whole operation instead',
+            }),
+        });
+        result = { output, logs };
+    }
+    catch (err) {
+        result = { error: err instanceof Error ? err.message : String(err), logs };
+    }
+    // Redact secret values from the output AND captured logs before responding.
+    res.json(redactSecrets(result, environmentDef.secrets));
+});
 api.post('/runs/:id/step', async (req, res) => {
-    const handle = runs.get(req.params.id);
-    if (!handle) {
+    // Drill-aware composite step: stepping INTO a Subflow reports
+    // `entered: { workflowId, nodeId }`, completing the child reports
+    // `exited: true` (see RunRegistry.step). Plain steps report just `done`.
+    const result = await runs.step(req.params.id);
+    if (!result) {
         res.status(404).json({ error: `Unknown run: ${req.params.id}` });
         return;
     }
-    const more = await handle.step();
-    res.json({ done: !more });
+    res.json(result);
 });
 api.post('/runs/:id/cancel', (req, res) => {
-    const handle = runs.get(req.params.id);
-    if (!handle) {
+    // Drill-aware: a stepped run drilled into subflows also cancels every
+    // stacked child and unblocks the parent executions (see RunRegistry.cancel).
+    if (!runs.cancel(req.params.id)) {
         res.status(404).json({ error: `Unknown run: ${req.params.id}` });
         return;
     }
-    handle.cancel();
     res.status(204).end();
 });
 api.get('/runs/:id/events', (req, res) => {
@@ -709,7 +812,7 @@ api.get('/runs/:id/events', (req, res) => {
     unsubscribe = runs.subscribe(runId, listener);
 });
 api.get('/agent/available', (_req, res) => {
-    res.json({ agents: detectAgents() });
+    res.json({ agents: detectAgentsCached() });
 });
 // First-run onboarding aggregate for the Welcome checklist (studio's
 // WelcomeDialog). Recomputed per request (cheap; mirrors /environments'
@@ -732,7 +835,10 @@ api.get('/setup-status', (_req, res) => {
     // A pristine project ships exactly the single `default/hello` example op.
     const onlyHello = ops.length === 1 && ops[0]?.id === 'default/hello';
     res.json({
-        agents: detectAgents(),
+        agents: detectAgentsCached(),
+        // Agent features snapshot changes with git (server/agents/runManager.ts);
+        // the checklist gates them on this. Same notion gitScope's isGitRepo uses.
+        git: { repo: isGitRepo(root) },
         environments: {
             configured: envs.configured,
             // The synthesized "local" fallback is "no environments yet" — report 0.
@@ -758,6 +864,52 @@ api.get('/setup-status', (_req, res) => {
 function skillInstalled(root, harness) {
     return [root, homedir()].some((base) => existsSync(join(base, `.${harness}`, 'skills', 'emberflow-basics', 'SKILL.md')));
 }
+// Package update notifier: the studio asks once per page load; checkForUpdate
+// caches registry hits for an hour and fails silent — an unreachable registry
+// (or a pre-publish package) just reports "no update".
+api.get('/update-status', async (_req, res) => {
+    const current = ownVersion() ?? '0.0.0';
+    const check = await checkForUpdate(current);
+    if (!check) {
+        res.json({ current, updateAvailable: false });
+        return;
+    }
+    res.json(check);
+});
+// One-click updater: npm-installs the latest package into the consumer
+// project. Single-flight — a second click while npm runs gets a 409, not a
+// second npm process fighting over node_modules.
+let updateInFlight = false;
+api.post('/update', async (_req, res) => {
+    if (!project) {
+        res.status(400).json({ ok: false, error: 'not a consumer project — no project is loaded to update' });
+        return;
+    }
+    if (isLinkedInstall(project.root)) {
+        res.status(400).json({
+            ok: false,
+            error: 'node_modules/@xdelivered/emberflow is a symlink (file:/npm-link dev setup) — refusing to npm install over it',
+        });
+        return;
+    }
+    if (updateInFlight) {
+        res.status(409).json({ ok: false, error: 'update already running' });
+        return;
+    }
+    updateInFlight = true;
+    try {
+        const result = await runNpmInstall(project.root);
+        if (result.ok) {
+            res.json({ ok: true, restartRequired: true });
+        }
+        else {
+            res.status(500).json({ ok: false, error: result.error });
+        }
+    }
+    finally {
+        updateInFlight = false;
+    }
+});
 /** The /setup-status `infrastructure` field: presence + a shallow summary. */
 function infraStatus() {
     const manifest = readInfrastructure();
@@ -786,10 +938,11 @@ api.post('/agent', (req, res) => {
         intent.action !== 'setup-auth' &&
         intent.action !== 'setup-environments' &&
         intent.action !== 'scout-infrastructure' &&
+        intent.action !== 'guided-setup' &&
         intent.action !== 'cover-operation' &&
         intent.action !== 'ask') {
         res.status(400).json({
-            error: `Unsupported intent.action: ${intent.action}. Must be one of new-scenario, edit-node, edit-flow, new-operation, setup-auth, setup-environments, scout-infrastructure, cover-operation, ask.`,
+            error: `Unsupported intent.action: ${intent.action}. Must be one of new-scenario, edit-node, edit-flow, new-operation, setup-auth, setup-environments, scout-infrastructure, guided-setup, cover-operation, ask.`,
         });
         return;
     }
@@ -805,7 +958,9 @@ api.post('/agent', (req, res) => {
             return;
         }
     }
-    else if (intent.action === 'setup-environments' || intent.action === 'scout-infrastructure') {
+    else if (intent.action === 'setup-environments' ||
+        intent.action === 'scout-infrastructure' ||
+        intent.action === 'guided-setup') {
         // instruction alone is required, already validated above; no flowId/environment needed.
     }
     else if (intent.action === 'ask') {
@@ -899,7 +1054,7 @@ const operationRunEnv = {
 // operation whose http.path collides with one of these would silently never
 // be reached (the internal route, registered first, always wins) — guarded
 // against below rather than left as a silent trap.
-const RESERVED_ROOT_PATHS = ['/healthz', '/nodes', '/samples', '/environments', '/workflows', '/runs', '/agent', '/serving'];
+const RESERVED_ROOT_PATHS = ['/healthz', '/nodes', '/samples', '/environments', '/workflows', '/runs', '/node-run', '/agent', '/serving'];
 function collidesWithReservedPath(path) {
     return RESERVED_ROOT_PATHS.some((reserved) => path === reserved || path.startsWith(`${reserved}/`));
 }
@@ -1007,6 +1162,22 @@ if (serveStudio) {
         console.warn(`[runner] EMBERFLOW_SERVE_STUDIO=1 but no studio-dist found near ${here} — run \`npm run build:studio\``);
     }
 }
+// Agent CLIs and node executions must not outlive the runner: agents are
+// spawned detached (their own process group), so without this a killed runner
+// leaves an orphaned agent editing the project — and possibly writing files
+// long after the studio is gone (observed in the wild). Cancel everything,
+// then exit.
+for (const signal of ['SIGINT', 'SIGTERM']) {
+    process.on(signal, () => {
+        try {
+            agentRuns.shutdown();
+            runs.shutdown();
+        }
+        finally {
+            process.exit(0);
+        }
+    });
+}
 app.listen(PORT, HOST, () => {
     console.log(`[emberflow-runner] listening on http://${HOST}:${PORT} — ${runs.nodeCount} nodes registered`);
     if (serveStudio) {

package/dist/server/runRegistry.d.ts

@@ -1,8 +1,12 @@
 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 = {
+export type RunEvent = 
+/** `workflowId` is the flow the node belongs to: the root flow for the
+ *  run's own nodes, the CHILD flow's id for a stepped subflow's nodes. */
+{
     type: 'nodeState';
+    workflowId: string;
     nodeId: string;
     state: NodeRunState;
 } | {
@@ -18,6 +22,17 @@ export type RunEvent = {
     };
 };
 type Listener = (event: RunEvent) => void;
+/** Result of one composite step on a stepped run (see RunRegistry.step). */
+export interface StepResult {
+    done: boolean;
+    /** Set when this step drove execution INTO a subflow child. */
+    entered?: {
+        workflowId: string;
+        nodeId: string;
+    };
+    /** Set when this step completed the deepest child and popped back out. */
+    exited?: true;
+}
 /** Manages live runs: buffers engine events per run and fans them out to SSE subscribers. */
 export declare class RunRegistry {
     private readonly loadFlow?;
@@ -62,10 +77,46 @@ export declare class RunRegistry {
          *  error-handler run — stamped onto this run's `finished` event as
          *  `errorHandler: { firedBy }`. Only meaningful alongside isErrorHandler. */
         errorHandlerFiredBy?: string;
+        /** When true (a step-mode run), Subflow children become step-drivable:
+         *  entering one pauses inside it instead of running it to completion in
+         *  a single opaque step. Drive the run via `step(runId)`. */
+        stepped?: boolean;
     }): {
         runId: string;
         handle: FlowRun;
     };
+    /**
+     * One composite step of a run, drill-aware. For stepped runs a Subflow node
+     * is no longer one opaque step: entering it pauses inside the child
+     * (`entered`), subsequent steps drive the child's nodes, and completing the
+     * child pops back out (`exited`). Non-stepped runs (no drill state) fall
+     * back to a plain executor step. Unknown run → undefined.
+     */
+    step(runId: string): Promise<StepResult | undefined>;
+    /**
+     * One composite step, drill-aware. Structured as a loop over levels: each
+     * pass drives the current deepest level (a pending stashed step, or a fresh
+     * executor step) while racing "a new child started". Popping a finished
+     * child continues the loop on its parent's stashed step WITH the race still
+     * armed — the parent's still-pending Subflow node execution may call
+     * runSubflow again (retry, or a custom node making sequential calls), and
+     * that re-entry must surface as `entered`, not deadlock the fold.
+     */
+    private stepLevels;
+    /**
+     * Cancel a run, drill-aware. For a stepped run drilled into subflows this
+     * cancels every stacked child deepest-first and rejects the promise each
+     * parent's Subflow node execution is blocked on — those pending executions
+     * then unwind in the background exactly like an in-flight node after a
+     * plain root cancel today (recorded, but the run is already finished).
+     * step() after cancel reports { done: true } without executing anything.
+     * Returns false for an unknown run.
+     */
+    /** Cancels every live (non-finished) run — the server's shutdown path, so
+     *  in-flight executions (and their drilled subflow children) don't keep
+     *  running headless after the process is asked to die. */
+    shutdown(): void;
+    cancel(runId: string): boolean;
     /**
      * Best-effort: fires `errorOperation` (resolved via the same `loadFlow`
      * callback Subflow nodes use) as a new run when `failedRun` finished with

package/dist/server/runRegistry.js

@@ -57,6 +57,10 @@ export class RunRegistry {
         // 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`.
+        // Stepped runs share ONE drill state across the root's runner and every
+        // nested child's runner (makeSubflowRunner threads `opts` through), so a
+        // grandchild pushes onto the same stack and nesting works.
+        const drillState = opts.stepped ? { stack: [] } : undefined;
         const subflowRunner = makeSubflowRunner({
             loadFlow: (id) => this.loadFlow?.(id),
             registry: this.registry,
@@ -67,6 +71,19 @@ export class RunRegistry {
             mockRun: opts.mockRun,
             trace: this.sink,
             onLog: (line) => emit({ type: 'log', line }),
+            drill: drillState,
+            // Stepped children stream node states into this run's SSE stream,
+            // tagged with the CHILD flow's id so the client can route them.
+            // After a drill-aware cancel the rejected parent executions unwind in
+            // the background (recording their Subflow nodes as failed) — child
+            // states from that unwinding must not reach subscribers post-finish.
+            onNodeState: drillState
+                ? (workflowId, nodeId, state) => {
+                    if (drillState.cancelled)
+                        return;
+                    emit({ type: 'nodeState', workflowId, nodeId, state });
+                }
+                : undefined,
         }, [flow.id]);
         const handle = startRun({
             flow,
@@ -82,9 +99,14 @@ export class RunRegistry {
             trace: this.sink,
             subflowRunner,
             events: {
-                onNodeStateChange: (nodeId, state) => emit({ type: 'nodeState', nodeId, state }),
+                onNodeStateChange: (nodeId, state) => emit({ type: 'nodeState', workflowId: flow.id, nodeId, state }),
                 onLog: (line) => emit({ type: 'log', line }),
                 onRunFinished: (run) => {
+                    // Idempotent: after a drill-aware cancel the root executor's pending
+                    // Subflow execution can fail in the background and re-finish the run
+                    // — subscribers already saw the cancelled `finished` event.
+                    if (entry.finished)
+                        return;
                     emit({
                         type: 'finished',
                         run,
@@ -100,9 +122,156 @@ export class RunRegistry {
             },
         });
         entry.handle = handle;
+        if (drillState)
+            entry.drill = { state: drillState };
         this.runs.set(handle.run.id, entry);
         return { runId: handle.run.id, handle };
     }
+    /**
+     * One composite step of a run, drill-aware. For stepped runs a Subflow node
+     * is no longer one opaque step: entering it pauses inside the child
+     * (`entered`), subsequent steps drive the child's nodes, and completing the
+     * child pops back out (`exited`). Non-stepped runs (no drill state) fall
+     * back to a plain executor step. Unknown run → undefined.
+     */
+    async step(runId) {
+        const entry = this.runs.get(runId);
+        if (!entry)
+            return undefined;
+        // Serialize per run: concurrent step() calls would each arm
+        // `state.onChildStarted` (last writer wins) and double-drive the
+        // executor, so the second caller waits for the first to settle.
+        const result = (entry.stepChain ?? Promise.resolve()).then(() => this.stepLevels(entry));
+        entry.stepChain = result.catch(() => undefined);
+        return result;
+    }
+    /**
+     * One composite step, drill-aware. Structured as a loop over levels: each
+     * pass drives the current deepest level (a pending stashed step, or a fresh
+     * executor step) while racing "a new child started". Popping a finished
+     * child continues the loop on its parent's stashed step WITH the race still
+     * armed — the parent's still-pending Subflow node execution may call
+     * runSubflow again (retry, or a custom node making sequential calls), and
+     * that re-entry must surface as `entered`, not deadlock the fold.
+     */
+    async stepLevels(entry) {
+        const drill = entry.drill;
+        if (!drill) {
+            const more = await entry.handle.step();
+            return { done: !more };
+        }
+        const { state } = drill;
+        // Cancelled mid-drill: the stack was already unwound by cancel(); report
+        // done without driving anything.
+        if (state.cancelled)
+            return { done: true };
+        // Set once this step pops a child; carried onto whatever this step
+        // ultimately reports (including an `entered` for a re-run child).
+        let exited = false;
+        const withExit = (r) => (exited ? { ...r, exited: true } : r);
+        for (;;) {
+            // The level being stepped: the deepest drilled-in child, or the root run.
+            const level = state.stack.length > 0 ? state.stack[state.stack.length - 1] : undefined;
+            const handle = level ? level.handle : entry.handle;
+            const pendingStep = level ? level.pendingStep : drill.rootPendingStep;
+            const setPending = (p) => {
+                if (level)
+                    level.pendingStep = p;
+                else
+                    drill.rootPendingStep = p;
+            };
+            // A Subflow node's execution blocks inside runSubflow until its child
+            // completes, so the step promise alone can never report "entered a
+            // child" — arm the child-started signal BEFORE awaiting and race them.
+            const childStarted = new Promise((res) => {
+                state.onChildStarted = res;
+            });
+            const stepPromise = pendingStep ?? handle.step();
+            setPending(undefined);
+            let raced;
+            try {
+                raced = await Promise.race([
+                    stepPromise.then((more) => ({ kind: 'stepped', more })),
+                    childStarted.then((child) => ({ kind: 'entered', child })),
+                ]);
+            }
+            catch (err) {
+                state.onChildStarted = undefined;
+                if (!level)
+                    throw err;
+                // A child level's step threw outright (not a recorded node failure —
+                // the executor catches those). Reject the parent's blocked runSubflow,
+                // which surfaces it as the Subflow node's error, then fold the parent
+                // (next loop pass, race re-armed).
+                state.stack.pop();
+                level.reject(err);
+                exited = true;
+                continue;
+            }
+            state.onChildStarted = undefined;
+            if (raced.kind === 'entered') {
+                // The level's step stays pending for the whole child run — stash it;
+                // the step that later pops this child folds its boolean back in.
+                setPending(stepPromise);
+                return withExit({
+                    done: false,
+                    entered: { workflowId: raced.child.workflowId, nodeId: raced.child.viaNodeId },
+                });
+            }
+            if (raced.more)
+                return withExit({ done: false });
+            // This level has no more nodes: its run is complete.
+            if (!level)
+                return withExit({ done: true });
+            // Pop the finished child and hand its completed run (succeeded OR failed)
+            // to the parent's blocked runSubflow — the success/failure semantics live
+            // in subflowRunner, byte-identical to the non-stepped path. The parent's
+            // stashed step is folded in by the next loop pass, with the child-started
+            // race re-armed so a retrying Subflow node re-entering its child yields
+            // `exited` + `entered` instead of hanging.
+            state.stack.pop();
+            level.resolve(level.handle.run);
+            exited = true;
+        }
+    }
+    /**
+     * Cancel a run, drill-aware. For a stepped run drilled into subflows this
+     * cancels every stacked child deepest-first and rejects the promise each
+     * parent's Subflow node execution is blocked on — those pending executions
+     * then unwind in the background exactly like an in-flight node after a
+     * plain root cancel today (recorded, but the run is already finished).
+     * step() after cancel reports { done: true } without executing anything.
+     * Returns false for an unknown run.
+     */
+    /** Cancels every live (non-finished) run — the server's shutdown path, so
+     *  in-flight executions (and their drilled subflow children) don't keep
+     *  running headless after the process is asked to die. */
+    shutdown() {
+        for (const [id, run] of this.runs) {
+            if (!run.finished)
+                this.cancel(id);
+        }
+    }
+    cancel(runId) {
+        const entry = this.runs.get(runId);
+        if (!entry)
+            return false;
+        const drill = entry.drill;
+        if (drill) {
+            const { state } = drill;
+            state.cancelled = true;
+            state.onChildStarted = undefined;
+            while (state.stack.length > 0) {
+                const child = state.stack.pop();
+                child.pendingStep = undefined;
+                child.handle.cancel();
+                child.reject(new Error('run cancelled'));
+            }
+            drill.rootPendingStep = undefined;
+        }
+        entry.handle.cancel();
+        return true;
+    }
     /**
      * Best-effort: fires `errorOperation` (resolved via the same `loadFlow`
      * callback Subflow nodes use) as a new run when `failedRun` finished with

package/dist/server/subflowRunner.d.ts

@@ -1,6 +1,42 @@
-import type { LogLine, NodeRegistry, StartRunOptions, TraceSink, WorkflowDefinition } from '../src/engine/index.js';
+import type { FlowRun, LogLine, NodeRegistry, NodeRunState, StartRunOptions, TraceSink, WorkflowDefinition, WorkflowRun } from '../src/engine/index.js';
 /** Max depth of nested Subflow calls (ancestry chain length) before a run fails. */
 export declare const SUBFLOW_DEPTH_CAP = 8;
+/**
+ * One live drilled-into child on a stepped run. Pushed by the subflow runner
+ * when a Subflow node starts its child; popped by the registry's composite
+ * step() when the child's own stepping completes. `resolve`/`reject` settle
+ * the promise the parent's Subflow node execution is blocked on.
+ */
+export interface DrillEntry {
+    handle: FlowRun;
+    /** The child flow's id (what the caller drilled into). */
+    workflowId: string;
+    /** The parent Subflow node that triggered the child. */
+    viaNodeId: string;
+    /** Hands the completed child run back to the blocked parent Subflow node. */
+    resolve: (run: WorkflowRun) => void;
+    reject: (err: unknown) => void;
+    /**
+     * This level's own executor.step() promise, left pending while a DEEPER
+     * child runs (a Subflow node's execution blocks on its child). Stashed by
+     * the registry when it observes `entered`; folded back in on exit.
+     */
+    pendingStep?: Promise<boolean>;
+}
+/**
+ * Per-root-run drill state for stepped runs. The root's subflow runner and
+ * every nested child's runner share the SAME instance, so grandchildren push
+ * onto the same stack and nesting Just Works.
+ */
+export interface DrillState {
+    stack: DrillEntry[];
+    /** Armed by the registry's step() while it awaits a level's step, so a
+     *  child starting can be raced against the (now blocked) step promise. */
+    onChildStarted?: (entry: DrillEntry) => void;
+    /** Set by RunRegistry.cancel(): unwinding parent executions must not start
+     *  (or block on) new children — runSubflow fails fast instead. */
+    cancelled?: boolean;
+}
 export interface SubflowRunnerOptions {
     /** Resolves a child workflow by id (server hosts this via apiStore.load). */
     loadFlow: (id: string) => WorkflowDefinition | undefined;
@@ -19,6 +55,17 @@ export interface SubflowRunnerOptions {
      *  prefixed with the child flow's name and the caller node's id, exactly as
      *  the live runner streams them over SSE. Absent for headless runs. */
     onLog?: (line: LogLine) => void;
+    /**
+     * Present only for stepped runs: children become step-drivable instead of
+     * running to completion. The runner pushes each started child onto
+     * `drill.stack` and blocks the Subflow node until the registry pops it.
+     */
+    drill?: DrillState;
+    /** Child nodeState forwarder for stepped runs — receives the CHILD flow's
+     *  id so the client can route states to the drilled-in view. Only wired
+     *  when `drill` is present (non-stepped children keep today's behavior:
+     *  their node states are discarded, only the output returns). */
+    onNodeState?: (workflowId: string, nodeId: string, state: NodeRunState) => void;
 }
 /**
  * Shared Subflow-runner factory used by BOTH the live runner