@theowlops/boombot 0.0.0-stage → 1.1.1

package/dist/node_modules/@boombot/protocol/providers/profiles/custom.js

@@ -0,0 +1,222 @@
+/**
+ * User-defined custom providers (Hermes-style `$HERMES_HOME/plugins/`).
+ *
+ * Users declare fully custom LLM providers in `<configDir>/custom-providers.json`
+ * (e.g. `~/.boombot/custom-providers.json`). Entries are validated — invalid
+ * ones are skipped with a warning, never fatal — and registered into the
+ * profile registry, so they appear in `provider.list` and work with the LLM
+ * client exactly like built-ins.
+ *
+ * This module is intentionally NOT imported by `./index.js`: the registry
+ * must stay importable without touching the filesystem. Callers
+ * (`agent-worker` startup) import this module directly and call
+ * `registerCustomProviders()`.
+ *
+ * Boundary: leaf package — node builtins only, no `@boombot/*` imports.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getProviderProfile, registerProvider } from './index.js';
+/** File name (inside the config dir) holding user-defined providers. */
+export const CUSTOM_PROVIDERS_FILE = 'custom-providers.json';
+/** Provider names: lowercase letters, digits, hyphens. */
+const NAME_PATTERN = /^[a-z0-9-]+$/u;
+const API_MODES = [
+    'chat_completions',
+    'anthropic_messages',
+];
+const AUTH_STYLES = ['bearer', 'x-api-key'];
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+/**
+ * Validate one raw entry. Returns the profile, or `undefined` (after warning)
+ * when the entry is unusable.
+ */
+function validateOne(raw, index, onWarn) {
+    const where = `${CUSTOM_PROVIDERS_FILE}[providers][${index}]`;
+    if (!isRecord(raw)) {
+        onWarn(`${where}: entry must be an object, skipping.`);
+        return undefined;
+    }
+    // --- name (required, unique, pattern) ---
+    const name = raw['name'];
+    if (!isNonEmptyString(name) || !NAME_PATTERN.test(name)) {
+        onWarn(`${where}: 'name' must match /^[a-z0-9-]+$/ (lowercase, digits, hyphens), skipping.`, { name: typeof name === 'string' ? name : undefined });
+        return undefined;
+    }
+    if (getProviderProfile(name) !== undefined) {
+        onWarn(`${where}: name '${name}' collides with an already-registered provider, skipping.`);
+        return undefined;
+    }
+    // --- apiMode (required) ---
+    const apiMode = raw['apiMode'];
+    if (typeof apiMode !== 'string' ||
+        !API_MODES.includes(apiMode)) {
+        onWarn(`${where}: 'apiMode' must be one of: ${API_MODES.join(', ')}. Skipping '${name}'.`);
+        return undefined;
+    }
+    // --- keyless / defaultBaseUrl ---
+    const keyless = raw['keyless'] === true;
+    const defaultBaseUrl = raw['defaultBaseUrl'];
+    if (!keyless) {
+        if (!isNonEmptyString(defaultBaseUrl)) {
+            onWarn(`${where}: 'defaultBaseUrl' is required for '${name}' (or set 'keyless': true), skipping.`);
+            return undefined;
+        }
+        try {
+            new URL(defaultBaseUrl);
+        }
+        catch {
+            onWarn(`${where}: 'defaultBaseUrl' is not a valid URL for '${name}', skipping.`, { defaultBaseUrl });
+            return undefined;
+        }
+    }
+    else if (defaultBaseUrl !== undefined &&
+        defaultBaseUrl !== null &&
+        typeof defaultBaseUrl !== 'string') {
+        onWarn(`${where}: 'defaultBaseUrl' must be a string when present for '${name}', skipping.`);
+        return undefined;
+    }
+    // --- authStyle (optional, defaults to bearer) ---
+    const authStyle = raw['authStyle'] ?? 'bearer';
+    if (typeof authStyle !== 'string' ||
+        !AUTH_STYLES.includes(authStyle)) {
+        onWarn(`${where}: 'authStyle' must be one of: ${AUTH_STYLES.join(', ')}. Skipping '${name}'.`);
+        return undefined;
+    }
+    // --- defaultModel (required) ---
+    const defaultModel = raw['defaultModel'];
+    if (!isNonEmptyString(defaultModel)) {
+        onWarn(`${where}: 'defaultModel' must be a non-empty string for '${name}', skipping.`);
+        return undefined;
+    }
+    // --- aliases (optional) ---
+    let aliases;
+    const rawAliases = raw['aliases'];
+    if (rawAliases !== undefined) {
+        if (!Array.isArray(rawAliases)) {
+            onWarn(`${where}: 'aliases' must be an array of strings for '${name}', skipping.`);
+            return undefined;
+        }
+        const clean = [];
+        for (const alias of rawAliases) {
+            if (typeof alias !== 'string' || !NAME_PATTERN.test(alias)) {
+                onWarn(`${where}: alias must match /^[a-z0-9-]+$/ for '${name}', dropping alias.`, { alias });
+                continue;
+            }
+            if (getProviderProfile(alias) !== undefined) {
+                onWarn(`${where}: alias '${alias}' collides with an existing provider for '${name}', dropping alias.`);
+                continue;
+            }
+            clean.push(alias);
+        }
+        if (clean.length > 0)
+            aliases = clean;
+    }
+    // --- authVersionHeader (optional, only meaningful for x-api-key) ---
+    let authVersionHeader;
+    const rawVersionHeader = raw['authVersionHeader'];
+    if (rawVersionHeader !== undefined) {
+        if (!isRecord(rawVersionHeader) ||
+            !isNonEmptyString(rawVersionHeader['name']) ||
+            !isNonEmptyString(rawVersionHeader['value'])) {
+            onWarn(`${where}: 'authVersionHeader' must be { name, value } strings for '${name}', skipping.`);
+            return undefined;
+        }
+        authVersionHeader = {
+            name: rawVersionHeader['name'],
+            value: rawVersionHeader['value'],
+        };
+    }
+    // --- optional string fields ---
+    const displayName = isNonEmptyString(raw['displayName']) ? raw['displayName'] : name;
+    const description = isNonEmptyString(raw['description'])
+        ? raw['description']
+        : undefined;
+    const defaultEmbeddingModel = isNonEmptyString(raw['defaultEmbeddingModel'])
+        ? raw['defaultEmbeddingModel']
+        : undefined;
+    return {
+        // Custom names are not members of the `ProviderKind` union by construction;
+        // the registry is string-keyed at runtime, so the cast is contained here.
+        name: name,
+        displayName,
+        apiMode: apiMode,
+        defaultBaseUrl: typeof defaultBaseUrl === 'string' ? defaultBaseUrl : null,
+        aliases,
+        authStyle: authStyle,
+        authVersionHeader,
+        defaultModel,
+        defaultEmbeddingModel,
+        keyless: keyless ? true : undefined,
+        requestUsage: raw['requestUsage'] === true ? true : undefined,
+        description,
+    };
+}
+/**
+ * Read and validate `<configDir>/custom-providers.json`.
+ *
+ * Returns the valid profiles (possibly empty). A missing file is not an
+ * error — it just means the user defined no custom providers. Malformed
+ * JSON or invalid entries produce warnings via `onWarn` and are skipped;
+ * this function never throws for user-data problems.
+ */
+export function loadCustomProviders(configDir, onWarn = () => { }) {
+    const path = join(configDir, CUSTOM_PROVIDERS_FILE);
+    if (!existsSync(path))
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (error) {
+        onWarn(`Could not parse ${CUSTOM_PROVIDERS_FILE}: ${error instanceof Error ? error.message : String(error)}. Skipping custom providers.`);
+        return [];
+    }
+    const list = isRecord(parsed) && Array.isArray(parsed['providers'])
+        ? parsed['providers']
+        : null;
+    if (list === null) {
+        onWarn(`${CUSTOM_PROVIDERS_FILE}: expected { "providers": [...] }. Skipping custom providers.`);
+        return [];
+    }
+    const out = [];
+    const seenInFile = new Set();
+    list.forEach((raw, index) => {
+        const profile = validateOne(raw, index, onWarn);
+        if (profile === undefined)
+            return;
+        const key = profile.name.toLowerCase();
+        if (seenInFile.has(key)) {
+            onWarn(`${CUSTOM_PROVIDERS_FILE}[providers][${index}]: duplicate name '${profile.name}' in file, skipping.`);
+            return;
+        }
+        seenInFile.add(key);
+        out.push(profile);
+    });
+    return out;
+}
+/**
+ * Load custom providers from `<configDir>/custom-providers.json` and register
+ * them into the profile registry. Returns the number successfully registered.
+ *
+ * Never throws for user-data problems — invalid entries are skipped with a
+ * warning. Registration itself is best-effort for the same reason.
+ */
+export function registerCustomProviders(configDir, onWarn = () => { }) {
+    let count = 0;
+    for (const profile of loadCustomProviders(configDir, onWarn)) {
+        try {
+            registerProvider(profile);
+            count += 1;
+        }
+        catch (error) {
+            onWarn(`Could not register custom provider '${profile.name}': ${error instanceof Error ? error.message : String(error)}. Skipping.`);
+        }
+    }
+    return count;
+}

