feat: multi-protocol model provider (Anthropic + OpenAI-compat) — support LiteLLM and RITS from main

[cwiklik]

Summary

Generalize the harness model wiring so a leaf/turn can be driven against any of the common LLM wire protocols — Anthropic Messages, OpenAI Chat Completions, (OpenAI Responses, deferred) — selected per model via SH_MODEL_API, delegating to Pi's existing providers. Unblocks OpenAI-compatible endpoints (IBM RITS, vLLM, OpenAI, Azure, most OSS gateways) from main; the Anthropic + LiteLLM paths are unchanged.

Closes #157. Design: docs/specs/2026-08-20-multi-protocol-model-provider-design.md.

What changed

• requireModel dispatches on SH_MODEL_API (anthropic default | openai-completions | openai-responses stub). New synthesizeOpenAICompletionsModel builds a Model<"openai-completions"> with baseUrl + headers, delegating to Pi's openai-completions provider.
• Config: SH_MODEL_BASE_URL (falls back to ANTHROPIC_BASE_URL/OPENAI_BASE_URL), SH_MODEL_HEADERS (JSON; string values support ${VAR} interpolation so a secret flows in via a secretKeyRef env, no inline literal), SH_MODEL_AUTH (bearer | custom-header | none).
• applyModelGateway no-ops for non-Anthropic models (they carry their own baseUrl/headers/auth).
• toolChoiceExtension is protocol-aware: Anthropic object {type:"auto"} vs OpenAI string "auto" (vLLM/RITS reject the object).
• Docs: OpenAI-compatible how-to added to README-k8s/kind/ocp.

Backward compatible: default (registry, or SH_MODEL_CUSTOM=1 without SH_MODEL_API) is byte-for-byte the Anthropic behavior shipped today.

Verification

• Unit: 24 tests green (run-turn-model + new tool-choice-extension) — OpenAI synth, base-URL fallback, ${VAR} interpolation, custom-header Bearer strip, validation errors, Anthropic-default regression, object-vs-string tool_choice. tsc --noEmit clean.
• Live gate (epoc002, RITS-hosted Granite ibm-granite/granite-4.1-8b):
  • SH_MODEL_API=openai-completions + SH_MODEL_HEADERS={"RITS_API_KEY":"${RITS_API_KEY}"} + SH_MODEL_AUTH=custom-header → auth succeeded (secret via secretKeyRef).
  • Log confirms tool_choice="auto" (string form) sent, no vLLM rejection.
  • Tool-requiring /turn ran hostname and returned the real pod name (unguessable) → structured tool call executed, stopReason:stop.

The pi-fork submodule has a pre-existing non-hermetic build issue (models.generated.ts regenerated from a live API drifts against a pinned type); the live image was built as a thin overlay of the two changed source files over the working base, which the harness loads via tsx. Not caused by this PR.

Follow-ups (not in this PR)

• Retire the /tmp OpenAI wiring fork (superseded by this).
• Slot a milestone-registry id in docs/specs/README.md (maintainer call).
• openai-responses synthesizer (deferred; all current targets are openai-completions).

Assisted-By: Claude Code

[pdettori]

Summary

Clean, well-scoped generalization: dispatch on SH_MODEL_API in requireModel, a new synthesizeOpenAICompletionsModel, a protocol-aware toolChoiceExtension (object vs string auto), and a correct applyModelGateway no-op guard for non-Anthropic APIs. The Anthropic default path is preserved byte-for-byte, ${VAR} header interpolation keeps secrets out of manifests, and the 24 unit tests cover synthesis, base-URL fallback, custom-header strip, interpolation, and validation errors. Docs (k8s/kind/ocp READMEs + design spec) match the code.

Areas reviewed: TypeScript (run-turn, tool-choice-extension), tests, docs. Commits: 4, all DCO signed-off. Agent/IDE config: none.

CI status — 2 failing, both pre-existing and unrelated to this PR

• check dies at Build pi-fork (type declarations) with the same supportsReasoningEffort / OpenAIResponsesCompat type error that also fails on main (run 32408167817). This PR touches neither pi-fork nor the generated types.
• trivy-scan flags CRITICAL/HIGH vulns in pnpm node_modules; this PR changes no package.json/lockfile.

⚠️ Verification caveat: because check fails at the pi-fork build step, the Typecheck and Test steps never run — so CI never actually executed the 24 tests or tsc --noEmit. The "24 green / tsc clean" evidence is locally-verified only. Worth merging with eyes open until the pre-existing pi-fork build issue is resolved.

Approving on the code's merit — the two inline notes are non-blocking suggestions.

Assisted-By: Claude Code

[pdettori]

suggestion — SH_MODEL_AUTH isn't validated. An unrecognized value (a typo like custom_header, or Bearer with a capital) silently falls through to bearer behavior — the Authorization strip and placeholder-key seed on lines 147–152 never fire, producing a confusing downstream auth failure rather than a clear error. SH_MODEL_API errors on unknown values (see requireModel); consider validating this enum the same way for symmetry.

[pdettori]

suggestion — this reads env.OPENAI_API_KEY but mutates the global process.env.OPENAI_API_KEY. When a caller passes a custom env (not process.env), the check and the write target different objects, so a caller supplying an env without the key pollutes the real process.env with "unused". The tests already work around this by passing OPENAI_API_KEY: "present". It's necessary because pi resolves the key from process.env at request time — worth a one-line comment noting the intentional read-env / write-global split (or seeding onto the passed env where feasible).