@noetic-tools/core 0.0.1 → 0.1.1

package/dist/interpreter/execute.js

@@ -1,17 +1,104 @@
-import { NoeticErrorImpl } from '../errors/noetic-error';
-import { emitFrameworkEvent, getBroadcaster, shouldEmit } from '../runtime/broadcaster-utils';
-import { executeBranch } from './execute-branch';
-import { executeEvery } from './execute-every';
-import { executeFork } from './execute-fork';
-import { executeLLM } from './execute-llm';
-import { executeLoop } from './execute-loop';
-import { executeProvide } from './execute-provide';
-import { executeRun } from './execute-run';
-import { executeSpawn } from './execute-spawn';
-import { executeTool } from './execute-tool';
-import { frameworkCast } from './framework-cast';
-import { isMutableContext } from './typeguards';
+import { NoeticErrorImpl } from '../errors/noetic-error.js';
+import { emitFrameworkEvent, getBroadcaster, shouldEmit } from '../runtime/broadcaster-utils.js';
+import { ContextImpl } from '../runtime/context-impl.js';
+import { DetachedHandleImpl } from '../runtime/detached-handle.js';
+import { frameworkCast } from '../util/framework-cast.js';
+import { executeLLM, executeProvide, executeRun, executeSpawn, executeTool, } from './execute-action.js';
+import { executeBranch, executeEvery, executeFork, executeLoop } from './execute-control.js';
+import { isMutableContext } from './typeguards.js';
+//#region Constants
 const MAX_DEPTH = 64;
