@noetic-tools/core 0.0.1 → 0.1.0

package/dist/runtime/durable/stall-nudge.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Two-strike stall-nudge helper composable with `runnableLoop`.
+ *
+ * A runner's first turn can end without settling the outcome signal
+ * and without the agent asking for external input — i.e. the agent
+ * stopped without calling either a terminal tool or an ask-user-style
+ * tool. That's a soft failure: rather than wait forever, we nudge the
+ * agent once to remind it of its options. If the second turn also
+ * ends in the same stalled shape we escalate: the caller-supplied
+ * `onStall` callback records the escalation (task pause, metrics,
+ * whatever the domain demands) and we settle the signal ourselves with
+ * a canonical "stalled" outcome so the parent unwinds cleanly.
+ *
+ * The helper factors the state machine out of the loop so callers can
+ * opt in per-runner. Task-specific concerns (how "pending external
+ * input" is detected, how escalation is recorded, what outcome
+ * represents a stalled failure) stay with the caller and flow in via
+ * the config.
+ */
+import type { InputMessageItem } from '../../types/items';
+import type { DetachedSignal } from './detached-signal';
+import type { AfterFirstTurnContext, RunnableLoopHarness } from './runnable-loop';
+/**
+ * Default developer-role text sent when the agent finishes a turn
+ * without calling a terminal tool or an ask-user tool. Kept short and
+ * unambiguous — the agent should be reminded of its options without
+ * being lectured. Callers may override via `createNudgeMessage(text)`.
+ */
+export declare const DEFAULT_NUDGE_MESSAGE_TEXT = "You finished a turn without calling a terminal tool or AskUserQuestion. If you need user input or instruction to continue, call AskUserQuestion now. Otherwise call your terminal tool to complete this phase.";
+export interface CreateNudgeMessageOpts {
+    /** Unique id for the message so item-log dedupe can distinguish re-spawns. */
+    readonly id: string;
+    /** Override the developer-role text. Defaults to `DEFAULT_NUDGE_MESSAGE_TEXT`. */
+    readonly text?: string;
+}
+export interface StallNudgeOpts<TOutcome> {
+    readonly harness: RunnableLoopHarness;
+    readonly threadId: string;
+    readonly signal: DetachedSignal<TOutcome>;
+    /**
+     * The framing message sent as the nudge. Use `createNudgeMessage`
+     * for the canonical developer-role item, or pass your own when a
+     * domain needs a custom shape.
+     */
+    readonly nudgeMessage: InputMessageItem;
+    /**
+     * True when the agent intentionally awaits external input (e.g. an
+     * outstanding ask-user request). When true the nudge is suppressed
+     * — the agent is not stalled, it is waiting for us.
+     */
+    hasPendingExternal(): boolean;
+    /**
+     * Record-side-effect callback fired when the agent stalls a second
+     * time. Use this to mark the task paused, emit a metric, append an
+     * event log entry — whatever the domain needs before the signal
+     * settles.
+     */
+    onStall(): Promise<void>;
+    /** Build the outcome value the signal resolves to on stall escalation. */
+    buildStalledOutcome(): TOutcome;
+}
+/**
+ * Build the canonical developer-role nudge message item. Callers who
+ * want a custom framing build their own `InputMessageItem`; this
+ * helper exists so the common case stays one line.
+ */
+export declare function createNudgeMessage(opts: CreateNudgeMessageOpts): InputMessageItem;
+/**
+ * Build a `runnableLoop`-compatible `afterFirstTurn` hook that
+ * implements the two-strike nudge state machine described in the
+ * module doc. The hook is a no-op when:
+ *
+ *   - the signal already settled (agent called a terminal tool), or
+ *   - the caller reports pending external input (`hasPendingExternal`
+ *     returns true — e.g. an outstanding ask-user request).
+ *
+ * Otherwise it sends the nudge message via `harness.execute`, waits
+ * for microtasks to flush, and re-checks the same two conditions. If
+ * the agent still hasn't progressed, the hook fires `onStall` and
+ * resolves the signal with `buildStalledOutcome()`.
+ */
+export declare function createStallNudgeHook<TOutcome>(opts: StallNudgeOpts<TOutcome>): (ctx: AfterFirstTurnContext) => Promise<void>;

package/dist/runtime/durable/stall-nudge.js

