Copy the shape of an existing provider (src/models/ollama.ts,
src/models/openai.ts, src/models/anthropic.ts). Do not invent a new
shape.
1. src/models/<name>.ts
- Match the existing provider interface (availability probe, chat/complete, token count, streaming).
- Availability probe ≤ 1.5 seconds. Long timeouts break REPL cold-start budget.
- HTTP via
undici(already a dependency). Noaxios, nonode-fetch. - Redact credentials via
src/security/redact.tsbefore any log call. - Map transport errors to
ForgeRuntimeErrorwith the rightretryableflag and arecoveryHintwhere possible.
2. src/models/registry.ts
- Add the id to
providerEnum. - Register the class in
initProviders. - If local (runs on the user's machine), add it to
isLocalProvider.
3. src/models/local-catalog.ts
- Add model id → family classification here. Do not write ad-hoc regex in the provider for capability detection.
4. src/models/router.ts
- Verify routing reaches the new provider via standard rules. If
routing changes, update
test/unit/adapter.test.ts.
5. Unit test
Mock the transport (see test/unit/adapter.test.ts). Cover:
- availability probe success and failure,
- chat/complete happy path,
- 429 retry behaviour,
- auth failure surfaces a non-retryable structured error.
6. Docs
Update the provider table in docs/ARCHITECTURE.md §6, bump the
README "At a glance" count, and add a one-line setup note to
docs/SETUP.md.
Finish with the verify skill.