Formalize cllama ingress surfaces and centralize runner protocol mapping

[mostlydev]

Problem

Issue #127 fixed the concrete OpenClaw + google/* + cllama breakage by making the OpenClaw driver compile Google models behind cllama as openai-completions instead of google-generative-ai.

That patch fixed the immediate outage, but it exposed a broader architectural gap:

• there is no single authoritative contract for what protocol a runner should speak to cllama
• docs/CLLAMA_SPEC.md and ADR-008 still describe cllama primarily as an OpenAI-compatible proxy
• the reference implementation already exposes more than that (/v1/chat/completions and /v1/messages)
• OpenClaw currently carries driver-local logic to decide whether a provider behind cllama should use a vendor-native API enum or a proxy-facing API enum
• future providers can reintroduce the same class of bug unless the proxy surface contract is explicit and centralized

Issue #130 adds regression coverage around the current OpenClaw helper split, but it intentionally stays test-only. It does not resolve the architecture question.

Why this matters

The direct-Gemini incident was not really about Google. It was a trust-boundary failure:

• operator-facing model refs use provider identity (google/gemini-*, anthropic/*, etc.)
• runner-facing config also wants a transport/API shape
• those are different concerns, but they are currently entangled in driver code

If we respond by adding one-off provider exceptions, or by inventing fake model prefixes like cllama/google/..., we will accumulate surface-area drift across drivers, docs, telemetry, pricing, and policy.

Decision to make

Adopt an explicit cllama ingress surface matrix owned by infrastructure.

Proposed direction:

1. cllama owns a small canonical set of runner-facing ingress surfaces.
   • minimum: OpenAI Chat Completions
   • minimum: Anthropic Messages
2. Drivers compile declared model refs to one of those proxy surfaces when cllama is enabled.
3. Provider identity stays in the model ref.
   • Do not invent synthetic operator-facing providers like cllama/google.
4. Vendor-native adapters should be added only when a concrete runner cannot target one of the canonical proxy surfaces.
   • They should be explicit exceptions, not the default design.

This keeps transport concerns in infrastructure while preserving operator-visible provider identity.

Scope

• define and document the canonical runner -> cllama ingress surfaces
• centralize proxy-surface selection in shared code instead of driver-local ad hoc switches
• make OpenClaw consume the shared contract
• reconcile docs/CLLAMA_SPEC.md and ADR-008 with the actual supported surfaces
• add regression coverage so future provider additions cannot silently reintroduce vendor-native APIs behind cllama where they do not belong
• confirm whether any driver besides OpenClaw needs a small integration change after the contract is centralized

Out of scope

• adding arbitrary vendor-native translation layers for every provider by default
• changing operator-facing model refs
• changing model-policy authority from ADR-019
• introducing multi-proxy runtime chaining

Acceptance criteria

• a single shared contract exists for selecting the proxy-facing surface used behind cllama
• OpenClaw no longer owns the canonical surface decision in a private helper
• direct google/* behind cllama routes through the OpenAI-compatible proxy surface
• Anthropic-family traffic behind cllama remains on the Anthropic Messages surface where required
• docs/spec/ADR text match the implementation instead of describing cllama as OpenAI-only when the runtime is not
• focused tests protect the surface matrix from future regressions

References

• Fix OpenClaw Google model API when routing through cllama #127
• Expand OpenClaw cllama provider API matrix regression coverage #130
• ADR-008
• ADR-019
• docs/CLLAMA_SPEC.md

[mostlydev]

Implemented the ingress-surface contract from this issue.

Summary:

• added shared cllama ingress-surface helpers in internal/cllama/ingress.go
• centralized provider alias normalization and provider -> surface selection there
• refactored OpenClaw to compile through the shared cllama surface contract instead of a private provider switch
• updated docs/CLLAMA_SPEC.md to describe the canonical ingress surface matrix (/v1/chat/completions and /v1/messages)
• updated ADR-008 and added ADR-023 to record the architecture decision explicitly
• verified with go test ./...

This keeps provider identity in model refs while making runner transport selection infrastructure-owned.