@theowlops/boombot 0.0.0-stage → 1.1.1

package/dist/node_modules/@boombot/protocol/plugin-sdk/manifest.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Plugin manifest for `@boombot/protocol` (lesson #7 from the
+ * Hermes/OpenClaw comparison: capability + configSchema + doctorContract,
+ * declared up front).
+ *
+ * Extensions ship an `boombot.plugin.json` file; the gateway validates it
+ * with `parseManifest` before loading anything.
+ */
+import type { ChannelKind } from './channel.js';
+/** Minimal JSON Schema subset, self-defined (no external dependency). */
+export interface JSONSchema {
+    readonly type?: 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';
+    readonly description?: string;
+    readonly properties?: Readonly<Record<string, JSONSchema>>;
+    readonly required?: readonly string[];
+    readonly items?: JSONSchema;
+    readonly enum?: readonly (string | number | boolean)[];
+    readonly additionalProperties?: boolean | JSONSchema;
+}
+/** Self-diagnostics contract: named checks the `doctor` command can run. */
+export interface DoctorContract {
+    readonly checks: readonly string[];
+}
+export interface BoomBotPluginManifest {
+    /** Reverse-DNS style id, e.g. `'boombot.telegram'`. */
+    readonly id: string;
+    /** Semver, e.g. `'1.2.0'`. */
+    readonly version: string;
+    readonly displayName: string;
+    readonly description?: string;
+    /** JavaScript module path relative to the manifest directory. Defaults to `index.js`. */
+    readonly entry?: string;
+    /** Capability tokens, e.g. `['channel.send', 'channel.receive']`. */
+    readonly capabilities: readonly string[];
+    readonly channels?: readonly ChannelKind[];
+    /** JSON Schema describing the plugin's config object. */
+    readonly configSchema: JSONSchema;
+    readonly doctorContract?: DoctorContract;
+}
+export type ParseManifestResult = {
+    readonly ok: true;
+    readonly manifest: BoomBotPluginManifest;
+} | {
+    readonly ok: false;
+    readonly errors: readonly string[];
+};
+/**
+ * Hand-written manifest validator (no extra dependencies on purpose —
+ * the SDK must stay tiny). Returns all errors found, not just the first.
+ */
+export declare function parseManifest(raw: unknown): ParseManifestResult;
+/**
+ * Validate-and-return convenience for extension entry points: parses the
+ * bundled `boombot.plugin.json` and throws on the first import if the manifest
+ * is invalid, so an extension never runs with broken metadata. Every
+ * extension's `src/manifest.ts` is this call plus the JSON import.
+ */
+export declare function defineManifest(raw: unknown): BoomBotPluginManifest;

package/dist/node_modules/@boombot/protocol/plugin-sdk/manifest.js