+//#endregion
+//#region Helpers
+/**
+ * Return the underlying `ContextImpl` when the context is one we produced
+ * in-process. Out-of-process descendants reach us through the adapter
+ * boundary and are not `ContextImpl` instances, so frontier bookkeeping is
+ * a no-op for them.
+ */
+function asContextImpl(ctx) {
+    return ctx instanceof ContextImpl ? ctx : null;
+}
+function harnessWithLayerStore(ctx) {
+    return frameworkCast(ctx.harness);
+}
+function buildSpawnOpts(ctx) {
+    const baseCtx = frameworkCast(ctx);
+    return {
+        itemSchemas: baseCtx.itemSchemas,
+        parentLayers: baseCtx.layers,
+        layerStore: harnessWithLayerStore(baseCtx).layerStateStore,
+    };
+}
+/**
+ * Resolve the subprocess adapter that should handle dispatch for this step.
+ * Precedence is `step.subprocess ?? ctx.harness.subprocess`. Per-call
+ * `detachedSpawn` overrides layer above this in the harness itself.
+ */
+function resolveStepAdapter(step, ctx) {
+    if ((step.kind === 'run' || step.kind === 'spawn') && step.subprocess) {
+        return step.subprocess;
+    }
+    return ctx.harness.subprocess;
+}
+/**
+ * Dispatch a run/spawn step through the resolved subprocess adapter.
+ *
+ * The `_localExecutor` closure carries the in-process fallback path — the
+ * in-memory adapter invokes it directly, preserving the pre-refactor
+ * dispatch semantics including parent-context inheritance, layer lifecycle,
+ * and synchronous error propagation. Out-of-process adapters ignore
+ * `_localExecutor` and run the step in a child runtime.
+ */
+async function dispatchViaAdapter(step, input, ctx, executor) {
+    const adapter = resolveStepAdapter(step, ctx);
+    const request = {
+        kind: 'step',
+        stepId: step.id,
+        serializedInput: input,
+        executionId: ctx.id,
+        overrides: {
+            threadId: ctx.threadId,
+            resourceId: ctx.resourceId,
+        },
+        _localExecutor: () => executor(),
+    };
+    const spawnPromise = adapter.spawn(request);
+    const handle = new DetachedHandleImpl({
+        id: ctx.id,
+        stepId: step.id,
+        adapter,
+        spawnPromise,
+    });
+    return handle.await();
+}
+/**
+ * @internal
+ * Dispatch a step at the per-kind handler level without adapter routing.
+ *
+ * Used as the top-level `_localExecutor` for `StepRun` / `StepSpawn`
+ * dispatches: the outer adapter call already recorded the request, so
+ * running the handler directly avoids a re-entrant adapter round-trip
+ * inside the same logical step. Nested step dispatches (e.g. `executeSpawn`
+ * descending into `step.child`) still go through `execute()` and route
+ * through the adapter as normal, so per-step overrides on descendants
+ * continue to work.
+ */
+export async function executeNoAdapter(step, input, ctx) {
+    switch (step.kind) {
+        case 'run':
+            return executeRun(step, input, ctx);
+        case 'spawn':
+            return executeSpawn(step, input, ctx, (s, i, c) => execute(s, i, c), buildSpawnOpts(ctx));
+        default:
+            // Kinds that don't currently route through the adapter (llm, tool,
+            // branch, fork, provide, loop, every). Delegate back to `execute()`
+            // so they exercise the normal dispatch table, framework-event emits,
+            // abort checks, and depth guard.
+            return execute(step, input, ctx);
+    }
+}
+//#endregion
 /**
  * Executes a step within the interpreter, dispatching to the appropriate handler by step kind.
  *
@@ -61,45 +148,61 @@ export async function execute(step, input, ctx) {
             data: startedData,
         });
     }
+    // Push onto the durable frontier so checkpoints can record exactly which
+    // step was in flight when the snapshot fired. Steps with empty ids are
+    // skipped — they are not reattachable by id and would pollute the stack.
+    const impl = asContextImpl(baseCtx);
+    if (impl && step.id.length > 0) {
+        impl.enterStep({
+            stepId: step.id,
+            input,
+        });
+    }
     let result;
-    switch (step.kind) {
-        case 'run':
-            result = await executeRun(step, input, ctx);
-            break;
-        case 'llm':
-            result = await executeLLM(step, input, ctx, baseCtx.layers);
-            break;
-        case 'tool':
-            result = await executeTool(step, input, ctx, baseCtx.harness);
-            break;
-        case 'branch':
-            result = await executeBranch(step, input, ctx, (s, i, c) => execute(s, i, c));
-            break;
-        case 'fork':
-            result = await executeFork(step, input, ctx, (s, i, c) => execute(s, i, c));
-            break;
-        case 'spawn':
-            result = await executeSpawn(step, input, ctx, (s, i, c) => execute(s, i, c), {
-                itemSchemas: baseCtx.itemSchemas,
-            });
-            break;
-        case 'provide':
-            result = await executeProvide(step, input, ctx, (s, i, c) => execute(s, i, c));
-            break;
-        case 'loop':
-            result = await executeLoop(step, input, ctx, (s, i, c) => execute(s, i, c));
-            break;
-        case 'every':
-            result = await executeEvery(step, input, ctx, (s, i, c) => execute(s, i, c));
-            break;
-        default: {
-            const _exhaustive = step;
-            throw new NoeticErrorImpl({
-                kind: 'step_failed',
-                stepId: 'unknown',
-                cause: new Error('Unknown step kind'),
-                retriesExhausted: false,
-            });
+    try {
+        switch (step.kind) {
+            case 'run':
+                result = await dispatchViaAdapter(step, input, ctx, () => executeRun(step, input, ctx));
+                break;
+            case 'llm':
+                result = await executeLLM(step, input, ctx, baseCtx.layers);
+                break;
+            case 'tool':
+                result = await executeTool(step, input, ctx, baseCtx.harness);
+                break;
+            case 'branch':
+                result = await executeBranch(step, input, ctx, (s, i, c) => execute(s, i, c));
+                break;
+            case 'fork':
+                result = await executeFork(step, input, ctx, (s, i, c) => execute(s, i, c));
+                break;
+            case 'spawn':
+                result = await dispatchViaAdapter(step, input, ctx, () => executeSpawn(step, input, ctx, (s, i, c) => execute(s, i, c), buildSpawnOpts(ctx)));
+                break;
+            case 'provide':
+                result = await executeProvide(step, input, ctx, (s, i, c) => execute(s, i, c));
+                break;
+            case 'loop':
+                result = await executeLoop(step, input, ctx, (s, i, c) => execute(s, i, c));
+                break;
+            case 'every':
+                result = await executeEvery(step, input, ctx, (s, i, c) => execute(s, i, c));
+                break;
+            default: {
+                const _exhaustive = step;
+                void _exhaustive;
+                throw new NoeticErrorImpl({
+                    kind: 'step_failed',
+                    stepId: 'unknown',
+                    cause: new Error('Unknown step kind'),
+                    retriesExhausted: false,
+                });
+            }
+        }
+    }
+    finally {
+        if (impl && step.id.length > 0) {
+            impl.leaveStep(step.id);
         }
     }
     // Emit step_completed framework event (respects step.emit option)

package/dist/interpreter/message-helpers.d.ts

@@ -1,9 +1 @@
-import type { LLMResponse } from '../types/common';
-import type { Context } from '../types/context';
-import type { InputMessageItem, Item } from '../types/items';
-export declare function createMessage(text: string, role: 'user' | 'developer'): InputMessageItem;
-export declare function extractAssistantText(items: ReadonlyArray<Item>): string;
-/** Naive token estimate: ~4 chars per token */
-export declare function estimateTokens(text: string): number;
-/** Accumulate token usage and cost from an LLM response onto the context. */
-export declare function trackUsage(ctx: Context, response: LLMResponse): void;
+export { trackUsage } from '../util/message-helpers.js';

