@arnilo/prism 0.0.1

package/docs/provider-layer.md

@@ -0,0 +1,172 @@
+# Provider layer
+
+## What it does
+
+The provider layer contains the small runtime pieces Prism already ships for host-owned model access:
+
+- `createProviderRegistry()` / `ProviderRegistry`: register and resolve `AIProvider` instances by id.
+- `createModelRegistry()` / `ModelRegistry`: register and resolve `ModelConfig` values by provider/model key.
+- `ModelConfig` metadata fields for display names, capabilities, limits, cost/cache pricing, opaque provider compat data, and host metadata.
+- Provider event helpers: create normalized `ProviderEvent` values for text, thinking, tool calls, usage, done, and errors, including optional cache read/write usage fields.
+- `toolCallContent()`: create a `ToolCallContent` block.
+- `createMockProvider()` / `MockProviderOptions`: create a deterministic scripted `AIProvider` for tests and examples.
+- `@arnilo/prism/testing/provider-conformance`: optional network-free assertion helpers for provider adapter tests.
+
+These APIs are exported from the root `@arnilo/prism` package. `ProviderRegistry` and `ModelRegistry` are public runtime API types that live beside their factory implementations, not in the type-only `contracts.ts` file.
+
+## When to use it
+
+Use this layer when a host app, extension package, or test needs to:
+
+- Keep an explicit provider/model registry instead of hidden globals.
+- Fail closed before any provider call when a provider or model is unknown.
+- Emit provider events without hand-writing event objects.
+- Test agent/provider flows without timers, credentials, SDKs, or network calls.
+
+Do not use this layer for credential storage, settings loading, tool dispatch, agent loops, package discovery, cache stores, or provider SDK configuration. Those stay host-owned or belong to provider packages.
+
+## Inputs / request
+
+### Provider registry
+
+```ts
+createProviderRegistry(providers?: readonly AIProvider[]): ProviderRegistry
+```
+
+`ProviderRegistry` methods:
+
+| Method | Input | Result |
+| --- | --- | --- |
+| `register(provider)` | `AIProvider` | Stores provider by `provider.id`. |
+| `get(id)` | provider id string | Returns provider or `undefined`. |
+| `resolve(model)` | provider id string or `{ provider: string }` | Returns provider or throws `Unknown provider: <id>`. |
+| `list()` | none | Returns registered providers in insertion order. |
+
+### Model registry
+
+```ts
+createModelRegistry(models?: readonly ModelConfig[]): ModelRegistry
+```
+
+`ModelRegistry` methods:
+
+| Method | Input | Result |
+| --- | --- | --- |
+| `register(model)` | `ModelConfig` | Stores model by provider/model key, preserving inert metadata. |
+| `get(provider, model)` | provider id and model id | Returns model config or `undefined`. |
+| `resolve(provider, model)` | provider id and model id | Returns model config or throws `Unknown model: <provider>/<model>`. |
+| `list()` | none | Returns registered model configs in insertion order. |
+
+### Provider event helpers
+
+```ts
+providerTextDelta(text: string): ProviderEvent
+providerThinkingDelta(text: string, signature?: string): ProviderEvent
+providerContentDelta(content: ContentBlock): ProviderEvent
+providerToolCallDelta(delta: { index: number; id?: string; name?: string; argumentsText?: string }): ProviderEvent
+providerToolCall(call: ToolCallContent): ProviderEvent
+providerUsage(usage: Usage): ProviderEvent
+providerDone(usage?: Usage): ProviderEvent
+providerError(error: unknown, secrets?: readonly (string | undefined)[]): ProviderEvent
+toolCallContent(id: string, name: string, args?: JsonObject): ToolCallContent
+```
+
+### Mock provider
+
+```ts
+createMockProvider(events?: readonly ProviderEvent[], options?: MockProviderOptions): AIProvider
+```
+
+`MockProviderOptions`:
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `id` | `string` | Optional provider id. Defaults to `mock`. |
+| `onRequest` | `(request: ProviderRequest) => void` | Optional request observer for tests. |
+
+## Outputs / response / events
+
+- Registry `resolve()` returns the matching provider/model or throws before any provider `generate()` call.
+- Provider event helpers return plain `ProviderEvent` objects.
+- `providerError()` converts unknown errors to redacted `ErrorInfo` through `errorToErrorInfo()` and preserves safe string/number `code` fields for retry classification.
+- `createMockProvider()` returns an `AIProvider` whose `generate()` yields the scripted events in order and checks `request.signal?.aborted` before each event.
+- The agent/session runtime passes its per-run abort signal as `ProviderRequest.signal`.
+
+## Request/response example
+
+```json
+{
+  "provider": "mock",
+  "model": "demo"
+}
+```
+
+Example provider events:
+
+```json
+[
+  { "type": "content_delta", "content": { "type": "text", "text": "Hello" } },
+  { "type": "done" }
+]
+```
+
+## Implementation example
+
+```ts
+import {
+  createModelRegistry,
+  createMockProvider,
+  createProviderRegistry,
+  providerDone,
+  providerTextDelta,
+  providerToolCall,
+  toolCallContent,
+} from "@arnilo/prism";
+
+const provider = createMockProvider([
+  providerTextDelta("Hello"),
+  providerToolCall(toolCallContent("call_1", "lookup", { id: "1" })),
+  providerDone(),
+]);
+
+const providers = createProviderRegistry([provider]);
+const models = createModelRegistry([{ provider: "mock", model: "demo" }]);
+
+const resolvedProvider = providers.resolve("mock");
+const resolvedModel = models.resolve("mock", "demo");
+
+for await (const event of resolvedProvider.generate({
+  model: resolvedModel,
+  messages: [{ role: "user", content: [{ type: "text", text: "Hi" }] }],
+  options: { sessionId: "session-1", cacheRetention: "short" },
+})) {
+  console.log(event.type);
+}
+```
+
+## Extension and configuration notes
+
+- Registries are explicit objects returned by factories. Prism does not create a hidden global provider/model registry.
+- Extension packages can contribute `AIProvider` and `ModelConfig` values by registering them with host-owned registries.
+- Model resolution and provider resolution are separate on purpose: hosts can validate a model exists before selecting a provider.
+- Credential resolvers stay outside these registries; pass credentials directly to the provider adapter or runtime edge that needs them.
+- Mock provider is for deterministic tests/examples. Real providers should implement `AIProvider` directly or through adapter packages.
+
+## Security and performance notes
+
+- Provider/model registries are `Map`-backed and perform O(1) lookup.
+- Registries store providers and model metadata only. Do not store API keys, credential resolvers, headers, tokens, or secret-bearing settings in them.
+- Unknown provider/model resolution fails before provider execution or network I/O.
+- `createMockProvider()` uses scripted events only: no timers, credentials, SDKs, or network.
+- Do not hide real secrets in mock event fixtures. If an error event must include secret-like text, use fake placeholders and redaction helpers.
+- `providerError(error, secrets)` only redacts the provided secret values. It is not a general secret scanner.
+- Providers may set safe `ErrorInfo.code` values such as `429`, `503`, or `ETIMEDOUT`; retry policy code treats them as classification hints, not trusted provider metadata.
+
+## Related APIs
+
+- [Agent/session runtime](agent-session-runtime.md): passes abort signals to providers, maps provider errors to session `error` events, and can retry configured transient provider-turn failures before output.
+- [Provider packages](provider-packages.md): explicit package primitive for registering providers, models, auth descriptors, request/cache policies, and prompt contributions.
+- [Public contracts](public-contracts.md): `AIProvider`, `ProviderRequest`, `ProviderEvent`, `ModelConfig`, `Usage`, and content/tool-call contracts.
+- [Credentials and redaction](credentials-and-redaction.md): credential and redaction helpers used by provider adapters.
+- [OpenAI-compatible provider](providers/openai-compatible.md): optional provider adapter that emits these normalized provider events.
+- [Provider conformance](provider-conformance.md): reusable network-free provider adapter checks, including content-preservation canaries for text/thinking/tool-call/tool-result/image blocks and secret-leak assertions.

