@inkdropapp/ai 0.1.3 → 0.1.5

package/src/providers/openai-compatible/validator-compiled.js

@@ -0,0 +1,4 @@
+// AUTO-GENERATED by scripts/build-validators.mjs. Do not edit by hand.
+import __ajv_runtime_0 from "ajv/dist/runtime/ucs2length.js";
+const func2 = __ajv_runtime_0.default ?? __ajv_runtime_0;
+"use strict";export const validate = validate10;export default validate10;const schema11 = {"type":"object","required":["id","baseURL","models"],"additionalProperties":false,"properties":{"id":{"type":"string","minLength":1},"displayName":{"type":"string"},"baseURL":{"type":"string","minLength":1},"models":{"type":"array","minItems":1,"items":{"type":"object","required":["id"],"additionalProperties":false,"properties":{"id":{"type":"string","minLength":1},"displayName":{"type":"string"},"capabilities":{"type":"object","additionalProperties":false,"properties":{"supportsTools":{"type":"boolean"},"supportsImages":{"type":"boolean"},"supportsThinking":{"type":"boolean"},"supportsStreamingTools":{"type":"boolean"},"maxTokens":{"type":"integer","minimum":1}}}}}},"defaultModelId":{"type":"string"},"defaultFastModelId":{"type":"string"}}};function validate10(data, {instancePath="", parentData, parentDataProperty, rootData=data}={}){let vErrors = null;let errors = 0;if(data && typeof data == "object" && !Array.isArray(data)){if(data.id === undefined){const err0 = {instancePath,schemaPath:"#/required",keyword:"required",params:{missingProperty: "id"},message:"must have required property '"+"id"+"'"};if(vErrors === null){vErrors = [err0];}else {vErrors.push(err0);}errors++;}if(data.baseURL === undefined){const err1 = {instancePath,schemaPath:"#/required",keyword:"required",params:{missingProperty: "baseURL"},message:"must have required property '"+"baseURL"+"'"};if(vErrors === null){vErrors = [err1];}else {vErrors.push(err1);}errors++;}if(data.models === undefined){const err2 = {instancePath,schemaPath:"#/required",keyword:"required",params:{missingProperty: "models"},message:"must have required property '"+"models"+"'"};if(vErrors === null){vErrors = [err2];}else {vErrors.push(err2);}errors++;}for(const key0 in data){if(!((((((key0 === "id") || (key0 === "displayName")) || (key0 === "baseURL")) || (key0 === "models")) || (key0 === "defaultModelId")) || (key0 === "defaultFastModelId"))){const err3 = {instancePath,schemaPath:"#/additionalProperties",keyword:"additionalProperties",params:{additionalProperty: key0},message:"must NOT have additional properties"};if(vErrors === null){vErrors = [err3];}else {vErrors.push(err3);}errors++;}}if(data.id !== undefined){let data0 = data.id;if(typeof data0 === "string"){if(func2(data0) < 1){const err4 = {instancePath:instancePath+"/id",schemaPath:"#/properties/id/minLength",keyword:"minLength",params:{limit: 1},message:"must NOT have fewer than 1 characters"};if(vErrors === null){vErrors = [err4];}else {vErrors.push(err4);}errors++;}}else {const err5 = {instancePath:instancePath+"/id",schemaPath:"#/properties/id/type",keyword:"type",params:{type: "string"},message:"must be string"};if(vErrors === null){vErrors = [err5];}else {vErrors.push(err5);}errors++;}}if(data.displayName !== undefined){if(typeof data.displayName !== "string"){const err6 = {instancePath:instancePath+"/displayName",schemaPath:"#/properties/displayName/type",keyword:"type",params:{type: "string"},message:"must be string"};if(vErrors === null){vErrors = [err6];}else {vErrors.push(err6);}errors++;}}if(data.baseURL !== undefined){let data2 = data.baseURL;if(typeof data2 === "string"){if(func2(data2) < 1){const err7 = {instancePath:instancePath+"/baseURL",schemaPath:"#/properties/baseURL/minLength",keyword:"minLength",params:{limit: 1},message:"must NOT have fewer than 1 characters"};if(vErrors === null){vErrors = [err7];}else {vErrors.push(err7);}errors++;}}else {const err8 = {instancePath:instancePath+"/baseURL",schemaPath:"#/properties/baseURL/type",keyword:"type",params:{type: "string"},message:"must be string"};if(vErrors === null){vErrors = [err8];}else {vErrors.push(err8);}errors++;}}if(data.models !== undefined){let data3 = data.models;if(Array.isArray(data3)){if(data3.length < 1){const err9 = {instancePath:instancePath+"/models",schemaPath:"#/properties/models/minItems",keyword:"minItems",params:{limit: 1},message:"must NOT have fewer than 1 items"};if(vErrors === null){vErrors = [err9];}else {vErrors.push(err9);}errors++;}const len0 = data3.length;for(let i0=0; i0<len0; i0++){let data4 = data3[i0];if(data4 && typeof data4 == "object" && !Array.isArray(data4)){if(data4.id === undefined){const err10 = {instancePath:instancePath+"/models/" + i0,schemaPath:"#/properties/models/items/required",keyword:"required",params:{missingProperty: "id"},message:"must have required property '"+"id"+"'"};if(vErrors === null){vErrors = [err10];}else {vErrors.push(err10);}errors++;}for(const key1 in data4){if(!(((key1 === "id") || (key1 === "displayName")) || (key1 === "capabilities"))){const err11 = {instancePath:instancePath+"/models/" + i0,schemaPath:"#/properties/models/items/additionalProperties",keyword:"additionalProperties",params:{additionalProperty: key1},message:"must NOT have additional properties"};if(vErrors === null){vErrors = [err11];}else {vErrors.push(err11);}errors++;}}if(data4.id !== undefined){let data5 = data4.id;if(typeof data5 === "string"){if(func2(data5) < 1){const err12 = {instancePath:instancePath+"/models/" + i0+"/id",schemaPath:"#/properties/models/items/properties/id/minLength",keyword:"minLength",params:{limit: 1},message:"must NOT have fewer than 1 characters"};if(vErrors === null){vErrors = [err12];}else {vErrors.push(err12);}errors++;}}else {const err13 = {instancePath:instancePath+"/models/" + i0+"/id",schemaPath:"#/properties/models/items/properties/id/type",keyword:"type",params:{type: "string"},message:"must be string"};if(vErrors === null){vErrors = [err13];}else {vErrors.push(err13);}errors++;}}if(data4.displayName !== undefined){if(typeof data4.displayName !== "string"){const err14 = {instancePath:instancePath+"/models/" + i0+"/displayName",schemaPath:"#/properties/models/items/properties/displayName/type",keyword:"type",params:{type: "string"},message:"must be string"};if(vErrors === null){vErrors = [err14];}else {vErrors.push(err14);}errors++;}}if(data4.capabilities !== undefined){let data7 = data4.capabilities;if(data7 && typeof data7 == "object" && !Array.isArray(data7)){for(const key2 in data7){if(!(((((key2 === "supportsTools") || (key2 === "supportsImages")) || (key2 === "supportsThinking")) || (key2 === "supportsStreamingTools")) || (key2 === "maxTokens"))){const err15 = {instancePath:instancePath+"/models/" + i0+"/capabilities",schemaPath:"#/properties/models/items/properties/capabilities/additionalProperties",keyword:"additionalProperties",params:{additionalProperty: key2},message:"must NOT have additional properties"};if(vErrors === null){vErrors = [err15];}else {vErrors.push(err15);}errors++;}}if(data7.supportsTools !== undefined){if(typeof data7.supportsTools !== "boolean"){const err16 = {instancePath:instancePath+"/models/" + i0+"/capabilities/supportsTools",schemaPath:"#/properties/models/items/properties/capabilities/properties/supportsTools/type",keyword:"type",params:{type: "boolean"},message:"must be boolean"};if(vErrors === null){vErrors = [err16];}else {vErrors.push(err16);}errors++;}}if(data7.supportsImages !== undefined){if(typeof data7.supportsImages !== "boolean"){const err17 = {instancePath:instancePath+"/models/" + i0+"/capabilities/supportsImages",schemaPath:"#/properties/models/items/properties/capabilities/properties/supportsImages/type",keyword:"type",params:{type: "boolean"},message:"must be boolean"};if(vErrors === null){vErrors = [err17];}else {vErrors.push(err17);}errors++;}}if(data7.supportsThinking !== undefined){if(typeof data7.supportsThinking !== "boolean"){const err18 = {instancePath:instancePath+"/models/" + i0+"/capabilities/supportsThinking",schemaPath:"#/properties/models/items/properties/capabilities/properties/supportsThinking/type",keyword:"type",params:{type: "boolean"},message:"must be boolean"};if(vErrors === null){vErrors = [err18];}else {vErrors.push(err18);}errors++;}}if(data7.supportsStreamingTools !== undefined){if(typeof data7.supportsStreamingTools !== "boolean"){const err19 = {instancePath:instancePath+"/models/" + i0+"/capabilities/supportsStreamingTools",schemaPath:"#/properties/models/items/properties/capabilities/properties/supportsStreamingTools/type",keyword:"type",params:{type: "boolean"},message:"must be boolean"};if(vErrors === null){vErrors = [err19];}else {vErrors.push(err19);}errors++;}}if(data7.maxTokens !== undefined){let data12 = data7.maxTokens;if(!(((typeof data12 == "number") && (!(data12 % 1) && !isNaN(data12))) && (isFinite(data12)))){const err20 = {instancePath:instancePath+"/models/" + i0+"/capabilities/maxTokens",schemaPath:"#/properties/models/items/properties/capabilities/properties/maxTokens/type",keyword:"type",params:{type: "integer"},message:"must be integer"};if(vErrors === null){vErrors = [err20];}else {vErrors.push(err20);}errors++;}if((typeof data12 == "number") && (isFinite(data12))){if(data12 < 1 || isNaN(data12)){const err21 = {instancePath:instancePath+"/models/" + i0+"/capabilities/maxTokens",schemaPath:"#/properties/models/items/properties/capabilities/properties/maxTokens/minimum",keyword:"minimum",params:{comparison: ">=", limit: 1},message:"must be >= 1"};if(vErrors === null){vErrors = [err21];}else {vErrors.push(err21);}errors++;}}}}else {const err22 = {instancePath:instancePath+"/models/" + i0+"/capabilities",schemaPath:"#/properties/models/items/properties/capabilities/type",keyword:"type",params:{type: "object"},message:"must be object"};if(vErrors === null){vErrors = [err22];}else {vErrors.push(err22);}errors++;}}}else {const err23 = {instancePath:instancePath+"/models/" + i0,schemaPath:"#/properties/models/items/type",keyword:"type",params:{type: "object"},message:"must be object"};if(vErrors === null){vErrors = [err23];}else {vErrors.push(err23);}errors++;}}}else {const err24 = {instancePath:instancePath+"/models",schemaPath:"#/properties/models/type",keyword:"type",params:{type: "array"},message:"must be array"};if(vErrors === null){vErrors = [err24];}else {vErrors.push(err24);}errors++;}}if(data.defaultModelId !== undefined){if(typeof data.defaultModelId !== "string"){const err25 = {instancePath:instancePath+"/defaultModelId",schemaPath:"#/properties/defaultModelId/type",keyword:"type",params:{type: "string"},message:"must be string"};if(vErrors === null){vErrors = [err25];}else {vErrors.push(err25);}errors++;}}if(data.defaultFastModelId !== undefined){if(typeof data.defaultFastModelId !== "string"){const err26 = {instancePath:instancePath+"/defaultFastModelId",schemaPath:"#/properties/defaultFastModelId/type",keyword:"type",params:{type: "string"},message:"must be string"};if(vErrors === null){vErrors = [err26];}else {vErrors.push(err26);}errors++;}}}else {const err27 = {instancePath,schemaPath:"#/type",keyword:"type",params:{type: "object"},message:"must be object"};if(vErrors === null){vErrors = [err27];}else {vErrors.push(err27);}errors++;}validate10.errors = vErrors;return errors === 0;}

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