package/dist/node_modules/@boombot/protocol/providers/profiles/deepseek.d.ts

@@ -0,0 +1,7 @@
+/**
+ * DeepSeek provider profile.
+ *
+ * Boundary: leaf package — node builtins only.
+ */
+import type { ProviderProfile } from './types.js';
+export declare const deepseekProfile: ProviderProfile;

package/dist/node_modules/@boombot/protocol/providers/profiles/deepseek.js

@@ -0,0 +1,9 @@
+export const deepseekProfile = {
+    name: 'deepseek',
+    displayName: 'DeepSeek',
+    apiMode: 'chat_completions',
+    defaultBaseUrl: 'https://api.deepseek.com/v1',
+    authStyle: 'bearer',
+    defaultModel: 'deepseek-chat',
+    description: 'DeepSeek API (OpenAI-compatible).',
+};

package/dist/node_modules/@boombot/protocol/providers/profiles/google.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Google provider profile.
+ *
+ * Uses the `v1beta/openai` compatibility endpoint, so it speaks the
+ * OpenAI chat-completions wire protocol with Bearer auth.
+ *
+ * Boundary: leaf package — node builtins only.
+ */
+import type { ProviderProfile } from './types.js';
+export declare const googleProfile: ProviderProfile;

package/dist/node_modules/@boombot/protocol/providers/profiles/google.js

