Step Union

The Step type is a discriminated union over the kind field:

import type {
  Step,
  StepConditional,
  StepInParallel,
  StepCallModel,
  StepLoop,
  StepWithContext,
  StepRunCode,
  StepSpawn,
  StepInvokeTool,
} from '@noetic-tools/core';

type _AssertShape<TContext, I, O> =
  | StepRunCode<TContext, I, O>
  | StepCallModel<TContext, I, O>
  | StepInvokeTool<TContext, I, O>
  | StepConditional<TContext, I, O>
  | StepInParallel<TContext, I, O>
  | StepSpawn<TContext, I, O>
  | StepWithContext<TContext, I, O>
  | StepLoop<TContext, I, O>;

type _AssertSubset<TContext, I, O> = _AssertShape<TContext, I, O> extends Step<TContext, I, O>
  ? true
  : false;

The exported Step union additionally includes StepSchedule for fixed-interval scheduling.

StepRunCode

StepRunCode<TContext, I, O>

Field	Type	Required	Description
`kind`	`'runCode'`	yes	Discriminant
`id`	`string`	yes	Step identifier
`execute`	`(input: I, ctx: Context<TContext>) => Promise<O>`	yes	Async function to execute
`retry`	`RetryPolicy`	no	Retry configuration

StepCallModel

StepCallModel<TContext, I, O>

Field	Type	Required	Description
`kind`	`'callModel'`	yes	Discriminant
`id`	`string`	yes	Step identifier
`model`	`string`	yes	Model identifier
`instructions`	`string`	no	System prompt / instructions for the model
`tools`	`Tool[]`	no	Allowed tool subset (`undefined` = all, `[]` = none)
`output`	`StandardSchemaV1<unknown, O> \| OutputCodec<O>`	no	Structured output schema (any Standard Schema v1; Zod is the default) or a streaming codec
`outputJsonSchema`	`Record<string, unknown>`	no	Explicit JSON Schema override/fallback for non-Zod output. Conversion order is Zod → StandardJSONSchemaV1 → this field; validation-only schemas require it
`params`	`ModelParams`	no	Sampling parameters
`emit`	`boolean \| ((eventType, data) => boolean)`	no	Controls framework event emission for this step. Defaults to `true`. Pass `false` to suppress all framework events, or a filter function to allow specific events through.

StepInvokeTool

StepInvokeTool<TContext, I, O>

Field	Type	Required	Description
`kind`	`'invokeTool'`	yes	Discriminant
`id`	`string`	yes	Step identifier
`tool`	`Tool<StandardSchemaV1<unknown, I>, StandardSchemaV1<unknown, O>>`	yes	Tool definition
`args`	`Partial<I>`	no	Preset arguments

StepConditional

StepConditional<TContext, I, O>

Field	Type	Required	Description
`kind`	`'conditional'`	yes	Discriminant
`id`	`string`	yes	Step identifier
`route`	`(input: I, ctx: Context<TContext>) => Step<TContext, I, O> \| null`	yes	Routing function (null skips)

StepInParallel

inParallel has three mode variants, each a separate interface.

StepInParallelRace

StepInParallelRace<TContext, I, O>

Field	Type	Required	Description
`kind`	`'inParallel'`	yes	Discriminant
`id`	`string`	yes	Step identifier
`mode`	`'race'`	yes	First completion wins
`paths`	`(input: I, ctx: Context<TContext>) => Step<TContext, I, O>[]`	yes	Path factory
`concurrency`	`number`	no	Max parallel paths

StepInParallelAll

StepInParallelAll<TContext, I, O>

Field	Type	Required	Description
`kind`	`'inParallel'`	yes	Discriminant
`id`	`string`	yes	Step identifier
`mode`	`'all'`	yes	Wait for all paths
`paths`	`(input: I, ctx: Context<TContext>) => Step<TContext, I, O>[]`	yes	Path factory
`merge`	`(results: O[], ctx: Context<TContext>) => O`	yes	Merge function
`concurrency`	`number`	no	Max parallel paths

StepInParallelSettle

StepInParallelSettle<TContext, I, O>

Field	Type	Required	Description
`kind`	`'inParallel'`	yes	Discriminant
`id`	`string`	yes	Step identifier
`mode`	`'settle'`	yes	Wait for all, include errors
`paths`	`(input: I, ctx: Context<TContext>) => Step<TContext, I, O>[]`	yes	Path factory
`merge`	`(results: SettleResult<O>[], ctx: Context<TContext>) => O`	yes	Merge function
`concurrency`	`number`	no	Max parallel paths

StepWithContext

StepWithContext<TContext, I, O>

Field	Type	Required	Description
`kind`	`'withContext'`	yes	Discriminant
`id`	`string`	yes	Step identifier
`child`	`Step<TContext, I, O>`	yes	Child step to execute with the provided layers
`context`	`ContextConfig \| ContextLayer[]`	yes	Context layers available to all descendant steps

StepSpawn

StepSpawn<TContext, I, O>

