Flow

Flow is the durable workflow boundary. One Flow subclass corresponds to one registered name, one default model selection, one step registry, one tool registry, and exactly one flow envelope inside a session document.

export abstract class Flow {
  static get id(): string;          // defaults to the class name
  public constructor();
  protected abstract configModel(): ModelSelection;
  protected configLlmCallPolicy(): LlmCallPolicy;
}

A flow instance is constructed fresh for every request and thrown away when the turn ends. Nothing on the instance survives except what is written into the session document.

Subclass hooks

configModel()

protected abstract configModel(): ModelSelection;

Declares the flow’s default provider, model, parameters, and runner retry policy, independently from step composition. It is resolved lazily on first use, validated through PicoModelCatalog, and then validated again against the registered provider adapter during bootstrap.

protected configModel() {
  return {
    provider: "openai",
    name: "gpt-4o",
    params: { temperature: 0.2 },
    retryAttempts: 3,
  } as const;
}

Every step without its own useModel(...) override inherits this selection, including retryAttempts. See Model catalog for the typing rules.

configLlmCallPolicy()

protected configLlmCallPolicy(): LlmCallPolicy;

Declares code-owned policy for each model invocation attempt independently from provider parameters. { timeoutMs: 60_000 } applies to every Step by default. A Step may override the same hook with another positive integer, or return { timeoutMs: null } to remove the inherited deadline. The policy is not persisted in the session document.

init()

public async init(): Promise<void>;

Called by FlowCreator.create() after the request config has been added as context, but before collectSteps() and before bootstrap() binds the FlowEngine. getFlowEngine() therefore throws inside init(). Use it only for setup that needs neither the engine nor a loaded session.

defineSteps()

protected defineSteps(): Step[];

Constructs the step registry. Steps are keyed by Step.id, which defaults to the class name, so the returned array is a registry rather than a graph — transitions live in the handlers.

protected defineSteps(): Step[] {
  return [
    new CollectCustomerStep(this).useMemory("customer"),
    new TerminateSessionStep(this).useMemory("end"),
  ];
}

Any step reachable by go(...), runStep(...), runSteps(...), or a logic response must appear here. Registering a different set of steps between turns can strand a restored session whose flow.currentStep no longer resolves.

initialStep()

protected initialStep(): StepClassType | null;

Returns the class whose id becomes flow.currentStep for a new session. Returning null selects the first entry of defineSteps(). A returned class that is not registered fails during document creation with Initial step '<name>' is not defined in flow '<id>'.

protected initialStep() {
  return this.getContext<boolean>("config.isPresident")
    ? PresidentStep
    : WeatherStep;
}

defineTool()

public defineTool(): ToolType[];

Flow-level tool definitions. They are merged with every step’s defineTool() into one flow-wide registry during bootstrap(). Duplicate names throw Duplicate tool '<name>' registered in flow '<id>'. See Defining and handling tools.

onRestoreSessionDoc()

protected async onRestoreSessionDoc(
  sessionDoc: SessionType,
): Promise<SessionType | null>;

The compatibility boundary for a stored session. Return the (optionally mutated) document to continue restoring it; return null to abandon it and create a fresh session document.

The default implementation is:

if (!this.isSessionCurrent(sessionDoc)) return null;
return sessionDoc;

isSessionCurrent(doc) compares doc.version against K.sessionDocVersion. sessionIdleMs(doc) returns the time since saveOn, allowing an override to enforce its own idle policy. Both are protected and overridable.

When the hook returns a document, bootstrap() saves it immediately through the normal compare-and-swap path before reading step state. The hook runs only for a document that already exists, is not completed or aborted, belongs to this flow, and satisfies the one-flow invariant. See Session document migration.

spawnSteps()

protected async spawnSteps(): Promise<string>;

Called by run() instead of the current step when getContext<boolean>('config._concurrent') is truthy. Pair it with concurrentSteps(...):

public async concurrentSteps<T>(options: {
  items: T[];
  batchSize: number;
  onConfig: (item: T) => object;
  onBotResponse: (item: T, response: any) => void;
}): Promise<void>;

concurrentSteps() slices items into sequential batches, runs each batch with Promise.all, and issues one SelfClient POST per item to SELF_URL carrying { flowName, config }. Each item therefore gets its own session document. Returning a string from spawnSteps() does not complete the coordinator session; call markCompleted() or sessionCompleted() explicitly. See Concurrent batch mode.

run()

public async run(message: string): Promise<RunResponseType>;

type RunResponseType = {
  success: boolean;
  completed: boolean;
  message: string;
  session: string;
  contentType: HttpContentType;
};

completed is requireCurrentStep().isEnd() and contentType is that same step’s contentType. Overriding run() takes over cursor selection, completion reporting, and content conversion; prefer step hooks.

isBatch()

public isBatch(): boolean;

When true, FlowEngine saves the session once before calling run(). It does not select the spawnSteps() path — that is decided by config._concurrent.

Flow-owned data and helpers

Cursor movement

Both throw if called from inside a nested execution frame: Cannot goto '<name>' from a child execution frame. A child returns a result to its owner instead. Moving to the step that is already current is a no-op.

Context

Context is seeded from the first request’s config, stored as { config: ... }, and persisted in flow.context. getContext is a lodash path read, so getContext<string>('config.tenantId') works. A restored session keeps its stored context; a new config on a later turn does not replace it.

Step state

SaveStateType is an enum with transient and persistent; persistent is the default. Transient state is stored under the _transient key and stripped on write. All three throw if the class is not registered.

Memory

public getMemory(): Memory;
public getMemory(nameSpace: string): MessageTypes[];

The no-argument form returns the flow’s Memory container, which is where summary policy is configured:

this.getMemory()
  .setSummaryModel({ provider: "openai", name: "gpt-4o" })
  .setSummaryConfig({ minMessages: 16, recentMessages: 8 })
  .enableSummary("conversation");

The string form returns the raw message array for one namespace. Namespaces must match /^[A-Za-z][A-Za-z0-9_-]{0,127}$/. Compaction runs inside saveSession(); a failure is recorded as a session warning rather than failing the turn.

Session access and completion

Overriding static get id() decouples the public flow name from a TypeScript class rename. The registered name must equal FlowClass.id — see FlowEngine.

Step and tool lookup

getCurrentStep() reads the durable cursor. getExecutingStep() returns the innermost step of the current nested execution frame, falling back to the durable cursor when no frame is open — that is the accessor the runner uses.

Runtime plumbing

These are public because the runtime uses the same class. Application flows should not call or override them: bootstrap, collectSteps, saveSession, tallyToken, setMemory, withNestedSequence, and enterChild.

The rest of the reference