Skip to content

spec.md

Latest commit

 

History

History
160 lines (123 loc) · 9.39 KB

spec.md

File metadata and controls

160 lines (123 loc) · 9.39 KB
Raw

Provider Runtime Contract

Status: maintained contract.

Ownership

Provider code lives in src/main/provider/:

  • defaults.ts and provider database define display/config/model metadata;
  • providerRegistry.ts maps a provider profile to a known runtime, model source, check strategy and auth kind;
  • index.ts owns provider/model settings and runtime instances;
  • aiSdk/ maps supported HTTP transports;
  • providers/ contains behavior that exceeds a generic transport;
  • auth/ owns OAuth/device flows and encrypted credential storage;
  • routes.ts exposes typed renderer operations.

Renderer code selects and configures providers but never owns API keys, OAuth refresh tokens or provider instances.

Integration rules

Adding a provider is an explicit reviewed source change, not a runtime npm/plugin loader. The .agents/skills/add-provider/SKILL.md workflow must map the requested provider to:

  1. stable provider ID and display metadata;
  2. known transport/runtime kind;
  3. default base URL and auth kind;
  4. model source, check strategy and check model;
  5. request headers, endpoint rewrites or capability exceptions;
  6. renderer icon/config and focused tests.

Prefer an existing OpenAI-compatible/Anthropic/AI SDK transport when wire behavior matches. Add a special adapter only when auth, request shape, discovery, streaming or error semantics differ. Do not infer runtime behavior from package names and do not install arbitrary SDKs dynamically.

API-key profiles such as NVIDIA, Hugging Face, Moonshot, StepFun, Upstage, Alibaba, MiniMax, DaoXE, Kimi For Coding and OpenCode Go remain catalog/registry mappings unless they need a real special adapter.

Default reset URLs are derived from each profile's base URL, except explicit website overrides (currently Vertex, Azure and MiniMax). Defaults never overwrite a saved user endpoint. Catalog-backed profile membership is derived in the main registry from provider-db, kimi-for-coding and openai-codex model-source strategies, not a separately maintained ID list. The existing default-provider route projects usesProviderDb for renderer refresh hints; this field is not a persisted provider setting. Model-fact cleanup remains profile-ID based and preserves explicit custom-model facts rather than inferring ownership from a shared transport.

Model capability identity

Provider service identity, transport identity, and provider-db capability identity are separate contracts. A provider profile owns credentials and its service endpoint. A transport route owns the wire protocol used by one model. A capability identity owns the single provider-db model record used for reasoning, sampling, tools, modalities, search, and other model behavior.

Aggregator routes resolve in two phases. Model ID and owner metadata first provide only the coarse Anthropic or Gemini family hint needed to choose an endpoint. The selected endpoint then participates in complete capability resolution. A transport endpoint is a fallback signal and never overrides an explicit, provider-local, owner, family, or catalog model match.

Capability identity is resolved in the main process and passed through the provider runtime. Renderer code consumes typed capability snapshots and does not reproduce provider routing rules. Per-model aggregator matches are derived request state and are not persisted in provider or model configuration. Provider-level capabilityProviderId remains an explicit compatibility override. Resolved identity keeps the request-facing model ID separate from the optional matched catalog model ID. Recognized origin families may select their authoritative provider-db owner, but ambiguous families never select a mirror by provider iteration order. Known provider profiles keep provider-local model configuration defaults; cross-provider defaults are limited to explicit overrides and profiles absent from provider-db, such as New API.

Generation controls use an effective request policy that can pass through, fix, or omit a parameter. Stored model and Session values remain user intent; policy is applied at the UI and wire boundaries without destructive normalization. Unknown catalog capabilities remain compatible by passing through unless an explicit model request policy requires a different wire shape.