@@ -0,0 +1,87 @@
+/**
+ * Two-strike stall-nudge helper composable with `runnableLoop`.
+ *
+ * A runner's first turn can end without settling the outcome signal
+ * and without the agent asking for external input — i.e. the agent
+ * stopped without calling either a terminal tool or an ask-user-style
+ * tool. That's a soft failure: rather than wait forever, we nudge the
+ * agent once to remind it of its options. If the second turn also
+ * ends in the same stalled shape we escalate: the caller-supplied
+ * `onStall` callback records the escalation (task pause, metrics,
+ * whatever the domain demands) and we settle the signal ourselves with
+ * a canonical "stalled" outcome so the parent unwinds cleanly.
+ *
+ * The helper factors the state machine out of the loop so callers can
+ * opt in per-runner. Task-specific concerns (how "pending external
+ * input" is detected, how escalation is recorded, what outcome
+ * represents a stalled failure) stay with the caller and flow in via
+ * the config.
+ */
+//#region Constants
+/**
+ * Default developer-role text sent when the agent finishes a turn
+ * without calling a terminal tool or an ask-user tool. Kept short and
+ * unambiguous — the agent should be reminded of its options without
+ * being lectured. Callers may override via `createNudgeMessage(text)`.
+ */
+export const DEFAULT_NUDGE_MESSAGE_TEXT = 'You finished a turn without calling a terminal tool or AskUserQuestion. If you need user input or instruction to continue, call AskUserQuestion now. Otherwise call your terminal tool to complete this phase.';
+//#endregion
+//#region Public API
+/**
+ * Build the canonical developer-role nudge message item. Callers who
+ * want a custom framing build their own `InputMessageItem`; this
+ * helper exists so the common case stays one line.
+ */
+export function createNudgeMessage(opts) {
+    return {
+        id: opts.id,
+        type: 'message',
+        role: 'developer',
+        status: 'completed',
+        content: [
+            {
+                type: 'input_text',
+                text: opts.text ?? DEFAULT_NUDGE_MESSAGE_TEXT,
+            },
+        ],
+    };
+}
+/**
+ * Build a `runnableLoop`-compatible `afterFirstTurn` hook that
+ * implements the two-strike nudge state machine described in the
+ * module doc. The hook is a no-op when:
+ *
+ *   - the signal already settled (agent called a terminal tool), or
+ *   - the caller reports pending external input (`hasPendingExternal`
+ *     returns true — e.g. an outstanding ask-user request).
+ *
+ * Otherwise it sends the nudge message via `harness.execute`, waits
+ * for microtasks to flush, and re-checks the same two conditions. If
+ * the agent still hasn't progressed, the hook fires `onStall` and
+ * resolves the signal with `buildStalledOutcome()`.
+ */
+export function createStallNudgeHook(opts) {
+    return async (ctx) => {
+        if (ctx.signalSettled()) {
+            return;
+        }
+        if (opts.hasPendingExternal()) {
+            return;
+        }
+        // First stall — send one nudge.
+        await opts.harness.execute(opts.nudgeMessage, {
+            threadId: opts.threadId,
+        });
+        await Promise.resolve();
+        if (ctx.signalSettled()) {
+            return;
+        }
+        if (opts.hasPendingExternal()) {
+            return;
+        }
+        // Second stall — escalate and settle.
+        await opts.onStall();
+        opts.signal.resolve(opts.buildStalledOutcome());
+    };
+}
+//#endregion

package/dist/runtime/in-memory-storage.js

