feat: add Codex AI proxy credential fallback

[simple-agent-manager]

Summary

• When no user-provided OpenAI API key exists for the openai-codex agent type, inject SAM's AI proxy as the credential source for zero-key onboarding
• Mirrors the Claude Code fallback (PR feat: add Claude Code AI proxy credential fallback #862) but for OpenAI/Codex: returns provider: 'openai-proxy' with baseURL: https://api.{domain}/ai/v1
• VM agent injects OPENAI_BASE_URL, OPENAI_API_KEY (callback token), and optionally OPENAI_MODEL env vars into the Codex container
• Default model gpt-4.1, configurable via AI_PROXY_DEFAULT_OPENAI_MODEL env var

Changes

• packages/shared/src/constants/ai-services.ts — new DEFAULT_AI_PROXY_OPENAI_MODEL constant
• apps/api/src/env.ts — added AI_PROXY_DEFAULT_OPENAI_MODEL env var type
• apps/api/src/routes/workspaces/runtime.ts — extended proxy fallback to include openai-codex with openai-proxy provider
• packages/vm-agent/internal/acp/session_host.go — added Codex env var injection branch
• apps/api/.env.example — documented new env var

Validation

• pnpm lint
• pnpm typecheck
• pnpm test (pre-existing ButtonGroup test failure unrelated)
• pnpm build
• 7 new unit tests + 12 existing proxy tests pass (no regressions)

Staging Verification (REQUIRED for all code changes — merge-blocking)

• Staging deployment green — Deploy Staging workflow passed for this branch
• Live app verified via Playwright — logged into app.sammy.party using test credentials
• Existing workflows confirmed working — dashboard, projects, settings all load correctly, no console errors
• New feature/fix verified on staging — backend-only API change; deploy succeeds, API healthy, no regressions. Full Codex proxy exercise requires provisioning a Codex workspace (infrastructure dependency).
• Infrastructure verification completed — N/A: no infra changes (cloud-init, DNS, TLS unchanged)
• Mobile and desktop verification notes added for UI changes — N/A: no UI changes

Staging Verification Evidence

• Staging deploy run #25196734803 succeeded
• Authenticated to app.sammy.party via token-login
• Dashboard renders with project cards, Settings loads, Project chat loads
• API health: {"status":"healthy"} at api.sammy.party/health
• No new console errors (0 errors, 1 warning — pre-existing)

UI Compliance Checklist (Required for UI changes)

N/A: no UI changes

End-to-End Verification (Required for multi-component changes)

• Data flow traced from user input to final outcome with code path citations
• Capability test exercises the complete happy path across system boundaries
• All spec/doc assumptions about existing behavior verified against code
• If any gap exists between automated test coverage and full E2E, manual verification steps documented below

Data Flow Trace

1. Agent session starts, VM agent calls POST /api/workspaces/:id/agent-key with agentType: 'openai-codex'
   → apps/api/src/routes/workspaces/runtime.ts agent-key handler
2. No user credential found → AI proxy fallback fires
   → runtime.ts:81 checks PROXY_ELIGIBLE_AGENTS.has('openai-codex') → true
3. Returns inferenceConfig: { provider: 'openai-proxy', baseURL: 'https://api.{domain}/ai/v1', model: 'gpt-4.1' }
   → runtime.ts:95-108
4. VM agent receives response, matches agentType == "openai-codex" && provider == "openai-proxy"
   → packages/vm-agent/internal/acp/session_host.go:1008-1020
5. Injects OPENAI_BASE_URL, OPENAI_API_KEY (callback token), OPENAI_MODEL into container env
6. Codex uses these to call {OPENAI_BASE_URL}/chat/completions → SAM's AI proxy

Untested Gaps

Go-side injection branch has no automated test (pre-existing gap — same for claude-code branch). TypeScript tests cover the full API response shape. Backlog task filed: tasks/backlog/2026-05-01-ai-proxy-credential-hardening.md.

Post-Mortem (Required for bug fix PRs)

N/A: not a bug fix

Specialist Review Evidence (Required for agent-authored PRs)

• All dispatched reviewers completed and findings addressed before merge
• If any reviewer did NOT complete: needs-human-review label added and merge deferred to human — all completed

Reviewer	Status	Outcome
task-completion-validator	PASS	All checks A-E pass; 1 LOW (pre-existing Go test gap)
go-specialist	PASS	1 MEDIUM (pre-existing double-injection pattern), 1 MEDIUM (pre-existing Go test gap), 1 LOW
cloudflare-specialist	ADDRESSED	.env.example added, Set moved to module scope, KV comment added (commit df28cfd)
security-auditor	ADDRESSED	2 HIGH (pre-existing patterns identical to claude-code PR#862) → backlog task filed; 3 MEDIUM (documented/pre-existing)
env-validator	ADDRESSED	.env.example entry added (commit 795a1c4)

Exceptions (If any)

• Scope: Security HIGH findings deferred to backlog
• Rationale: Both HIGH findings (callback token lifetime, platform_proxy sentinel) are pre-existing architectural patterns identical to the already-merged claude-code proxy (PR feat: add Claude Code AI proxy credential fallback #862). Not regressions from this PR.
• Expiration: Tracked in tasks/backlog/2026-05-01-ai-proxy-credential-hardening.md

Agent Preflight (Required)

• Preflight completed before code changes

Classification

• external-api-change
• cross-component-change
• business-logic-change
• public-surface-change
• docs-sync-change
• security-sensitive-change
• ui-change
• infra-change

External References

N/A: mirrors existing claude-code proxy pattern (PR #862). No new external API integration.

Codebase Impact Analysis

• packages/shared — new constant DEFAULT_AI_PROXY_OPENAI_MODEL
• apps/api — extended agent-key fallback in runtime.ts, new env var in env.ts
• packages/vm-agent — new injection branch in session_host.go

Documentation & Specs

• apps/api/.env.example — added AI_PROXY_DEFAULT_OPENAI_MODEL
• CLAUDE.md — no update needed (AI proxy gateway entry already covers the pattern)

Constitution & Risk Check

• Principle XI (No Hardcoded Values): Default model gpt-4.1 is configurable via AI_PROXY_DEFAULT_OPENAI_MODEL env var with shared constant fallback
• All URLs derived from BASE_DOMAIN env var
• No hardcoded timeouts or limits introduced

[sonarqubecloud]

Quality Gate failed

Failed conditions
79.0% Duplication on New Code (required ≤ 3%)

See analysis details on SonarQube Cloud