small gleam coding and (not yet) persistent agent daemon with a detachable cli forked from okami.mom/albedo
albedo robot-docs models.md
13 kB · 247 lines
Markdown
at main

Models catalog #

The models extension supplies model metadata to the harness. Provider extensions can also supply model lists and metadata. Authentication and profile selection are described in model authentication.

Cache #

The models extension stores the catalog as models.json in the Albedo home. Its default URL is https://models.dev/api.json, and its default refresh interval is 24 hours. A refresh runs in the background when the cache is missing or old. A failed fetch keeps the previous cache. refreshHours set to zero disables that automatic fetch. An explicit reload reports fetch errors.

The typed catalog projection decodes provider and model metadata and trims fetched catalogs to the fields lookup uses. The catalog cache owns isolated parsing, the persisted index, and publication of the provider and model maps together. It parses one file revision once. A revision is the file's size and modification time from albedo_env/file_revision. One caller parses a revision while the others wait on the catalog's sdk/file path lock. The maps are shared through sdk/pinned without copying them. The index is saved beside the catalog as models.json.index in version 4. A version 3 index from an earlier daemon is still read, and the next parse writes version 4. The fetch goes through sdk/cached_fetch. The catalogue module bounds fetched catalogs at 32 MiB and answers lookups and listings from those maps. Legacy untrimmed files are rewritten on first parse while preserving their modification time. The catalog is external data, not a guarantee of a provider's current offerings.

Lookup #

catalog.select uses the endpoint host to select a provider when possible. chatgpt.com selects the OpenAI catalog identity. Without an attributed match, it uses the smallest known context limit, reports an output limit only when known limits agree, and intersects reported modalities and efforts. select_provider instead requires the named provider.

When a model is missing, the catalogue lookup can infer low, medium, and high reasoning efforts from certain model names. That fallback does not supply catalog limits. A failed lookup otherwise returns no metadata.

Display names #

ModelInfo carries an optional display_name separately from the request's model ID. The model resource returns it as label, falling back to the ID for absent or blank names. Names are presentation only; clients send the original ID when selecting or invoking a model.

The Codex and Claude catalogs retain upstream display_name, and Antigravity retains its discovered name after stripping trailing variant effort suffixes such as (High) or (XHigh). The models.dev projection keeps each model's name through trimming and index reloads. Unattributed lookup uses a name only when the reported nonempty names agree. Older caches without names still work.

Reasoning defaults #

ModelInfo stores supported reasoning levels and the optional default_effort separately, both as types.Effort. Each catalog reads its provider's names into that type at its own edge and leaves out a name albedo has no level for; Antigravity's extra-low tier is minimal. An ordered list of supported levels does not establish a provider default. The model resource exposes both facts to clients. A null default means that Albedo does not know the level.

The Codex catalog retains the backend's default_reasoning_level as default_effort in its cache. It accepts that default only when it is a supported requestable level. Old caches without the field remain readable. Other catalogs can leave the default unknown rather than guess from the model name or effort order.

The runtime resolver converts saved reasoning choices before constructing the provider context:

  • inherit follows the profile's explicit effort when configured. Otherwise it follows the model default.
  • default follows the model default even when the profile specifies a level.
  • A supported level such as high is an explicit override.

Antigravity requires an Albedo-selected fallback tier; its catalog reports that tier with default_effort_source set to albedo. Provider-advertised defaults use provider. Conflicting Codex account defaults are left unknown.

A known model default becomes the request's effort. An unknown default omits the effort control so the provider decides. The reserved choices do not reach provider request encoders. Catalog reads remain local and do not send inference requests. Clients must preserve the choice across model switches rather than replace it with their own preferred level.

Request effort #

A request carries a typed effort, types.Effort: none, minimal, low, medium, high, xhigh or max, or no effort at all. Saved session and profile choices stay strings, inherit, default or a level name. Session configuration, child and peer creation, profile settings and the proxy parse a level name with types.parse_effort when it arrives and refuse one it does not name; runtime.resolve_effort turns the saved choice into the turn's effort.

