@noetic-tools/core 2.0.0 → 2.2.0

package/dist/interpreter/execute-action.js

@@ -1,10 +1,11 @@
 /**
  * Action step handlers: run, llm, spawn, provide, tool.
  */
-import { createMessage, estimateTokens, extractAssistantText, frameworkCast, isNoeticError, NoeticConfigError, NoeticErrorImpl, } from '@noetic-tools/types';
+import { createMessage, estimateTokens, extractAssistantText, frameworkCast, isNoeticError, isOutputCodec, NoeticConfigError, NoeticErrorImpl, } from '@noetic-tools/types';
 import { ZodError } from 'zod';
-import { allocateBudgets, assembleView, buildToolExecutionContext, ContextImpl, commitLayerUsage, computeLayerUsage, contextToExecCtx, DEFAULT_PROJECTION, defaultItemSchemaRegistry, emitFrameworkEvent, getBroadcaster, resolveLayerTools, returnLayers, snapshotCwdState, spawnLayers, } from './action-deps.js';
-import { SteeringAction } from './action-types.js';
+import { emitToolUi } from '../runtime/tool-ui.js';
+import { allocateBudgets, assembleView, buildToolExecutionContext, ContextImpl, commitLayerUsage, computeLayerUsage, contextToExecCtx, DEFAULT_PROJECTION, defaultItemSchemaRegistry, emitFrameworkEvent, getBroadcaster, resolveLayerTools, returnLayers, shouldEmit, snapshotCwdState, spawnLayers, } from './action-deps.js';
+import { isServerToolSpec, SteeringAction } from './action-types.js';
 import { cloneWithGuard } from './clone-guard.js';
 import { collectAllTools, deduplicateTools } from './collect-tools.js';
 import { trackUsage } from './message-helpers.js';
@@ -164,6 +165,97 @@ async function runInputPipeline({ ctx, layers, input, }) {
     }
     return rerenderRequests;
 }
+/**
+ * Classify a step's `output` into the JSON-schema vs streaming-codec modes.
+ *
+ * An `OutputCodec` (e.g. OpenUI Lang) carries its own system-prompt fragment
+ * and is NOT a JSON schema — its `instructions` fold into the system prompt and
+ * it is kept off `outputSchema` (which drives JSON-schema formatting).
+ */
+function resolveOutputMode(output, baseInstructions) {
+    // A generic type predicate does not reliably narrow a `ZodType<O> |
+    // OutputCodec<O>` union through a free type parameter, so bridge the two
+    // branches with the sanctioned framework cast — `isOutputCodec` guarantees
+    // the discriminant at runtime.
+    const isCodec = isOutputCodec(output);
+    const outputCodec = isCodec ? frameworkCast(output) : undefined;
+    const outputSchema = isCodec ? undefined : frameworkCast(output);
+    const codecInstructions = outputCodec?.instructions;
+    const resolvedInstructions = codecInstructions !== undefined
+        ? [
+            baseInstructions,
+            codecInstructions,
+        ]
+            .filter((s) => s !== undefined)
+            .join('\n\n')
+        : baseInstructions;
+    return {
+        outputCodec,
+        outputSchema,
+        resolvedInstructions,
+    };
+}
+/**
+ * Drive an `OutputCodec` with the finished assistant text: emit its `openui.*`
+ * framework events (gated by `step.emit`) and return the codec's typed value.
+ * True per-delta streaming lives in the model caller; here the statements are
+ * delivered at turn finalization, which the transport still forwards.
+ */
+function finalizeCodecOutput(codec, lastText, ctx, emit) {
+    const session = codec.start();
+    const broadcaster = getBroadcaster(ctx);
+    const agentName = ctx.harness.config.name;
+    session.push(lastText, (eventType, data) => {
+        if (shouldEmit(emit, eventType, data)) {
+            emitFrameworkEvent({
+                broadcaster,
+                agentName,
+                eventType,
+                data,
+            });
+        }
+    });
+    return session.finish(lastText);
+}
+/** JSON-parse + Zod-validate the assistant text, raising `llm_parse_error`. */
+function parseSchemaOutput(schema, lastText, stepId) {
+    try {
+        return schema.parse(JSON.parse(lastText));
+    }
+    catch (e) {
+        if (e instanceof SyntaxError || e instanceof ZodError) {
+            throw new NoeticErrorImpl({
+                kind: 'llm_parse_error',
+                stepId,
+                raw: lastText,
+                schema,
+                zodError: e instanceof ZodError
+                    ? e
+                    : new ZodError([
+                        {
+                            code: 'custom',
+                            message: `Invalid JSON: ${e.message}`,
+                            path: [],
+                        },
+                    ]),
+            });
+        }
+        throw e;
+    }
+}
+/**
+ * Turn the finished assistant text into the step's typed output: a streaming
+ * codec, a Zod schema, or raw text passthrough.
+ */
+function finalizeStepOutput(params) {
+    if (params.outputCodec) {
+        return finalizeCodecOutput(params.outputCodec, params.lastText, params.ctx, params.emit);
+    }
+    if (params.outputSchema) {
+        return parseSchemaOutput(params.outputSchema, params.lastText, params.stepId);
+    }
+    return frameworkCast(params.lastText);
+}
 export async function executeLLM(step, input, ctx, layers) {
     const baseCtx = frameworkCast(ctx);
     const hasLayers = layers !== undefined && layers.length > 0;
@@ -178,8 +270,29 @@ export async function executeLLM(step, input, ctx, layers) {
             hint: "Ensure `model` (or your `(ctx) => string` getter) returns a non-empty identifier, e.g. 'anthropic/claude-sonnet-4-20250514'.",
         });
     }
