zidane/providers

Resolve the creds-file path at call time rather than module-load time, so env changes between import and first OAuth use (test suites, multi-project CLIs) are honored.

Order:

1. ZIDANE_CREDENTIALS_PATH — explicit override. The chat host sets this at launch to point at the credentials file in its storage directory, so the harness providers find the same file the host manages.
2. ~/.credentials.json — home-anchored default.

The working directory is never consulted: launching zidane inside an untrusted checkout would let that repo plant a .credentials.json and become the credential source (and receive rotated refresh tokens on the next refresh persist). Same trust model as the TUI's legacy-file migration in chat/credentials.ts, which only honors the home-anchored location.

Cursor provider (OAuth).

Auth is fully wired: bun run auth --cursor (or the TUI wizard) logs in via Cursor's poll-based PKCE flow and persists credentials; this provider resolves

• refreshes the OAuth token on every turn via resolveOAuthApiKey.

Inference is not wired yet. Cursor does not expose an OpenAI-compatible HTTP endpoint — it speaks a protobuf/Connect agent protocol over HTTP/2 to api2.cursor.sh. Implementing stream() requires porting that transport (generated protobuf schemas + an HTTP/2 streaming client) in-process, which is intentionally left as a follow-up. Until then stream() resolves the token (proving auth works) and then throws a clear, actionable error.

The openaiCompat base supplies the message-format helpers (formatTools, userMessage, toolResultsMessage, …) so the provider satisfies the full Provider contract and slots into the registry; only stream is overridden.

A key for what a session shares when no session id is available: the static half of the system prompt plus the first user message.

Deliberately NOT the whole transcript — that grows every turn, which would hand out a new key per request and defeat the point. Nor the dynamic half of the system prompt (after SYSTEM_PROMPT_BOUNDARY, see splitSystemPrompt): it carries the date and working directory, so hashing it would move the key when the day rolls over mid-session. What remains stays byte-identical for a session's life and moves only with a different agent profile, a new opener, or a compaction that rewrites the head.

The message contribution is capped at its first 4 KiB of JSON: this runs on every stream call, and a first message carrying inline media (multi-MB base64) would pay a full stringify + hash per turn for no routing benefit — the first few hundred bytes already distinguish sessions, and the servers themselves only hash ~the first 256 tokens for routing. Two sessions that agree on system + 4 KiB of opener share a routing bucket, which is exactly when sharing a replica helps rather than hurts.

32 hex chars of sha256, matching the digest width used in src/attachment-handle.ts.

OAuth registry surface.

refreshAnthropicToken / refreshOpenAICodexToken are zidane's local reimplementations of functions pi-ai exported until 0.80.6 and dropped in 0.80.8. The runtime of its @earendil-works/pi-ai/oauth entrypoint is export {} (it ships types only). They are exported HERE because consumers that imported them from pi-ai otherwise have no supported replacement.

Get an API key for a provider from OAuth credentials, refreshing expired tokens through the registered flow. Same contract as the pi-ai original (null when no credentials are stored for the provider, throws on unknown provider or refresh failure), with two deliberate additions:

• refresh failures keep the underlying reason — the original discarded it, leaving invalid_grant (needs re-login) indistinguishable from a transient network error.
• options.force rotates regardless of the local expiry, for 401 recovery when the server revoked the grant before our stored timestamp said so. Expressed as a flag rather than by handing this function a credential with a doctored expires: callers persist whatever comes back, so a fabricated expiry that a provider echoes through would land in the credential store. See resolveOAuthApiKey in ./oauth.ts.

Mistral provider (La Plateforme).

Thin wrapper around openaiCompat with Mistral-specific defaults (base URL, default model, reasoning_effort planner). supportsReasoning stays off: Mistral carries thinking inside content chunks rather than a reasoning_content field, so there is nothing to echo back upstream — thinking streams to the UI and is dropped from subsequent requests.

Map zidane's thinking level to Mistral's reasoning_effort. Only the two documented values are emitted — 'none' (thinking chunk omitted, content stays a plain string) and 'high' (full thinking chunk). adaptive sends nothing so the model's own default applies.

Exported for tests.

