@inkdropapp/ai 0.1.3 → 0.1.5

package/README.md

@@ -12,6 +12,7 @@ in the Inkdrop Electron main process.
 - **URL-keyed credential storage** via `@napi-rs/keyring`. Two endpoints to the same provider get separate keyring entries automatically.
 - **Single streaming event type** — every provider's stream is reduced to a `StreamEvent` discriminated union.
 - **Retry-aware error type** — `RateLimitExceeded` / `ServerOverloaded` carry `retryAfter` (seconds) parsed from the response header.
+- **Per-call observability** — opt-in `apiCallListener` receives a structured event per upstream HTTP request (URL, sanitized headers, body, status, duration). Designed to back a user-facing API invocation log.
 - **No tools, no agents, no UI, no persistence in v0.1** — see [Out of scope](#out-of-scope-deferred).
 
 ---
@@ -100,9 +101,9 @@ Inkdrop's AI features map onto two slots:
 
 A slot resolves to `(provider, model)` via:
 
-1. Explicit binding from `settings.slots[slot]`, if both the provider id and model id resolve. *(Advanced — pin a specific model per slot or mix providers across slots.)*
+1. Explicit binding from `settings.slots[slot]`, if both the provider id and model id resolve. _(Advanced — pin a specific model per slot or mix providers across slots.)_
 2. For `'fast'` only: fall back to `settings.slots.default` if that resolves.
-3. Preferred provider from `settings.providerId`, if configured — takes its `defaultModel()` (for `default`) or `defaultFastModel()` (for `fast`). *(The simple UI knob — one provider dropdown drives every slot.)*
+3. Preferred provider from `settings.providerId`, if configured — takes its `defaultModel()` (for `default`) or `defaultFastModel()` (for `fast`). _(The simple UI knob — one provider dropdown drives every slot.)_
 4. First **authenticated** registered provider in alphabetical id order, taking its `defaultModel()` / `defaultFastModel()`.
 5. `undefined` if no provider can satisfy the slot.
 
@@ -232,6 +233,61 @@ Three contracts you can rely on:
 The library is currently text-only — `tool-call` / `tool-result` variants are
 typed for forward compat but never produced.
 
+### API call logging
+
+Pass `apiCallListener` to `AIRegistry` to receive one event per upstream HTTP
+request. Useful for backing a user-facing "API invocation log" view, or for
+ad-hoc debugging in development.
+
+```ts
+import { AIRegistry, type AIModelApiCallEvent } from '@inkdropapp/ai'
+
+const registry = new AIRegistry({
+  settings,
+  apiCallListener: (event: AIModelApiCallEvent) => {
+    const status = event.status ?? `failed: ${event.failure}`
+    console.log(
+      `[${event.providerId}] ${event.request.method} ${event.request.url}`,
+      `→ ${status} (${event.durationMs}ms)`
+    )
+    if (event.errorBody) console.error(event.errorBody)
+  }
+})
+```
+
+The listener fires exactly once per HTTP request, after response headers
+arrive (or after the fetch itself fails). For streaming responses, `durationMs`
+is time-to-first-byte — the response stream is _not_ tee'd. Only error bodies
+(`status >= 400`) are captured. API keys are redacted from `request.headers`
+before the event is emitted.
+
+The hook is best-effort logging only: exceptions thrown from the listener are
+swallowed so they cannot interrupt the request path.
+
+Event shape:
+
+```ts
+type AIModelApiCallEvent = {
+  providerId: string
+  startedAt: number // epoch ms
+  durationMs: number // headers received (TTFB for streams)
+  request: {
+    method: string
+    url: string
+    headers: Record<string, string> // authorization / x-api-key redacted
+    body: unknown // parsed JSON when possible, else string
+  }
+  status: number | undefined // undefined when fetch itself threw
+  errorBody?: string // populated only when status >= 400
+  failure?: string // populated only when fetch itself threw
+}
+```
+
+**Gap to be aware of:** mid-stream errors (e.g. Anthropic's `event: error`
+frames inside a `200 OK` SSE body) are surfaced via the `StreamEvent` union
+(`{ kind: 'error' }`), _not_ through the API call listener. The listener only
+sees what the HTTP layer sees.
+
 ### Errors
 
 `AIError` is the base class. Variants:
@@ -274,8 +330,9 @@ hosts that want to predict the name (e.g. for an onboarding hint).
 ```ts
 new AIRegistry({
   settings: AISettings,
-  catalog?: AIModelCatalog,   // server-distributed model lists; see "Model catalogues"
-  keyStore?: KeyStore
+  catalog?: AIModelCatalog,           // server-distributed model lists; see "Model catalogues"
+  keyStore?: KeyStore,
+  apiCallListener?: AIModelApiCallListener  // wire-level invocation log; see "API call logging"
 })
 
 registry.listProviders(): AIProvider[]
@@ -370,6 +427,51 @@ const settings: AISettings = {
 `openrouter` looks up `OPENROUTER_API_KEY`; `ollama_local` looks up
 `OLLAMA_LOCAL_API_KEY`. Each gets its own keyring entry under its `baseURL`.
 
+### Adding an OpenAI-compatible provider at runtime
+
+Two-step flow: persist the new entry into `AISettings` and rebuild the
+registry, then set the API key on the resulting provider instance.
+
+```ts
+// 1. Add the entry to settings and persist (host owns the config layer).
+const next: AISettings = {
+  ...settings,
+  providers: {
+    ...settings.providers,
+    openaiCompatible: [
+      ...(settings.providers.openaiCompatible ?? []),
+      {
+        id: 'groq',
+        baseURL: 'https://api.groq.com/openai/v1',
+        models: [{ id: 'llama-3.3-70b-versatile' }]
+      }
+    ]
+  }
+}
+writeConfigFile(next) // your persistence layer
+registry.updateSettings(next)
+
+// 2. The provider now exists in the registry — set its API key.
+const provider = registry.getProvider('groq')!
+await provider.setApiKey('gsk-...')
+```
+
+`updateSettings` rebuilds the provider list but preserves the shared
+`KeyStore`, so any keys already in the keyring stay resolved.
+
+If your UX needs to **validate the key before persisting the entry**, you can
+write directly to the `KeyStore` first — keys are stored against the
+normalised `baseURL`, not the provider id, so this works without the entry
+being registered yet:
+
+```ts
+await registry.keyStore.setKey('https://api.groq.com/openai/v1', 'gsk-...')
+// later, once validated: persist the AISettings entry and updateSettings.
+```
+
+Once you add the entry and rebuild, `provider.isAuthenticated()` returns
+`true` because the key already lives under that `baseURL`.
+
 ### Mixing slots across providers
 
 ```ts
@@ -458,9 +560,11 @@ for (const { provider, model } of registry.listAllModels()) {
 
 ```sh
 npm install
-npm test          # runs all 82 tests against the real system keyring
+npm test                  # runs the full test suite against the real system keyring
 npm run lint
-npm run gen       # emits .d.ts files into types/
+npm run build             # regenerates standalone validators, then emits .d.ts into types/
+npm run build:validators  # regenerates standalone validators only (run after a schema change)
+npm run build:types       # emits .d.ts files into types/
 ```
 
 Tests use a unique per-run keyring service name (`inkdrop.ai.test.<hex>`) so they

package/package.json

@@ -1,16 +1,19 @@
 {
   "name": "@inkdropapp/ai",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "AI integration common module",
   "type": "module",
   "main": "src/index.ts",
   "types": "types/index.d.ts",
-  "scripts": {
-    "lint": "eslint src __tests__",
-    "test": "node --experimental-vm-modules --no-warnings=ExperimentalWarning node_modules/jest/bin/jest.js --config jest.config.cjs --runInBand",
-    "build": "tsc --declaration --emitDeclarationOnly",
-    "format": "prettier --write .",
-    "prepublishOnly": "npm-run-all lint test build"
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.ts"
+    },
+    "./constants": {
+      "types": "./types/provider-constants.d.ts",
+      "default": "./src/provider-constants.ts"
+    }
   },
   "keywords": [
     "ai",
@@ -18,7 +21,6 @@
   ],
   "author": "Takuya Matsuyama <t@inkdrop.app>",
   "license": "UNLICENSED",
-  "packageManager": "pnpm@11.1.1",
   "dependencies": {
     "@ai-sdk/anthropic": "4.0.0-beta.42",
     "@ai-sdk/openai-compatible": "3.0.0-beta.36",
@@ -26,6 +28,7 @@
     "@inkdropapp/ai-catalog": "^0.1.0",
     "@napi-rs/keyring": "^1.2.0",
     "ai": "7.0.0-beta.116",
+    "ajv": "^8.20.0",
     "npm-run-all2": "^8.0.4"
   },
   "devDependencies": {
@@ -42,5 +45,13 @@
   "files": [
     "src",
     "types"
-  ]
-}
+  ],
+  "scripts": {
+    "lint": "eslint src __tests__",
+    "test": "node --experimental-vm-modules --no-warnings=ExperimentalWarning node_modules/jest/bin/jest.js --config jest.config.cjs --runInBand",
+    "build:validators": "node scripts/build-validators.mjs",
+    "build:types": "tsc --declaration --emitDeclarationOnly",
+    "build": "npm-run-all build:validators build:types",
+    "format": "prettier --write ."
+  }
+}