@@ -0,0 +1,116 @@
+import { CHANNEL_KINDS } from './channel.js';
+const ID_PATTERN = /^[a-z0-9][a-z0-9-]*(\.[a-z0-9][a-z0-9-]*)+$/;
+const VERSION_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$/;
+const CAPABILITY_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim() !== '';
+}
+/**
+ * Hand-written manifest validator (no extra dependencies on purpose —
+ * the SDK must stay tiny). Returns all errors found, not just the first.
+ */
+export function parseManifest(raw) {
+    const errors = [];
+    if (!isRecord(raw)) {
+        return { ok: false, errors: ['manifest must be a JSON object'] };
+    }
+    if (!isNonEmptyString(raw['id'])) {
+        errors.push('id must be a non-empty string');
+    }
+    else if (!ID_PATTERN.test(raw['id'])) {
+        errors.push(`id must be reverse-DNS style (e.g. 'boombot.telegram'), got '${raw['id']}'`);
+    }
+    if (!isNonEmptyString(raw['version'])) {
+        errors.push('version must be a non-empty string');
+    }
+    else if (!VERSION_PATTERN.test(raw['version'])) {
+        errors.push(`version must be semver, got '${raw['version']}'`);
+    }
+    if (!isNonEmptyString(raw['displayName'])) {
+        errors.push('displayName must be a non-empty string');
+    }
+    if (raw['description'] !== undefined && typeof raw['description'] !== 'string') {
+        errors.push('description must be a string when present');
+    }
+    if (raw['entry'] !== undefined &&
+        (!isNonEmptyString(raw['entry']) || raw['entry'].includes('\0'))) {
+        errors.push('entry must be a non-empty path string when present');
+    }
+    if (!Array.isArray(raw['capabilities']) || raw['capabilities'].length === 0) {
+        errors.push('capabilities must be a non-empty array of strings');
+    }
+    else {
+        for (const cap of raw['capabilities']) {
+            if (!isNonEmptyString(cap)) {
+                errors.push('capabilities must contain only non-empty strings');
+                break;
+            }
+            if (!CAPABILITY_PATTERN.test(cap)) {
+                errors.push(`capability '${cap}' must be lowercase alphanumeric with . _ - separators`);
+                break;
+            }
+        }
+    }
+    if (raw['channels'] !== undefined) {
+        if (!Array.isArray(raw['channels'])) {
+            errors.push('channels must be an array of channel kinds when present');
+        }
+        else {
+            for (const ch of raw['channels']) {
+                if (!CHANNEL_KINDS.includes(ch)) {
+                    errors.push(`unknown channel kind '${String(ch)}' (known: ${CHANNEL_KINDS.join(', ')})`);
+                    break;
+                }
+            }
+        }
+    }
+    if (!isRecord(raw['configSchema'])) {
+        errors.push('configSchema must be a JSON Schema object');
+    }
+    else if (raw['configSchema']['type'] !== undefined && typeof raw['configSchema']['type'] !== 'string') {
+        errors.push('configSchema.type must be a string when present');
+    }
+    const doctor = raw['doctorContract'];
+    if (doctor !== undefined) {
+        if (!isRecord(doctor)) {
+            errors.push('doctorContract must be an object when present');
+        }
+        else if (!Array.isArray(doctor['checks']) ||
+            !doctor['checks'].every((c) => isNonEmptyString(c))) {
+            errors.push('doctorContract.checks must be an array of non-empty strings');
+        }
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    const manifest = {
+        id: raw['id'],
+        version: raw['version'],
+        displayName: raw['displayName'],
+        capabilities: raw['capabilities'],
+        configSchema: raw['configSchema'],
+        ...(typeof raw['description'] === 'string' ? { description: raw['description'] } : {}),
+        ...(typeof raw['entry'] === 'string' ? { entry: raw['entry'] } : {}),
+        ...(Array.isArray(raw['channels']) ? { channels: raw['channels'] } : {}),
+        ...(isRecord(raw['doctorContract'])
+            ? { doctorContract: { checks: raw['doctorContract']['checks'] } }
+            : {}),
+    };
+    return { ok: true, manifest };
+}
+/**
+ * Validate-and-return convenience for extension entry points: parses the
+ * bundled `boombot.plugin.json` and throws on the first import if the manifest
+ * is invalid, so an extension never runs with broken metadata. Every
+ * extension's `src/manifest.ts` is this call plus the JSON import.
+ */
+export function defineManifest(raw) {
+    const result = parseManifest(raw);
+    if (!result.ok) {
+        throw new Error(`boombot.plugin.json is invalid: ${result.errors.join('; ')}`);
+    }
+    return result.manifest;
+}

package/dist/node_modules/@boombot/protocol/plugin-sdk/plugin.d.ts

@@ -0,0 +1,25 @@
+import type { JSONSchema } from './manifest.js';
+export interface PluginToolDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: JSONSchema;
+}
+export interface PluginToolCall {
+    readonly id: string;
+    readonly name: string;
+    readonly arguments: Readonly<Record<string, unknown>>;
+}
+export interface PluginToolResult {
+    readonly output: string;
+    readonly error?: boolean;
+}
+export type PluginToolHandler = (call: PluginToolCall, signal?: AbortSignal) => Promise<PluginToolResult> | PluginToolResult;
+export interface BoomBotPluginApi {
+    readonly config: unknown;
+    registerTool(definition: PluginToolDefinition, handler: PluginToolHandler): void;
+    log(level: 'debug' | 'info' | 'warn' | 'error', message: string): void;
+}
+export interface BoomBotPlugin {
+    activate(api: BoomBotPluginApi): void;
+    deactivate?(): void;
+}

