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.

Providers with a safe live adapter register provider_live:<id> sources. Claude, Codex, and Hermes inspect a short-lived ACP session and preserve the exact model and configuration options it advertises. Cursor instead runs cursor-agent models, groups its transport aliases into logical model IDs, and stores the valid Reasoning, Fast, and Thinking combinations without exposing those aliases. The first catalog read with no recorded status bootstraps these sources before returning; later reads use persisted rows and refresh them in the background. A failed attempt is recorded as source status and never replaces the last successful rows with an empty catalog.

Provider overlays

A provider overlay with runtime_provider = "claude" uses the Claude live-discovery adapter while keeping its own provider ID, launch command, environment/home policy, credential bindings, and profile/workspace catalog scope. Creating or deleting an overlay through Settings updates live source registration without a daemon restart. Removal clears that overlay's live discovery cache across profiles/workspaces; recreating it requires a new successful discovery. Source health appears as provider_live:<overlay-id>.

Claude's advertised aliases, such as haiku and sonnet, map to logical catalog IDs using the runtime family's built-in identities and the overlay's configured model identities. Session creation resolves the private transport alias from that overlay's live catalog. Another account's catalog cannot establish availability for the overlay. Built-in identity hints do not add unadvertised rows.

Refresh and inspect the overlay before curating a model:

compozy provider models refresh claude-secondary
compozy provider models list claude-secondary --all
compozy provider models set claude-secondary <model-id-from-list>

Command-based overlays such as Cursor and OpenCode must configure models.discovery.command for their account. The built-in discovery command is not inherited across account commands.

An empty or failed live response remains visible in source status; it does not make static model IDs startable. Existing explicit models.curated entries still control the curated view.

Automatic model updates

Live provider catalogs have a five-minute freshness window. The daemon refreshes them periodically and schedules a non-blocking refresh when a read finds stale data. A newly released model therefore appears without a CompozyOS code change when the provider advertises it through ACP, cursor-agent models, a configured discovery source, or an extension model.source. The built-in catalog is only an offline fallback; it includes Claude Opus 5 so that model remains visible before the first successful live refresh.

An explicit models.curated set still controls the default curated view. A newly discovered model may first appear only under view=all until it is featured or added to that set. OpenClaw is provider-managed: its Gateway owns model selection, so CompozyOS does not fabricate catalog controls for it.

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",
      "config_options": [
        {
          "id": "thinking",
          "label": "Thinking",
          "category": "thought_level",
          "kind": "boolean",
          "current_bool": false
        }
      ],
      "configurations": [{ "reasoning_effort": "high", "fast": true, "thinking": false }],
      "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 or default_speed. The effort must be canonical and present in that model's actual subset. Speed accepts normal or fast; Fast is rejected when the model explicitly advertises only normal configurations. Omitted fields preserve projected values; a call with no optional fields 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 set cursor grok-4.5 --default-effort=high --default-speed=fast
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

• A first catalog read with no matching source status bootstraps the dynamic source before returning.
• Later reads return persisted rows immediately and schedule non-blocking refresh work. The refresh planner skips a source while its five-minute TTL remains fresh.
• A 30-second background sweep evaluates provider-live and extension sources, so expired rows refresh even when no catalog client is polling.
• Failed refreshes record diagnostics and retain the last successful rows as stale data. A later background, read-triggered, or explicit refresh retries the source.
• 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.

Codex uses the installed native CLI app server’s model/list endpoint to discover each model’s supported reasoning levels, default, and visibility across all result pages. This includes new models without adding their names to the built-in catalog. Explicit discovery commands retain their configured behavior. Claude and Hermes use short-lived ACP inspection so catalog values match the runtime transport. Cursor uses cursor-agent models; advertised reasoning, thinking, and Fast variants remain selectable through their exact launch bindings. Reasoning support alone does not imply an adjustable effort. Effort IDs are provider-owned strings: known values such as ultra receive friendly labels, and new advertised values survive discovery, persistence, and selection without a release. The active provider validates membership. OpenCode discovery reads opencode models --verbose to retain each model's capabilities and effort variants. Configured discovery uses its declared command or endpoint, and extension sources call their models/list capability. Dynamic sources fail closed by recording source status; an explicit Cursor model is accepted only when a fresh Cursor catalog row advertises its logical identity. Stale rows remain visible as fallback metadata but cannot authorize that explicit 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.