@theowlops/boombot 0.0.0-stage → 1.1.0

package/dist/node_modules/@boombot/protocol/providers/request-profile.js

@@ -0,0 +1,118 @@
+import { getProviderProfile, listProviderProfiles } from './profiles/index.js';
+/**
+ * Tier-1 default profile for a provider kind, read from the provider's
+ * declarative profile (e.g. Anthropic rejects requests without `max_tokens`,
+ * so its default lives in the profile, not as a magic constant).
+ * Unknown kinds get `{}` (fail-open: the caller validates the kind).
+ */
+export function kindDefaultProfile(kind) {
+    return getProviderProfile(kind)?.defaultProfile ?? {};
+}
+/**
+ * All tier-1 defaults, keyed by provider name. Built lazily from the
+ * registry so third-party `registerProvider()` calls are honored.
+ */
+export function allKindDefaultProfiles() {
+    const out = {};
+    for (const profile of listProviderProfiles()) {
+        out[profile.name] = profile.defaultProfile ?? {};
+    }
+    return out;
+}
+function isPlainRecord(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Recursively merge two JSON-ish records. Plain objects merge key-by-key to
+ * any depth; arrays, scalars and class instances are replaced wholesale;
+ * `undefined` values never overwrite. Shared by profile merging and by the
+ * request builder applying `extraBody` onto the wire body.
+ */
+export function deepMergeRecords(base, override) {
+    const out = { ...base };
+    for (const [key, value] of Object.entries(override)) {
+        if (value === undefined)
+            continue;
+        const prev = out[key];
+        out[key] = isPlainRecord(prev) && isPlainRecord(value) ? deepMergeRecords(prev, value) : value;
+    }
+    return out;
+}
+/** Copy only defined values from `override` onto a shallow clone of `base`. */
+function mergeDefined(base, override) {
+    const out = { ...(base ?? {}) };
+    for (const [key, value] of Object.entries(override)) {
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+/**
+ * Deep-merge request profiles left-to-right: later profiles win.
+ * See the module docstring for the exact merge rules.
+ */
+export function mergeRequestProfiles(...profiles) {
+    let out = {};
+    for (const profile of profiles) {
+        if (profile === undefined)
+            continue;
+        if (profile.maxTokens !== undefined)
+            out = { ...out, maxTokens: profile.maxTokens };
+        if (profile.temperature !== undefined)
+            out = { ...out, temperature: profile.temperature };
+        if (profile.topP !== undefined)
+            out = { ...out, topP: profile.topP };
+        if (profile.headers !== undefined) {
+            out = { ...out, headers: mergeDefined(out.headers, { ...profile.headers }) };
+        }
+        if (profile.extraBody !== undefined) {
+            out = { ...out, extraBody: deepMergeRecords(out.extraBody ?? {}, profile.extraBody) };
+        }
+        if (profile.reasoning !== undefined) {
+            out = { ...out, reasoning: mergeDefined(out.reasoning, { ...profile.reasoning }) };
+        }
+    }
+    return out;
+}
+/**
+ * Resolve the effective request profile for one model:
+ * kind defaults < provider.extra < provider.modelProfiles[model].
+ */
+export function resolveRequestProfile(kind, providerExtra, modelProfiles, model) {
+    return mergeRequestProfiles(kindDefaultProfile(kind), providerExtra, modelProfiles?.[model]);
+}
+/** Structural check used by the provider service when validating stored/wire input. */
+export function isRequestProfile(value) {
+    if (!isPlainRecord(value))
+        return false;
+    const v = value;
+    if (v['maxTokens'] !== undefined && (typeof v['maxTokens'] !== 'number' || !Number.isInteger(v['maxTokens']) || v['maxTokens'] <= 0))
+        return false;
+    if (v['temperature'] !== undefined && (typeof v['temperature'] !== 'number' || Number.isNaN(v['temperature']) || v['temperature'] < 0))
+        return false;
+    if (v['topP'] !== undefined && (typeof v['topP'] !== 'number' || Number.isNaN(v['topP']) || v['topP'] < 0 || v['topP'] > 1))
+        return false;
+    if (v['headers'] !== undefined) {
+        if (!isPlainRecord(v['headers']))
+            return false;
+        for (const headerValue of Object.values(v['headers'])) {
+            if (typeof headerValue !== 'string')
+                return false;
+        }
+    }
+    if (v['extraBody'] !== undefined && !isPlainRecord(v['extraBody']))
+        return false;
+    if (v['reasoning'] !== undefined) {
+        if (!isPlainRecord(v['reasoning']))
+            return false;
+        const r = v['reasoning'];
+        if (r['effort'] !== undefined && (typeof r['effort'] !== 'string' || r['effort'].length === 0))
+            return false;
+        if (r['budgetTokens'] !== undefined && (typeof r['budgetTokens'] !== 'number' || !Number.isInteger(r['budgetTokens']) || r['budgetTokens'] <= 0))
+            return false;
+    }
+    return true;
+}

package/dist/node_modules/@boombot/protocol/providers/service.d.ts

@@ -0,0 +1,2 @@
+import { type ProviderService, type ProviderServiceOptions } from './types.js';
+export declare function createProviderService(options: ProviderServiceOptions): ProviderService;

package/dist/node_modules/@boombot/protocol/providers/service.js

@@ -0,0 +1,418 @@
+/**
+ * File-backed `ProviderService` implementation.
+ *
+ * State lives in a single JSON file (`{ version: 3, providers: [...] }`).
+ * v1 stores are migrated on load (the default chat `model` is derived from
+ * the first discovered model); v2 stores are migrated to the v3 key ring
+ * (the single `apiKeyCipher` becomes `apiKeyCiphers: [cipher]`). API keys are
+ * stored AES-256-GCM encrypted (see `cipher.ts`); the file is
+ * chmodded 0600 whenever it holds secret material (best-effort on Windows).
+ * Writes are atomic (temp file + rename) so a crashed process never leaves a
+ * half-written registry.
+ */
+import { randomUUID } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from 'node:fs';
+import { dirname } from 'node:path';
+import { decryptSecret, encryptSecret } from './cipher.js';
+import { defaultBaseUrlFor } from './probe.js';
+import { getProviderProfile, listProviderProfiles } from './profiles/index.js';
+import { isRequestProfile } from './request-profile.js';
+import { ProviderError, } from './types.js';
+const STORE_VERSION = 3;
+/** Oldest store version `load()` still reads (migrated forward on load). */
+const STORE_VERSION_MIN = 1;
+/** Sanity cap on the key ring: rotation is for a handful of keys, not hundreds. */
+const MAX_API_KEYS_PER_PROVIDER = 32;
+/**
+ * A kind is valid when a profile is registered for it — built-ins plus any
+ * user-defined custom providers (`custom-providers.json`). Registry-aware so
+ * custom kinds work without touching this file.
+ */
+function isProviderKind(value) {
+    return typeof value === 'string' && getProviderProfile(value) !== undefined;
+}
+function validateApiKeys(apiKeys) {
+    if (apiKeys.length > MAX_API_KEYS_PER_PROVIDER) {
+        throw new ProviderError('VALIDATION', `apiKeys holds at most ${MAX_API_KEYS_PER_PROVIDER} keys (got ${apiKeys.length}).`);
+    }
+    if (apiKeys.some((key) => typeof key !== 'string' || key.length === 0)) {
+        throw new ProviderError('VALIDATION', 'apiKeys must be an array of non-empty strings.');
+    }
+}
+function validateRequestProfileField(value, field) {
+    if (!isRequestProfile(value)) {
+        throw new ProviderError('VALIDATION', `'${field}' is not a valid request profile.`);
+    }
+}
+function validateModelProfiles(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new ProviderError('VALIDATION', "'modelProfiles' must be an object keyed by model id.");
+    }
+    for (const [model, profile] of Object.entries(value)) {
+        if (model.length === 0) {
+            throw new ProviderError('VALIDATION', "'modelProfiles' keys must be non-empty model ids.");
+        }
+        validateRequestProfileField(profile, `modelProfiles['${model}']`);
+    }
+}
+function validateInput(input) {
+    if (typeof input.name !== 'string' || input.name.trim().length === 0) {
+        throw new ProviderError('VALIDATION', 'Provider name must be a non-empty string.');
+    }
+    if (!isProviderKind(input.kind)) {
+        throw new ProviderError('VALIDATION', `Unknown provider kind '${String(input.kind)}'. Expected one of: ${listProviderProfiles()
+            .map((p) => p.name)
+            .join(', ')}.`);
+    }
+    if (input.baseUrl !== undefined) {
+        let url;
+        try {
+            url = new URL(input.baseUrl);
+        }
+        catch {
+            throw new ProviderError('VALIDATION', `Invalid baseUrl '${input.baseUrl}'.`);
+        }
+        if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+            throw new ProviderError('VALIDATION', 'baseUrl must use http(s).');
+        }
+    }
+    if (input.models !== undefined) {
+        if (!Array.isArray(input.models) || input.models.some((m) => typeof m !== 'string' || m.length === 0)) {
+            throw new ProviderError('VALIDATION', 'models must be an array of non-empty strings.');
+        }
+    }
+    if (input.model !== undefined && (typeof input.model !== 'string' || input.model.length === 0)) {
+        throw new ProviderError('VALIDATION', 'model must be a non-empty string.');
+    }
+    if (input.apiKey !== undefined && input.apiKeys !== undefined) {
+        throw new ProviderError('VALIDATION', "Pass either 'apiKey' or 'apiKeys', not both.");
+    }
+    if (input.apiKey !== undefined && typeof input.apiKey !== 'string') {
+        throw new ProviderError('VALIDATION', 'apiKey must be a string.');
+    }
+    if (input.apiKeys !== undefined)
+        validateApiKeys(input.apiKeys);
+    if (input.extra !== undefined)
+        validateRequestProfileField(input.extra, 'extra');
+    if (input.modelProfiles !== undefined)
+        validateModelProfiles(input.modelProfiles);
+}
+/** Decrypted ring size for activation checks (stored entries may be legacy). */
+function ringSize(provider) {
+    return provider.apiKeyCiphers?.length ?? (provider.apiKeyCipher !== undefined ? 1 : 0);
+}
+function activationIssue(provider) {
+    if (!provider.baseUrl && defaultBaseUrlFor(provider.kind) === null) {
+        return `Provider kind '${provider.kind}' requires a baseUrl.`;
+    }
+    if (!provider.model && !provider.models?.[0]) {
+        return 'Provider requires a default model.';
+    }
+    if (provider.kind !== 'local' && ringSize(provider) === 0) {
+        return 'Provider requires an API key.';
+    }
+    return null;
+}
+function assertActivatable(provider) {
+    const issue = activationIssue(provider);
+    if (issue !== null)
+        throw new ProviderError('VALIDATION', issue);
+}
+function isStoredProvider(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    return (typeof v['id'] === 'string' &&
+        typeof v['name'] === 'string' &&
+        isProviderKind(v['kind']) &&
+        typeof v['active'] === 'boolean' &&
+        (v['model'] === undefined || typeof v['model'] === 'string') &&
+        (v['apiKeyCiphers'] === undefined ||
+            (Array.isArray(v['apiKeyCiphers']) && v['apiKeyCiphers'].every((c) => typeof c === 'string'))) &&
+        (v['keyCursor'] === undefined ||
+            (typeof v['keyCursor'] === 'number' && Number.isInteger(v['keyCursor']) && v['keyCursor'] >= 0)) &&
+        (v['extra'] === undefined || isRequestProfile(v['extra'])) &&
+        (v['modelProfiles'] === undefined ||
+            (typeof v['modelProfiles'] === 'object' &&
+                v['modelProfiles'] !== null &&
+                !Array.isArray(v['modelProfiles']) &&
+                Object.values(v['modelProfiles']).every((p) => isRequestProfile(p)))));
+}
+/**
+ * Migrate a v1 stored provider to v2: the default chat model becomes an
+ * explicit field. v1 only had the discovered `models` list (whose first
+ * entry the setup wizard / probe used as the de-facto default), so the
+ * migration preserves that meaning instead of dropping it.
+ */
+function migrateV1ToV2(entry) {
+    if (entry.model !== undefined)
+        return entry;
+    const firstModel = entry.models?.[0];
+    return firstModel === undefined ? entry : { ...entry, model: firstModel };
+}
+/**
+ * Migrate a v2 stored provider to v3: the single `apiKeyCipher` becomes a
+ * one-entry `apiKeyCiphers` ring, and the rotation cursor starts at 0.
+ */
+function migrateV2ToV3(entry) {
+    const { apiKeyCipher, ...rest } = entry;
+    return {
+        ...rest,
+        ...(apiKeyCipher !== undefined ? { apiKeyCiphers: [apiKeyCipher] } : {}),
+        keyCursor: entry.keyCursor ?? 0,
+    };
+}
+export function createProviderService(options) {
+    const { storagePath, masterKey } = options;
+    if (typeof storagePath !== 'string' || storagePath.length === 0) {
+        throw new ProviderError('VALIDATION', 'storagePath must be a non-empty string.');
+    }
+    if (typeof masterKey !== 'string' || masterKey.length === 0) {
+        throw new ProviderError('VALIDATION', 'masterKey must be a non-empty string.');
+    }
+    const providers = new Map();
+    let loaded = false;
+    function assertLoaded() {
+        if (!loaded)
+            throw new ProviderError('STORAGE', 'ProviderService.load() must be called first.');
+    }
+    function toPublic(stored) {
+        const ciphers = stored.apiKeyCiphers ?? [];
+        return {
+            id: stored.id,
+            name: stored.name,
+            kind: stored.kind,
+            ...(stored.baseUrl !== undefined ? { baseUrl: stored.baseUrl } : {}),
+            hasKey: ciphers.length > 0,
+            keyCount: ciphers.length,
+            ...(stored.keyCursor !== undefined ? { keyCursor: stored.keyCursor } : {}),
+            active: stored.active,
+            ...(stored.model !== undefined ? { model: stored.model } : {}),
+            ...(stored.models !== undefined ? { models: [...stored.models] } : {}),
+            ...(stored.extra !== undefined ? { extra: stored.extra } : {}),
+            ...(stored.modelProfiles !== undefined ? { modelProfiles: { ...stored.modelProfiles } } : {}),
+        };
+    }
+    function getStoredOrThrow(id) {
+        const stored = providers.get(id);
+        if (!stored)
+            throw new ProviderError('NOT_FOUND', `Provider '${id}' not found.`);
+        return stored;
+    }
+    async function persist() {
+        const file = { version: STORE_VERSION, providers: [...providers.values()] };
+        mkdirSync(dirname(storagePath), { recursive: true });
+        const tmpPath = `${storagePath}.tmp`;
+        writeFileSync(tmpPath, JSON.stringify(file, null, 2), 'utf8');
+        const holdsSecrets = [...providers.values()].some((p) => (p.apiKeyCiphers?.length ?? 0) > 0);
+        if (holdsSecrets) {
+            try {
+                chmodSync(tmpPath, 0o600);
+            }
+            catch {
+                // Best effort: Windows has no POSIX permission bits (chmodSync is a
+                // no-op for ACLs), so the store is NOT OS-protected there.
+                // See SECURITY.md §5.
+            }
+        }
+        renameSync(tmpPath, storagePath);
+    }
+    async function load() {
+        providers.clear();
+        if (!existsSync(storagePath)) {
+            loaded = true;
+            return;
+        }
+        let raw;
+        try {
+            raw = readFileSync(storagePath, 'utf8');
+        }
+        catch (err) {
+            throw new ProviderError('STORAGE', `Cannot read provider store at '${storagePath}': ${err instanceof Error ? err.message : String(err)}`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            throw new ProviderError('STORAGE', `Provider store at '${storagePath}' is not valid JSON.`);
+        }
+        if (typeof parsed !== 'object' || parsed === null) {
+            throw new ProviderError('STORAGE', `Provider store at '${storagePath}' has an unexpected shape.`);
+        }
+        const file = parsed;
+        if (typeof file.version !== 'number' ||
+            file.version < STORE_VERSION_MIN ||
+            file.version > STORE_VERSION ||
+            !Array.isArray(file.providers)) {
+            throw new ProviderError('STORAGE', `Provider store at '${storagePath}' has an unsupported version (expected ${STORE_VERSION_MIN}–${STORE_VERSION}).`);
+        }
+        const fileVersion = file.version;
+        for (const entry of file.providers) {
+            if (!isStoredProvider(entry)) {
+                throw new ProviderError('STORAGE', `Provider store at '${storagePath}' contains an invalid entry.`);
+            }
+            let stored = { ...entry };
+            if (fileVersion === 1)
+                stored = migrateV1ToV2(stored);
+            if (fileVersion <= 2)
+                stored = migrateV2ToV3(stored);
+            providers.set(entry.id, stored);
+        }
+        loaded = true;
+        const active = [...providers.values()].find((provider) => provider.active);
+        let repaired = false;
+        if (active !== undefined && activationIssue(active) !== null) {
+            for (const provider of providers.values())
+                provider.active = false;
+            const replacement = [...providers.values()].find((provider) => activationIssue(provider) === null);
+            if (replacement !== undefined)
+                replacement.active = true;
+            repaired = true;
+        }
+        if (fileVersion < STORE_VERSION || repaired) {
+            // Upgrade the file on disk so the next load is clean.
+            await persist();
+        }
+    }
+    async function list() {
+        assertLoaded();
+        return [...providers.values()].map(toPublic);
+    }
+    /**
+     * Resolve the key-ring update for a `save()`: `apiKey` (single) and
+     * `apiKeys` (ring) are mutually exclusive and both replace the whole ring.
+     * Returns `undefined` when the input carries no key fields (keep stored).
+     */
+    function resolveKeyRingUpdate(input) {
+        if (input.apiKey !== undefined) {
+            return input.apiKey.length > 0 ? [encryptSecret(masterKey, input.apiKey)] : [];
+        }
+        if (input.apiKeys !== undefined) {
+            return input.apiKeys.map((key) => encryptSecret(masterKey, key));
+        }
+        return undefined;
+    }
+    async function save(input) {
+        assertLoaded();
+        validateInput(input);
+        const existing = input.id !== undefined ? providers.get(input.id) : undefined;
+        if (existing) {
+            const updated = { ...existing, name: input.name, kind: input.kind };
+            if (input.baseUrl !== undefined)
+                updated.baseUrl = input.baseUrl;
+            if (input.model !== undefined)
+                updated.model = input.model;
+            if (input.models !== undefined)
+                updated.models = [...input.models];
+            const ring = resolveKeyRingUpdate(input);
+            if (ring !== undefined) {
+                updated.apiKeyCiphers = ring;
+                delete updated.apiKeyCipher;
+                // Keep the cursor inside the new ring.
+                updated.keyCursor = ring.length > 0 ? (updated.keyCursor ?? 0) % ring.length : 0;
+            }
+            if (input.extra !== undefined)
+                updated.extra = { ...input.extra };
+            if (input.modelProfiles !== undefined) {
+                updated.modelProfiles = Object.fromEntries(Object.entries(input.modelProfiles).map(([model, profile]) => [model, { ...profile }]));
+            }
+            updated.active = input.active ?? existing.active;
+            if (updated.active)
+                assertActivatable(updated);
+            providers.set(existing.id, updated);
+            if (updated.active) {
+                for (const p of providers.values())
+                    p.active = p.id === updated.id;
+            }
+            await persist();
+            return toPublic(updated);
+        }
+        const id = input.id ?? randomUUID();
+        if (providers.has(id)) {
+            // Practically unreachable (randomUUID collision), but fail loudly.
+            throw new ProviderError('VALIDATION', `Provider id '${id}' is already taken.`);
+        }
+        const ring = resolveKeyRingUpdate(input) ?? [];
+        const stored = {
+            id,
+            name: input.name,
+            kind: input.kind,
+            ...(input.baseUrl !== undefined ? { baseUrl: input.baseUrl } : {}),
+            ...(ring.length > 0 ? { apiKeyCiphers: ring, keyCursor: 0 } : {}),
+            active: input.active ?? false,
+            ...(input.model !== undefined ? { model: input.model } : {}),
+            ...(input.models !== undefined ? { models: [...input.models] } : {}),
+            ...(input.extra !== undefined ? { extra: { ...input.extra } } : {}),
+            ...(input.modelProfiles !== undefined
+                ? {
+                    modelProfiles: Object.fromEntries(Object.entries(input.modelProfiles).map(([model, profile]) => [model, { ...profile }])),
+                }
+                : {}),
+        };
+        if (input.active === true)
+            assertActivatable(stored);
+        if (input.active === undefined && ![...providers.values()].some((p) => p.active)) {
+            stored.active = activationIssue(stored) === null;
+        }
+        if (stored.active) {
+            for (const p of providers.values())
+                p.active = false;
+        }
+        providers.set(id, stored);
+        await persist();
+        return toPublic(stored);
+    }
+    function decryptRing(stored) {
+        const ciphers = stored.apiKeyCiphers ?? [];
+        try {
+            return ciphers.map((cipher) => decryptSecret(masterKey, cipher));
+        }
+        catch {
+            throw new ProviderError('STORAGE', `Stored API key for provider '${stored.id}' cannot be decrypted (wrong master key?).`);
+        }
+    }
+    async function getApiKey(id) {
+        assertLoaded();
+        const stored = getStoredOrThrow(id);
+        const keys = decryptRing(stored);
+        if (keys.length === 0)
+            return null;
+        // The cursor key is the ring's current head; fall back to the first key
+        // when the persisted cursor somehow points past the ring.
+        const cursor = stored.keyCursor ?? 0;
+        return keys[((cursor % keys.length) + keys.length) % keys.length] ?? keys[0] ?? null;
+    }
+    async function getApiKeys(id) {
+        assertLoaded();
+        return decryptRing(getStoredOrThrow(id));
+    }
+    async function setKeyCursor(id, cursor) {
+        assertLoaded();
+        const stored = getStoredOrThrow(id);
+        const size = stored.apiKeyCiphers?.length ?? 0;
+        stored.keyCursor = size > 0 ? ((cursor % size) + size) % size : 0;
+        await persist();
+    }
+    async function activate(id) {
+        assertLoaded();
+        const stored = getStoredOrThrow(id);
+        assertActivatable(stored);
+        for (const p of providers.values())
+            p.active = p.id === stored.id;
+        await persist();
+        return toPublic(stored);
+    }
+    async function deleteProvider(id) {
+        assertLoaded();
+        const stored = getStoredOrThrow(id);
+        providers.delete(id);
+        if (stored.active) {
+            const next = [...providers.values()].find((provider) => activationIssue(provider) === null);
+            if (next !== undefined)
+                next.active = true;
+        }
+        await persist();
+    }
+    return { load, list, save, getApiKey, getApiKeys, setKeyCursor, activate, delete: deleteProvider };
+}

package/dist/node_modules/@boombot/protocol/providers/types.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Public types for `@boombot/protocol`.
+ *
+ * These shapes intentionally mirror the provider wire schemas in
+ * `@boombot/protocol` (`providerSchema` / `providerInputSchema`)
+ * structurally, without depending on that package: the gateway parses the
+ * wire payload with zod and hands the result straight to `ProviderService`.
+ * Keeping this package dependency-free (node builtins only) makes it a leaf
+ * the gateway, CLI and tools can all share.
+ */
+import type { RequestProfile } from './request-profile.js';
+/** LLM provider kinds. Must stay in sync with `providerKindSchema` in `@boombot/protocol`. */
+export type ProviderKind = 'openai' | 'anthropic' | 'google' | 'mistral' | 'xai' | 'deepseek' | 'openai-compatible' | 'local';
+/**
+ * All known provider kinds, derived from the profile registry
+ * (`./profiles/`). The registry is the single source of truth; this list
+ * stays in sync automatically as providers are added.
+ */
+export declare const PROVIDER_KINDS: readonly ProviderKind[];
+/**
+ * Provider record as exposed to callers. API keys are NEVER present here —
+ * `hasKey`/`keyCount` only report whether keys are stored. Matches the wire
+ * `providerSchema` (minus nothing, plus nothing).
+ */
+export interface Provider {
+    readonly id: string;
+    readonly name: string;
+    readonly kind: ProviderKind;
+    readonly baseUrl?: string;
+    readonly hasKey: boolean;
+    /** Number of API keys in the provider's key ring (KeyRoulette). */
+    readonly keyCount: number;
+    /**
+     * Key-rotation cursor: index of the key the ring tries first. Operational
+     * state only, no secret material.
+     */
+    readonly keyCursor?: number;
+    readonly active: boolean;
+    /**
+     * Default chat model used for turns. Explicit, and — unlike `models` —
+     * never overwritten by `provider.test` discovery.
+     */
+    readonly model?: string;
+    /**
+     * Mutable on purpose: matches the wire `providerSchema` (`models?: string[]`)
+     * so handler responses typecheck without casts.
+     */
+    readonly models?: string[];
+    /**
+     * Provider-level request profile (tier 2 of 3: kind defaults <
+     * `extra` < per-model override). Applies to every model of this provider.
+     */
+    readonly extra?: RequestProfile;
+    /**
+     * Per-model request profile overrides (tier 3 of 3), keyed by model id.
+     * Wins over `extra` and the kind defaults for that one model.
+     */
+    readonly modelProfiles?: Readonly<Record<string, RequestProfile>>;
+}
+/**
+ * Input accepted by `ProviderService.save`. Mirrors the wire
+ * `providerInputSchema`: `apiKey`/`apiKeys` are write-only (stored
+ * encrypted), everything else is a plain field update. Omitted optional
+ * fields keep their stored value on update; pass `apiKey: ''` (or
+ * `apiKeys: []`) to explicitly clear the stored key ring.
+ */
+export interface ProviderInput {
+    readonly id?: string;
+    readonly name: string;
+    readonly kind: ProviderKind;
+    readonly baseUrl?: string;
+    /** Default chat model for turns. Omitted on update = keep the stored value. */
+    readonly model?: string;
+    readonly models?: readonly string[];
+    readonly apiKey?: string;
+    /**
+     * Replace the whole key ring. Mutually exclusive with `apiKey` — passing
+     * both is a validation error.
+     */
+    readonly apiKeys?: readonly string[];
+    /** Provider-level request profile (tier 2). Omitted on update = keep. */
+    readonly extra?: RequestProfile;
+    /** Per-model profile overrides (tier 3). Omitted on update = keep. */
+    readonly modelProfiles?: Readonly<Record<string, RequestProfile>>;
+    readonly active?: boolean;
+}
+export interface ProviderServiceOptions {
+    /** JSON file the registry persists to, e.g. `<dataDir>/providers.json`. */
+    readonly storagePath: string;
+    /**
+     * Master secret used to encrypt API keys at rest (AES-256-GCM, key derived
+     * via SHA-256). Keep it in an env var (`BOOMBOT_MASTER_KEY`), never in the file.
+     */
+    readonly masterKey: string;
+}
+/** Error thrown by `ProviderService` for expected failure modes. */
+export declare class ProviderError extends Error {
+    readonly code: 'NOT_FOUND' | 'VALIDATION' | 'STORAGE';
+    constructor(code: ProviderError['code'], message: string);
+}
+/**
+ * CRUD + key vault for LLM provider configs. At most one provider is active;
+ * `activate()` enforces that it is complete enough to serve turns.
+ */
+export interface ProviderService {
+    /** Load persisted state from `storagePath`. Must be called before any other method. */
+    load(): Promise<void>;
+    /** All providers, newest-last, without secret material. */
+    list(): Promise<Provider[]>;
+    /** Create or update a provider. `apiKey`/`apiKeys` are write-only. */
+    save(input: ProviderInput): Promise<Provider>;
+    /** Decrypted API key, or `null` when none is stored. */
+    getApiKey(id: string): Promise<string | null>;
+    /**
+     * All decrypted API keys for a provider, in ring order. Empty when none
+     * is stored. KeyRoulette rotates through these on 401/429.
+     */
+    getApiKeys(id: string): Promise<string[]>;
+    /**
+     * Persist the key-rotation cursor (called by KeyRoulette when a key
+     * fails so rotation survives restarts).
+     */
+    setKeyCursor(id: string, cursor: number): Promise<void>;
+    /** Make exactly this provider active. */
+    activate(id: string): Promise<Provider>;
+    /** Remove a provider. If it was active, the oldest remaining becomes active. */
+    delete(id: string): Promise<void>;
+}
+/** Options for {@link probeProvider}. */
+export interface ProbeOptions {
+    readonly kind: ProviderKind;
+    readonly baseUrl?: string;
+}
+/** Result of {@link probeProvider}. */
+export interface ProbeResult {
+    readonly ok: boolean;
+    /** Model ids discovered via the provider's models catalog, when available. */
+    readonly models?: string[];
+    /** Human-readable failure reason. Never contains secret material. */
+    readonly error?: string;
+}