package/docs/provider-packages.md

@@ -0,0 +1,171 @@
+# Provider packages
+
+## What it does
+
+Provider package primitives let a host or extension register provider-related contributions explicitly:
+
+- `defineProviderPackage()`: validates and returns an inert provider package definition.
+- `ProviderPackage`: package metadata plus a `setup(api)` callback.
+- `ModelConfig` metadata: `displayName`, `capabilities`, `limits`, `cost`, opaque `compat`, and `metadata`.
+- New contribution registries and `ExtensionAPI` methods for provider packages, auth methods, provider request policies, and system prompt contributions.
+- Auth method descriptors for API-key, OAuth, and custom provider auth flows.
+
+These primitives do not load packages, discover manifests, read credentials, refresh OAuth tokens, or call providers.
+
+## When to use it
+
+Use provider packages when a host wants to bundle model metadata, provider adapters, auth descriptors, cache/request policies, or prompt contributions behind one explicit setup call.
+
+Do not use provider packages as a package manager, credential store, env loader, provider-specific cache implementation, or live integration runner.
+
+## Inputs / request
+
+```ts
+import { defineProviderPackage } from "@arnilo/prism";
+
+export default defineProviderPackage({
+  name: "demo-provider",
+  setup(api) {
+    api.registerProvider(provider);
+    api.registerModel({
+      provider: "demo",
+      model: "demo-large",
+      displayName: "Demo Large",
+      capabilities: { input: ["text"], reasoning: true, tools: true },
+      limits: { contextWindow: 128_000, maxOutputTokens: 8_192 },
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, currency: "USD" },
+      compat: { vendorSpecific: true },
+    });
+  },
+});
+```
+
+`compat` is provider-owned inert JSON. Core does not branch on provider names or interpret vendor-specific fields.
+
+Provider packages can also contribute auth descriptors and request policies without resolving credentials:
+
+```ts
+import { createSessionCachePolicy } from "@arnilo/prism";
+
+api.registerAuthMethod({ provider: "demo", kind: "api_key", credentialName: "apiKey" });
+api.registerAuthMethod({ provider: "demo", kind: "oauth", oauth: demoOAuthProvider });
+api.registerProviderRequestPolicy(createSessionCachePolicy({ retention: "short" }));
+api.registerSystemPromptContribution({ id: "demo-prompt", source: "package", mode: "append", text: "Use demo provider rules." });
+```
+
+Hosts decide which credential resolvers, env objects, OAuth stores, request policies, and prompt contributions become active. Request policies can set generic `ProviderRequest.options` such as `sessionId`, `cacheRetention`, `headers`, retry/timeouts, and opaque `extra`; provider adapters decide how to map those options to provider payloads.
+
+## First-party provider package skeletons
+
+Phase 12 adds explicit npm workspaces for [`@arnilo/prism-provider-openai`](providers/openai.md), [`@arnilo/prism-provider-opencode-go`](providers/opencode-go.md), [`@arnilo/prism-provider-openrouter`](providers/openrouter.md), [`@arnilo/prism-provider-zai`](providers/zai.md), and [`@arnilo/prism-provider-kimi`](providers/kimi.md). Each package starts with a side-effect-free `create*ProviderPackage()` export, README, TypeScript build, network-free default tests, and an env-gated live-test placeholder.
+
+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. `@arnilo/prism-provider-opencode-go` now registers static OpenCode Go metadata and package-local OpenAI/Anthropic-compatible routes from caller-supplied credentials only. `@arnilo/prism-provider-openrouter` now registers an app-controlled OpenRouter catalog with routing/reasoning/cache passthrough and no setup catalog fetch. `@arnilo/prism-provider-zai` now registers static GLM metadata with Z.AI thinking/reasoning/tool-stream request mapping. `@arnilo/prism-provider-kimi` now registers Kimi Coding Anthropic-compatible behavior by default and optional Moonshot metadata only when requested.
+
+## Outputs / response / events
+
+`defineProviderPackage()` returns the same package object or throws when `name` is blank. A package contributes only when a host passes it to an extension/kernel/setup flow and calls `setup()` explicitly.
+
+## Request/response example
+
+Provider package manifest contribution and the generic request options a provider request policy can set:
+
+```json
+{
+  "manifest": {
+    "name": "demo-provider-manifest",
+    "contributions": [
+      { "kind": "providerPackage", "name": "demo-provider" },
+      { "kind": "providerRequestPolicy", "name": "demo.cache" }
+    ]
+  },
+  "providerRequest.options": {
+    "sessionId": "sess_123",
+    "cacheKey": "demo",
+    "cacheRetention": "short",
+    "headers": { "x-demo": "1" }
+  }
+}
+```
+
+## Implementation example
+
+Wire a provider package with model metadata plus a session cache policy through the extension kernel:
+
+```ts
+import { createExtensionKernel, defineProviderPackage, createSessionCachePolicy } from "@arnilo/prism";
+
+const pkg = defineProviderPackage({
+  name: "demo-provider",
+  setup(api) {
+    api.registerProvider(/* host-owned AIProvider */ null as never);
+    api.registerModel({
+      provider: "demo",
+      model: "demo-large",
+      displayName: "Demo Large",
+      capabilities: { input: ["text"], reasoning: true, tools: true },
+      limits: { contextWindow: 128_000, maxOutputTokens: 8_192 },
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, currency: "USD" },
+      compat: { vendorSpecific: true },
+    });
+    api.registerProviderRequestPolicy(createSessionCachePolicy({ retention: "short" }));
+  },
+});
+
+const kernel = createExtensionKernel();
+await kernel.load([pkg]);
+```
+
+## Extension and configuration notes
+
+- Hosts decide which credential resolvers, env objects, OAuth stores, request
+  policies, and prompt contributions become active; the package only *declares*
+  them.
+- `createSessionCachePolicy()` acts as a concrete cache policy hook
+  (`provider_request`) that sets generic `ProviderRequest.options`
+  (`sessionId`, `cacheKey`, `cacheRetention`, `headers`, opaque `extra`) before
+  `AIProvider.generate()`; provider adapters map those options to provider payloads.
+- `ModelConfig.compat` is provider-owned inert JSON: cache policy overrides,
+  reasoning/thinking formats, and provider-specific usage mapping live there
+  rather than in core, so Prism never branches on provider names.
+- A package contributes auth methods and request policies without resolving
+  credentials; OAuth/api-key resolution runs only when the host wires the
+  matching credential resolver.
+- Packages can also be declared as inert manifest contributions and resolved
+  later through registries (see the Manifest declarations section below).
+
+## Security and performance notes
+
+- Keep resolved credential values out of `ModelConfig`, provider package metadata, docs metadata, auth method metadata, and registries.
+- Registration is in-memory only and does no filesystem, network, env, OAuth refresh, or command access.
+- Provider-specific behavior belongs in provider packages, not Prism core.
+- Adapter serializers should preserve Prism content blocks (text, thinking, tool_call, tool_result, and image when the model declares image input) in provider-native request shape, or fail explicitly when a block is unsupported.
+
+## Manifest declarations
+
+Provider packages, auth methods, provider request policies, and system prompt contributions can also be declared in data-only Prism manifests:
+
+```ts
+import { definePrismManifest } from "@arnilo/prism";
+
+export default definePrismManifest({
+  name: "demo-provider-manifest",
+  contributions: [
+    { kind: "providerPackage", name: "demo-provider" },
+    { kind: "authMethod", name: "demo.api-key", metadata: { credentialName: "apiKey" } },
+    { kind: "providerRequestPolicy", name: "demo.cache" },
+    { kind: "systemPromptContribution", name: "demo.prompt" },
+  ],
+});
+```
+
+Manifest declarations are inert. The host must later resolve them through registries or extension setup and make explicit trust decisions before activating any package, auth flow, request policy, or prompt contribution.
+
+## Related APIs
+
+- [Provider layer](provider-layer.md): provider/model registries and provider events.
+- [Provider conformance](provider-conformance.md): reusable network-free checks for provider adapters.
+- [Contribution registries](contribution-registries.md): registry bundle and extension contribution points.
+- [Configuration and manifests](configuration-and-manifests.md): data-only manifest `kind` values.
+- [System prompts](system-prompts.md): composing selected package/app/user/run prompt layers.
+- [Credentials and redaction](credentials-and-redaction.md): host-owned credential helpers.
+- [Public contracts](public-contracts.md): public type inventory.

