/providers (bro)
Mechanics live in config and the @broject/providers bindings. This
skill is the contract reference — providers are configured, never
hardcoded.
What a provider is
A named entry in bro.config.json providers — { type, …connection }.
Consumers pick by name; the name carries no semantics. The type
(provider kind) fixes the connection shape and which surfaces the entry
can serve.
{
"providers": {
// One API host, many models — each model declares its wire.
"orcarouter": {
"type": "api",
"baseUrl": "https://api.orcarouter.ai",
"apiKeyCommand": "secret-tool lookup service typesafe.ai",
"models": {
"typesafe/jev-1.13": "systemone",
"acme/cheap-chat": "openai-compat",
"acme/auto-x": null // inferred
}
},
"kilo-cli": { "type": "acp", "command": "kilo --acp", "model": "typesafe/jev-1.13" },
"local": { "type": "cli", "command": "devin -p --prompt-file {promptFile}", "model": "devin-1" }
}
}
Kinds and surfaces
| kind |
call (judge) |
spawn (fleet) |
api |
by model wire — systemone typed, openai-compat prose |
— |
acp |
typed on a jev-family model, else prose |
yes |
cli |
prose — stdout parsed |
yes — loop.agent template contract |
- An
api entry is a host + auth + a models allowlist —
{ "<model-id>": "systemone" | "openai-compat" | { "wire": … } | null }.
null/absent infers the wire: jev-family ids → systemone,
everything else → openai-compat. model pins the default;
judge.model or a per-call override must name an allowed id —
anything else is a config error listing the allowlist.
cli.command is a shell template: {promptFile} expands to the
quoted path of a file holding the prompt (appended as the last arg
when absent); {model} expands to the resolved effective model,
quoted. The process runs and exits, stdout is the answer. A model
override the template can't consume — --model/profile/judge.model
on a command with no {model} — is a loud error, not a relabel:
provenance never claims a model the worker didn't run.
- An
acp entry's call grade is decided by the served model —
typesafe/jev-* (or bare jev-*) is typed transport; anything else
is prose and stamps provider:<name>:prose in decidedBy.
- A
cli entry's optional models is a shell template emitting one
model id per line — the catalog surface, e.g.
"models": "opencode models". Absent = no enumerable catalog; a
pinned model still renders.
brouter — the model-centric routing registry
brouter.models inverts the lookup: the MODEL id is the routing key.
A consumer asks for a model and the registry answers which provider
serves it (spec: specs/bro-n1p0s.md).
{
"brouter": {
"models": {
"swe-2-max": "devin-acp", // shorthand: same id upstream
"jev": { "provider": "kilo-cli", "model": "kilo/orcarouter/typesafe/jev-1.13" }, // alias → upstream id
"cheap": ["opencode-free", "pi"] // ordered candidates, first = primary
}
}
}
Resolution order (first hit wins): a qualified <provider>/<model> id
(head must be a configured provider) → brouter.models.<id> → the
catalog (providers serving the id, in config order). A declared route
to an unconfigured provider is a config error naming the key; absent
brouter = routing off.
bro providers route <id> prints the primary route as
provider/model; --all prints every candidate. Unresolved exits 1.
--model with no --provider/agents.<backend>.provider resolves
through the static index (declared routes + statically-known
models) — a spawn never pays a live catalog probe; an unresolved
model stays a provenance label.
bro providers models [name…] — the catalog
Renders every provider's model list as <name>/<model-id> — the
uniform provider/model vocabulary hosts' pickers share (claude's
/bro:models command wraps exactly this call). Source per kind:
api — the models allowlist keys (config-declared, offline).
acp — session/new's model configOptions, enumerated live over
the protocol: the same list the agent's own model picker serves.
cli — the models template's stdout lines, plus the pinned
model deduped (a pinned model always renders — a provider never
prints silently empty).
Named providers error loudly (providers.<name> is not configured);
a failed provider warns and never stops the rest.
Consumer wiring
- Any provider kind may set
account to an opaque identity shared by
aliases; when omitted it defaults to the provider name. Fleet walls
follow that account across repos on this host.
- Judge:
judge.provider: '<name>' + judge.model: '<allowed-id>'
(+ judge.fallback: '<name>'). The resolved model's wire picks the
adapter — systemone → typed judgments, openai-compat → prose.
A prose-grade answer is never counted as a calibrated typed judgment —
decidedBy says which. Legacy judge.{baseUrl,model,apiKeyEnv} /
judge.llm synthesize anonymous single-model api entries with a
deprecation warning.
- Fleet:
agents.<backend>.provider: '<name>' or
fleet.profiles.<p>.provider — the provider supplies what runs inside
the backend's spawn; provenance rides BRO_AGENT_PROVIDER /
BRO_AGENT_MODEL into the registry entry and bro fleet output.
Non-negotiables
- No defaults, no hardcoding. Absent
providers = provider behavior
off, never a silent vendor. A consumer naming a missing entry errors
at use — providers.<name> is not configured — never falls through.
- Secrets ride env var names or lookup commands.
apiKeyEnv names
the variable (SCREAMING_SNAKE); apiKeyCommand names a secret-store
lookup (secret-tool lookup …, pass show …, op read …) whose
stdout is the key. The key value never lands in config or error
output — a command smuggling one inline is rejected.
- Retired kinds fail the config.
type: "systemone" or
"openai-compat" as a provider type is a hard error naming the
migration — move the entry to type: "api" + models map.
- Surface errors are config errors. Asking an
api entry to spawn,
or a non-call kind to judge, fails at resolution naming kind + surface.
bro doctor reports the registry — entries (name, kind,
default/served models), unset apiKeyEnv vars, and
dangling/surface-mismatched consumer refs, as warn rows that never
block the exit code.
Policy
- A new vendor is a registry entry, not a new connector — kinds
exist for connection-shape differences only (the union is closed at
three); protocol differences inside an HTTP host are
models map
entries, not kinds.
- Diagnose with
bro doctor before touching provider config — a warn
row there is the failure a spawn/decide would hit, said early.
Presets and add/test
bro providers add <preset> [--name <name>] [--global] [--force] writes a provider entry for a verified preset — acp presets (kilo, claude-code, claude-acp, codex, gemini-cli, goose, opencode, devin) and the cli preset claude (claude -p --dangerously-skip-permissions --output-format stream-json --verbose < {promptFile}; claude-acp rides the claude-code-acp adapter binary). Defaults to project bro.config.json; --global writes to global $XDG_CONFIG_HOME/bro/config.json. Without --global, refuses if bro.config.ts shadows. With --global, refuses if config.ts shadows. Refuses to overwrite existing entries without --force.
bro providers test <name> smoke-tests an ACP provider connection by initializing over ACP.
1---23name: providers4description: "Use when configuring or debugging bro's provider registry — `providers` in bro.config.json, provider kinds (api/acp/cli), model wire selection, `judge.provider` / `agents.<backend>.provider` references, or `bro doctor` provider rows. Mechanics live in the CLI + @broject/providers; this skill carries the contract and policy only."5metadata:6 source: https://skillmd.com/skills/theplenkov/providers7---89# /providers (bro)1011**Mechanics live in config and the `@broject/providers` bindings.** This12skill is the contract reference — providers are configured, never13hardcoded.1415## What a provider is1617A named entry in `bro.config.json` `providers` — `{ type, …connection }`.18Consumers pick **by name**; the name carries no semantics. The `type`19(provider kind) fixes the connection shape and which surfaces the entry20can serve.2122```jsonc23{24 "providers": {25 // One API host, many models — each model declares its wire.26 "orcarouter": {27 "type": "api",28 "baseUrl": "https://api.orcarouter.ai",29 "apiKeyCommand": "secret-tool lookup service typesafe.ai",30 "models": {31 "typesafe/jev-1.13": "systemone",32 "acme/cheap-chat": "openai-compat",33 "acme/auto-x": null // inferred34 }35 },36 "kilo-cli": { "type": "acp", "command": "kilo --acp", "model": "typesafe/jev-1.13" },37 "local": { "type": "cli", "command": "devin -p --prompt-file {promptFile}", "model": "devin-1" }38 }39}40```4142## Kinds and surfaces4344| kind | call (judge) | spawn (fleet) |45| ----- | -------------------------------------------------------- | ---------------------------------- |46| `api` | by model wire — `systemone` typed, `openai-compat` prose | — |47| `acp` | typed on a `jev`-family model, else prose | yes |48| `cli` | prose — stdout parsed | yes — loop.agent template contract |49- An `api` entry is a host + auth + a **`models` allowlist** —50 `{ "<model-id>": "systemone" | "openai-compat" | { "wire": … } | null }`.51 `null`/absent infers the wire: `jev`-family ids → `systemone`,52 everything else → `openai-compat`. `model` pins the default;53 `judge.model` or a per-call override must name an allowed id —54 anything else is a config error listing the allowlist.55- `cli.command` is a shell template: `{promptFile}` expands to the56 quoted path of a file holding the prompt (appended as the last arg57 when absent); `{model}` expands to the resolved effective model,58 quoted. The process runs and exits, stdout is the answer. A model59 override the template can't consume — `--model`/profile/`judge.model`60 on a command with no `{model}` — is a loud error, not a relabel:61 provenance never claims a model the worker didn't run.62- An `acp` entry's call grade is decided by the served model —63 `typesafe/jev-*` (or bare `jev-*`) is typed transport; anything else64 is prose and stamps `provider:<name>:prose` in `decidedBy`.65- A `cli` entry's optional `models` is a shell template emitting one66 model id per line — the catalog surface, e.g.67 `"models": "opencode models"`. Absent = no enumerable catalog; a68 pinned `model` still renders.6970## `brouter` — the model-centric routing registry7172`brouter.models` inverts the lookup: the MODEL id is the routing key.73A consumer asks for a model and the registry answers which provider74serves it (spec: specs/bro-n1p0s.md).7576```jsonc77{78 "brouter": {79 "models": {80 "swe-2-max": "devin-acp", // shorthand: same id upstream81 "jev": { "provider": "kilo-cli", "model": "kilo/orcarouter/typesafe/jev-1.13" }, // alias → upstream id82 "cheap": ["opencode-free", "pi"] // ordered candidates, first = primary83 }84 }85}86```8788Resolution order (first hit wins): a qualified `<provider>/<model>` id89(head must be a configured provider) → `brouter.models.<id>` → the90catalog (providers serving the id, in config order). A declared route91to an unconfigured provider is a config error naming the key; absent92`brouter` = routing off.9394- `bro providers route <id>` prints the primary route as95 `provider/model`; `--all` prints every candidate. Unresolved exits 1.96- `--model` with no `--provider`/`agents.<backend>.provider` resolves97 through the **static** index (declared routes + statically-known98 models) — a spawn never pays a live catalog probe; an unresolved99 model stays a provenance label.100101## `bro providers models [name…]` — the catalog102103Renders every provider's model list as `<name>/<model-id>` — the104uniform `provider/model` vocabulary hosts' pickers share (claude's105`/bro:models` command wraps exactly this call). Source per kind:106107- `api` — the `models` allowlist keys (config-declared, offline).108- `acp` — `session/new`'s model `configOptions`, enumerated live over109 the protocol: the same list the agent's own model picker serves.110- `cli` — the `models` template's stdout lines, plus the pinned111 `model` deduped (a pinned model always renders — a provider never112 prints silently empty).113114Named providers error loudly (`providers.<name> is not configured`);115a failed provider warns and never stops the rest.116117## Consumer wiring118119- Any provider kind may set `account` to an opaque identity shared by120 aliases; when omitted it defaults to the provider name. Fleet walls121 follow that account across repos on this host.122- **Judge**: `judge.provider: '<name>'` + `judge.model: '<allowed-id>'`123 (+ `judge.fallback: '<name>'`). The resolved model's wire picks the124 adapter — `systemone` → typed judgments, `openai-compat` → prose.125 A prose-grade answer is never counted as a calibrated typed judgment —126 `decidedBy` says which. Legacy `judge.{baseUrl,model,apiKeyEnv}` /127 `judge.llm` synthesize anonymous single-model `api` entries with a128 deprecation warning.129- **Fleet**: `agents.<backend>.provider: '<name>'` or130 `fleet.profiles.<p>.provider` — the provider supplies what runs inside131 the backend's spawn; provenance rides `BRO_AGENT_PROVIDER` /132 `BRO_AGENT_MODEL` into the registry entry and `bro fleet` output.133134## Non-negotiables135136- **No defaults, no hardcoding.** Absent `providers` = provider behavior137 off, never a silent vendor. A consumer naming a missing entry errors138 at use — `providers.<name> is not configured` — never falls through.139- **Secrets ride env var names or lookup commands.** `apiKeyEnv` names140 the variable (SCREAMING_SNAKE); `apiKeyCommand` names a secret-store141 lookup (`secret-tool lookup …`, `pass show …`, `op read …`) whose142 stdout is the key. The key value never lands in config or error143 output — a command smuggling one inline is rejected.144- **Retired kinds fail the config.** `type: "systemone"` or145 `"openai-compat"` as a provider `type` is a hard error naming the146 migration — move the entry to `type: "api"` + `models` map.147- **Surface errors are config errors.** Asking an `api` entry to spawn,148 or a non-call kind to judge, fails at resolution naming kind + surface.149- **`bro doctor` reports the registry** — entries (name, kind,150 default/served models), unset `apiKeyEnv` vars, and151 dangling/surface-mismatched consumer refs, as warn rows that never152 block the exit code.153154## Policy155156- A new vendor is a **registry entry**, not a new connector — kinds157 exist for connection-shape differences only (the union is closed at158 three); protocol differences inside an HTTP host are `models` map159 entries, not kinds.160- Diagnose with `bro doctor` before touching provider config — a warn161 row there is the failure a spawn/decide would hit, said early.162163## Presets and add/test164165- `bro providers add <preset> [--name <name>] [--global] [--force]` writes a provider entry for a verified preset — `acp` presets (kilo, claude-code, claude-acp, codex, gemini-cli, goose, opencode, devin) and the `cli` preset `claude` (`claude -p --dangerously-skip-permissions --output-format stream-json --verbose < {promptFile}`; `claude-acp` rides the `claude-code-acp` adapter binary). Defaults to project `bro.config.json`; `--global` writes to global `$XDG_CONFIG_HOME/bro/config.json`. Without `--global`, refuses if `bro.config.ts` shadows. With `--global`, refuses if `config.ts` shadows. Refuses to overwrite existing entries without `--force`.166- `bro providers test <name>` smoke-tests an ACP provider connection by initializing over ACP.