@inkdropapp/ai 0.1.0

package/types/errors.d.ts

@@ -0,0 +1,69 @@
+/** Discriminant for {@link AIError} subclasses. */
+export type AIErrorKind = 'no-api-key' | 'rate-limit-exceeded' | 'server-overloaded' | 'authentication' | 'prompt-too-large' | 'upstream';
+/**
+ * Base class for every error this library surfaces. Concrete subclasses are
+ * tagged with `kind` so consumers can switch on it without instanceof chains.
+ *
+ * Errors are emitted as `{ kind: 'error', error }` events inside completion
+ * streams rather than thrown — consumers that iterate the stream do not need
+ * try/catch.
+ */
+export declare abstract class AIError extends Error {
+    abstract readonly kind: AIErrorKind;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown / emitted when a provider has no resolvable API key — neither in its
+ * environment variable nor in the system keyring.
+ */
+export declare class NoApiKey extends AIError {
+    readonly providerId: string;
+    readonly envVarName: string | null;
+    readonly kind: "no-api-key";
+    constructor(providerId: string, envVarName: string | null);
+}
+/** Upstream returned 401 / 403 — the configured key was rejected. */
+export declare class AuthenticationError extends AIError {
+    readonly providerId: string;
+    readonly kind: "authentication";
+    constructor(providerId: string, message?: string);
+}
+/** Upstream returned 429. `retryAfter` is in seconds, parsed from the response header. */
+export declare class RateLimitExceeded extends AIError {
+    readonly providerId: string;
+    readonly retryAfter: number | undefined;
+    readonly kind: "rate-limit-exceeded";
+    constructor(providerId: string, retryAfter: number | undefined, message?: string);
+}
+/** Upstream returned 503 / 529. `retryAfter` is in seconds, parsed from the response header. */
+export declare class ServerOverloaded extends AIError {
+    readonly providerId: string;
+    readonly retryAfter: number | undefined;
+    readonly kind: "server-overloaded";
+    constructor(providerId: string, retryAfter: number | undefined, message?: string);
+}
+/** Prompt exceeds the model's context window (HTTP 413, or message says so). */
+export declare class PromptTooLarge extends AIError {
+    readonly providerId: string;
+    readonly tokenCount: number | undefined;
+    readonly maxTokens: number | undefined;
+    readonly kind: "prompt-too-large";
+    constructor(providerId: string, tokenCount: number | undefined, maxTokens: number | undefined, message?: string);
+}
+/**
+ * Catch-all for upstream failures that don't map to a more specific variant.
+ * `status` is the HTTP status code when known; `cause` preserves the original
+ * AI SDK error for debugging.
+ */
+export declare class UpstreamError extends AIError {
+    readonly providerId: string;
+    readonly status?: number | undefined;
+    readonly kind: "upstream";
+    constructor(providerId: string, message: string, status?: number | undefined, options?: {
+        cause?: unknown;
+    });
+}
+/** Type guard for {@link AIError} and any of its subclasses. */
+export declare const isAIError: (error: unknown) => error is AIError;

package/types/index.d.ts

@@ -0,0 +1,10 @@
+export type { AIProvider, AIModel, CompletionRequest } from './provider.js';
+export type { StreamEvent, Usage, FinishReason } from './stream-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 { Registry, type RegistryOptions, type ResolvedSlot } from './registry.js';

package/types/internal/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/internal/map-ai-sdk-stream.d.ts

@@ -0,0 +1,25 @@
+import type { StreamTextResult, ToolSet } from 'ai';
+import type { StreamEvent } from '../stream-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>;

package/types/key-store.d.ts

@@ -0,0 +1,45 @@
+export type KeyStoreOptions = {
+    /** Keyring service name. Defaults to `inkdrop.ai`. Override in tests. */
+    service?: string;
+};
+/**
+ * URL-keyed credential storage. The keyring entry's account is the *normalised*
+ * baseURL, not the provider id — so two endpoints to the same provider (e.g.
+ * staging + prod, or two Ollama hosts) get separate entries.
+ *
+ * Resolution order in {@link KeyStore.getKey}:
+ *   1. The provider's environment variable (if a name is given and the var is non-empty).
+ *   2. The system keyring (`@napi-rs/keyring`) under `service` + normalised `baseURL`.
+ *
+ * The cache is keyed on normalised `baseURL` to avoid repeated keyring round-trips.
+ * Cache reads do not check the env var — env-var changes mid-process are not
+ * reflected unless {@link KeyStore.invalidate} is called.
+ */
+export declare class KeyStore {
+    readonly service: string;
+    private readonly cache;
+    constructor(options?: KeyStoreOptions);
+    /**
+     * Resolves the API key for a given `baseURL`.
+     *
+     * @param envVarName - Provider's env-var name, or `null` to skip env lookup.
+     * @param baseURL - The endpoint URL. Normalised before keying.
+     * @returns The key, or `null` if neither env nor keyring has one.
+     */
+    getKey(envVarName: string | null, baseURL: string): Promise<string | null>;
+    /** Stores `key` for `baseURL` in the system keyring and the in-memory cache. */
+    setKey(baseURL: string, key: string): Promise<void>;
+    /**
+     * Removes the keyring entry for `baseURL` and drops it from the cache.
+     * No-ops if the entry doesn't exist.
+     */
+    deleteKey(baseURL: string): Promise<void>;
+    /**
+     * Drops cached entries.
+     *
+     * @param baseURL - When provided, only that URL's cached key is dropped;
+     * when omitted, the entire cache is cleared. Call this when the user
+     * changes a provider's `baseURL` so the next request re-resolves the key.
+     */
+    invalidate(baseURL?: string): void;
+}

package/types/provider.d.ts

@@ -0,0 +1,74 @@
+import type { CacheConfiguration, ModelCapabilities } from '@inkdropapp/ai-catalog';
+import type { ModelMessage } from 'ai';
+import type { StreamEvent } from './stream-events.js';
+/**
+ * Inputs for a single one-shot streaming completion.
+ *
+ * `messages` reuses the AI SDK's `ModelMessage` type so callers can construct
+ * messages with the same shape the underlying SDK expects.
+ */
+export type CompletionRequest = {
+    messages: ModelMessage[];
+    temperature?: number;
+    maxOutputTokens?: number;
+    /** Forwarded to the underlying SDK call; aborts in-flight HTTP and ends the stream. */
+    abortSignal?: AbortSignal;
+};
+/**
+ * A single configured model belonging to a provider.
+ *
+ * `capabilities` are the source of truth for whether a feature (tools, images,
+ * thinking) is available — UI gating and request-construction logic should
+ * branch on these flags rather than on `provider.id`.
+ */
+export interface AIModel {
+    /** Stable model id as the provider expects it on the wire. */
+    readonly id: string;
+    /** Human-readable label for menus / picker UIs. */
+    readonly displayName: string;
+    /** Back-reference to the owning provider. */
+    readonly provider: AIProvider;
+    readonly capabilities: ModelCapabilities;
+    /** Present when the provider supports prompt caching for this model (Anthropic). */
+    readonly cacheConfiguration?: CacheConfiguration;
+    /**
+     * Streams a completion. The returned iterable always terminates — either
+     * with a `'finish'` event on success, or with an `'error'` event on failure.
+     * Consumers do not need to wrap iteration in try/catch.
+     */
+    streamCompletion(request: CompletionRequest): AsyncIterable<StreamEvent>;
+}
+/**
+ * One AI integration (one auth identity + one base URL) exposing a list of
+ * `AIModel` instances. Multiple instances of the same provider class can
+ * coexist as long as their `id`s differ — that's how the long-tail
+ * OpenAI-compatible providers (OpenRouter, Together, Ollama, …) are modelled.
+ */
+export interface AIProvider {
+    /** Stable provider id; appears in `AISettings.slots[*].providerId`. */
+    readonly id: string;
+    /** Human-readable label. */
+    readonly name: string;
+    /** Resolved base URL for HTTP calls; doubles as the keyring account key. */
+    readonly baseURL: string;
+    /**
+     * Environment variable consulted before the keyring during auth resolution.
+     * `null` for providers that cannot have an env-var convention.
+     */
+    readonly envVarName: string | null;
+    listModels(): AIModel[];
+    getModel(id: string): AIModel | undefined;
+    /** "Best" model for long-form / general chat tasks. */
+    defaultModel(): AIModel | undefined;
+    /** Cheap / low-latency model for autocomplete-style features. */
+    defaultFastModel(): AIModel | undefined;
+    /**
+     * `true` iff a key is currently resolvable via env var or system keyring.
+     * Does not perform a network round-trip.
+     */
+    isAuthenticated(): Promise<boolean>;
+    /** Persists `key` to the system keyring under this provider's `baseURL`. */
+    setApiKey(key: string): Promise<void>;
+    /** Removes the keyring entry for this provider's `baseURL`. */
+    clearApiKey(): Promise<void>;
+}

package/types/providers/anthropic-models.d.ts

@@ -0,0 +1,30 @@
+import type { CacheConfiguration, ModelCapabilities } from '../capabilities.js';
+/** Static description of one Anthropic model. */
+export type AnthropicModelDescriptor = {
+    id: string;
+    displayName: string;
+    capabilities: ModelCapabilities;
+    cacheConfiguration: CacheConfiguration;
+};
+/**
+ * Default prompt-cache thresholds applied to every Anthropic model unless the
+ * user explicitly overrides them per model.
+ */
+export declare const DEFAULT_ANTHROPIC_CACHE_CONFIG: CacheConfiguration;
+/**
+ * Default capability flags for an Anthropic model. Used as the baseline for
+ * user-declared models; built-in entries override `maxTokens`/`maxOutputTokens`
+ * per model.
+ */
+export declare const DEFAULT_ANTHROPIC_CAPABILITIES: ModelCapabilities;
+/**
+ * Hard-coded catalogue of the Claude 4.x models the library ships with.
+ *
+ * Adding a model here makes it visible in `provider.listModels()` and to the
+ * picker UI. A user can also expose ids that aren't here by mapping them
+ * onto the SDK directly — but for an Inkdrop-grade BYOK experience, this
+ * built-in list is the supported surface.
+ */
+export declare const ANTHROPIC_MODELS: readonly AnthropicModelDescriptor[];
+export declare const DEFAULT_MODEL_ID = "claude-sonnet-4-6";
+export declare const DEFAULT_FAST_MODEL_ID = "claude-haiku-4-5";

package/types/providers/anthropic.d.ts

@@ -0,0 +1,41 @@
+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, 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 sdkClient;
+    private sdkClientApiKey;
+    constructor(keyStore: KeyStore, config?: AnthropicProviderConfig, catalog?: AnthropicCatalog);
+    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.d.ts

@@ -0,0 +1,59 @@
+import { type OpenAICompatibleProvider as SdkOpenAICompatibleProvider } from '@ai-sdk/openai-compatible';
+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, …).
+ *
+ * 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 sdkClient;
+    private sdkClientApiKey;
+    constructor(keyStore: KeyStore, config: OpenAICompatibleProviderConfig);
+    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/registry.d.ts