@@ -1,4 +1,4 @@
-import { frameworkCast } from '../interpreter/framework-cast';
+import { frameworkCast } from '../util/framework-cast';
 //#region Public API
 /**
  * @public Process-local, Map-backed StorageAdapter.

package/dist/runtime/item-log-impl.d.ts

@@ -1,5 +1,5 @@
 import type { ItemSchemaRegistry } from '../schemas/item';
-import type { ItemLog } from '../types/context';
+import type { ItemLog } from '../types/context-parts/item-log';
 import type { Item } from '../types/items';
 export declare class ItemLogImpl implements ItemLog {
     private readonly itemSchemas;

package/dist/runtime/step-registry.d.ts

@@ -0,0 +1,42 @@
+import type { ContextMemory } from '../types/memory';
+import type { Step } from '../types/step';
+/** Registry-wide step type — stored at the widest generic parameters so
+ *  callers can register steps with narrower input/output types without
+ *  fighting variance. The public `Step` default already uses `unknown` for
+ *  the input and output parameters, matching this shape. */
+type RegisteredStep = Step<ContextMemory, unknown, unknown>;
+/**
+ * @public
+ * Registers a step so the subprocess adapter can look it up by id.
+ *
+ * Called automatically by the step builders when a `Step` is constructed.
+ * Policy: **latest registration wins**. Dispatch-and-lookup happen in the
+ * same tick, so the live entry is always the one the caller just built;
+ * cross-test pollution from bun's per-file process model (describe blocks
+ * rebuild the same step id) is not a safety concern here. Strict
+ * "reject duplicate id with a different body" detection + a test-side
+ * `clearRegistry` wiring is deferred — see the tracked follow-up task on
+ * the team's board (strict-registry-plus-test-clear).
+ */
+export declare function registerStep<TMemory, I, O>(step: Step<TMemory, I, O>): void;
+/**
+ * @public
+ * Looks up a registered step by id. Returns `null` when the id is not known
+ * — callers (e.g. the in-memory adapter's step dispatch path) translate the
+ * miss into a typed configuration error.
+ */
+export declare function lookupStep(id: string): RegisteredStep | null;
+/**
+ * @public
+ * Returns a read-only view over the registry. Primarily for tests and
+ * debugging; production callers should use `lookupStep`.
+ */
+export declare function getRegistry(): ReadonlyMap<string, RegisteredStep>;
+/**
+ * @public
+ * Clears the registry. Test-only helper — exported because several suites
+ * need a clean registry between describe blocks. Not part of the public API
+ * surface consumed by agent authors.
+ */
+export declare function clearRegistry(): void;
+export {};

package/dist/runtime/step-registry.js

@@ -0,0 +1,77 @@
+import { NoeticConfigError } from '../errors/noetic-config-error';
+import { setDefaultRegistrar } from '../types/step-registrar';
+import { frameworkCast } from '../util/framework-cast';
+//#endregion
+//#region Module state
+const registry = new Map();
+//#endregion
+//#region Public API
+/**
+ * @public
+ * Registers a step so the subprocess adapter can look it up by id.
+ *
+ * Called automatically by the step builders when a `Step` is constructed.
+ * Policy: **latest registration wins**. Dispatch-and-lookup happen in the
+ * same tick, so the live entry is always the one the caller just built;
+ * cross-test pollution from bun's per-file process model (describe blocks
+ * rebuild the same step id) is not a safety concern here. Strict
+ * "reject duplicate id with a different body" detection + a test-side
+ * `clearRegistry` wiring is deferred — see the tracked follow-up task on
+ * the team's board (strict-registry-plus-test-clear).
+ */
+export function registerStep(step) {
+    if (!step.id || step.id.trim() === '') {
+        throw new NoeticConfigError({
+            code: 'EMPTY_STEP_ID',
+            message: 'registerStep() requires a step with a non-empty id.',
+            hint: 'Set `id` on the step before constructing it.',
+        });
+    }
+    // `frameworkCast` is the approved single-point escape for generic variance:
+    // narrowing I/O from specific types to the registry's widened `unknown`
+    // shape is structurally safe at runtime because the registry only holds
+    // references and dispatches them through the same `execute()` pipeline.
+    const widened = frameworkCast(step);
+    registry.set(step.id, widened);
+}
+/**
+ * @public
+ * Looks up a registered step by id. Returns `null` when the id is not known
+ * — callers (e.g. the in-memory adapter's step dispatch path) translate the
+ * miss into a typed configuration error.
+ */
+export function lookupStep(id) {
+    return registry.get(id) ?? null;
+}
+/**
+ * @public
+ * Returns a read-only view over the registry. Primarily for tests and
+ * debugging; production callers should use `lookupStep`.
+ */
+export function getRegistry() {
+    return registry;
+}
+/**
+ * @public
+ * Clears the registry. Test-only helper — exported because several suites
+ * need a clean registry between describe blocks. Not part of the public API
+ * surface consumed by agent authors.
+ */
+export function clearRegistry() {
+    registry.clear();
+}
+//#endregion
+//#region Default-registrar installation
+/**
+ * Install this module's `registerStep` as the runtime default registrar.
+ * Executes on first import — which happens transitively from
+ * `agent-harness.ts` and from anywhere that imports `@noetic-tools/core`'s
+ * top-level barrel. Builders call `getDefaultRegistrar().register(step)`
+ * from `../types/step-registrar` and get this concrete implementation
+ * without depending on `core-runtime` themselves (fixes the
+ * `core-primitives → core-runtime` layer_direction violations).
+ */
+setDefaultRegistrar({
+    register: registerStep,
+});
+//#endregion

