flow/run/flow

Source: src/flow/run/flow.ts

runFlow: a checked run walked from its first node to its last.

It takes a CheckedRun and nothing else of the world: the working tree, the ports and each check script’s content were fixed by checkRun, so a flow checked against one project cannot run in another. The runner reaches git through the git port only, and the disk through its run directory only, when it is given one.

FlowResult

type

export type FlowResult =
	| { readonly ok: true; readonly output?: unknown; readonly usage: Usage }
	| { readonly ok: false; readonly error: FlowError; readonly path: string; readonly usage: Usage };

How a run ended. output is the last root node’s; a failure names the visit it started at. usage sums every visit, wallMs being the run’s.

runFlow

function

export async function runFlow(run: CheckedRun, input: unknown, options: RunFlowOptions = {}): Promise<FlowResult> { /* … */ }

Runs run on input. Given runDir, the run directory first receives the snapshot, then the journal as the run goes, and the run holds its lock until it ends.

Throws, before anything is spawned, on an input off the flow’s input:, and on a run directory that already holds a run: that is the caller’s mistake, not a run that went wrong. Every other failure is a result.

RunFlowOptions

type

export type RunFlowOptions = {
	/** Defaults to the real `spawn`. Pass a `stopSwitch`'s, with its `signal`, to stop a visit or the run. */
	spawn?: SpawnFn;
	/** Aborting it stops the run: no node starts, and nothing catches the failure. Declining a card that offers no "enough" does the same. */
	signal?: AbortSignal;
	/** The run's events, its visits and its subagents' alike. */
	onEvent?: EventListener;
	/** The model of every agent turn, over the flow's `model:` and each agent's own. */
	model?: string;
	/** The bound of every agent turn, over each node's `timeout:` and the flow's. A check keeps its own. */
	timeoutMs?: number;
	/**
	 * The run directory, which holds the snapshot, the journal and each
	 * subagent's transcript, and where a `measuredRun` leaves `usage.json`.
	 * Absent, nothing touches the disk, and the run cannot be resumed.
	 */
	runDir?: string;
};

What a run varies. Each defaults to the real thing.