Step Types

Step Union

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

import type {
  Step,
  StepConditional,
  StepDecide,
  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>
  | StepDecide<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 and StepSequence, what an array of steps becomes.

StepReplay

Every step interface extends StepReplay<TContext, I>, so these fields apply to every row below. See Replay Identity.

StepEmitItems

Every step interface also extends StepEmitItems<TContext, I, O, M>. See Emitting Items Early and Custom Items.

StepRunCode

StepRunCode<TContext, I, O>

StepCallModel

StepCallModel<TContext, I, O>

StepInvokeTool

StepInvokeTool<TContext, I, O>

StepDecide

StepDecide<TContext, I, O>

A step that asks a model typed questions and returns typed answers with probabilities. It reads the conversation but never appends to it, and runs no steering hooks. Built by decide().

DecideStep

type DecideStep<TContext, I, Q extends DecideQuestions> =
  StepDecide<TContext, I, DecideAnswers<Q>> & { readonly questions: Q };

What decide() returns: a StepDecide that keeps its literal question map, so routeSwitch can infer the questions, choices, and levels it routes by. DecideAnswers<Q> maps each question id to its answer type or Refusal; AnsweredAll<Q> is the same with Refusal removed.

decide() infers Q from questions; pass it no type arguments. To type ctx.context in the context selector, annotate its parameter ((ctx: Context<MyContext>) => …).

Questions and answers

type DecideQuestions = Readonly<Record<string, DecideQuestion>>;
type DecideQuestion = BooleanQuestion | ChoiceQuestion | ScoreQuestion;

interface BooleanQuestion {
  type: 'boolean';
  instructions?: string;
  criteria?: { true?: string; false?: string };
  threshold?: number;
}

interface ChoiceQuestion<K extends string = string> {
  type: 'choice';
  instructions?: string;
  choices: readonly K[] | Readonly<Record<K, string>>;
}

interface ScoreQuestion<L extends string = string> {
  type: 'score';
  instructions?: string;
  levels: readonly L[] | ReadonlyArray<{ label: L; description?: string }>;
}

type DecideAnswer = BooleanAnswer | ChoiceAnswer | ScoreAnswer | Refusal;

interface BooleanAnswer {
  type: 'boolean';
  value: boolean;
  probability: number;
}

interface ChoiceAnswer<K extends string = string> {
  type: 'choice';
  value: K;
  confidence: number;
  probabilities: Readonly<Record<K, number>>;
}

interface ScoreAnswer<L extends string = string> {
  type: 'score';
  value: number;
  level: L;
  confidence: number;
  probabilities: Readonly<Record<L, number>>;
}

interface Refusal {
  type: 'refusal';
}

See decide for what each field means.

StepConditional

StepConditional<TContext, I, O>

StepInParallel

inParallel has three mode variants, each a separate interface.

StepInParallelRace

StepInParallelRace<TContext, I, O>

StepInParallelAll

StepInParallelAll<TContext, I, O>

StepInParallelSettle

StepInParallelSettle<TContext, I, O>

StepWithContext

StepWithContext<TContext, I, O>

StepSpawn

StepSpawn<TContext, I, O>

StepLoop

StepLoop<TContext, I, O>

StepSequence

StepSequence<TContext, I, O>

What an array of steps becomes. An array of steps runs in sequence, each step's output the next one's input, wherever these take a step: harness.run and ctx.harness.run, harness.detachedSpawn and ctx.harness.detachedSpawn, agentGraph, spawn and withContext children, schedule bodies, inParallel paths, a conditional route's pick, and when/otherwise clauses. There is no step.sequence; write the array.

A loop's steps, a wait's around and a verify's act take a list of single steps and run it in sequence themselves, without a sequence step. decide/routeSwitch cases (and uncertain/default) and a loop's until decide step take a single step only.

An empty array throws EMPTY_STEP_ARRAY; a one-element array is its element. An element that is not a step (a nested array, null, an object without a step kind and string id) throws INVALID_STEP_IN_ARRAY: nested arrays are rejected, not flattened. The sequence keeps a frozen copy of the array, so changing the array after building changes nothing.

StepArray, StepArrayInput and StepArrayOutput

import { AgentHarness, runCode } from '@noetic-tools/core';

const trim = runCode({ id: 'trim', execute: async (input: string) => input.trim() });
const count = runCode({ id: 'count', execute: async (input: string) => input.length });

const harness = new AgentHarness({ name: 'arrays', params: {} });
const length: number = await harness.run([trim, count], '  hi  ', harness.createContext());

Each element is a StepLike: an object with a step kind and that kind's required fields, so a bare { kind, id } lookalike is not a step. Every step carries a type-only marker, '~types'?: StepTypes<I, O> (never set at runtime), from which an element's input and output are read. run and detachedSpawn infer the array as a tuple and check every link (ValidStepChain<T>): each step must take the previous step's output, unless that output is typed unknown (as a call step's is). The input is the first step's (StepsInput<T>, StepArrayInput<T>) and the output the last step's (StepsOutput<T>, StepArrayOutput<T>). They also accept a Step<C, T, T>[] variable and a Steps<C, I, O> value passed through generic code.

Steps<TContext, I, O> is what the builders and agentGraph accept: a step, a StepChain<I, O> (a non-empty tuple whose first step takes I and last step outputs O), or HomogeneousSteps<TContext, I, O> (an array of Step<TContext, T, T> when I and O are both T). A builder checks an array's ends against its I and O; only run and detachedSpawn check the links between.

StepSchedule

StepSchedule<TContext, I, O>

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.

Supporting Types

SettleResult

MergeFn

MergeFn<TContext, O, R = O> combines inParallel path results into one output. R is the element type of results: O in all mode, SettleResult<O> in settle mode.

type MergeFn<TContext = ContextData, O = unknown, R = O> = (
  results: R[],
  ctx: Context<TContext>,
) => O;

RetryPolicy

ModelParams

ToolChoice

ToolChoiceMode | { tool: string }. ToolChoiceMode is an ESM literal enum: Auto ('auto'), Required ('required'), None ('none'). { tool } forces one client tool by name.

Tool

ExecuteStepFn

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

StepInput and StepOutput

import { runCode } from '@noetic-tools/core';
import type { StepInput, StepOutput } from '@noetic-tools/core';

const count = runCode({ id: 'count', execute: async (input: string) => input.length });

type CountIn = StepInput<typeof count>;   // string
type CountOut = StepOutput<typeof count>; // number

Pull a step's input or output type out of its type. routeSwitch uses them to type its output as the union of every case's output.