@@ -0,0 +1,10 @@
+export const googleProfile = {
+    name: 'google',
+    displayName: 'Google',
+    apiMode: 'chat_completions',
+    defaultBaseUrl: 'https://generativelanguage.googleapis.com/v1beta/openai',
+    aliases: ['gemini'],
+    authStyle: 'bearer',
+    defaultModel: 'gemini-2.0-flash',
+    description: 'Google Gemini via the OpenAI-compatibility endpoint.',
+};

package/dist/node_modules/@boombot/protocol/providers/profiles/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Provider profile registry (Hermes-style).
+ *
+ * Providers are discovered, not hardcoded: each provider is a declarative
+ * `ProviderProfile` in its own module, registered here. Third parties can
+ * call `registerProvider()` to add custom providers without touching this
+ * package's types.
+ *
+ * The 8 built-in providers self-register on import.
+ *
+ * Boundary: leaf package — node builtins only, no `@boombot/*` imports.
+ */
+import type { ProviderKind } from '../types.js';
+import type { ProviderProfile } from './types.js';
+export type { ProviderApiMode, ProviderAuthStyle, ProviderProfile } from './types.js';
+/**
+ * Register a provider profile. Later registrations with the same name win
+ * (lets embedders override a built-in). Aliases must not collide with an
+ * existing name or alias — a collision throws.
+ */
+export declare function registerProvider(profile: ProviderProfile): void;
+/** Look up a profile by name or alias (case-insensitive). `undefined` when unknown. */
+export declare function getProviderProfile(name: string): ProviderProfile | undefined;
+/** All registered profiles, in registration order. */
+export declare function listProviderProfiles(): readonly ProviderProfile[];
+/**
+ * Provider kinds derived from the registry. Kept in sync with the
+ * `ProviderKind` union in `../types.js` — every union member must have a
+ * registered profile (asserted by the built-in self-registration below).
+ */
+export declare function registeredProviderKinds(): readonly ProviderKind[];

package/dist/node_modules/@boombot/protocol/providers/profiles/index.js