Map zidane's thinking level to Z.ai's extra_body.thinking request shape. GLM has no depth knob — thinking is a binary switch — so any non-off level enables it and off explicitly disables it (GLM-5.x/4.7 think by default, so a silent omission would not turn thinking off).

Exported for tests.

Read the shared credentials file.

Returns {} when the file is missing OR when the file exists but is corrupted / not valid JSON. Corrupt-file tolerance is important: the refresh-then-persist path below writes atomically, but older builds wrote in place and could have truncated the file on a crash. Treating corruption as "no stored creds" lets users re-auth without manually deleting the file.

Supports two on-disk shapes:

1. Legacy (untagged): { "anthropic": { access, refresh, expires, ... } } — written by older bun run auth.
2. New (kind-tagged): { "anthropic": { kind: 'oauth', access, refresh, expires, ... } } — written by the TUI. Entries with kind: 'apikey' are skipped — those reach providers via env vars set at TUI launch (see applyApiKeyEnv).

Register a custom OAuth flow with the local registry (./oauth-registry) so lazy refresh through resolveOAuthApiKey can resolve providerId.

Public because provider extensions need it: without registration, getOAuthApiKey('<id>', …) throws Unknown OAuth provider the first time a stored token expires. Idempotent per id (the registry is a keyed map). Returns a promise for API stability.

Sanitize a single tool's inputSchema for safe forwarding to the provider. Returns the rewritten schema + a list of warnings describing everything that changed.

Never mutates the input. Returns the same reference when no rewrite was needed (clean-schema fast path) — sanitizeToolSpecs relies on this to keep the formatTools hot loop allocation-free across turns when the registered tool set is already wire-valid.

Convenience: sanitize a batch of tools and emit a single de-duped console.warn per unique warning line. Returns the rewritten tools preserving original ordering and reference identity for clean schemas (no reallocation when nothing needed to change).

The sanitiser runs every request. The de-dupe set is local to one call, so within a batch each warning line is logged once and the first occurrence is kept.

Final name guard: a tool whose name violates the provider constraint is DROPPED (not throwingly forwarded) with a one-time warning. An invalid name 400s the entire messages.create — taking every other tool and the turn down with it — so silently degrading one capability is the strictly safer failure mode. Upstream aliasing already coerces MCP names to valid wire names, so in practice this only fires for names that cannot be represented at all; it's defense-in-depth that keeps a malformed name in the list from reaching the wire.

Install (or clear, with null) the process-wide catalog. Latest call wins.

Prefer behavior.modelCatalog when you can: it needs no global state and scopes to one agent or one run. Use this for a deployment-wide correction, or when the host's model picker must see the override too.

Z.ai (Zhipu) GLM provider.

Thin wrapper around openaiCompat pinned to the reasoning_content round-trip mode: thinking arrives in the reasoning_content delta field and is echoed back on assistant messages under the same name, keeping GLM's interleaved/preserved thinking coherent across tool calls.

Provider-level capability flags used by the agent loop to route tool results and user messages appropriately.

Known providers should set these explicitly. For legacy compatibility, omitted vision is still treated permissively in some tool-result paths; newer media kinds (audio, video) and documents are opt-in and should be set to true before bytes are forwarded natively.

Provider-level metadata the agent core reads.

Every field the core consumes is declared here. The open Record<string, unknown> tail exists for provider-PRIVATE bookkeeping (a provider stashing something only it reads back) — core code must never reach into it through a structural cast, because a cast is an undeclared contract between two modules that no compiler checks.

A catalog: either a ModelCatalogSource or the table shorthand — a plain record keyed "<provider>:<modelId>".

The table form is a pure OVERLAY: entries patch or add models, and each provider keeps every bundled model the table doesn't name. Hiding bundled models requires the list function, so the easy path can't accidentally blank a provider's picker.

setModelCatalog({ 'openai:gpt-5.6': { maxTokens: 128000 } })

How to obtain the affinity key for a request.

• undefined / false — send nothing (default).
• 'session' — the request's session id; send nothing when it has none.
• true — the request's session id when it has one, otherwise a hash of the cacheable prefix via derivePromptCacheKey.
• any other string — use verbatim, for every request.
• function — compute per request; returning undefined omits the field for that request, so a host can key some traffic and not the rest.