Supervisor

One step at a time

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

## Goal

Turn a task into a finished deliverable by having a supervisor agent delegate one step at a time to specialist agents, each with its own tools, and read every result before choosing the next step.

## How it works

1. Define each specialist as a full agent with its own instructions, tools and loop, and write a one-line description of each for the supervisor.
2. Call the supervisor with the Supervisor prompt, filling in the team descriptions, the task and the results so far, and parse its JSON reply into action, agent, instruction and answer.
3. If action is delegate, run the named specialist with the Specialist agent prompt and the instruction as its brief; it runs its own tool loop and returns a short report.
4. Append the agent name, the instruction and the report to the results list, then call the supervisor again.
5. If action is finish, return the answer together with the results list.
6. A specialist may lead a sub-team of its own: it runs this same loop over its sub-agents and reports one summarized result upward.

## Prompts

### Supervisor prompt

```markdown
You lead a team of specialist agents. You never do the work yourself.

<team>
{{team_descriptions}}
</team>

<task>{{task}}</task>
<results_so_far>{{history}}</results_so_far>

Choose the next step. Respond in JSON:
{"action": "delegate" | "finish",
 "agent": "<name from the team>",
 "instruction": "a self-contained brief with the goal and what to return",
 "answer": "only when finishing: the final deliverable"}
Delegate one step at a time. Finish only when the task is fully done.
```

### Specialist agent prompt

```markdown
You are the {{role}} on a team. You have these tools: {{tools}}.

Your supervisor gave you this brief:
<brief>{{instruction}}</brief>

Do exactly what the brief asks, using your tools as needed.
Report back concisely: what you did, what you found, and anything you could not do.
```

## Stop rule

Stop when the supervisor returns finish, or after 8 delegations. On the cap, return the results gathered so far with a status saying the task was not finished.

## Requirements

- Cap delegations per task (default 8) and tool calls per specialist run (default 10).
- If the supervisor's reply is not valid JSON or names an agent not on the team, retry once with the error appended, then stop with a failed status.
- If a specialist errors or hits its cap, return that as its report, so the supervisor can retry, reassign or finish; never crash the run.
- Give each specialist only its brief, not the supervisor's history, and keep the specialist's own tool calls out of the supervisor's context.
- Log each delegation with the agent, the instruction, the report, the tokens and the duration.
- Add a test with a stub supervisor that delegates to the researcher, then the coder, then finishes; assert exactly two specialist runs in that order and that the finish answer is returned.

Parallel subagents

Implement the Supervisor pattern (Parallel subagents variant) in this codebase, using the LLM client and language we already use.

## Goal

Answer a broad research question by having a lead agent plan, run several subagents in parallel on separate parts of it, and combine their condensed findings into one cited report.

## How it works

1. Call the lead agent with the Lead agent prompt and the question; parse its JSON into action, subtasks (objective, output, tools, boundaries) and report, and save its plan to memory before spawning anything.
2. For each subtask, start a subagent with the Subagent prompt, a fresh context and only that brief; run all of them in parallel.
3. Each subagent runs its own tool loop and returns condensed findings with a source for each fact, or an error saying what it could not find.
4. Reload the plan from memory, and call the lead again with every finding so far; it either spawns more subtasks for the gaps or replies done with a draft report.
5. Send the draft and every source to the citation agent with the Citation agent prompt, and return the cited report.

## Prompts

### Lead agent prompt

```markdown
You lead a research effort. You plan and delegate; subagents do the searching.

<question>{{question}}</question>
<plan>{{plan}}</plan>
<findings_so_far>{{findings}}</findings_so_far>

Decide whether the findings answer the question. Respond in JSON:
{"action": "spawn" | "done",
 "subtasks": [{"objective": "...", "output": "what to return",
               "tools": ["..."], "boundaries": "what not to cover"}],
 "report": "only when done: the full answer, a source for each claim"}
Spawn only subtasks that do not overlap each other or the findings so far.
Use 1 subagent for a simple fact, 2 to 4 for a comparison.
```

### Subagent prompt

