@noetic-tools/core 5.3.0 → 5.4.1

package/dist/builders/step-builders.js

@@ -1,199 +1,182 @@
 import { NoeticConfigError } from '@noetic-tools/types';
 import { getDefaultRegistrar } from '../types/step-registrar.js';
 //#endregion
-//#region SubHarness builder helper
+//#region ACP agent builder helper
 /**
- * Shared construction for every harness step kind. Each `step.<kind>()` is a
- * thin wrapper so the kinds stay individually typed while the validation and
- * registration live in one place.
+ * Validation shared by `step.acpAgent`. Kept separate from the builder so the
+ * checks stay readable and the builder stays a one-liner.
  */
-function buildSubHarnessStep(kind, builderName, opts) {
+function validateAcpAgentOpts(opts) {
     if (!opts.id || opts.id.trim() === '') {
         throw new NoeticConfigError({
             code: 'EMPTY_STEP_ID',
-            message: `${builderName}() requires a non-empty id.`,
-            hint: `Pass a unique string as the id field, e.g. ${builderName}({ id: "review", ... }).`,
+            message: 'step.acpAgent() requires a non-empty id.',
+            hint: 'Pass a unique string as the id field, e.g. step.acpAgent({ id: "review", ... }).',
         });
     }
-    if (!opts.harness) {
+    if (!opts.agent) {
         throw new NoeticConfigError({
-            code: 'MISSING_SUB_HARNESS',
-            message: `${builderName}() requires a harness adapter.`,
-            hint: `Pass a harness factory result, e.g. harness: ${builderName.replace('step.', '')}({ model }).`,
+            code: 'MISSING_ACP_AGENT',
+            message: 'step.acpAgent() requires an agent adapter.',
+            hint: 'Pass an agent factory result, e.g. agent: claudeCode() from @noetic-tools/acp.',
         });
     }
-    // Eager adapters are validated now; function-form adapters are validated
-    // post-resolution in executeSubHarness so the same SUB_HARNESS_KIND_MISMATCH
-    // error surfaces whether the caller passes an adapter or a getter.
-    if (typeof opts.harness !== 'function' && opts.harness.harnessId !== kind) {
+    // Presence, not emptiness: an empty `prompt` is a valid way to say "use the
+    // step's runtime input as the prompt", which the handler supports.
+    if (opts.prompt === undefined && opts.content === undefined) {
         throw new NoeticConfigError({
-            code: 'SUB_HARNESS_KIND_MISMATCH',
-            message: `${builderName}() was given a '${opts.harness.harnessId}' harness.`,
-            hint: `Use the matching builder, e.g. step.${opts.harness.harnessId}({ ... }).`,
+            code: 'MISSING_PROMPT',
+            message: 'step.acpAgent() requires a prompt or content blocks.',
+            hint: 'Pass `prompt` for plain text, or `content` for image/audio/resource blocks.',
+        });
+    }
+}
+//#endregion
+//#region Builders
+/**
+ * Creates a pure async computation step.
+ *
+ * @public
+ * @param opts.id - Unique step identifier used in traces and error messages.
+ * @param opts.execute - Async function `(input, ctx) => output` that performs the work.
+ * @param opts.retry - Optional retry policy controlling attempts, backoff, and delay.
+ * @param opts.subprocess - Optional per-step subprocess adapter override.
+ * @returns A `StepRunCode` that can be composed into larger pipelines. The step
+ *   is auto-registered in the shared step registry so the subprocess
+ *   adapter can dispatch it by id.
+ * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
+ * @throws `NoeticConfigError` with code `MISSING_EXECUTE_FUNCTION` if `execute` is not provided.
+ * @throws `NoeticConfigError` with code `DUPLICATE_STEP_ID` if another step with the same id is already registered with a different body.
+ */
+export function runCode(opts) {
+    if (!opts.id || opts.id.trim() === '') {
+        throw new NoeticConfigError({
+            code: 'EMPTY_STEP_ID',
+            message: 'runCode() requires a non-empty id.',
+            hint: 'Pass a unique string as the id field, e.g. runCode({ id: "my-step", ... }).',
+        });
+    }
+    if (!opts.execute) {
+        throw new NoeticConfigError({
+            code: 'MISSING_EXECUTE_FUNCTION',
+            message: 'runCode() requires an execute function.',
+            hint: 'Provide an async execute function, e.g. execute: async (input, ctx) => result.',
         });
     }
     const built = {
-        kind,
+        kind: 'runCode',
         ...opts,
     };
     getDefaultRegistrar().register(built);
     return built;
 }
-//#endregion
-//#region Builders
+/**
+ * Creates a model call step with optional tools and structured output.
+ *
+ * @public
+ * @param opts.id - Unique step identifier used in traces and error messages.
+ * @param opts.model - Model identifier, eager string or `(ctx) => string` getter (resolved at step execution time).
+ * @param opts.instructions - Optional system prompt; eager string or `(ctx) => string | undefined` getter.
+ * @param opts.tools - Optional tools; eager array or `(ctx) => Tool[] | undefined` getter.
+ * @param opts.output - Optional Zod schema enabling structured output parsing.
+ * @param opts.params - Optional model parameters (temperature, topP, maxTokens, stopSequences).
+ * @returns A `StepCallModel` that can be composed into larger pipelines. The step
+ *   is auto-registered in the shared step registry.
+ * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
+ * @throws `NoeticConfigError` with code `MISSING_MODEL` if an eager `model` string is empty. Function-form models are validated at step execution.
+ */
+export function callModel(opts) {
+    if (!opts.id || opts.id.trim() === '') {
+        throw new NoeticConfigError({
+            code: 'EMPTY_STEP_ID',
+            message: 'callModel() requires a non-empty id.',
+            hint: 'Pass a unique string as the id field, e.g. callModel({ id: "my-llm", ... }).',
+        });
+    }
+    // Only validate eager models here. Function-form models are validated
+    // post-resolution in executeCallModel so the same MISSING_MODEL error surfaces
+    // whether the caller passes a string or a getter.
+    if (typeof opts.model === 'string' && opts.model.trim() === '') {
+        throw new NoeticConfigError({
+            code: 'MISSING_MODEL',
+            message: 'callModel() requires a non-empty model.',
+            hint: "Pass a model identifier, e.g. model: 'anthropic/claude-sonnet-4-20250514'.",
+        });
+    }
+    const built = {
+        kind: 'callModel',
+        ...opts,
+    };
+    getDefaultRegistrar().register(built);
+    return built;
+}
+/**
+ * Creates a tool execution step that invokes a typed tool definition.
+ *
+ * @public
+ * @param opts.id - Unique step identifier used in traces and error messages.
+ * @param opts.tool - The tool definition with typed input/output schemas.
+ * @param opts.args - Optional partial args that override or supplement model-provided arguments.
+ * @returns A `StepInvokeTool` that can be composed into larger pipelines. The step
+ *   is auto-registered in the shared step registry.
+ * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
+ * @throws `NoeticConfigError` with code `MISSING_TOOL` if `tool` is not provided.
+ */
+export function invokeTool(opts) {
+    if (!opts.id || opts.id.trim() === '') {
+        throw new NoeticConfigError({
+            code: 'EMPTY_STEP_ID',
+            message: 'invokeTool() requires a non-empty id.',
+            hint: 'Pass a unique string as the id field, e.g. invokeTool({ id: "my-tool", ... }).',
+        });
+    }
+    if (!opts.tool) {
+        throw new NoeticConfigError({
+            code: 'MISSING_TOOL',
+            message: 'invokeTool() requires a tool.',
+            hint: 'Provide a tool definition created with the tool() builder.',
+        });
+    }
+    const built = {
+        kind: 'invokeTool',
+        ...opts,
+    };
+    getDefaultRegistrar().register(built);
+    return built;
+}
+/**
+ * The ACP step builder namespace. Unlike the flattened base builders
+ * (`runCode`, `callModel`, `invokeTool`), the coding-agent builder stays
+ * grouped under `step`.
+ *
+ * @public
+ */
 export const step = {
     /**
-     * Creates a pure async computation step.
-     *
-     * @public
-     * @param opts.id - Unique step identifier used in traces and error messages.
-     * @param opts.execute - Async function `(input, ctx) => output` that performs the work.
-     * @param opts.retry - Optional retry policy controlling attempts, backoff, and delay.
-     * @param opts.subprocess - Optional per-step subprocess adapter override.
-     * @returns A `StepRun` that can be composed into larger pipelines. The step
-     *   is auto-registered in the shared step registry so the subprocess
-     *   adapter can dispatch it by id.
-     * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
-     * @throws `NoeticConfigError` with code `MISSING_EXECUTE_FUNCTION` if `execute` is not provided.
-     * @throws `NoeticConfigError` with code `DUPLICATE_STEP_ID` if another step with the same id is already registered with a different body.
-     */
-    run(opts) {
-        if (!opts.id || opts.id.trim() === '') {
-            throw new NoeticConfigError({
-                code: 'EMPTY_STEP_ID',
-                message: 'step.run() requires a non-empty id.',
-                hint: 'Pass a unique string as the id field, e.g. step.run({ id: "my-step", ... }).',
-            });
-        }
-        if (!opts.execute) {
-            throw new NoeticConfigError({
-                code: 'MISSING_EXECUTE_FUNCTION',
-                message: 'step.run() requires an execute function.',
-                hint: 'Provide an async execute function, e.g. execute: async (input, ctx) => result.',
-            });
-        }
-        const built = {
-            kind: 'run',
-            ...opts,
-        };
-        getDefaultRegistrar().register(built);
-        return built;
-    },
-    /**
-     * Creates an LLM model call step with optional tools and structured output.
+     * Creates a step that delegates a turn to an external coding agent over the
+     * Agent Client Protocol.
      *
-     * @public
-     * @param opts.id - Unique step identifier used in traces and error messages.
-     * @param opts.model - Model identifier, eager string or `(ctx) => string` getter (resolved at step execution time).
-     * @param opts.instructions - Optional system prompt; eager string or `(ctx) => string | undefined` getter.
-     * @param opts.tools - Optional tools; eager array or `(ctx) => Tool[] | undefined` getter.
-     * @param opts.output - Optional Zod schema enabling structured output parsing.
-     * @param opts.params - Optional model parameters (temperature, topP, maxTokens, stopSequences).
-     * @returns A `StepLLM` that can be composed into larger pipelines. The step
-     *   is auto-registered in the shared step registry.
-     * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
-     * @throws `NoeticConfigError` with code `MISSING_MODEL` if an eager `model` string is empty. Function-form models are validated at step execution.
-     */
-    llm(opts) {
-        if (!opts.id || opts.id.trim() === '') {
-            throw new NoeticConfigError({
-                code: 'EMPTY_STEP_ID',
-                message: 'step.llm() requires a non-empty id.',
-                hint: 'Pass a unique string as the id field, e.g. step.llm({ id: "my-llm", ... }).',
-            });
-        }
-        // Only validate eager models here. Function-form models are validated
-        // post-resolution in executeLLM so the same MISSING_MODEL error surfaces
-        // whether the caller passes a string or a getter.
-        if (typeof opts.model === 'string' && opts.model.trim() === '') {
-            throw new NoeticConfigError({
-                code: 'MISSING_MODEL',
-                message: 'step.llm() requires a non-empty model.',
-                hint: "Pass a model identifier, e.g. model: 'anthropic/claude-sonnet-4-20250514'.",
-            });
-        }
-        const built = {
-            kind: 'llm',
-            ...opts,
-        };
-        getDefaultRegistrar().register(built);
-        return built;
-    },
-    /**
-     * Creates a tool execution step that invokes a typed tool definition.
+     * One builder covers every ACP-speaking agent: the agent itself is supplied
+     * as an adapter, so adding an agent never changes this API or the published
+     * workflow schema.
      *
      * @public
-     * @param opts.id - Unique step identifier used in traces and error messages.
-     * @param opts.tool - The tool definition with typed input/output schemas.
-     * @param opts.args - Optional partial args that override or supplement LLM-provided arguments.
-     * @returns A `StepTool` that can be composed into larger pipelines. The step
-     *   is auto-registered in the shared step registry.
-     * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
-     * @throws `NoeticConfigError` with code `MISSING_TOOL` if `tool` is not provided.
+     * @param opts.id - Unique step identifier.
+     * @param opts.agent - An agent adapter, e.g. `claudeCode()` from `@noetic-tools/acp`.
+     * @param opts.prompt - The turn prompt; eager string or `(ctx) => string` getter.
+     * @param opts.permissions - Declarative policy answering the agent's permission requests.
+     * @param opts.output - Optional Standard Schema enabling structured output parsing.
+     * @returns A `StepAcpAgent`, auto-registered in the step registry.
+     * @throws `NoeticConfigError` `EMPTY_STEP_ID` / `MISSING_ACP_AGENT` / `MISSING_PROMPT`.
      */
-    tool(opts) {
-        if (!opts.id || opts.id.trim() === '') {
-            throw new NoeticConfigError({
-                code: 'EMPTY_STEP_ID',
-                message: 'step.tool() requires a non-empty id.',
-                hint: 'Pass a unique string as the id field, e.g. step.tool({ id: "my-tool", ... }).',
-            });
-        }
-        if (!opts.tool) {
-            throw new NoeticConfigError({
-                code: 'MISSING_TOOL',
-                message: 'step.tool() requires a tool.',
-                hint: 'Provide a tool definition created with the tool() builder.',
-            });
-        }
+    acpAgent(opts) {
+        validateAcpAgentOpts(opts);
         const built = {
-            kind: 'tool',
+            kind: 'acp-agent',
             ...opts,
         };
         getDefaultRegistrar().register(built);
         return built;
     },
-    /**
-     * Creates a step that delegates a turn to the Claude Code harness.
-     *
-     * @public
-     * @param opts.id - Unique step identifier.
-     * @param opts.harness - A `claudeCode(...)` adapter from `@noetic-tools/sub-harness-claude-code`.
-     * @param opts.prompt - The turn prompt; eager string or `(ctx) => string` getter.
-     * @param opts.settings - Shared harness settings (model, permission mode, …).
-     * @param opts.output - Optional Zod schema enabling structured output parsing.
-     * @returns A `StepSubHarness` of kind `claude-code`, auto-registered in the step registry.
-     * @throws `NoeticConfigError` `EMPTY_STEP_ID` / `MISSING_SUB_HARNESS` / `SUB_HARNESS_KIND_MISMATCH`.
-     */
-    claudeCode(opts) {
-        return buildSubHarnessStep('claude-code', 'step.claudeCode', opts);
-    },
-    /**
-     * Creates a step that delegates a turn to the Codex harness.
-     * @public
-     * @param opts - See {@link step.claudeCode}; `opts.harness` is a `codex(...)` adapter.
-     * @returns A `StepSubHarness` of kind `codex`.
-     */
-    codex(opts) {
-        return buildSubHarnessStep('codex', 'step.codex', opts);
-    },
-    /**
-     * Creates a step that delegates a turn to the opencode harness.
-     * @public
-     * @param opts - See {@link step.claudeCode}; `opts.harness` is an `opencode(...)` adapter.
-     * @returns A `StepSubHarness` of kind `opencode`.
-     */
-    opencode(opts) {
-        return buildSubHarnessStep('opencode', 'step.opencode', opts);
-    },
-    /**
-     * Creates a step that delegates a turn to the pi harness.
-     * @public
-     * @param opts - See {@link step.claudeCode}; `opts.harness` is a `pi(...)` adapter.
-     * @returns A `StepSubHarness` of kind `pi`.
-     */
-    pi(opts) {
-        return buildSubHarnessStep('pi', 'step.pi', opts);
-    },
 };
 //#endregion

package/dist/builders/tool-builder.d.ts

@@ -1,6 +1,5 @@
-import type { FunctionCallItem, FunctionCallOutputItem, Item, ItemSchemaExtensions, Tool, ToolContextDeclaration, ToolExecutionContext, ToolResultExtensionItem, ToolUiDeclaration } from '@noetic-tools/types';
-import type { ZodTypeAny, z } from 'zod';
-interface ToolConfig<I extends ZodTypeAny, O extends ZodTypeAny> {
+import type { FunctionCallItem, FunctionCallOutputItem, InferSchemaOutput, InputSchemaConfig, Item, ItemSchemaExtensions, StandardSchemaV1, Tool, ToolContextDeclaration, ToolExecutionContext, ToolResultExtensionItem, ToolUiDeclaration } from '@noetic-tools/types';
+type ToolConfig<I extends StandardSchemaV1, O extends StandardSchemaV1> = {
     name: string;
     description: string;
     input: I;
@@ -9,21 +8,19 @@ interface ToolConfig<I extends ZodTypeAny, O extends ZodTypeAny> {
     decorateResultItem?: (params: {
         baseItem: FunctionCallOutputItem;
         callItem: FunctionCallItem;
-        args: z.infer<I>;
-        result: z.infer<O> | undefined;
+        args: InferSchemaOutput<I>;
+        result: InferSchemaOutput<O> | undefined;
         output: string;
         error?: boolean;
     }) => Item | ToolResultExtensionItem;
-    execute: (args: z.infer<I>, toolCtx: ToolExecutionContext) => Promise<z.infer<O>>;
+    execute: (args: InferSchemaOutput<I>, toolCtx: ToolExecutionContext) => Promise<InferSchemaOutput<O>>;
     needsApproval?: boolean;
-    /** Optional context declaration — the runtime generates a ContextLayer from this via toolContextLayer(). */
+    /** Optional context declaration — the runtime generates a ContextLayer from this via toolCalls(). */
     context?: ToolContextDeclaration;
-    /** @deprecated Renamed to `context`. */
-    memory?: ToolContextDeclaration;
     /** Optional UI declaration — the runtime emits the rendered fragments at call/progress/result points. */
     ui?: ToolUiDeclaration<I, O>;
-}
-interface GeneratorToolConfig<I extends ZodTypeAny, E extends ZodTypeAny, O extends ZodTypeAny> {
+} & InputSchemaConfig<I>;
+type GeneratorToolConfig<I extends StandardSchemaV1, E extends StandardSchemaV1, O extends StandardSchemaV1> = {
     name: string;
     description: string;
     input: I;
@@ -33,30 +30,29 @@ interface GeneratorToolConfig<I extends ZodTypeAny, E extends ZodTypeAny, O exte
     decorateResultItem?: (params: {
         baseItem: FunctionCallOutputItem;
         callItem: FunctionCallItem;
-        args: z.infer<I>;
-        result: z.infer<O> | undefined;
+        args: InferSchemaOutput<I>;
+        result: InferSchemaOutput<O> | undefined;
         output: string;
         error?: boolean;
     }) => Item | ToolResultExtensionItem;
-    execute: (args: z.infer<I>, toolCtx: ToolExecutionContext) => AsyncGenerator<z.infer<E>, z.infer<O>>;
+    execute: (args: InferSchemaOutput<I>, toolCtx: ToolExecutionContext) => AsyncGenerator<InferSchemaOutput<E>, InferSchemaOutput<O>>;
     needsApproval?: boolean;
-    /** Optional context declaration — the runtime generates a ContextLayer from this via toolContextLayer(). */
+    /** Optional context declaration — the runtime generates a ContextLayer from this via toolCalls(). */
     context?: ToolContextDeclaration;
-    /** @deprecated Renamed to `context`. */
-    memory?: ToolContextDeclaration;
     /** Optional UI declaration — the runtime emits the rendered fragments at call/progress/result points. */
-    ui?: ToolUiDeclaration<I, O, z.infer<E>>;
-}
+    ui?: ToolUiDeclaration<I, O, InferSchemaOutput<E>>;
+} & InputSchemaConfig<I>;
 /**
- * Creates a typed Tool with Zod schema inference for input and output.
+ * Creates a typed Tool with Standard Schema inference for input and output.
+ * Accepts Zod, Valibot, or any Standard Schema v1 implementation.
  *
  * @public
  */
-export declare function tool<I extends ZodTypeAny, O extends ZodTypeAny>(config: ToolConfig<I, O>): Tool<I, O>;
+export declare function tool<I extends StandardSchemaV1, O extends StandardSchemaV1>(config: ToolConfig<I, O>): Tool<I, O>;
 /**
  * Creates a typed Tool that can stream progress events before returning a final output.
  *
  * @public
  */
-export declare function toolWithGenerator<I extends ZodTypeAny, E extends ZodTypeAny, O extends ZodTypeAny>(config: GeneratorToolConfig<I, E, O>): Tool<I, O>;
+export declare function toolWithGenerator<I extends StandardSchemaV1, E extends StandardSchemaV1, O extends StandardSchemaV1>(config: GeneratorToolConfig<I, E, O>): Tool<I, O>;
 export {};

package/dist/builders/tool-builder.js

@@ -1,5 +1,4 @@
 import { NoeticConfigError } from '@noetic-tools/types';
-import { resolveContextOption } from './context-option.js';
 //#endregion
 //#region Helpers
 function validateToolConfig(name, execute) {
@@ -21,7 +20,8 @@ function validateToolConfig(name, execute) {
 //#endregion
 //#region Public API
 /**
- * Creates a typed Tool with Zod schema inference for input and output.
+ * Creates a typed Tool with Standard Schema inference for input and output.
+ * Accepts Zod, Valibot, or any Standard Schema v1 implementation.
  *
  * @public
  */
@@ -32,11 +32,12 @@ export function tool(config) {
         description: config.description,
         input: config.input,
         output: config.output,
+        inputJsonSchema: config.inputJsonSchema,
         itemSchemas: config.itemSchemas,
         decorateResultItem: config.decorateResultItem,
         execute: config.execute,
         needsApproval: config.needsApproval,
-        context: resolveContextOption(config),
+        context: config.context,
         ui: config.ui,
     };
 }
@@ -53,11 +54,12 @@ export function toolWithGenerator(config) {
         input: config.input,
         event: config.event,
         output: config.output,
+        inputJsonSchema: config.inputJsonSchema,
         itemSchemas: config.itemSchemas,
         decorateResultItem: config.decorateResultItem,
         execute: config.execute,
         needsApproval: config.needsApproval,
-        context: resolveContextOption(config),
+        context: config.context,
         ui: config.ui,
     };
 }

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

@@ -1,29 +1,33 @@
 /**
  * Converts a validated `WorkflowDocument` into a live `Step` tree.
  *
- * Each node kind maps to the corresponding builder (`step.llm`, `fork`,
+ * Each node kind maps to the corresponding builder (`callModel`, `inParallel`,
  * `loop`, etc.) so hydrated steps are indistinguishable from programmatic
  * ones — they register in the step registry, carry retry policies, etc.
  */
 import type { ContextData, ContextLayer } from '@noetic-tools/context';
-import type { ExecuteStepFn, OutputCodec, Step, SubHarness, SubHarnessKind, SubprocessAdapter, Tool } from '@noetic-tools/types';
+import type { AcpAgent, ExecuteStepFn, OutputCodec, Step, 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 {
     tools: ReadonlyMap<string, Tool>;
     executeStep: ExecuteStepFn;
     layers?: ReadonlyMap<string, ContextLayer>;
-    /** SubHarness adapters keyed by harness id, resolving `claude-code`/`codex`/… nodes. */
-    subHarnesses?: ReadonlyMap<SubHarnessKind, SubHarness>;
     /**
-     * Output codecs keyed by the `library` ref an `llm` node's `output` codec
+     * ACP agent adapters keyed by `agentId`, resolving an `acp-agent` node's
+     * `agent` field. An OPEN registry — supporting a new agent needs no schema
+     * change, only another entry here.
+     */
+    acpAgents?: ReadonlyMap<string, AcpAgent>;
+    /**
+     * Output codecs keyed by the `library` ref a `callModel` node's `output` codec
      * reference names — the live codec built from a component library, e.g.
      * `new Map([['dashboard-lib', openUi(dashboardLibrary)]])` from
-     * `@noetic-tools/openui`. Resolved the same way sub-harness adapters are.
+     * `@noetic-tools/openui`. Resolved the same way ACP agent adapters are.
      */
     uiLibraries?: ReadonlyMap<string, OutputCodec>;
     /**
-     * Resolves a named subprocess adapter ref declared on a `run` node's
+     * Resolves a named subprocess adapter ref declared on a `runCode` node's
      * `subprocess` field. When a node omits the ref, the step falls back to
      * `ctx.subprocess` at execution time.
      */