Provider Model Catalog

The model catalog is the daemon-owned authority for provider model selection before a prompt binds ACP. The session-create dialog, CLI, HTTP, UDS, Host API, web settings, and the OpenAI-compatible model list all read the same projected rows. Creating a session does not start ACP; the first prompt carries its nested runtime snapshot and negotiates the selected provider, model, reasoning effort, and speed.

Catalog refresh never blocks session creation. Every refresh is detached from the request lifetime, runs under an explicit deadline, falls back to stale rows when refresh fails, and exposes source health through structured status. A requested model or reasoning effort can still fail before the first prompt when the active ACP adapter does not advertise an applicable option.

Why a separate catalog

ACP models.availableModels is observed only after prompt binding or replay, which is too late for the session-create dialog and for agents picking a model through CLI/HTTP/UDS. The catalog splits two concepts that used to live together:

• Pre-prompt catalog: which provider models CompozyOS knows about before a prompt binds a session.
• Bound runtime config: which controls the current ACP process exposes right now.

The catalog is daemon-owned, persisted, refreshable, extensible, and agent-manageable. Active session configOptions continue to govern the live session — catalog rows never override them.

Source priorities and merge

The merge key is (provider_id, model_id). Source rows are preserved separately and merged on read.

Higher-priority non-empty fields win; lower-priority sources fill missing fields. Ties resolve by fresher refreshed_at, then ascending source_id. models.dev and builtin rows can enrich metadata but never prove account-level availability.

Cursor registers provider_live:cursor with cursor-agent acp. The first catalog read with no recorded Cursor discovery status starts a short-lived ACP inspection under the provider's resolved home policy, reads the exact values in Cursor's advertised model option, and stores those rows before returning the projection. The human-readable cursor-agent models aliases are not used. Later reads use the stored result. A failed first attempt is also stored as source status; use the normal refresh surfaces to retry or update the account catalog.

Input, output, cache-read, cache-write, and reasoning prices merge independently and retain the source of the winning field. A cost estimate is available only when every nonzero usage bucket has its own finite, non-negative rate and all active rates have compatible provenance. Rates are never inferred between buckets.

Merged availability

The merged projection exposes both nullable available and string availability_state so stale live truth is visible instead of collapsed:

Manual model entry remains valid even when no source advertises the model. models.curated is metadata, never an allowlist.

Curated and all views

Catalog lists default to view=curated. When a provider has an explicit models.curated set, the projection contains its visible explicit entries plus visible featured models. Live discovery updates availability and metadata, but does not expand that set with every upstream model. When no explicit set exists, every current non-hidden, non-deprecated row forms the fallback. An explicit set still counts when all its entries are hidden or deprecated, so curation never reopens the full catalog by accident. Rows sort curated first, then non-deprecated, featured, newest known release date, and canonical model ID. This keeps excluded featured rows below actual curated members and demotes every deprecated row in the full search set.

view=all returns every current row, including hidden and deprecated entries. Use it when inspecting or reversing curation. The response field curated means the row participates in the current curated projection; it is not merely a check for a matching TOML array entry.

Native HTTP and UDS endpoints

List endpoints accept these query parameters:

• provider_id: filter by CompozyOS provider id (only on the cross-provider list).
• source_id: filter by catalog source id (config, models_dev, provider_live:<id>, extension:<slug>).
• view: curated (default) or all on list endpoints.
• refresh=true: refresh sources before listing.
• include_stale=true: include stale source rows in the merged projection.

Refresh requests accept an optional JSON body:

{
  "source_id": "provider_live:codex",
  "force": true,
  "request_id": "rfsh-2026-05-07-abc"
}

request_id (or a daemon-generated value) is the refresh_request_id correlation key surfaced in logs and source status events. Refresh work runs under daemon-owned lifetime: the request's cancel does not cancel refresh work, and the daemon joins outstanding refresh workers during shutdown.

The native list response shape is:

{
  "models": [
    {
      "provider_id": "codex",
      "model_id": "gpt-5.6-sol",
      "display_name": "GPT-5.6 Sol",
      "sources": [
        {
          "source_id": "config",
          "source_kind": "config",
          "priority": 120,
          "stale": false,
          "refreshed_at": "2026-05-07T18:32:11Z"
        },
        {
          "source_id": "models_dev",
          "source_kind": "models_dev",
          "priority": 50,
          "stale": false,
          "refreshed_at": "2026-05-07T03:00:00Z"
        }
      ],
      "available": true,
      "availability_state": "available_live",
      "stale": false,
      "refreshed_at": "2026-05-07T18:32:11Z",
      "context_window": 1050000,
      "max_output_tokens": 128000,
      "supports_tools": true,
      "supports_reasoning": true,
      "reasoning_efforts": ["none", "low", "medium", "high", "xhigh", "max"],
      "default_reasoning_effort": "medium",
      "cost": { "input_per_million": 5, "output_per_million": 30 },
      "curated": true,
      "deprecated": false,
      "hidden": false,
      "featured": true,
      "release_date": "2026-06-26",
      "reasoning_source": "catalog"
    }
  ]
}

Each cost bucket is independent. A model with five explicitly configured rates returns all five fields; omitted fields remain unpriced:

{
  "cost": {
    "input_per_million": 1.1,
    "output_per_million": 2.2,
    "cache_read_per_million": 0.11,
    "cache_write_per_million": 0.22,
    "reasoning_per_million": 3.3
  }
}

The built-in curated seeds are metadata, not an account-level availability promise. ACP live options remain authoritative when a session starts.

GPT-5.6 seeds carry release date 2026-06-26; Claude Fable 5 carries 2026-06-09. Unknown release dates remain absent rather than being inferred. The seed table lists only input/output rates; an active cache-read, cache-write, or reasoning bucket remains unpriced unless another catalog source provides that bucket's explicit rate.

Source status payloads carry source_id, provider_id, source_kind, refresh_state (idle | refreshing | succeeded | failed), last_refresh, next_refresh, last_success, row_count, stale, and a redacted last_error. Raw secrets, command lines, OAuth material, or provider response bodies never appear in last_error.

The HTTP and UDS transports return canonical, byte-equal JSON for the same projection so cross- transport regression tests can compare daemon output directly.

Native tools

Managed agents can use the compozy__provider_models toolset instead of shelling out to the CLI. The native tools share the same daemon service and response payloads as HTTP, UDS, and compozy provider models.

compozy__provider_models_list accepts view=curated|all; provider_id remains optional for read and refresh tools. compozy__provider_models_curate is mutating, requires providers.models.write, and accepts required provider_id/model_id plus optional hidden, featured, deprecated, and default_effort. The effort must be canonical and present in that model's actual subset. Omitted flags preserve projected values; a call with no optional flags still materializes an explicit curation row. Resolve the live descriptor before calling it.

OpenAI-compatible projection

A list-only OpenAI-compatible endpoint is registered on HTTP only. UDS does not expose this route.

GET /api/openai/v1/models
GET /api/openai/v1/models?provider_id=codex