package/dist/interpreter/message-helpers.js

@@ -1,42 +1 @@
-import { isAssistantMessage, isMutableContext, isOutputText } from './typeguards';
-export function createMessage(text, role) {
-    return {
-        id: crypto.randomUUID(),
-        status: 'completed',
-        type: 'message',
-        role,
-        content: [
-            {
-                type: 'input_text',
-                text,
-            },
-        ],
-    };
-}
-export function extractAssistantText(items) {
-    const lastMsg = items.findLast(isAssistantMessage);
-    if (!lastMsg) {
-        return '';
-    }
-    return (lastMsg.content
-        ?.filter(isOutputText)
-        ?.map((c) => c.text)
-        ?.join('') ?? '');
-}
-/** Naive token estimate: ~4 chars per token */
-export function estimateTokens(text) {
-    return Math.ceil(text.length / 4);
-}
-/** Accumulate token usage and cost from an LLM response onto the context. */
-export function trackUsage(ctx, response) {
-    if (!isMutableContext(ctx)) {
-        return;
-    }
-    ctx.tokens.input += response.usage.inputTokens;
-    ctx.tokens.output += response.usage.outputTokens;
-    ctx.tokens.total += response.usage.inputTokens + response.usage.outputTokens;
-    ctx.tokens.cached = (ctx.tokens.cached ?? 0) + (response.usage.cachedTokens ?? 0);
-    if (response.cost) {
-        ctx.cost = ctx.cost + response.cost;
-    }
-}
+export { trackUsage } from '../util/message-helpers.js';

package/dist/interpreter/step-dispatcher.d.ts

