agentic-mobile-control/openspec/changes/database-llm-provider-management/proposal.md

Why

The Cloud Control Plane proxy currently reads its LLM provider, model, and credentials from process environment variables. Changing a model therefore requires a deployment change and cannot be audited or operated from the Cloud Console, even though every cloud-transport Host Agent already depends on the control plane for its planner decisions.

What Changes

• Add a durable, Cloud-wide catalog of planner Provider profiles. Each profile records its supported provider kind (anthropic or openai-compatible), model, timeout, optional OpenAI-compatible base URL, enabled state, and an encrypted API key.
• Add an administrator-only Cloud API and Cloud Console view to create, list, update, activate, disable, and retire Provider profiles. Read responses never expose an API key; writes can rotate a key without returning it.
• Make the cloud planner-decision endpoint resolve the active profile from the database for each request, so a newly activated profile applies to all cloud-transport Host Agents without changing their configuration or restarting them.
• Remove Cloud API environment-variable configuration for the planner provider, model, timeout, and Provider API keys. An absent active database profile fails closed instead of silently using a stale environment credential.
• Add an encryption-key configuration for protecting Provider API keys at rest and document deployment, rotation, and migration behavior.
• Extend the existing provider client construction so cloud-managed OpenAI-compatible profiles pass their encrypted API key and configured base URL explicitly to the OpenAI SDK, while Host Agent direct transport continues to use its existing environment-based credentials.

Capabilities

New Capabilities

• llm-provider-management: Durable, administrator-managed Cloud-wide LLM Provider profiles, encrypted credential handling, and Console/API operations.

Modified Capabilities

• cloud-planner-proxy: Cloud planner decisions select their provider, model, timeout, and credential from the active database profile once database management is enabled, rather than requiring a Cloud API restart and environment-variable change.

Impact

• packages/cloud-platform/cloud: SQLAlchemy models, repository contract and implementation, Alembic migration, encrypted-secret service, and planner client construction from a resolved profile.
• apps/cloud-api and cloud.sdk: an authenticated management router and application composition for the new service.
• cloud-console: an administrator-only Provider management view, client API, and types.
• Cloud deployment configuration: the encryption key remains deployment-held, while planner Provider/model/timeout/API-key environment variables are removed.