package/dist/node_modules/@boombot/protocol/plugin-sdk/plugin.js

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

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

@@ -0,0 +1,7 @@
+/** Encrypt `plaintext` with `masterKey`. Returns the wire-format payload. */
+export declare function encryptSecret(masterKey: string, plaintext: string): string;
+/**
+ * Decrypt a payload produced by {@link encryptSecret}. Throws when the
+ * master key is wrong or the payload was tampered with (GCM auth fails).
+ */
+export declare function decryptSecret(masterKey: string, payload: string): string;

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

@@ -0,0 +1,52 @@
+/**
+ * At-rest encryption for provider API keys.
+ *
+ * AES-256-GCM with a 96-bit random IV per encryption; the 256-bit key is
+ * derived from the caller-supplied master secret via SHA-256. Deriving
+ * (instead of requiring exactly 32 bytes) keeps the `BOOMBOT_MASTER_KEY`
+ * contract ergonomic — any non-empty string works — while staying a standard
+ * construction.
+ *
+ * Wire format: `base64(iv).base64(ciphertext).base64(authTag)`.
+ */
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto';
+function deriveKey(masterKey) {
+    return createHash('sha256').update(masterKey, 'utf8').digest();
+}
+function b64url(buf) {
+    return buf.toString('base64');
+}
+function fromB64(s) {
+    return Buffer.from(s, 'base64');
+}
+/** Encrypt `plaintext` with `masterKey`. Returns the wire-format payload. */
+export function encryptSecret(masterKey, plaintext) {
+    if (!masterKey)
+        throw new Error('encryptSecret: masterKey must not be empty');
+    const key = deriveKey(masterKey);
+    const iv = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', key, iv);
+    const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return `${b64url(iv)}.${b64url(ciphertext)}.${b64url(tag)}`;
+}
+/**
+ * Decrypt a payload produced by {@link encryptSecret}. Throws when the
+ * master key is wrong or the payload was tampered with (GCM auth fails).
+ */
+export function decryptSecret(masterKey, payload) {
+    if (!masterKey)
+        throw new Error('decryptSecret: masterKey must not be empty');
+    const parts = payload.split('.');
+    if (parts.length !== 3)
+        throw new Error('decryptSecret: malformed payload');
+    const [ivB64, ctB64, tagB64] = parts;
+    const key = deriveKey(masterKey);
+    const decipher = createDecipheriv('aes-256-gcm', key, fromB64(ivB64));
+    decipher.setAuthTag(fromB64(tagB64));
+    const plaintext = Buffer.concat([
+        decipher.update(fromB64(ctB64)),
+        decipher.final(),
+    ]);
+    return plaintext.toString('utf8');
+}

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

@@ -0,0 +1,19 @@
+/**
+ * `@boombot/protocol` — LLM provider registry for BoomBot.
+ *
+ * File-backed CRUD (`createProviderService`) with API keys encrypted at rest
+ * (AES-256-GCM, `BOOMBOT_MASTER_KEY`-derived key), plus a live connectivity
+ * probe (`probeProvider`) used by the gateway's `provider.test` handler.
+ *
+ * Boundary: leaf package — node builtins only, no `@boombot/*` imports.
+ * Provider shapes mirror `@boombot/protocol`'s wire schemas
+ * structurally so the gateway can pass zod-parsed payloads straight in.
+ */
+export { decryptSecret, encryptSecret } from './cipher.js';
+export { buildAuthHeaders, defaultBaseUrlFor, probeProvider } from './probe.js';
+export { createProviderService } from './service.js';
+export { DEFAULT_KEY_COOLDOWN_MS, KeyRoulette, type KeyRouletteOptions, } from './key-roulette.js';
+export { deepMergeRecords, isRequestProfile, kindDefaultProfile, mergeRequestProfiles, resolveRequestProfile, type ReasoningProfile, type RequestProfile, } from './request-profile.js';
+export { PROVIDER_KINDS, ProviderError, type ProbeOptions, type ProbeResult, type Provider, type ProviderInput, type ProviderKind, type ProviderService, type ProviderServiceOptions, } from './types.js';
+export { getProviderProfile, listProviderProfiles, registerProvider, registeredProviderKinds, type ProviderApiMode, type ProviderAuthStyle, type ProviderProfile, } from './profiles/index.js';
+export { CUSTOM_PROVIDERS_FILE, loadCustomProviders, registerCustomProviders, type CustomProviderWarnFn, } from './profiles/custom.js';

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