Field	Type	Required	Description
`kind`	`'spawn'`	yes	Discriminant
`id`	`string`	yes	Step identifier
`child`	`Step<TContext, I, O>`	yes	Child step to execute
`context`	`ContextConfig \| ContextLayer[]`	no	Spawn-local context layers
`timeout`	`number`	no	Timeout in milliseconds

StepLoop

StepLoop<TContext, I, O>

Field	Type	Required	Description
`kind`	`'loop'`	yes	Discriminant
`id`	`string`	yes	Step identifier
`steps`	`ReadonlyArray<Step<TContext, I, O>>`	yes	Loop body steps
`until`	`Until`	yes	Termination predicate
`maxIterations`	`number`	no	Safety limit on iterations
`maxHistorySize`	`number`	no	Max history items to retain
`inbox`	`Channel<string>`	no	Channel for external messages that prevent loop from stopping
`parkTimeout`	`number`	no	Milliseconds to wait on inbox before stopping (0 = non-blocking)
`prepareNext`	`(output: O, verdict: Verdict, ctx: Context<TContext>) => I`	no	Transform output to next input
`onError`	`(error: NoeticError, ctx: Context<TContext>) => 'retry' \| 'skip' \| 'abort'`	no	Error handler

A step that runs a body step on a fixed-interval schedule, optionally woken sooner by a wake channel. Runs forever until the executing context is cancelled. The operator output is void — schedule does not accumulate iteration outputs.

Field	Type	Required	Description
`kind`	`'schedule'`	yes	Discriminant
`id`	`string`	yes	Step identifier
`step`	`Step<TContext, I, O>`	yes	Body step executed on each iteration
`interval`	`number`	yes	Park duration between iterations in milliseconds. Must be `>= 0`.
`inbox`	`Channel<unknown>`	no	Channel that wakes the parking interval when any value arrives
`onError`	`'continue' \| 'fail'`	no	Behavior when `step` throws. Defaults to `'continue'` (record the error and keep parking).
`jitter`	`number`	no	Random jitter applied to the park duration in milliseconds. Must be `>= 0`. Defaults to `0`.

Supporting Types

SettleResult

Field	Type	Description
`stepId`	`string`	Step that produced this result
`status`	`'fulfilled' \| 'rejected'`	Outcome
`value`	`O`	Present if fulfilled
`error`	`NoeticError`	Present if rejected

RetryPolicy

Field	Type	Description
`maxAttempts`	`number`	Maximum retry attempts
`backoff`	`'fixed' \| 'linear' \| 'exponential'`	Backoff strategy
`initialDelay`	`number`	Initial delay in milliseconds
`maxDelay`	`number`	Maximum delay cap (optional)

ModelParams

Field	Type	Description
`temperature`	`number`	Sampling temperature (optional)
`topP`	`number`	Nucleus sampling (optional)
`maxTokens`	`number`	Max response tokens (optional)
`stopSequences`	`string[]`	Stop sequences (optional)

Tool

Field	Type	Description
`name`	`string`	Tool name (used by the LLM for selection).
`description`	`string`	Tool description shown to the LLM.
`input`	`StandardSchemaV1<I>`	Schema validating tool input arguments (any Standard Schema v1; Zod is the default).
`output`	`StandardSchemaV1<O>`	Schema validating tool return value.
`inputJsonSchema`	`Record<string, unknown>`	Explicit JSON Schema override/fallback for non-Zod input. Conversion order is Zod → StandardJSONSchemaV1 → this field; validation-only schemas require it.
`event`	`StandardSchemaV1`	Optional schema validating streaming events yielded during execution.
`itemSchemas`	`ItemSchemaExtensions`	Optional item schemas for tool-call/result extensions contributed by this tool. `toolResults` schemas are owner-scoped: they validate only this tool's own result items and never reject a sibling tool's results. Schemas are pure shape validators (gates, not normalizers) — the original item is returned on match, and Zod transforms/defaults are unsupported.
`decorateResultItem`	`(params) => Item`	Decorate the harness-created tool-result item before it is appended/emitted. The decorated item must satisfy this tool's own `itemSchemas.toolResults` (when declared) — including for error outputs such as malformed-arguments results — or the round fails with `NoeticError` kind `item_schema_mismatch`.
`execute`	`(args: InferSchemaOutput<I>, toolCtx: ToolExecutionContext) => Promise<InferSchemaOutput<O>> \| AsyncGenerator<unknown, InferSchemaOutput<O>>`	Async function (or generator) that performs the tool's work. `InferSchemaOutput` is `z.output` for Zod schemas and `StandardSchemaV1.InferOutput` otherwise.
`needsApproval`	`boolean`	Optional. When `true`, execution pauses for human approval before running.
`context`	`ToolContextDeclaration`	Optional. Declares tool-owned state the runtime materializes into a `ContextLayer`.

ExecuteStepFn

declare const executeStepShape: <TContext, I, O>(
  step: Step<TContext, I, O>,
  input: I,
  ctx: Context<TContext>,
) => Promise<O>;

Step Types