package/src/events.ts

@@ -0,0 +1,105 @@
+import type { AIError } from './errors.js'
+
+// ─── In-stream completion events ─────────────────────────────────────────────
+//
+// Fire while a single `streamCompletion` call is in flight. Provider-agnostic:
+// every concrete provider's stream is reduced to `StreamEvent` so consumers
+// never branch on provider id.
+
+/**
+ * Why a completion stream stopped producing output.
+ *
+ * Mirrors the AI SDK's `FinishReason`. Unknown / provider-specific values are
+ * normalised to `'other'` rather than silently passed through.
+ */
+export type FinishReason =
+  | 'stop'
+  | 'length'
+  | 'content-filter'
+  | 'tool-calls'
+  | 'error'
+  | 'other'
+
+/**
+ * Token usage for a single completion. Every field is optional because
+ * not every provider reports every counter.
+ */
+export type Usage = {
+  /** Tokens consumed from the prompt. */
+  inputTokens?: number
+  /** Tokens generated in the response. */
+  outputTokens?: number
+  /** `inputTokens + outputTokens` as reported by the provider. */
+  totalTokens?: number
+  /** Of `inputTokens`, how many were a cache hit (Anthropic prompt-cache reads). */
+  cacheReadInputTokens?: number
+  /** Of `inputTokens`, how many were written to the prompt cache for future reads. */
+  cacheCreationInputTokens?: number
+  /** Subset of `outputTokens` spent on reasoning / thinking content. */
+  reasoningTokens?: number
+}
+
+/**
+ * Provider-agnostic streaming events. Every concrete provider's stream is
+ * reduced to this discriminated union so consumers never branch on provider id.
+ *
+ * Errors arrive as `{ kind: 'error', ... }` events, not as thrown exceptions —
+ * this lets the host pump events across an Electron IPC boundary one at a time
+ * without needing try/catch around the iterator.
+ *
+ * `tool-call` and `tool-result` are typed but never produced in the current
+ * version (one-shot text completions only). They're reserved for forward compat.
+ */
+export type StreamEvent =
+  | { kind: 'text-delta'; delta: string }
+  | { kind: 'tool-call'; id: string; name: string; input: unknown }
+  | { kind: 'tool-result'; id: string; name: string; result: unknown }
+  | { kind: 'usage-update'; usage: Usage }
+  | { kind: 'finish'; finishReason: FinishReason; usage: Usage }
+  | { kind: 'error'; error: AIError }
+
+// ─── HTTP-level invocation events ────────────────────────────────────────────
+//
+// Fire once per upstream HTTP request, independent of the in-stream
+// `StreamEvent` pipeline. Threaded into providers via
+// `AIRegistryOptions.apiCallListener`.
+
+/**
+ * Wire-level record of one HTTP request the library made to an upstream
+ * provider API. Emitted via {@link AIRegistryOptions.apiCallListener} so the host
+ * can persist or surface an invocation log to end users.
+ *
+ * The listener is invoked exactly once per HTTP request — after the response
+ * headers arrive (or after the fetch itself fails). Streaming response bodies
+ * are *not* tee'd; only error bodies (HTTP status >= 400) are captured.
+ *
+ * API keys are redacted from `request.headers` before the event is emitted.
+ */
+export type AIModelApiCallEvent = {
+  /** Provider id that owns the SDK client which made the call. */
+  providerId: string
+  /** Epoch ms at which the fetch was issued. */
+  startedAt: number
+  /**
+   * Wall-clock time from fetch start to response headers (or to the fetch
+   * promise settling on failure). For streaming responses this is
+   * time-to-first-byte, not total stream duration.
+   */
+  durationMs: number
+  request: {
+    method: string
+    url: string
+    /** Outgoing headers; `authorization` / `x-api-key` / `anthropic-api-key` are redacted. */
+    headers: Record<string, string>
+    /** Parsed JSON when the body was a JSON string; the raw string otherwise. */
+    body: unknown
+  }
+  /** HTTP status, or `undefined` if the fetch itself failed before a response. */
+  status: number | undefined
+  /** Response body — populated only when `status >= 400`. */
+  errorBody?: string
+  /** Failure reason — populated only when fetch itself threw (network error, abort, …). */
+  failure?: string
+}
+
+export type AIModelApiCallListener = (event: AIModelApiCallEvent) => void