@@ -0,0 +1,56 @@
+import { anthropicProfile } from './anthropic.js';
+import { deepseekProfile } from './deepseek.js';
+import { googleProfile } from './google.js';
+import { localProfile } from './local.js';
+import { mistralProfile } from './mistral.js';
+import { openaiProfile } from './openai.js';
+import { openaiCompatibleProfile } from './openai-compatible.js';
+import { xaiProfile } from './xai.js';
+const byName = new Map();
+const byAlias = new Map();
+/**
+ * Register a provider profile. Later registrations with the same name win
+ * (lets embedders override a built-in). Aliases must not collide with an
+ * existing name or alias — a collision throws.
+ */
+export function registerProvider(profile) {
+    const key = profile.name.toLowerCase();
+    byName.set(key, profile);
+    for (const alias of profile.aliases ?? []) {
+        const aliasKey = alias.toLowerCase();
+        if (byName.has(aliasKey) || byAlias.has(aliasKey)) {
+            throw new Error(`Provider alias '${alias}' collides with an existing provider name or alias.`);
+        }
+        byAlias.set(aliasKey, profile);
+    }
+}
+/** Look up a profile by name or alias (case-insensitive). `undefined` when unknown. */
+export function getProviderProfile(name) {
+    const key = name.toLowerCase();
+    return byName.get(key) ?? byAlias.get(key);
+}
+/** All registered profiles, in registration order. */
+export function listProviderProfiles() {
+    return [...byName.values()];
+}
+/**
+ * Provider kinds derived from the registry. Kept in sync with the
+ * `ProviderKind` union in `../types.js` — every union member must have a
+ * registered profile (asserted by the built-in self-registration below).
+ */
+export function registeredProviderKinds() {
+    return listProviderProfiles().map((p) => p.name);
+}
+// Built-in providers self-register on import, in `ProviderKind` order.
+for (const profile of [
+    openaiProfile,
+    anthropicProfile,
+    googleProfile,
+    mistralProfile,
+    xaiProfile,
+    deepseekProfile,
+    openaiCompatibleProfile,
+    localProfile,
+]) {
+    registerProvider(profile);
+}

package/dist/node_modules/@boombot/protocol/providers/profiles/local.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Local provider profile.
+ *
+ * For self-hosted inference (Ollama, LM Studio, vLLM, …). No default base
+ * URL and no API key required — the user points it at their local server.
+ *
+ * Boundary: leaf package — node builtins only.
+ */
+import type { ProviderProfile } from './types.js';
+export declare const localProfile: ProviderProfile;

package/dist/node_modules/@boombot/protocol/providers/profiles/local.js

@@ -0,0 +1,11 @@
+export const localProfile = {
+    name: 'local',
+    displayName: 'Local',
+    apiMode: 'chat_completions',
+    defaultBaseUrl: null,
+    aliases: ['ollama', 'self-hosted'],
+    authStyle: 'bearer',
+    defaultModel: '',
+    keyless: true,
+    description: 'Self-hosted model server (Ollama, LM Studio, vLLM). No API key needed.',
+};

package/dist/node_modules/@boombot/protocol/providers/profiles/mistral.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Mistral provider profile.
+ *
+ * Boundary: leaf package — node builtins only.
+ */
+import type { ProviderProfile } from './types.js';
+export declare const mistralProfile: ProviderProfile;

package/dist/node_modules/@boombot/protocol/providers/profiles/mistral.js

@@ -0,0 +1,9 @@
+export const mistralProfile = {
+    name: 'mistral',
+    displayName: 'Mistral',
+    apiMode: 'chat_completions',
+    defaultBaseUrl: 'https://api.mistral.ai/v1',
+    authStyle: 'bearer',
+    defaultModel: 'mistral-large-latest',
+    description: 'Mistral API (OpenAI-compatible).',
+};

package/dist/node_modules/@boombot/protocol/providers/profiles/openai-compatible.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Generic OpenAI-compatible provider profile.
+ *
+ * For any third-party endpoint speaking the chat-completions protocol.
+ * No default base URL — the user must supply one.
+ *
+ * Boundary: leaf package — node builtins only.
+ */
+import type { ProviderProfile } from './types.js';
+export declare const openaiCompatibleProfile: ProviderProfile;

package/dist/node_modules/@boombot/protocol/providers/profiles/openai-compatible.js

@@ -0,0 +1,10 @@
+export const openaiCompatibleProfile = {
+    name: 'openai-compatible',
+    displayName: 'OpenAI-compatible',
+    apiMode: 'chat_completions',
+    defaultBaseUrl: null,
+    aliases: ['custom', 'generic'],
+    authStyle: 'bearer',
+    defaultModel: '',
+    description: 'Any OpenAI-compatible endpoint (custom base URL required).',
+};

package/dist/node_modules/@boombot/protocol/providers/profiles/openai.d.ts

@@ -0,0 +1,7 @@
+/**
+ * OpenAI provider profile.
+ *
+ * Boundary: leaf package — node builtins only.
+ */
+import type { ProviderProfile } from './types.js';
+export declare const openaiProfile: ProviderProfile;