@@ -0,0 +1,61 @@
+import type { Context } from '../types/context.js';
+import type { DetachedHandle } from '../types/detached.js';
+import type { ContextMemory } from '../types/memory.js';
+import type { Step } from '../types/step.js';
+import type { SubprocessAdapter } from '../types/subprocess-adapter.js';
+/**
+ * Resolve the subprocess adapter used for a given step dispatch.
+ *
+ * Precedence: `detachedSpawn-overrides.subprocess ?? step.subprocess ??
+ * harness.subprocess`. Only `StepRun` and `StepSpawn` currently carry a
+ * `subprocess` field — other variants always fall through to the harness
+ * default.
+ *
+ * @internal
+ */
+export declare function resolveStepAdapter<TMemory, I, O>(step: Step<TMemory, I, O>, callOverride: SubprocessAdapter | undefined, fallback: SubprocessAdapter): SubprocessAdapter;
+/**
+ * Minimum harness surface the dispatcher needs. `AgentHarness` satisfies
+ * this shape — kept structural so tests can pass a stub.
+ *
+ * @internal
+ */
+export interface StepDispatchHandle {
+    readonly subprocess: SubprocessAdapter;
+    createContext(opts?: {
+        parent?: Context;
+        threadId?: string;
+        resourceId?: string;
+        cwdInit?: string;
+    }): Context;
+}
+export interface DetachedSpawnOverrides {
+    /** Override the child's thread id. Default inherits from `parentCtx.threadId`. */
+    threadId?: string;
+    /** Override the child's resource id. Default inherits from `parentCtx.resourceId`. */
+    resourceId?: string;
+    /** Override the child's initial cwd. Used by worktree isolation to root the child at the worktree path. */
+    cwdInit?: string;
+    /**
+     * Per-call subprocess adapter override. Takes precedence over both
+     * `step.subprocess` and `harness.subprocess`. Pass a custom adapter to
+     * dispatch this specific spawn through a different runtime (e.g. a
+     * local OS subprocess or a test double that records the request).
+     */
+    subprocess?: SubprocessAdapter;
+}
+/**
+ * Route a step through the configured subprocess adapter and return a
+ * `DetachedHandle` that polls until the adapter reports a terminal
+ * status. The adapter's `spawn()` may be async (the default in-memory
+ * adapter schedules the step body on the microtask queue, and
+ * out-of-process adapters may await an OS spawn).
+ *
+ * `executeNoAdapter` is used as the local executor so the adapter we just
+ * routed through does not re-route the same step. The handler still uses
+ * `execute()` for nested children, so per-step overrides on descendants
+ * keep working.
+ *
+ * @internal
+ */
+export declare function dispatchStepThroughAdapter<I, O>(h: StepDispatchHandle, s: Step<ContextMemory, I, O>, input: I, parentCtx: Context, overrides?: DetachedSpawnOverrides): DetachedHandle<O>;

package/dist/interpreter/step-dispatcher.js

@@ -0,0 +1,67 @@
+import { DetachedHandleImpl } from '../runtime/detached-handle.js';
+import { executeNoAdapter } from './execute.js';
+//#region Adapter resolution
+/**
+ * Resolve the subprocess adapter used for a given step dispatch.
+ *
+ * Precedence: `detachedSpawn-overrides.subprocess ?? step.subprocess ??
+ * harness.subprocess`. Only `StepRun` and `StepSpawn` currently carry a
+ * `subprocess` field — other variants always fall through to the harness
+ * default.
+ *
+ * @internal
+ */
+export function resolveStepAdapter(step, callOverride, fallback) {
+    if (callOverride) {
+        return callOverride;
+    }
+    if ((step.kind === 'run' || step.kind === 'spawn') && step.subprocess) {
+        return step.subprocess;
+    }
+    return fallback;
+}
+//#endregion
+//#region Dispatcher
+/**
+ * Route a step through the configured subprocess adapter and return a
+ * `DetachedHandle` that polls until the adapter reports a terminal
+ * status. The adapter's `spawn()` may be async (the default in-memory
+ * adapter schedules the step body on the microtask queue, and
+ * out-of-process adapters may await an OS spawn).
+ *
+ * `executeNoAdapter` is used as the local executor so the adapter we just
+ * routed through does not re-route the same step. The handler still uses
+ * `execute()` for nested children, so per-step overrides on descendants
+ * keep working.
+ *
+ * @internal
+ */
+export function dispatchStepThroughAdapter(h, s, input, parentCtx, overrides) {
+    const childCtx = h.createContext({
+        parent: parentCtx,
+        threadId: overrides?.threadId ?? parentCtx.threadId,
+        resourceId: overrides?.resourceId ?? parentCtx.resourceId,
+        cwdInit: overrides?.cwdInit,
+    });
+    const adapter = resolveStepAdapter(s, overrides?.subprocess, h.subprocess);
+    const request = {
+        kind: 'step',
+        stepId: s.id,
+        serializedInput: input,
+        executionId: childCtx.id,
+        overrides: {
+            threadId: overrides?.threadId ?? parentCtx.threadId,
+            resourceId: overrides?.resourceId ?? parentCtx.resourceId,
+            cwdInit: overrides?.cwdInit,
+        },
+        _localExecutor: () => executeNoAdapter(s, input, childCtx),
+    };
+    const spawnPromise = adapter.spawn(request);
+    return new DetachedHandleImpl({
+        id: childCtx.id,
+        stepId: s.id,
+        adapter,
+        spawnPromise,
+    });
+}
+//#endregion

