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

# `workflows/orchestrate`

Source: [`src/workflows/orchestrate.ts`](https://github.com/AI-for-dev/combo/blob/main/src/workflows/orchestrate.ts)

`orchestrate`: 1 → ?. An agent *decides* the split, then the split runs.

How that decision is read - and why it is a parsed convention rather than a
tool call - lives in `plan.ts`. What is left here is the shape: plan, fan out
over it, optionally synthesise.

## `orchestrate`

*function*

```typescript
export async function orchestrate(options: OrchestrateOptions): Promise<OrchestrateResult> { /* … */ }
```

Asks an agent to split the work, then runs the split it asked for.

This is a **dynamic** fan-out: unlike {@link fanOut}, nobody wrote the tasks
in advance. Everything else is the same machinery - bounded concurrency, one
subagent per branch, no shared state - because a plan the model wrote deserves
no more trust than a plan the caller wrote, and a good deal less latitude.

## `OrchestrateOptions`

*type*

```typescript
export type OrchestrateOptions = PlanOptions & {
	/** Subtasks in flight at once, as in {@link fanOut}. Defaults to 4. */
	concurrency?: number;
	/** When given, this agent turns the subtask results into one answer. */
	reduceWith?: Agent;
};
```

{@link PlanOptions}, plus how the planned subtasks are run and folded.

## `OrchestrateResult`

*type*

```typescript
export type OrchestrateResult = WorkflowResult & {
	/** What the planner asked for, after validation. Empty when planning failed. */
	plan: PlannedTask[];
	/** The planner's own turn. Kept whatever happened next. */
	planning: Result;
	/** One result per planned subtask, in plan order. */
	results: Result[];
	/** The synthesis, present only when `reduceWith` was given. */
	answer?: Result;
};
```

The plan, what it produced, and optionally the one answer it was folded into.

As a `Result`: the synthesis when `reduceWith` was given, otherwise the
planner's turn with the subtasks' outputs, labelled, where its own would be.
`usage` covers planning, subtasks and synthesis over the whole run; `ok` is
false when the planning failed, produced nothing runnable, or a subtask
failed. `steps` is the planner's turn, every subtask, then the synthesis.