-    const resolvedInstructions = await resolveLazy(step.instructions, ctx);
+    const baseInstructions = await resolveLazy(step.instructions, ctx);
+    const { outputCodec, outputSchema, resolvedInstructions } = resolveOutputMode(step.output, baseInstructions);
     const resolvedStepTools = await resolveLazy(step.tools, ctx);
+    // `step.tools` is heterogeneous: client `Tool`s plus inline OpenRouter
+    // server-tool specs (web search/fetch). Partition them — client tools flow
+    // through the unified-tool / allowedToolNames / steering machinery as before;
+    // server-tool specs bypass it entirely and are stamped onto the model request
+    // (`_serverTools`) for the model caller to wrap via the SDK's `serverTool()`.
+    // `undefined` (unrestricted) is preserved as-is; only a present array is
+    // partitioned so the `[] = opt-out` semantics of step.tools stay intact.
+    let clientStepTools;
+    const serverToolSpecs = [];
+    if (resolvedStepTools !== undefined) {
+        clientStepTools = [];
+        for (const entry of resolvedStepTools) {
+            if (isServerToolSpec(entry)) {
+                serverToolSpecs.push(entry);
+            }
+            else {
+                clientStepTools.push(entry);
+            }
+        }
+    }
     // Append user input — through layer pipeline if layers exist, otherwise direct.
     // The append pipeline may request a context re-render (e.g. a layer that
     // expanded an input reference into new content); applied after recall below.
@@ -196,7 +309,7 @@ export async function executeLLM(step, input, ctx, layers) {
             baseCtx.itemLog.append(createMessage(input, 'user'));
         }
     }
-    const { tools: resolvedTools, allowedToolNames } = resolveToolsAndRestrictions(resolvedStepTools, layers, baseCtx);
+    const { tools: resolvedTools, allowedToolNames } = resolveToolsAndRestrictions(clientStepTools, layers, baseCtx);
     // Resolve the projection policy (step override > harness default > fallback)
     // and split the context budget across layers via allocateBudgets.
     const policy = step.projection ?? baseCtx.harness.config.projection ?? DEFAULT_PROJECTION;
@@ -281,6 +394,7 @@ export async function executeLLM(step, input, ctx, layers) {
                         ...projectedHistoryItems,
                     ];
         }