package/docs/providers/kimi.md

@@ -0,0 +1,110 @@
+# Kimi provider package
+
+## What it does
+
+`@arnilo/prism-provider-kimi` provides explicit, side-effect-free setup for Kimi For
+Coding using an Anthropic-compatible `/messages` endpoint with
+`User-Agent: KimiCLI/1.5` (unless overridden). Moonshot/Open Platform model
+metadata is optional.
+
+The package registers the `kimi-coding` provider, default Kimi Coding model
+metadata, and an `api_key` auth method through `createExtensionKernel().load([...])`.
+
+## When to use it
+
+Use it when a host app wants the Kimi For Coding endpoint through Prism's
+`AgentSession` runtime with Kimi-specific serializer behavior.
+
+Do not use it for Moonshot Open Platform default registration, automatic
+credential discovery, catalog fetches, or real-network tests.
+
+## Inputs / request
+
+```ts
+import { createKimiProviderPackage } from "@arnilo/prism-provider-kimi";
+
+createKimiProviderPackage(options: KimiProviderPackageOptions): ProviderPackage
+defineKimiModel(config: KimiModelConfig): KimiModelConfig
+```
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `kimiApiKey` | `CredentialValueSource` | Direct/callback/resolver API-key source for Kimi. |
+| `fetch` | `typeof fetch` | Optional fetch implementation for tests/hosts. |
+| `baseUrl` | `string` | Overrides the Kimi base URL. |
+| `id` | `string` | Overrides the provider id (default `kimi-coding`). |
+| `userAgent` | `string` | Overrides `User-Agent: KimiCLI/1.5`. |
+| `models` | `readonly ModelConfig[]` | Overrides `kimiCodingModels` defaults. |
+| `includeMoonshotModels` | `boolean` | Registers Moonshot models when `true` (default off). |
+| `moonshotModels` | `readonly ModelConfig[]` | Overrides `moonshotKimiModels` when included. |
+
+## Outputs / response / events
+
+| Surface | Behavior |
+| --- | --- |
+| Provider stream | Prism text, thinking (preserved only when `model.compat.preserveThinking` is true, otherwise downgraded to text), tool-call delta/final, `usage`, `done`, redacted `error`. |
+| Block preservation | Text, thinking, assistant `tool_call` → `tool_use`, `tool_result` → `tool_result`, images when `capabilities.input` includes `"image"`. |
+| Auth method | `api_key` for `kimi-coding`, credential name `apiKey`. |
+
+Unsupported block placements or unclaimed images fail before fetch.
+
+## Request/response example
+
+Example request (Anthropic-compatible `/messages` shape):
+
+```json
+{
+  "model": "kimi-latest",
+  "messages": [{ "role": "user", "content": "Hello" }],
+  "stream": true
+}
+```
+
+## Implementation example
+
+```ts
+import { createExtensionKernel } from "@arnilo/prism";
+import { createKimiProviderPackage } from "@arnilo/prism-provider-kimi";
+
+const kernel = createExtensionKernel();
+await kernel.load([
+  createKimiProviderPackage({ kimiApiKey: "fake-kimi-key", includeMoonshotModels: false }),
+]);
+```
+
+Register Moonshot/Open Platform metadata explicitly:
+
+```ts
+import { createKimiProviderPackage } from "@arnilo/prism-provider-kimi";
+
+await kernel.load([
+  createKimiProviderPackage({ kimiApiKey: "fake", includeMoonshotModels: true }),
+]);
+```
+
+## Extension and configuration notes
+
+- Hosts choose base URL, provider id, `User-Agent`, model list, credential source,
+  and `fetch` impl.
+- Moonshot/Open Platform metadata is registered only with
+  `includeMoonshotModels: true`; it is not core behavior.
+- Package contributes models via the extension `api` and an `api_key` auth method.
+
+## Security and performance notes
+
+- No network calls during import, setup, build, or default tests.
+- No automatic environment, file, keychain, or shell credential lookup.
+- Kimi credentials are resolved per request from caller-supplied values or resolvers
+  and redacted from errors.
+- Live tests stay opt-in behind `PRISM_LIVE_PROVIDER_TESTS=1` plus fake-safe
+  provider-specific env names; default tests are network-free.
+
+## Related APIs
+
+- [Provider packages](../provider-packages.md): `defineProviderPackage`,
+  `ModelConfig`/`compat`, Anthropic-compatible routes.
+- [Credentials and redaction](../credentials-and-redaction.md):
+  `resolveCredentialValue`, `redactSecrets`.
+- [Provider layer](../provider-layer.md): `ProviderRequest.options` and usage
+  mapping.
+- [Provider conformance](../provider-conformance.md): network-free adapter tests.