package/dist/interpreter/typeguards.d.ts

@@ -1,25 +1,18 @@
-import type { ChannelStore } from '../runtime/channel-store';
-import { ContextImpl } from '../runtime/context-impl';
-import type { Context } from '../types/context';
-import type { FunctionCallItem, Item, MessageItem } from '../types/items';
-import type { ContextMemory } from '../types/memory';
-import type { MutableContext } from '../types/mutable-context';
+import type { ChannelStore } from '../runtime/channel-store.js';
+import { ContextImpl } from '../runtime/context-impl.js';
+import type { Context } from '../types/context.js';
+import type { FunctionCallItem, Item } from '../types/items.js';
+import type { ContextMemory } from '../types/memory.js';
+import type { MutableContext } from '../types/mutable-context.js';
+export { isAssistantMessage, isOutputText, isUserMessage } from '../util/message-helpers.js';
 export declare function isMutableContext(ctx: Context<ContextMemory>): ctx is MutableContext;
 export declare function isContextImpl(ctx: Context<ContextMemory>): ctx is ContextImpl;
 /**
  * Co-located with `isContextImpl` so the import of `ContextImpl` flows through
  * the same module other interpreters pull it from, sidestepping a circular
- * TDZ when this helper is used by `execute-every.ts`.
+ * TDZ when this helper is used by `executeEvery` in `execute-control.ts`.
  */
 export declare function getContextChannelStore<TMemory>(ctx: Context<TMemory>): ChannelStore | undefined;
-export declare function isAssistantMessage(item: unknown): item is MessageItem;
-export declare function isUserMessage(item: unknown): item is MessageItem;
 export declare function isFunctionCall(item: Item): item is FunctionCallItem;
-export declare function isOutputText(part: {
-    type: string;
-}): part is {
-    type: 'output_text';
-    text: string;
-};
 declare function assertNever(_value: never): never;
 export { assertNever };

package/dist/interpreter/typeguards.js

