@inkdropapp/ai 0.1.4 → 0.1.6

package/src/registry.ts

@@ -1,11 +1,16 @@
 import type { AIModelCatalog } from '@inkdropapp/ai-catalog'
+import type { AIModelApiCallListener, StreamEvent } from './events.js'
 import { NoApiKey } from './errors.js'
 import { KeyStore } from './key-store.js'
-import type { AIModel, AIProvider, CompletionRequest } from './provider.js'
-import { AnthropicProvider } from './providers/anthropic.js'
-import { OpenAICompatibleProvider } from './providers/openai-compatible.js'
+import type {
+  AIModel,
+  AIModelOptions,
+  AIProvider,
+  CompletionRequest
+} from './provider.js'
+import { AnthropicProvider } from './providers/anthropic/provider.js'
+import { OpenAICompatibleProvider } from './providers/openai-compatible/provider.js'
 import type { AISettings, SlotConfig, SlotName } from './settings.js'
-import type { StreamEvent } from './stream-events.js'
 
 /** Result of resolving a slot to a concrete `(provider, model)` pair. */
 export type ResolvedSlot = {
@@ -24,6 +29,16 @@ export type AIRegistryOptions = {
   catalog?: AIModelCatalog
   /** Pass an existing `KeyStore` to share its in-memory cache across registries. */
   keyStore?: KeyStore
+  /**
+   * Invoked once per upstream HTTP request made by any provider in this
+   * registry. The hook is best-effort logging only — exceptions thrown from
+   * the listener are swallowed so they cannot interrupt the request path.
+   *
+   * Use this to back a user-facing "API invocation log" view. Streaming
+   * response bodies are not captured; only error bodies (status >= 400) are.
+   * See {@link AIModelApiCallEvent}.
+   */
+  apiCallListener?: AIModelApiCallListener
 }
 
 /**
@@ -50,11 +65,13 @@ export class AIRegistry {
   private providers: Map<string, AIProvider> = new Map()
   private settings: AISettings
   private catalog: AIModelCatalog | undefined
+  private readonly apiCallListener: AIModelApiCallListener | undefined
 
   constructor(options: AIRegistryOptions) {
     this.keyStore = options.keyStore ?? new KeyStore()
     this.settings = options.settings
     this.catalog = options.catalog
+    this.apiCallListener = options.apiCallListener
     this.rebuildProviders()
   }
 
@@ -183,18 +200,25 @@ export class AIRegistry {
   private rebuildProviders(): void {
     const built: AIProvider[] = []
 
+    const providerOptions: AIModelOptions = {
+      apiCallListener: this.apiCallListener
+    }
+
     if (this.settings.providers.anthropic) {
       built.push(
         new AnthropicProvider(
           this.keyStore,
           this.settings.providers.anthropic,
-          this.catalog?.anthropic
+          this.catalog?.anthropic,
+          providerOptions
         )
       )
     }
 
     for (const config of this.settings.providers.openaiCompatible ?? []) {
-      built.push(new OpenAICompatibleProvider(this.keyStore, config))
+      built.push(
+        new OpenAICompatibleProvider(this.keyStore, config, providerOptions)
+      )
     }
 
     // Sort once at build time so `Map` iteration (insertion order) is

package/src/utils/logging-fetch.ts

@@ -0,0 +1,122 @@
+import type { AIModelApiCallEvent, AIModelApiCallListener } from '../events.js'
+
+type FetchFn = typeof fetch
+type FetchInput = Parameters<FetchFn>[0]
+type FetchInit = NonNullable<Parameters<FetchFn>[1]>
+type FetchHeaders = FetchInit['headers']
+
+const REDACTED_HEADERS = new Set([
+  'authorization',
+  'x-api-key',
+  'anthropic-api-key',
+  'api-key'
+])
+
+const sanitizeHeaders = (
+  headers: FetchHeaders | undefined
+): Record<string, string> => {
+  const out: Record<string, string> = {}
+  const put = (key: string, value: string) => {
+    out[key] = REDACTED_HEADERS.has(key.toLowerCase()) ? '[redacted]' : value
+  }
+  if (!headers) return out
+  if (typeof Headers !== 'undefined' && headers instanceof Headers) {
+    headers.forEach((value, key) => put(key, value))
+  } else if (Array.isArray(headers)) {
+    for (const entry of headers) put(entry[0], entry[1])
+  } else {
+    for (const [key, value] of Object.entries(headers)) put(key, String(value))
+  }
+  return out
+}
+
+const parseBody = (body: unknown): unknown => {
+  if (body == null) return undefined
+  if (typeof body !== 'string') return '[non-string body]'
+  try {
+    return JSON.parse(body)
+  } catch {
+    return body
+  }
+}
+
+const extractUrl = (input: FetchInput): string => {
+  if (typeof input === 'string') return input
+  if (input instanceof URL) return input.toString()
+  return input.url
+}
+
+const extractMethod = (
+  input: FetchInput,
+  init: FetchInit | undefined
+): string => {
+  if (init?.method) return init.method
+  if (typeof input !== 'string' && !(input instanceof URL)) return input.method
+  return 'GET'
+}
+
+const safeNotify = (
+  listener: AIModelApiCallListener,
+  event: AIModelApiCallEvent
+): void => {
+  try {
+    listener(event)
+  } catch {
+    // Swallow — a misbehaving listener must not break the fetch path.
+  }
+}
+
+/**
+ * Wraps an underlying `fetch` to emit an {@link AIModelApiCallEvent} per HTTP request.
+ *
+ * Emits exactly once per call. On HTTP error (`!response.ok`) the response is
+ * `clone()`'d and the body is read as text into `event.errorBody`; the
+ * original response is returned untouched so the SDK still consumes the
+ * stream normally. Successful streaming responses are *not* tee'd — only the
+ * status is recorded.
+ */
+export const createLoggingFetch = (
+  providerId: string,
+  listener: AIModelApiCallListener,
+  inner: FetchFn = fetch
+): FetchFn => {
+  return async (input, init) => {
+    const startedAt = Date.now()
+    const url = extractUrl(input)
+    const method = extractMethod(input, init)
+    const headers = sanitizeHeaders(init?.headers)
+    const body = parseBody(init?.body)
+
+    const buildEvent = (extras: {
+      status: number | undefined
+      errorBody?: string
+      failure?: string
+    }): AIModelApiCallEvent => ({
+      providerId,
+      startedAt,
+      durationMs: Date.now() - startedAt,
+      request: { method, url, headers, body },
+      ...extras
+    })
+
+    try {
+      const response = await inner(input, init)
+      if (!response.ok) {
+        let errorBody: string
+        try {
+          errorBody = await response.clone().text()
+        } catch {
+          errorBody = '[could not read error body]'
+        }
+        safeNotify(listener, buildEvent({ status: response.status, errorBody }))
+      } else {
+        safeNotify(listener, buildEvent({ status: response.status }))
+      }
+      return response
+    } catch (err) {
+      const failure = err instanceof Error ? err.message : String(err)
+      safeNotify(listener, buildEvent({ status: undefined, failure }))
+      throw err
+    }
+  }
+}

package/src/{internal → utils}/map-ai-sdk-stream.ts

@@ -4,7 +4,7 @@ import type {
   TextStreamPart,
   ToolSet
 } from 'ai'
-import type { FinishReason, StreamEvent, Usage } from '../stream-events.js'
+import type { FinishReason, StreamEvent, Usage } from '../events.js'
 import { mapAiSdkError } from './map-ai-sdk-error.js'
 
 const mapUsage = (usage: LanguageModelUsage | undefined): Usage => {

package/types/constants.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Pure-data constants 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,
+ *     SLOT_DEFAULT,
+ *     SLOT_FAST
+ *   } 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';
+/**
+ * String literals for the two task slots exposed by {@link SlotName}.
+ * `satisfies SlotName` preserves the narrow literal type while verifying at
+ * compile time that the value is a valid `SlotName`.
+ */
+export declare const SLOT_DEFAULT = "default";
+export declare const SLOT_FAST = "fast";

package/types/events.d.ts

@@ -0,0 +1,99 @@
+import type { AIError } from './errors.js';
+/**
+ * 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;
+};
+/**
+ * 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/types/index.d.ts

@@ -1,11 +1,11 @@
-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, SlotConfig, CommonProviderConfig, AnthropicProviderConfig, AnthropicModelConfig, OpenAICompatibleProviderConfig, OpenAICompatibleModelConfig } from './settings.js';
 export { ANTHROPIC_MODELS, ANTHROPIC_DEFAULT_MODEL_ID, ANTHROPIC_DEFAULT_FAST_MODEL_ID, DEFAULT_ANTHROPIC_CACHE_CONFIG, DEFAULT_ANTHROPIC_CAPABILITIES, BUILT_IN_CATALOG, type AIModelCatalog, type AnthropicCatalog, type AnthropicModelDescriptor, type CacheConfiguration, type ModelCapabilities } from '@inkdropapp/ai-catalog';
 export { AIError, NoApiKey, AuthenticationError, RateLimitExceeded, ServerOverloaded, PromptTooLarge, UpstreamError, isAIError, type AIErrorKind } from './errors.js';
 export { KeyStore, type KeyStoreOptions } from './key-store.js';
 export { normalizeBaseURL } from './url.js';
-export { ANTHROPIC_PROVIDER_ID, ANTHROPIC_PROVIDER_NAME, ANTHROPIC_ENV_VAR, ANTHROPIC_DEFAULT_BASE_URL, OPENAI_COMPATIBLE_PROVIDER_ID, OPENAI_COMPATIBLE_PROVIDER_NAME, deriveEnvVarName } from './provider-constants.js';
-export { AnthropicProvider } from './providers/anthropic.js';
-export { OpenAICompatibleProvider } from './providers/openai-compatible.js';
+export { ANTHROPIC_PROVIDER_ID, ANTHROPIC_PROVIDER_NAME, ANTHROPIC_ENV_VAR, ANTHROPIC_DEFAULT_BASE_URL, OPENAI_COMPATIBLE_PROVIDER_ID, OPENAI_COMPATIBLE_PROVIDER_NAME, deriveEnvVarName, SLOT_DEFAULT, SLOT_FAST } from './constants.js';
+export { AnthropicProvider } from './providers/anthropic/provider.js';
+export { OpenAICompatibleProvider } from './providers/openai-compatible/provider.js';
 export { AIRegistry, type AIRegistryOptions, type ResolvedSlot } from './registry.js';

package/types/provider-constants.d.ts

@@ -17,32 +17,5 @@
  *     deriveEnvVarName
  *   } from '@inkdropapp/ai/constants'
  */
-export declare const ANTHROPIC_PROVIDER_ID = "anthropic";
-export declare const ANTHROPIC_PROVIDER_NAME = "Anthropic";
-export declare const ANTHROPIC_ENV_VAR = "ANTHROPIC_API_KEY";
-export declare const ANTHROPIC_DEFAULT_BASE_URL = "https://api.anthropic.com";
-/**
- * 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 declare const OPENAI_COMPATIBLE_PROVIDER_ID = "openaiCompatible";
-export declare 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 declare const deriveEnvVarName: (id: string) => string;
+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/types/provider.d.ts

@@ -1,6 +1,17 @@
 import type { CacheConfiguration, 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/types/providers/anthropic/constants.d.ts

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

package/types/providers/anthropic/provider.d.ts

@@ -0,0 +1,42 @@
+import { type AnthropicProvider as SdkAnthropicProvider } from '@ai-sdk/anthropic';
+import { type AnthropicCatalog } from '@inkdropapp/ai-catalog';
+import type { KeyStore } from '../../key-store.js';
+import type { AIModel, AIModelOptions, AIProvider } from '../../provider.js';
+import type { AnthropicProviderConfig } from '../../settings.js';
+/**
+ * The Anthropic (Claude) provider.
+ *
+ * Wraps `@ai-sdk/anthropic`. Loads its model catalogue from one of:
+ *   1. The {@link AnthropicCatalog} passed at construction time (server-distributed).
+ *   2. The compiled-in {@link ANTHROPIC_MODELS} list as a fallback.
+ *
+ * User-declared `config.models` are layered on top, overriding entries with
+ * matching ids regardless of source.
+ *
+ * Lazily constructs the SDK client on first stream and caches it across
+ * requests. The cached client is invalidated whenever `setApiKey` /
+ * `clearApiKey` is called or the resolved API key changes.
+ */
+export declare class AnthropicProvider implements AIProvider {
+    readonly id = "anthropic";
+    readonly name = "Anthropic";
+    readonly envVarName = "ANTHROPIC_API_KEY";
+    readonly baseURL: string;
+    private readonly keyStore;
+    private readonly modelsById;
+    private readonly defaultId;
+    private readonly defaultFastId;
+    private readonly apiCallListener;
+    private sdkClient;
+    private sdkClientApiKey;
+    constructor(keyStore: KeyStore, config?: AnthropicProviderConfig, catalog?: AnthropicCatalog, options?: AIModelOptions);
+    listModels(): AIModel[];
+    getModel(id: string): AIModel | undefined;
+    defaultModel(): AIModel | undefined;
+    defaultFastModel(): AIModel | undefined;
+    isAuthenticated(): Promise<boolean>;
+    setApiKey(key: string): Promise<void>;
+    clearApiKey(): Promise<void>;
+    /** Internal — used by AnthropicAIModel to resolve the SDK client lazily. */
+    getSdkClient(): Promise<SdkAnthropicProvider>;
+}

package/types/providers/openai-compatible/constants.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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 declare const OPENAI_COMPATIBLE_PROVIDER_ID = "openaiCompatible";
+export declare 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 declare const deriveEnvVarName: (id: string) => string;

package/types/providers/openai-compatible/provider.d.ts

@@ -0,0 +1,47 @@
+import { type OpenAICompatibleProvider as SdkOpenAICompatibleProvider } from '@ai-sdk/openai-compatible';
+import type { KeyStore } from '../../key-store.js';
+import type { AIModel, AIModelOptions, AIProvider } from '../../provider.js';
+import type { OpenAICompatibleProviderConfig } from '../../settings.js';
+/**
+ * Provider for any OpenAI-compatible chat-completions endpoint
+ * (OpenRouter, Together, Fireworks, Groq, vLLM, Ollama via `/v1`, LiteLLM, …).
+ *
+ * Each user-named entry in `AISettings.providers.openaiCompatible[]`
+ * becomes one instance. The env-var name is derived from the entry's `id`
+ * via {@link deriveEnvVarName}; the keyring account is the resolved `baseURL`.
+ *
+ * Capability flags are user-declared per model (with sensible defaults of
+ * `tools: true`, `images: false`, `thinking: false`); the host UI keys off
+ * those flags exactly the same as for Anthropic.
+ *
+ * Some endpoints (Ollama, vLLM, …) require no API key. The provider
+ * accommodates this by passing `apiKey: undefined` to the SDK rather than
+ * proactively throwing `NoApiKey` — auth failures only surface if the
+ * upstream actually returns 401.
+ */
+export declare class OpenAICompatibleProvider implements AIProvider {
+    readonly id: string;
+    readonly name: string;
+    readonly baseURL: string;
+    readonly envVarName: string;
+    private readonly config;
+    private readonly keyStore;
+    private readonly modelsById;
+    private readonly apiCallListener;
+    private sdkClient;
+    private sdkClientApiKey;
+    constructor(keyStore: KeyStore, config: OpenAICompatibleProviderConfig, options?: AIModelOptions);
+    listModels(): AIModel[];
+    getModel(id: string): AIModel | undefined;
+    defaultModel(): AIModel | undefined;
+    defaultFastModel(): AIModel | undefined;
+    isAuthenticated(): Promise<boolean>;
+    setApiKey(key: string): Promise<void>;
+    clearApiKey(): Promise<void>;
+    /** Internal — used by OpenAICompatibleAIModel to resolve the SDK client lazily. */
+    getSdkClient(): Promise<SdkOpenAICompatibleProvider>;
+    /** Internal — exposed for tests / 401 handling: did the user configure an explicit auth value? */
+    hasConfiguredKey(): Promise<boolean>;
+    /** Internal — used by the model when upstream returns 401: surface a NoApiKey if the user never configured one. */
+    ensureAuthenticatedOrThrow(): Promise<void>;
+}

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

@@ -0,0 +1,9 @@
+export function validate(data: any, { instancePath, parentData, parentDataProperty, rootData }?: {
+    instancePath?: string | undefined;
+    rootData?: any;
+}): boolean;
+export default validate10;
+declare function validate10(data: any, { instancePath, parentData, parentDataProperty, rootData }?: {
+    instancePath?: string | undefined;
+    rootData?: any;
+}): boolean;

package/types/providers/openai-compatible/validator.d.ts

@@ -0,0 +1,14 @@
+import type { OpenAICompatibleProviderConfig } from '../../settings.js';
+/**
+ * Throws if `config` doesn't conform to the OpenAI-compatible provider schema.
+ *
+ * The validator is precompiled to a standalone ESM module by
+ * `scripts/build-validators.mjs`, so loading this module does not call
+ * `new Function(...)` — making it safe to use in Electron renderer processes
+ * under a strict CSP without `unsafe-eval`.
+ *
+ * Catches the kinds of mistakes a settings UI or hand-written config can make:
+ * missing required fields, wrong types, unknown keys, empty `models[]`, or an
+ * empty string where a non-empty one is required.
+ */
+export declare const validateOpenAICompatibleProviderConfig: (config: OpenAICompatibleProviderConfig) => void;

package/types/registry.d.ts

@@ -1,8 +1,8 @@
 import type { AIModelCatalog } from '@inkdropapp/ai-catalog';
+import type { AIModelApiCallListener, StreamEvent } from './events.js';
 import { KeyStore } from './key-store.js';
 import type { AIModel, AIProvider, CompletionRequest } from './provider.js';
 import type { AISettings, SlotName } from './settings.js';
-import type { StreamEvent } from './stream-events.js';
 /** Result of resolving a slot to a concrete `(provider, model)` pair. */
 export type ResolvedSlot = {
     provider: AIProvider;
@@ -19,6 +19,16 @@ export type AIRegistryOptions = {
     catalog?: AIModelCatalog;
     /** Pass an existing `KeyStore` to share its in-memory cache across registries. */
     keyStore?: KeyStore;
+    /**
+     * Invoked once per upstream HTTP request made by any provider in this
+     * registry. The hook is best-effort logging only — exceptions thrown from
+     * the listener are swallowed so they cannot interrupt the request path.
+     *
+     * Use this to back a user-facing "API invocation log" view. Streaming
+     * response bodies are not captured; only error bodies (status >= 400) are.
+     * See {@link AIModelApiCallEvent}.
+     */
+    apiCallListener?: AIModelApiCallListener;
 };
 /**
  * Top-level entrypoint to the library.
@@ -44,6 +54,7 @@ export declare class AIRegistry {
     private providers;
     private settings;
     private catalog;
+    private readonly apiCallListener;
     constructor(options: AIRegistryOptions);
     /** All configured providers, sorted alphabetically by id. */
     listProviders(): AIProvider[];

package/types/utils/logging-fetch.d.ts

@@ -0,0 +1,13 @@
+import type { AIModelApiCallListener } from '../events.js';
+type FetchFn = typeof fetch;
+/**
+ * Wraps an underlying `fetch` to emit an {@link AIModelApiCallEvent} per HTTP request.
+ *
+ * Emits exactly once per call. On HTTP error (`!response.ok`) the response is
+ * `clone()`'d and the body is read as text into `event.errorBody`; the
+ * original response is returned untouched so the SDK still consumes the
+ * stream normally. Successful streaming responses are *not* tee'd — only the
+ * status is recorded.
+ */
+export declare const createLoggingFetch: (providerId: string, listener: AIModelApiCallListener, inner?: FetchFn) => FetchFn;
+export {};

package/types/utils/map-ai-sdk-error.d.ts

@@ -0,0 +1,21 @@
+import { AIError } from '../errors.js';
+/**
+ * Reduces an arbitrary unknown error coming out of the AI SDK to one of our
+ * {@link AIError} variants.
+ *
+ * Mapping rules:
+ * - Existing `AIError` → returned unchanged.
+ * - `LoadAPIKeyError` → `NoApiKey`.
+ * - `APICallError` with status:
+ *   - 401 / 403 → `AuthenticationError`
+ *   - 429 → `RateLimitExceeded` (with `retryAfter` parsed from header)
+ *   - 503 / 529 → `ServerOverloaded` (with `retryAfter`)
+ *   - 413, or any message that "looks like" a context-length overflow → `PromptTooLarge`
+ *   - anything else → `UpstreamError` carrying status + cause
+ * - Other `AISDKError` / `Error` instances → `UpstreamError` (or `PromptTooLarge`
+ *   if the message matches).
+ *
+ * @param providerId - Used to attribute the error in messages and downstream
+ * routing decisions.
+ */
+export declare const mapAiSdkError: (error: unknown, providerId: string) => AIError;

package/types/utils/map-ai-sdk-stream.d.ts

@@ -0,0 +1,25 @@
+import type { StreamTextResult, ToolSet } from 'ai';
+import type { StreamEvent } from '../events.js';
+/**
+ * Adapts the AI SDK's `streamText().fullStream` into the library's
+ * provider-agnostic {@link StreamEvent} stream.
+ *
+ * Three contracts that downstream code relies on:
+ *
+ * 1. **No throwing.** Errors thrown by the iterator (e.g. mid-stream HTTP
+ *    failure) are caught and re-emitted as `{ kind: 'error', error }`.
+ *    The iterator always terminates cleanly, so consumers that pump events
+ *    over IPC don't need to wrap iteration in try/catch.
+ * 2. **Errors are terminal.** When an `error` event from the SDK is observed
+ *    the iterator returns immediately — any subsequent SDK chunks are dropped.
+ * 3. **Unknown SDK part types are silently ignored.** Forward-compat with
+ *    new AI SDK chunk variants without a library bump.
+ *
+ * Emits in this order over the lifetime of one completion:
+ * `text-delta*` → `usage-update?` → `finish | error`.
+ *
+ * @param result - The object returned by `streamText()`.
+ *                 Only its `fullStream` is consumed.
+ * @param providerId - Provider id used to attribute any wrapped errors.
+ */
+export declare function mapAiSdkStream(result: Pick<StreamTextResult<ToolSet, never, never>, 'fullStream'>, providerId: string): AsyncIterable<StreamEvent>;