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:
| Protocol | Used by |
|---|---|
anthropic-messages | Anthropic, OpenCode, OpenRouter, Databricks, muse, AWS Bedrock (Claude), Google Vertex (Claude), Azure (Foundry Claude) |
openai-completions | OpenCode, OpenRouter, Databricks, muse, Azure |
openai-responses | OpenAI, ChatGPT/codex, OpenCode, Databricks, muse, Azure |
google-generative-ai | the Gemini API, Google Vertex (Gemini) |
bedrock-converse | AWS 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:
| Provider | Protocols | Credential |
|---|---|---|
| Anthropic | anthropic-messages | key |
| OpenAI | openai-responses | key |
| Gemini API | google-generative-ai | key |
| ChatGPT/codex | openai-responses, with its flags | subscription login |
| OpenRouter | openai-completions, with compat.anthropic for Claude | key |
OpenCode: opencode-go and opencode-zen | anthropic-messages, openai-completions, openai-responses, google-generative-ai | key, one for both |
| Databricks | anthropic-messages, openai-completions, openai-responses | key |
| muse (the Meta Model API) | anthropic-messages, openai-completions, openai-responses | key |
| AWS Bedrock | anthropic-messages for Claude and bedrock-converse for other models, both with AWS framing | Bedrock API key, or SigV4 through sign() |
| Google Vertex | anthropic-messages for Claude, google-generative-ai for Gemini | token from credential() |
| Azure (not built yet: see #224) | openai-completions, openai-responses; anthropic-messages for Foundry Claude | api-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).
- In 7 successful streams (text, tool use,
max_tokens,stop_sequence, adaptive thinking),message_deltacarried thestop_reasonand was followed bymessage_stop, the last event. /v1/messages?beta=truereturned the same status, header names, body keys and event names as/v1/messages.- Without
tools,tool_choiceofautoornonereturned 200.anyandtoolreturned 400. - A
tool_useblock carriescaller:{"type": "direct"}for a client tool call, and{"type": "code_execution_20250825", "tool_id": "srvtoolu_..."}when server-side code execution calls the tool. Replaying the block withoutcallerreturned 200. An invalidcallerreturned 400. - More than 4
cache_controlblocks acrosstools,systemandmessagesreturned 400. - A reply stops with
pause_turnwhen the server-side loop for a hosted tool such as web search reaches its iteration limit, 10 by default. The reply may end in aserver_tool_useblock with no result block. Anthropic's continuation: "append the assistant's response to your messages and make another API request", with the sametools(https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons). Apause_turnreply is nevertool_use: a client tool call stops withtool_use. Fiber continues a paused reply asdocs/loop.md, "A reply paused by a hosted tool", says. - More than 20 tools with
strict: truereturned 400, "The maximum number of strict tools supported is 20" (measured October 1, 2026). thinking: {type: "enabled", budget_tokens: 1024}withmax_tokens: 2048returned 200 onclaude-haiku-4-5through OpenRouter's native Messages endpoint (research/reasoning-resume, September 27, 2026), whileenabledonclaude-sonnet-5-5returned 400 ("Use thinking.type.adaptive and output_config.effort").- A replayed
tool_useblock carriesinputas an object: a call whose arguments are not an object is sent back withinputof{}, paired with its failed result quoting what the model sent (docs/tools.md, "Before a call runs").
Google Generative AI wire facts
Measured against gemini-3.1-flash-lite on the Gemini API:
- The
x-goog-api-keyheader and the?key=query parameter both authenticate. systemInstruction.roleset touser,modelor left out is accepted, and the instruction is obeyed in all three.parametersJsonSchemaaccepted a schema with$ref,$defsandanyOf.parametersrejected the same$refwith HTTP 400.- A replayed
functionCallpart without athoughtSignaturefails with HTTP 400. In the calls sampled, the model put anidon eachfunctionCallit emitted. Four replay cases were accepted: a conforming id, an id outside[a-zA-Z0-9_-]{1,64}, a 65-character id, and afunctionResponseid that differs from the call's. - A
functionResponsemay carry an image inparts, and the model read it. - A request that declares function tools beside the hosted
google_searchis refused with HTTP 400 unlesstoolConfigsetsincludeServerSideToolInvocationstotrue. With the flag the search arrives astoolCallandtoolResponsecontent parts, each signed with its ownthoughtSignature, before the answer text; the candidate'sgroundingMetadataon the last chunk carries the result URLs. Measured October 9, 2026 ongemini-3-flash-preview. - Function-calling mode
VALIDATEDreturned schema-valid arguments whereAUTOreturned arguments that broke an enum and an integer type. In the sample it did not force a call.
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).
- Gemini's base URL is
https://aiplatform.googleapis.com/v1/projects/<project>/locations/global/publishers/google, andgoogle-generative-aiappends the Gemini API's own/models/<id>:streamGenerateContent?alt=sse. The stream is the Gemini API's, withmodelVersion,createTimeandusageMetadata.trafficTypeadded. The token goes inauthorization: Bearer;x-goog-api-keyanswered 401 "API keys are not supported by this API". - Every Gemini API fact above held for
gemini-3.1-flash-lite:systemInstruction.roleuser,modelor left out was obeyed;parametersJsonSchematook$defs,$refandanyOfunderVALIDATED, andparametersrefused them with 400; a replayedfunctionCallwithout itsthoughtSignaturefailed with 400, and the three odd ids were accepted; an image infunctionResponse.partswas read. Calls carried an id on every model butgemini-3.1-pro-preview-customtools, whose call had none. AthinkingLevelstreamed athoughtpart, the text, then an empty part carrying the signature. - Function tools beside the hosted
google_searchwere accepted withoutincludeServerSideToolInvocations. With or without it the search came only as the last chunk'sgroundingMetadata, never astoolCallandtoolResponseparts, so no Vertex model declaresweb_search. One of two requests with the flag ended after its first chunk with no finish reason. - Implicit caching reports reads: a session's later call counted 3,167 of its
3,590 input tokens as
cachedContentTokenCount. globalis served fromaiplatform.googleapis.comand a region from<region>-aiplatform.googleapis.com;global-aiplatform.googleapis.comanswered 404.gemini-3.1-flash-liteanswered 404 atus-central1andasia-south1: Gemini 3 is served atglobalonly, so every Vertex model's base URL namesglobal.- Claude's base URL is the same with
publishers/anthropic. A model that declarescompat.vertex_raw_predictposts theanthropic-messagesbody to<base_url>/models/<id>:streamRawPredict, withanthropic_version: vertex-2023-10-16in place ofmodel. No Claude model answered on the probe's project, so this rests on Google's and Anthropic's documentation: each answered 404 "not found or your project does not have access to it", andclaude-fable-5403 "requires data sharing to be enabled for publisher 'anthropic'". - Every
streamRawPredictfailure came as a list holding one error object,[{"error": {...}}]. Undervertex_raw_predictthe object inside is read, as any provider's error body is (docs/errors.md). - An unknown model, or one the project cannot call, answered 404
NOT_FOUNDwith "Publisher modelprojects/.../models/<id>was not found"; a garbage token and an expired one the same 401UNAUTHENTICATED, reasonACCESS_TOKEN_TYPE_UNSUPPORTED; a 429RESOURCE_EXHAUSTED"Resource exhausted. Please try again later." with noRetry-Afterand noRetryInfo.gemini-4-argonanswered one call and then refused every request with 403 "Request rejected in accordance with our terms of use and policies", so it is not shipped. Gemini's error bodies arrived ascontent-type: text/event-stream.
OpenCode wire facts
Measured on October 1, 2026 with one OpenCode key (research/opencode-probe).
- The
opencodeextension declares two providers,opencode-goandopencode-zen, because Go and Zen serve many of the same model ids and bill them differently:opencode-go/gpt-6-lunaandopencode-zen/gpt-6-lunaare two models. The same key works on both, and both providers read it fromOPENCODE_API_KEY. Both providers name one stored credential ("Credentials"), so one stored key serves both. opencode-gois a subscription athttps://opencode.ai/zen/go, and its models declare"subscription": truebeside their prices ("Cost").opencode-zenis billed per token athttps://opencode.ai/zen, and its models carry prices only.- Both serve
openai-responsesat/v1/responses,openai-completionsat/v1/chat/completionsandanthropic-messagesat/v1/messages. Zen also servesgoogle-generative-aiat/v1/models/<model>:generateContent: one request each togemini-3.5-flash-liteandgemini-3.8-flashanswered 200 (research/opencode-zen-gemini-probe). - A model speaks one protocol.
muse-spark-1.3-contributoron Go answered on/v1/responses, and on the other two it answered 400 withModelProtocolUnsupported. Each model declares its protocol. - Go and Zen list different models:
GET /zen/go/v1/modelslisted 30 andGET /zen/v1/modelslisted 18, with ids only, no prices or protocols. A Go model sent to Zen's URL answered 400 "Model is unavailable". - No response carries a cost, and nothing marks a call as subscription. Go's
spend shows only as quota (
docs/tools.md, "Provider quota"). - Requests carry
x-opencode-session(docs/prompt-cache.md, "Cache markers and keys"). Go refuses a request without it: HTTP 400 "Request is missing x-opencode-session and cannot be routed efficiently", measured on October 1, 2026. Cloudflare answers 403 "error code: 1010" to Python's defaultUser-Agent, so the probe sent its own. - Go sends
store: falseon itsopenai-responsesandopenai-completionsrequests, as the OpenAI provider does on every request; itsanthropic-messagesrequests carry nostorekey.
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).
- A model with
compat.bedrock_invokeposts to<base_url>/model/<id>/invoke-with-response-stream, with the id percent-encoded (:as%3A) andaccept: application/vnd.amazon.eventstream. The body is theanthropic-messagesbody with nomodeland nostream, andanthropic_version: bedrock-2023-05-31where Anthropic takes theanthropic-versionheader. A model's beta flags go in the body'santhropic_betalist, through itsextra_body; Fiber sends noanthropic-betaheader. - The reply is AWS event-stream framing. Each message is a prelude (its total
length and its headers' length, big-endian 32-bit, then the prelude's
CRC-32), string headers, a payload and the CRC-32 of the rest of the
message. Each
:event-typechunkmessage's JSON payload holdsbytes, one Anthropic stream event in base64, beside apfield of padding. The events are Anthropic's own,message_starttomessage_stop, andmessage_stopalso carriesamazon-bedrock-invocationMetrics. No stream probed sentping. A message whose checksum fails, or whose lengths are out of range, fails the call withstream_incomplete, since nothing after it can be trusted. message_startsplits cache writes by lifetime incache_creation, as Anthropic's does. Prompt caching wrote and read with a 5-minute marker, a 1-hourttlwas accepted, and Fiber's own sessions recorded 1-hour writes and later reads, a resumed turn's included.thinking: {type: "enabled", budget_tokens}streamed a signed thinking block on Haiku 4.5, and a signed thinking block sent back in the next request was accepted. Adaptive thinking withoutput_config.effortwas accepted on Haiku 5.5.- A thinking block's signature carries the AWS account id in clear inside its base64, so a recording's signatures are scrubbed before it is checked in.
- A failure before the stream is a JSON body,
{"message": ...}, or{"Message": ...}for a malformed API key, and names its exception only in theX-Amzn-ErrorTypeheader, asValidationException:http://internal.amazon.com/coral/com.amazon.bedrock/(docs/errors.md, "Recognising an AWS exception"). An unknown model id, and a geography's profile used from a region outside it, answered 400ValidationException"The provided model identifier is invalid.". - A failure during the stream is a message whose
:message-typeisexception, naming itself in camel case in:exception-type, such asthrottlingException, with its text in the payload'smessage. The probe reached none.
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).
- A request posts to
<base_url>/model/<id>/converse-stream, the id percent-encoded as on Invoke, withaccept: application/vnd.amazon.eventstream. A Bedrock API key goes inauthorization: Bearer, andsign()replaces it with SigV4 ("Protocols and providers"). The body holdssystem, one text block, left out when the system prompt is empty;messages;inferenceConfig.maxTokens, the output limit (docs/errors.md, "Output tokens");toolConfigwhen the request has tools; andadditionalModelRequestFieldsfor a thinking level ("Thinking"). - Consecutive inputs of one role fold into one
userorassistantmessage, as onanthropic-messages. A person's text is atextblock, and each image animageblock,{format, source: {bytes}}, after it. A tool call istoolUsewithtoolUseId(the provider's id when it ends in nine letters and digits, else the action id),nameandinput. A result istoolResultwith thattoolUseIdandcontent: [{text}], plusstatus: "error"when the call failed: AWS documents the field for Nova and Claude only, and five other models accepted it. A result's images, and a PDF's pages rendered as images, follow it asimageblocks in the same user message: Ministral 3 8B and Qwen3 VL refused an image insidetoolResult, and took it beside. - Each tool is
{toolSpec: {name, description, inputSchema: {json}}}, in name order, with nodescriptionwhen it is empty, as AWS documents one of at least one character, and nostrict: Nova Micro refused the field,trueorfalse, where gpt-oss and Ministral took both.toolChoiceis left out forauto, Converse's default, and fornone, which Converse lacks;anysends{any: {}}, and a tool's name{tool: {name}}. - A request whose messages hold a
toolUseortoolResultblock and that has notoolConfiganswered 400. Fiber's requests without tools hold neither: the reviewer, a note request and an extension'shost.modelcall send text. - A Mistral model reads the last nine characters of a replayed
toolUseId, and refuses them unless they are letters and digits. An id Bedrock issued passes, and so does an action id; another provider's id, such asfunctions.read:0, may not, so Fiber sends the action id in its place. - The reply is AWS event-stream framing. Each message's
:event-typenames its event and its JSON payload is the event, beside apfield of padding:messageStart; per content block an optionalcontentBlockStart, itscontentBlockDeltas andcontentBlockStop, each withcontentBlockIndex;messageStopwithstopReason; thenmetadatawithusage, the last event of every stream probed. A stream that ends beforemetadatafails withstream_incomplete. Only a tool call's block has a start, carrying its id and name; its input arrives as JSON text indelta.toolUse.input. A text or reasoning block opens with its first delta. - Reasoning arrives in
delta.reasoningContentastext, asignature(Claude only), orredactedContent(Grok). Fiber logs it in the form Converse takes back,reasoningContentholdingreasoningTextwith its text and signature, orredactedContent, and sends it back unchanged to the model that produced it (docs/loop.md, "What the model is sent"). All three forms were accepted back. Nova 2 Lite's text is the literal[REDACTED]. A Claude signature carries the AWS account id inside its base64, as on Invoke. stopReasonend_turn,tool_useandstop_sequencecomplete the reply, andmax_tokenscuts it off at the output limit.guardrail_intervenedandcontent_filteredfail the call withrefused,model_context_window_exceededwithcontext_overflow, andmalformed_model_outputandmalformed_tool_usewithstream_incomplete, so the retry asks again. The probe reachedend_turn,tool_useandmax_tokens.usage.inputTokensexcludes cache reads and writes: Nova Micro reported 4 input beside 2,121 read.cacheReadInputTokensis the call'scache_read, andcacheWriteInputTokensa write under"5m", the lifetime of acachePointsent withoutttl(docs/prompt-cache.md, "Cache markers and keys"). No reply carried thecacheDetailsAWS documents.- Converse names no generation in its stream. Fiber takes the response's
x-amzn-RequestIdheader, AWS's id for the call, as the generation id, so the model's declared prices apply ("Cost"). A 200 stream and a 400 error both carried one, a UUID. A response without it, or with an empty one, leaves the generation unnamed: Fiber mints its id, and the call is unpriced. - A failure before the stream names its exception in
X-Amzn-ErrorType, and one during it is anexceptionmessage, as on Invoke (docs/errors.md, "Recognising an AWS exception"). An unknown model id answered 400ValidationException"The provided model identifier is invalid.", and a model the account may not use 403AccessDeniedException. - A replayed
toolUseblock carriesinputas an object: a call whose arguments are not an object is sent back withinputof{}, paired with its failed result quoting what the model sent (docs/tools.md, "Before a call runs").
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:
- A reply has
text, a string or a list of strings streamed as fragments in order, ortool_calls, a list of{"name": ..., "arguments": {...}}, or both. It may addreasoning, a string streamed before the text;usage, theinput,outputandcache_readtokens it reports, each 0 when absent; andevery_ms, a pause on the session's clock before every text fragment after the first. Its tool calls' ids arecall_<step>_<n>, both counted from 1. It names no generation and reports no cost. - An error is
{"error": {"code": ..., "message": ..., "retry_after_ms": ...}}, alone in its step.codeis one a failed model call has (docs/errors.md, "A failed model call"), andretry_after_msmay be left out.
{"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:
- its name, which is the first half of every model reference
- how its credential is found (see Credentials), or a
credential()function that returns a token login, whenfiber loginruns that function as a login instead of reading a key:browser, whose device-code form takes--devicecredential_label, when that function supplies the credential and reads nothing Fiber stores, as AWS Bedrock's and Google Vertex's do:names, what a credential label names, such asAWS profile,default, what thedefaultlabel reads, optionalcredential_env, a list of environment variable names whose nonempty values prove presence, andcredential_paths, the paths it draws secrets from, which the credential deny protects (docs/permissions.md, "Credentials"). Such a provider has no key forfiber loginto store, sofiber doctorshows its label as that source, unchecked (docs/invocation.md, "Commands and flags"), and no sentence advisesfiber login(docs/errors.md, "The shape"). It is never declared besideloginor acredentialkey source- headers sent on every request
- a
sign()function, if every request must carry a signature reviewer_model, optional: the package defaultfiber loginpreselects as the provider's reviewer, and the final fallback when no reviewer is configured (docs/permissions.md, "How it runs"). A first-party package names the model its vendor's own agent reviews with, at the current generation:claude-sonnet-5-5,gpt-6-luna; Google ships no reviewer, sogemininames its middle tier,gemini-3.8-flash. A first-party package never names a contributor model asreviewer_model, and a package whose models are all contributor models names none.
For each model:
- its id, as the vendor spells it
name, optional: its display name, such asClaude Opus 5.5, which the model picker's filter matches beside the provider and id (docs/tui.md, "Swapped views"); a model with no name is matched on provider and id only- its protocol and base URL, which can differ between models of one provider, and may name a per-account host ("A per-account host")
- compatibility flags the native protocol reads, such as whether the vendor
accepts
store, which field carries the token limit, which thinking dialect it speaks, and whether the request leaves thestrictkey off every tool (compat.no_strict, whichclaude-opus-4-1needs on the Databricks gateway: it rejectsstricteven asfalse) - the thinking levels it supports ("Thinking")
- whether deferred tools work for it, declared only after a probe
(
docs/tools.md, "Which tools the model sees"), except the Databricks Claude rows set from theirproviders/anthropiccounterparts there web_search: the vendor's own hosted-search tool type, exactly as it is sent, such asweb_search_20250305orgoogle_search; absent when the model's provider hosts no search for it ("Hosted web search")- extra request body fields, which may not name a field Fiber builds itself ("Extra request body fields")
prompt_addendum, naming a Markdown file in the extension package whose text is appended to the system prompt for this model only (docs/system-prompt.md, "The model's addendum"); a named file that is missing or outside the package fails the load, under the same checkpromptgets- context window, which every model declares: one without it is left out of
the model list with the notice
model_invalid, because compaction and the size notices are measured against it - output token limit, input kinds and cost
- whether a subscription login covers it ("Cost")
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:
| Protocol | Fields extra_body may not name |
|---|---|
anthropic-messages | model, system, messages, tools, tool_choice, stream, cache_control |
openai-completions | model, messages, tools, tool_choice, stream |
openai-responses | model, instructions, input, tools, tool_choice, stream |
google-generative-ai | systemInstruction, contents, tools, toolConfig |
bedrock-converse | system, 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.
Hosted web search
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
- OpenAI's
gpt-6-lunarejectsmax_tokenswith a 400 and takesmax_completion_tokens. OpenRouter, withz-ai/glm-5.3-flash, accepts both. - OpenAI, with
gpt-6-luna, sent a usage chunk (choices: []) in the one stream that setstream_options.include_usageand none in the one that did not. OpenRouter, withz-ai/glm-5.3-flash, sends a usage chunk either way, and repeatsfinish_reasonon it. - A model with
compat.gemini, such as a Databricks Gemini service, sends nostream_optionsorprompt_cache_key, and each nullabletypepair[T, "null"]outside anenum,const,defaultorexamplesvalue is sent astype: Twithnullable: true: the gateway's Gemini route rejects all three. - OpenRouter, with
z-ai/glm-5.3-flash, streams reasoning asreasoningplusreasoning_detailsentries of typereasoning.text. Across the streams run on that model, it sent noreasoning_contentorreasoning_text. - OpenRouter, with
z-ai/glm-5.3-flashpinned to one upstream, readsreasoning,reasoning_contentandreasoning_detailson a replayed assistant message. - OpenRouter, with
z-ai/glm-5.3-flash, acceptscache_controlon a system part, the last message and a tool, and acceptsttlon the system part. It also accepted one request with an invalidtype. This shows acceptance only. Withanthropic/claude-haiku-4.5pinned to the Anthropic upstream, OpenRouter passes markers on the system part, the last message and a tool, andttl, through to Anthropic (research/openai-completions-probe). - Tool-call deltas from
gpt-6-lunaand from OpenRouter withz-ai/glm-5.3-flashcarryindex. OpenRouter adds: OPENROUTER PROCESSINGcomment lines to the stream. - On Databricks,
gemini-4-argonrejectsreasoning_effortwith a 400 whilegemini-3-8-flashaccepts it (research/databricks-gateway-probe). - On Databricks, open-weight chat services reject
max_completion_tokenswith a 400 and takemax_tokens, while the GPT and Gemini services on the same route takemax_completion_tokens(research/databricks-gateway-probe). - A gateway serving Gemini returns a tool call's
extra_content(such asextra_content.google.thought_signature) on the call; the last delta carrying one wins. Fiber decodes each such call with its carrier immediately before it, an empty-textReasoningholding the verbatim{"extra_content": ...}, the calls in stream order. Undercompat.geminia bare{"extra_content": ...}carrier waits for its own model's next tool call and replays back byte-identical on that call only, in conversation order; a user turn, a tool result or a foreign-model call clears it, a trailing carrier is dropped, and without the flag noextra_contentis ever sent. A wider object is no carrier: it merges into the assistant message as before, and a foreign model's carrier never merges.
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:
| Protocol | cache_read | cache_write |
|---|---|---|
anthropic-messages | cache_read_input_tokens | cache_creation.ephemeral_5m_input_tokens under "5m", cache_creation.ephemeral_1h_input_tokens under "1h" |
openai-completions | prompt_tokens_details.cached_tokens | prompt_tokens_details.cache_write_tokens, always under "5m" |
openai-responses | input_tokens_details.cached_tokens | input_tokens_details.cache_write_tokens, always under "5m" |
bedrock-converse | cacheReadInputTokens | cacheWriteInputTokens, 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.
- At start, Fiber refreshes each provider that has a credential when its
cached list is older than
model_lists.refresh_after(docs/configuration.md) or its extension source is newer than the cached copy. The default age is one day. Each provider that ran is unloaded once its list is written. Only the extensions the session uses stay loaded, among them each provider whose quota a client asked for (docs/tools.md, "Fetching"), and a provider with no credential never runs. - When no cached copy exists,
models()runs when the list is first needed, but only for a provider with a credential.models()receives{ key, placeholders }: the provider's key as a session reads it, absent when its token comes fromcredential(), and the host each declared placeholder holds. Fiber does not callmodels()while a declared placeholder has no value or a value that is not a host, so the key goes only to a host the person set. - The model picker refreshes, in the background, any provider whose list
is older than
model_lists.refresh_afteror whose extension source is newer than the cached copy, and updates the list when the result arrives. Its refresh button refreshes every provider with a credential, and the models.dev catalog, whatever the age of each.
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:
- The package's table pins and
providers/models-corrections.toml. - The fetched models.dev catalog.
- 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.
| Protocol | Largest dimension | Largest encoded image | Images per request | Resizing the vendor documents |
|---|---|---|---|---|
anthropic-messages | 8000 px; 2000 px per image once a request holds more than 20 | 10 MB as base64 (5 MB on Bedrock and Google Cloud); 32 MB per request | 600, or 100 for a model with a 200k-token context | to 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-completions | none; 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 request | 1,500 | at detail: high; original keeps the size and rejects over 30,000 patches |
google-generative-ai | none stated | 20 MB per request, inline | 3,600 | none stated; the page describes 768 px tiles for counting tokens |
Requests to check the table, on September 29, 2026, one image each:
claude-sonnet-5-5: an 8000 by 6000 px PNG was accepted and counted 4,788 input tokens. A 9000 by 9000 px PNG failed with a 400 naming the 8000 px limit, and a 23 MB base64 PNG with a 400 naming the 10 MB limit. A GIF was accepted.gpt-6-luna, default detail: on each protocol, an 8000 by 6000 px PNG (47,000 patches) and a 9000 by 9000 px PNG were rejected with a 400 naming the 30,000 patch limit. A 23 MB base64 PNG was accepted on both, and a GIF onopenai-responses.gemini-3.1-flash-lite: the 8000 by 6000 px and 9000 by 9000 px PNGs, a 23 MB base64 PNG (over the 20 MB the page states) and a GIF (which the page does not list) were all accepted, at 1,091 to 1,116 prompt tokens.
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:
-
Fiber tries the exact string as
provider/model. -
If nothing matches and the string ends in
:and a thinking level (off,minimal,low,medium,high,xhighormax), Fiber strips the suffix, matches the rest and applies that thinking level. -
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, asprovider/model. A provider that is installed but lacks the named model isno_model. A bare id that no installed provider has isno_modeltoo, and its message says to runfiber models. When no switched-on provider has the id but a logged-out installed one does, the error iscredential_missing: it names the provider as not logged in, with the login command, except a logged-outcredential()holder's sentence carries no such command (docs/errors.md, "The shape"). Only aprovider/modelwhose provider is not installed isextension_missing. These rules match a model left out withmodel_unconfiguredtoo, so naming one ismodel_unconfigured, notno_model, and a bare id it shares with another provider's model ismodel_ambiguousonly 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:
--modelgiven 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.- The model a resumed session was using.
- 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 stored credential
- an environment variable
- a file
- the output of a command, run once per process
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:
--credential <label>on a resume, which both doors accept.- The label a resumed session was using.
- For a delegate started with a role, the role's
credential(docs/delegates.md, "Choosing a model"). providers."<name>".credential, from any layer except a repository's.- 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.
headersare sent on every request that uses the token, and are cached and refreshed with it. ChatGPT/codex returns itschatgpt-account-idhere. A header Fiber builds itself, such asauthorization, fails the call withcredential_failed.emailis read only byfiber login, which uses it as the label when--asis absent ("Logging in"). Every other call ignores it.
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:
- rate limits (HTTP 429)
- server errors (HTTP 5xx) and overload responses
- a request timeout (HTTP 408) and a conflict (HTTP 409)
- a failure with no HTTP status, such as a dropped connection
- a stream that ends before its protocol's terminal event
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.