# Provider feature parity

Alvin's agent capabilities live in **Alvin's own orchestration** (the
`OpenAICompatibleProvider` tool loop, `subagents.ts`, `alvin-dispatch.ts`,
`personality.ts`), not inside any one vendor SDK. So any other provider can
reach near-parity with the Agent SDK just by running that loop. This
doc records what each provider tier gets, and why.

## How parity is wired (capability flags, not "is it the SDK")

Behaviour is gated on **capability flags**, never on `config.type === "claude-sdk"`:

- `supportsTools` — runs Alvin's 8-tool executor loop (read/write/shell/web/…).
- `supportsDispatch` — can spawn **detached** sub-agents (`alvin_dispatch_agent`).
- `supportsLiveSteer` — honours mid-turn **/btw** steering.
- `supportsReasoning` — acts on **/effort** (forwards `reasoning_effort` / `--effort`).

For every `OpenAICompatibleProvider`, `supportsDispatch` and `supportsLiveSteer`
**default ON** for any tool-capable endpoint (getters in
`openai-compatible.ts`), so Gemini / Groq / NVIDIA / OpenRouter / Ollama / the
agent-CLI bridge all opt in automatically. A preset may force either flag off.

The system prompt is built from **`PromptCaps`** (`promptCapsFromProvider`), so
the other tool providers get the same agentic scaffolding the SDK gets:
action-narration, the available-tools summary, the detached-dispatch rules
(lean `alvin_dispatch_agent` variant), live-steer guidance, **and** the
public-safe **agent-CLI voice** (symbol/emoji conventions, dry humor,
do-then-explain, the occasional unprompted heads-up). The Agent SDK already
has that voice natively, so it's skipped there.

## Parity matrix

| Capability | Agent SDK | Agent-CLI bridge | Gemini / Groq / GPT / NVIDIA / OpenRouter | Ollama (local) | Codex CLI |
|---|---|---|---|---|---|
| 8-tool executor loop | ✅ | ✅ | ✅ | ✅ per-model (gemma4:e4b ✓, gemma3n:e4b ✗) | ⚠️ own internal loop |
| Parallel in-process sub-agents | ✅ | ✅ | ✅ (run on the active provider) | ✅ | as a sub-agent only |
| Detached sub-agents (`alvin_dispatch_agent`) | ✅ | ✅ | ✅ → run on **that** provider | ✅ | ❌ (black-box) |
| Live `/btw` steering | ✅ | ✅ | ✅ | ✅ | ❌ |
| `/effort` reasoning | ✅ | ✅ (`--effort`) | ✅ Gemini 2.5/3 · o3 · others ❌ | ❌ | ❌ |
| Workspaces — persona / model / cwd | ✅ | ✅ | ✅ | ✅ | ✅ |
| Workspaces — temperature / toolset | ✅ | ✅ | ✅ | ✅ | ❌ (no Alvin tool loop) |
| Streaming answer text (v5.120.0) | ✅ | ❌ one frame (see below) | ✅ | ✅ | ❌ |
| Agent-CLI voice / personality | native | native | ✅ injected | ✅ injected | ✅ injected |

### Streaming answer text — and `OPENAI_TOOL_STREAM`

The tool loop asks every OpenAI-compatible endpoint for `stream: true` and
passes each event-stream fragment straight on, so the answer appears while it
is written instead of arriving in one piece at the end. Tool arguments are
still assembled in full before anything runs; an endpoint that ignores
`stream: true` and returns a finished JSON body is read exactly as before.

Two routes deliberately do not stream. The bundled **agent-CLI bridge**
sends its whole text in one frame anyway, and once its headers are out a CLI
failure would arrive as a text fragment rather than an HTTP error — the turn
would be counted as a success and the chain would not move on. The **plain-text
tool protocol** (`promptMode`, used when an endpoint refuses native `tools:`)
carries its calls inside the text and strips them after the round; streamed,
the raw protocol block would be read before it is removed.

