fiber

Model routing

How Fiber reaches a model, and how one is chosen. Vocabulary is GLOSSARY.md. The provider seam is docs/architecture.md, and the extension runtime is docs/extensions.md. The reasoning behind the protocol and provider split is ADR 0007. Each protocol's wire facts, read from reference implementations, are in research/provider-harvest.

Protocols and providers

A protocol is a wire format: how a request is shaped, and how a streamed reply is parsed into actions. A provider is an endpoint that speaks one or more protocols: a name, a credential, base URLs and a list of models.

Protocols are native Rust in the provider module. Five speak to vendors:

ProtocolUsed by
anthropic-messagesAnthropic, OpenCode, OpenRouter, Databricks, muse, AWS Bedrock (Claude), Google Vertex (Claude), Azure (Foundry Claude)
openai-completionsOpenCode, OpenRouter, Databricks, muse, Azure
openai-responsesOpenAI, ChatGPT/codex, OpenCode, Databricks, muse, Azure
google-generative-aithe Gemini API, Google Vertex (Gemini)
bedrock-converseAWS Bedrock (models other than Claude)

A sixth, scripted, speaks to no vendor: it reads a script file ("The scripted provider").

AWS event-stream framing is a per-model flag, not a protocol. anthropic-messages reads it for Claude on Bedrock, which Bedrock serves through its Invoke API: a model whose data declares compat.bedrock_invoke ("Bedrock Invoke wire facts"). bedrock-converse always reads it ("Bedrock Converse wire facts").

ChatGPT/codex speaks openai-responses with two compatibility flags its extension declares on each model, store: false and cache_key_header: "session_id", and one provider header, originator: fiber. It sends no OpenAI-Beta header. The account-id header comes from its credential() ("Keys, tokens and OAuth"). Its streamed events, tool calls and reasoning items are parsed as plain Responses. A stream ends with response.completed: all 45 SSE streams sent to gpt-6-luna that returned 200 did, and none contained response.done. Requests with the OpenAI-Beta header omitted, tried with one request body, also returned 200. With gpt-6-luna the endpoint accepted parallel_tool_calls, tool_choice and text.verbosity. It rejected temperature with status 400, and a service_tier of flex or auto.

openai-responses maps a failed reply whose error.code or error.type is usage_limit_reached or usage_not_included to quota_exceeded, on any endpoint and whatever the HTTP status, and never retries it. No other vendor sends these codes, so the match needs no flag. When the body has resets_at (Unix seconds), Fiber uses retry-after first. Only when the reply has no retry-after header at all does it use the milliseconds from the reply's Date header until resets_at as retry_after_ms; a present but unparseable retry-after vetoes that fallback. Without a usable Date, no fallback wait is set. The message names the reset time. rate_limit_exceeded stays rate_limited. No usage-limit reply has been probed: the match rests on the reference implementations (research/codex-responses-probe, "The usage-limit error body").

On OpenAI's own endpoint, with gpt-6-luna, instructions and a system message in input gave the same answer and the same prompt cache for one prompt, and switching between the two kept the cached prefix. For one tool schema with an optional property, a function tool with no strict key was accepted, and the response reported strict: true with the schema rewritten (every property required, additionalProperties: false). The same schema with an explicit strict: true was rejected with a 400. Details: research/openai-responses-probe.

Required nullable integer, string and boolean properties were accepted with strict: true by OpenAI Responses, Chat Completions, Anthropic Messages, OpenCode Go Chat Completions and OpenRouter Messages. Each sampled call sent null for the arguments the prompt asked it to leave unset. The probe records and its limits are in research/strict-nullable-probe.

So Fiber sends strict on every tool, on every protocol that has strict mode, and decides it per tool, except on bedrock-converse, which sends no strict: Nova refuses the field whether it is true or false ("Bedrock Converse wire facts"), and except on a model whose data sets compat.no_strict, which sends no strict key at all: the Databricks gateway rejects strict even as false on claude-opus-4-1 (the Databricks gateway example below). It sends true only when the tool's schema already fits the vendor's strict subset, and false otherwise. Fiber never rewrites a schema to fit, and never moves keywords into the description. Fiber's built-in tools are written to fit the strict subset, except a tool whose section in docs/tools.md says it is sent with strict: false.

An extension cannot add a protocol. A vendor with a new wire format needs a Fiber release.

Every provider is an extension, the first-party ones included, except the built-in scripted provider ("The scripted provider"). Extensions are installed, not built into the binary. Installing Fiber installs every first-party provider, and a person may remove any of them. How extensions arrive and stay current is docs/extensions.md.

A first-party provider is one Fiber can probe and re-record. There are ten, and an eleventh, Azure, is not built yet:

ProviderProtocolsCredential
Anthropicanthropic-messageskey
OpenAIopenai-responseskey
Gemini APIgoogle-generative-aikey
ChatGPT/codexopenai-responses, with its flagssubscription login
OpenRouteropenai-completions, with compat.anthropic for Claudekey
OpenCode: opencode-go and opencode-zenanthropic-messages, openai-completions, openai-responses, google-generative-aikey, one for both
Databricksanthropic-messages, openai-completions, openai-responseskey
muse (the Meta Model API)anthropic-messages, openai-completions, openai-responseskey
AWS Bedrockanthropic-messages for Claude and bedrock-converse for other models, both with AWS framingBedrock API key, or SigV4 through sign()
Google Vertexanthropic-messages for Claude, google-generative-ai for Geminitoken from credential()
Azure (not built yet: see #224)openai-completions, openai-responses; anthropic-messages for Foundry Claudeapi-key header, or token from credential()

The protocols are the ones each provider serves and Fiber speaks for it. A package's shipped models may use only some of them, and a model on another one is added once it is probed. The OpenAI provider sends store: false on every request. Google Vertex's flags and URLs are data, like any provider's. AWS Bedrock ships its Claude models under a geography's inference profile, such as global.anthropic.claude-haiku-4-5-20251001-v1:0, on anthropic-messages. Its other models speak bedrock-converse: each model that answered a probe's ConverseStream request with a tool config, under its on-demand id and every geography's profile models.dev lists for it, such as openai.gpt-oss-20b-1:0 or global.amazon.nova-2-lite-v1:0 ("Bedrock Converse wire facts"). Google Vertex ships its Gemini 3 and later models only, at the global location: no Claude model answered on the project it was probed with ("Google Vertex wire facts"), so its Claude models are added once one is probed.

AWS Bedrock's credential() returns a Bedrock API key, sent as authorization: Bearer, or AWS credentials, with which its sign() signs each request with SigV4 in place of that header. The session's credential label is the AWS profile name. Under any label but default it runs aws configure export-credentials --format process --profile <label>, so a profile, SSO or an assumed role works without an AWS SDK. A person picks the profile as any label is picked ("Which credential a session uses"), such as in the global file:

{ "providers": { "bedrock": { "credential": "my-profile" } } }

and switches it mid-session with /credential <profile>, which gets that profile's own credentials. Under default it takes the first of: a Bedrock API key in AWS_BEARER_TOKEN_BEDROCK; AWS keys in AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, with AWS_SESSION_TOKEN when set; and the AWS CLI's own default chain, which reads AWS_PROFILE. Credentials with an Expiration are refreshed before it, as any token is ("Keys, tokens and OAuth"). Without a declared environment or path source ("Credentials"), startup fails with credential_missing before any callback or session. When a source exists but acquisition fails, the call fails with credential_failed, and the extension's own message, in provider.message (docs/errors.md, "The shape"), says to set AWS_BEARER_TOKEN_BEDROCK or name a profile. fiber login bedrock is not supported: it stores a key, and a provider with credential() reads none ("Which credential a session uses"), so a Bedrock API key comes from the environment only. The AWS region is the package's region setting, the per-account host its base URL names, read from AWS_REGION when unset ("A per-account host"). Its data declares the AWS CLI files that credential() draws secrets from, $AWS_SHARED_CREDENTIALS_FILE else ~/.aws/credentials, ~/.aws/sso/cache/ and ~/.aws/cli/cache/, and the credential deny refuses tool calls that touch them (Credentials). A profile's credential_process in AWS_CONFIG_FILE is not covered.

Google Vertex's credential() returns an OAuth access token from the Google Cloud CLI, sent as authorization: Bearer. The session's credential label names a gcloud configuration. Under any label but default it runs gcloud config config-helper --configuration <label>, which prints that configuration's account's token and its expiry; a person picks the configuration as any label is picked ("Which credential a session uses"), such as in the global file:

{ "providers": { "vertex": { "credential": "work" } } }

and switches it mid-session with /credential <configuration>. Under default it takes the active configuration's token. Only when gcloud has no account selected at all, saying "You do not currently have an active account selected", does it take Application Default Credentials' token instead: gcloud auth application-default print-access-token. Any other failure, such as a login that needs reauthentication or a selected account with no credentials, fails with credential_failed and says to run gcloud auth login, so a session never switches to the account Application Default Credentials hold. Each command's --format prints the token and its expiry and no other field. The token is refreshed before its expiry, as any token is ("Keys, tokens and OAuth"). Without a declared path source ("Credentials"), startup fails with credential_missing before gcloud or a session starts. With a source present but no account selected and no Application Default Credentials, the callback fails with credential_failed, and the extension's own message, in provider.message, says to run gcloud auth login or gcloud auth application-default login, or name a configuration. The failure keeps gcloud's own reason, with an address shown as [account] and any run of 20 or more token-like characters as [redacted]. fiber login vertex is not supported: it stores a key, and a provider with credential() reads none. The Google Cloud project is the package's project setting, which its base URL names, read from GOOGLE_CLOUD_PROJECT when unset ("A per-account host"). Its data declares the gcloud credential files that credential() draws secrets from: credentials.db, access_tokens.db, legacy_credentials/ and application_default_credentials.json in the gcloud configuration directory, $CLOUDSDK_CONFIG else ~/.config/gcloud; the credential deny refuses tool calls that touch them (Credentials).

A provider Fiber cannot probe is left to the community: a vendor whose subscription Fiber does not hold, or a key vendor such as Groq, Mistral, Moonshot or DeepSeek. The first-party extensions and docs/extensions.md ("What writing a provider looks like") are the examples to start from.

Anthropic messages wire facts

Measured on claude-sonnet-5-5 against api.anthropic.com (research/anthropic-messages-probe).

Google Generative AI wire facts

Measured against gemini-3.1-flash-lite on the Gemini API:

Gemini accepted required nullable integer, string and boolean properties in both AUTO and VALIDATED mode, returning nulls in both samples (nullable probe).

Fiber sends mode VALIDATED only when every tool in the request fits the strict subset. VALIDATED on gemini-3-flash-preview does not enforce maxLength, so Gemini requests keep AUTO, because ask_user and the session naming tool both declare it (research/gemini-validated-probe/README.md). Fiber's own argument check still validates every call (docs/tools.md, "Before a call runs").

A functionCall that arrives without an id is logged with no provider_id (docs/events.md, tool_call_requested). Fiber pairs the call with its result by its action id, which stays local. Only an id the model emitted is sent back.

A reply's text fragments, thought parts and functionCall parts each carry their own thoughtSignature when the model gave one. Unsigned text fragments join into one part. A signed fragment is its own part. An empty signed fragment's signature rides on the text before it. Fiber logs each part as its own item, in the order the model sent it, and each part replays in that order with its own signature (docs/loop.md, "What the model is sent"). A reply that repeats the same text in two parts is replayed as two parts, each with its own signature.

Because a replayed functionCall needs the signature its own model gave it, a tool call and its result that another model reference made are sent to Gemini as plain text, not as functionCall and functionResponse parts (docs/loop.md, "What the model is sent").

The Gemini API answers HTTP 404 "no longer available to new users" for gemini-2.5-flash-lite, gemini-2.5-flash and gemini-2.5-pro on a key created in September 2026.

Fiber targets Gemini 3 and later on google-generative-ai. Google Vertex serves gemini-2.5-flash-lite, and there it emitted no id on a call, took a made-up id on replay, and did not read an image in functionResponse.parts. It also refuses the includeThoughts Fiber sends on every request while no thinking level is set ("Google Vertex wire facts").

Google Vertex wire facts

Measured on October 20, 2026 against aiplatform.googleapis.com, mostly with gemini-3.1-flash-lite, and one tool call to each Gemini 3 and later model (research/vertex-probe).

OpenCode wire facts

Measured on October 1, 2026 with one OpenCode key (research/opencode-probe).

Which thinking level each Go and Zen model takes is probed in research/opencode-thinking.

Bedrock Invoke wire facts

Measured on October 20, 2026 against bedrock-runtime.ap-south-1.amazonaws.com with global.anthropic.claude-haiku-4-5-20251001-v1:0, and one request to global.anthropic.claude-haiku-5-5 (research/bedrock-invoke-probe).

Bedrock Converse wire facts

Measured on October 20, 2026 against bedrock-runtime.ap-south-1.amazonaws.com with gpt-oss 20B and 120B, Ministral 3 8B, Qwen3 32B and VL, DeepSeek V3.2, Nova Micro, Lite, Pro and 2 Lite and Grok 4.7, and with Claude Haiku 4.5 for a signed reasoning block (research/bedrock-converse-probe).

The scripted provider

scripted is the one provider built into the binary, and the only one that reaches no network. Its protocol of the same name reads a script file instead of a socket. A script is a list of steps, each one model reply: text, a tool call with its arguments, a given error such as a rate limit, or a reply streamed slowly. Each request takes the next step, in order. A request is never matched against a step, so a prompt that changes does not change the reply. A request after the last step fails the turn. It takes the session's tools in name order, each as Fiber's own definition serialised to a JSON object, with no vendor wrapping and no strict flag.

A script is a JSON file, {"steps": [...]}, read whole each time a model on it is connected: when a session starts or resumes on it, switches back to it, resolves its reviewer to it, or resolves a delegate to it through a configured roles.* reference (a string or an object's model). Each step is an object, a reply or an error:

{"steps": [
  {"text": ["Reading ", "the file."], "tool_calls": [{"name": "read", "arguments": {"path": "notes.md"}}]},
  {"error": {"code": "rate_limited", "message": "Slow down.", "retry_after_ms": 2000}},
  {"text": "Done.", "every_ms": 200, "usage": {"input": 120, "output": 4}}
]}

Each request takes one step, a retried request included, so a rate_limited step followed by a text step is a retry that succeeds. A request after the last step fails invalid_request, which is never retried, naming the script and the request. Each connection starts at step 1, and a reviewer or delegate on a script has its own steps. A script that cannot be read fails with io_failed, and a malformed one with config_invalid naming the file and the step: at startup before any line is written, on a switch as its rejection, and for a reviewer as a reviewer failure.

A session selects it with an ordinary model reference, scripted/<path>, where the model id is the script's path, resolved against the session's workspace. It needs no credential and has no quota, cost or prompt cache. The model picker does not offer it, and it is never chosen unless named. A session switches only to a scripted model it started with: /model naming another scripted/<path> is rejected with invalid_arguments.

It exists for testing extensions, reproducing a bug from a script anyone can replay, and running a pipeline end to end without a model. It bypasses the vendor decoders, so it proves nothing about a vendor's wire format; recorded and scripted streams on the fake server prove that (docs/testing.md, "Model calls").

What a provider extension declares

Most of a provider is data. For the provider:

For each model:

The databricks provider's headers carry Databricks-Ai-Gateway-Request-Tags, a JSON object of request tags whose source is always fiber. The configuration key providers.databricks.request_tags merges more tags into that header for the session's model calls only, and only for the provider named databricks; the discovery requests keep the source-only header. The header is built when the session connects from the configuration read at startup, so a reload never changes it (docs/configuration.md, "When Fiber reads configuration"). The key, its layers and its handling of an invalid value are in docs/configuration.md, "A provider's data".

A first-party package's models list is generated, except openrouter's and databricks's, which their models() functions read from their vendors ("Model discovery"): openrouter's takes each model's name from OpenRouter's list, and databricks's matches the workspace's model services to its catalog rows. cargo xtask models-dev reads models.dev (https://models.dev/api.json) and keeps each source's models that call tools and output text, leaving out Gemini models before Gemini 3 ("Google Generative AI wire facts") and any model with no context window. It derives each model's name, protocol, context window, output token limit, input kinds and cost from models.dev, and takes every other field, such as base_url, compat, web_search, thinking_levels and the provider's credential and reviewer_model, from a table it keeps per package. A gateway package's model (opencode-go, opencode-zen) whose id a vendor package also lists takes that vendor's thinking row unless its own table names one; every other gateway model names its own thinking row, with levels and a default, or an explicit empty row for a model that takes none. A databricks model found by discovery takes the thinking row of the vendor model its bare service name matches, looked up by the same match key discovery routes it with, overlaid by providers/databricks/thinking-overlay.json, which wins on a shared key over the four thinking-vendor packages' rows; an overlay row may be explicitly empty, and an empty row still wins over a vendor row; a service neither names a row for keeps no levels. The table also lists the ids a package keeps when its models are a subset of the source's (codex keeps five of models.dev's openai models; bedrock keeps its Claude models' inference profiles and the other models that answered a probe through ConverseStream, "Protocols and providers"), names a model's protocol where models.dev cannot (bedrock's Claude models speak anthropic-messages, its others bedrock-converse), and pins a derived field the vendor's endpoint differs on (codex's context_window is the ChatGPT backend's 272000, where models.dev lists the API's 1050000). It leaves out every model models.dev marks status = "deprecated", in every package. A table entry for a model it leaves out as deprecated is skipped with a note, and an entry for an id models.dev does not list fails the run. It applies providers/models-corrections.toml last: each entry names a package, a model and the fields it overrides, with the vendor page that says so and the models.dev pull request that fixes the same data upstream. An entry exists only while models.dev is wrong, and the run that finds models.dev agreeing with it deletes it. A rerun on an unchanged models.dev changes nothing. A scheduled workflow runs it every night and opens a pull request when a committed file changes (docs/ci.md); no other CI job fetches model lists. A test regenerates the lists from a checked-in copy of models.dev and fails when a committed file differs.

This generated list is each package's fallback. A package whose vendor has a listing endpoint also lists its models live ("Model discovery").

Fiber never guesses a flag from a URL or a provider name. A flag the vendor needs is declared, or it is not set.

Extra request body fields

A model's extra_body adds fields to every request sent to it, after Fiber has built the request. It may add a field or replace one such as max_tokens or a thinking setting. It may not name a field that carries what Fiber records, or that Fiber relies on to read the reply:

ProtocolFields extra_body may not name
anthropic-messagesmodel, system, messages, tools, tool_choice, stream, cache_control
openai-completionsmodel, messages, tools, tool_choice, stream
openai-responsesmodel, instructions, input, tools, tool_choice, stream
google-generative-aisystemInstruction, contents, tools, toolConfig
bedrock-conversesystem, messages, toolConfig

google-generative-ai and bedrock-converse carry the model and streaming in the URL, not the body. On bedrock-converse, extra_body's inferenceConfig and additionalModelRequestFields are laid over Fiber's own key by key, so a model can add a field beside the output limit and the thinking level; the output limit still caps a maxTokens it names. cache_control is reserved because cache markers are Fiber's alone (docs/prompt-cache.md, "Cache markers and keys").

A model whose extra_body names one of these is left out of the model list, with the notice model_invalid naming the model and the field. The same applies to a model a provider's models() function returns. So the tools and system prompt in the session log are always the ones sent, and the tool set is fixed for a given Fiber build.

A model's web_search names the vendor's hosted-search tool type as the vendor spells it. Each protocol accepts only the types its code reads back (docs/tools.md, "Hosted by the provider"): openai-completions reads openrouter:web_search. A model whose web_search names any other type is left out of the model list, with the notice model_invalid naming the model and the type, as for a forbidden extra_body field.

A per-account host

Some providers serve each account from its own host, such as a Databricks workspace or an Azure resource, or from its own path, such as a Google Cloud project on Vertex. A model's base_url names that part with a placeholder, {name}:

"base_url": "https://{workspace}/ai-gateway/anthropic/v1"

A placeholder in the path is filled and checked the same way, so its value must have a host's shape, as a Google Cloud project id does.

The extension's manifest lists the same pattern under providers (docs/extensions.md, "What a package holds"), so an install or an offer shows where the host comes from. The value is one of the extension's own settings, which only the person sets (docs/configuration.md, "Extension settings"), globally or per project, with fiber config set or in config/<extension>.json. The package may name an environment variable to read when the setting is unset, such as DATABRICKS_HOST. A placeholder's setting is never a repo_settings key, so a repository never sets it, as it never changes a base URL ("Choosing the model").

Before a value fills its placeholder, Fiber strips one leading https:// and one trailing /, so DATABRICKS_HOST can carry https://adb-123.azuredatabricks.net/. What remains must be a host: ASCII letters, digits, . and -, with an optional : and a port from 0 to 65535. A setting that is not a host is not replaced by the environment variable.

A model whose placeholder has no value, or a value that is not a host, is left out of the model list. A value that is not a host raises the notice model_unconfigured. For a placeholder with no value, fiber models prints one grouped notice, not one per model: it names the providers and settings and counts the models it leaves out, then lists the models that are configured, possibly none. fiber doctor groups missing-host models by provider and setting, naming both and counting the models left out. A search filters the count as it filters the list: the count holds the left-out models whose provider/model contains the text, and no notice prints when none does. In the model picker the count instead holds the left-out models whose provider, id or display name matches each space-separated query word in order, and shows no row when none does (docs/tui.md, "Swapped views"). The terminal's model picker raises no notice for a placeholder with no value, and counts the left-out models under their provider instead (docs/tui.md, "The model picker"). Doctor filters out providers without credential presence before filling placeholders: for a credentialed provider, a value that is not a host remains a per-model notice; an uncredentialed provider produces neither kind of notice. Sessions and fiber config set model keep their per-model notice behavior. The model can still be named ("Naming a model"): a session that chooses it exits with model_unconfigured, and fiber config set model accepts it with that notice (docs/configuration.md, "When Fiber writes"). The notice names three fixes, login first: run fiber login <provider>, which asks for the host; set the named setting in config/<extension>.json in Fiber home, for every project at once; or, when it names an environment variable, export that variable in the shell profile and run fiber hub refresh, since the hub reads its environment when it starts. For a provider whose data declares credential_label it names only the last two: its fiber login would store a key the provider never reads ("What a provider extension declares").

fiber login <provider> asks for each missing value after the credential is stored and before the reviewer, saving each answer globally. When a project-layer empty hides a saved answer, the login names that file: the answer holds for every other project and session.

What the login asks

One question per missing value, in declaration order: the setting, with its declared environment variable in parentheses when one exists. An answer that is not a host is refused and asked again; an empty line is refused the same way. End of input ends the questions with nothing saved for the remaining values. Without a terminal the login prints one line per missing value instead, naming the setting with the config file that fills it, and the declared variable when one exists.

openai-completions facts

Every protocol reports input without cache reads and writes, as docs/events.md (tokens) defines it. Where a vendor's input figure includes them, the protocol's module subtracts them. OpenRouter's prompt_tokens includes cached_tokens, for example 15 with 14 cached (research/openai-completions-probe).

Each protocol reads cache reads and writes from these usage fields:

Protocolcache_readcache_write
anthropic-messagescache_read_input_tokenscache_creation.ephemeral_5m_input_tokens under "5m", cache_creation.ephemeral_1h_input_tokens under "1h"
openai-completionsprompt_tokens_details.cached_tokensprompt_tokens_details.cache_write_tokens, always under "5m"
openai-responsesinput_tokens_details.cached_tokensinput_tokens_details.cache_write_tokens, always under "5m"
bedrock-conversecacheReadInputTokenscacheWriteInputTokens, under "5m"

OpenAI keeps one 30-minute lifetime and Responses sends no lifetime, so a Responses write lands under "5m". OpenAI's input_tokens includes both counts: a cache-warming request reported 2,347 input with 2,344 written, and the next reported 2,347 with 2,344 cached (research/openai-responses-probe).

Here is the Databricks gateway as an example. It serves about 53 models. Claude models work only through its Anthropic route, because its default route rejects reasoning_effort. So the extension declares each Claude model with anthropic-messages, the /ai-gateway/anthropic/v1 base URL and compat.bearer. Models that support the Responses API get openai-responses, and the rest get openai-completions. It also sends one custom header on every request. A gemini- service, or one whose catalog row names GEMINI_ENTERPRISE, carries compat.gemini on the protocol already chosen. A service whose catalog row's provider_type is neither OPENAI nor GEMINI_ENTERPRISE carries compat.max_tokens, so its output limit goes in max_tokens. Two Claude rows differ per model, as probed through the gateway: the claude-sonnet-4-5 rows carry no deferred_tools, because the gateway rejects their deferred load; and claude-opus-4-1 carries compat.no_strict, because the gateway rejects the strict key on it, even as false, so its tools are sent with no strict key at all. The returned list holds one entry per service, sorted by id. All of that is data.

Model discovery

A provider may also declare a Lua models() function that returns its model list. Fiber stores the result on disk in Fiber home's cache, and every surface that shows a model list draws from that copy at once: the terminal's model picker, fiber models, and anything an agent reads. A refresh runs in the background and never holds a list back. The generator leaves out ids a package's table skips because the vendor rejects them, and a gateway model no probe reaches is skipped.

Displayed lists filter out providers without credential presence on every read, including cached reads, before grouping missing host settings. Logging out hides their models without deleting cache files. No refresh starts for a provider that is off. Installed provider identity remains available for session resolution and credential diagnostics. Displayed lists, catalogues and role marking use Providers::switched_on to count only switched-on providers.

The age of a list is the age of its cache file, so sessions that start together refresh a provider once. A provider already refreshing is not started again. A models() that fails, or returns something other than a model list, leaves the cached list in place, with an extension_failed notice naming the extension. Nothing refreshes on a timer, so an idle Fiber does no work. A refresh never changes the tool definitions a session has sent: an agent sees a new list only through a tool result (docs/prompt-cache.md).

The function can ask the vendor's own listing endpoint, read a file, or look up metadata anywhere, models.dev included. A service the vendor lists but backs with no serving endpoint is deliberately left out of discovery: its entry keeps its place in the returned list and carries omit_reason with the provider's reason, and Fiber drains each marked entry into one model_omitted notice naming the model and the reason, the way model_invalid names a defective declaration. Each omission is also named once in the diagnostic log. The mark applies to static provider data too: a static entry carrying omit_reason drains the same way.

The load reports each model_invalid once per reason and each model_omitted once per marked entry; a later admission on the same registry reports only what the registry has not already reported.

Which models exist, and what Fiber knows about them

The vendor's own list decides which models a provider offers. Every first-party package whose vendor has a listing endpoint declares a models() that calls it with the person's credential, except OpenRouter, whose models endpoint needs no key: anthropic, openai, gemini, codex, muse and databricks use the person's credential; openrouter sends none, avoiding needless credential exposure. It keeps the models that output text and call tools, judged by the vendor's fields where it has them and by models.dev otherwise. A package whose vendor has no listing endpoint, and every package before its first refresh or without a credential, shows its generated list (cargo xtask models-dev above).

Fiber also fetches models.dev's catalog (https://models.dev/api.json), one GET with no key, under the same rule as a provider's list: at start or when the picker opens, only when the cached copy is older than model_lists.refresh_after, and on the picker's refresh. Setting model_lists.models_dev = false stops the fetch, and the generated values stand in for it. A failed fetch keeps the cached copy.

Each field of a listed model takes the first of these that names it:

  1. The package's table pins and providers/models-corrections.toml.
  2. The fetched models.dev catalog.
  3. The generated list.

Fields only Fiber keeps, such as thinking_levels, compat, base_url and web_search, come from the package's table alone.

A model the vendor lists that none of the three knows is shown and usable, marked new (docs/tui.md, "The model picker"). It takes cautious values: text input only, no thinking levels, a context window of 128000 tokens and an output limit of 8192, and no price, so its cost reads as unknown. The mark and the cautious values go once any of the three names the model.

A model models.dev marks status = "deprecated" is left out of every list. A session or setting that names it by id still runs it, and Fiber shows a model_deprecated notice naming it once per session.

A provider runs Lua in five functions at most: models(), quota(), credential(), sign() and cost(). Only sign() runs on the request path, credential() only when the cached token has already expired ("Keys, tokens and OAuth"), and cost() only after a call has ended ("Cost").

Signing a request

A provider may declare a Lua sign() function for a scheme that signs each request, such as AWS SigV4. It receives the method, the URL, the headers, the SHA-256 of the body and the time, in whole Unix seconds from the extension's clock, since SigV4 signs over the time and Lua has no clock of its own. It returns headers to add. It cannot change the body. If sign() fails or returns headers Fiber cannot use, the call fails with credential_failed, and is not retried. SigV4's chain of HMACs uses the host.hmac_sha256 host call (docs/extensions.md, "Host calls"). It declares a timeout like every callback (docs/extensions.md, "How an extension runs"), and a retry signs again.

Nothing changes a request's body on its way to a provider. A transform such as redacting secrets runs where the text enters the session, in the before_message and after_tool hooks (docs/extensions.md, "Hooks"), so the secret never reaches the log or any request.

Quota

A provider may declare a Lua quota() function that returns how much quota it has left: windows, each with percent used and a reset time where the vendor reports one, or credit remaining with its limit. It asks the vendor's usage endpoint through host.http. Each vendor reports quota differently, and overage past a cap is invisible in every response Fiber has seen (fiber-zig#96), so the shape stays in the provider's package rather than in the protocol. When it runs, and what the model and the person see, is docs/tools.md, "Provider quota".

Cost

A call's cost in usage_recorded is the vendor's own figure where the response or a generation lookup reports one, as OpenRouter's does (docs/events.md, "Usage and notices"). Otherwise it is the model's declared cost prices applied to the call's tokens, each kind at its own price; a cache_write entry keyed "1h" prices at twice the selected input price. A model with neither has cost null, and the person sees its tokens only. A call whose generation the provider never named has cost null, whatever the model declares.

A provider whose vendor offers a generation lookup declares a Lua cost() function. It receives a table { generation_id, base_url, key }: the generation's id, the base URL the call went to, and the key the session used for the call (absent when the provider's token comes from credential()). It returns the generation's cost in US dollars, or nothing when the vendor does not have it. It asks the vendor through host.http, so the lookup's URL and the shape of its answer stay in the provider's package, as quota()'s do. The loop calls it once, 30 seconds after a call that ended without the vendor's own figure, on the session's injected clock: a stream closed early, cancelled or failed. It never calls it for an id Fiber minted, because the vendor never named that generation (docs/events.md, usage_recorded). A returned cost is written as a second usage_recorded with the same generation_id. Nothing returned, an error or a timeout leaves the first record as it is, and the loop does not ask again. A session that ends before the 30 seconds pass writes nothing more. OpenRouter's lookup answers "not found" until the cost is ready, which took up to 30 seconds when probed (research/openrouter-cost).

A model priced by request size declares tiers (docs/configuration.md, "A provider's data"). The tier with the highest input_tokens_above that the call's whole input exceeds gives every price for the whole call; below every threshold, the base prices apply. A "1h" write costs twice that tier's input price. The whole input is input plus cache_read plus cache_write from the call's tokens, because a vendor that prices by request size counts the whole prompt, cached or not.

A model that a subscription login serves declares "subscription": true beside its prices, which are the vendor's API prices. Its calls are logged with subscription, so the person sees what the work would cost on an API key, kept apart from money billed per token, and budget.usd never counts them (docs/loop.md, "Spending budget"). ChatGPT/codex declares every model this way.

Image limits

Every image is processed once, when it enters the session: an image from read, in an MCP tool result, or pasted in a prompt or steer command. web_fetch saves an image as downloaded and gives its path, so the image enters through read. The processed file is what is written to the session's artifacts/, what the log's image part names (path, mime_type, width and height of the stored file), and what every request sends. A resume sends the same bytes. The provider module does not resize.

The image child does the work (docs/invocation.md, "Processes"). It reads the header. An image over 50 megapixels (width × height > 50,000,000) is refused without decoding. A GIF always becomes PNG (first frame). A PNG, JPEG or WebP within the cap is stored byte for byte, not decoded. Otherwise it is fitted.

One cap for every protocol: longest side 2000 px, and at most 1 MB (1,048,576 bytes) as base64. Every image in context is resent as base64 on every request (Fiber keeps no vendor-side state), so one 4.5 MB image would outweigh a 600k-token text context in bytes. 2000 px fits Anthropic's 2000 px per-image rule for requests with more than 20 images, Bedrock/Vertex's 5 MB, and OpenAI's 30,000-patch limit (2000×2000 is 3,969 patches). Measured: a 2000 px screenshot is 162,676 bytes of base64 as PNG at Default compression, and six photographs fitted inside 2000 px are 232,204 to 672,632 bytes of base64 as JPEG at quality 80 (research/image-limits/README.md).

Fitting keeps the aspect ratio, never enlarges, and uses Lanczos3. A JPEG input is re-encoded as JPEG at quality 80; any other input as PNG at image's Default compression level. If the result is still over 1 MB of base64, JPEG at quality 80 is tried and kept if it fits; if neither fits, the longest side is cut to three quarters and both are tried again, until one fits.

There is no limit on the total image bytes in one request. A request over a vendor's request limit (Gemini documents 20 MB inline, Anthropic 32 MB) fails as the vendor returns it.

The table is what each vendor documents. The sources are platform.claude.com/docs/en/build-with-claude/vision, developers.openai.com/api/docs/guides/images-vision and ai.google.dev/gemini-api/docs/image-understanding.

ProtocolLargest dimensionLargest encoded imageImages per requestResizing the vendor documents
anthropic-messages8000 px; 2000 px per image once a request holds more than 2010 MB as base64 (5 MB on Bedrock and Google Cloud); 32 MB per request600, or 100 for a model with a 200k-token contextto 2576 px and 4784 tokens on Claude 4.7 and later, 1568 px and 1568 tokens on other models; a computer-use or browser-use tool_result image over the limit is rejected
openai-responses, openai-completionsnone; 30,000 patches of 32 px per image (the gpt-5.6 family: high detail fits 2048 px and 2,500 patches)512 MB per request1,500at detail: high; original keeps the size and rejects over 30,000 patches
google-generative-ainone stated20 MB per request, inline3,600none stated; the page describes 768 px tiles for counting tokens

Requests to check the table, on September 29, 2026, one image each:

The measurements are in research/image-limits/README.md.

Naming a model

A session's stored model reference is always provider/model, for example databricks/databricks-claude-opus-5.

When a person types a model:

  1. Fiber tries the exact string as provider/model.

  2. If nothing matches and the string ends in : and a thinking level (off, minimal, low, medium, high, xhigh or max), Fiber strips the suffix, matches the rest and applies that thinking level.

  3. Through the session's bare-id resolution, a bare model id counts only switched-on providers: it works if exactly one switched-on provider has it. Two or more switched-on matches are the error model_ambiguous, which lists only the switched-on matches. Prefix the provider, as provider/model. A provider that is installed but lacks the named model is no_model. A bare id that no installed provider has is no_model too, and its message says to run fiber models. When no switched-on provider has the id but a logged-out installed one does, the error is credential_missing: it names the provider as not logged in, with the login command, except a logged-out credential() holder's sentence carries no such command (docs/errors.md, "The shape"). Only a provider/model whose provider is not installed is extension_missing. These rules match a model left out with model_unconfigured too, so naming one is model_unconfigured, not no_model, and a bare id it shares with another provider's model is model_ambiguous only with at least two switched-on holders, configured or not.

    A session's resolver inventory is installed-wide: it names every installed provider. Only bare-id candidate selection and displayed lists filter on credential presence ("Credentials"). A switch reads the pinned startup configuration, but presence is live: storing or removing a credential flips the next bare-id resolution with no configuration change.

The exact match comes first because OpenRouter model ids contain colons.

A delegate's model is named with its harness first: harness:provider/model:level, such as fiber:openai/gpt-5.6:xhigh, claude:opus:high or cursor-agent:composer-2.5. The rules for it are docs/delegates.md ("Choosing a model").

Thinking

A session has one reasoning setting, its thinking level: off, minimal, low, medium, high, xhigh or max. Fiber has no separate effort setting. Each protocol module maps the level to whatever its vendor takes, whether a token budget, an effort parameter or both. A model declares the levels it supports, and the model picker offers only those.

The level comes from, in order: a :level suffix typed with the model, which applies to that session only; the session's own choice, from the picker or /thinking; models."provider/model".thinking; the top-level thinking key; and otherwise the model's own default (docs/configuration.md).

A level the model does not declare is checked by where it came from. One asked for now, by a :level suffix, the session's choice or a driver, fails with invalid_arguments. A configured one, from models."provider/model".thinking or the top-level thinking, is ignored: the session uses the model's own default and logs the notice config_key_ignored, naming the key, the level and the model. A model that declares no levels, such as a local Ollama model, runs with none.

On anthropic-messages a model takes adaptive thinking unless its data declares compat.thinking_budget. Adaptive thinking sends the level as thinking: {type: "adaptive"} with output_config: {effort}. A budget-tier model sends the level as thinking: {type: "enabled", budget_tokens} with no output_config: minimal sends 1024, low 2048, medium 8192, and high, xhigh and max 16384. The budget is measured against the sent max_tokens: with none, the level's budget is sent; at or below 1024, no thinking key is sent; otherwise the budget is capped so at least 1024 tokens stay for the reply, and is never below 1024.

On bedrock-converse a model takes a level only through the field its data names in compat.reasoning_field, sent in additionalModelRequestFields: reasoning_effort sends {reasoning_effort: <level>}, as gpt-oss takes it, and reasoningConfig sends {reasoningConfig: {type: "enabled", maxReasoningEffort: <level>}}, as Nova 2 Lite takes it. At high the second sends no maxTokens, because Nova 2 Lite refuses it beside that level. off sends neither field. A model without the flag is sent no level, so the bedrock package declares none for it ("Bedrock Converse wire facts").

Choosing the model

Fiber picks the model for a session in this order:

  1. --model given on a resume that starts the process, which both doors accept: fiber ask, and the terminal, which passes it to each session it starts. -c model= on the same run joins this layer.
  2. The model a resumed session was using.
  3. The default in config.

If none of these gives a model, the terminal opens a model picker, and saving the choice writes the config default. A headless run fails with the error code no_model. Fiber never picks a model that nobody chose.

A one-shot review run gets a different model by passing --model. A role is a configured name for a delegate's model reference (docs/delegates.md). Roles name only the models delegates use; the session's own model is chosen in the order above. Roles are configured at roles."<name>" (docs/configuration.md).

A repository's configuration may choose the default model from providers already installed. It cannot declare a provider or change a provider's base URL. If it could, a cloned repository could point openrouter at its own server, and Fiber would send it your OpenRouter key. A repository that needs a provider ships an extension, whose manifest names the provider and its base URLs. The extension loads only after a person approves it, and the offer shows each base URL (docs/extensions.md, "Code a repository ships").

Credentials

A provider may hold several credentials, such as two subscriptions or a work and a personal key. Each has a credential label, such as work or alice@example.com. A stored credential is a file only the owner can read (mode 0600) in Fiber home at credentials/<name>/<label>. <name> is the provider's own name, unless its provider data names a shared credential.

A key can come from:

A key that is not stored takes its label from the configuration that points at it. A person sets these at providers."<name>".credentials."<label>" (docs/configuration.md, "Secrets"), never from a repository. The source a provider's data declares has the label default.

A stored credential owns its label. If it fails, Fiber reports the failure. It does not fall back to an environment variable or a command under the same label.

A provider is switched on exactly when it has credential presence, independently of installation and the label a session selects. Provider data and discovery ignore extensions."<name>".enabled; non-provider init, commands and hooks in the same package still obey it.

For a key or OAuth provider, any label counts: a validated stored regular file, a nonempty environment value, an existing regular-file source, or a configured command. Empty regular files count; presence checks neither read key bytes nor run commands or callbacks. Stored-path validation, including symlink refusal, stays unchanged. Presence is not proof that acquisition will succeed.

A provider whose credential comes from a function and declares credential_label instead uses only its declared credential_env and credential_paths. Stored labels and configured key origins, including commands, do not count. Any declared environment variable set to a nonempty value counts, including whitespace. Bedrock declares AWS_BEARER_TOKEN_BEDROCK and AWS_ACCESS_KEY_ID; either alone proves presence, not validity. Vertex declares none.

Declared paths use the environment replacement and appended join described in docs/configuration.md, "A provider's data". A regular file counts even when empty. A directory needs one entry: Fiber performs one directory read, checks at most its first result, and never opens or inspects the entry. Symlinks to declared files and directories are followed; missing targets and failed checks do not prove presence. These rules do not change stored-path validation. No AWS or gcloud command runs to decide presence.

Logging in

fiber login <provider> --as <label> stores a credential under that label. Without --as, the label is the account's email when the login reveals one, as credential()'s email does, and default otherwise. A login whose label is already stored is refused, and the message names --as. The first label a provider stores is written to providers."<name>".credential in the global file, unless that key is already set. A provider that logs in by browser also takes --device, which logs in with a device code instead.

At a terminal the login asks, once the credential is stored, which model reviews that provider's calls: the provider's models with the saved providers."<name>".reviewer_model preselected, else the package default, and nothing preselected when neither exists. The pick is saved to that global key, one per provider; reviewer.model stays the override that applies to every provider. Without a terminal the credential is stored and nothing is asked.

Removing the last stored label switches a provider off unless another source, such as its environment key or a configured command, still supplies presence. Removing one label while another remains does not switch it off. Logout removes stored credentials, not external sources or model-list caches.

Which credential a session uses

Provider presence considers any eligible label, not the selected label. A missing selected label still fails at startup even if another keeps the provider on; Fiber never substitutes that other label.

A session picks its credential label when it starts. Fiber picks it in this order:

  1. --credential <label> on a resume, which both doors accept.
  2. The label a resumed session was using.
  3. For a delegate started with a role, the role's credential (docs/delegates.md, "Choosing a model").
  4. providers."<name>".credential, from any layer except a repository's.
  5. Otherwise default, the source the provider's data declares.

The order applies to a provider that takes a credential: a scripted session has no label ("The scripted provider"), so any label asked for one fails with credential_missing.

A label that names no credential fails with credential_missing, naming the labels the provider has.

The label is part of the request settings, so preamble_built records it (docs/events.md, "Preamble"). A resume with --credential that changes it records model_changed, as a switch does.

A person switches credential with /credential <label>, and a driver with the credential command (docs/invocation.md). A credential switch accepted while a model switch is queued applies to the queued model's provider. The credentials query lists that provider's labels and the label it uses now. With no label, /credential opens the credential picker (docs/tui.md, "Swapped views"): Enter chooses a label and saves it; Ctrl+S chooses it for this session only and saves nothing. The switch applies at the next turn boundary and rebuilds the prompt cache, because a vendor holds the cache per account or workspace (docs/prompt-cache.md, "Switching model"). The terminal saves the label to the global providers."<name>".credential, unless the person chooses it with Ctrl+S in the credential picker. A per-project file can pin a label for one project. Saving the label never changes another session that is already running.

Fiber never changes a session's credential by itself. It does not rotate credentials, and it does not move to another label when one runs out of quota or is rejected. The failure is reported as any other.

When a credential is missing or fails

Fiber looks for the session's credential at startup, before the session starts. A provider with no presence fails before its credential callback runs; the built-in local scripted provider needs no credential. A run with none fails there with credential_missing (docs/errors.md, "Before a session exists"). A credential that is stored but cannot be used, or a credential() call that errors, fails with credential_failed, except a failed OAuth refresh ("Keys, tokens and OAuth"). Neither is retried.

A model or credential switch reads the credential it switches to when the switch is prepared, if this process has not read it yet. A failure rejects the switch with the same codes and keeps nothing, so the next switch reads it again.

Keys, tokens and OAuth

Most first-party providers use a key. The table in Protocols and providers says which use something else.

A provider whose credential is a token that expires declares a Lua credential() function. It returns { token = <string>, expires_at = <Unix seconds>, headers = { [name] = <string> }, email = <string> }: the token, the time it expires, and two optional fields. It receives { label = <string>, credential = <string> }: the session's credential label, and the stored credential's name, which is the shared credential name when the provider's data names one and the provider's own name otherwise. During fiber login, label is the --as value, and is absent when the label comes from the returned email.

Fiber caches the token per credential name and label, so a /credential switch gets that label's token, never the previous one. It calls the function again, off the request path, when a request finds the token within 5 minutes of expiry. A request that finds the token already expired, because the session sat idle past it or the earlier refresh failed, waits for one call: an idle Fiber does no work, so nothing refreshes on a timer, and failing the request would only make the person send it again. A cloud's own sign-in, such as Google Vertex's, is this function, written in the extension, not in Fiber.

An OAuth login is extension code too. The extension's credential() builds its vendor's flow from native host calls: opening the browser, a one-shot localhost callback, PKCE, device-code polling and the locked credential file (docs/extensions.md, "Host calls"). It adds its vendor's own steps. codex reads the account id from the access token's https://api.openai.com/auth claim chatgpt_account_id, and the email from the id_token's email claim.

ChatGPT/codex is the only subscription login Fiber ships. A subscription login ships when its vendor permits use from other harnesses and Fiber can probe it. The Claude subscription is reachable only by running Claude Code, as a harness extension (docs/delegates.md).

The refresh lock is native. A refresh takes a lock on the credential file, re-reads it, and refreshes once, so two sessions never refresh the same token twice. If the refresh fails, the stored credential stays in place, and the call fails with authentication_failed, or connection_failed when the token endpoint could not be reached. Logging in again is the fix for a rejected refresh.

A headless run whose credential has expired and cannot be refreshed fails with authentication_failed. It never prompts, because nobody is there to answer. Mid-session, with a full client attached, credential() may run the provider's login instead, and the client receives its URL (docs/extensions.md, "Host calls"). At startup nobody is attached yet.

When a model call fails

A failed model call is recorded as docs/events.md describes: an assistant message that completed with a failed outcome and an error. A retry is a new action. Which failure gets which code, and which codes are retried, is docs/errors.md, "A failed model call".

Fiber retries these failures:

A model call gives each address its host resolves to 15 seconds to connect, and fails when it waits 300 seconds for any byte to arrive or be sent, from the request through the end of the stream, the wait for the response's headers included. Reasoning models can stay silent for minutes, so the idle limit is long. Either failure is connection_failed and is retried like a dropped connection. Neither is a configuration key.

A response header x-should-retry overrides the status: true retries the failure, false does not. Fiber never retries quota or billing errors, an unknown_stop_reason or a paused_too_long, whatever the header says. An extension's host.model call applies this policy within the callback's timeout (docs/extensions.md, "Host calls").

Among the responses probed, only Anthropic sent x-should-retry: false on its 400 and 404 responses, true on a 429. Anthropic's 429 also carried retry-after in seconds. muse sent retry-after: 60 on a 429 for an oversized max_tokens; three sends of it returned the same 429, so a client that honours the header retries it in a loop. Among the responses OpenAI, Gemini, ChatGPT/codex and OpenRouter returned to cheap failing requests, none carried x-should-retry, retry-after-ms or retry-after, and none of those vendors reached a 429 (research/retry-signals/). No vendor sent retry-after-ms. The saved responses had statuses 200, 400, 401, 403, 404, 405 and 429; no 409, 425 or 501 appeared, which does not show a vendor never sends them.

The wait a provider asks for, in seconds, becomes the error's retry_after_ms, in milliseconds rounded up. Fiber reads it from retry-after. On google-generative-ai, Fiber reads Retry-After or the error body's RetryInfo.retryDelay, whichever is present. That is the shape Google documents, and no Gemini API 429 was reached (research/retry-signals/). The one 429 Google Vertex sent carried neither, so Fiber waits its own backoff for one ("Google Vertex wire facts").

The defaults are 3 retries with exponential backoff: 2 seconds, then 4, then 8, with each delay capped at 60 seconds. If the server asks Fiber to wait longer than 60 seconds, the call fails at once with that wait in the error, so a person or a caller can decide. The values are config. The terminal and the headless door use the same policy. A caller that wants to outlast a long outage retries the whole run.

When a stream dies midway, the partial text is not kept, because deltas are ephemeral. A tool call the model finished emitting inside a failed message never runs. The retry asks the model again.

An openai-responses stream that ends in response.failed is one such failure. Everything it already streamed is dropped, finished tool calls included, and the call is retried. Its code comes from the error body, and is stream_incomplete when no other code matches (docs/errors.md).

When the retries run out, the step fails with the provider's error. Fiber never switches to another model or provider on its own.