package/dist/node_modules/@boombot/protocol/providers/profiles/openai.js

@@ -0,0 +1,11 @@
+export const openaiProfile = {
+    name: 'openai',
+    displayName: 'OpenAI',
+    apiMode: 'chat_completions',
+    defaultBaseUrl: 'https://api.openai.com/v1',
+    authStyle: 'bearer',
+    defaultModel: 'gpt-4o-mini',
+    defaultEmbeddingModel: 'text-embedding-3-small',
+    requestUsage: true,
+    description: 'OpenAI API (GPT models).',
+};

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

@@ -0,0 +1,58 @@
+/**
+ * Declarative provider profiles (Hermes-style).
+ *
+ * Each LLM provider is described by a single `ProviderProfile` object instead
+ * of scattered `switch (kind)` branches. Adding a provider means adding one
+ * file — no changes to types, no new switch cases.
+ *
+ * Boundary: leaf package — node builtins only, no `@boombot/*` imports.
+ */
+import type { RequestProfile } from '../request-profile.js';
+import type { ProviderKind } from '../types.js';
+/** Wire protocol a provider speaks. Determines request shape and decoder. */
+export type ProviderApiMode = 'chat_completions' | 'anthropic_messages';
+/** How the API key is sent on every request. */
+export type ProviderAuthStyle = 'bearer' | 'x-api-key';
+/**
+ * Declarative description of one LLM provider.
+ *
+ * All behavior the gateway's LLM client derives from `ProviderKind` lives
+ * here: base URL, auth headers, wire protocol, and tier-1 request defaults.
+ */
+export interface ProviderProfile {
+    /** Machine name. Must be a member of `ProviderKind`. */
+    readonly name: ProviderKind;
+    /** Human-readable name shown in UIs. */
+    readonly displayName: string;
+    /** Wire protocol: request format + response decoder. */
+    readonly apiMode: ProviderApiMode;
+    /** Default base URL, or `null` when the user must supply one. */
+    readonly defaultBaseUrl: string | null;
+    /** Alternate names accepted by `getProviderProfile`. */
+    readonly aliases?: readonly string[];
+    /** How the API key is transmitted. */
+    readonly authStyle: ProviderAuthStyle;
+    /**
+     * Extra version header for `x-api-key` auth (e.g. Anthropic's
+     * `anthropic-version: 2023-06-01`). Ignored for `bearer` auth.
+     */
+    readonly authVersionHeader?: {
+        readonly name: string;
+        readonly value: string;
+    };
+    /** Sensible default chat model suggestion (user config wins). */
+    readonly defaultModel: string;
+    /** Tier-1 request profile defaults for this provider. */
+    readonly defaultProfile?: RequestProfile;
+    /** Whether this provider can serve without an API key. */
+    readonly keyless?: boolean;
+    /**
+     * Request token usage in streaming responses
+     * (`stream_options: { include_usage: true }` for chat_completions).
+     */
+    readonly requestUsage?: boolean;
+    /** Default embedding model for semantic search (if the provider offers one). */
+    readonly defaultEmbeddingModel?: string;
+    /** Short description for UIs and setup wizards. */
+    readonly description?: string;
+}

package/dist/node_modules/@boombot/protocol/providers/profiles/types.js

@@ -0,0 +1 @@
+export {};

package/dist/node_modules/@boombot/protocol/providers/profiles/xai.d.ts

@@ -0,0 +1,7 @@
+/**
+ * xAI provider profile.
+ *
+ * Boundary: leaf package — node builtins only.
+ */
+import type { ProviderProfile } from './types.js';
+export declare const xaiProfile: ProviderProfile;

package/dist/node_modules/@boombot/protocol/providers/profiles/xai.js

@@ -0,0 +1,10 @@
+export const xaiProfile = {
+    name: 'xai',
+    displayName: 'xAI',
+    apiMode: 'chat_completions',
+    defaultBaseUrl: 'https://api.x.ai/v1',
+    aliases: ['grok'],
+    authStyle: 'bearer',
+    defaultModel: 'grok-3-mini',
+    description: 'xAI API (Grok models, OpenAI-compatible).',
+};

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