`OPENAI_TOOL_STREAM=off` restores the pre-v5.120.0 behaviour in full: one
request with `stream: false`, one complete answer at the end. It is an operator
escape hatch for a third-party endpoint whose fragments a setup cannot handle —
an endpoint that simply cannot stream needs nothing, it falls back by itself.

### Detached sub-agents run on the user's provider

The in-process sub-agent path always ran on the active provider. Detached
dispatch now matches: `selectDispatchBackend` prefers the **generic worker**
when a provider outside the Agent SDK family is active (`activeProviderIsClaude:false`),
threading the active `providerKey` into the worker — so a Gemini user's
background audit runs on Gemini, not silently on the agent CLI. Providers backed
by the Agent SDK vendor (SDK, the bridge, any `claude-*` model) keep the agent
CLI in print mode, the natural equivalent worker.

### `/effort` on cloud endpoints

`reasoning_effort` is forwarded only when a preset sets `supportsReasoning`.
Cloud OpenAI-compatible APIs only accept `low|medium|high`, so the value is
clamped `max → high` (`reasoningEffortValue`); the bridge keeps `max` (its
`--effort` accepts it). `supportsReasoning` is enabled per-preset only after the
endpoint is verified to accept the field, to avoid a 400 knocking the request
out of the tool loop. **Enabled:** Gemini 2.5/3 (verified: `reasoning_effort`
→ HTTP 200, live tool-loop with `effort:max` confirmed) and o3 (native OpenAI
reasoning). **Left off:** non-reasoning chat models like `llama-3.3-70b` (Groq
returns HTTP 400 for `reasoning_effort`) and `gpt-4o`/`gpt-4.1`.

## Codex CLI — honest limits

`codex-cli` is the one tier that **cannot** reach full parity, by architecture:
it shells out to `codex exec` (one-shot, `--ephemeral`, `-s read-only`) and runs
its **own** agent loop *inside the Codex binary*. Alvin never sees Codex's tool
calls or mid-turn state, so:

- ✅ **Gets:** the agent-CLI voice + action-narration (injected via the system
  prompt, which `codex exec` folds into its input), the workspace **persona**,
  the **model** override (`-m`), and the working dir (`-C`). Works fine as a
  *sub-agent* of another provider.
- ❌ **Can't get:** Alvin's 8-tool loop, detached `alvin_dispatch_agent`
  dispatch, live `/btw` steering, workspace **toolset** restriction, or
  `temperature`/`effort` forwarding — all of those hook into Alvin's own
  tool-round loop, which Codex bypasses. Codex is also `read-only` sandboxed by
  default (no writes / network from inside Codex).

To bring Codex to full parity you'd need a Codex equivalent of the agent-CLI
bridge (an OpenAI-`tool_calls` front for `codex`), which the Codex CLI does not
currently expose. Out of scope until it does.

## Local models (Ollama) — per-model tool support

The Ollama endpoint is auto-detected as tool-capable, so Alvin always *attempts*
the tool loop; whether it works depends on the model emitting OpenAI
`tool_calls`. Verified live on a MacBook Air (2026-06-16, Ollama 0.30.8):

- **`gemma4:e4b` (the default) ✅** — runs the FULL loop: `tool_use` fired,
  `python_execute` returned the correct unfakeable SHA256, and a mid-task /btw
  note folded on the 1st round (pivot to "PARIS"). Real OpenAI tool_calls.
- **`llama3.2:3b` ✅** — full loop + steering (pivot after the running batch).
- **`gemma3n:e4b` ✗** — the older on-device variant emits Gemma's own
  ```` ```tool_code ```` blocks, which Ollama's OpenAI layer does **not** translate
  to `tool_calls`; it hallucinated the hash and never entered the loop. The
  provider degrades cleanly to plain text and still gets the agent-CLI voice.

So local parity is real — pick a model that speaks OpenAI tool_calls
(gemma4, llama3.x, qwen2.5, mistral) for agentic use.
