@arnilo/prism 0.0.1

package/docs/providers/openai.md

@@ -0,0 +1,131 @@
+# OpenAI provider package
+
+## What it does
+
+`@arnilo/prism-provider-openai` provides explicit, side-effect-free setup for the OpenAI
+Responses API (`createOpenAIResponsesProvider`) and OpenAI Codex
+subscription Responses (`createOpenAICodexProvider`), plus a Codex OAuth provider
+implementing RFC 7636 PKCE browser/device-code login.
+
+The package registers providers, model metadata, and `api_key` / `oauth` auth
+methods through `createExtensionKernel().load([...])` — no
+hidden globals, no automatic provider/model resolution.
+
+## When to use it
+
+Use it when a host app wants OpenAI Responses or Codex-backed runs through
+Prism's `AgentSession` runtime, or needs a Codex OAuth login flow (ChatGPT
+Plus/Pro/Codex subscription).
+
+Do not use it for Chat Completions-only endpoints (use
+[`@arnilo/prism/providers/openai-compatible`](openai-compatible.md) instead), automatic
+credential discovery, or real-network tests.
+
+## Inputs / request
+
+```ts
+import { createOpenAIProviderPackage } from "@arnilo/prism-provider-openai";
+
+createOpenAIProviderPackage(options: OpenAIProviderPackageOptions): ProviderPackage
+```
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `apiKey` | `CredentialValueSource` | Direct/callback/resolver source for the Responses API key. |
+| `codexAccessToken` | `CredentialValueSource` | Access token for the Codex subscription backend. |
+| `fetch` | `typeof fetch` | Optional fetch implementation for tests/hosts. |
+| `baseUrl` | `string` | Overrides `https://api.openai.com/v1`. |
+| `codexBaseUrl` | `string` | Overrides `https://chatgpt.com/backend-api/codex`. |
+
+`ProviderRequest.options.sessionId`, `cacheKey`, `cacheRetention`, `headers`,
+`compat`, and `extra` map to request headers/payload fields.
+
+## Outputs / response / events
+
+| Surface | Behavior |
+| --- | --- |
+| Provider stream | Prism text, thinking (downgraded to text), `tool_call` deltas/finals, `usage`, `done`, redacted `error` events. |
+| Block preservation | Text, thinking (downgraded), assistant `tool_call` → `function_call` input items, `tool_result` → `function_call_output` input items, images when `capabilities.input` includes `"image"`. |
+| Auth methods | `api_key` for `openai`; `oauth` for `openai-codex`. |
+
+Unsupported block placements or unclaimed images fail before `fetch`.
+
+## Request/response example
+
+Responses request body (Codex subscription shape, abbreviated):
+
+```json
+{
+  "model": "gpt-5-codex",
+  "instructions": "You are a coding agent.",
+  "input": [{ "type": "message", "role": "user", "content": [{ "type": "input_text", "text": "Hello" }] }],
+  "stream": true
+}
+```
+
+OAuth authorize URL (PKCE, `S256`):
+
+```
+https://auth.openai.com/authorize?response_type=code&client_id=...&code_challenge=<base64url(SHA-256(verifier))>&code_challenge_method=S256&redirect_uri=<redirect>&scope=<scope>
+```
+
+## Implementation example
+
+```ts
+import { createExtensionKernel, createEnvCredentialResolver } from "@arnilo/prism";
+import { createOpenAIProviderPackage } from "@arnilo/prism-provider-openai";
+
+const kernel = createExtensionKernel();
+await kernel.load([
+  createOpenAIProviderPackage({
+    apiKey: createEnvCredentialResolver({ OPENAI_API_KEY: "fake" }, { openai: "OPENAI_API_KEY" }),
+  }),
+]);
+```
+
+OAuth login (caller-supplied callbacks, mocked in tests):
+
+```ts
+import { createOpenAICodexOAuthProvider, createPkceVerifier, computeS256Challenge } from "@arnilo/prism-provider-openai";
+
+const oauth = createOpenAICodexOAuthProvider({
+  redirectUri: "http://localhost:1455/auth/callback",
+  scope: "openai.chatgpt",
+  // callbacks supplied/brand-owned
+});
+const verifier = createPkceVerifier();
+const challenge = computeS256Challenge(verifier);
+```
+
+## Extension and configuration notes
+
+- `createOpenAIProviderPackage` wires the API-key Responses backend and the Codex
+  OAuth backend separately via `baseUrl` and `codexBaseUrl`; a Codex OAuth access
+  token never silently hits the plain `/v1` endpoint.
+- `OpenAICodexOAuthOptions.redirectUri` and `scope` are forwarded to the authorize
+  URL; `scope` is also sent on the device-code POST body when supplied.
+- Hosts/apps control model selection, credential resolution, and cache policy per
+  run/model through `RunOptions` and `ModelConfig.compat`.
+- OAuth browser/device-code flows run only when the caller explicitly invokes the
+  OAuth provider.
+
+## Security and performance notes
+
+- No network calls during import, setup, build, or default tests.
+- No automatic environment, file, keychain, or shell credential lookup; Prism never
+  reads `process.env` on its own.
+- API keys/access tokens are resolved per request from caller-supplied values or
+  resolvers; OAuth errors redact known token values (`[REDACTED]`).
+- The PKCE verifier is exchanged at the token endpoint, never sent on the authorize
+  URL.
+- Live tests stay opt-in behind `PRISM_LIVE_PROVIDER_TESTS=1` plus fake-safe
+  provider-specific env names; default `npm test` is network-free.
+
+## Related APIs
+
+- [Provider packages](../provider-packages.md): `defineProviderPackage`, auth
+  methods, request/cache policies, model compat metadata.
+- [Credentials and redaction](../credentials-and-redaction.md):
+  `createEnvCredentialResolver`, `resolveCredentialValue`, `redactSecrets`.
+- [OpenAI-compatible provider](openai-compatible.md): Chat Completions-only adapter.
+- [Provider conformance](../provider-conformance.md): network-free adapter tests.