Auth and secrets

  • API keys and OAuth credentials are written and read in main process storage.
  • Renderer status and route payloads are redacted; raw token, key and account identity are never emitted.
  • Refresh is single-flight and persists rotated credentials before they replace the active instance.
  • Browser OAuth uses shell.openExternal plus loopback callback when supported; paste/device fallback is provider-specific and must be explicit.
  • AbortSignal, proxy, timeout and provider error mapping must survive every adapter layer.

Fireworks

Fireworks uses the existing OpenAI-compatible transport with API-key credentials and the fireworks-ai provider-db catalog. Connection checks generate text with accounts/fireworks/models/gpt-oss-120b; they do not assume the inference endpoint exposes a model-discovery API. The default endpoint is https://api.fireworks.ai/inference/v1.

For existing Fireworks configurations, normalize only the old official /inference endpoint (with or without a trailing slash) in the request-time copy. Preserve saved configuration, already-versioned endpoints and custom proxies. No special provider class or storage migration is required.

Upstream references: OpenAI compatibility and GPT OSS 120B model ID.

APIMODELS

apimodels uses the OpenAI-compatible transport with API-key credentials. Live model discovery keeps only records with modality: 'chat'; other catalog entries require unsupported routes. The catalog is public, so connection checks generate text with gpt-5.6-luna and the shared 16-token output limit to validate credentials. Embeddings are disabled for this profile.

Upstream reference: Language Models API.

CloudGPU

cloudgpu uses the OpenAI-compatible transport with API-key credentials. Live model discovery lists every chat model from the public /v1/models catalog. The catalog has no capability field, so ids that are clearly not chat models (embedding, rerank, image, audio, speech, TTS and transcription ids) are skipped by name. The catalog is public, so connection checks generate text with deepseek-v4.1-flash and the shared 16-token output limit to validate credentials. Embeddings are disabled for this profile.

Upstream reference: API docs.

Obscurify.ai

obscurify uses the OpenAI-compatible transport with API-key credentials. Live model discovery reads the public /v1/models catalog, keeps each model's context_length and tools flag, and skips entries that are not chat models: decision models (decisions: true, which include the typesafe/jev-* judgment models) and ids that match the shared non-chat filter, such as image models. The catalog is public, so connection checks generate text with meta-llama/llama-3.3-70b-instruct and the shared 16-token output limit to validate credentials. Embeddings are disabled for this profile.

Upstream reference: API docs.

OpenAI Codex

openai-codex is separate from standard openai: distinct provider ID, runtime kind, credential store, routes and request adapter. Current recommended catalog includes gpt-6.1-sol, gpt-6-astra, gpt-6-sol, gpt-6-luna, gpt-5.5, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-image-2.5-sunburst, gpt-image-2.5-flare and gpt-image-2. Chat models require provider-db metadata. Curated image models remain listed when metadata is missing and use the OpenAI image-route compatibility fallback; explicit user model settings retain precedence. Connection check uses gpt-5.6-luna. GPT-5.4, GPT-5.4 mini and Codex Spark are omitted following their Codex retirement.

Codex requests include required instructions and backend routing headers, preserve streaming/tool/reasoning behavior, and surface entitlement failure without logging token or account identifiers. Rejected refresh tokens retain their HTTP failure metadata and require sign-in again; media CLI calls return authentication_failed with retriable: false. Other media provider failures expose only normalized HTTP status and retryability. Unreadable credential files remain storage failures. OAuth error bodies are parsed before diagnostic messages are limited to 1,000 characters. Image generation uses the same OAuth credential path with /images/generations; Responses-only body normalization does not apply to image requests. The image-generation projection preserves shared OpenAI image settings but disables vision input because the standalone route accepts only text prompts. Background provider-db refresh skips its dedicated runtime catalog; manual refresh remains available.

Validation

Provider work must test registry mapping, defaults/import, auth redaction/refresh, request adapter, model catalog/check and renderer configuration where affected. Existing providers must remain unchanged unless the spec explicitly includes a migration.

Non-goals: runtime provider manifests, renderer-owned credentials, automatic SDK installation and provider behavior inferred from external catalogs.