# `SuperPi.Workers.SubagentWorker`
[🔗](https://github.com/oleksandr/super-pi-beam/blob/v0.1.0/lib/super_pi/workers/oban_workers.ex#L84)

Oban worker in the `:subagents` queue: runs one child conversation for `delegate_subagent`.

The plugin creates the child conversation and its `pi.subagent` task, then enqueues this job. Any
node can run it, so the queue limit (`config :super_pi, Oban, queues: [subagents: n]`) bounds the
children of the whole cluster. The job:

1. claims the task (`pending` to `running`). A task that was aborted while it waited is skipped.
2. starts the child's machine and submits the prompt. The machine is unique in the cluster, so
   it may run on another node than this job.
3. settles the task with the final text (`complete_task/2`) or the error (`fail_task/2`). That
   wakes the parent, whose machine is parked in `:awaiting_children`.

`max_attempts: 1`: an LLM turn can have side effects (a worker edits files), so a retry could
repeat them. A job lost with its node is not retried. The child's machine is restarted by Horde,
resumes the turn from the durable state and settles the task itself (`settle/2`, called from
the machine when the turn of a child conversation ends). If only the machine is lost, this job
starts it again and waits for the task to settle.

Test hook: `config :super_pi, :subagent_machine_opts` is merged into the child machine's
options (an `llm_responder`, say). A job argument cannot carry a function.

# `final_text`

```elixir
@spec final_text(term()) :: String.t()
```

The text of an assistant message.

# `machine_opts`

```elixir
@spec machine_opts(String.t()) :: keyword()
```

Machine options of a child with this role: its extensions, plus the test hook.

# `settle`

```elixir
@spec settle(integer(), {:ok, String.t()} | {:error, term()}) :: :ok
```

Records how the child ended on its `pi.subagent` task, once. Called by this worker and by the
child's machine when its turn ends, whichever comes first; the later call changes nothing. The
event `subagent_finished` is published by the call that settles the task.

---

*Consult [api-reference.md](api-reference.md) for complete listing*