package/docs/providers/opencode-go.md

@@ -0,0 +1,103 @@
+# OpenCode Go provider package
+
+## What it does
+
+`@arnilo/prism-provider-opencode-go` provides explicit, side-effect-free setup for the
+OpenCode Go API-key provider using Prism model metadata and
+OpenAI-compatible/Anthropic-compatible routes with `x-opencode-session`
+cache/session headers.
+
+The package registers a provider, default model metadata, and an `api_key` auth
+method through `createExtensionKernel().load([...])`.
+
+## When to use it
+
+Use it when a host app wants to run an OpenAI-compatible or Anthropic-compatible
+OpenCode Go endpoint through Prism's `AgentSession` runtime with per-request
+session/cache headers.
+
+Do not use it for automatic credential discovery, catalog fetches, or
+real-network tests.
+
+## Inputs / request
+
+```ts
+import { createOpenCodeGoProviderPackage } from "@arnilo/prism-provider-opencode-go";
+
+createOpenCodeGoProviderPackage(options: OpenCodeGoProviderPackageOptions): ProviderPackage
+```
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `apiKey` | `CredentialValueSource` | Direct/callback/resolver API-key source. |
+| `fetch` | `typeof fetch` | Optional fetch implementation for tests/hosts. |
+| `baseUrl` | `string` | Overrides the OpenCode Go base URL. |
+| `models` | `readonly ModelConfig[]` | Overrides `openCodeGoModels` defaults. |
+
+`ProviderRequest.options.sessionId` maps to the `x-opencode-session` header;
+`cacheKey`/`cacheRetention` map to OpenCode cache retention.
+
+## Outputs / response / events
+
+| Surface | Behavior |
+| --- | --- |
+| Provider stream | Prism text, thinking, tool-call delta/final, `usage`, `done`, redacted `error`. |
+| Session/cache | `x-opencode-session` and cache headers added before `generate()`. |
+| Auth method | `api_key` for `opencode-go`, credential name `apiKey`. |
+
+## Request/response example
+
+Example headers added before fetch:
+
+```json
+{
+  "Authorization": "Bearer <resolved-key>",
+  "x-opencode-session": "<ProviderRequest.options.sessionId>"
+}
+```
+
+## Implementation example
+
+```ts
+import { createExtensionKernel } from "@arnilo/prism";
+import { createOpenCodeGoProviderPackage } from "@arnilo/prism-provider-opencode-go";
+
+const kernel = createExtensionKernel();
+await kernel.load([createOpenCodeGoProviderPackage({ apiKey: "fake-opencode-key" })]);
+```
+
+Override model metadata:
+
+```ts
+import { createOpenCodeGoProviderPackage, openCodeGoModels } from "@arnilo/prism-provider-opencode-go";
+
+await kernel.load([
+  createOpenCodeGoProviderPackage({ apiKey: "fake", models: openCodeGoModels }),
+]);
+```
+
+## Extension and configuration notes
+
+- Hosts choose base URL, model list, credential source, and `fetch` impl.
+- The serializer is inherited from the OpenAI-compatible route; Anthropic-compatible
+  routes preserve `tool_use`/`tool_result` blocks.
+- 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.
+- API keys 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`, request/cache policies.
+- [Credentials and redaction](../credentials-and-redaction.md):
+  `resolveCredentialValue`, `redactSecrets`.
+- [OpenAI-compatible provider](openai-compatible.md): underlying Chat Completions
+  adapter.
+- [Provider conformance](../provider-conformance.md): network-free adapter tests.

package/docs/providers/openrouter.md

@@ -0,0 +1,105 @@
+# OpenRouter provider package
+
+## What it does
+
+`@arnilo/prism-provider-openrouter` provides explicit, side-effect-free setup for the
+OpenRouter API-key provider with app-controlled model catalog and per-model cache
+policy/routing overrides.
+
+The package registers a provider, caller-supplied model metadata, and an
+`api_key` auth method through `createExtensionKernel().load([...])`. Apps control the model catalog instead of
+accepting a fetched or hard-coded one.
+
+## When to use it
+
+Use it when a host app wants OpenRouter routing passthrough, reasoning controls,
+and per-model cache policy through Prism's `AgentSession` runtime, and needs to
+override cache behavior per model rather than accept a single hard-coded policy.
+
+Do not use it for catalog fetches, automatic credential discovery, or
+real-network tests.
+
+## Inputs / request
+
+```ts
+import { createOpenRouterProviderPackage, defineOpenRouterModel } from "@arnilo/prism-provider-openrouter";
+
+createOpenRouterProviderPackage(options: OpenRouterProviderPackageOptions): ProviderPackage
+defineOpenRouterModel(config: OpenRouterModelConfig): OpenRouterModelConfig
+```
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `apiKey` | `CredentialValueSource` | Direct/callback/resolver API-key source. |
+| `fetch` | `typeof fetch` | Optional fetch implementation for tests/hosts. |
+| `baseUrl` | `string` | Overrides the OpenRouter base URL. |
+| `appUrl` | `string` | App URL for attribution `HTTP-Referer` header. |
+| `appTitle` | `string` | App title for the `X-Title` attribution header. |
+| `models` | `readonly ModelConfig[]` | App-supplied model catalog (no default fetch). |
+
+`OpenRouterModelConfig.compat.openRouterRouting` controls routing order,
+`data_collection`, reasoning, and per-model cache policy overrides.
+
+## Outputs / response / events
+
+| Surface | Behavior |
+| --- | --- |
+| Provider stream | Prism text, thinking, tool-call delta/final, `usage` (with cache read/write mapped), `done`, redacted `error`. |
+| Attribution | `HTTP-Referer`/`X-Title` headers sent only when `appUrl`/`appTitle` are supplied. |
+| Auth method | `api_key` for `openrouter`, credential name `apiKey`. |
+
+## Request/response example
+
+Per-model routing override:
+
+```json
+{
+  "model": "anthropic/claude-sonnet-4",
+  "routing": { "order": ["anthropic"], "data_collection": "deny" }
+}
+```
+
+## Implementation example
+
+```ts
+import { createExtensionKernel } from "@arnilo/prism";
+import { createOpenRouterProviderPackage, defineOpenRouterModel } from "@arnilo/prism-provider-openrouter";
+
+const sonnet = defineOpenRouterModel({
+  model: "anthropic/claude-sonnet-4",
+  compat: { openRouterRouting: { order: ["anthropic"], data_collection: "deny" } },
+});
+
+const kernel = createExtensionKernel();
+await kernel.load([
+  createOpenRouterProviderPackage({ apiKey: "fake-openrouter-key", models: [sonnet] }),
+]);
+```
+
+## Extension and configuration notes
+
+- Apps supply the model catalog via `models`; no catalog is fetched during setup.
+- `defineOpenRouterModel` lets apps override cache policy and routing per model.
+- Hosts choose base URL, attribution, credential source, and `fetch` impl.
+- Package contributes models and an `api_key` auth method.
+
+## Security and performance notes
+
+- No catalog fetch during setup; no automatic environment, file, keychain, or shell
+  credential lookup.
+- API keys are resolved per request from caller-supplied values or resolvers and
+  redacted from errors.
+- Attribution headers are sent only when `appUrl`/`appTitle` are supplied — no
+  hidden app identity.
+- 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`, cache policy, request policies.
+- [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/zai.md

@@ -0,0 +1,108 @@
+# ZAI provider package
+
+## What it does
+
+`@arnilo/prism-provider-zai` provides explicit, side-effect-free setup for the ZAI GLM
+API-key provider using Prism's OpenAI-compatible route with the
+`thinkingFormat: "zai"` model-compat setting, developer-role fallback, and
+GLM tool-stream quirks.
+
+The package registers a provider, default model metadata, and an `api_key` auth
+method through `createExtensionKernel().load([...])`.
+
+## When to use it
+
+Use it when a host app wants to run the ZAI GLM endpoint through Prism's
+`AgentSession` runtime with ZAI-specific thinking/tool-stream handling.
+
+Do not use it for automatic credential discovery, catalog fetches, or
+real-network tests.
+
+## Inputs / request
+
+```ts
+import { createZaiProviderPackage } from "@arnilo/prism-provider-zai";
+
+createZaiProviderPackage(options: ZaiProviderPackageOptions): ProviderPackage
+defineZaiModel(config: ZaiModelConfig): ZaiModelConfig
+```
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `apiKey` | `CredentialValueSource` | Direct/callback/resolver API-key source. |
+| `fetch` | `typeof fetch` | Optional fetch implementation for tests/hosts. |
+| `baseUrl` | `string` | Overrides the ZAI base URL. |
+| `id` | `string` | Overrides the provider id (default `zai`). |
+| `models` | `readonly ModelConfig[]` | Overrides `zaiModels` defaults. |
+
+`ModelConfig.compat.thinkingFormat: "zai"` enables ZAI thinking handling;
+`developerRoleFallback` controls developer-role fallback.
+
+## 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_calls`, `tool_result` → role `tool` messages, images when `capabilities.input` includes `"image"`. |
+| Auth method | `api_key` for the configured provider id, credential name `apiKey`. |
+
+Unsupported block placements or unclaimed images fail before fetch.
+
+## Request/response example
+
+Example request body (OpenAI-compatible Chat Completions shape):
+
+```json
+{
+  "model": "glm-4.6",
+  "messages": [{ "role": "user", "content": "Hello" }],
+  "stream": true
+}
+```
+
+## Implementation example
+
+```ts
+import { createExtensionKernel } from "@arnilo/prism";
+import { createZaiProviderPackage } from "@arnilo/prism-provider-zai";
+
+const kernel = createExtensionKernel();
+await kernel.load([createZaiProviderPackage({ apiKey: "fake-zai-key" })]);
+```
+
+Override the provider id and models:
+
+```ts
+import { createZaiProviderPackage, defineZaiModel, zaiModels } from "@arnilo/prism-provider-zai";
+
+await kernel.load([
+  createZaiProviderPackage({ id: "zai", apiKey: "fake", models: zaiModels }),
+]);
+```
+
+## Extension and configuration notes
+
+- Hosts choose base URL, provider id, model list, credential source, and `fetch`
+  impl.
+- `defineZaiModel` lets apps set ZAI-specific `compat` (thinking format, developer
+  fallback).
+- 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.
+- API keys 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`, thinking formats.
+- [Credentials and redaction](../credentials-and-redaction.md):
+  `resolveCredentialValue`, `redactSecrets`.
+- [OpenAI-compatible provider](openai-compatible.md): underlying Chat Completions
+  adapter.
+- [Provider conformance](../provider-conformance.md): network-free adapter tests.