@@ -0,0 +1,33 @@
+import type { ErrorObject } from 'ajv'
+import type { OpenAICompatibleProviderConfig } from '../../settings.js'
+import validate from './validator-compiled.js'
+
+const formatErrors = (
+  errors: ReadonlyArray<ErrorObject> | null | undefined
+): string => {
+  if (!errors || errors.length === 0) return 'unknown validation error'
+  return errors
+    .map(e => `config${e.instancePath ?? ''} ${e.message ?? ''}`.trim())
+    .join(', ')
+}
+
+/**
+ * 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 const validateOpenAICompatibleProviderConfig = (
+  config: OpenAICompatibleProviderConfig
+): void => {
+  if (validate(config)) return
+  throw new Error(
+    `Invalid OpenAI-compatible provider config: ${formatErrors(validate.errors)}`
+  )
+}

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/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,10 +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 { AnthropicProvider } from './providers/anthropic.js';
-export { OpenAICompatibleProvider, deriveEnvVarName } 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 } from './provider-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

@@ -0,0 +1,21 @@
+/**
+ * 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/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";

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/providers/openai-compatible.d.ts

@@ -2,19 +2,6 @@ import { type OpenAICompatibleProvider as SdkOpenAICompatibleProvider } from '@a
 import type { KeyStore } from '../key-store.js';
 import type { AIModel, AIProvider } from '../provider.js';
 import type { OpenAICompatibleProviderConfig } from '../settings.js';
-/**
- * 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 declare const deriveEnvVarName: (id: string) => string;
 /**
  * Provider for any OpenAI-compatible chat-completions endpoint
  * (OpenRouter, Together, Fireworks, Groq, vLLM, Ollama via `/v1`, LiteLLM, …).

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 {};