tutti/docs/architecture/model-access-plans.md

Model Access Plans

Model access plans are daemon-owned, per-workspace configurations for routing supported agent runtimes through a named model endpoint. A plan owns its wire protocol, endpoint, encrypted credential, model catalog, default model, detection state, and enabled state.

This slice owns Plans. WorkspaceAgent is the user-facing configuration seam that combines one Harness AgentTarget with an optional Plan/default model and instructions. The older per-AgentTarget binding and modelpolicy domains are compatibility-only: they remain readable for historical sessions and deletion protection, but Desktop Settings must not expose them as parallel writable configuration.

Ownership

• services/tuttid/biz/modelplan owns the Plan model and validation.
• services/tuttid/data/workspace owns Plan persistence and retains legacy binding persistence during the compatibility window.
• services/tuttid/service/modelplan owns CRUD, staged endpoint detection, and deletion protection.
• services/tuttid/service/workspaceagent owns every new Harness-to-Plan mapping. services/tuttid/service/modelbinding is a legacy adapter and reference source; Desktop no longer calls its write routes.
• packages/agent/daemon/providerregistry declares whether a provider runtime accepts a model-plan endpoint, which protocol it consumes, and whether it requires the Responses-to-Chat gateway adapter.
• packages/agent/runtimeprep contains the provider-specific endpoint adapters. Codex and Tutti Agent receive session-scoped Responses provider configurations pointed at the daemon's loopback Model Gateway; Claude Code receives its supported environment contract; OpenCode receives a session-scoped opencode.json provider block via OPENCODE_CONFIG (credential travels only as TUTTI_MODEL_PLAN_API_KEY with an {env:…} reference in the file).
• services/tuttid/service/modelgateway owns the local Responses API ↔ Chat Completions API transport adapter. It does not define session lifecycle, expose a public daemon API, or act as a general multi-provider protocol IR.
• services/tuttid/service/agent resolves the WorkspaceAgent and supplies its Plan endpoint to runtime preparation. Unsnapshotted historical sessions may still use the isolated legacy-binding fallback.
• Desktop settings and AgentGUI composer surfaces consume the daemon APIs directly; they do not own plan credentials or detection state.

Provider support is fail-closed. A provider may advertise modelPlanBinding only when its registry descriptor declares a protocol and a matching runtime-preparation adapter exists. OpenCode consumes openai plans through that path; Cursor currently keeps its provider-native credential source. Provider catalog identity carries modelPlanProtocol so desktop resolves protocols through the catalog instead of provider-identity switches.

Request And Runtime Flow

1. A client creates a Plan through the OpenAPI-defined daemon route. Saving does not require or trigger detection; the user may explicitly run the connection check on any saved Plan.
2. The user explicitly creates a WorkspaceAgent by choosing one Harness and, optionally, one Plan/default model. Saving a Plan never creates the Harness × Plan Cartesian product.
3. Before a new session starts, tuttid resolves that WorkspaceAgent and validates its requested model against the Plan catalog.
4. Runtime preparation injects the endpoint and credential only into the session-scoped provider environment/configuration. Codex and Tutti Agent receive a temporary gateway token instead of the upstream Plan credential. Credentials are never returned by the API or written into generated instructions and manifests.

Disabling a plan prevents new sessions from using it; existing running sessions are not interrupted. Deleting a plan is rejected while any consumer still references it: agent target bindings and model-usage policies both count. The references API returns agent_target and model_policy entries, each carrying the consumer's role (bindings report default; policies report execution, planning, or review). Symmetrically, deleting a model-usage policy is rejected while any agent binding still references it; rebind or clear those bindings first.

Product Availability

Model Plan reads and writes are generally available and do not depend on desktop preferences. Desktop always exposes Plans in an independent top-level Model tab and Custom Agents under Agent. Historical lab.modelPlans and lab.workspaceAgents preference values are ignored.

Credential Ownership