package/dist/schemas/workflow.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Zod schemas for JSON-serialisable workflow definitions.
+ *
+ * A `WorkflowDocument` is a portable, JSON-safe representation of a noetic
+ * step tree. It covers every step kind except `run` (which carries arbitrary
+ * closures). The hydrator in `builders/workflow-hydrator.ts` converts a
+ * validated document back into live `Step` objects via the existing builders.
+ */
+import { z } from 'zod';
+interface UntilAnyPredicate {
+    kind: 'any';
+    predicates: UntilPredicate[];
+}
+interface UntilAllPredicate {
+    kind: 'all';
+    predicates: UntilPredicate[];
+}
+/** @public Discriminated union of named until predicates usable in JSON workflows. */
+export type UntilPredicate = {
+    kind: 'maxSteps';
+    n: number;
+} | {
+    kind: 'maxCost';
+    usd: number;
+} | {
+    kind: 'maxDuration';
+    ms: number;
+} | {
+    kind: 'noToolCalls';
+} | {
+    kind: 'outputContains';
+    marker: string;
+} | {
+    kind: 'outputEquals';
+    sentinel: string;
+} | {
+    kind: 'converged';
+    threshold?: number;
+} | UntilAnyPredicate | UntilAllPredicate;
+/** @public Zod schema validating a named `until` predicate (including `any`/`all` combinators). */
+export declare const UntilPredicateSchema: z.ZodType<UntilPredicate>;
+/** @public ESM literal enum for merge strategies. */
+export declare const MergeStrategy: {
+    readonly Last: "last";
+    readonly First: "first";
+    readonly Concat: "concat";
+};
+/** @public Named merge strategy for fork nodes. */
+export type MergeStrategy = (typeof MergeStrategy)[keyof typeof MergeStrategy];
+/** @public Zod schema for the named merge strategy used by `fork` nodes. */
+export declare const MergeStrategySchema: z.ZodEnum<{
+    concat: "concat";
+    last: "last";
+    first: "first";
+}>;
+declare const ModelParamsSchema: z.ZodObject<{
+    temperature: z.ZodOptional<z.ZodNumber>;
+    topP: z.ZodOptional<z.ZodNumber>;
+    maxTokens: z.ZodOptional<z.ZodNumber>;
+    stopSequences: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+interface WorkflowNodeBase {
+    id: string;
+}
+export interface LlmWorkflowNode extends WorkflowNodeBase {
+    kind: 'llm';
+    model?: string;
+    instructions: string;
+    tools?: string[];
+    params?: z.infer<typeof ModelParamsSchema>;
+}
+export interface ToolWorkflowNode extends WorkflowNodeBase {
+    kind: 'tool';
+    toolName: string;
+    args?: Record<string, unknown>;
+}
+export interface BranchRoute {
+    match: string;
+    target: WorkflowNode;
+}
+export interface BranchWorkflowNode extends WorkflowNodeBase {
+    kind: 'branch';
+    routes: BranchRoute[];
+    default?: WorkflowNode;
+}
+export interface ForkWorkflowNode extends WorkflowNodeBase {
+    kind: 'fork';
+    mode: 'race' | 'all' | 'settle';
+    paths: WorkflowNode[];
+    merge?: MergeStrategy;
+    concurrency?: number;
+}
+export interface SpawnWorkflowNode extends WorkflowNodeBase {
+    kind: 'spawn';
+    child: WorkflowNode;
+    timeout?: number;
+}
+export interface ProvideWorkflowNode extends WorkflowNodeBase {
+    kind: 'provide';
+    child: WorkflowNode;
+    layers: string[];
+}
+export interface LoopWorkflowNode extends WorkflowNodeBase {
+    kind: 'loop';
+    body: WorkflowNode;
+    until: UntilPredicate;
+    maxIterations?: number;
+}
+export interface SequenceWorkflowNode extends WorkflowNodeBase {
+    kind: 'sequence';
+    steps: WorkflowNode[];
+}
+export interface EveryWorkflowNode extends WorkflowNodeBase {
+    kind: 'every';
+    step: WorkflowNode;
+    ms: number;
+    onError?: 'continue' | 'fail';
+}
+/** @public Discriminated union of all JSON-serialisable workflow node kinds. */
+export type WorkflowNode = LlmWorkflowNode | ToolWorkflowNode | BranchWorkflowNode | ForkWorkflowNode | SpawnWorkflowNode | ProvideWorkflowNode | LoopWorkflowNode | SequenceWorkflowNode | EveryWorkflowNode;
+/** @public Zod schema validating a single `WorkflowNode` (any of the 9 JSON-safe kinds). */
+export declare const WorkflowNodeSchema: z.ZodType<WorkflowNode>;
+/** @public Top-level envelope for a JSON workflow definition. */
+export interface WorkflowDocument {
+    version: 1;
+    root: WorkflowNode;
+}
+/** @public Zod schema validating a complete `WorkflowDocument`. */
+export declare const WorkflowDocumentSchema: z.ZodType<WorkflowDocument>;
+/** Validates a candidate workflow document. Throws `ZodError` on invalid input. */
+export declare function validateWorkflow(input: unknown): WorkflowDocument;
+/** Walks a workflow tree depth-first, yielding each node. */
+export declare function walkWorkflow(node: WorkflowNode): Iterable<WorkflowNode>;
+/**
+ * Returns the maximum depth of a workflow tree.
+ * Leaf nodes (`llm`, `tool`) have depth 0. Structural nodes add +1.
+ */
+export declare function workflowDepth(node: WorkflowNode): number;
+export {};

package/dist/schemas/workflow.js

@@ -0,0 +1,232 @@
+/**
+ * Zod schemas for JSON-serialisable workflow definitions.
+ *
+ * A `WorkflowDocument` is a portable, JSON-safe representation of a noetic
+ * step tree. It covers every step kind except `run` (which carries arbitrary
+ * closures). The hydrator in `builders/workflow-hydrator.ts` converts a
+ * validated document back into live `Step` objects via the existing builders.
+ */
+import { z } from 'zod';
+//#endregion
+//#region Until Predicate Schemas
+const MaxStepsPredicateSchema = z.object({
+    kind: z.literal('maxSteps'),
+    n: z.number().int().positive(),
+});
+const MaxCostPredicateSchema = z.object({
+    kind: z.literal('maxCost'),
+    usd: z.number().positive(),
+});
+const MaxDurationPredicateSchema = z.object({
+    kind: z.literal('maxDuration'),
+    ms: z.number().positive(),
+});
+const NoToolCallsPredicateSchema = z.object({
+    kind: z.literal('noToolCalls'),
+});
+const OutputContainsPredicateSchema = z.object({
+    kind: z.literal('outputContains'),
+    marker: z.string().min(1),
+});
+const OutputEqualsPredicateSchema = z.object({
+    kind: z.literal('outputEquals'),
+    sentinel: z.string().min(1),
+});
+const ConvergedPredicateSchema = z.object({
+    kind: z.literal('converged'),
+    threshold: z.number().min(0).max(1).optional(),
+});
+const UntilPredicateRef = z.lazy(() => UntilPredicateSchema);
+const AnyPredicateSchema = z.object({
+    kind: z.literal('any'),
+    predicates: z.array(UntilPredicateRef).min(1),
+});
+const AllPredicateSchema = z.object({
+    kind: z.literal('all'),
+    predicates: z.array(UntilPredicateRef).min(1),
+});
+/** @public Zod schema validating a named `until` predicate (including `any`/`all` combinators). */
+export const UntilPredicateSchema = z.union([
+    MaxStepsPredicateSchema,
+    MaxCostPredicateSchema,
+    MaxDurationPredicateSchema,
+    NoToolCallsPredicateSchema,
+    OutputContainsPredicateSchema,
+    OutputEqualsPredicateSchema,
+    ConvergedPredicateSchema,
+    AnyPredicateSchema,
+    AllPredicateSchema,
+]);
+//#endregion
+//#region Merge Strategy
+/** @public ESM literal enum for merge strategies. */
+export const MergeStrategy = {
+    Last: 'last',
+    First: 'first',
+    Concat: 'concat',
+};
+/** @public Zod schema for the named merge strategy used by `fork` nodes. */
+export const MergeStrategySchema = z.enum([
+    'last',
+    'first',
+    'concat',
+]);
+//#endregion
+//#region Model Params
+const ModelParamsSchema = z.object({
+    temperature: z.number().min(0).optional(),
+    topP: z.number().min(0).max(1).optional(),
+    maxTokens: z.number().int().positive().optional(),
+    stopSequences: z.array(z.string()).optional(),
+});
+//#endregion
+//#region Workflow Node Schema
+const WorkflowNodeRef = z.lazy(() => WorkflowNodeSchema);
+const SHARED_FIELDS = {
+    id: z.string().min(1),
+};
+const LlmNodeSchema = z.object({
+    kind: z.literal('llm'),
+    ...SHARED_FIELDS,
+    model: z.string().optional(),
+    instructions: z.string(),
+    tools: z.array(z.string()).optional(),
+    params: ModelParamsSchema.optional(),
+});
+const ToolNodeSchema = z.object({
+    kind: z.literal('tool'),
+    ...SHARED_FIELDS,
+    toolName: z.string().min(1),
+    args: z.record(z.string(), z.unknown()).optional(),
+});
+const BranchRouteSchema = z.object({
+    match: z.string().min(1),
+    target: z.lazy(() => WorkflowNodeSchema),
+});
+const BranchNodeSchema = z.object({
+    kind: z.literal('branch'),
+    ...SHARED_FIELDS,
+    routes: z.array(BranchRouteSchema).min(1),
+    default: WorkflowNodeRef.optional(),
+});
+const ForkNodeSchema = z.object({
+    kind: z.literal('fork'),
+    ...SHARED_FIELDS,
+    mode: z.enum([
+        'race',
+        'all',
+        'settle',
+    ]),
+    paths: z.array(WorkflowNodeRef).min(1),
+    merge: MergeStrategySchema.optional(),
+    concurrency: z.number().int().positive().optional(),
+});
+const SpawnNodeSchema = z.object({
+    kind: z.literal('spawn'),
+    ...SHARED_FIELDS,
+    child: WorkflowNodeRef,
+    timeout: z.number().positive().optional(),
+});
+const ProvideNodeSchema = z.object({
+    kind: z.literal('provide'),
+    ...SHARED_FIELDS,
+    child: WorkflowNodeRef,
+    layers: z.array(z.string().min(1)).min(1),
+});
+const LoopNodeSchema = z.object({
+    kind: z.literal('loop'),
+    ...SHARED_FIELDS,
+    body: WorkflowNodeRef,
+    until: UntilPredicateSchema,
+    maxIterations: z.number().int().positive().optional(),
+});
+const SequenceNodeSchema = z.object({
+    kind: z.literal('sequence'),
+    ...SHARED_FIELDS,
+    steps: z.array(WorkflowNodeRef).min(1),
+});
+const EveryNodeSchema = z.object({
+    kind: z.literal('every'),
+    ...SHARED_FIELDS,
+    step: WorkflowNodeRef,
+    ms: z.number().nonnegative(),
+    onError: z
+        .enum([
+        'continue',
+        'fail',
+    ])
+        .optional(),
+});
+/** @public Zod schema validating a single `WorkflowNode` (any of the 9 JSON-safe kinds). */
+export const WorkflowNodeSchema = z.discriminatedUnion('kind', [
+    LlmNodeSchema,
+    ToolNodeSchema,
+    BranchNodeSchema,
+    ForkNodeSchema,
+    SpawnNodeSchema,
+    ProvideNodeSchema,
+    LoopNodeSchema,
+    SequenceNodeSchema,
+    EveryNodeSchema,
+]);
+/** @public Zod schema validating a complete `WorkflowDocument`. */
+export const WorkflowDocumentSchema = z.object({
+    version: z.literal(1),
+    root: WorkflowNodeSchema,
+});
+//#endregion
+//#region Helpers
+/** Returns the direct child nodes of a workflow node. Leaf nodes return an empty array. */
+function childNodes(node) {
+    switch (node.kind) {
+        case 'sequence':
+            return node.steps;
+        case 'fork':
+            return node.paths;
+        case 'spawn':
+        case 'provide':
+            return [
+                node.child,
+            ];
+        case 'loop':
+            return [
+                node.body,
+            ];
+        case 'every':
+            return [
+                node.step,
+            ];
+        case 'branch': {
+            const children = node.routes.map((r) => r.target);
+            if (node.default) {
+                children.push(node.default);
+            }
+            return children;
+        }
+        default:
+            return [];
+    }
+}
+/** Validates a candidate workflow document. Throws `ZodError` on invalid input. */
+export function validateWorkflow(input) {
+    return WorkflowDocumentSchema.parse(input);
+}
+/** Walks a workflow tree depth-first, yielding each node. */
+export function* walkWorkflow(node) {
+    yield node;
+    for (const child of childNodes(node)) {
+        yield* walkWorkflow(child);
+    }
+}
+/**
+ * Returns the maximum depth of a workflow tree.
+ * Leaf nodes (`llm`, `tool`) have depth 0. Structural nodes add +1.
+ */
+export function workflowDepth(node) {
+    const children = childNodes(node);
+    if (children.length === 0) {
+        return 0;
+    }
+    return 1 + Math.max(0, ...children.map(workflowDepth));
+}
+//#endregion