Module agent 

Driving agent CLIs.

Every agent in magi is a subscription CLI (claude, opencode, agy) or an arbitrary command, invoked headless in a working directory. There is no API-key path on purpose: the CLIs carry the operator’s own plan, and they are the only interface that exposes an agent’s whole tool loop rather than a single completion.

Seats, not agents

Conversations are keyed by seat (SeatState::key), never by agent id. A model that implements candidate B and also sits as judge 3 gets two unrelated conversations, so the judge cannot recognise its own work from having written it. Sessions are what make deliberation affordable — a judge remembers its own argument instead of being re-fed the entire candidate set — and seat scoping is what keeps that from destroying blindness.

Session mechanics per CLI

CLI	open	resume
claude	--session-id <uuid> (magi mints it)	--resume <uuid>
opencode	--format json reports sessionID	-s <id>
agy	--output-format json reports conversation_id	--conversation <id>

Claude is the only one magi can address before the first turn; the other two report an id back, so SeatState::captured_session stays None until a turn has completed and has_session answers honestly instead of optimistically.

Structs

AgentOutput

Result of an agent invocation.

Invocation

One agent invocation.

Quota

Evidence that a CLI ran out of its rate limit / quota, distinct from an ordinary failure.

SeatState

Conversation state for one seat, persisted with the run so magi run --resume continues the same CLI conversations.

Functions

artifacts_dir

Absolute path of a run’s artifact directory.

has_session

Can a follow-up prompt rely on this seat remembering the conversation?

invoke

Invoke spec for seat, updating the seat’s conversation state.

missing_programs

Preflight: which configured agents are not runnable here?