@@ -0,0 +1,19 @@
+/**
+ * `@boombot/protocol` — LLM provider registry for BoomBot.
+ *
+ * File-backed CRUD (`createProviderService`) with API keys encrypted at rest
+ * (AES-256-GCM, `BOOMBOT_MASTER_KEY`-derived key), plus a live connectivity
+ * probe (`probeProvider`) used by the gateway's `provider.test` handler.
+ *
+ * Boundary: leaf package — node builtins only, no `@boombot/*` imports.
+ * Provider shapes mirror `@boombot/protocol`'s wire schemas
+ * structurally so the gateway can pass zod-parsed payloads straight in.
+ */
+export { decryptSecret, encryptSecret } from './cipher.js';
+export { buildAuthHeaders, defaultBaseUrlFor, probeProvider } from './probe.js';
+export { createProviderService } from './service.js';
+export { DEFAULT_KEY_COOLDOWN_MS, KeyRoulette, } from './key-roulette.js';
+export { deepMergeRecords, isRequestProfile, kindDefaultProfile, mergeRequestProfiles, resolveRequestProfile, } from './request-profile.js';
+export { PROVIDER_KINDS, ProviderError, } from './types.js';
+export { getProviderProfile, listProviderProfiles, registerProvider, registeredProviderKinds, } from './profiles/index.js';
+export { CUSTOM_PROVIDERS_FILE, loadCustomProviders, registerCustomProviders, } from './profiles/custom.js';

package/dist/node_modules/@boombot/protocol/providers/key-roulette.d.ts