+        const _serverTools = serverToolSpecs.length > 0 ? serverToolSpecs : undefined;
         const request = resolvedTools
             ? {
                 model: resolvedModel,
@@ -288,8 +402,9 @@ export async function executeLLM(step, input, ctx, layers) {
                 instructions: resolvedInstructions,
                 tools: resolvedTools,
                 params: step.params,
-                outputSchema: step.output,
+                outputSchema: outputSchema,
                 emit: step.emit,
+                _serverTools,
                 ctx: baseCtx,
                 layers,
                 allowedToolNames,
@@ -301,8 +416,9 @@ export async function executeLLM(step, input, ctx, layers) {
                 items: assembledItems,
                 instructions: resolvedInstructions,
                 params: step.params,
-                outputSchema: step.output,
+                outputSchema: outputSchema,
                 emit: step.emit,
+                _serverTools,
                 nodeId: step.id,
                 parentSpan: baseCtx.span,
             };
@@ -353,33 +469,14 @@ export async function executeLLM(step, input, ctx, layers) {
             await baseCtx.harness.storeLayers(layers, response, baseCtx);
         }
         const lastText = extractAssistantText(response.items);
-        if (step.output) {
-            try {
-                const parsed = JSON.parse(lastText);
-                return step.output.parse(parsed);
-            }
-            catch (e) {
-                if (e instanceof SyntaxError || e instanceof ZodError) {
-                    throw new NoeticErrorImpl({
-                        kind: 'llm_parse_error',
-                        stepId: step.id,
-                        raw: lastText,
-                        schema: step.output,
-                        zodError: e instanceof ZodError
-                            ? e
-                            : new ZodError([
-                                {
-                                    code: 'custom',
-                                    message: `Invalid JSON: ${e.message}`,
-                                    path: [],
-                                },
-                            ]),
-                    });
-                }
-                throw e;
-            }
-        }
-        return frameworkCast(lastText);
+        return finalizeStepOutput({
+            stepId: step.id,
+            emit: step.emit,
+            outputCodec,
+            outputSchema,
+            lastText,
+            ctx: baseCtx,
+        });
     }
     // Safety net: the loop above always returns or throws within the body.
     // This throw is unreachable but protects against future refactors that
@@ -587,21 +684,32 @@ function isAsyncGenerator(value) {
 async function consumeToolGenerator(params) {
     const broadcaster = getBroadcaster(params.ctx);
     const agentName = params.ctx.harness.config.name;
+    const events = [];
     while (true) {
         const next = await params.generator.next();
         if (next.done) {
             return next.value;
         }
+        events.push(next.value);
         emitFrameworkEvent({
             broadcaster,
             agentName,
             eventType: 'tool_progress',
             data: {
                 stepId: params.stepId,
-                toolName: params.toolName,
+                toolName: params.tool.name,
                 event: next.value,
             },
         });
+        // A direct `step.tool` has no model call id — the step id keys its region.
+        emitToolUi({
+            ctx: params.ctx,
+            tool: params.tool,
+            callId: params.stepId,
+            phase: 'progress',
+            args: params.args,
+            events,
+        });
     }
 }
 export async function executeTool(step, input, ctx, harness, layers) {
@@ -625,20 +733,44 @@ export async function executeTool(step, input, ctx, harness, layers) {
             });
         }
     }