@@ -0,0 +1,98 @@
+import type { AIModelCatalog } from '@inkdropapp/ai-catalog';
+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;
+    model: AIModel;
+};
+export type RegistryOptions = {
+    settings: AISettings;
+    /**
+     * Optional server-distributed catalogue of supported models per provider.
+     * When omitted, each provider uses its compiled-in defaults (e.g. `ANTHROPIC_MODELS`).
+     * The host typically fetches this from an API and either passes it at
+     * construction time or swaps it in later via {@link Registry.updateCatalog}.
+     */
+    catalog?: AIModelCatalog;
+    /** Pass an existing `KeyStore` to share its in-memory cache across registries. */
+    keyStore?: KeyStore;
+};
+/**
+ * Top-level entrypoint to the library.
+ *
+ * Owns one instance of every configured provider, resolves task slots with
+ * fallback, and is the only place feature code calls to start a completion.
+ *
+ * The `Registry` is stateless beyond its provider list — it doesn't observe
+ * settings on its own. Call {@link Registry.updateSettings} when settings
+ * change to rebuild providers.
+ *
+ * @example
+ * ```ts
+ * const registry = new Registry({ settings })
+ * const events = await registry.streamCompletion('default', { messages })
+ * for await (const event of events) {
+ *   if (event.kind === 'text-delta') process.stdout.write(event.delta)
+ * }
+ * ```
+ */
+export declare class Registry {
+    readonly keyStore: KeyStore;
+    private providers;
+    private settings;
+    private catalog;
+    constructor(options: RegistryOptions);
+    /** All configured providers, sorted alphabetically by id. */
+    listProviders(): AIProvider[];
+    getProvider(id: string): AIProvider | undefined;
+    /** Flat list of every model across every provider. Useful for picker UIs. */
+    listAllModels(): {
+        provider: AIProvider;
+        model: AIModel;
+    }[];
+    /**
+     * Resolves a slot to a concrete `(provider, model)` pair.
+     *
+     * Order:
+     *   1. Explicit binding `settings.slots[slot]`, if both provider and model resolve.
+     *   2. For `'fast'` only: fall back to `settings.slots.default`.
+     *   3. First authenticated provider in alphabetical id order, taking that
+     *      provider's `defaultModel()` (or `defaultFastModel()` for the fast slot).
+     *      Mirrors Zed's `available_fallback_model` without the Zed-Cloud preference.
+     *   4. `undefined` if no provider can satisfy the slot.
+     *
+     * Async because the third step calls `provider.isAuthenticated()`, which may
+     * touch the keyring.
+     */
+    resolveSlot(slot: SlotName): Promise<ResolvedSlot | undefined>;
+    private tryBinding;
+    /**
+     * Streams a completion for a task slot.
+     *
+     * Resolves the slot via {@link Registry.resolveSlot}; throws {@link NoApiKey}
+     * if no provider can satisfy it (no slot binding, and no authenticated
+     * provider available for the implicit fallback). Otherwise returns the
+     * model's stream — note that *upstream* errors (auth, rate limit, etc.)
+     * arrive as `'error'` events inside the iterable, not as thrown exceptions.
+     */
+    streamCompletion(slot: SlotName, request: CompletionRequest): Promise<AsyncIterable<StreamEvent>>;
+    /**
+     * Replaces the active settings and rebuilds the provider list.
+     * The shared `KeyStore` cache is preserved.
+     */
+    updateSettings(next: AISettings): void;
+    /**
+     * Replaces the active model catalogue and rebuilds providers.
+     *
+     * Pass `undefined` to revert to providers' compiled-in defaults. Typical
+     * usage: app starts with no catalogue, fetches one from the server, then
+     * calls `updateCatalog(catalog)` once the response lands.
+     *
+     * The shared `KeyStore` cache and authentication state are preserved.
+     */
+    updateCatalog(next: AIModelCatalog | undefined): void;
+    private rebuildProviders;
+}

