@noetic-tools/core 2.0.0 → 2.1.0

package/dist/builders/step-builders.d.ts

@@ -1,5 +1,5 @@
 import type { ContextMemory } from '@noetic-tools/memory';
-import type { Context, Lazy, ModelParams, RetryPolicy, StepLLM, StepRun, StepSubHarness, StepTool, SubHarness, SubHarnessSessionPolicy, SubHarnessSettings, SubprocessAdapter, Tool } from '@noetic-tools/types';
+import type { Context, Lazy, ModelParams, RetryPolicy, ServerToolSpec, StepLLM, StepRun, StepSubHarness, StepTool, SubHarness, SubHarnessSessionPolicy, SubHarnessSettings, SubprocessAdapter, Tool } from '@noetic-tools/types';
 import type { ZodType } from 'zod';
 interface StepRunOpts<TMemory, I, O> {
     id: string;
@@ -18,8 +18,12 @@ interface StepLLMOpts<TMemory, O> {
     model: Lazy<string, TMemory>;
     /** Optional instructions; eager string or `(ctx) => string | undefined` getter. */
     instructions?: Lazy<string | undefined, TMemory>;
-    /** Optional tools; eager array or `(ctx) => Tool[] | undefined` getter. */
-    tools?: Lazy<Tool[] | undefined, TMemory>;
+    /**
+     * Optional tools; eager array or `(ctx) => (...)[] | undefined` getter. Each
+     * entry is either a client `Tool` or an inline `ServerToolSpec` (an OpenRouter
+     * server tool the provider executes, e.g. web search/fetch).
+     */
+    tools?: Lazy<(Tool | ServerToolSpec)[] | undefined, TMemory>;
     output?: ZodType<O>;
     params?: ModelParams;
     emit?: boolean | ((eventType: string, data: Record<string, unknown>) => boolean);

package/dist/builders/workflow-hydrator.d.ts

@@ -6,7 +6,7 @@
  * ones — they register in the step registry, carry retry policies, etc.
  */
 import type { ContextMemory, MemoryLayer } from '@noetic-tools/memory';
-import type { ExecuteStepFn, Step, SubHarness, SubHarnessKind, Tool } from '@noetic-tools/types';
+import type { ExecuteStepFn, Step, SubHarness, SubHarnessKind, SubprocessAdapter, Tool } from '@noetic-tools/types';
 import type { WorkflowDocument, WorkflowNode } from '../schemas/workflow.js';
 /** @public Context required to hydrate a JSON workflow into live steps. */
 export interface HydrationContext {
@@ -15,6 +15,12 @@ export interface HydrationContext {
     layers?: ReadonlyMap<string, MemoryLayer>;
     /** SubHarness adapters keyed by harness id, resolving `claude-code`/`codex`/… nodes. */
     subHarnesses?: ReadonlyMap<SubHarnessKind, SubHarness>;
+    /**
+     * Resolves a named subprocess adapter ref declared on a `run` node's
+     * `subprocess` field. When a node omits the ref, the step falls back to
+     * `ctx.subprocess` at execution time.
+     */
+    resolveSubprocess?: (ref: string) => SubprocessAdapter | undefined;
 }
 /**
  * Hydrates a single `WorkflowNode` into a live `Step`.

package/dist/builders/workflow-hydrator.js

@@ -5,7 +5,8 @@
  * `loop`, etc.) so hydrated steps are indistinguishable from programmatic
  * ones — they register in the step registry, carry retry policies, etc.
  */
-import { frameworkCast, NoeticConfigError } from '@noetic-tools/types';
+import { frameworkCast, isServerToolSpec, NoeticConfigError } from '@noetic-tools/types';
+import { DetachedHandleImpl } from '../runtime/detached-handle.js';
 import { all, any } from '../until/combinators.js';
 import { until } from '../until/predicates.js';
 import { branch, fork } from './control-flow-builders.js';
@@ -52,12 +53,34 @@ function hydrateLlmNode(node, ctx) {
     if (node.kind !== 'llm') {
         return frameworkCast(undefined);
     }
-    const resolvedTools = resolveTools(node.tools, ctx.tools);
+    // Every `tools` entry is an object `{ type, parameters? }`. Partition by the
+    // `type` value: a reserved `openrouter:*` server-tool literal is a SERVER
+    // tool (flows through unchanged); any other `type` is a CLIENT tool whose
+    // `type` is the registered tool NAME (resolved from the registry; a client
+    // entry's `parameters` is ignored). Both kinds are combined back into one
+    // `tools` array; the interpreter partitions them again at execution (server
+    // specs bypass the client-tool machinery and reach the model call's
+    // server-tool channel).
+    const toolNames = [];
+    const serverSpecs = [];
+    for (const entry of node.tools ?? []) {
+        if (isServerToolSpec(entry)) {
+            serverSpecs.push(entry);
+        }
+        else {
+            toolNames.push(entry.type);
+        }
+    }
+    const resolvedTools = resolveTools(toolNames, ctx.tools);
+    const combined = [
+        ...resolvedTools,
+        ...serverSpecs,
+    ];
     return step.llm({
         id: node.id,
         model: node.model ?? 'openai/gpt-4o',
         instructions: node.instructions,
-        tools: resolvedTools.length > 0 ? resolvedTools : undefined,
+        tools: combined.length > 0 ? combined : undefined,
         params: node.params,
     });
 }
@@ -106,6 +129,31 @@ function hydrateToolNode(node, ctx) {
         },
     }));
 }