A provider sends the effort a request asks for when the model takes it, and otherwise applies its own rule with what its catalog knows about the model. Nothing outside the provider reads a model's effort list to choose a request's effort.

  • Claude, Codex, the OpenAI-compatible provider, GitHub Copilot, OpenCode Go and Zen, Mistral, Perplexity and Bedrock Messages use extension.within_listed_efforts with their catalog's entry for the model: the highest listed level below the one asked for, else the lowest above it, never stepping down to none, and no effort for a model listed without efforts or not listed at all (types.nearest_effort).
  • Bedrock Converse applies the same rule to its verified levels, and sends no reasoning fields for a model without a verified mapping.
  • The Anthropic gateway applies it to thinking.supported_efforts.
  • Vertex Gemini maps every level onto a budgeted model's budgets, none and minimal turning thinking off where the model allows it, and to the nearest named level for a model that takes levels. A model its table does not know gets no thinking control.
  • Antigravity picks the nearest of the variant tiers the model lists, and takes the level as asked for a model listing none.

A summarizer request of its own (loop.separate: lcm leaves and merges, persistent-agent consolidation, rolling and rewind summaries) asks for medium. Replayed summaries and the persistent-agent memory request keep the turn's effort, because they read the turn's cached prefix. A generated title asks for none, which a provider sends as the lowest level the model takes. The request ledger records the effort a request asked for.

New sessions save inherit when effort is omitted or null. Existing saved levels remain explicit overrides. Existing null choices retain their legacy omission behavior. Codex's legacy null choice still sends medium, matching its earlier encoder. See session settings for the persistence and validation owners.

The clients annotate the actual default level in their reasoning menus. They show a provider-default entry only when its level is unknown. They display the effective level separately from its source: the profile, the model default, or an Albedo fallback. When a profile overrides effort, a separate advanced action switches between that profile and the model default. Normal model and reasoning selections affect only the current session. Saving profile defaults requires a separate explicit action. Do not expose inherit and default as competing effort levels. See the terminal controls and web controls.

Profile effort and replay rules #

A provider extension can override catalog facts for its own saved profiles through ProfileModelPlugin. Core asks the installed extension that the profile names, enabled or not:

  • runtime.profile_effort_override uses its efforts in place of the catalog's list. The model resource and session effort validation both read it.
  • session_configure calls its replay with the latest projected history before it queues or applies a model switch.

The Bedrock extension is the only contributor. A saved Converse profile answers its verified effort controls, and Some([]) for an unknown model. A Messages profile keeps the catalog's efforts. Any other or unreadable api value answers Some([]). A Converse profile refuses a switch when history holds native blocks that only their origin model can replay. See the contract.

Model lists #

model_lists exposes ids, refetch, saved, and ready for provider-specific lists. ModelCatalog.list receives the runtime's key environment as its third argument. A remote listing that discovers an environment key passes it on, and other catalogs ignore it. Its cache stores lists separately from the general catalog, in the albedo_model_lists registry table and $ALBEDO_HOME/model-lists, and applies success and failure expiry periods. Consumers must handle a missing or unavailable list. The proxy uses profile and catalog information when it lists models.

The custom anthropic-api provider keeps its own model-list namespace, separate from Claude's catalog and credentials. Model metadata still comes from the Anthropic catalog.

The custom anthropic-api provider lists models from its configured API root's /models route. The list contains every sorted, unique ID the route returns, not model limits or thinking capabilities; the Anthropic catalog supplies those facts for Claude models, prefixed aliases included. The selected ID remains the request's model ID. See custom Anthropic gateways for credentials.

OpenAI-compatible lists share catalog.ids for sorted, unique IDs. Providers retain eligibility, credential precedence, headers, timeouts, and HTTP status policy.

The generic OpenAI-compatible extension also keeps the architecture.input_modalities each listed model reports (read by catalog.input_modalities) in openai-modalities-<hash>.json per endpoint, and its catalog lookup answers with them, completed from models.dev. A model that reports only text input then gets its images projected out instead of sent to a server that would refuse them. A model whose list entry omits the field keeps the old behavior. The extension's picker keeps a model that reports architecture.output_modalities (read by catalog.output_modalities) when it lists text, and hides one that does not; only a listed model without that field is judged by its ID's name. The ordinary HTTP client preserves response headers for conditional catalog requests. Mixed-credential catalog reads do not establish model-session affinity.

The GitHub Copilot catalog keeps the supported_endpoints of each model its /models fetch lists in github-copilot-endpoints-<hash>.json per API endpoint. Each session's connection carries them, and the wire sends a model to Chat Completions, Responses or Messages by what the list names. A model listed on several endpoints keeps the route its family usually takes when that is among them. Before a list has been fetched, or for a model it does not name, the family decides.

Codex reads codex-models.json from the correctly encoded home path. If that file is absent, it checks the legacy path that treated UTF-8 bytes as Unicode codepoints and validates the cache before copying its bytes to the canonical path. An unreadable canonical file does not trigger the fallback. The Codex catalog owns this migration.