Authentication uses the same bearer-auth and middleware contract as the rest of /api/*. CORS and rate-limit behavior follow HTTP defaults. Errors are wrapped in the OpenAI envelope shape ({"error": {...}}) but reuse CompozyOS's normal status-code semantics. Refresh work is not available through this endpoint; clients use the native catalog endpoints, the CLI, the Host API, or the web for refreshes.

{
  "object": "list",
  "data": [
    {
      "id": "gpt-5.6-sol",
      "object": "model",
      "created": 0,
      "owned_by": "codex",
      "compozy": {
        "provider_id": "codex",
        "model_id": "gpt-5.6-sol",
        "display_name": "GPT-5.6 Sol",
        "sources": ["config", "models_dev"],
        "available": true,
        "availability_state": "available_live",
        "stale": false,
        "supports_tools": true,
        "supports_reasoning": true,
        "reasoning_efforts": ["none", "low", "medium", "high", "xhigh", "max"],
        "default_reasoning_effort": "medium",
        "context_window": 1050000,
        "max_output_tokens": 128000,
        "cost": { "input_per_million": 5, "output_per_million": 30 }
      }
    }
  ]
}

The compozy extension key carries CompozyOS-specific metadata. Generated OpenAPI/SDK contracts treat it as a typed object (OpenAIModelCompozyPayload), not a free-form blob. This endpoint uses the curated projection; use the native catalog list with view=all to inspect hidden or deprecated rows.

Provider models CLI

The CLI surface lives under the singular provider namespace because the catalog is provider- scoped and already neighbors compozy provider auth. A top-level compozy models … alias is intentionally out of scope for the MVP to avoid forking the command contract before the first one is stable.

compozy provider models list [provider] -o json
compozy provider models list [provider] --all -o json
compozy provider models list [provider] --source models_dev --refresh --include-stale
compozy provider models set codex gpt-5.6-sol --featured=true
compozy provider models set codex gpt-5.6-luna --hidden=true --default-effort=high
compozy provider models refresh [provider] -o json
compozy provider models refresh [provider] --source provider_live:codex --force --request-id rfsh-abc
compozy provider models status [provider] -o json

refresh returns the same source-status payloads as the native HTTP/UDS refresh endpoints — not a single success line — so CI scripts and agents can act on partial-source failures without parsing stderr. List defaults to curated; --all exposes hidden and deprecated rows for reversal. --hidden=false, --featured=false, and --deprecated=false explicitly clear flags. set is a serialized global mutation and returns the config-apply result. JSON output is canonical: identical between compozy provider models … and the daemon HTTP response for the same projection.

Stable selection and curation errors

Session negotiation failures return HTTP/UDS 422 for the prompt that selected the runtime. A failed bind, replacement, or rollback does not create a persisted user_message; the logical session stays available for a later prompt. CLI and native-tool errors preserve the same diagnostic code.

See compozy provider models for full flag and output documentation generated from the cobra source.

Extension model.source contract

Extensions can provide model rows by declaring the manifest provide capability model.source. The daemon validates rows, persists them, and applies the normal merge policy. Extensions cannot own global catalog state; they only contribute source rows.

[capabilities]
provides = ["model.source"]

[permissions]
requires = ["models/list", "models/refresh", "models/status"]

[subprocess]
command = "node"
args = ["dist/index.js"]

For a subprocess extension this manifest is generated by compozy extension build from the SDK declaration; declare the provide surface and the permission list in code. CompozyOS derives the model:read and model:write consent areas from those methods — see Extension Permissions.

Extensions that provide model.source must implement the CompozyOS-to-extension service method models/list. The daemon calls it with a deadline-bound context; the extension returns rows scoped to provider IDs the extension declares.

Capability grants follow the same area-based scheme as other Host API methods:

Marketplace extensions are limited to read-oriented grants by policy, so a marketplace extension can declare model.read and read the projection but must request model.write explicitly to trigger refresh, and refresh grants stay subject to the marketplace policy review.

Extension source rows can carry deprecated, hidden, featured, nullable release_date, and independent input/output/cache-read/cache-write/reasoning rates. They are always validated through internal/modelcatalog; non-finite or negative rates, invalid dates, and other malformed rows produce a recorded source status (with redacted error) instead of corrupting the projection.

Refresh lifetime and serialization

• Cursor discovery runs once on the first catalog read that has no provider_live:cursor status.
• Later catalog list calls return stored rows without rerunning the Cursor CLI.
• A recorded failed or disabled first attempt is retried only by an explicit refresh.
• Refresh detaches from request cancellation via context.WithoutCancel(ctx) and re-attaches an explicit deadline through context.WithDeadline.
• Refresh work is serialized per provider_id before any subprocess or provider-home work.
• Concurrent refresh requests for the same provider coalesce behind the in-flight refresh and return identical source statuses when it finishes.
• Refreshes for different providers can run concurrently.
• The daemon joins outstanding refresh workers during shutdown.

Most discovery paths never create an ACP session. Cursor uses a short-lived ACP inspection because its CLI aliases are not transport values. Live provider sources fail closed by recording source status; an explicit Cursor model is accepted only when a fresh Cursor ACP catalog entry advertises its exact value. Stale rows remain visible as fallback metadata but cannot authorize that explicit Cursor selection.

Observability

Catalog operations emit structured events with the following correlation keys:

• refresh_request_id
• provider_id
• source_id
• source_kind
• model_id for row-scoped events
• extension_name for extension sources
• session_id only for ACP session config observations

Tracked events include refresh started/succeeded/failed, source row count changes, stale fallback usage, all-source failure, extension source denied/unavailable, and ACP config option captured/ updated transitions.

Related pages

• Providers covers [providers.<id>.models] and the per-provider models.discovery shape.
• config.toml documents [model_catalog.sources.models_dev] defaults.
• compozy provider models is the CLI generated from the cobra source.
• Develop Extensions covers the manifest provide capability model.source and Host API model methods.