@@ -0,0 +1,79 @@
+/**
+ * KeyRoulette-lite: per-provider API key rotation.
+ *
+ * A provider may hold a *ring* of API keys (each stored AES-256-GCM encrypted
+ * like the old single key — the cipher is untouched). The roulette picks
+ * which key serves the next request:
+ *
+ * - The persisted `cursor` is the first key tried. It only advances when a
+ *   key fails with HTTP 401/429, so a healthy key keeps serving traffic
+ *   (sticky-until-failure, not blind round-robin on every request).
+ * - A failed key is benched for `cooldownMs` (default 60s) so the ring does
+ *   not spin straight back into a dead key while retrying.
+ * - When the cursor's key is benched, the next healthy key scanning forward
+ *   (wrapping) is used.
+ * - A single success clears the key's bench — transient blips do not
+ *   permanently sideline a key.
+ * - When every key is benched, `pickIndex()` returns `null` and the caller
+ *   fails the request loudly instead of hammering dead keys.
+ *
+ * The cursor is the only persisted state (via `onCursorAdvanced`, which the
+ * gateway wires to `ProviderService.setKeyCursor`). Cooldowns are
+ * intentionally in-memory: after a restart every key is tried again, which
+ * is the safe direction for a short bench.
+ *
+ * This class is transport-agnostic: the gateway's `KeyRotatingLlmClient`
+ * (`agent-worker/src/services/key-roulette-client.ts`) drives it on the real
+ * request path and retries the failed request with the next key.
+ *
+ * Boundary: leaf package — node builtins only, no `@boombot/*` imports.
+ */
+export interface KeyRouletteOptions {
+    /** Decrypted keys in ring order. Must be non-empty. */
+    readonly keys: readonly string[];
+    /** Persisted cursor: index of the key to try first. Defaults to 0. */
+    readonly cursor?: number;
+    /** Bench duration for a failed key, in ms. Defaults to 60_000. */
+    readonly cooldownMs?: number;
+    /**
+     * Called whenever the cursor advances (on failure) so the caller can
+     * persist it. May be async; failures are the caller's to handle.
+     */
+    readonly onCursorAdvanced?: (cursor: number) => void | Promise<void>;
+    /** Clock override, for tests. Defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+/** Default bench for a key that answered 401/429. */
+export declare const DEFAULT_KEY_COOLDOWN_MS = 60000;
+export declare class KeyRoulette {
+    private readonly keys;
+    private cursor;
+    private readonly cooldownMs;
+    private readonly onCursorAdvanced;
+    private readonly clock;
+    /** Key index → epoch ms when the bench expires. */
+    private readonly benchedUntil;
+    constructor(options: KeyRouletteOptions);
+    /** Number of keys in the ring. */
+    get size(): number;
+    /** Current cursor — the index `pickIndex()` tries first. */
+    get currentCursor(): number;
+    /** The key at `index` (normalized into range). */
+    keyAt(index: number): string;
+    /** Epoch ms when the bench for `index` expires, or 0 when not benched. */
+    benchExpiresAt(index: number): number;
+    private isBenched;
+    /**
+     * Pick the next usable key index: the cursor when healthy, otherwise the
+     * next healthy key scanning forward (wrapping around the ring).
+     * Returns `null` when every key is benched.
+     */
+    pickIndex(now?: number): number | null;
+    /**
+     * Mark the key at `index` as failed: bench it for `cooldownMs` and advance
+     * the cursor past it (persisted through `onCursorAdvanced`).
+     */
+    markFailed(index: number, now?: number): Promise<void>;
+    /** A success clears the key's bench — transient blips do not sideline keys. */
+    recordSuccess(index: number): void;
+}

package/dist/node_modules/@boombot/protocol/providers/key-roulette.js

@@ -0,0 +1,81 @@
+/** Default bench for a key that answered 401/429. */
+export const DEFAULT_KEY_COOLDOWN_MS = 60_000;
+function normalizeIndex(index, size) {
+    return ((index % size) + size) % size;
+}
+export class KeyRoulette {
+    keys;
+    cursor;
+    cooldownMs;
+    onCursorAdvanced;
+    clock;
+    /** Key index → epoch ms when the bench expires. */
+    benchedUntil = new Map();
+    constructor(options) {
+        if (options.keys.length === 0) {
+            throw new Error('KeyRoulette requires at least one key.');
+        }
+        if (options.cooldownMs !== undefined && (!Number.isFinite(options.cooldownMs) || options.cooldownMs < 0)) {
+            throw new Error('KeyRoulette cooldownMs must be a non-negative number.');
+        }
+        this.keys = options.keys;
+        this.cursor = normalizeIndex(options.cursor ?? 0, options.keys.length);
+        this.cooldownMs = options.cooldownMs ?? DEFAULT_KEY_COOLDOWN_MS;
+        this.onCursorAdvanced = options.onCursorAdvanced ?? (() => { });
+        this.clock = options.now ?? Date.now;
+    }
+    /** Number of keys in the ring. */
+    get size() {
+        return this.keys.length;
+    }
+    /** Current cursor — the index `pickIndex()` tries first. */
+    get currentCursor() {
+        return this.cursor;
+    }
+    /** The key at `index` (normalized into range). */
+    keyAt(index) {
+        return this.keys[normalizeIndex(index, this.keys.length)];
+    }
+    /** Epoch ms when the bench for `index` expires, or 0 when not benched. */
+    benchExpiresAt(index) {
+        return this.benchedUntil.get(normalizeIndex(index, this.keys.length)) ?? 0;
+    }
+    isBenched(index, now) {
+        const until = this.benchedUntil.get(index);
+        if (until === undefined)
+            return false;
+        if (until <= now) {
+            // Bench expired — drop it so the map does not grow unboundedly.
+            this.benchedUntil.delete(index);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Pick the next usable key index: the cursor when healthy, otherwise the
+     * next healthy key scanning forward (wrapping around the ring).
+     * Returns `null` when every key is benched.
+     */
+    pickIndex(now = this.clock()) {
+        for (let step = 0; step < this.keys.length; step++) {
+            const index = normalizeIndex(this.cursor + step, this.keys.length);
+            if (!this.isBenched(index, now))
+                return index;
+        }
+        return null;
+    }
+    /**
+     * Mark the key at `index` as failed: bench it for `cooldownMs` and advance
+     * the cursor past it (persisted through `onCursorAdvanced`).
+     */
+    async markFailed(index, now = this.clock()) {
+        const at = normalizeIndex(index, this.keys.length);
+        this.benchedUntil.set(at, now + this.cooldownMs);
+        this.cursor = normalizeIndex(at + 1, this.keys.length);
+        await this.onCursorAdvanced(this.cursor);
+    }
+    /** A success clears the key's bench — transient blips do not sideline keys. */
+    recordSuccess(index) {
+        this.benchedUntil.delete(normalizeIndex(index, this.keys.length));
+    }
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Live connectivity probe for an LLM provider.
+ *
+ * Strategy:
+ * 1. `GET {baseUrl}/models` — the OpenAI-style catalog (Anthropic also serves
+ *    `/v1/models` with `x-api-key` + `anthropic-version`). On success the
+ *    discovered model ids are returned so callers can persist them.
+ * 2. Fallback: minimal non-streaming `POST {baseUrl}/chat/completions` when
+ *    the catalog endpoint 404s/405s — verifies the key works even when the
+ *    provider has no models endpoint.
+ *
+ * Never throws for expected failures: they come back as `{ ok: false, error }`.
+ * Error strings never include secret material.
+ */
+import type { ProbeOptions, ProbeResult, ProviderKind } from './types.js';
+/**
+ * Default base URL for a provider kind, or `null` when the kind has no
+ * default and requires an explicit `baseUrl` (`openai-compatible`, `local`).
+ * Resolved from the provider's declarative profile — the single source of
+ * truth the connectivity probe and the gateway's LLM client share.
+ */
+export declare function defaultBaseUrlFor(kind: ProviderKind): string | null;
+/**
+ * Authorization headers for a provider kind, derived from its profile:
+ * `x-api-key` (+ version header) for `x-api-key` auth, `Bearer` otherwise.
+ * Exported so the gateway's LLM client authenticates exactly like the probe does.
+ */
+export declare function buildAuthHeaders(kind: ProviderKind, apiKey?: string): Record<string, string>;
+export declare function probeProvider(options: ProbeOptions, apiKey?: string, timeoutMs?: number): Promise<ProbeResult>;

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

@@ -0,0 +1,96 @@
+import { getProviderProfile } from './profiles/index.js';
+const DEFAULT_TIMEOUT_MS = 10_000;
+/**
+ * Default base URL for a provider kind, or `null` when the kind has no
+ * default and requires an explicit `baseUrl` (`openai-compatible`, `local`).
+ * Resolved from the provider's declarative profile — the single source of
+ * truth the connectivity probe and the gateway's LLM client share.
+ */
+export function defaultBaseUrlFor(kind) {
+    return getProviderProfile(kind)?.defaultBaseUrl ?? null;
+}
+function authHeaders(kind, apiKey) {
+    const headers = { Accept: 'application/json' };
+    if (!apiKey)
+        return headers;
+    const profile = getProviderProfile(kind);
+    if (profile?.authStyle === 'x-api-key') {
+        headers['x-api-key'] = apiKey;
+        if (profile.authVersionHeader) {
+            headers[profile.authVersionHeader.name] = profile.authVersionHeader.value;
+        }
+    }
+    else {
+        headers['Authorization'] = `Bearer ${apiKey}`;
+    }
+    return headers;
+}
+/**
+ * Authorization headers for a provider kind, derived from its profile:
+ * `x-api-key` (+ version header) for `x-api-key` auth, `Bearer` otherwise.
+ * Exported so the gateway's LLM client authenticates exactly like the probe does.
+ */
+export function buildAuthHeaders(kind, apiKey) {
+    return authHeaders(kind, apiKey);
+}
+function toErrorMessage(err) {
+    if (err instanceof Error) {
+        if (err.name === 'AbortError' || err.name === 'TimeoutError')
+            return 'Probe timed out.';
+        return err.message;
+    }
+    return String(err);
+}
+export async function probeProvider(options, apiKey, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const rawBase = options.baseUrl ?? getProviderProfile(options.kind)?.defaultBaseUrl ?? '';
+    const baseUrl = rawBase.replace(/\/+$/, '');
+    if (!baseUrl) {
+        return { ok: false, error: `Provider kind '${options.kind}' requires a baseUrl.` };
+    }
+    let parsed;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch {
+        return { ok: false, error: `Invalid baseUrl '${baseUrl}'.` };
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        return { ok: false, error: 'baseUrl must use http(s).' };
+    }
+    const headers = authHeaders(options.kind, apiKey);
+    const request = (path, init) => fetch(`${baseUrl}${path}`, {
+        ...init,
+        headers: { ...headers, ...(init?.headers ?? {}) },
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    try {
+        const catalog = await request('/models', { method: 'GET' });
+        if (catalog.ok) {
+            const body = (await catalog.json().catch(() => null));
+            const models = Array.isArray(body?.data)
+                ? body.data
+                    .map((m) => m?.id)
+                    .filter((id) => typeof id === 'string' && id.length > 0)
+                : [];
+            return { ok: true, models };
+        }
+        if (catalog.status === 404 || catalog.status === 405) {
+            const chat = await request('/chat/completions', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    model: 'probe',
+                    messages: [{ role: 'user', content: 'ok' }],
+                    max_tokens: 1,
+                }),
+            });
+            if (chat.ok)
+                return { ok: true };
+            return { ok: false, error: `Probe failed: HTTP ${chat.status}.` };
+        }
+        return { ok: false, error: `Probe failed: HTTP ${catalog.status}.` };
+    }
+    catch (err) {
+        return { ok: false, error: `Probe failed: ${toErrorMessage(err)}` };
+    }
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Anthropic provider profile.
+ *
+ * The only provider on the Messages wire protocol: `x-api-key` auth plus
+ * the `anthropic-version` header, and `max_tokens` is required on every
+ * request (hence the tier-1 default).
+ *
+ * Boundary: leaf package — node builtins only.
+ */
+import type { ProviderProfile } from './types.js';
+export declare const anthropicProfile: ProviderProfile;

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

@@ -0,0 +1,11 @@
+export const anthropicProfile = {
+    name: 'anthropic',
+    displayName: 'Anthropic',
+    apiMode: 'anthropic_messages',
+    defaultBaseUrl: 'https://api.anthropic.com/v1',
+    authStyle: 'x-api-key',
+    authVersionHeader: { name: 'anthropic-version', value: '2023-06-01' },
+    defaultModel: 'claude-sonnet-4-5',
+    defaultProfile: { maxTokens: 4096 },
+    description: 'Anthropic Messages API (Claude models).',
+};

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

@@ -0,0 +1,22 @@
+import type { ProviderProfile } from './types.js';
+/** File name (inside the config dir) holding user-defined providers. */
+export declare const CUSTOM_PROVIDERS_FILE = "custom-providers.json";
+/** Warning sink. The gateway passes its logger; default drops warnings. */
+export type CustomProviderWarnFn = (message: string, meta?: Record<string, unknown>) => void;
+/**
+ * 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 declare function loadCustomProviders(configDir: string, onWarn?: CustomProviderWarnFn): ProviderProfile[];
+/**
+ * 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 declare function registerCustomProviders(configDir: string, onWarn?: CustomProviderWarnFn): number;