Model Capabilities

Model Capabilities

contractVersion: 1.0.1

Model capabilities are declared per (providerId, modelId) and feed Capability Negotiation. The bundled provider extensions register their known model declarations at provider load time; third-party providers register theirs the same way.

---

Authoritative seven-capability vector

Every model declaration carries a ProviderCapabilityClaims record (see Providers contract):

Field	Type	Meaning
streaming	CapabilityLevel	Model can stream text deltas instead of only whole responses.
toolCalling	CapabilityLevel	Model can emit structured tool-call requests core can parse.
structuredOutput	CapabilityLevel	Model can enforce JSON or another declared structured response shape.
multimodal	CapabilityLevel	Model can consume non-text input parts such as images.
reasoning	CapabilityLevel	Model can emit thinking / reasoning deltas or summaries. Configuration of reasoning effort and thinking budget is via the active provider's adapter-native provider params; each adapter page enumerates the accepted fields (Anthropic effort/thinking; OpenAI reasoningEffort/reasoningSummary; Gemini thinkingConfig.{ thinkingBudget, thinkingLevel, includeThoughts }).
contextWindow	number | 'probed'	Usable input-token window, or deferred discovery when unknown at load time.
promptCaching	CapabilityLevel	Provider/model supports prompt-cache semantics. Defaults to probed for detect-on-use. See Prompt Caching for the cross-provider strategy.

CapabilityLevel is one of:

Level	Semantics
hard	Guaranteed by the provider for this model.
preferred	Expected to be available but negotiates as degraded if absent.
probed	Unknown until first use or explicit runtime probe.
absent	Not available for this model.

---

Declaration convention

Reference and third-party providers register their known model declarations at provider load time. Each declaration carries a (providerId, modelId) key and the seven capability claims above. Example: the Anthropic reference provider declares claude-opus-4-7 with streaming: hard, toolCalling: hard, structuredOutput: preferred, multimodal: preferred, reasoning: preferred, contextWindow: 200000, promptCaching: probed.

Consumers resolve a selected model by (providerId, modelId). An unknown pair falls back to the conservative default vector documented in § Defaults and probing.

Declarations are process-local and immutable by key. If a provider declares the same (providerId, modelId) twice with different claims, the first declaration wins and core emits a SuppressedError observability event with reason Validation/DuplicateModelDeclaration.

---

Defaults and probing

When a model declaration is absent, core falls back to the conservative default vector:

Capability	Default
streaming	hard
toolCalling	probed
structuredOutput	probed
multimodal	probed
reasoning	probed
contextWindow	probed
promptCaching	probed

promptCaching: probed is intentional. Prompt caching is detect-on-use: compatible providers may silently accept cache markers, reject them, or expose cache benefits only on specific models. The default must not advertise prompt caching as hard, and it must not mark it absent before the adapter has attempted use.

---

Session capability contract

At session start, core computes the session capability contract from the attached State Machine, active Context Providers, active Hooks, security mode, and other runtime needs. It compares that contract with the active (providerId, modelId) declaration. /model and /provider switches re-run the same check.

Mismatch handling belongs to Capability Negotiation: hard misses reject with ProviderCapability/MissingCapability; preferred misses warn; probed misses remain deferred until the feature is invoked.

---

Context window subtleties

• contextWindow is a token count, not a character count.
• Tokenization differs per provider; adapters should declare the usable window after provider-specific reservations.
• When unknown, declare contextWindow: 'probed' and let context budgeting treat the window as deferred.

---

Capability drift

Remote providers and compatibility proxies can change capabilities between sessions. Capability probes are run at session start every time and not persisted in the slim session manifest; a later session repeats the negotiation against current claims. Mismatch diagnostics surface via Validation/CapabilityProbeMismatch events. Core does not silently pick a fallback model.

---

Related pages

• Capability Negotiation
• Protocol Adapters
• Providers (contract)
• Provider Params
• Anthropic
• OpenAI-Compatible
• Gemini
• Capability-Mismatch-Switch flow

---

Changelog

1.0.0 — initial

• Seven-capability vector codified: streaming, toolCalling, structuredOutput, multimodal, reasoning, contextWindow, promptCaching.
• CapabilityLevel enum with four levels: hard, preferred, probed, absent. Conservative default vector for unknown (providerId, modelId) pairs.
• Per-pair declaration model: providers register declarations at load time; first declaration wins on conflict; capability drift treated by re-probing every session.

1.0.1 — Provider Params cross-reference on reasoning

• The reasoning row's "Meaning" cell adds a pointer to Provider Params and the per-adapter native-fields tables. The capability dimension itself is unchanged; configuration of reasoning is a per-adapter concern documented elsewhere.
• Page now carries an explicit contractVersion line. Prior content is codified as 1.0.0 — initial in this changelog.