package/docs/providers/openai-compatible.md

@@ -0,0 +1,125 @@
+# OpenAI-compatible provider
+
+## What it does
+
+`@arnilo/prism/providers/openai-compatible` exports `createOpenAICompatibleProvider()` and `OpenAICompatibleProviderOptions`.
+
+The adapter implements `AIProvider` for OpenAI-compatible Chat Completions streaming APIs using native or injected `fetch`. It maps streaming Server-Sent Events into Prism `ProviderEvent` values for text, thinking, tool-call fragments, final tool calls, usage, done, and errors.
+
+It has no provider SDK dependency.
+
+## When to use it
+
+Use this adapter when a host app or extension package wants to connect a Prism provider to an OpenAI-compatible `/chat/completions` endpoint.
+
+Do not use it for the OpenAI Responses API, provider-specific non-streaming APIs, automatic credential discovery, or real-network tests. Inject `fetch` in tests.
+
+## Inputs / request
+
+Import from the subpath:
+
+```ts
+import { createOpenAICompatibleProvider } from "@arnilo/prism/providers/openai-compatible";
+```
+
+Options:
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `id` | `string` | Optional provider id. Defaults to `openai-compatible`. |
+| `baseUrl` | `string` | Base API URL; `/chat/completions` is appended. |
+| `apiKey` | `CredentialValueSource` | Optional direct/callback/resolver credential source. |
+| `fetch` | `typeof fetch` | Optional fetch implementation for tests or custom hosts. |
+
+Provider requests use the standard `ProviderRequest` shape: `model`, `messages`, optional `tools`, `metadata`, and `signal`.
+
+## Outputs / response / events
+
+The returned provider emits normalized `ProviderEvent` values:
+
+| Stream input | Prism output |
+| --- | --- |
+| `delta.content` | `content_delta` with text content. |
+| `delta.reasoning_content` | `content_delta` with thinking content. |
+| streamed `tool_calls` fragments | `tool_call_delta` events. |
+| complete accumulated tool call | final `tool_call` event. |
+| `usage` | `usage` event. |
+| `[DONE]` or stream end | `done` event. |
+| HTTP/stream/parsing error | `error` event with redacted `ErrorInfo`. |
+
+The adapter passes `request.signal` to `fetch` for abort propagation.
+
+## Request/response example
+
+Example request body sent to an OpenAI-compatible endpoint:
+
+```json
+{
+  "model": "demo-model",
+  "messages": [
+    { "role": "user", "content": "Hello" }
+  ],
+  "stream": true,
+  "stream_options": { "include_usage": true }
+}
+```
+
+Example Prism events:
+
+```json
+[
+  { "type": "content_delta", "content": { "type": "text", "text": "Hel" } },
+  { "type": "content_delta", "content": { "type": "text", "text": "lo" } },
+  { "type": "done" }
+]
+```
+
+## Implementation example
+
+```ts
+import { createOpenAICompatibleProvider } from "@arnilo/prism/providers/openai-compatible";
+
+const provider = createOpenAICompatibleProvider({
+  baseUrl: "https://api.openai.com/v1",
+  apiKey: () => process.env.OPENAI_API_KEY,
+});
+
+for await (const event of provider.generate({
+  model: { provider: provider.id, model: "demo-model" },
+  messages: [{ role: "user", content: [{ type: "text", text: "Hello" }] }],
+})) {
+  console.log(event.type);
+}
+```
+
+Test with injected fetch, not the network:
+
+```ts
+const provider = createOpenAICompatibleProvider({
+  baseUrl: "https://example.test/v1",
+  fetch: async () => new Response("data: [DONE]\\n\\n", { status: 200 }),
+});
+```
+
+## Extension and configuration notes
+
+- Extension packages can create this provider and register it with a host-owned provider registry.
+- Hosts choose the provider id, base URL, model configs, credential source, and fetch implementation.
+- The adapter resolves `apiKey` per request through `resolveCredentialValue()`.
+- This adapter currently targets Chat Completions streaming only.
+- The serializer preserves text, thinking (downgraded to text), assistant `tool_call` blocks as `tool_calls`, `tool_result` blocks as role `tool` messages, and image blocks when the model declares `capabilities.input` includes `"image"`. Unsupported block placements or unclaimed images fail before fetch.
+
+## Security and performance notes
+
+- Credentials are host-owned and resolved only when `generate()` runs.
+- Resolved API keys are used for the HTTP `Authorization` header and passed to error redaction; they are not stored in registries or events.
+- Redaction only removes known values supplied to the helper. Avoid logging raw provider requests/responses.
+- `fetch` receives the request `AbortSignal`.
+- Tests should use injected `fetch` and never make real network calls.
+- Tool-call arguments are accumulated as streamed text, parsed as JSON only when the final tool call is emitted, and default to `{}` for empty argument text.
+
+## Related APIs
+
+- [Provider layer](../provider-layer.md): registries, provider events, tool-call helpers, and mock provider.
+- [Credentials and redaction](../credentials-and-redaction.md): `resolveCredentialValue()`, `CredentialValueSource`, `redactSecrets()`, and `errorToErrorInfo()`.
+- [Public contracts](../public-contracts.md): `AIProvider`, `ProviderRequest`, `ProviderEvent`, `ToolDefinition`, `ToolCallContent`, and `Usage`.