@noetic-tools/core 5.3.0 → 5.4.1

package/README.md

@@ -1,6 +1,6 @@
 # @noetic-tools/core
 
-Core primitives for the [Noetic](https://github.com/mattapperson/noetic) agent framework: step types, the interpreter, the runtime, the memory layer contract, and built-in patterns.
+Core primitives for the [Noetic](https://github.com/mattapperson/noetic) agent framework: step types, the interpreter, the runtime, and the context layer contract.
 
 ## Install
 
@@ -10,6 +10,8 @@ npm install @noetic-tools/core
 
 `@noetic-tools/core` depends on `@openrouter/agent` (the OpenRouter LLM adapter) and `zod`; your package manager installs both automatically. Runs on Node.js 18+ and Bun.
 
+Tool and structured-output schemas accept any [Standard Schema v1](https://standardschema.dev/schema) validator. Model-facing JSON Schema resolves through three tiers: Zod's native converter, the [Standard JSON Schema v1](https://standardschema.dev/json-schema) companion trait, then an explicit `inputJsonSchema` / `outputJsonSchema` override. Zod 4.2+, ArkType 2.1.28+, Zod Mini, VineJS, and Sury implement the companion trait; Valibot provides it via `toStandardJsonSchema()` from `@valibot/to-json-schema`.
+
 ## Set your API key
 
 Noetic talks to LLMs through [OpenRouter](https://openrouter.ai). Grab a key at [openrouter.ai/keys](https://openrouter.ai/keys) and export it — the runtime reads `OPENROUTER_API_KEY` by default:
@@ -23,20 +25,20 @@ export OPENROUTER_API_KEY=sk-or-...
 A complete, runnable program. Save it as `agent.mjs` and run `node agent.mjs`:
 
 ```ts
-import { AgentHarness, step } from '@noetic-tools/core';
+import { AgentHarness, callModel } from '@noetic-tools/core';
 
-// 1. Define a single LLM step. `model` and `instructions` live here.
-const greet = step.llm({
+// 1. Define a single model-call step. `model` and `instructions` live here.
+const greet = callModel({
   id: 'greet',
   model: 'openai/gpt-4o-mini', // any OpenRouter model id (provider/model)
   instructions: 'You are a friendly assistant. Greet the user by name in one short sentence.',
 });
 
-// 2. Create the harness. `name` and `params` are required; `llm` selects the provider.
+// 2. Create the harness. `name` and `params` are required; `callModelDefaults` selects the provider.
 const harness = new AgentHarness({
   name: 'greeter',
   params: {},
-  llm: { provider: 'openrouter' }, // apiKey defaults to process.env.OPENROUTER_API_KEY
+  callModelDefaults: { provider: 'openrouter' }, // apiKey defaults to process.env.OPENROUTER_API_KEY
 });
 
 // 3. Run the step with a context and print the model's reply.

package/dist/adapters/in-memory-subprocess/step-completion.js

@@ -31,7 +31,7 @@ export async function completeProcessRun({ request, handle, run, handles, active
                 error: serializeError(err),
             },
         });
-        // Same rationale as the success branch above — clear the durable
+        // Same rationale as the success path above — clear the durable
         // manifest so `listLive()` doesn't resurrect this handle on reboot.
         await clearIfDurable(handle.id);
     }

package/dist/adapters/openrouter.d.ts

@@ -1,5 +1,5 @@
 import type { ContextLayer } from '@noetic-tools/context';
-import type { AgentHarnessContract, Context, Item, LLMResponse, Tool } from '@noetic-tools/types';
+import type { AgentHarnessContract, Context, Item, LLMResponse, StandardSchemaV1, Tool } from '@noetic-tools/types';
 import type * as OpenRouterAgent from '@openrouter/agent';
 import type { EmbedFn } from '../types/embed.js';
 type ProviderOutputItem = OpenRouterAgent.OpenResponsesResult['output'][number];
@@ -40,6 +40,17 @@ export declare function extractUsage(usage: OpenRouterAgent.Usage | null | undef
  * to names like `plan/updatePrd`) is preserved.
  */
 export declare function sanitizeToolNameForWire(name: string): string;
+/**
+ * Resolve the JSON Schema sent to the model. Zod keeps its legacy-compatible
+ * fast path. For other validators, an explicit override wins over the Standard
+ * JSON Schema v1 companion trait.
+ * @internal
+ */
+export declare function resolveWireJsonSchema(params: {
+    schema: StandardSchemaV1;
+    explicitJsonSchema?: Record<string, unknown>;
+    what: string;
+}): Record<string, unknown>;
 /** @internal */
 export declare function convertTools({ tools }: ConvertToolsParams): SdkTool[];
 /** @internal */

package/dist/adapters/openrouter.js

@@ -1,4 +1,4 @@
-import { frameworkCast, isAssistantMessage, NoeticConfigError, SteeringAction, } from '@noetic-tools/types';
+import { frameworkCast, isAssistantMessage, isStandardJsonSchema, isZodSchema, NoeticConfigError, SteeringAction, validateSchema, } from '@noetic-tools/types';
 import { z } from 'zod';
 import { buildToolExecutionContext } from '../runtime/tool-context.js';
 import { emitToolUi } from '../runtime/tool-ui.js';
@@ -210,6 +210,72 @@ function cacheWriteTokensOf(details) {
 export function sanitizeToolNameForWire(name) {
     return name.replace(/[^a-zA-Z0-9_-]/g, '_');
 }
+/**
+ * Resolve the JSON Schema sent to the model. Zod keeps its legacy-compatible
+ * fast path. For other validators, an explicit override wins over the Standard
+ * JSON Schema v1 companion trait.
+ * @internal
+ */
+export function resolveWireJsonSchema(params) {
+    const { schema, explicitJsonSchema, what } = params;
+    if (isZodSchema(schema)) {
+        return sanitizeJsonSchema(z.toJSONSchema(schema, {
+            target: 'draft-07',
+        }));
+    }
+    if (explicitJsonSchema) {
+        return sanitizeJsonSchema(explicitJsonSchema);
+    }
+    if (isStandardJsonSchema(schema)) {
+        try {
+            return sanitizeJsonSchema(schema['~standard'].jsonSchema.input({
+                target: 'draft-07',
+            }));
+        }
+        catch {
+            // Fall through to the actionable configuration error below.
+        }
+    }
+    throw new NoeticConfigError({
+        code: 'MISSING_JSON_SCHEMA',
+        message: `The ${what} cannot be converted to JSON Schema.`,
+        hint: 'Use a schema implementing StandardJSONSchemaV1 or pass `inputJsonSchema` on tool() / `outputJsonSchema` on step.llm().',
+    });
+}
+function sanitizeJsonSchema(value) {
+    return Object.fromEntries(Object.entries(value)
+        .filter(([key]) => !key.startsWith('~'))
+        .map(([key, nested]) => [
+        key,
+        sanitizeJsonSchemaValue(nested),
+    ]));
+}
+function sanitizeJsonSchemaValue(value) {
+    if (Array.isArray(value)) {
+        return value.map(sanitizeJsonSchemaValue);
+    }
+    if (typeof value === 'object' && value !== null) {
+        return sanitizeJsonSchema(frameworkCast(value));
+    }
+    return value;
+}
+/**
+ * The OpenRouter SDK requires a live Zod `inputSchema` and runs
+ * `z.toJSONSchema` over it; it never executes these tool objects (Noetic owns
+ * its tool loop). For non-Zod inputs, bridge the resolved JSON Schema through
+ * a wire-only `z.any().meta(...)` so the SDK emits it unchanged. Noetic, not
+ * the SDK, validates tool-call args.
+ */
+function inputSchemaForWire(tool) {
+    if (isZodSchema(tool.input)) {
+        return tool.input;
+    }
+    return z.any().meta(resolveWireJsonSchema({
+        schema: tool.input,
+        explicitJsonSchema: tool.inputJsonSchema,
+        what: `input schema of tool '${tool.name}'`,
+    }));
+}
 /** @internal */
 export function convertTools({ tools }) {
     return tools.map((t) => frameworkCast({
@@ -217,7 +283,7 @@ export function convertTools({ tools }) {
         function: {
             name: sanitizeToolNameForWire(t.name),
             description: t.description,
-            inputSchema: t.input,
+            inputSchema: inputSchemaForWire(t),
         },
     }));
 }
@@ -232,7 +298,7 @@ export async function executeToolCall(params) {
     // Model sees sanitised tool names (see `sanitizeToolNameForWire`). Match
     // against both the original and sanitised name so internal identity (e.g.
     // `plan/updatePrd` used by steering whitelists, skill docs, and the
-    // `planContext.beforeToolCall` hook) stays intact while the wire name is
+    // `plan()` layer's `beforeToolCall` hook) stays intact while the wire name is
     // provider-compliant.
     const matchedTool = params.tools.find((t) => t.name === params.toolName || sanitizeToolNameForWire(t.name) === params.toolName);
     if (!matchedTool) {
@@ -256,6 +322,14 @@ export async function executeToolCall(params) {
             };
         }
     }
+    const validated = await validateSchema(matchedTool.input, params.args);
+    if (!validated.success) {
+        return {
+            output: `Error: invalid arguments for tool '${params.toolName}': ${validated.zodError.message}`,
+            error: true,
+        };
+    }
+    const parsedArgs = validated.value;
     const toolCtx = buildToolExecutionContext(params.context, params.harness);
     const callId = params.callId;
     const uiBase = callId !== undefined
@@ -263,7 +337,7 @@ export async function executeToolCall(params) {
             ctx: params.context,
             tool: matchedTool,
             callId,
-            args: params.args,
+            args: parsedArgs,
         }
         : undefined;
     if (uiBase) {
@@ -273,7 +347,7 @@ export async function executeToolCall(params) {
         });
     }
     try {
-        const executionResult = matchedTool.execute(params.args, toolCtx);
+        const executionResult = matchedTool.execute(parsedArgs, toolCtx);
         // Generator tools stream progress; drive them here so tool-UI `progress`
         // fragments emit per yield (the non-UI case just consumes to the return).
         let result;

package/dist/builders/acp-agent-tool.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Exposes an ACP coding agent as a `Tool`, so a `callModel` step can delegate
+ * work to it by calling it.
+ *
+ * `step.acpAgent` puts the agent in the step tree, where the *author* decides
+ * when it runs. This puts it in the model's hands instead: the model decides
+ * that a task wants a coding agent and calls the tool, the same way it would
+ * call any other. Everything else — permissions, session policy, the event
+ * bridge, usage accounting — is identical, because the tool runs the very same
+ * step underneath.
+ */
+import type { AcpAgent, AcpClientCapabilityConfig, AcpMcpServer, AcpPermissionHandler, AcpPermissionPolicy, AcpSessionPolicy, Tool } from '@noetic-tools/types';
+import { z } from 'zod';
+/** @public Options for {@link acpAgentTool}. */
+export interface AcpAgentToolOptions {
+    /** The ACP agent adapter to delegate to, e.g. `claudeCode()`. */
+    agent: AcpAgent;
+    /**
+     * Tool name the model calls. Defaults to `delegate_to_<agentId>` with
+     * non-identifier characters replaced, e.g. `delegate_to_claude_code`.
+     */
+    name?: string;
+    /**
+     * What the model is told the tool does. Defaults to a generic description —
+     * override it to steer *when* the model delegates, which matters far more
+     * than the default wording.
+     */
+    description?: string;
+    /** Working directory for the agent's session. Defaults to the runtime cwd. */
+    cwd?: string;
+    /** Session mode to switch to before each delegated turn. */
+    mode?: string;
+    /** Model to select before each delegated turn. */
+    model?: string;
+    /** MCP servers to expose to the agent. */
+    mcpServers?: ReadonlyArray<AcpMcpServer>;
+    /** Declarative answer to the agent's permission requests. Defaults to denying. */
+    permissions?: AcpPermissionPolicy;
+    /** Async resolver consulted when policy and steering both abstain. */
+    onPermissionRequest?: AcpPermissionHandler;
+    /** Which client capabilities to advertise to the agent. */
+    clientCapabilities?: AcpClientCapabilityConfig;
+    /**
+     * Session policy for the delegated turns. Give it a `reuse` key with
+     * `keepAlive: 'run'` (or `'harness'`) to let the model hold a *conversation*
+     * with the agent across several tool calls instead of starting cold each
+     * time — usually what you want, since the second call almost always builds
+     * on the first.
+     */
+    session?: AcpSessionPolicy;
+}
+declare const AcpAgentToolInputSchema: z.ZodObject<{
+    prompt: z.ZodString;
+}, z.core.$strip>;
+declare const AcpAgentToolOutputSchema: z.ZodObject<{
+    text: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Build a {@link Tool} that hands a prompt to an ACP coding agent.
+ *
+ * @public
+ * @param opts.agent - The agent adapter, e.g. `claudeCode()` from `@noetic-tools/acp`.
+ * @returns A `Tool` accepting `{ prompt }` and returning `{ text }`.
+ * @throws `NoeticConfigError` `MISSING_ACP_AGENT` when no adapter is given.
+ */
+export declare function acpAgentTool(opts: AcpAgentToolOptions): Tool<typeof AcpAgentToolInputSchema, typeof AcpAgentToolOutputSchema>;
+export {};

package/dist/builders/acp-agent-tool.js

@@ -0,0 +1,87 @@
+/**
+ * Exposes an ACP coding agent as a `Tool`, so a `callModel` step can delegate
+ * work to it by calling it.
+ *
+ * `step.acpAgent` puts the agent in the step tree, where the *author* decides
+ * when it runs. This puts it in the model's hands instead: the model decides
+ * that a task wants a coding agent and calls the tool, the same way it would
+ * call any other. Everything else — permissions, session policy, the event
+ * bridge, usage accounting — is identical, because the tool runs the very same
+ * step underneath.
+ */
+import { NoeticConfigError } from '@noetic-tools/types';
+import { z } from 'zod';
+import { step } from './step-builders.js';
+import { tool } from './tool-builder.js';
+const AcpAgentToolInputSchema = z.object({
+    prompt: z.string().min(1).describe('What the coding agent should do, in plain language.'),
+});
+const AcpAgentToolOutputSchema = z.object({
+    text: z.string().describe("The coding agent's final response."),
+});
+//#endregion
+//#region Helpers
+/** `claude-code` → `delegate_to_claude_code`. */
+function defaultToolName(agentId) {
+    return `delegate_to_${agentId.replace(/[^a-zA-Z0-9_]/g, '_')}`;
+}
+function defaultDescription(agentId) {
+    return [
+        `Delegate a coding task to the ${agentId} agent, which works directly in the workspace.`,
+        'Give it a complete, self-contained instruction — it does not see this conversation.',
+        'Prefer it for multi-file edits, running builds or tests, and exploring an unfamiliar codebase.',
+    ].join(' ');
+}
+//#endregion
+//#region Public API
+/**
+ * Build a {@link Tool} that hands a prompt to an ACP coding agent.
+ *
+ * @public
+ * @param opts.agent - The agent adapter, e.g. `claudeCode()` from `@noetic-tools/acp`.
+ * @returns A `Tool` accepting `{ prompt }` and returning `{ text }`.
+ * @throws `NoeticConfigError` `MISSING_ACP_AGENT` when no adapter is given.
+ */
+export function acpAgentTool(opts) {
+    if (!opts.agent) {
+        throw new NoeticConfigError({
+            code: 'MISSING_ACP_AGENT',
+            message: 'acpAgentTool() requires an agent adapter.',
+            hint: 'Pass an agent factory result, e.g. agent: claudeCode() from @noetic-tools/acp.',
+        });
+    }
+    const name = opts.name ?? defaultToolName(opts.agent.agentId);
+    // Built once, not per call: `step.acpAgent` registers itself in the step
+    // registry, so constructing one per invocation would fill the registry with
+    // duplicate ids. An empty `prompt` means "use the step's runtime input",
+    // which is exactly the tool's argument.
+    const delegated = step.acpAgent({
+        id: `${name}:step`,
+        agent: opts.agent,
+        prompt: '',
+        cwd: opts.cwd,
+        mode: opts.mode,
+        model: opts.model,
+        mcpServers: opts.mcpServers,
+        permissions: opts.permissions,
+        onPermissionRequest: opts.onPermissionRequest,
+        clientCapabilities: opts.clientCapabilities,
+        session: opts.session,
+    });
+    return tool({
+        name,
+        description: opts.description ?? defaultDescription(opts.agent.agentId),
+        input: AcpAgentToolInputSchema,
+        output: AcpAgentToolOutputSchema,
+        async execute(args, toolCtx) {
+            // Running through the harness on the tool's own context means the
+            // delegated turn lands in the same item log, usage totals, and event
+            // stream as any other step — it is a real step, not a side channel.
+            const text = await toolCtx.harness.run(delegated, args.prompt, toolCtx.ctx);
+            return {
+                text,
+            };
+        },
+    });
+}
+//#endregion

package/dist/builders/control-flow-builders.d.ts

@@ -1,5 +1,5 @@
 import type { ContextData } from '@noetic-tools/context';
-import type { Context, SettleResult, Step, StepBranch, StepForkAll, StepForkRace, StepForkSettle } from '@noetic-tools/types';
+import type { Context, SettleResult, Step, StepConditional, StepInParallelAll, StepInParallelRace, StepInParallelSettle } from '@noetic-tools/types';
 /**
  * Creates a parallel execution step that races paths and returns the first result.
  *
@@ -8,16 +8,16 @@ import type { Context, SettleResult, Step, StepBranch, StepForkAll, StepForkRace
  * @param opts.mode - Must be `'race'`: first path to resolve wins, others are cancelled.
  * @param opts.paths - Factory `(input, ctx) => Step[]` generating the parallel paths.
  * @param opts.concurrency - Optional maximum number of paths to run simultaneously.
- * @returns A `StepForkRace` step.
+ * @returns A `StepInParallelRace` step.
  * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
  */
-export declare function fork<TContext = ContextData, I = unknown, O = unknown>(opts: {
+export declare function inParallel<TContext = ContextData, I = unknown, O = unknown>(opts: {
     id: string;
     mode: 'race';
     paths: (input: I, ctx: Context<TContext>) => Step<TContext, I, O>[];
     concurrency?: number;
     _optimizable?: Step<TContext>[];
-}): StepForkRace<TContext, I, O>;
+}): StepInParallelRace<TContext, I, O>;
 /**
  * Creates a parallel execution step that waits for all paths and merges results.
  *
@@ -27,18 +27,18 @@ export declare function fork<TContext = ContextData, I = unknown, O = unknown>(o
  * @param opts.paths - Factory `(input, ctx) => Step[]` generating the parallel paths.
  * @param opts.merge - Combines all path results into a single output value.
  * @param opts.concurrency - Optional maximum number of paths to run simultaneously.
- * @returns A `StepForkAll` step.
+ * @returns A `StepInParallelAll` step.
  * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
  * @throws `NoeticConfigError` with code `MISSING_MERGE_FUNCTION` if `merge` is not provided.
  */
-export declare function fork<TContext = ContextData, I = unknown, O = unknown>(opts: {
+export declare function inParallel<TContext = ContextData, I = unknown, O = unknown>(opts: {
     id: string;
     mode: 'all';
     paths: (input: I, ctx: Context<TContext>) => Step<TContext, I, O>[];
     merge: (results: O[], ctx: Context<TContext>) => O;
     concurrency?: number;
     _optimizable?: Step<TContext>[];
-}): StepForkAll<TContext, I, O>;
+}): StepInParallelAll<TContext, I, O>;
 /**
  * Creates a parallel execution step that waits for all paths, collecting errors as results.
  *
@@ -48,18 +48,18 @@ export declare function fork<TContext = ContextData, I = unknown, O = unknown>(o
  * @param opts.paths - Factory `(input, ctx) => Step[]` generating the parallel paths.
  * @param opts.merge - Combines settled results (successes and failures) into a single output.
  * @param opts.concurrency - Optional maximum number of paths to run simultaneously.
- * @returns A `StepForkSettle` step.
+ * @returns A `StepInParallelSettle` step.
  * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
  * @throws `NoeticConfigError` with code `MISSING_MERGE_FUNCTION` if `merge` is not provided.
  */
-export declare function fork<TContext = ContextData, I = unknown, O = unknown>(opts: {
+export declare function inParallel<TContext = ContextData, I = unknown, O = unknown>(opts: {
     id: string;
     mode: 'settle';
     paths: (input: I, ctx: Context<TContext>) => Step<TContext, I, O>[];
     merge: (results: SettleResult<O>[], ctx: Context<TContext>) => O;
     concurrency?: number;
     _optimizable?: Step<TContext>[];
-}): StepForkSettle<TContext, I, O>;
+}): StepInParallelSettle<TContext, I, O>;
 /**
  * Creates a conditional routing step that selects the next step at runtime.
  *
@@ -67,12 +67,12 @@ export declare function fork<TContext = ContextData, I = unknown, O = unknown>(o
  * @param opts.id - Unique step identifier used in traces and error messages.
  * @param opts.route - Routing function `(input, ctx) => Step | null`. Returns the next step
  *   to execute, or `null` to skip (pass input through as output). May be async.
- * @returns A `StepBranch` step.
+ * @returns A `StepConditional` step.
  * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
  * @throws `NoeticConfigError` with code `MISSING_ROUTE_FUNCTION` if `route` is not provided.
  */
-export declare function branch<TContext = ContextData, I = unknown, O = unknown>(opts: {
+export declare function conditional<TContext = ContextData, I = unknown, O = unknown>(opts: {
     id: string;
     route: (input: I, ctx: Context<TContext>) => Step<TContext, I, O> | null | Promise<Step<TContext, I, O> | null>;
     _optimizable?: Step<TContext>[];
-}): StepBranch<TContext, I, O>;
+}): StepConditional<TContext, I, O>;

package/dist/builders/control-flow-builders.js

@@ -1,22 +1,22 @@
 import { frameworkCast, NoeticConfigError } from '@noetic-tools/types';
 import { getDefaultRegistrar } from '../types/step-registrar.js';
-export function fork(opts) {
+export function inParallel(opts) {
     if (!opts.id || opts.id.trim() === '') {
         throw new NoeticConfigError({
             code: 'EMPTY_STEP_ID',
-            message: 'fork() requires a non-empty id.',
-            hint: 'Pass a unique string as the id field, e.g. fork({ id: "my-fork", ... }).',
+            message: 'inParallel() requires a non-empty id.',
+            hint: 'Pass a unique string as the id field, e.g. inParallel({ id: "my-inParallel", ... }).',
         });
     }
     if ((opts.mode === 'all' || opts.mode === 'settle') && !opts.merge) {
         throw new NoeticConfigError({
             code: 'MISSING_MERGE_FUNCTION',
-            message: `fork() mode '${opts.mode}' requires a merge function.`,
+            message: `inParallel() mode '${opts.mode}' requires a merge function.`,
             hint: 'Provide a merge function that combines path results into a single output.',
         });
     }
     const built = frameworkCast({
-        kind: 'fork',
+        kind: 'inParallel',
         ...opts,
     });
     getDefaultRegistrar().register(built);
@@ -29,27 +29,27 @@ export function fork(opts) {
  * @param opts.id - Unique step identifier used in traces and error messages.
  * @param opts.route - Routing function `(input, ctx) => Step | null`. Returns the next step
  *   to execute, or `null` to skip (pass input through as output). May be async.
- * @returns A `StepBranch` step.
+ * @returns A `StepConditional` step.
  * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
  * @throws `NoeticConfigError` with code `MISSING_ROUTE_FUNCTION` if `route` is not provided.
  */
-export function branch(opts) {
+export function conditional(opts) {
     if (!opts.id || opts.id.trim() === '') {
         throw new NoeticConfigError({
             code: 'EMPTY_STEP_ID',
-            message: 'branch() requires a non-empty id.',
-            hint: 'Pass a unique string as the id field, e.g. branch({ id: "my-branch", ... }).',
+            message: 'conditional() requires a non-empty id.',
+            hint: 'Pass a unique string as the id field, e.g. conditional({ id: "my-conditional", ... }).',
         });
     }
     if (!opts.route) {
         throw new NoeticConfigError({
             code: 'MISSING_ROUTE_FUNCTION',
-            message: 'branch() requires a route function.',
+            message: 'conditional() requires a route function.',
             hint: 'Provide a route function that selects the next step at runtime.',
         });
     }
     const built = {
-        kind: 'branch',
+        kind: 'conditional',
         ...opts,
     };
     getDefaultRegistrar().register(built);

package/dist/{patterns → builders}/dynamic-workflow.d.ts

@@ -36,7 +36,7 @@ export interface ParseAndRunWorkflowOpts {
     input?: string;
     maxDepth?: number;
     /**
-     * Context layers the document's `provide` / `spawn` nodes may reference by name.
+     * Context layers the document's `withContext` / `spawn` nodes may reference by name.
      * Without a registry those nodes resolve to NO layers rather than failing, so a
      * host that runs layer-bearing workflows must pass its layers here.
      */

package/dist/{patterns → builders}/dynamic-workflow.js

@@ -3,10 +3,10 @@
  * then hydrates and runs it within the same harness session.
  */
 import { frameworkCast, NoeticConfigError } from '@noetic-tools/types';
-import { step } from '../builders/step-builders.js';
-import { hydrateWorkflow } from '../builders/workflow-hydrator.js';
 import { NoeticAttr } from '../observability/genai-attributes.js';
 import { WorkflowDocumentSchema, workflowDepth, workflowGraph } from '../schemas/workflow.js';
+import { callModel, runCode } from './step-builders.js';
+import { hydrateWorkflow } from './workflow-hydrator.js';
 //#endregion
 //#region Constants
 const DEFAULT_MAX_DEPTH = 5;
@@ -21,19 +21,25 @@ The workflow document must be valid JSON with this structure:
 }
 
 A WorkflowNode is one of:
-- { "kind": "llm", "id": "<unique>", "instructions": "<prompt>", "model": "<optional>", "tools": ["<tool-name>", ...] }
-- { "kind": "tool", "id": "<unique>", "toolName": "<name>", "args": { ... } }
-- { "kind": "sequence", "id": "<unique>", "steps": [<WorkflowNode>, ...] }
-- { "kind": "fork", "id": "<unique>", "mode": "all"|"race"|"settle", "paths": [<WorkflowNode>, ...], "merge": "last"|"first"|"concat" }
-- { "kind": "loop", "id": "<unique>", "body": <WorkflowNode>, "until": { "kind": "maxSteps", "n": <number> } }
-- { "kind": "branch", "id": "<unique>", "routes": [{ "match": "<substring>", "target": <WorkflowNode> }], "default": <WorkflowNode> }
-- { "kind": "spawn", "id": "<unique>", "child": <WorkflowNode> }
+- { "kind": "callModel", "id": "<unique>", "instructions": "<prompt>", "model": "<optional>", "tools": [{ "type": "<tool-name>" }, ...] } (one LLM call)
+- { "kind": "invokeTool", "id": "<unique>", "toolName": "<name>", "args": { ... } } (call one tool directly, no LLM)
+- { "kind": "runCode", "id": "<unique>", "execute": "<source code>" } (runs the code in a subprocess with the step input on stdin; only emit if the task needs deterministic computation AND a subprocess adapter is available)
+- { "kind": "sequence", "id": "<unique>", "steps": [<WorkflowNode>, ...] } (run children in order, threading each output into the next)
+- { "kind": "inParallel", "id": "<unique>", "mode": "all"|"race"|"settle", "paths": [<WorkflowNode>, ...], "merge": "last"|"first"|"concat" } (fan out; supply exactly one of "paths" or "each": <WorkflowNode> — with "each", add "over": "<key>" to fan out over an array in the input JSON)
+- { "kind": "loop", "id": "<unique>", "body": <WorkflowNode>, "until": <UntilPredicate>, "maxIterations": <optional number> } (repeat the body until the predicate holds)
+- { "kind": "conditional", "id": "<unique>", "routes": [{ "match": "<substring>", "target": <WorkflowNode> }], "default": <WorkflowNode> } (route on a substring of the input)
+- { "kind": "spawn", "id": "<unique>", "child": <WorkflowNode>, "timeout": <optional ms> } (run the child in an isolated sub-context)
+- { "kind": "withContext", "id": "<unique>", "child": <WorkflowNode>, "layers": ["<layer-name>", ...] } (run the child with named context layers; only emit if the task names layers that exist, since this planner provides no layer registry and unknown names resolve to NO layers)
+- { "kind": "schedule", "id": "<unique>", "step": <WorkflowNode>, "interval": <ms>, "onError": "continue"|"fail" } (re-runs the step forever on an interval and never returns — only emit for an explicitly daemon-style task)
 - { "kind": "subflow", "id": "<unique>", "document": { "version": 1, "root": <WorkflowNode> } } (an inline sub-workflow run as one step; only emit the inline form — named refs require a registry this planner does not provide)
-- { "kind": "claude-code"|"codex"|"opencode"|"pi", "id": "<unique>", "prompt": "<turn prompt>", "settings": { "model": "<optional>", "permissionMode": "<optional>" } }
+- { "kind": "acp-agent", "id": "<unique>", "agent": "<registered agent id, e.g. claude-code>", "prompt": "<turn prompt>", "mode": "<optional session mode>", "model": "<optional>" }
 
-SubHarness nodes (claude-code, codex, opencode, pi) delegate a turn to an external coding agent; only emit one if a matching harness adapter is registered for the workflow.
+Every entry of a callModel node's "tools" is an OBJECT, never a bare string. Use { "type": "<tool-name>" } to let the model call one of the tools listed below. Two provider-executed tools are also available without being listed: { "type": "openrouter:web_search" } and { "type": "openrouter:web_fetch" }, each accepting an optional "parameters" object.
 
-Until predicates: maxSteps, maxCost, maxDuration, noToolCalls, outputContains, outputEquals, converged, any, all.
+An acp-agent node delegates a turn to an external coding agent over the Agent Client Protocol; only emit one if a matching agent adapter is registered for the workflow.
+
+An UntilPredicate (the "until" field of a loop) is one of:
+{ "kind": "maxSteps", "n": <positive int> }, { "kind": "maxCost", "usd": <positive number> }, { "kind": "maxDuration", "duration": <ms> }, { "kind": "noToolCalls" }, { "kind": "never" } (never stops — pair with "maxIterations"), { "kind": "outputContains", "marker": "<text>" }, { "kind": "outputEquals", "sentinel": "<text>" }, { "kind": "converged", "threshold": <optional 0-1> }, { "kind": "any", "predicates": [<UntilPredicate>, ...] }, { "kind": "all", "predicates": [<UntilPredicate>, ...] }.
 
 Respond with ONLY the JSON document, no markdown fences or explanation.`;
 //#endregion
@@ -56,7 +62,7 @@ export function dynamicWorkflow(opts) {
     const maxDepth = opts.maxDepth ?? DEFAULT_MAX_DEPTH;
     const maxRevisions = opts.maxRevisions ?? DEFAULT_MAX_REVISIONS;
     const toolMap = buildToolMap(opts.tools);
-    return step.run({
+    return runCode({
         id: 'dynamic-workflow',
         execute: async (input, ctx) => {
             const harness = ctx.harness;
@@ -81,7 +87,7 @@ export function dynamicWorkflow(opts) {
                 const prompt = lastError
                     ? `${basePrompt}\n\nPrevious attempt failed with error: ${lastError}\nPlease fix the workflow and try again.`
                     : basePrompt;
-                const plannerStep = step.llm({
+                const plannerStep = callModel({
                     id: `dynamic-workflow-planner-${revision}`,
                     model,
                     instructions: prompt,