<!-- Generated by scripts/gen-docs.ts from the TSDoc in src/. Do not edit by hand. -->

# `flow/run/flow`

Source: [`src/flow/run/flow.ts`](https://github.com/AI-for-dev/combo/blob/main/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*

```typescript
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*

```typescript
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*

```typescript
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.