• Plan credentials are AES-256-GCM encrypted at rest in model_plans (api_key_ciphertext), sharing the managed-credential key derivation.
• API responses expose only hasApiKey. For Responses-gateway consumers (currently Codex and Tutti Agent), the upstream credential remains in daemon memory and only a random 256-bit gateway token enters TUTTI_MODEL_PLAN_API_KEY. Other supported runtimes continue to receive their provider-specific session environment, and the legacy workspace-app grant broker remains a separate credential egress.
• Credentials must never appear in logs, events, timeline payloads, detection results, or generated provider instructions. runtimeprep writes the Codex-compatible provider table with env_key, never the key value. The gateway also redacts the exact upstream credential from forwarded error bodies.

Staged Detection

modelplan.Service.Detect runs four daemon-verifiable stages in order — network → auth → model_discovery → inference — each with a machine-readable failureReason/remedy code. A Plan becomes ready when all four stages pass or are explicitly skipped. Saving a new or changed Plan never runs this check and never blocks on its result: a new Plan starts undetected, and connection changes reset it to undetected until the user runs the saved-row check.

Providers without a /models catalog (404 on every candidate) keep working: discovery is skipped when manual models exist and the inference stage becomes the authoritative credential check.

Provider discovery is a candidate catalog, not a user selection. When an endpoint-backed draft has no selected model but discovery returns candidates, detection may use the first candidate only as the ephemeral inference target for that run. The tested id is recorded in the detection snapshot, while the Plan's models and defaultModel remain unchanged until the user selects one.

official_subscription uses a different adapter behind the same stages. The provider registry chooses the one native runtime for each protocol (Codex for OpenAI and Claude Code for Anthropic). Detection checks installation/runtime, the provider's existing login, provider-native model discovery, and one hidden minimal inference call. It never accepts a Base URL/API key or returns native credentials. Endpoint-backed templates continue to use the HTTP detection path.

Runtime Injection Chain

WorkspaceAgent primary Plan/default model
  -> agent.Service.resolveModelPlanEndpoint (Create + prepareRuntime)
  -> runtimeprep.PrepareInput.ModelEndpoint
  -> Codex / Tutti Agent:
     agent.Service registers workspace/session route in loopback Model Gateway
     -> provider preparer writes local /v1 + temporary env_key + wire_api=responses
     -> gateway translates POST /v1/responses to upstream /v1/chat/completions
     ClaudeCodePreparer: ANTHROPIC_BASE_URL + ANTHROPIC_API_KEY|ANTHROPIC_AUTH_TOKEN
     OpenCodePreparer: session opencode.json provider block via OPENCODE_CONFIG
  -> provider runtime speaks to the plan endpoint for the whole session

Rules:

• Protocol compatibility is explicit: codex/tutti-agent/opencode consume openai plans, claude-code consumes anthropic plans. Cursor keeps provider-native credentials (no endpoint injection) — no fake UI entry points.
• Anthropic-protocol credential injection follows the endpoint's Claude Code contract, not a blanket “official versus relay” rule. api.anthropic.com and Kimi Coding (api.kimi.com) require ANTHROPIC_API_KEY/x-api-key; other relay-style endpoints keep the bearer ANTHROPIC_AUTH_TOKEN default. Runtime preparation explicitly blanks the opposite credential variable so inherited shell or Claude settings cannot override the Plan's auth shape. Detection and the launched Agent must use equivalent authentication shapes, or a plan can pass inference detection while every real Agent turn gets 401.
• Model addressing is a second registry strategy (ModelPlanModelAddressing): OpenCode declares provider_prefixed, so its composer/settings values carry the injected tutti-model-plan/<model> namespace resolved against the session-scoped provider block. Other providers consume raw plan model ids; validation strips the namespace back to plan-domain ids.
• Disabled or protocol-mismatched plans fall back to the provider-native credential source with a structured log, never a broken session.
• A plan-bound session validates requested models against the plan's model list (validateModelAgainstPlan), not provider catalogs.
• Responses-gateway routes are in-memory runtime resources keyed by workspace/session. Create failure, deletion, legacy cleanup paths, and resume replacement revoke the previous token. Before each new ordinary Turn, a plan-bound Session compares its snapshotted revision with the current revision of that exact Plan. A change prepares a replacement runtime from the new immutable revision, atomically swaps the durable snapshot, and only then admits the Turn. Guidance and an already-running Turn keep their existing binding.
• The Responses-to-Chat gateway is bound to 127.0.0.1:0 on its own listener and serves only authenticated POST /v1/responses. It is not mounted on the public tuttid HTTP router, so no daemon OpenAPI change is involved.
• Gateway v1 supports messages, text/image input, function calls and outputs, function tools (including Codex namespace containers, with collision-safe Chat names restored on Responses output), reasoning effort/content extensions, Chat JSON/SSE, usage, cancellation, and bounded timeouts. Responses roles follow the Codex-to-Chat normalization used by cc-switch: developer becomes system, latest_reminder and unknown internal roles become user, text-only content-part arrays are joined with newlines, and all textual system instructions are merged in original order into the first Chat message. This preserves instruction precedence while supporting upstreams that only tokenize the portable role set or only allow system at message index zero. At the request boundary, the gateway intersects tool registrations with this translatable set: non-translatable hosted or future tool declarations are omitted before forwarding to Chat. If filtering leaves no tools, it also omits tool_choice and parallel_tool_calls. Explicit selection of a filtered tool, required with no remaining tool, and hosted tool call/output history remain hard errors because dropping them would change requested or already-recorded conversation semantics. Background Responses, Conversations, Realtime/WebSocket, /responses/compact, and non-empty previous_response_id are also rejected instead of dropped.
• Composer options for a bound target replace provider-native model options with the plan's models (applyModelPlanComposerOverlay); each option carries the source plan name and runtimeContext.modelPlan = {id, name, protocol}.