+function hydrateRunNode(node, ctx) {
+    if (node.kind !== 'run') {
+        return frameworkCast(undefined);
+    }
+    const code = node.execute;
+    const subprocessRef = node.subprocess;
+    return frameworkCast(step.run({
+        id: node.id,
+        retry: node.retry,
+        execute: async (input, execCtx) => {
+            const adapter = resolveSubprocessAdapter({
+                ref: subprocessRef,
+                hydrationCtx: ctx,
+                execCtx,
+                nodeId: node.id,
+            });
+            return runCodeViaSubprocess({
+                adapter,
+                nodeId: node.id,
+                code,
+                input: stringifyResult(input),
+            });
+        },
+    }));
+}
 function hydrateBranchNode(node, ctx) {
     if (node.kind !== 'branch') {
         return frameworkCast(undefined);
@@ -137,14 +185,33 @@ function hydrateForkNode(node, ctx) {
     if (node.kind !== 'fork') {
         return frameworkCast(undefined);
     }
-    const hydratedPaths = node.paths.map((p) => hydrateNode(p, ctx));
+    // Static fork: paths are known at hydration time and feed the optimizer.
+    // Dynamic fork (`each`): paths are produced per fork-input at runtime, one
+    // child per array item, so they cannot be pre-computed or optimized.
+    const dynamic = node.each !== undefined;
+    const eachTemplate = node.each;
+    const staticPaths = dynamic ? [] : (node.paths ?? []).map((p) => hydrateNode(p, ctx));
+    const pathsFactory = (input) => {
+        if (!dynamic || !eachTemplate) {
+            return staticPaths;
+        }
+        const items = selectArray(input, node.over, node.id);
+        return items.map((item, i) => buildPerItemStep({
+            forkId: node.id,
+            eachTemplate,
+            item,
+            index: i,
+            ctx,
+        }));
+    };
+    const optimizable = dynamic ? undefined : frameworkCast(staticPaths);
     if (node.mode === 'race') {
         return fork({
             id: node.id,
             mode: 'race',
-            paths: () => hydratedPaths,
+            paths: pathsFactory,
             concurrency: node.concurrency,
-            _optimizable: frameworkCast(hydratedPaths),
+            _optimizable: optimizable,
         });
     }
     const mergeFn = buildMerge(node.merge ?? 'last');
@@ -152,22 +219,22 @@ function hydrateForkNode(node, ctx) {
         return fork({
             id: node.id,
             mode: 'settle',
-            paths: () => hydratedPaths,
+            paths: pathsFactory,
             merge: (results) => {
                 const values = results.filter((r) => r.status === 'fulfilled').map((r) => r.value ?? '');
                 return mergeFn(values);
             },
             concurrency: node.concurrency,
-            _optimizable: frameworkCast(hydratedPaths),
+            _optimizable: optimizable,
         });
     }
     return fork({
         id: node.id,
         mode: 'all',
-        paths: () => hydratedPaths,
+        paths: pathsFactory,
         merge: mergeFn,
         concurrency: node.concurrency,
-        _optimizable: frameworkCast(hydratedPaths),
+        _optimizable: optimizable,
     });
 }
 function hydrateSpawnNode(node, ctx) {
@@ -281,6 +348,7 @@ function hydrateSubHarnessNode(node, ctx) {
 const NODE_HYDRATORS = {
     llm: hydrateLlmNode,
     tool: hydrateToolNode,
+    run: hydrateRunNode,
     branch: hydrateBranchNode,
     fork: hydrateForkNode,
     spawn: hydrateSpawnNode,
@@ -332,6 +400,148 @@ function stringifyResult(value) {
     return JSON.stringify(value);
 }
 //#endregion
+//#region Dynamic Fork Helpers
+/**
+ * Parses the fork input (a JSON string) and locates the array to fan out over.
+ * When `over` is set, reads that property off the parsed object; otherwise the
+ * parsed value itself must be an array.
+ */
+function selectArray(input, over, nodeId) {
+    let parsed;
+    try {
+        parsed = JSON.parse(input);
+    }
+    catch {
+        throw new NoeticConfigError({
+            code: 'INVALID_FORK_INPUT',
+            message: `Dynamic fork '${nodeId}' could not parse its input as JSON.`,
+            hint: 'A dynamic fork (with `each`) expects its input to be a JSON array (or a JSON object when `over` is set).',
+        });
+    }
+    const candidate = over === undefined ? parsed : frameworkCast(parsed)?.[over];
+    if (!Array.isArray(candidate)) {
+        throw new NoeticConfigError({
+            code: 'INVALID_FORK_INPUT',
+            message: `Dynamic fork '${nodeId}' did not resolve an array${over ? ` at key '${over}'` : ''}.`,
+            hint: over
+                ? `Ensure the input JSON object has an array at '${over}'.`
+                : 'Ensure the input is a JSON array, or set `over` to select an array property.',
+        });
+    }
+    return candidate;
+}
+/**
+ * Builds one fork path for a single dynamic-fork item. The item is injected as
+ * the body's input (forks pass the same fork-input to every path), and the
+ * template's node ids are suffixed with `-${i}` so each instantiation has
+ * unique ids for tracing and step-registry uniqueness.
+ */
+function buildPerItemStep(opts) {
+    const { forkId, eachTemplate, item, index, ctx } = opts;
+    const hydratedEach = hydrateNode(suffixNodeIds(eachTemplate, `-${index}`), ctx);
+    return frameworkCast(step.run({
+        id: `${forkId}-item-${index}`,
+        execute: async (_input, execCtx) => {
+            const itemInput = JSON.stringify(item);
+            return stringifyResult(await ctx.executeStep(hydratedEach, itemInput, execCtx));
+        },
+    }));
+}
+/** Keys whose values are opaque data bags, never child workflow nodes. */
+const NON_NODE_KEYS = new Set([
+    'args',
+    'params',
+    'parameters',
+]);
+/**
+ * Deep-clones a workflow node template, appending `suffix` to the `id` of every
+ * nested node so a per-item instantiation has globally-unique step ids.
+ */
+function suffixNodeIds(node, suffix) {
+    const clone = structuredClone(node);
+    const walk = (value) => {
+        if (!value || typeof value !== 'object') {
+            return;
+        }
+        if (Array.isArray(value)) {
+            for (const entry of value) {
+                walk(entry);
+            }
+            return;
+        }
+        const record = frameworkCast(value);
+        if (typeof record.kind === 'string' && typeof record.id === 'string') {
+            record.id = `${record.id}${suffix}`;
+        }
+        for (const [key, child] of Object.entries(record)) {
+            if (NON_NODE_KEYS.has(key)) {
+                continue;
+            }
+            walk(child);
+        }
+    };
+    walk(clone);
+    return clone;
+}
+//#endregion
+//#region Run Node Helpers
+/**
+ * Resolves the subprocess adapter for a `run` node. When the node names an
+ * adapter ref, the host must supply a `resolveSubprocess` resolver; otherwise
+ * the step falls back to the harness adapter on the execution context.
+ */
+function resolveSubprocessAdapter(opts) {
+    const { ref, hydrationCtx, execCtx, nodeId } = opts;
+    if (ref === undefined) {
+        return execCtx.subprocess;
+    }
+    const resolved = hydrationCtx.resolveSubprocess?.(ref);
+    if (!resolved) {
+        throw new NoeticConfigError({
+            code: 'UNKNOWN_SUBPROCESS_REFERENCE',
+            message: `Subprocess adapter '${ref}' referenced in run node '${nodeId}' could not be resolved.`,
+            hint: 'Pass a `resolveSubprocess(ref)` mapping in the HydrationContext, or omit `subprocess` to use the harness default (ctx.subprocess).',
+        });
+    }
+    return resolved;
+}
+/**
+ * Dispatches a `run` node's code string through a subprocess adapter: ships the
+ * code plus the JSON-stringified input as a process request (input on stdin),
+ * waits for the handle to settle, and returns the captured stdout as the step
+ * output. A non-zero exit / failed handle surfaces as a thrown error.
+ *
+ * The code is never eval'd in-process (Cloudflare Workers forbid eval). The
+ * adapter owns running the code and capturing stdout into `handle.metadata.result`.
+ */
+async function runCodeViaSubprocess(opts) {
+    const { adapter, nodeId, code, input } = opts;
+    const request = {
+        kind: 'process',
+        command: 'node',
+        args: [
+            '-e',
+            code,
+        ],
+        stdin: input,
+        metadata: {
+            noeticRun: true,
+            stepId: nodeId,
+            code,
+            input,
+        },
+    };
+    const spawnPromise = adapter.spawn(request);
+    const handle = new DetachedHandleImpl({
+        id: `run-${nodeId}`,
+        stepId: nodeId,
+        adapter,
+        spawnPromise,
+    });
+    const result = await handle.await();
+    return stringifyResult(result);
+}
+//#endregion
 //#region Public API
 /**
  * Hydrates a single `WorkflowNode` into a live `Step`.

package/dist/harness/model-call.js

@@ -1,4 +1,5 @@
 import { frameworkCast, NoeticConfigError } from '@noetic-tools/types';
+import { serverTool } from '@openrouter/agent';
 import { z } from 'zod';
 import { convertTools, executeToolCall, extractOutputItems, extractSystemInstruction, extractUsage, itemsToInput, sanitizeToolNameForWire, } from '../adapters/openrouter.js';
 import { isFunctionCall } from '../interpreter/typeguards.js';
@@ -188,15 +189,29 @@ function prepareModelRequest(request, agentName) {
         .join('\n\n') || undefined;
     const broadcaster = getBroadcaster(request.ctx);
     const filteredTools = filterAllowedTools(request);
+    // Client (function) tools convert to SDK tool definitions; OpenRouter server
+    // tools (web_search/web_fetch) are wrapped via the SDK's `serverTool()` so
+    // its convertToolsToAPIFormat accepts them — a raw `{type}` entry crashes it.
+    // `parameters` keys stay camelCase: the SDK's outbound zod schema strips
+    // unknown keys, so snake_case would be silently dropped.
+    const clientSdkTools = filteredTools && filteredTools.length > 0
+        ? convertTools({
+            tools: filteredTools,
+        })
+        : [];
+    const serverSdkTools = (request._serverTools ?? []).map((s) => serverTool(frameworkCast({
+        type: s.type,
+        parameters: s.parameters,
+    })));
+    const sdkTools = [
+        ...clientSdkTools,
+        ...frameworkCast(serverSdkTools),
+    ];
     return {
         instructions,
         remaining,
         broadcaster,
-        sdkTools: filteredTools && filteredTools.length > 0
-            ? convertTools({
-                tools: filteredTools,
-            })
-            : undefined,
+        sdkTools: sdkTools.length > 0 ? sdkTools : undefined,
         emitIfAllowed(eventType, data) {
             if (!shouldEmit(request.emit, eventType, data)) {
                 return;

package/dist/index.d.ts

@@ -115,7 +115,9 @@ export { MergeStrategySchema, UntilPredicateSchema, validateWorkflow, WorkflowDo
 export type { Channel, ChannelHandle, ExternalChannel } from '@noetic-tools/types';
 /** @public */
 /** @public */
-export type { LLMResponse, LlmProviderConfig, ModelParams, RetryPolicy, StepMeta, TokenUsage, Tool, ToolMemoryDeclaration, } from '@noetic-tools/types';
+export type { LLMResponse, LlmProviderConfig, ModelParams, RetryPolicy, ServerToolSpec, StepMeta, TokenUsage, Tool, ToolMemoryDeclaration, } from '@noetic-tools/types';
+/** @public */
+export { isServerToolSpec } from '@noetic-tools/types';
 /** @public */
 /** @public */
 /** @public */

package/dist/index.js

@@ -98,6 +98,8 @@ export { defaultItemSchemaRegistry, ItemSchema, ItemSchemaRegistry } from '@noet
 /** @public */
 export { MergeStrategySchema, UntilPredicateSchema, validateWorkflow, WorkflowDocumentSchema, WorkflowNodeSchema, walkWorkflow, workflowDepth, } from './schemas/workflow.js';
 /** @public */
+export { isServerToolSpec } from '@noetic-tools/types';
+/** @public */
 export { getToolCwd, setToolCwd, snapshotCwdState } from './runtime/cwd-helpers.js';
 /** @public */
 export { DetachedStatus } from '@noetic-tools/types';

package/dist/interpreter/action-types.d.ts

@@ -1,3 +1,3 @@
 export type { ContextMemory, ExecutionContext, MemoryConfig, MemoryLayer, } from '@noetic-tools/memory';
-export type { AgentHarnessContract, Context, ContextRerenderRequest, ExecuteStepFn, FunctionCallItem, Item, ProjectionPolicy, RecallLayerOutput, RetryPolicy, StepLLM, StepMeta, StepProvide, StepRun, StepSpawn, StepTool, Tool, } from '@noetic-tools/types';
-export { SteeringAction } from '@noetic-tools/types';
+export type { AgentHarnessContract, Context, ContextRerenderRequest, ExecuteStepFn, FunctionCallItem, Item, ProjectionPolicy, RecallLayerOutput, RetryPolicy, ServerToolSpec, StepLLM, StepMeta, StepProvide, StepRun, StepSpawn, StepTool, Tool, } from '@noetic-tools/types';
+export { isServerToolSpec, SteeringAction } from '@noetic-tools/types';

package/dist/interpreter/action-types.js

@@ -1 +1 @@
-export { SteeringAction } from '@noetic-tools/types';
+export { isServerToolSpec, SteeringAction } from '@noetic-tools/types';

package/dist/interpreter/collect-tools.js

@@ -1,4 +1,4 @@
-import { frameworkCast } from '@noetic-tools/types';
+import { frameworkCast, isServerToolSpec } from '@noetic-tools/types';
 /**
  * Recursively walks a step tree and collects all Tool instances
  * declared on LLM steps. Used to build the unified tool set
@@ -31,9 +31,14 @@ function walkStep(step, out) {
             // Skip function-form tools: they're resolved per execution from `ctx`
             // and cannot contribute to the pre-computed unified set. Consumers that
             // need those tools in the pool should register them via
-            // `AgentHarness.tools` instead.
+            // `AgentHarness.tools` instead. Inline server-tool specs (web search/
+            // fetch) are not client `Tool`s — they never enter the unified pool.
             if (Array.isArray(step.tools)) {
-                out.push(...step.tools);
+                for (const entry of step.tools) {
+                    if (!isServerToolSpec(entry)) {
+                        out.push(entry);
+                    }
+                }
             }
             return;
         case 'run':

package/dist/interpreter/execute-action.js

@@ -4,7 +4,7 @@
 import { createMessage, estimateTokens, extractAssistantText, frameworkCast, isNoeticError, 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 { 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';
@@ -180,6 +180,26 @@ export async function executeLLM(step, input, ctx, layers) {
     }
     const resolvedInstructions = await resolveLazy(step.instructions, ctx);
     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 +216,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 +301,7 @@ export async function executeLLM(step, input, ctx, layers) {
                         ...projectedHistoryItems,
                     ];
         }
+        const _serverTools = serverToolSpecs.length > 0 ? serverToolSpecs : undefined;
         const request = resolvedTools
             ? {
                 model: resolvedModel,
@@ -290,6 +311,7 @@ export async function executeLLM(step, input, ctx, layers) {
                 params: step.params,
                 outputSchema: step.output,
                 emit: step.emit,
+                _serverTools,
                 ctx: baseCtx,
                 layers,
                 allowedToolNames,
@@ -303,6 +325,7 @@ export async function executeLLM(step, input, ctx, layers) {
                 params: step.params,
                 outputSchema: step.output,
                 emit: step.emit,
+                _serverTools,
                 nodeId: step.id,
                 parentSpan: baseCtx.span,
             };

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<{
@@ -87,7 +118,14 @@ 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>;
 }
 export interface ToolWorkflowNode extends WorkflowNodeBase {
@@ -95,6 +133,23 @@ export interface ToolWorkflowNode extends WorkflowNodeBase {
     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 +162,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 +220,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(),
@@ -121,7 +156,7 @@ const LlmNodeSchema = z.object({
     ...SHARED_FIELDS,
     model: z.string().optional(),
     instructions: z.string(),
-    tools: z.array(z.string()).optional(),
+    tools: z.array(LlmToolEntrySchema).optional(),
     params: ModelParamsSchema.optional(),
 });
 const ToolNodeSchema = z.object({
@@ -130,6 +165,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 +182,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 +191,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 +256,7 @@ export const WorkflowNodeSchema = z
     .discriminatedUnion('kind', [
     LlmNodeSchema,
     ToolNodeSchema,
+    RunNodeSchema,
     BranchNodeSchema,
     ForkNodeSchema,
     SpawnNodeSchema,
@@ -243,7 +292,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 [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/core",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "type": "module",
   "description": "Step primitives, interpreter, runtime, and memory layer contract for Noetic agents.",
   "license": "Apache-2.0",
@@ -67,7 +67,7 @@
   },
   "dependencies": {
     "@noetic-tools/memory": "^1.0.1",
-    "@noetic-tools/types": "^1.1.0",
+    "@noetic-tools/types": "^1.2.0",
     "@openrouter/agent": "^0.6.0",
     "zod": "^4.0.0"
   },

package/schema/noetic-workflow.schema.json

@@ -41,7 +41,24 @@
             "tools": {
               "type": "array",
               "items": {
-                "type": "string"
+                "type": "object",
+                "properties": {
+                  "type": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "parameters": {
+                    "type": "object",
+                    "propertyNames": {
+                      "type": "string"
+                    },
+                    "additionalProperties": {}
+                  }
+                },
+                "required": [
+                  "type"
+                ],
+                "additionalProperties": false
               }
             },
             "params": {
@@ -108,6 +125,65 @@
           ],
           "additionalProperties": false
         },
+        {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "type": "string",
+              "const": "run"
+            },
+            "id": {
+              "type": "string",
+              "minLength": 1
+            },
+            "execute": {
+              "type": "string",
+              "minLength": 1
+            },
+            "retry": {
+              "type": "object",
+              "properties": {
+                "maxAttempts": {
+                  "type": "integer",
+                  "exclusiveMinimum": 0,
+                  "maximum": 9007199254740991
+                },
+                "backoff": {
+                  "type": "string",
+                  "enum": [
+                    "fixed",
+                    "linear",
+                    "exponential"
+                  ]
+                },
+                "initialDelay": {
+                  "type": "number",
+                  "minimum": 0
+                },
+                "maxDelay": {
+                  "type": "number",
+                  "minimum": 0
+                }
+              },
+              "required": [
+                "maxAttempts",
+                "backoff",
+                "initialDelay"
+              ],
+              "additionalProperties": false
+            },
+            "subprocess": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "required": [
+            "kind",
+            "id",
+            "execute"
+          ],
+          "additionalProperties": false
+        },
         {
           "type": "object",
           "properties": {
@@ -177,6 +253,13 @@
                 "$ref": "#/$defs/WorkflowNode"
               }
             },
+            "each": {
+              "$ref": "#/$defs/WorkflowNode"
+            },
+            "over": {
+              "type": "string",
+              "minLength": 1
+            },
             "merge": {
               "type": "string",
               "enum": [
@@ -194,8 +277,7 @@
           "required": [
             "kind",
             "id",
-            "mode",
-            "paths"
+            "mode"
           ],
           "additionalProperties": false
         },