@@ -1,4 +1,6 @@
-import { ContextImpl } from '../runtime/context-impl';
+import { ContextImpl } from '../runtime/context-impl.js';
+// Re-exports for backward compatibility; the pure variants live in util/.
+export { isAssistantMessage, isOutputText, isUserMessage } from '../util/message-helpers.js';
 export function isMutableContext(ctx) {
     // Check if the context has writable mutable fields (ContextImpl or compatible mock)
     if (ctx instanceof ContextImpl) {
@@ -14,7 +16,7 @@ export function isContextImpl(ctx) {
 /**
  * Co-located with `isContextImpl` so the import of `ContextImpl` flows through
  * the same module other interpreters pull it from, sidestepping a circular
- * TDZ when this helper is used by `execute-every.ts`.
+ * TDZ when this helper is used by `executeEvery` in `execute-control.ts`.
  */
 export function getContextChannelStore(ctx) {
     if (ctx instanceof ContextImpl) {
@@ -22,28 +24,9 @@ export function getContextChannelStore(ctx) {
     }
     return undefined;
 }
-export function isAssistantMessage(item) {
-    return (typeof item === 'object' &&
-        item !== null &&
-        'type' in item &&
-        item.type === 'message' &&
-        'role' in item &&
-        item.role === 'assistant');
-}
-export function isUserMessage(item) {
-    return (typeof item === 'object' &&
-        item !== null &&
-        'type' in item &&
-        item.type === 'message' &&
-        'role' in item &&
-        item.role === 'user');
-}
 export function isFunctionCall(item) {
     return item.type === 'function_call' && 'callId' in item && 'name' in item;
 }
-export function isOutputText(part) {
-    return part.type === 'output_text';
-}
 function assertNever(_value) {
     throw new Error('Exhaustive check failed');
 }

package/dist/memory/budget.d.ts

@@ -1,5 +1,5 @@
-import type { Context } from '../types/context';
-import type { MemoryLayer } from '../types/memory';
+import type { Context } from '../types/context.js';
+import type { MemoryLayer } from '../types/memory.js';
 export interface BudgetAllocation {
     layerId: string;
     allocated: number;

package/dist/memory/budget.js

@@ -1,4 +1,4 @@
-import { NoeticErrorImpl } from '../errors/noetic-error';
+import { NoeticErrorImpl } from '../errors/noetic-error.js';
 function extractMin(config) {
     if (config && typeof config === 'object' && 'min' in config) {
         return config.min;

package/dist/{runtime → memory}/exec-context-factory.d.ts

@@ -1,5 +1,5 @@
-import type { Context } from '../types/context';
-import type { ExecutionContext } from '../types/memory';
+import type { Context } from '../types/context.js';
+import type { ExecutionContext } from '../types/memory.js';
 /**
  * Optional overrides for `contextToExecCtx`. Used by `executeSpawn` to build
  * parent and child execution contexts that reuse the same tokenize / trace /

package/dist/{runtime → memory}/exec-context-factory.js

@@ -1,4 +1,4 @@
-import { estimateTokens } from '../interpreter/message-helpers';
+import { estimateTokens } from '../util/message-helpers.js';
 /**
  * Maps a full `Context` to the lightweight `ExecutionContext` consumed by memory layer hooks.
  * Centralised here so the mapping stays consistent across agent-harness, layer-api, and the

package/dist/memory/flow-schema.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Zod schema for plan-mode flow JSON.
+ *
+ * A "flow" is a JSON-serialisable subset of noetic's `Step` shape that the model
+ * may emit during plan mode. The runtime expands each node into a concrete `Step`
+ * via the existing builders (`step.llm`, `fork`, `spawn`) at execute time.
+ *
+ * Tool references inside `llm` nodes are name strings. They get resolved against
+ * the harness's live tool registry when the flow runs.
+ */
+import { z } from 'zod';
+interface NodeBase {
+    id: string;
+    subPlanRef?: string;
+}
+export interface LlmFlowNode extends NodeBase {
+    kind: 'llm';
+    model?: string;
+    instructions: string;
+    tools?: string[];
+}
+export interface SubagentFlowNode extends NodeBase {
+    kind: 'subagent';
+    preset: string;
+    prompt: string;
+}
+export interface ForkFlowNode extends NodeBase {
+    kind: 'fork';
+    mode: 'all' | 'race' | 'settle';
+    paths: FlowNode[];
+}
+export interface SpawnFlowNode extends NodeBase {
+    kind: 'spawn';
+    child: FlowNode;
+}
+export interface SequenceFlowNode extends NodeBase {
+    kind: 'sequence';
+    steps: FlowNode[];
+}
+export type FlowNode = LlmFlowNode | SubagentFlowNode | ForkFlowNode | SpawnFlowNode | SequenceFlowNode;
+/** Top-level flow document: a single root node. */
+export declare const FlowSchema: z.ZodType<FlowNode, unknown, z.core.$ZodTypeInternals<FlowNode, unknown>>;
+/** Validates a candidate flow document. Throws `ZodError` on invalid input. */
+export declare function validateFlow(input: unknown): FlowNode;
+/** Walks a flow tree depth-first, yielding each node. */
+export declare function walkFlow(root: FlowNode): Iterable<FlowNode>;
+/**
+ * Returns the maximum depth of a flow tree. A leaf (llm/subagent) is depth 0.
+ * Structural nodes (sequence/fork/spawn) contribute +1 over their deepest child.
+ */
+export declare function flowDepth(node: FlowNode): number;
+export {};

package/dist/memory/flow-schema.js

@@ -0,0 +1,102 @@
+/**
+ * Zod schema for plan-mode flow JSON.
+ *
+ * A "flow" is a JSON-serialisable subset of noetic's `Step` shape that the model
+ * may emit during plan mode. The runtime expands each node into a concrete `Step`
+ * via the existing builders (`step.llm`, `fork`, `spawn`) at execute time.
+ *
+ * Tool references inside `llm` nodes are name strings. They get resolved against
+ * the harness's live tool registry when the flow runs.
+ */
+import { z } from 'zod';
+//#endregion
+//#region Schema
+const FlowNodeRef = z.lazy(() => FlowNodeSchema);
+const SHARED_FIELDS = {
+    id: z.string().min(1),
+    subPlanRef: z.string().optional(),
+};
+const LlmNodeSchema = z.object({
+    kind: z.literal('llm'),
+    ...SHARED_FIELDS,
+    model: z.string().optional(),
+    instructions: z.string(),
+    tools: z.array(z.string()).optional(),
+});
+const SubagentNodeSchema = z.object({
+    kind: z.literal('subagent'),
+    ...SHARED_FIELDS,
+    preset: z.string().min(1),
+    prompt: z.string(),
+});
+const ForkNodeSchema = z.object({
+    kind: z.literal('fork'),
+    ...SHARED_FIELDS,
+    mode: z.enum([
+        'all',
+        'race',
+        'settle',
+    ]),
+    paths: z.array(FlowNodeRef).min(1),
+});
+const SpawnNodeSchema = z.object({
+    kind: z.literal('spawn'),
+    ...SHARED_FIELDS,
+    child: FlowNodeRef,
+});
+const SequenceNodeSchema = z.object({
+    kind: z.literal('sequence'),
+    ...SHARED_FIELDS,
+    steps: z.array(FlowNodeRef).min(1),
+});
+const FlowNodeSchema = z.discriminatedUnion('kind', [
+    LlmNodeSchema,
+    SubagentNodeSchema,
+    ForkNodeSchema,
+    SpawnNodeSchema,
+    SequenceNodeSchema,
+]);
+/** Top-level flow document: a single root node. */
+export const FlowSchema = FlowNodeSchema;
+//#endregion
+//#region Public API
+/** Validates a candidate flow document. Throws `ZodError` on invalid input. */
+export function validateFlow(input) {
+    return FlowSchema.parse(input);
+}
+/** Walks a flow tree depth-first, yielding each node. */
+export function* walkFlow(root) {
+    yield root;
+    if (root.kind === 'fork') {
+        for (const path of root.paths) {
+            yield* walkFlow(path);
+        }
+        return;
+    }
+    if (root.kind === 'sequence') {
+        for (const step of root.steps) {
+            yield* walkFlow(step);
+        }
+        return;
+    }
+    if (root.kind === 'spawn') {
+        yield* walkFlow(root.child);
+    }
+}
+/**
+ * Returns the maximum depth of a flow tree. A leaf (llm/subagent) is depth 0.
+ * Structural nodes (sequence/fork/spawn) contribute +1 over their deepest child.
+ */
+export function flowDepth(node) {
+    if (node.kind === 'sequence') {
+        return 1 + Math.max(0, ...node.steps.map(flowDepth));
+    }
+    if (node.kind === 'fork') {
+        return 1 + Math.max(0, ...node.paths.map(flowDepth));
+    }
+    if (node.kind === 'spawn') {
+        return 1 + flowDepth(node.child);
+    }
+    return 0;
+}
+//#endregion