Orchestrator-Workers

Single round

Implement the Orchestrator-Workers pattern in this codebase, using the LLM client and language we already use.

## Goal

Carry out a task whose subtasks cannot be known in advance: an orchestrator model plans them at run time, workers do them in parallel, and the orchestrator combines the results.

## How it works

1. Call the orchestrator with the Orchestrator planning prompt, filling in the task, and parse the JSON reply into a list of subtasks, each with a target and an instruction.
2. Check the plan in code: at least one subtask, no more than the cap, and every subtask has a non-empty target and instruction. If the reply is not valid JSON or fails the check, re-ask once with the error, then stop with that error.
3. Start one worker per subtask, concurrently, with the Worker prompt; each worker sees only its own target and instruction.
4. Collect every worker's result, keyed by target. A worker that errors is retried once, then recorded as failed with its error.
5. Call the orchestrator again with the Synthesis prompt, passing the task and all the results, failures included, and return its combined answer.

## Prompts

### Orchestrator planning prompt

```markdown
Break the task below into independent subtasks, one per file or
source that needs separate work. Do not invent work the task does
not need.

<task>{{task}}</task>

Respond in JSON:
{"subtasks": [{"target": "...", "instruction": "self-contained instructions"}]}
```

### Worker prompt

```markdown
You are handling one part of a larger task. Do only this part.

<target>{{subtask.target}}</target>
<instruction>{{subtask.instruction}}</instruction>

Return the finished change and a one-line note on anything you
could not do.
```

### Synthesis prompt

```markdown
Combine the worker results into one coherent answer for the task.
Flag any conflicts between workers and resolve them.

<task>{{task}}</task>
<results>{{results}}</results>
```

## Stop rule

One plan, one round of workers and one synthesis, then stop. The orchestrator does not spawn a second round; if work is missing, the synthesis says so.

## Requirements

- Cap the number of subtasks (default 8) and the number of workers running at once (default 4).
- Make each worker's instruction self-contained: a worker gets no shared history and cannot see the other workers.
- The synthesis must list every failed subtask and every conflict between workers, never drop them.
- Log the plan, each worker's input, output and latency, and the synthesis input, under one run id.
- Add a test with a stub LLM whose plan has 3 subtasks; assert 3 worker calls with distinct targets and one synthesis call whose input holds all 3 results.

Iterative rounds

Implement the Orchestrator-Workers pattern (Iterative rounds variant) in this codebase, using the LLM client and language we already use.

## Goal

Answer a research question with a lead model that sends out rounds of parallel subagents, decides after each round whether more research is needed, and passes the final report to a citation step.

## How it works

1. Call the lead with the Lead agent prompt, passing the question and the findings so far (none in round 1), and parse the JSON reply into done, subtasks and, when done, a report.
2. If done is false, start one subagent per subtask, concurrently, with the Subagent prompt; each has its own search tools and returns findings with their source URLs.
3. Append every subagent's findings to a findings store kept outside the lead's context; a subagent that errors or hits its tool-call cap returns what it has with a note saying so.
4. Call the lead again with the question and all the stored findings, and repeat until it replies done. When the round cap is reached, call it once more with final_round set, which requires a report.
5. Send the report and the findings to the citation step with the Citation prompt, which attaches a source to every claim, and return the cited report.

## Prompts

### Lead agent prompt

```markdown
You lead a research team. Decide what still needs finding out
to answer the question well, and split it into independent
subtasks for parallel researchers (at most {{max_subagents}}).

<question>{{question}}</question>
<findings>{{findings}}</findings>

Respond in JSON. If more research is needed:
{"done": false, "subtasks": [{"objective": "...", "where_to_look": "..."}]}
If the findings are enough:
{"done": true, "report": "the full answer, written from the findings"}

{{#if final_round}}
This is the last round: you must reply with done true and write
the best report the findings support, naming any gaps.
{{/if}}
```

### Subagent prompt

```markdown
You are one of several researchers working in parallel. Research
only this objective, using your search tools, and stop when you
have solid answers or after {{max_tool_calls}} tool calls.

<objective>{{objective}}</objective>
<hints>{{where_to_look}}</hints>

Return your findings as short statements, each with its source URL.
```

### Citation prompt

```markdown
Add citations to the report below. For every factual claim, attach
the URL from the findings that supports it. If no finding supports
a claim, mark it [unsourced]; never invent a source.

<report>{{report}}</report>
<findings>{{findings}}</findings>
```

## Stop rule

Stop when the lead replies done, or after 3 rounds. After the last round the lead is called once with final_round set and must write a report, noting gaps, which is marked incomplete. If that reply is still not a report, return the raw findings marked incomplete. The citation step runs once on any report.

## Requirements

- Cap rounds (default 3), subagents per round (default 5) and tool calls per subagent (default 10), all as parameters.
- If the lead's reply is not valid JSON, retry once with the parse error; if it fails again, take the final-round path: call the lead with final_round set, and fall back to the raw findings marked incomplete.
- Store the plan and the findings outside the lead's context, so a long run can be resumed and the lead re-reads only what it needs.
- The citation step may only cite URLs that appear in the findings; flag any claim it cannot source instead of inventing one.
- Add a test with a stub LLM whose lead returns 3 subtasks, then 2, then done; assert 5 subagent calls, 3 lead calls and 1 citation call.