Orders the tool sub-calls a Code Mode program makes.

A program is a batch of tool calls the model wrote as code — loops, fan-out, branches — and nothing in the program says how those calls may interleave. The scheduler decides, and it decides conservatively.

One driver lane

Every ordering decision (classify, start, commit) happens inside this GenServer's own process, so the lane is the serialized mailbox: there is no bespoke lock, no ETS counter, nothing to get wrong under contention. State is a submission-ordered pending queue, an inflight set, and a head-of-line cursor that commits settled sub-calls strictly in submission order — a call that finishes early waits for its predecessors, so the program observes one deterministic order regardless of how the work actually raced.

Execution itself fans out through Task.Supervisor.async_nolink/2 on Nous.TaskSupervisor — the same supervisor and the same a-crash-is-a-result policy Nous.AgentRunner.ToolExecution uses for parallel native tool calls. That module uses Task.Supervisor.async_stream_nolink/4 because it has the whole batch up front; here sub-calls arrive one at a time from a running program, so a stream over a finished list is the wrong shape. $callers is propagated the same way regardless (see "Caller chain" below).

Exclusive by default

A tool is treated as EXCLUSIVE unless its module exports concurrency_safe?/1 and that function returns exactly true for the call's arguments. Absent attribute, unloadable module, wrong return, raise, throw or exit — all mean exclusive. This is fail-safe, not fail-open: a tool that does not say it is safe to run concurrently is assumed unsafe, because the failure mode of guessing wrong is interleaved side effects on someone else's data.

An exclusive call drains the pool, runs alone, and holds the barrier through its commit — not merely through execution, which would let a concurrent call commit inside its window. See mode/0 and the drive/1 comments.

What the program can see

A failed sub-call arrives inside the program as {:error, %{"tool" => name, "message" => message}} — a plain map of two strings. Never a struct, never a stacktrace, never a %Nous.Errors.ToolError{} with its :original_error still attached. Model-authored code is one prompt-injection hop from the transcript, so the operator's Logger gets the detail and the program gets two strings.

Arguments are snapshotted twice

At submission the scheduler materializes two independent JSON-shaped snapshots of the arguments: one dispatched to the tool, one written to the session log. Neither path can influence the other, so a tool cannot desync the audit record from what actually ran. Normalizing both is also what makes the audit record true: what the tool received and what the log says are the same shape, and a program cannot smuggle a live BEAM handle (pid, ref, port, closure) into a tool through the transport.

Session events, outside model history

Each sub-dispatch appends exactly one BOOKKEEPING :tool_call event to the Nous.Agent.Context the scheduler was handed, at the moment it starts, in submission order. Bookkeeping events project to no message (Nous.Session.Log.derive_messages/1), so ctx.messages is unchanged by any number of sub-dispatches: only what the program logs or returns re-enters the model's context.

There are two ways to read that trail back. context/1 is for a caller that handed in a real Nous.Agent.Context. logged_events/1 is for one that owns none: Nous.Tools.RunCode is handed a %Nous.RunContext{}, which has no session log at all, so it forwards the pairs as Nous.Tool.ContextUpdate.log_event/3 operations and the runner appends them to the context that does exist.

Caller chain

$callers is not propagated across GenServer.start_link/3, so the scheduler captures the starting process's chain and reinstalls it in its own process dictionary. Sub-call tasks therefore see [scheduler, starter | ...] and process-scoped overrides — Nous.ModelDispatcher.put_dispatcher/1, Mox allowances, Ecto sandbox ownership — keep working inside a sub-call.

Shape

{:ok, sched} = Scheduler.start_link(dispatch: dispatch, context: ctx)

# Phase D hands this straight to Nous.CodeMode.bindings/4 as `:dispatch`,
# and every granted-tool closure routes through the lane.
Scheduler.dispatch_fun(sched)

# Or drive it directly: submit many, await in any order.
{:ok, ticket} = Scheduler.submit(sched, tool, %{"q" => "elixir"}, run_ctx)
Scheduler.await(sched, ticket)

The scheduler is one plain module plus one GenServer. It is deliberately not supervised: it lives and dies with a single run_code call, and stop/2 releases every outstanding caller with an error rather than leaving a program blocked on a lane that no longer exists.