Model Switch Semantics

• Within one plan (same credential/base URL): the model change applies to the next call of the same session — modelSwitch capability, existing session settings update path.
• Across plans or credential sources: always a new session (the endpoint is fixed at session start). UI must present this as "will apply in a new session" and reuse the existing handoff/draft-prefill launch path; there is no pretend hot switch.
• Configuration changes never touch running calls; they affect the next call that has not started.

Acceptance Ladder And The Fixed Review Rule

modelpolicy keeps a per-session acceptance ladder: agent_claimed → auto_checked → user_accepted. Only an explicit user action reaches user_accepted today. Automated review runs and automated ladder advancement remain deferred; do not document or UI-promise those behaviors until the later stack layer lands. Review runs must never close work without the user.

Explicit in-composer “model consult” (ask another plan/model for advice from the current session) is not a product surface: do not ship composer entry points, runtime commands, timeline cards, or @ mentions for it. Model access plans remain configurable through workspace settings and Agent/plan assignment surfaces; the composer does not select models through its @ panel.

Migration

model_plans_v1 backfills every legacy managed_model_provider_credentials row into a named plan (mp-migrated-<provider>), copying the ciphertext as-is. The WorkspaceAgent migration deterministically materializes legacy AgentTarget bindings as source=legacy_binding Agents. Legacy binding rows stay for rollback and pre-snapshot session recovery; new renderer writes are forbidden and the migration must remain idempotent.

The retired first_use_json column and model_plan_first_use_candidates_v1 table migration remain in the SQLite schema for downgrade compatibility. Current code does not expose, write, or reconcile first-use state.

Reference Protection

DELETE /v1/workspaces/{id}/model-plans/{planId} is blocked (409 model_plan_referenced) while WorkspaceAgents or legacy consumers reference the plan; GET .../references lists the consumers so the UI shows impact before edits. The resolver composes per-consumer sources (modelbinding.Service, modelpolicy.Service, and workspaceagent.Service). Symmetrically, DELETE /v1/workspaces/{id}/model-policies/{policyId} is blocked (409 model_policy_referenced) while any agent binding still references the policy.

What To Avoid

• Do not add a "global current model" or a second AgentTarget binding editor. New model selection is owned by explicit WorkspaceAgents.
• Do not surface plan credentials to the renderer, tests, or snapshots.
• Do not point Codex or Tutti Agent directly at a Chat-only Plan while declaring wire_api = "responses"; the loopback Model Gateway is the protocol boundary.
• Do not advertise modelPlanBinding for providers without a real injection path.
• Do not let automated review close work; the ladder tops out at auto_checked without the user.