@arnilo/prism 0.2.8 → 0.2.9

package/docs/provider-packages.md

@@ -23,6 +23,9 @@ Do not use provider packages as a package manager, credential store, env loader,
 | Package | 0.0.12 auth registration | Subscription OAuth boundary |
 | --- | --- | --- |
 | `@arnilo/prism-provider-openai` | `api_key` for `openai`; `oauth` for `openai-codex` | Existing host-invoked OpenAI Codex PKCE/device-code flow only. |
+| `@arnilo/prism-provider-xai` | `api_key` and `oauth` for `xai` | Host-invoked SuperGrok / X Premium RFC 8628 device-code against `auth.x.ai`. Public Grok CLI client id is not a secret. No PKCE loopback, no `~/.grok` import, no `cli-chat-proxy.grok.com`. |
+| `@arnilo/prism-provider-deepseek` | `api_key` only | No subscription OAuth. |
+| `@arnilo/prism-provider-clinepass` | `api_key` only | No Cline WorkOS / Cline OAuth store share. Host supplies `CLINE_API_KEY`. |
 | `@arnilo/prism-provider-anthropic` | `api_key` only | No Claude Code/Claude.ai subscription OAuth, credential-file/setup-token import, or routing. [Anthropic requires product developers to use API keys or supported cloud providers](https://docs.anthropic.com/en/docs/claude-code/legal-and-compliance). |
 | `@arnilo/prism-provider-google` | `api_key` only | No Gemini CLI OAuth or credential/token import. [Gemini CLI prohibits third-party OAuth piggybacking](https://github.com/google-gemini/gemini-cli/blob/main/docs/resources/tos-privacy.md); use Google AI Studio API keys. Vertex/ADC uses separate [`@arnilo/prism-provider-vertex`](providers/vertex.md). |
 | `@arnilo/prism-provider-azure` | host Entra token or Azure resource key | Workload identity via `credential` callback; endpoint host preserved ([docs](providers/azure.md)). |
@@ -70,7 +73,7 @@ Hosts decide which credential resolvers, env objects, OAuth stores, request poli
 
 Provider request options: `ProviderRequestOptions` carries session/cache/header/compat/extra hints only. Timeouts are host-owned (`RunOptions.signal`/host abort controllers); retries are runtime-owned (`AgentConfig.retry`/`RunOptions.retry`). Provider-level timeout/retry hints were removed in 0.1.5. Provider packages should not add provider-specific retry loops unless the vendor protocol requires it and runtime retry cannot cover the failure mode.
 
-First-party providers map generic `ModelConfig.parameters.maxTokens` to real output-token request fields instead of sending `maxTokens` on the wire: OpenAI Responses uses `max_output_tokens`; OpenRouter, OpenCode Go OpenAI-compatible, OpenCode Go Anthropic-style, Z.AI, Kimi, and NeuralWatt use `max_tokens`. Other `model.parameters` values pass through unchanged unless the provider docs say otherwise.
+First-party providers map generic `ModelConfig.parameters.maxTokens` to real output-token request fields instead of sending `maxTokens` on the wire: OpenAI Responses uses `max_output_tokens`; ClinePass uses `max_completion_tokens`; OpenRouter, OpenCode Go, Z.AI, Kimi, NeuralWatt, DeepSeek, and xAI use `max_tokens`. Other `model.parameters` values pass through unchanged unless the provider docs say otherwise.
 
 ## First-party provider package skeletons
 
@@ -80,9 +83,9 @@ Phase 12 adds explicit npm workspaces for [`@arnilo/prism-provider-openai`](prov
 
 Phase 6 also adds optional [`@arnilo/prism-provider-ai-sdk`](providers/ai-sdk.md), which adapts a host-owned AI SDK `LanguageModelV4` to Prism's `AIProvider`. It joins `@arnilo/prism-providers` as the seventh adapter while remaining independent from the six HTTP implementations.
 
-Provider live tests are real smoke tests gated by `PRISM_LIVE_PROVIDER_TESTS=1` plus the provider-specific API key (`OPENAI_API_KEY`, `OPENROUTER_API_KEY`, `KIMI_API_KEY`, `ZAI_API_KEY`, `NEURALWATT_API_KEY`, or `OPENCODE_API_KEY`). They cover text generation, tool-call loop behavior, abort/error paths where supported, and no-secret-leak assertions; they skip by default and never run in release verification.
+Provider live tests are real smoke tests gated by `PRISM_LIVE_PROVIDER_TESTS=1` plus the provider-specific API key (`OPENAI_API_KEY`, `OPENROUTER_API_KEY`, `KIMI_API_KEY`, `ZAI_API_KEY`, `NEURALWATT_API_KEY`, `OPENCODE_API_KEY`, `DEEPSEEK_API_KEY`, `XAI_API_KEY`, or `CLINE_API_KEY`). They cover text generation, tool-call loop behavior, abort/error paths where supported, and no-secret-leak assertions; they skip by default and never run in release verification. SuperGrok login is operator-only (`PRISM_LIVE_XAI_OAUTH=1`).
 
-These workspaces still follow the same rule as external packages: no provider SDK dependency, catalog fetch, env scan, keychain/file credential lookup, shell auth command, OAuth login, or live provider call runs by default. `@arnilo/prism-provider-openai` now registers OpenAI Responses and OpenAI Codex providers from caller-supplied credentials only, with optional `models`/`codexModels` overrides and an opt-in `listOpenAIModels()` helper for official `GET /models` discovery. `@arnilo/prism-provider-opencode-go` now registers docs-verified OpenCode Go open coding models with dual OpenAI/Anthropic routes (`compat.route`), official default base `https://opencode.ai/zen/go/v1`, `reasoning_content`/thinking preserve, and an opt-in `listOpenCodeGoModels()` helper for official `GET /zen/go/v1/models`. `@arnilo/prism-provider-openrouter` now registers an app-controlled OpenRouter catalog with routing/`reasoning`/cache passthrough, assistant `reasoning` replay, optional top-level automatic `cache_control`, and an opt-in `listOpenRouterModels()` helper for official `GET /api/v1/models` (setup still never fetches). `@arnilo/prism-provider-zai` now registers featured GLM-5.x/4.x metadata with official `thinking`/`reasoning_effort`/`tool_stream`/`clear_thinking` mapping, Preserved Thinking `reasoning_content` replay, implicit context caching, and an opt-in `listZaiModels()` helper for OpenAI-compatible `GET /models`. `@arnilo/prism-provider-kimi` now registers Kimi Coding Anthropic-compatible behavior by default, optional callable Moonshot Open Platform Chat Completions when `includeMoonshotModels` is requested, official Coding/Open Platform featured ids, thinking/`reasoning_effort` compat mapping, and an opt-in `listKimiModels()` helper for Moonshot `GET /v1/models`. `@arnilo/prism-provider-neuralwatt` now registers static featured model metadata with NeuralWatt reasoning_effort/thinking_token_budget/chat_template_kwargs request mapping, SSE comment tolerance, an opt-in `listNeuralWattModels()` helper for explicit `/v1/models` discovery, `getNeuralWattQuota()` for on-demand account balance/usage/energy, `neuralWattEventsWithTelemetry()`/`mapNeuralWattTelemetry()` for `: energy`/`: cost` telemetry, and `classifyNeuralWattError()` for retry classification. None of these helpers run during package setup or generation. `@arnilo/prism-provider-anthropic` registers native Anthropic Messages (`createAnthropicProviderPackage` / `listAnthropicModels`). `@arnilo/prism-provider-google` registers native Gemini `generateContent` streaming (`createGoogleProviderPackage` / `listGoogleModels`; Vertex identity stays in the separate package). Both follow the same zero-setup-network / host-owned credential / provider-owned-header rules; see [`docs/providers/anthropic.md`](providers/anthropic.md) and [`docs/providers/google.md`](providers/google.md).
+These workspaces still follow the same rule as external packages: no provider SDK dependency, catalog fetch, env scan, keychain/file credential lookup, shell auth command, OAuth login, or live provider call runs by default. `@arnilo/prism-provider-openai` now registers OpenAI Responses and OpenAI Codex providers from caller-supplied credentials only, with optional `models`/`codexModels` overrides and an opt-in `listOpenAIModels()` helper for official `GET /models` discovery. `@arnilo/prism-provider-opencode-go` now registers docs-verified OpenCode Go open coding models with dual OpenAI/Anthropic routes (`compat.route`), official default base `https://opencode.ai/zen/go/v1`, `reasoning_content`/thinking preserve, and an opt-in `listOpenCodeGoModels()` helper for official `GET /zen/go/v1/models`. `@arnilo/prism-provider-openrouter` now registers an app-controlled OpenRouter catalog with routing/`reasoning`/cache passthrough, assistant `reasoning` replay, optional top-level automatic `cache_control`, and an opt-in `listOpenRouterModels()` helper for official `GET /api/v1/models` (setup still never fetches). `@arnilo/prism-provider-zai` now registers featured GLM-5.x/4.x metadata with official `thinking`/`reasoning_effort`/`tool_stream`/`clear_thinking` mapping, Preserved Thinking `reasoning_content` replay, implicit context caching, and an opt-in `listZaiModels()` helper for OpenAI-compatible `GET /models`. `@arnilo/prism-provider-kimi` now registers Kimi Coding Anthropic-compatible behavior by default, optional callable Moonshot Open Platform Chat Completions when `includeMoonshotModels` is requested, official Coding/Open Platform featured ids, thinking/`reasoning_effort` compat mapping, and an opt-in `listKimiModels()` helper for Moonshot `GET /v1/models`. `@arnilo/prism-provider-neuralwatt` now registers static featured model metadata with NeuralWatt reasoning_effort/thinking_token_budget/chat_template_kwargs request mapping, SSE comment tolerance, an opt-in `listNeuralWattModels()` helper for explicit `/v1/models` discovery, `getNeuralWattQuota()` for on-demand account balance/usage/energy, `neuralWattEventsWithTelemetry()`/`mapNeuralWattTelemetry()` for `: energy`/`: cost` telemetry, and `classifyNeuralWattError()` for retry classification. None of these helpers run during package setup or generation. `@arnilo/prism-provider-deepseek` registers featured `deepseek-v4-flash` / `deepseek-v4-pro` with official `thinking` / `reasoning_effort`, tool-turn `reasoning_content` replay, implicit prefix cache, and caller-gated `listDeepSeekModels`. `@arnilo/prism-provider-xai` registers featured Completions (`grok-4.6` / `grok-4.3` / `grok-build-0.1`), `x-grok-conv-id`, `reasoning_content` replay, caller-gated `listXaiModels`, and host-invoked SuperGrok device-code OAuth against `auth.x.ai`. `@arnilo/prism-provider-clinepass` registers a static `cline-pass/*` catalog, stream-only Chat Completions, per-model `reasoning_effort` maps, and `api_key` only (no WorkOS, no `listClinePassModels`). `@arnilo/prism-provider-anthropic` registers native Anthropic Messages (`createAnthropicProviderPackage` / `listAnthropicModels`). `@arnilo/prism-provider-google` registers native Gemini `generateContent` streaming (`createGoogleProviderPackage` / `listGoogleModels`; Vertex identity stays in the separate package). Both follow the same zero-setup-network / host-owned credential / provider-owned-header rules; see [`docs/providers/anthropic.md`](providers/anthropic.md) and [`docs/providers/google.md`](providers/google.md).
 
 ### Phase 10 compatibility matrix
 
@@ -101,13 +104,16 @@ Every package remains explicit, setup-zero-fetch, and late-credential-bound. `Mo
 | Alibaba | DashScope OpenAI-compatible; caller-gated list | text, image | tool deltas, Qwen thinking | implicit / optional markers; protected host probe |
 | Ollama | Cloud/local OpenAI-compatible; caller-gated list | text, image | tool deltas, reasoning effort | implicit only; protected host/daemon probe |
 | NeuralWatt | OpenAI-compatible; caller-gated list | text, image | tool deltas, reasoning and telemetry | implicit; protected API-key smoke |
+| DeepSeek | OpenAI-compatible; caller-gated list | text | tool deltas, `reasoning_content` on tool turns | implicit; protected API-key smoke |
+| xAI | OpenAI-compatible Completions; caller-gated list | text, image | tool deltas, `reasoning_content` replay | implicit + `x-grok-conv-id`; protected API-key smoke; SuperGrok login operator-only |
+| ClinePass | OpenAI-compatible stream-only; static `cline-pass/*` catalog | text | tool deltas, per-model `reasoning_effort` | implicit; protected API-key smoke |
 | Azure | Azure/Foundry OpenAI-compatible; host models | selected endpoint/model capability | normalized OpenAI-compatible tools | no Prism cache mapping; protected host workload-identity probe |
 | Bedrock | Bedrock OpenAI-compatible; host models | selected endpoint/model capability | normalized OpenAI-compatible tools | no Prism cache mapping; protected host IAM/IRSA probe |
 | Vertex | Vertex OpenAPI-compatible; host models | selected endpoint/model capability | normalized OpenAI-compatible tools | no Prism cache mapping; protected host ADC/WIF probe |
 
 ### First-party cache behavior
 
-Every first-party provider package hardens prompt-cache behavior so it cannot emit invalid cache retention values or over-broad cache-control markers, and so provider-owned `authorization`/session/security headers cannot be overridden by caller `ProviderRequest.options.headers`. Cache behavior is provider-specific and best-effort: OpenAI/OpenRouter use explicit hints, NeuralWatt/Z.AI use implicit caching, and OpenCode Go/Kimi are route/model-dependent. See [Provider caching](provider-caching.md#per-provider-cache-behavior) for the canonical explicit/implicit matrix.
+Every first-party provider package hardens prompt-cache behavior so it cannot emit invalid cache retention values or over-broad cache-control markers, and so provider-owned `authorization`/session/security headers cannot be overridden by caller `ProviderRequest.options.headers`. Cache behavior is provider-specific and best-effort: OpenAI/OpenRouter use explicit hints, NeuralWatt/Z.AI/DeepSeek/ClinePass use implicit caching, xAI adds a sanitized `x-grok-conv-id`, and OpenCode Go/Kimi are route/model-dependent. See [Provider caching](provider-caching.md#per-provider-cache-behavior) for the canonical explicit/implicit matrix.
 
 - **OpenAI** (`kind: openai_key`): `prompt_cache_key` is sanitized and clamped to 64 chars; `prompt_cache_retention` is emitted as `24h` only when the model declares `cache.longRetention`, and omitted for `short`/`none` (the API only accepts absent or `24h`). `prompt_tokens_details.cached_tokens` maps to `Usage.cacheReadTokens`.
 - **OpenAI-compatible core adapter**: Chat Completions sends no `prompt_cache_key`/`prompt_cache_retention`/`cache_control` fields; endpoints cache implicitly. `prompt_tokens_details.cached_tokens` maps to `Usage.cacheReadTokens`.
@@ -118,6 +124,9 @@ Every first-party provider package hardens prompt-cache behavior so it cannot em
 - **Kimi**: default catalog models use implicit caching (no `cache_control`); hosts opt in via `ModelConfig.cache.kind: cache_control` on the Anthropic `/messages` route, then markers apply only to selected breakpoints (`long` → `ttl: 1h`); the Moonshot OpenAI route sends none. `cache_read_input_tokens`/`cache_creation_input_tokens` map to cache usage.
 - **Alibaba Cloud** (implicit by default, optional `cache_control`): DashScope implicit prefix caching is automatic; hosts opt in via `ModelConfig.cache.kind: cache_control`, then `cache_control: {"type":"ephemeral"}` markers apply only to selected breakpoints, capped at 4. `prompt_tokens_details.cached_tokens`/`cache_creation_input_tokens` map to cache usage. Caller-gated `listAlibabaModels`.
 - **Ollama** (`kind: implicit`): Ollama KV/prefix caching is automatic with no request knob; sends no explicit cache payload. Ollama reports no cached-token count, so `Usage.cacheReadTokens` stays `undefined`. Caller-gated `listOllamaModels`.
+- **DeepSeek** (`kind: implicit`): official prefix cache; no cache payload. Tool schemas canonicalized. `prompt_cache_hit_tokens` → `cacheReadTokens`. Caller-gated `listDeepSeekModels`.
+- **xAI** (`kind: implicit`): prefix cache plus sanitized `x-grok-conv-id` (never a SuperGrok token). Replay `reasoning_content` on reasoning models. `cached_tokens` → `cacheReadTokens`. Caller-gated `listXaiModels`.
+- **ClinePass** (`kind: implicit`): no cache payload; stream-only. `cached_tokens` / `prompt_cache_hit_tokens` map when present. Static `cline-pass/*` catalog.
 
 See [Provider caching](provider-caching.md) for the `PromptCacheHints` surface and shared helpers, and [Provider conformance](provider-conformance.md) for the `assertUsageAccounting` and `assertProviderOwnedHeadersWin` checks every first-party package exercises.
 
@@ -162,6 +171,9 @@ Template: [`listNeuralWattModels`](providers/neuralwatt.md) in `@arnilo/prism-pr
 | OpenCode Go | **`listOpenCodeGoModels`** (official `GET /zen/go/v1/models`) | Featured dual-route official Go aliases | Official Go docs endpoint table + sparse list API |
 | NeuralWatt | **`listNeuralWattModels` (exists)** | Featured aliases without guessed pricing | Auth optional for public models |
 | AI SDK | None | Host-owned `LanguageModelV4` | No Prism-side catalog by design |
+| DeepSeek | **`listDeepSeekModels`** (OpenAI-compatible `GET /models`) | Featured `deepseek-v4-flash` / `deepseek-v4-pro` | Official Completions catalog |
+| xAI | **`listXaiModels`** (OpenAI-compatible `GET /models`) | Featured Completions (`grok-4.6` / `grok-4.3` / `grok-build-0.1`) | `grok-4.5` / Responses deferred |
+| ClinePass | None | Static official `cline-pass/*` slugs | No documented `GET /models` |
 
 Host pattern:
 
@@ -176,7 +188,7 @@ Discovery may populate `ModelConfig.cache` and `ModelConfig.cost` from live meta
 
 Hosts set effort with portable helpers from `@arnilo/prism` (`applyThinkingLevel`, `thinkingCompatFor`) that write official fields into `ProviderRequestOptions.compat`. Model defaults stay on `ModelConfig.compat`; per-turn patches win via `mergeProviderRequestOptions`. Providers keep reading `options.compat` / `model.compat` — do not invent a parallel options tree or put effort only in `extra`.
 
-Canonical contract: [Thinking and reasoning](thinking-and-reasoning.md). Package-local knobs (NeuralWatt budgets, Z.AI `tool_stream`, Kimi keep/all) remain on `compat` beside the shared families.
+Canonical contract: [Thinking and reasoning](thinking-and-reasoning.md). Package-local knobs (NeuralWatt budgets, Z.AI `tool_stream`, Kimi keep/all, ClinePass `thinkingLevelMap`, DeepSeek tool-turn `reasoning_content` replay, xAI reasoning replay) remain on `compat` beside the shared families.
 
 ## Third-party provider packaging
 
@@ -186,7 +198,8 @@ provider packages: an `Extension` whose `setup(api)` calls
 provider packages (`@arnilo/prism-provider-openai`, `@arnilo/prism-provider-openrouter`,
 `@arnilo/prism-provider-kimi`, `@arnilo/prism-provider-zai`,
 `@arnilo/prism-provider-opencode-go`, `@arnilo/prism-provider-alibaba`,
-`@arnilo/prism-provider-ollama`) are **opt-in and individually installable**;
+`@arnilo/prism-provider-ollama`, `@arnilo/prism-provider-deepseek`,
+`@arnilo/prism-provider-xai`, `@arnilo/prism-provider-clinepass`) are **opt-in and individually installable**;
 `@arnilo/prism` core runs without any first-party provider package (mock-only).
 
 A host mixes first-party packages and third-party providers in one resolver.

package/docs/providers/clinepass.md

@@ -0,0 +1,120 @@
+# ClinePass provider package
+
+## What it does
+
+`@arnilo/prism-provider-clinepass` provides explicit, side-effect-free setup for
+the ClinePass OpenAI-compatible Chat Completions API at
+`https://api.cline.bot/api/v1`. Requests always stream. Model ids are official
+`cline-pass/…` slugs from a static featured catalog.
+
+## When to use it
+
+Use it when a host has a ClinePass subscription key (`CLINE_API_KEY`) and wants
+those open coding models through Prism `AgentSession`.
+
+Do not use it for Cline WorkOS OAuth, Claude/Gemini subscription routing,
+non-stream `{ data, success }` responses ([cline#12647](https://github.com/cline/cline/issues/12647)),
+or caller-gated `GET /models` (no documented OpenAI models endpoint).
+
+## Inputs / request
+
+```ts
+import { createClinePassProviderPackage } from "@arnilo/prism-provider-clinepass";
+
+createClinePassProviderPackage(options: ClinePassProviderPackageOptions): ProviderPackage
+```
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `apiKey` | `CredentialValueSource` | Host-supplied ClinePass key. No env scan. |
+| `fetch` | `typeof fetch` | Optional fetch for tests/hosts. |
+| `baseUrl` | `string` | Default `https://api.cline.bot/api/v1`. |
+| `id` | `string` | Provider id (default `clinepass`). |
+| `models` | `readonly ModelConfig[]` | Overrides static `clinePassModels`. |
+
+There is no `listClinePassModels`.
+
+### Thinking / reasoning compat
+
+Per-model `compat.thinkingLevelMap` maps portable levels to wire
+`reasoning_effort`. Request `options.compat.reasoning_effort` (or
+`applyThinkingLevel(..., "reasoning_effort")`) wins.
+
+| Family | slugs | map |
+| --- | --- | --- |
+| GLM | `cline-pass/glm-5.2` | `off→none`, `low/medium/high`, `xhigh` passthrough. Do not send `max` (upstream 500). |
+| Kimi K3 | `cline-pass/kimi-k3` | `high→max` only. Off/low/medium omitted. |
+| Kimi | `kimi-k2.7-code`, `kimi-k2.6` | `low/medium/high`. Off omitted. |
+| DeepSeek | `deepseek-v4-pro`, `deepseek-v4-flash` | `off→none`, `high`/`xhigh→high`. |
+| Standard | MiMo, MiniMax, Qwen | `off→none`, `low/medium/high`. |
+
+Completion budget is `max_completion_tokens` (not `max_tokens`).
+
+## Outputs / response / events
+
+| Surface | Behavior |
+| --- | --- |
+| Provider stream | Prism text, thinking (`delta.reasoning` / `delta.reasoning_content`), tool-call, `usage`, `done`, redacted `error`. |
+| Cache | Implicit upstream. `cached_tokens` / `prompt_cache_hit_tokens` → `cacheReadTokens` when present. No `cache_control`. |
+| Auth | `api_key` only. |
+| Non-stream | Unsupported. `{ success, data }` wrappers are not parsed. |
+
+## Request/response example
+
+```json
+{
+  "model": "cline-pass/deepseek-v4-flash",
+  "messages": [{ "role": "user", "content": "Hello" }],
+  "stream": true,
+  "reasoning_effort": "high"
+}
+```
+
+## Implementation example
+
+```ts
+import { createExtensionKernel } from "@arnilo/prism";
+import { createClinePassProviderPackage } from "@arnilo/prism-provider-clinepass";
+
+const kernel = createExtensionKernel();
+await kernel.load([createClinePassProviderPackage({ apiKey: "fake-cline-key" })]);
+```
+
+Per-turn effort:
+
+```ts
+await session.prompt("Plan the refactor", {
+  providerOptions: { compat: { reasoning_effort: "low" } },
+});
+```
+
+## Extension and configuration notes
+
+- Featured slugs: `glm-5.2`, `kimi-k3`, `kimi-k2.7-code`, `kimi-k2.6`,
+  `deepseek-v4-pro`, `deepseek-v4-flash`, `mimo-v2.5`, `mimo-v2.5-pro`,
+  `minimax-m3`, `qwen3.8-max`, `qwen3.7-max`, `qwen3.7-plus` (all prefixed
+  `cline-pass/`).
+- Catalog is static. Hosts may pass `models` to override.
+- Multi-backend gateway: key compat off `api.cline.bot`, not the upstream vendor.
+- Reference USD-per-million costs are catalog metadata; ClinePass itself is a subscription.
+
+## Security and performance notes
+
+- No network on import, setup, build, or default tests.
+- No WorkOS, no Cline OAuth store share, no env/file lookup.
+- API keys resolved per request and redacted from errors.
+- Provider-owned headers win. One POST per generate. Bounded error bodies.
+- Live tests: `PRISM_LIVE_PROVIDER_TESTS=1` plus `CLINE_API_KEY`.
+
+## Related APIs
+
+- [Provider packages](../provider-packages.md)
+- [Thinking and reasoning](../thinking-and-reasoning.md)
+- [Provider caching](../provider-caching.md)
+- [Credentials and redaction](../credentials-and-redaction.md)
+- [Provider conformance](../provider-conformance.md)
+
+## Official evidence
+
+- [ClinePass](https://docs.cline.bot/getting-started/clinepass)
+- [Non-stream wrap](https://github.com/cline/cline/issues/12647)

package/docs/providers/deepseek.md

@@ -0,0 +1,147 @@
+# DeepSeek provider package
+
+## What it does
+
+`@arnilo/prism-provider-deepseek` provides explicit, side-effect-free setup for the
+DeepSeek Chat Completions API (`POST /chat/completions`) with official thinking
+mode, reasoning-effort mapping, tool-turn `reasoning_content` replay, and
+implicit prefix caching.
+
+The package registers a provider, featured V4 model metadata, and an `api_key`
+auth method through `createExtensionKernel().load([...])`.
+
+## When to use it
+
+Use it when a host app wants DeepSeek V4 Flash / Pro through Prism's
+`AgentSession` runtime with official `thinking` / `reasoning_effort` mapping
+and automatic KV prefix cache.
+
+Do not use it for the Anthropic-compatible route, automatic credential
+discovery, setup-time catalog fetches, or real-network tests.
+
+## Inputs / request
+
+```ts
+import {
+  createDeepSeekProviderPackage,
+  defineDeepSeekModel,
+  listDeepSeekModels,
+} from "@arnilo/prism-provider-deepseek";
+
+createDeepSeekProviderPackage(options: DeepSeekProviderPackageOptions): ProviderPackage
+defineDeepSeekModel(config: DeepSeekModelConfig): ModelConfig
+listDeepSeekModels(options?: ListDeepSeekModelsOptions): Promise<ModelConfig[]>
+```
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `apiKey` | `CredentialValueSource` | Direct/callback/resolver API-key source. |
+| `fetch` | `typeof fetch` | Optional fetch implementation for tests/hosts. |
+| `baseUrl` | `string` | Overrides the DeepSeek base URL (default `https://api.deepseek.com`). |
+| `id` | `string` | Overrides the provider id (default `deepseek`). |
+| `models` | `readonly ModelConfig[]` | Overrides featured `deepseekModels` defaults. |
+
+### Thinking / reasoning compat
+
+Official body fields (request `options.compat` wins over `model.compat`):
+
+| Compat / body field | Wire shape | Notes |
+| --- | --- | --- |
+| `thinking` | `boolean` or `{ type: "enabled" \| "disabled" }` | Default **enabled**. Boolean `true`/`false` maps to those types. |
+| `reasoning_effort` | `low` \| `high` \| `max` | Default `high`. Portable `medium` and `xhigh` map to `high`. Omitted when thinking is disabled. |
+
+`applyThinkingLevel(..., "thinking_type")` toggles `thinking.type`. Set
+`reasoning_effort` in `compat` for effort. `ProviderRequestOptions.cacheRetention: "none"`
+forces `thinking: { type: "disabled" }`.
+
+Thinking mode ignores `temperature`, `top_p`, `presence_penalty`, and
+`frequency_penalty`; this adapter strips them so they cannot break the cache prefix.
+
+## Outputs / response / events
+
+| Surface | Behavior |
+| --- | --- |
+| Provider stream | Prism text, thinking (`delta.reasoning_content`), tool-call delta/final, `usage`, `done`, redacted `error`. |
+| Block preservation | Text; thinking → `reasoning_content` on tool-turn assistants (otherwise dropped, never flattened into text); assistant `tool_call` → `tool_calls`; `tool_result` → role `tool`. |
+| Auth method | `api_key` for the configured provider id, credential name `apiKey`. |
+| Usage | `prompt_cache_hit_tokens` → `Usage.cacheReadTokens` via `mapOpenAIChatUsage`. |
+
+Unsupported media blocks fail before fetch. Text-only input.
+
+## Request/response example
+
+```json
+{
+  "model": "deepseek-v4-flash",
+  "messages": [{ "role": "user", "content": "Hello" }],
+  "stream": true,
+  "thinking": { "type": "enabled" },
+  "reasoning_effort": "high"
+}
+```
+
+## Implementation example
+
+```ts
+import { createExtensionKernel } from "@arnilo/prism";
+import { createDeepSeekProviderPackage, listDeepSeekModels } from "@arnilo/prism-provider-deepseek";
+
+const kernel = createExtensionKernel();
+await kernel.load([createDeepSeekProviderPackage({ apiKey: "fake-deepseek-key" })]);
+
+const live = await listDeepSeekModels({ apiKey: "fake-deepseek-key" });
+await kernel.load([createDeepSeekProviderPackage({ apiKey: "fake-deepseek-key", models: live })]);
+```
+
+Per-turn thinking override:
+
+```ts
+await session.prompt("Plan the refactor", {
+  providerOptions: {
+    compat: {
+      thinking: { type: "enabled" },
+      reasoning_effort: "low",
+    },
+  },
+});
+```
+
+## Extension and configuration notes
+
+- Default base URL is `https://api.deepseek.com`. The Anthropic-compatible
+  route is not implemented.
+- Featured `deepseekModels` are offline bootstrap aliases (`deepseek-v4-flash`,
+  `deepseek-v4-pro`) with 1M context / 384k max output, `cache.kind: "implicit"`,
+  and documented USD-per-million cost including cache-read.
+- `listDeepSeekModels()` is caller-gated `GET {base}/models`. Setup never fetches.
+- Tool JSON Schema keys (`properties` / `required`) are sorted before send so the
+  implicit prefix stays stable.
+- Tool-turn assistants must replay `reasoning_content` or the API returns 400.
+  Non-tool multi-turn may omit it (the API ignores it).
+
+## Security and performance notes
+
+- SSE streams and HTTP error bodies use bounded transport helpers.
+- No network calls during import, setup, build, or default tests.
+- No automatic environment, file, keychain, or shell credential lookup.
+- API keys are resolved per request and redacted from errors (including discovery).
+- Provider-owned headers (`content-type`, `authorization`) win over caller headers.
+- One POST per generate. No provider retry loop.
+- Live tests stay opt-in behind `PRISM_LIVE_PROVIDER_TESTS=1` plus `DEEPSEEK_API_KEY`.
+
+## Related APIs
+
+- [Provider packages](../provider-packages.md): `defineProviderPackage`,
+  caller-gated discovery, per-turn thinking.
+- [Thinking and reasoning](../thinking-and-reasoning.md): portable
+  `applyThinkingLevel` → DeepSeek `thinking.type` / `reasoning_effort`.
+- [Credentials and redaction](../credentials-and-redaction.md):
+  `resolveCredentialValue`, `redactSecrets`.
+- [Provider caching](../provider-caching.md): implicit DeepSeek prefix cache.
+- [Provider conformance](../provider-conformance.md): network-free adapter tests.
+
+## Official evidence
+
+- [Thinking Mode](https://api-docs.deepseek.com/guides/thinking_mode)
+- [KV Cache](https://api-docs.deepseek.com/guides/kv_cache)
+- [Create Chat Completion](https://api-docs.deepseek.com/api/create-chat-completion)

package/docs/providers/openai.md

@@ -54,7 +54,7 @@ uses official Responses `reasoning: { effort, summary? }` via
 | Continuation | An incomplete Responses stream self-resumes at most eight HTTP hops using opaque `previous_response_id`; a cursor is at most 4 KiB, is never replayed, and is observable as `continuation_required`. |
 | Realtime | `createOpenAIRealtimeSession()` exposes server-session creation, audio in/out, transcript deltas, provider-hosted calls, interrupt, and idempotent close through the neutral `RealtimeSession` seam. |
 | Block preservation | User/system text → `input_text`; assistant text → `output_text`; assistant host `tool_call` → top-level `function_call` with `call_id`; provider-hosted calls are not replayed; `tool_result` → top-level `function_call_output`; images/files/audio when declared on the model. Bare thinking without an encrypted Responses reasoning item is omitted on replay. |
-| Auth methods | `api_key` for `openai`; host-invoked subscription `oauth` for `openai-codex`. This is Prism's only first-party subscription OAuth flow in 0.0.12. |
+| Auth methods | `api_key` for `openai`; host-invoked subscription `oauth` for `openai-codex`. xAI SuperGrok is the other first-party subscription OAuth flow ([xAI](xai.md)). |
 
 Unsupported block placements or unclaimed images fail before `fetch`. Provider-hosted calls are telemetry only: Prism never dispatches them as host tools or sends a `tool_result`.
 

package/docs/providers/xai.md

@@ -0,0 +1,138 @@
+# xAI provider package
+
+## What it does
+
+`@arnilo/prism-provider-xai` provides explicit, side-effect-free setup for the
+xAI Grok Chat Completions API (`POST https://api.x.ai/v1/chat/completions`)
+with implicit prefix caching via a sanitized `x-grok-conv-id` header, reasoning
+replay, and host-invoked SuperGrok / X Premium OAuth.
+
+The package registers a provider, featured Completions models, an `api_key`
+auth method, and an `oauth` auth method (`createXaiOAuthProvider`, id `xai`).
+
+## When to use it
+
+Use it when a host wants Grok 4.6 / 4.3 / Build through Prism with either an
+xAI API key or a SuperGrok / X Premium subscription login.
+
+Do not use it for Responses-only `grok-4.5`, PKCE loopback, `cli-chat-proxy.grok.com`,
+`~/.grok` credential import, or setup-time catalog fetches.
+
+## Inputs / request
+
+```ts
+import {
+  createXaiOAuthProvider,
+  createXaiProviderPackage,
+  listXaiModels,
+} from "@arnilo/prism-provider-xai";
+
+createXaiProviderPackage(options: XaiProviderPackageOptions): ProviderPackage
+createXaiOAuthProvider(options?: XaiOAuthOptions): OAuthProvider
+listXaiModels(options?: ListXaiModelsOptions): Promise<ModelConfig[]>
+```
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `apiKey` | `CredentialValueSource` | API key **or** SuperGrok access token (host wires after `login` / `refreshOAuthCredential`). |
+| `fetch` | `typeof fetch` | Optional fetch for tests/hosts. |
+| `baseUrl` | `string` | Default `https://api.x.ai/v1`. |
+| `id` | `string` | Provider id (default `xai`). |
+| `models` | `readonly ModelConfig[]` | Overrides featured `xaiModels`. |
+| `oauth` | `XaiOAuthOptions` | Optional client id / endpoints / referrer overrides. |
+
+### Cache header
+
+`x-grok-conv-id` is `sanitizeCacheKey(cache.key ?? cacheKey ?? sessionId, 128)`.
+Omitted when `cache.mode` is `off`, `cacheRetention` is `none`, or the key sanitizes empty.
+
+### SuperGrok OAuth
+
+RFC 8628 device-code. Default public client id
+`b1a00492-073a-47ea-816f-4c329264a828` is **not a secret**. Scope
+`openid profile email offline_access grok-cli:access api:access`. Referrer
+default `prism`. Endpoints: `https://auth.x.ai/oauth2/device/code`,
+`/token`, `/revoke`. Form-urlencoded bodies. `verification_uri` /
+`verification_uri_complete` must be `https:`. Refresh keeps the previous
+`refresh_token` when omitted and applies a 5-minute expiry skew. Revoke is
+best-effort; `revokeOAuthCredential` still deletes the local store.
+
+No PKCE loopback. Login requires `onDeviceCode`. Setup never logs in.
+
+## Outputs / response / events
+
+| Surface | Behavior |
+| --- | --- |
+| Provider stream | Prism text, thinking (`delta.reasoning_content` / `delta.reasoning`), tool-call, `usage`, `done`, redacted `error`. |
+| Cache usage | `prompt_tokens_details.cached_tokens` → `cacheReadTokens`. If `cached_tokens > prompt_tokens` (exclusive report), values are kept as-is; unused input is not invented. |
+| Auth | `api_key` and `oauth` (`getCredential` → `{ type: "bearer", value: access }`). |
+| Images | Allowed when `capabilities.input` includes `image`. Rejected otherwise. |
+
+## Request/response example
+
+```json
+{
+  "model": "grok-4.6",
+  "messages": [{ "role": "user", "content": "Hello" }],
+  "stream": true
+}
+```
+
+Header: `x-grok-conv-id: sess-1`.
+
+## Implementation example
+
+```ts
+import { createExtensionKernel, refreshOAuthCredential } from "@arnilo/prism";
+import { createXaiOAuthProvider, createXaiProviderPackage } from "@arnilo/prism-provider-xai";
+
+const kernel = createExtensionKernel();
+await kernel.load([createXaiProviderPackage({ apiKey: "fake-xai-key" })]);
+
+const oauth = createXaiOAuthProvider();
+const creds = await oauth.login({
+  onDeviceCode: ({ userCode, verificationUri }) => {
+    console.log(`Open ${verificationUri} and enter ${userCode}`);
+  },
+});
+await store.set("xai", creds);
+
+await kernel.load([
+  createXaiProviderPackage({
+    apiKey: async () => {
+      const current = await store.get("xai");
+      return (await refreshOAuthCredential({ provider: oauth, credentials: current, store })).access;
+    },
+  }),
+]);
+```
+
+## Extension and configuration notes
+
+- Featured Completions: `grok-4.6` (500k), `grok-4.3` (1M), `grok-build-0.1` (256k). All image + reasoning, `cache.kind: "implicit"`.
+- `grok-4.5` / Responses API is not implemented.
+- `listXaiModels()` is caller-gated `GET {base}/models`. Setup never fetches.
+- Reasoning models replay `reasoning_content` and do not flatten thinking into text.
+- Generate always hits `https://api.x.ai/v1/chat/completions` (same backend for API key and SuperGrok access).
+
+## Security and performance notes
+
+- Public client id is documented as not a secret. Device/user/access/refresh codes are redacted.
+- HTTPS verification URI only. No PKCE loopback. No `~/.grok/**` or env scan.
+- Provider-owned headers (`authorization`, `content-type`) win. Conv-id is never a credential.
+- Bounded OAuth and API error bodies. No retry loop. No refresh timer.
+- Live API-key smoke: `PRISM_LIVE_PROVIDER_TESTS=1` + `XAI_API_KEY`. SuperGrok login is operator-only (`PRISM_LIVE_XAI_OAUTH=1`).
+
+## Related APIs
+
+- [Provider packages](../provider-packages.md): OAuth support matrix.
+- [Credentials and redaction](../credentials-and-redaction.md): SuperGrok is authorized; Claude/Gemini are not.
+- [Credential storage](../credential-storage.md): host-owned store after explicit `login`.
+- [Provider caching](../provider-caching.md): implicit xAI prefix cache + conv-id.
+- [Thinking and reasoning](../thinking-and-reasoning.md): xAI reasoning replay.
+- [OpenAI Codex](openai.md): the other first-party subscription OAuth flow.
+
+## Official evidence
+
+- [Prompt caching](https://docs.x.ai/developers/advanced-api-usage/prompt-caching)
+- [OIDC discovery](https://auth.x.ai/.well-known/openid-configuration)