feat(cloud-agent-next): reject unavailable models before admission

[eshurakov]

Summary

• Adds lightweight personal and organization model-validation API contracts so Cloud Agent can check selected Kilo model availability against the effective catalog before dispatch.
• Architecturally, cloud-agent-next now performs prompt-only model preflight at prepare, start, and send admission boundaries, failing unavailable selections synchronously and treating unavailable validation infrastructure as retryable failure.
• Aligns dispatched model normalization and extends the fake gateway/E2E harness to prove rejected models create no sandbox work or chat-completion dispatch.

Verification

• Confirmed accepted models complete a cold turn plus hot follow-up turns through both the unified and legacy API surfaces using the deterministic local fake gateway.
• Confirmed an unavailable initial model is rejected before sandbox creation or chat-completion dispatch through both API surfaces using the fake validation gateway.
• Confirmed an unavailable initial model is rejected before sandbox creation through both API surfaces when validation routes through the local Next.js gateway.
• Confirmed unavailable follow-up sends reject without an added chat-completion dispatch for both API surfaces; the gated legacy turn completes after release with no remaining fake-gateway waiters.

Reviewer Notes

• Focus on catalog-source resolution in services/cloud-agent-next/src/model-validation.ts, including official versus override/token-routed validation and scoped 401 fallback behavior.
• Prompt-only enforcement is intentional; command-valued prepared sessions remain outside this change.
• The preflight adds an availability request before accepted prompt work and fails closed when availability cannot be established.

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Executive Summary

Incremental commit feab35479 simplifies the 404 rollout strategy: instead of falling back to the catalog endpoint when the official /validate route returns 404, validation is now silently skipped (fail-open) with a warning log. The change is clean, tests are updated to match, and no new issues are introduced.

Resolved Issues

File	Issue	Status
services/cloud-agent-next/src/model-validation.ts	organizationId interpolated without encodeURIComponent in buildKiloOverrideValidationUrl	✅ Fixed in 974b45399 — uses encodedOrganizationId
services/cloud-agent-next/src/session/model-preflight.ts	Silent skip of model validation when turn is undefined — logic opaque	✅ Clarified in 974b45399 — comment added explaining legacy metadata fallback
apps/web/src/app/api/openrouter/models/validate/route.ts	Could the BYOK and experiment catalog reads run in parallel	✅ Fixed in 01a08128b — now uses Promise.all
services/cloud-agent-next/src/router/handlers/session-send.ts	Could preflight run only for a new admission? A retry would needlessly re-validate	✅ Fixed in 01a08128b — prompt retries with an already-admitted message skip model preflight
services/cloud-agent-next/src/model-validation.ts	404 fallback to catalog creates mutual recursion risk	✅ Simplified in feab35479 — 404 from official route now returns skipped (fail-open with warning log), validateFromExistingOfficialCatalog and officialCatalogResponseSchema removed entirely

Notes on incremental diff (feab354)

Simplified 404 handling: The previous strategy fell back to the catalog endpoint (/api/openrouter/models or /api/organizations/:id/models) when the /validate route returned 404 during rollout. This created mutual recursion between validateFromOfficialSource and validateFromExistingOfficialCatalog. The new strategy simply returns { type: 'skipped' } which passes validation with a warning log — appropriate for the rollout window.

Asymmetric 404 behavior is intentional: The official source is fail-open on 404 (route not deployed), while override/BYOK sources remain fail-closed on 404 (line 176: validation-unavailable). This correctly reflects that a 404 from an override endpoint is unexpected and not a rollout concern.

Files Reviewed (27 files)

• apps/web/src/app/api/openrouter/models/validate/route.ts
• apps/web/src/app/api/openrouter/models/validate/route.test.ts
• apps/web/src/app/api/organizations/[id]/models/validate/route.ts
• apps/web/src/lib/ai-gateway/validate-kilo-agent-model.server.ts (deleted)
• apps/web/src/lib/ai-gateway/validate-kilo-agent-model.server.test.ts (deleted)
• services/cloud-agent-next/src/model-validation.ts
• services/cloud-agent-next/src/model-validation.test.ts
• services/cloud-agent-next/src/session/model-preflight.ts
• services/cloud-agent-next/src/session/model-preflight.test.ts
• services/cloud-agent-next/src/session/session-message-queue.ts
• services/cloud-agent-next/src/session/session-message-queue.test.ts
• services/cloud-agent-next/src/session/queue-message.ts
• services/cloud-agent-next/src/session/legacy-prepared-admission.ts
• services/cloud-agent-next/src/router/handlers/session-execution.ts
• services/cloud-agent-next/src/router/handlers/session-send.ts
• services/cloud-agent-next/src/router/handlers/session-start.ts
• services/cloud-agent-next/src/router/handlers/session-prepare.ts
• services/cloud-agent-next/src/persistence/CloudAgentSession.ts
• services/cloud-agent-next/src/persistence/model-utils.ts
• services/cloud-agent-next/src/router.test.ts
• services/cloud-agent-next/test/e2e/fake-llm-server.ts
• services/cloud-agent-next/test/e2e/lifecycle.ts
• services/cloud-agent-next/test/e2e/client.ts
• services/cloud-agent-next/test/e2e/README.md
• services/cloud-agent-next/test/unit/fake-llm-server.test.ts

---

_{Reviewed by claude-4.6-sonnet-20260217 · 382,976 tokens}

_{Review guidance: REVIEW.md from base branch main}