```markdown
You are a research subagent. Work only on this brief:
<objective>{{objective}}</objective>
Return: {{output}}. Do not cover: {{boundaries}}.

Use your tools ({{tools}}). Start with broad searches, then narrow down.
Stop when you can answer, or after {{max_tool_calls}} tool calls.
Reply with condensed findings in under 300 words, a source for each fact,
and anything you could not find.
```

### Citation agent prompt

```markdown
Add citations to the report below. Do not change its wording or its claims.

<report>{{report}}</report>
<sources>{{sources}}</sources>

After each claim, cite the source that supports it.
List any claim that no source supports under "Unsupported claims".
```

## Stop rule

Stop when the lead replies done, or after 3 spawn rounds. On the cap, have the lead write the report from what it has and list the open questions in it.

## Requirements

- Cap subagents per round (default 4), spawn rounds (default 3) and tool calls per subagent (default 15). If the lead asks for more subagents than the cap, run the first 4 and return the rest to the lead as not yet run.
- Give each subagent a timeout (default 5 minutes); report a timeout or crash to the lead as that subagent's finding instead of dropping it.
- Subagents never see each other's context or the lead's; they get only their brief.
- If the lead's reply is not valid JSON, retry once with the parse error, then write the report from the findings so far.
- Add a test with a stub lead that spawns two subagents and then replies done; assert both subagents started before either finished, and the citation agent ran once.

Ledger orchestrator

Implement the Supervisor pattern (Ledger orchestrator variant) in this codebase, using the LLM client and language we already use.

## Goal

Complete an open-ended task with a team of worker agents by keeping a written plan and a per-turn progress check, and replanning whenever progress stalls.

## How it works

1. Call the orchestrator with the Task ledger prompt to fill the task ledger: the given facts, facts to look up, educated guesses and a step-by-step plan.
2. Each turn, call the orchestrator with the Progress ledger prompt, passing the task ledger and the turn history, and parse its JSON into is_complete, is_progressing, is_in_loop, next_speaker and instruction.
3. If is_complete is true, ask the orchestrator for the final answer from the history and return it.
4. Otherwise send the instruction to the agent named in next_speaker, run it, and append its reply, or its error, to the history.
5. If the turn was not progressing or was in a loop, add one to a stall counter; otherwise reset the counter to zero.
6. When the stall counter exceeds the stall threshold (default 2), run the Task ledger prompt again with everything learned so far to update the facts, guesses and plan; then reset the counter and clear the workers' history.

## Prompts

### Task ledger prompt

```markdown
You lead a team: {{team_descriptions}}.

<task>{{task}}</task>
{{#if history}}<what_happened_so_far>{{history}}</what_happened_so_far>{{/if}}

Write the task ledger:
1. Facts given in the task.
2. Facts to look up, and where.
3. Facts to derive (by reasoning or computation).
4. Educated guesses.
5. A short plan: which team member does what, in order.
{{#if history}}The old plan stalled. Say why, then write a new plan that avoids it.{{/if}}
```

### Progress ledger prompt

```markdown
<task_ledger>{{task_ledger}}</task_ledger>
<history>{{history}}</history>

Answer in JSON:
{"is_complete": true|false,
 "is_progressing": true|false,
 "is_in_loop": true|false,
 "next_speaker": "one of {{team_names}}",
 "instruction": "what that member should do next, self-contained"}
```

## Stop rule

Stop when the progress ledger says the task is complete, after 20 turns, or after 3 replans. On a cap, return the best partial result with the latest task ledger and a status saying the task was not finished.

## Requirements

- Make the stall threshold (default 2), the turn cap (default 20) and the replan cap (default 3) parameters.
- If the progress ledger reply is not valid JSON or names an unknown agent, retry once, then count the turn as a stall.
- Store both ledgers outside the orchestrator's context and log every version, so a run can be audited turn by turn.
- Give each worker only the instruction for its turn, not the ledgers.
- Add a test with a stub orchestrator whose progress ledger reports no progress on turns 1 to 3, progress on turn 4 and completion on turn 5; assert the task-ledger prompt ran exactly twice and the stall counter was 0 after the replan.