Models & providers

Arcturn drives every model through a single client interface, so a provider change is a --model flag rather than a code change. Adapters register themselves into a provider registry, which is why adding a backend never touches dispatch code.

The last two rows matter more than they look: most third-party inference services speak one of those two protocols, so Arcturn reaches them without a bespoke adapter each. Endpoint presets ship as remembered { baseUrl, apiKeyEnv, protocol } triples — run arcturn --list-providers for the current set. A preset is a convenience, not a gate: any endpoint works by URL without one.

Model ids are <provider>/<model>. Pass one with --model, or switch mid-session with /model <id>. Model names pass through verbatim, so anything the endpoint serves works.

A bare wire model name resolves too when it is unambiguous across the catalog, and a miss triggers the extended preset table to register itself once before retrying — so a fresh process never pays for the whole table unless something needs it.

Two of the four route kinds reach a live call site today: main for the conversation loop, and subagent for delegated work — sub-agents, scouts and /team members alike — so a mechanical subtask need not run on the model steering the session. compaction and title are accepted in config and reserved; a session title is derived from the task text directly today and makes no model call at all. A missing route falls back to whatever main resolved to, and a bad id is caught rather than thrown — the kind falls back and records a warning, because a stale model id in a config file must never be the reason Arcturn fails to start.

A model string can also be an array, which builds a failover chain. The rule that matters: failover only happens before output starts. Once a single delta reaches the consumer the turn is committed to that model, because splicing two half-answers together would corrupt the message. Only transient errors — rate limits, overload, network — trigger a switch; a bad key or a user abort fails identically on every link.

The curated catalog is hand-maintained, which means it goes stale the moment a provider ships a new generation. /model refresh queries each preset’s own list-models endpoint — for whichever presets already have a key set — and registers anything new it finds without ever overwriting a curated entry.

Results are cached at ~/.arcturn/live-models.json for 24 hours. A model discovered this way gets conservative defaults until a curated entry supersedes it, and a preset whose refresh fails falls back to its last cached result rather than dropping its models for that round.

Costs are tracked per request whenever a model’s pricing is known. Where a price could not be sourced confidently it is omitted rather than guessed, so the cost field is simply absent instead of quietly wrong.

Prompt caching is supported through the same interface, and --max-cost turns live spend into an enforcement mechanism: the run is aborted at the next turn boundary once cumulative cost reaches the ceiling, not flagged after the fact.