feat: self-hosted OpenAI-compatible providers (LiteLLM) for Pi

[hauserkristof]

Summary

Adds support for self-hosted, OpenAI-compatible LLM providers (such as a LiteLLM proxy) to Warden's Pi runtime. You can now register a named provider in warden.toml, point any model lane at it with the usual provider/model selector, and run Warden entirely against your own infrastructure — no dependency on a hosted vendor.

The provider is generic: any OpenAI-compatible endpoint works. LiteLLM is the worked example, not a hard requirement.

What's included

• Config schema — [defaults.providers.<name>] blocks (base URL, API kind, optional headers, model list). Only id is required per model; Warden fills sensible defaults (name, reasoning, input, contextWindow, maxTokens, zero cost).
• Runtime registration — custom providers are normalized and registered in the Pi adapter, exposed through getRuntimeProviderOptions, and threaded through every model lane (agent, auxiliary, synthesis).
• Env-only credentials — API keys are resolved from the environment (apiKeyEnv → WARDEN_<NAME>_API_KEY → <NAME>_API_KEY), never from warden.toml.
• Fail-fast preflight — a non-loopback provider with no resolvable key fails before any analysis, with a clear message. Loopback URLs (localhost, 127.0.0.1, ::1, bracketed [::1]) may run keyless.
• Consistent across entry points — the preflight runs in the CLI, the trigger executor, scheduled workflows, and the PR workflow.
• Docs — new "Self-hosted / OpenAI-compatible providers" section in config/models.mdx, plus the Pi models.json alternative.

Behavior decisions

• One model drives every lane. The auxiliary lane (structured extraction, dedup, merge, fix evaluation) and the synthesis lane now inherit the resolved global default model (defaults.agent.model → defaults.model → --model → WARDEN_MODEL) when their own model is unset. Explicit [defaults.auxiliary] / [defaults.synthesis] still win.

  This is important for self-hosted setups: previously, setting only defaults.model = "litellm/..." kept just the agent lane on your proxy while extraction/dedup/synthesis silently fell back to the runtime's built-in default model — which resolves against a different provider (e.g. Gemini via Google's API). That both broke runs (auth/quota errors mid-analysis) and leaked model output carrying code context off the endpoint you deliberately chose. The inheritance fix closes that gap.

• Loopback exemption. Unauthenticated local endpoints are a legitimate setup, so loopback hosts are allowed without a key while every other host requires one.

Configuration example

[defaults]
runtime = "pi"
model = "litellm/my-model"   # provider-prefixed; drives all lanes

[defaults.providers.litellm]
baseUrl = "http://localhost:4000/v1"
api = "openai-completions"
# apiKeyEnv = "WARDEN_LITELLM_API_KEY"   # optional; overrides the default lookup

[[defaults.providers.litellm.models]]
id = "my-model"
# reasoning = true        # mark reasoning models
# maxTokens = 16384       # give reasoning models headroom

Then: export WARDEN_LITELLM_API_KEY=... and run Warden as usual.

Testing

• Unit + integration coverage for provider normalization, key resolution, loopback detection, the auth preflight, provider forwarding through all lanes, and the new auxiliary/synthesis model inheritance (both resolution sites).
• Custom-provider preflight tests are hermetic (no ambient env dependence).
• Validated end-to-end against a live LiteLLM proxy: config parsing → key resolution → preflight → registration → request → response, across agent, auxiliary, and synthesis lanes, including a reasoning model.
• Full suite green: pnpm lint, pnpm build, pnpm test, docs build.

Notes

• v1 is OpenAI-completions only; other API shapes are out of scope.
• Self-hosted models report $0 cost unless explicit costs are configured.

🤖 Generated with Claude Code

https://claude.ai/code/session_01E7ptHmVh79CqJev6WHnWNm

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit e31e6fe. Configure here.}

[cursor]

Layered repo triggers miss model

High Severity

Org-level defaults.providers and defaults.model for a self-hosted lane are handled inconsistently across layers. Repo-only triggers inherit custom providers from the base config but not the base default model, so trigger execution can run auxiliary and synthesis calls without the org’s litellm/… model while providers are present. Workflow-scoped dedup and consolidate still resolve the base model via resolveWorkflowAuxiliaryOptions, so analysis and posting can disagree on which model and provider lane runs.

Additional Locations (1)

• packages/warden/src/action/workflow/pr-workflow.ts#L177-L204

 

^{Reviewed by Cursor Bugbot for commit e31e6fe. Configure here.}

[cursor]

Dedup defaults drop Pi providers

Medium Severity

Semantic dedup and batch consolidate now forward providerOptions using getRuntimeProviderOptions, but still default an omitted runtime to claude for both getRuntime and the provider-options lookup. Elsewhere in this change set the effective default runtime is pi, and getRuntimeProviderOptions only builds custom provider registration for Pi. Callers that pass providers without an explicit runtime therefore hit the Claude adapter and silently omit custom provider registration.

Additional Locations (1)

• packages/warden/src/output/dedup.ts#L919-L929

 

^{Reviewed by Cursor Bugbot for commit e31e6fe. Configure here.}