package/src/index.ts

@@ -1,5 +1,16 @@
-export type { AIProvider, AIModel, CompletionRequest } from './provider.js'
-export type { StreamEvent, Usage, FinishReason } from './stream-events.js'
+export type {
+  AIProvider,
+  AIModel,
+  AIModelOptions,
+  CompletionRequest
+} from './provider.js'
+export type {
+  StreamEvent,
+  Usage,
+  FinishReason,
+  AIModelApiCallEvent,
+  AIModelApiCallListener
+} from './events.js'
 export type {
   AISettings,
   SlotName,
@@ -36,11 +47,17 @@ export {
 } from './errors.js'
 export { KeyStore, type KeyStoreOptions } from './key-store.js'
 export { normalizeBaseURL } from './url.js'
-export { AnthropicProvider } from './providers/anthropic.js'
 export {
-  OpenAICompatibleProvider,
+  ANTHROPIC_PROVIDER_ID,
+  ANTHROPIC_PROVIDER_NAME,
+  ANTHROPIC_ENV_VAR,
+  ANTHROPIC_DEFAULT_BASE_URL,
+  OPENAI_COMPATIBLE_PROVIDER_ID,
+  OPENAI_COMPATIBLE_PROVIDER_NAME,
   deriveEnvVarName
-} from './providers/openai-compatible.js'
+} from './provider-constants.js'
+export { AnthropicProvider } from './providers/anthropic/provider.js'
+export { OpenAICompatibleProvider } from './providers/openai-compatible/provider.js'
 export {
   AIRegistry,
   type AIRegistryOptions,

package/src/provider-constants.ts

@@ -0,0 +1,31 @@
+/**
+ * Pure-data provider metadata for settings UIs.
+ *
+ * This module has no class or native-module imports, so it's safe to load in
+ * an Electron renderer process — unlike the main package entrypoint, which
+ * transitively pulls in `@napi-rs/keyring`.
+ *
+ * Consume via the `@inkdropapp/ai/constants` subpath:
+ *
+ *   import {
+ *     ANTHROPIC_PROVIDER_ID,
+ *     ANTHROPIC_PROVIDER_NAME,
+ *     ANTHROPIC_ENV_VAR,
+ *     ANTHROPIC_DEFAULT_BASE_URL,
+ *     OPENAI_COMPATIBLE_PROVIDER_ID,
+ *     OPENAI_COMPATIBLE_PROVIDER_NAME,
+ *     deriveEnvVarName
+ *   } from '@inkdropapp/ai/constants'
+ */
+
+export {
+  ANTHROPIC_PROVIDER_ID,
+  ANTHROPIC_PROVIDER_NAME,
+  ANTHROPIC_ENV_VAR,
+  ANTHROPIC_DEFAULT_BASE_URL
+} from './providers/anthropic/constants.js'
+export {
+  OPENAI_COMPATIBLE_PROVIDER_ID,
+  OPENAI_COMPATIBLE_PROVIDER_NAME,
+  deriveEnvVarName
+} from './providers/openai-compatible/constants.js'

package/src/provider.ts

@@ -3,7 +3,19 @@ import type {
   ModelCapabilities
 } from '@inkdropapp/ai-catalog'
 import type { ModelMessage } from 'ai'
-import type { StreamEvent } from './stream-events.js'
+import type { AIModelApiCallListener, StreamEvent } from './events.js'
+
+/**
+ * Provider-construction options that apply to every model the provider hosts.
+ * Threaded by `AIRegistry` into each provider's constructor.
+ */
+export type AIModelOptions = {
+  /**
+   * Invoked once per upstream HTTP request made by any model on this provider.
+   * See {@link AIModelApiCallListener}.
+   */
+  apiCallListener?: AIModelApiCallListener
+}
 
 /**
  * Inputs for a single one-shot streaming completion.

package/src/providers/anthropic/constants.ts

@@ -0,0 +1,4 @@
+export const ANTHROPIC_PROVIDER_ID = 'anthropic'
+export const ANTHROPIC_PROVIDER_NAME = 'Anthropic'
+export const ANTHROPIC_ENV_VAR = 'ANTHROPIC_API_KEY'
+export const ANTHROPIC_DEFAULT_BASE_URL = 'https://api.anthropic.com'

package/src/providers/{anthropic.ts → anthropic/provider.ts}

@@ -14,21 +14,28 @@ import {
   type ModelCapabilities
 } from '@inkdropapp/ai-catalog'
 import { streamText } from 'ai'
-import { NoApiKey } from '../errors.js'
-import type { KeyStore } from '../key-store.js'
-import { mapAiSdkError } from '../internal/map-ai-sdk-error.js'
-import { mapAiSdkStream } from '../internal/map-ai-sdk-stream.js'
-import type { AIModel, AIProvider, CompletionRequest } from '../provider.js'
+import { NoApiKey } from '../../errors.js'
+import type { AIModelApiCallListener, StreamEvent } from '../../events.js'
+import type { KeyStore } from '../../key-store.js'
+import type {
+  AIModel,
+  AIModelOptions,
+  AIProvider,
+  CompletionRequest
+} from '../../provider.js'
 import type {
   AnthropicModelConfig,
   AnthropicProviderConfig
-} from '../settings.js'
-import type { StreamEvent } from '../stream-events.js'
-
-const PROVIDER_ID = 'anthropic'
-const PROVIDER_NAME = 'Anthropic'
-const ENV_VAR = 'ANTHROPIC_API_KEY'
-const DEFAULT_BASE_URL = 'https://api.anthropic.com'
+} from '../../settings.js'
+import { createLoggingFetch } from '../../utils/logging-fetch.js'
+import { mapAiSdkError } from '../../utils/map-ai-sdk-error.js'
+import { mapAiSdkStream } from '../../utils/map-ai-sdk-stream.js'
+import {
+  ANTHROPIC_DEFAULT_BASE_URL,
+  ANTHROPIC_ENV_VAR,
+  ANTHROPIC_PROVIDER_ID,
+  ANTHROPIC_PROVIDER_NAME
+} from './constants.js'
 
 /**
  * The Anthropic (Claude) provider.
@@ -45,15 +52,16 @@ const DEFAULT_BASE_URL = 'https://api.anthropic.com'
  * `clearApiKey` is called or the resolved API key changes.
  */
 export class AnthropicProvider implements AIProvider {
-  readonly id = PROVIDER_ID
-  readonly name = PROVIDER_NAME
-  readonly envVarName = ENV_VAR
+  readonly id = ANTHROPIC_PROVIDER_ID
+  readonly name = ANTHROPIC_PROVIDER_NAME
+  readonly envVarName = ANTHROPIC_ENV_VAR
   readonly baseURL: string
 
   private readonly keyStore: KeyStore
   private readonly modelsById: Map<string, AnthropicAIModel>
   private readonly defaultId: string
   private readonly defaultFastId: string
+  private readonly apiCallListener: AIModelApiCallListener | undefined
 
   private sdkClient: SdkAnthropicProvider | undefined
   private sdkClientApiKey: string | undefined
@@ -61,10 +69,12 @@ export class AnthropicProvider implements AIProvider {
   constructor(
     keyStore: KeyStore,
     config: AnthropicProviderConfig = {},
-    catalog?: AnthropicCatalog
+    catalog?: AnthropicCatalog,
+    options: AIModelOptions = {}
   ) {
     this.keyStore = keyStore
-    this.baseURL = config.baseURL ?? DEFAULT_BASE_URL
+    this.baseURL = config.baseURL ?? ANTHROPIC_DEFAULT_BASE_URL
+    this.apiCallListener = options.apiCallListener
 
     const baseModels = catalog?.models ?? ANTHROPIC_MODELS
     this.defaultId = catalog?.defaultModelId ?? ANTHROPIC_DEFAULT_MODEL_ID
@@ -121,7 +131,13 @@ export class AnthropicProvider implements AIProvider {
       throw new NoApiKey(this.id, this.envVarName)
     }
     if (this.sdkClient && this.sdkClientApiKey === apiKey) return this.sdkClient
-    this.sdkClient = createAnthropic({ apiKey, baseURL: this.baseURL })
+    this.sdkClient = createAnthropic({
+      apiKey,
+      baseURL: this.baseURL,
+      fetch: this.apiCallListener
+        ? createLoggingFetch(this.id, this.apiCallListener)
+        : undefined
+    })
     this.sdkClientApiKey = apiKey
     return this.sdkClient
   }

package/src/providers/openai-compatible/constants.ts

@@ -0,0 +1,32 @@
+/**
+ * The `AISettings.providers` key for OpenAI-compatible entries. Use this to
+ * tag a settings-UI row as "an OpenAI-compatible provider" (vs. the built-in
+ * Anthropic row).
+ *
+ * Runtime provider ids for OpenAI-compatible entries are user-chosen
+ * (`AISettings.providers.openaiCompatible[].id`); this constant is the
+ * *type/kind*, not an instance id.
+ */
+export const OPENAI_COMPATIBLE_PROVIDER_ID = 'openaiCompatible'
+export const OPENAI_COMPATIBLE_PROVIDER_NAME = 'OpenAI-Compatible'
+
+/**
+ * Derives the env-var name for an OpenAI-compatible provider entry from its
+ * user-chosen `id`.
+ *
+ * Rules: replace any non-alphanumeric character with `_`, collapse runs of `_`,
+ * uppercase, append `_API_KEY`.
+ *
+ * Examples:
+ *   `openrouter`     → `OPENROUTER_API_KEY`
+ *   `together_ai`    → `TOGETHER_AI_API_KEY`
+ *   `ollama-local`   → `OLLAMA_LOCAL_API_KEY`
+ *   `my.proxy`       → `MY_PROXY_API_KEY`
+ */
+export const deriveEnvVarName = (id: string): string => {
+  const sanitized = id
+    .replace(/[^a-zA-Z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .toUpperCase()
+  return `${sanitized}_API_KEY`
+}

package/src/providers/{openai-compatible.ts → openai-compatible/provider.ts}

@@ -7,16 +7,24 @@ import type {
   ModelCapabilities
 } from '@inkdropapp/ai-catalog'
 import { streamText } from 'ai'
-import { NoApiKey } from '../errors.js'
-import type { KeyStore } from '../key-store.js'
-import { mapAiSdkError } from '../internal/map-ai-sdk-error.js'
-import { mapAiSdkStream } from '../internal/map-ai-sdk-stream.js'
-import type { AIModel, AIProvider, CompletionRequest } from '../provider.js'
+import { NoApiKey } from '../../errors.js'
+import type { AIModelApiCallListener, StreamEvent } from '../../events.js'
+import type { KeyStore } from '../../key-store.js'
+import type {
+  AIModel,
+  AIModelOptions,
+  AIProvider,
+  CompletionRequest
+} from '../../provider.js'
 import type {
   OpenAICompatibleModelConfig,
   OpenAICompatibleProviderConfig
-} from '../settings.js'
-import type { StreamEvent } from '../stream-events.js'
+} from '../../settings.js'
+import { createLoggingFetch } from '../../utils/logging-fetch.js'
+import { mapAiSdkError } from '../../utils/map-ai-sdk-error.js'
+import { mapAiSdkStream } from '../../utils/map-ai-sdk-stream.js'
+import { deriveEnvVarName } from './constants.js'
+import { validateOpenAICompatibleProviderConfig } from './validator.js'
 
 const DEFAULT_CAPABILITIES: ModelCapabilities = {
   supportsTools: true,
@@ -26,26 +34,6 @@ const DEFAULT_CAPABILITIES: ModelCapabilities = {
   maxTokens: 32_000
 }
 
-/**
- * Derives the env-var name for a user-named provider entry.
- *
- * Rules: replace any non-alphanumeric character with `_`, collapse runs of `_`,
- * uppercase, append `_API_KEY`.
- *
- * Examples:
- *   `openrouter`     → `OPENROUTER_API_KEY`
- *   `together_ai`    → `TOGETHER_AI_API_KEY`
- *   `ollama-local`   → `OLLAMA_LOCAL_API_KEY`
- *   `my.proxy`       → `MY_PROXY_API_KEY`
- */
-export const deriveEnvVarName = (id: string): string => {
-  const sanitized = id
-    .replace(/[^a-zA-Z0-9]+/g, '_')
-    .replace(/^_+|_+$/g, '')
-    .toUpperCase()
-  return `${sanitized}_API_KEY`
-}
-
 const mergeCapabilities = (
   override: Partial<ModelCapabilities> | undefined
 ): ModelCapabilities => ({
@@ -79,13 +67,20 @@ export class OpenAICompatibleProvider implements AIProvider {
   private readonly config: OpenAICompatibleProviderConfig
   private readonly keyStore: KeyStore
   private readonly modelsById: Map<string, OpenAICompatibleAIModel>
+  private readonly apiCallListener: AIModelApiCallListener | undefined
 
   private sdkClient: SdkOpenAICompatibleProvider | undefined
   private sdkClientApiKey: string | undefined
 
-  constructor(keyStore: KeyStore, config: OpenAICompatibleProviderConfig) {
+  constructor(
+    keyStore: KeyStore,
+    config: OpenAICompatibleProviderConfig,
+    options: AIModelOptions = {}
+  ) {
+    validateOpenAICompatibleProviderConfig(config)
     this.config = config
     this.keyStore = keyStore
+    this.apiCallListener = options.apiCallListener
     this.id = config.id
     this.name = config.displayName ?? config.id
     this.baseURL = config.baseURL
@@ -147,7 +142,10 @@ export class OpenAICompatibleProvider implements AIProvider {
     this.sdkClient = createOpenAICompatible({
       name: this.id,
       baseURL: this.baseURL,
-      apiKey: apiKey ?? undefined
+      apiKey: apiKey ?? undefined,
+      fetch: this.apiCallListener
+        ? createLoggingFetch(this.id, this.apiCallListener)
+        : undefined
     })
     this.sdkClientApiKey = apiKey ?? ''
     return this.sdkClient

package/src/providers/openai-compatible/validator-compiled.d.ts

@@ -0,0 +1,7 @@
+// AUTO-GENERATED by scripts/build-validators.mjs. Do not edit by hand.
+import type { ValidateFunction } from 'ajv'
+import type { OpenAICompatibleProviderConfig } from '../../settings.js'
+
+declare const validate: ValidateFunction<OpenAICompatibleProviderConfig>
+export default validate
+export { validate }