152 lines
7.1 KiB
Markdown
152 lines
7.1 KiB
Markdown
# ADR: Optional AI egress gateways for runtime-neutral Mos
|
|
|
|
**Status:** Proposed for controlled prototypes; not approved as Mosaic core
|
|
|
|
**Date:** 2026-07-14
|
|
|
|
**Issues:** #754, #755
|
|
|
|
**Decision owner:** Mosaic Gateway / provider-adapter architecture
|
|
|
|
## Context
|
|
|
|
The emergency Mos continuity path kept Claude Code as the harness and translated Anthropic Messages traffic to Codex OAuth through a small localhost proxy. That preserved the existing Claude Discord plugin and transcript, but exposed two architectural facts:
|
|
|
|
1. Harness identity, channel entitlement, provider credentials, and inference transport are separate concerns.
|
|
2. A generic AI gateway can improve provider routing, budgets, and observability, but must not become Mosaic's identity, authorization, tenant, or orchestration boundary.
|
|
|
|
The Tess qualification report also found that current provider rebinding is not identity-continuous failover. Mosaic still needs a logical agent identity, durable connector lease/fencing, canonical handoff/checkpoint, exactly-once receipts, concrete harness adapters, and cross-harness rollback E2E.
|
|
|
|
## Decision
|
|
|
|
Mosaic MAY support LiteLLM, Bifrost, the purpose-built Claude/Codex proxy, or future gateways as optional egress implementations behind `IProviderAdapter` / `AgentRuntimeProvider`.
|
|
|
|
Mosaic Gateway remains authoritative for:
|
|
|
|
- authenticated actor and tenant identity;
|
|
- logical agent identity and connector binding;
|
|
- authorization, approval, and policy;
|
|
- lease epoch and stale-holder fencing;
|
|
- audit correlation and redaction;
|
|
- canonical handoff/checkpoint state;
|
|
- idempotency and side-effect receipts.
|
|
|
|
An egress gateway MUST NOT:
|
|
|
|
- receive channel ingress directly;
|
|
- authorize tools or connector ownership;
|
|
- define Mosaic tenant or agent identity;
|
|
- persist raw Mosaic handoffs or channel credentials;
|
|
- bypass adapter capability negotiation;
|
|
- silently fail over when policy, lease, or provider health is uncertain.
|
|
|
|
Allowed topology:
|
|
|
|
```text
|
|
Discord / Matrix / CLI / web
|
|
↓
|
|
Mosaic Gateway: identity, authz, lease/fence, approvals, audit
|
|
↓
|
|
IProviderAdapter / AgentRuntimeProvider
|
|
↓
|
|
optional egress gateway
|
|
↓
|
|
upstream provider or subscription-backed OAuth session
|
|
```
|
|
|
|
## Candidate assessment
|
|
|
|
### Purpose-built `raine/claude-code-proxy`
|
|
|
|
**Disposition:** Approved only for the verified emergency localhost bridge.
|
|
|
|
Strengths:
|
|
|
|
- explicit Codex device OAuth flow;
|
|
- small operational surface;
|
|
- Anthropic Messages translation suitable for Claude Code;
|
|
- model and reasoning-effort enforcement;
|
|
- straightforward loopback systemd supervision and rollback.
|
|
|
|
Constraints:
|
|
|
|
- not a Mosaic multi-tenant control plane;
|
|
- Claude built-in channels still depend on Claude subscription entitlement and feature lookup;
|
|
- model aliases can obscure the upstream model unless proxy policy/logs are treated as evidence;
|
|
- no replacement for connector leasing, canonical handoff, or exactly-once effects.
|
|
|
|
### LiteLLM
|
|
|
|
**Disposition:** Candidate for a formal adapter-only prototype and terms/security review.
|
|
|
|
Current documentation states that ChatGPT subscription access is available through an OAuth device-code flow. LiteLLM also provides broad provider routing, virtual keys, budgets, observability, and OpenAI/Anthropic-compatible surfaces.
|
|
|
|
Required prototype gates:
|
|
|
|
- verify the exact ChatGPT subscription OAuth flow and supported models against current provider terms;
|
|
- document token location, encryption, revocation, refresh, scope, and incident response;
|
|
- prove tenant isolation and prevent virtual keys from becoming Mosaic principals;
|
|
- verify streaming, tool calls, reasoning controls, cancellation, and idempotency metadata;
|
|
- fail closed instead of selecting an unhealthy provider merely to return a result;
|
|
- demonstrate that Mosaic audit correlation survives gateway retries/failover;
|
|
- keep channel ingress and connector credentials outside LiteLLM.
|
|
|
|
Source references:
|
|
|
|
- [LiteLLM ChatGPT subscription provider](https://docs.litellm.ai/docs/providers/chatgpt)
|
|
- [LiteLLM providers](https://docs.litellm.ai/docs/providers)
|
|
|
|
### Bifrost
|
|
|
|
**Disposition:** Candidate for governance/routing research; subscription OAuth compatibility unverified.
|
|
|
|
Useful concepts include virtual keys, budgets, rate limits, weighted load balancing, and automatic provider failover. Those features may inform Mosaic egress policy, but Bifrost virtual keys are downstream credentials—not Mosaic actors or tenants.
|
|
|
|
Required prototype gates:
|
|
|
|
- verify Codex/ChatGPT subscription OAuth rather than assuming API-key compatibility;
|
|
- map budgets and virtual keys to server-derived Mosaic tenants without duplicating authority;
|
|
- prove failover does not violate connector lease, approval, or exactly-once semantics;
|
|
- ensure request/response logs are redacted before persistence;
|
|
- disable or constrain automatic failover when policy or side-effect state is ambiguous.
|
|
|
|
Source references:
|
|
|
|
- [Bifrost overview](https://docs.getbifrost.ai/overview)
|
|
- [Bifrost repository](https://github.com/maximhq/bifrost)
|
|
|
|
### `teremterem/claude-code-gpt-5-codex`
|
|
|
|
**Disposition:** Not selected as the emergency implementation; useful as a historical LiteLLM recipe.
|
|
|
|
The reviewed repository uses `OPENAI_API_KEY`, tells previously authenticated Claude users to log out, and documents a Claude Web Search schema incompatibility. Logging Claude out conflicts with the channel-entitlement requirement observed in the live Mos cutover. The repository therefore does not, as provided, satisfy subscription-OAuth plus built-in-channel continuity.
|
|
|
|
Source references:
|
|
|
|
- [Repository](https://github.com/teremterem/claude-code-gpt-5-codex)
|
|
- [Environment template](https://github.com/teremterem/claude-code-gpt-5-codex/blob/main/.env.template)
|
|
|
|
## Security consequences
|
|
|
|
- Subscription OAuth grants are high-value credentials and require the same lifecycle controls as service credentials.
|
|
- Downstream virtual keys reduce provider-key exposure but do not establish user, tenant, or agent authority.
|
|
- Automatic retry/failover can duplicate tool or external side effects unless Mosaic owns operation IDs and receipts.
|
|
- Gateway telemetry can contain prompts, tool schemas, and model output; redaction and retention policy must apply before persistence.
|
|
- A localhost unauthenticated translation endpoint must remain loopback-only and process-isolated.
|
|
|
|
## Acceptance before production use
|
|
|
|
1. Threat model and provider-terms review approved.
|
|
2. Credential lifecycle and revocation drill documented and exercised.
|
|
3. Adapter contract tests pass for streaming, tools, cancellation, reasoning policy, errors, and audit correlation.
|
|
4. Tenant-bound authorization remains entirely in Mosaic Gateway.
|
|
5. Failure injection proves no duplicate side effects across retries or provider failover.
|
|
6. Rollback to the prior provider path is exercised.
|
|
7. Independent code and security reviews approve the exact deployed revision.
|
|
|
|
## Follow-up
|
|
|
|
- #754 owns cross-harness logical identity, checkpoint, receipt, adapter, and failover work.
|
|
- #755 / PR #757 implements the first logical identity and connector lease/fencing boundary.
|
|
- A later issue should prototype LiteLLM and Bifrost behind the provider adapter after #755 is merged and independently qualified.
|