+    emitToolUi({
+        ctx: baseCtx,
+        tool: step.tool,
+        callId: step.id,
+        phase: 'call',
+        args: parseResult.data,
+    });
     try {
         const toolCtx = buildToolExecutionContext(baseCtx, harness);
-        const result = step.tool.execute(parseResult.data, toolCtx);
-        if (isAsyncGenerator(result)) {
-            return frameworkCast(await consumeToolGenerator({
-                generator: result,
+        const execResult = step.tool.execute(parseResult.data, toolCtx);
+        const result = isAsyncGenerator(execResult)
+            ? await consumeToolGenerator({
+                generator: execResult,
                 stepId: step.id,
-                toolName: step.tool.name,
+                tool: step.tool,
                 ctx: baseCtx,
-            }));
-        }
-        return frameworkCast(await result);
+                args: parseResult.data,
+            })
+            : await execResult;
+        emitToolUi({
+            ctx: baseCtx,
+            tool: step.tool,
+            callId: step.id,
+            phase: 'result',
+            args: parseResult.data,
+            output: result,
+        });
+        return frameworkCast(result);
     }
     catch (e) {
+        emitToolUi({
+            ctx: baseCtx,
+            tool: step.tool,
+            callId: step.id,
+            phase: 'error',
+            args: parseResult.data,
+            error: e,
+        });
         if (e instanceof NoeticErrorImpl) {
             throw e;
         }

package/dist/runtime/tool-ui.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Tool-authored UI fragment emission.
+ *
+ * When a tool declares a `ui` block (`ToolUiDeclaration`), the runtime runs its
+ * render functions at the call / progress / result / error lifecycle points and
+ * forwards each returned `UiFragment` as an `openui.fragment` framework event
+ * (namespaced `${agentName}:openui.fragment`). The framework never interprets
+ * the fragment source — a UI surface (memory layer + transport) composes it.
+ *
+ * The `ui` methods are declared bivariantly on `ToolUiDeclaration`, so the
+ * erased `Tool` handle the runtime holds can call them with runtime values.
+ */
+import type { Context, Tool } from '@noetic-tools/types';
+/** The tool-UI lifecycle point being rendered. */
+export type ToolUiPhase = 'call' | 'progress' | 'result' | 'error';
+/** Parameters for {@link emitToolUi}. */
+export interface EmitToolUiParams {
+    ctx: Context;
+    tool: Tool;
+    callId: string;
+    phase: ToolUiPhase;
+    /** Parsed tool args (partial at `call` time). */
+    args: unknown;
+    /** Events seen so far — for `progress`. */
+    events?: unknown[];
+    /** The tool's return value — for `result`. */
+    output?: unknown;
+    /** The thrown error — for `error`. */
+    error?: unknown;
+}
+/**
+ * Render the tool's UI fragment for one lifecycle phase and, when it produces
+ * one, emit it as an `openui.fragment` framework event. No-op when the tool
+ * declares no `ui` for that phase.
+ */
+export declare function emitToolUi(params: EmitToolUiParams): void;

package/dist/runtime/tool-ui.js

@@ -0,0 +1,57 @@
+/**
+ * Tool-authored UI fragment emission.
+ *
+ * When a tool declares a `ui` block (`ToolUiDeclaration`), the runtime runs its
+ * render functions at the call / progress / result / error lifecycle points and
+ * forwards each returned `UiFragment` as an `openui.fragment` framework event
+ * (namespaced `${agentName}:openui.fragment`). The framework never interprets
+ * the fragment source — a UI surface (memory layer + transport) composes it.
+ *
+ * The `ui` methods are declared bivariantly on `ToolUiDeclaration`, so the
+ * erased `Tool` handle the runtime holds can call them with runtime values.
+ */
+import { frameworkCast } from '@noetic-tools/types';
+import { emitFrameworkEvent, getBroadcaster } from './broadcaster-utils.js';
+const OPENUI_FRAGMENT_EVENT = 'openui.fragment';
+function renderFragment(params) {
+    const ui = params.tool.ui;
+    if (!ui) {
+        return null;
+    }
+    // The `ui` methods are typed against the tool's own I/O schemas, erased to
+    // `ZodTypeAny` on the `Tool` handle the runtime holds. frameworkCast bridges
+    // the runtime values (`unknown`) to those erased parameter types.
+    const args = frameworkCast(params.args);
+    const output = frameworkCast(params.output);
+    switch (params.phase) {
+        case 'call':
+            return ui.call ? ui.call(args) : null;
+        case 'progress':
+            return ui.progress ? ui.progress(params.events ?? []) : null;
+        case 'result':
+            return ui.result ? ui.result(output, args) : null;
+        case 'error':
+            return ui.error ? ui.error(params.error, args) : null;
+    }
+}
+/**
+ * Render the tool's UI fragment for one lifecycle phase and, when it produces
+ * one, emit it as an `openui.fragment` framework event. No-op when the tool
+ * declares no `ui` for that phase.
+ */
+export function emitToolUi(params) {
+    const fragment = renderFragment(params);
+    if (fragment === null) {
+        return;
+    }
+    emitFrameworkEvent({
+        broadcaster: getBroadcaster(params.ctx),
+        agentName: params.ctx.harness.config.name,
+        eventType: OPENUI_FRAGMENT_EVENT,
+        data: {
+            callId: params.callId,
+            dialect: fragment.dialect,
+            source: fragment.source,
+        },
+    });
+}

package/dist/schemas/workflow.d.ts

@@ -2,9 +2,11 @@
  * 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.
+ * step tree. It covers every step kind. The `run` node carries its body as a
+ * code STRING (not an in-process closure) dispatched through a subprocess
+ * adapter, keeping the document JSON-safe. The hydrator in
+ * `builders/workflow-hydrator.ts` converts a validated document back into live
+ * `Step` objects via the existing builders.
  */
 import type { SubHarnessKind } from '@noetic-tools/types';
 import { z } from 'zod';
@@ -60,6 +62,35 @@ declare const ModelParamsSchema: z.ZodObject<{
     maxTokens: z.ZodOptional<z.ZodNumber>;
     stopSequences: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
+/**
+ * A uniform tool entry on an `llm` node. Every entry is an object keyed by
+ * `type`:
+ *   - A CLIENT tool is `{ type: "<registered-tool-name>" }`. The hydrator
+ *     resolves `type` against the tool registry; `parameters` (if present) is
+ *     ignored — client tools receive their call args from the model at runtime.
+ *   - A SERVER tool is `{ type: "openrouter:web_search" | "openrouter:web_fetch",
+ *     parameters?: {...} }`. The provider executes it; `parameters` keys are
+ *     camelCase (e.g. `maxResults`, `searchContextSize`) — the SDK re-serialises
+ *     them and silently drops unknown keys.
+ *
+ * Server vs client is decided by the `type` value (a reserved `openrouter:*`
+ * server-tool literal vs an arbitrary tool name), not by the entry's shape.
+ */
+declare const LlmToolEntrySchema: z.ZodObject<{
+    type: z.ZodString;
+    parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+/** Retry policy for a `run` node, mirroring `RetryPolicy` in `@noetic-tools/types`. */
+declare const RetryPolicySchema: z.ZodObject<{
+    maxAttempts: z.ZodNumber;
+    backoff: z.ZodEnum<{
+        fixed: "fixed";
+        linear: "linear";
+        exponential: "exponential";
+    }>;
+    initialDelay: z.ZodNumber;
+    maxDelay: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
 declare const HarnessSettingsSchema: z.ZodObject<{
     model: z.ZodOptional<z.ZodString>;
     permissionMode: z.ZodOptional<z.ZodEnum<{
@@ -83,18 +114,57 @@ declare const HarnessSessionPolicySchema: z.ZodObject<{
 interface WorkflowNodeBase {
     id: string;
 }
+/**
+ * A reference to a streaming `OutputCodec` for an `llm` node's structured
+ * output. The hydrator resolves `library` from `HydrationContext.uiLibraries`
+ * to a live codec (e.g. `openUi(myLibrary)` from `@noetic-tools/openui`), the
+ * same registry-resolution pattern sub-harness nodes use for adapters. Kept a
+ * *reference* because a codec is a runtime object, not JSON-expressible.
+ */
+export interface OutputCodecRef {
+    /** The codec dialect. Only `'openui'` is defined today. */
+    codec: 'openui';
+    /** Registry key resolved from `HydrationContext.uiLibraries`. */
+    library: string;
+}
 export interface LlmWorkflowNode extends WorkflowNodeBase {
     kind: 'llm';
     model?: string;
     instructions: string;
-    tools?: string[];
+    /**
+     * Tool entries. Every entry is an object `{ type, parameters? }`. A CLIENT
+     * tool is `{ type: "<registered-tool-name>" }` (resolved from the registry);
+     * a SERVER tool is `{ type: "openrouter:web_search" | "openrouter:web_fetch",
+     * parameters?: {...} }` (executed by the provider). Client vs server is
+     * decided by the `type` value.
+     */
+    tools?: z.infer<typeof LlmToolEntrySchema>[];
     params?: z.infer<typeof ModelParamsSchema>;
+    /** Streaming output-codec reference, resolved from `HydrationContext.uiLibraries`. */
+    output?: OutputCodecRef;
 }
 export interface ToolWorkflowNode extends WorkflowNodeBase {
     kind: 'tool';
     toolName: string;
     args?: Record<string, unknown>;
 }
+/**
+ * A node that runs a serialised code body. Unlike the programmatic `step.run`
+ * (which carries a closure), the JSON form carries `execute` as a code STRING.
+ * The code is never eval'd in-process (Cloudflare Workers forbid eval); it is
+ * dispatched through a subprocess adapter (`ctx.subprocess`, or a named adapter
+ * resolved by ref). Execution therefore requires a subprocess adapter capable
+ * of running the code and returning its stdout.
+ */
+export interface RunWorkflowNode extends WorkflowNodeBase {
+    kind: 'run';
+    /** Source code executed in the subprocess. Receives the step input on stdin. */
+    execute: string;
+    /** Optional retry policy applied to the step. */
+    retry?: z.infer<typeof RetryPolicySchema>;
+    /** Named subprocess adapter ref; defaults to `ctx.subprocess` when omitted. */
+    subprocess?: string;
+}
 export interface BranchRoute {
     match: string;
     target: WorkflowNode;
@@ -107,7 +177,22 @@ export interface BranchWorkflowNode extends WorkflowNodeBase {
 export interface ForkWorkflowNode extends WorkflowNodeBase {
     kind: 'fork';
     mode: 'race' | 'all' | 'settle';
-    paths: WorkflowNode[];
+    /**
+     * Static fan-out: one child per entry. Mutually exclusive with `each` —
+     * supply exactly one.
+     */
+    paths?: WorkflowNode[];
+    /**
+     * Dynamic fan-out: instantiate this body template once per item of a
+     * runtime-produced array (data-dependent N). Mutually exclusive with `paths`.
+     */
+    each?: WorkflowNode;
+    /**
+     * Selector key into the fork input (parsed as JSON) locating the array to
+     * fan out over. When omitted, the input string itself is parsed as a JSON
+     * array. Only meaningful with `each`.
+     */
+    over?: string;
     merge?: MergeStrategy;
     concurrency?: number;
 }
@@ -150,7 +235,7 @@ export interface SubHarnessWorkflowNode extends WorkflowNodeBase {
     session?: z.infer<typeof HarnessSessionPolicySchema>;
 }
 /** @public Discriminated union of all JSON-serialisable workflow node kinds. */
-export type WorkflowNode = LlmWorkflowNode | ToolWorkflowNode | BranchWorkflowNode | ForkWorkflowNode | SpawnWorkflowNode | ProvideWorkflowNode | LoopWorkflowNode | SequenceWorkflowNode | EveryWorkflowNode | SubHarnessWorkflowNode;
+export type WorkflowNode = LlmWorkflowNode | ToolWorkflowNode | RunWorkflowNode | BranchWorkflowNode | ForkWorkflowNode | SpawnWorkflowNode | ProvideWorkflowNode | LoopWorkflowNode | SequenceWorkflowNode | EveryWorkflowNode | SubHarnessWorkflowNode;
 /** @public Zod schema validating a single `WorkflowNode` (any JSON-safe kind). */
 export declare const WorkflowNodeSchema: z.ZodType<WorkflowNode>;
 /** @public Top-level envelope for a JSON workflow definition. */

package/dist/schemas/workflow.js

@@ -2,9 +2,11 @@
  * 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.
+ * step tree. It covers every step kind. The `run` node carries its body as a
+ * code STRING (not an in-process closure) dispatched through a subprocess
+ * adapter, keeping the document JSON-safe. 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
@@ -85,6 +87,39 @@ const ModelParamsSchema = z.object({
     stopSequences: z.array(z.string()).optional(),
 });
 //#endregion
+//#region Tool Entries
+/**
+ * A uniform tool entry on an `llm` node. Every entry is an object keyed by
+ * `type`:
+ *   - A CLIENT tool is `{ type: "<registered-tool-name>" }`. The hydrator
+ *     resolves `type` against the tool registry; `parameters` (if present) is
+ *     ignored — client tools receive their call args from the model at runtime.
+ *   - A SERVER tool is `{ type: "openrouter:web_search" | "openrouter:web_fetch",
+ *     parameters?: {...} }`. The provider executes it; `parameters` keys are
+ *     camelCase (e.g. `maxResults`, `searchContextSize`) — the SDK re-serialises
+ *     them and silently drops unknown keys.
+ *
+ * Server vs client is decided by the `type` value (a reserved `openrouter:*`
+ * server-tool literal vs an arbitrary tool name), not by the entry's shape.
+ */
+const LlmToolEntrySchema = z.object({
+    type: z.string().min(1),
+    parameters: z.record(z.string(), z.unknown()).optional(),
+});
+//#endregion
+//#region Retry Policy
+/** Retry policy for a `run` node, mirroring `RetryPolicy` in `@noetic-tools/types`. */
+const RetryPolicySchema = z.object({
+    maxAttempts: z.number().int().positive(),
+    backoff: z.enum([
+        'fixed',
+        'linear',
+        'exponential',
+    ]),
+    initialDelay: z.number().nonnegative(),
+    maxDelay: z.number().nonnegative().optional(),
+});
+//#endregion
 //#region SubHarness Settings
 const HarnessSettingsSchema = z.object({
     model: z.string().optional(),
@@ -116,13 +151,18 @@ const WorkflowNodeRef = z.lazy(() => WorkflowNodeSchema);
 const SHARED_FIELDS = {
     id: z.string().min(1),
 };
+const OutputCodecRefSchema = z.object({
+    codec: z.literal('openui'),
+    library: 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(),
+    tools: z.array(LlmToolEntrySchema).optional(),
     params: ModelParamsSchema.optional(),
+    output: OutputCodecRefSchema.optional(),
 });
 const ToolNodeSchema = z.object({
     kind: z.literal('tool'),
@@ -130,6 +170,13 @@ const ToolNodeSchema = z.object({
     toolName: z.string().min(1),
     args: z.record(z.string(), z.unknown()).optional(),
 });
+const RunNodeSchema = z.object({
+    kind: z.literal('run'),
+    ...SHARED_FIELDS,
+    execute: z.string().min(1),
+    retry: RetryPolicySchema.optional(),
+    subprocess: z.string().min(1).optional(),
+});
 const BranchRouteSchema = z.object({
     match: z.string().min(1),
     target: z.lazy(() => WorkflowNodeSchema),
@@ -140,7 +187,8 @@ const BranchNodeSchema = z.object({
     routes: z.array(BranchRouteSchema).min(1),
     default: WorkflowNodeRef.optional(),
 });
-const ForkNodeSchema = z.object({
+const ForkNodeSchema = z
+    .object({
     kind: z.literal('fork'),
     ...SHARED_FIELDS,
     mode: z.enum([
@@ -148,9 +196,14 @@ const ForkNodeSchema = z.object({
         'all',
         'settle',
     ]),
-    paths: z.array(WorkflowNodeRef).min(1),
+    paths: z.array(WorkflowNodeRef).min(1).optional(),
+    each: WorkflowNodeRef.optional(),
+    over: z.string().min(1).optional(),
     merge: MergeStrategySchema.optional(),
     concurrency: z.number().int().positive().optional(),
+})
+    .refine((node) => (node.paths === undefined) !== (node.each === undefined), {
+    message: "fork node requires exactly one of 'paths' (static) or 'each' (dynamic).",
 });
 const SpawnNodeSchema = z.object({
     kind: z.literal('spawn'),
@@ -208,6 +261,7 @@ export const WorkflowNodeSchema = z
     .discriminatedUnion('kind', [
     LlmNodeSchema,
     ToolNodeSchema,
+    RunNodeSchema,
     BranchNodeSchema,
     ForkNodeSchema,
     SpawnNodeSchema,
@@ -243,7 +297,12 @@ function childNodes(node) {
         case 'sequence':
             return node.steps;
         case 'fork':
-            return node.paths;
+            if (node.each) {
+                return [
+                    node.each,
+                ];
+            }
+            return node.paths ?? [];
         case 'spawn':
         case 'provide':
             return [