@@ -0,0 +1,102 @@
+/**
+ * Layered request profiles for LLM calls.
+ *
+ * A request profile carries the per-request knobs the gateway applies when
+ * building a provider HTTP request: scalar params (`maxTokens`,
+ * `temperature`, `topP`), extra HTTP `headers`, an `extraBody` object merged
+ * into the JSON request body, and per-model `reasoning` knobs.
+ *
+ * Three tiers merge left-to-right, later tiers winning:
+ *
+ *   kind defaults < provider.extra < per-model override
+ *
+ * - Tier 1 (kind defaults): hardcoded per `ProviderKind` (e.g. Anthropic
+ *   requires `max_tokens`, so its default lives here instead of as a magic
+ *   constant at the call site).
+ * - Tier 2 (`provider.extra`): stored on the provider record in
+ *   `providers.json`, applies to every model of that provider.
+ * - Tier 3 (per-model override): `provider.modelProfiles[model]`, wins over
+ *   everything for that one model.
+ *
+ * Merge rules (shared by every consumer — there is exactly one merge
+ * implementation):
+ * - `undefined` means "unset" and never overwrites a set value. There is no
+ *   way to *clear* an inherited value except by overriding it with a new one.
+ * - Scalars are replaced wholesale.
+ * - `headers` merge key-by-key (later tier wins per header name).
+ * - `extraBody` merges recursively: plain objects merge key-by-key to any
+ *   depth; arrays and scalars are replaced, never concatenated.
+ * - `reasoning` merges field-by-field like `headers`.
+ *
+ * Boundary: leaf package — node builtins only, no `@boombot/*` imports.
+ * Pure functions; the gateway's `llm-client.ts` is the single consumer on
+ * the real request path.
+ */
+import type { ProviderKind } from './types.js';
+/**
+ * Reasoning knobs a profile can carry. Each wire protocol maps them its own
+ * way at request-build time:
+ * - `effort` → OpenAI-compatible `reasoning_effort` (o-series / gpt-5 style).
+ * - `budgetTokens` → Anthropic `thinking: { type: 'enabled', budget_tokens }`.
+ */
+export interface ReasoningProfile {
+    /** OpenAI-style reasoning effort, e.g. `'low' | 'medium' | 'high'`. */
+    readonly effort?: string;
+    /** Anthropic-style thinking budget in tokens. */
+    readonly budgetTokens?: number;
+}
+/**
+ * Per-request overrides for one LLM call. Every field is optional; absent
+ * fields inherit from the lower tier.
+ */
+export interface RequestProfile {
+    /** Mapped to `max_tokens` (Anthropic) / `max_completion_tokens`-style body params. */
+    readonly maxTokens?: number;
+    readonly temperature?: number;
+    readonly topP?: number;
+    /**
+     * Extra HTTP headers merged over the auth headers. Auth headers always
+     * stay authoritative: on a name conflict the auth value wins, so a profile
+     * can never silently swap the credential.
+     */
+    readonly headers?: Readonly<Record<string, string>>;
+    /**
+     * Extra top-level fields merged into the JSON request body. Applied after
+     * the mapped scalar params, so it works as an escape hatch for
+     * provider-specific knobs (e.g. `top_k`, `min_p`, `seed`).
+     */
+    readonly extraBody?: Readonly<Record<string, unknown>>;
+    /** Per-model reasoning knobs; mapped per wire protocol. */
+    readonly reasoning?: ReasoningProfile;
+}
+/**
+ * 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 declare function kindDefaultProfile(kind: ProviderKind): RequestProfile;
+/**
+ * All tier-1 defaults, keyed by provider name. Built lazily from the
+ * registry so third-party `registerProvider()` calls are honored.
+ */
+export declare function allKindDefaultProfiles(): Readonly<Record<string, RequestProfile>>;
+/**
+ * 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 declare function deepMergeRecords(base: Readonly<Record<string, unknown>>, override: Readonly<Record<string, unknown>>): Record<string, unknown>;
+/**
+ * Deep-merge request profiles left-to-right: later profiles win.
+ * See the module docstring for the exact merge rules.
+ */
+export declare function mergeRequestProfiles(...profiles: readonly (RequestProfile | undefined)[]): RequestProfile;
+/**
+ * Resolve the effective request profile for one model:
+ * kind defaults < provider.extra < provider.modelProfiles[model].
+ */
+export declare function resolveRequestProfile(kind: ProviderKind, providerExtra: RequestProfile | undefined, modelProfiles: Readonly<Record<string, RequestProfile>> | undefined, model: string): RequestProfile;
+/** Structural check used by the provider service when validating stored/wire input. */
+export declare function isRequestProfile(value: unknown): value is RequestProfile;