package/types/settings.d.ts

@@ -0,0 +1,94 @@
+import type { CacheConfiguration, ModelCapabilities } from '@inkdropapp/ai-catalog';
+/**
+ * Task-routing slot names.
+ *
+ * - `default` — long-form generation; the user's "main" model.
+ * - `fast` — latency-sensitive features (NES, quick rewrite, title suggest).
+ */
+export type SlotName = 'default' | 'fast';
+/** Explicit binding of a slot to a `(provider, model)` pair. */
+export type SlotConfig = {
+    providerId: string;
+    modelId: string;
+};
+/**
+ * Fields every provider config carries. Per-provider configs extend this
+ * to add provider-specific knobs (and may narrow `baseURL` to required when
+ * there's no sensible default).
+ */
+export type CommonProviderConfig = {
+    /** Endpoint root. Falls back to a provider-specific default when omitted. */
+    baseURL?: string;
+};
+/**
+ * One entry under an OpenAI-compatible provider's `models[]`. Capability flags
+ * are user-declared (a partial — sensible defaults are applied for fields the
+ * user omits).
+ */
+export type OpenAICompatibleModelConfig = {
+    id: string;
+    displayName?: string;
+    capabilities?: Partial<ModelCapabilities>;
+};
+/**
+ * One user-named OpenAI-compatible provider entry (e.g. `openrouter`,
+ * `together_ai`, `ollama_local`). Each becomes a separate `AIProvider`
+ * instance at runtime with its own keyring entry.
+ *
+ * `baseURL` is required here — there's no sensible default when the user is
+ * pointing at an arbitrary endpoint.
+ */
+export type OpenAICompatibleProviderConfig = CommonProviderConfig & {
+    id: string;
+    displayName?: string;
+    /** Endpoint root, e.g. `https://openrouter.ai/api/v1`. */
+    baseURL: string;
+    models: OpenAICompatibleModelConfig[];
+    /** Defaults to `models[0]` when omitted. */
+    defaultModelId?: string;
+    /** Defaults to `defaultModel()` when omitted. */
+    defaultFastModelId?: string;
+};
+/**
+ * One user-declared Anthropic model on top of the built-in Claude catalogue.
+ * Useful when Anthropic ships a new model id before this library does.
+ *
+ * If `id` matches a built-in model, this entry overrides it. Otherwise it's
+ * added to the catalogue.
+ */
+export type AnthropicModelConfig = {
+    id: string;
+    displayName?: string;
+    capabilities?: Partial<ModelCapabilities>;
+    cacheConfiguration?: CacheConfiguration;
+};
+/**
+ * Anthropic provider config.
+ *
+ * - `baseURL` is only needed for proxy / staging endpoints.
+ * - `models` adds (or overrides) Claude entries on top of the built-in
+ *   {@link ANTHROPIC_MODELS} catalogue.
+ *
+ * Default-model selection is *not* configured here — use `slots` at the top
+ * of `AISettings` to bind features to specific models.
+ */
+export type AnthropicProviderConfig = CommonProviderConfig & {
+    models?: AnthropicModelConfig[];
+};
+/**
+ * Top-level AI configuration. The host (Inkdrop main process) constructs this
+ * from whichever persistence layer it uses and passes it to `Registry`.
+ *
+ * The library never reads or writes settings to disk itself.
+ */
+export type AISettings = {
+    providers: {
+        anthropic?: AnthropicProviderConfig;
+        openaiCompatible?: OpenAICompatibleProviderConfig[];
+    };
+    /**
+     * Per-slot model overrides. Unset slots fall back to the first registered
+     * provider's `defaultModel` / `defaultFastModel`.
+     */
+    slots?: Partial<Record<SlotName, SlotConfig>>;
+};

package/types/stream-events.d.ts

@@ -0,0 +1,61 @@
+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;
+};

package/types/url.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Conservative baseURL normalisation for keying credential entries.
+ *
+ * Rules:
+ * - lowercase scheme + host
+ * - drop default port (`:443` for https, `:80` for http) for the matching scheme
+ * - strip a single trailing `/` from the path
+ *
+ * Path case, query, and fragment are preserved verbatim. Under-normalising
+ * splits keyring entries that should share a key; over-normalising merges
+ * entries that should be separate. The rules above are intentionally minimal.
+ *
+ * @throws if `input` is not a parseable absolute URL.
+ */
+export declare const normalizeBaseURL: (input: string) => string;