melchizedek-agents 0.9.6 → 0.16.0

package/dist/lib/models/capabilities.js

@@ -0,0 +1,291 @@
+/**
+ * lib/models/capabilities.ts — what an agent keeps and loses on the path
+ * its model will actually take.
+ *
+ * WHY this file exists:
+ *   A model id is the whole routing decision, and some of what an agent
+ *   declares only exists on one provider: Gemini grounding, xAI's x_search
+ *   and Collections, the server-side web_search sentinel that every cloud
+ *   adapter turns into its provider's native search. Until now the only
+ *   defence against losing one was a one-time console.warn inside an
+ *   adapter. This module states the loss BEFORE a request is made, per
+ *   agent, on the RESOLVED transport (direct or gateway), so the doctor
+ *   (lib/doctor.ts), the A2A startup log (lib/compile.ts) and the ledger
+ *   (llm.capability.dropped) all say the same thing.
+ *
+ * It knows nothing about gateways beyond planTransport(); a future
+ * transport that restores a native feature changes the table here, not
+ * the callers.
+ */
+import { PROVIDERS } from './providerMap.js';
+import { planTransport } from './gateway.js';
+import { nativeSearchOn, PLATFORMS_FOR, platformFromEnv } from './endpoints.js';
+/** The platform a direct path uses (ADR 0023); a misconfigured one reads as direct here, the doctor reports it. */
+function directPlatform(provider) {
+    try {
+        return platformFromEnv(provider);
+    }
+    catch {
+        return 'direct';
+    }
+}
+/**
+ * Server-side tool sentinels and the providers whose DIRECT adapter
+ * honours them natively. Anything not listed is a client-side function
+ * tool and travels on every path.
+ */
+export const SERVER_SIDE_TOOLS = {
+    web_search: ['gemini', 'anthropic', 'openai', 'xai'],
+    google_search: ['gemini'],
+    x_search: ['xai'],
+    collections_search: ['xai'],
+};
+export function describeCapabilities(model, tools = [], opts = {}) {
+    const plan = planTransport(model, opts);
+    const platform = plan.transport === 'direct' && plan.provider !== 'ollama' ? directPlatform(plan.provider) : undefined;
+    const native = [];
+    const dropped = [];
+    const portable = [];
+    for (const name of tools) {
+        const providers = SERVER_SIDE_TOOLS[name];
+        if (!providers) {
+            portable.push(name);
+        }
+        else if (plan.transport === 'direct' && providers.includes(plan.provider) && nativeSearchOn(plan.provider, platform ?? 'direct')) {
+            native.push(name);
+        }
+        else {
+            dropped.push(name);
+        }
+    }
+    return {
+        model,
+        provider: plan.provider,
+        providerLabel: PROVIDERS[plan.provider].label,
+        transport: plan.transport,
+        ...(plan.gateway ? { gateway: plan.gateway.id } : {}),
+        ...(platform && platform !== 'direct' ? { platform } : {}),
+        funded: plan.funded,
+        keyEnv: plan.keyEnv,
+        native,
+        dropped,
+        portable,
+    };
+}
+/**
+ * One line for a startup log, or undefined when there is nothing to say —
+ * a funded direct path with no dropped tool is the quiet default.
+ */
+export function capabilitySummary(agentName, r) {
+    if (!r.funded) {
+        return `${agentName}: ${r.model} has no route — set ${r.keyEnv ?? 'a provider key'} (or a MODEL_GATEWAY).`;
+    }
+    const via = r.transport === 'gateway' ? ` via gateway:${r.gateway}` : '';
+    if (r.dropped.length === 0) {
+        return via ? `${agentName}: ${r.model}${via}.` : undefined;
+    }
+    const why = r.transport === 'gateway'
+        ? 'a gateway cannot enable upstream native search'
+        : r.provider === 'ollama'
+            ? 'a local model has no native search'
+            : r.platform
+                ? `native search is not sent to ${r.providerLabel} on ${r.platform}`
+                : `${r.providerLabel} has no native ${r.dropped.join('/')}`;
+    return `${agentName}: ${r.model}${via} — dropped ${r.dropped.join(', ')} (${why}).`;
+}
+// ── The capability matrix (ADR 0019) ─────────────────────────────────────────
+//
+// "Multi-model" promises that any provider can run any role, orchestrators
+// included. This table states, per resolved path (a direct provider, or the
+// gateway transport), what an agent can rely on. Each cell describes what the
+// ADAPTER SENDS, not how a given model behaves once it receives the request:
+//
+//   supported    the feature reaches the provider in its native form
+//   degraded     it reaches the provider in a weaker form; `note` names the loss
+//   unsupported  the adapter does not send it; `note` says what happens instead
+//
+// `evidence: 'test'` cells are asserted against the real outgoing request body
+// in tests/capabilityMatrix.test.ts, so changing an adapter without changing
+// its row fails a test. `evidence: 'adk'` cells are ADK's own Gemini adapter,
+// which this repo does not build requests for.
+export const CAPABILITIES = [
+    'delegation',
+    'memory_tools',
+    'structured_output',
+    'thinking_with_tools',
+    'streaming',
+    'vision',
+    'native_search',
+];
+export const CAPABILITY_LABELS = {
+    delegation: 'delegation (subagents as tools)',
+    memory_tools: 'memory tools (load_memory)',
+    structured_output: 'structured output (outputSchema)',
+    thinking_with_tools: 'thinking with tool use',
+    streaming: 'token streaming',
+    vision: 'image input',
+    native_search: 'native web search',
+};
+const ok = (evidence = 'test', note) => note ? { support: 'supported', note, evidence } : { support: 'supported', evidence };
+const degraded = (note) => ({ support: 'degraded', note, evidence: 'test' });
+const unsupported = (note) => ({ support: 'unsupported', note, evidence: 'test' });
+const nativeSearch = (row) => SERVER_SIDE_TOOLS.web_search.includes(row)
+    ? ok(row === 'gemini' ? 'adk' : 'test')
+    : unsupported('no native search on this path; the web_search sentinel is dropped (use web_extract)');
+const RESPONSES_REASONING_NOTE = 'reasoning is requested, but reasoning items are not carried across tool calls, so the model re-reasons each step';
+const CHAT_THINKING_NOTE = 'thinkingConfig budgets are ignored on chat-completions; generateContentConfig.reasoningEffort is the lever';
+export const CAPABILITY_MATRIX = {
+    gemini: {
+        delegation: ok('adk'),
+        memory_tools: ok('adk'),
+        structured_output: ok('adk'),
+        thinking_with_tools: ok('adk'),
+        streaming: ok('adk'),
+        vision: ok('adk'),
+        native_search: nativeSearch('gemini'),
+    },
+    anthropic: {
+        delegation: ok(),
+        memory_tools: ok(),
+        structured_output: ok('test', 'sent as a forced tool call; with a thinking budget the tool is offered under tool_choice auto'),
+        thinking_with_tools: unsupported('signed thinking blocks are not replayed on tool loops, which Anthropic requires; give a thinking Claude agent no tools'),
+        streaming: ok(),
+        vision: unsupported('image parts are dropped from the request; route image work to a Gemini, GPT or vision Ollama agent'),
+        native_search: nativeSearch('anthropic'),
+    },
+    openai: {
+        delegation: ok(),
+        memory_tools: ok(),
+        structured_output: ok(),
+        thinking_with_tools: degraded(RESPONSES_REASONING_NOTE),
+        streaming: ok(),
+        vision: ok('test', 'user-turn images only'),
+        native_search: nativeSearch('openai'),
+    },
+    xai: {
+        delegation: ok(),
+        memory_tools: ok(),
+        structured_output: ok(),
+        thinking_with_tools: degraded(RESPONSES_REASONING_NOTE),
+        streaming: ok(),
+        vision: ok('test', 'user-turn images only'),
+        native_search: nativeSearch('xai'),
+    },
+    ollama: {
+        delegation: ok(),
+        memory_tools: ok(),
+        structured_output: degraded('JSON mode only (json_object): the output is JSON but the schema is not enforced'),
+        thinking_with_tools: degraded(CHAT_THINKING_NOTE),
+        streaming: ok(),
+        vision: ok('test', 'needs a vision model, e.g. ollama/qwen3-vl:8b'),
+        native_search: nativeSearch('ollama'),
+    },
+    gateway: {
+        delegation: ok(),
+        memory_tools: ok(),
+        structured_output: ok('test', 'strict json_schema; upstream support varies by model'),
+        thinking_with_tools: degraded(CHAT_THINKING_NOTE),
+        streaming: ok(),
+        vision: ok('test', 'upstream model must accept images'),
+        native_search: unsupported('a gateway cannot enable upstream native search; the web_search sentinel is dropped'),
+    },
+};
+/** The matrix cell for a model on the path it will actually take. */
+export function capabilityOf(model, capability, opts = {}) {
+    const plan = planTransport(model, opts);
+    const row = plan.transport === 'gateway' ? 'gateway' : plan.provider;
+    if (row !== 'gateway' && row !== 'ollama') {
+        const cell = platformCell(row, directPlatform(row), capability);
+        if (cell)
+            return { row, ...cell };
+    }
+    return { row, ...CAPABILITY_MATRIX[row][capability] };
+}
+export function requiredCapabilities(agent) {
+    const tools = agent.tools ?? [];
+    const needs = new Set();
+    if (agent.delegates)
+        needs.add('delegation');
+    if (tools.includes('load_memory'))
+        needs.add('memory_tools');
+    if (agent.outputSchema)
+        needs.add('structured_output');
+    const thinking = agent.generateContentConfig?.thinkingConfig;
+    const thinks = !!thinking && (thinking.thinkingBudget ?? 0) !== 0;
+    if (thinks && (tools.length > 0 || agent.delegates))
+        needs.add('thinking_with_tools');
+    if (tools.includes('web_search'))
+        needs.add('native_search');
+    return [...needs];
+}
+/** The capabilities an agent needs that its resolved path does not fully give it. */
+export function capabilityGaps(model, agent, opts = {}) {
+    const gaps = [];
+    for (const capability of requiredCapabilities(agent)) {
+        const cell = capabilityOf(model, capability, opts);
+        if (cell.support === 'supported')
+            continue;
+        gaps.push({ capability, support: cell.support, row: cell.row, ...(cell.note ? { note: cell.note } : {}) });
+    }
+    return gaps;
+}
+// ── Cloud platforms (ADR 0023) ───────────────────────────────────────────────
+//
+// On Vertex AI, Bedrock and Azure OpenAI the adapter sends the same request
+// as on the provider's own API (the vendor SDK's platform client speaks the
+// same dialect), so every cell is the provider's row, except where the
+// adapter deliberately sends less. Native search is the one such cell today.
+/** The cell that differs from the provider's row on a platform, or undefined. */
+export function platformCell(provider, platform, capability) {
+    if (platform === 'direct' || capability !== 'native_search')
+        return undefined;
+    if (nativeSearchOn(provider, platform))
+        return undefined;
+    return unsupported(`not sent on ${PLATFORM_LABEL[platform]}; the web_search sentinel is dropped (use web_extract)`);
+}
+const PLATFORM_LABEL = {
+    direct: 'the provider API',
+    vertex: 'Vertex AI',
+    bedrock: 'Bedrock',
+    azure: 'Azure OpenAI',
+};
+const SUPPORT_MARK = { supported: '✓', degraded: '◐', unsupported: '✗' };
+/** The matrix as a Markdown table plus notes, for documentation and the doctor. */
+export function renderCapabilityMatrix() {
+    const rows = Object.keys(CAPABILITY_MATRIX);
+    const label = (r) => (r === 'gateway' ? 'Gateway (any id)' : PROVIDERS[r].label);
+    const lines = [];
+    lines.push(`| Capability | ${rows.map(label).join(' | ')} |`);
+    lines.push(`|---|${rows.map(() => '---').join('|')}|`);
+    const notes = [];
+    for (const cap of CAPABILITIES) {
+        const cells = rows.map((r) => {
+            const cell = CAPABILITY_MATRIX[r][cap];
+            if (!cell.note)
+                return SUPPORT_MARK[cell.support];
+            notes.push(`${label(r)} · ${CAPABILITY_LABELS[cap]}: ${cell.note}.`);
+            return `${SUPPORT_MARK[cell.support]}${notes.length}`;
+        });
+        lines.push(`| ${CAPABILITY_LABELS[cap]} | ${cells.join(' | ')} |`);
+    }
+    lines.push('');
+    lines.push('✓ supported · ◐ degraded · ✗ unsupported. Gemini cells are ADK\'s own adapter; every other cell is asserted against the request the adapter sends.');
+    lines.push('');
+    notes.forEach((n, i) => lines.push(`${i + 1}. ${n}`));
+    lines.push('');
+    lines.push('**Cloud platforms** (ADR 0023): the same adapter and request as the provider\'s own API, except as listed. These paths are tested against mocks, not against the live clouds.');
+    lines.push('');
+    lines.push('| Path | Differs from the provider row |');
+    lines.push('|---|---|');
+    for (const provider of Object.keys(PLATFORMS_FOR)) {
+        for (const platform of PLATFORMS_FOR[provider]) {
+            if (platform === 'direct')
+                continue;
+            const diffs = CAPABILITIES.map((cap) => [cap, platformCell(provider, platform, cap)])
+                .filter(([, cell]) => cell)
+                .map(([cap, cell]) => `${CAPABILITY_LABELS[cap]}: ${SUPPORT_MARK[cell.support]} ${cell.note ?? ''}`.trim());
+            lines.push(`| ${PROVIDERS[provider].label} on ${PLATFORM_LABEL[platform]} | ${diffs.join('; ') || 'nothing'} |`);
+        }
+    }
+    return lines.join('\n');
+}

package/dist/lib/models/claudeLlm.d.ts

@@ -48,6 +48,7 @@
 import { BaseLlm } from '@google/adk';
 import type { LlmRequest, LlmResponse } from '@google/adk';
 import type { BaseLlmConnection } from '@google/adk';
+import type { ProviderEndpoint } from './endpoints.ts';
 /** ADK toolsDict → Anthropic tool definitions (lowercase schemas; the
  *  web_search sentinel becomes Anthropic's native server tool). */
 export declare function buildAnthropicTools(llmRequest: LlmRequest): any[];
@@ -58,9 +59,17 @@ export declare class ClaudeLlm extends BaseLlm {
      */
     static readonly supportedModels: Array<string | RegExp>;
     private apiKey?;
-    constructor({ model, apiKey }: {
+    private endpoint?;
+    private searchDropWarned;
+    /**
+     * `endpoint` (ADR 0023): where the request goes — Anthropic's API (or a
+     * proxy at its base URL), Bedrock, or Vertex AI. Default: the environment's
+     * (`ANTHROPIC_PLATFORM`).
+     */
+    constructor({ model, apiKey, endpoint }: {
         model: string;
         apiKey?: string;
+        endpoint?: ProviderEndpoint;
     });
     /**
      * Main generation method called by the ADK Runner for every turn.

package/dist/lib/models/claudeLlm.js

@@ -46,9 +46,11 @@
  *   translated to Anthropic's tool_use / tool_result blocks.
  */
 import { BaseLlm, LLMRegistry } from '@google/adk';
-import { traceLlmGeneration, setLlmSpanAttribute, } from "../observability/tracer.js";
-import { wantsWebSearch, isWebSearchSentinel, } from "../tools/webSearchTool.js";
-import { toLowercaseJsonSchema } from "./schemaNormalize.js";
+import { traceLlmGeneration, setLlmSpanAttribute, } from '../observability/tracer.js';
+import { wantsWebSearch, isWebSearchSentinel, } from '../tools/webSearchTool.js';
+import { providerRequestOptions } from '../runtime/turnControl.js';
+import { toLowercaseJsonSchema, toolDeclarationFor } from './schemaNormalize.js';
+import { claudeClientSpec, endpointFromEnv, instantiateClient, nativeSearchOn, platformModel, SdkMissingError } from './endpoints.js';
 /** Anthropic's minimum extended-thinking budget. */
 /** Name of the synthetic tool that carries an ADK outputSchema answer. */
 const STRUCTURED_OUTPUT_TOOL = 'structured_output';
@@ -61,12 +63,12 @@ export function buildAnthropicTools(llmRequest) {
     for (const [, tool] of Object.entries(llmRequest.toolsDict ?? {})) {
         if (isWebSearchSentinel(tool))
             continue; // added as a server tool below
-        const t = tool;
-        if (t.name && t.description) {
+        const decl = toolDeclarationFor(tool);
+        if (decl) {
             anthropicTools.push({
-                name: t.name,
-                description: t.description,
-                input_schema: toLowercaseJsonSchema(t.parameters ?? { type: 'object', properties: {} }),
+                name: decl.name,
+                description: decl.description,
+                input_schema: decl.parameters,
             });
         }
     }
@@ -89,9 +91,17 @@ export class ClaudeLlm extends BaseLlm {
      */
     static supportedModels = [/^claude-.+/];
     apiKey;
-    constructor({ model, apiKey }) {
+    endpoint;
+    searchDropWarned = false;
+    /**
+     * `endpoint` (ADR 0023): where the request goes — Anthropic's API (or a
+     * proxy at its base URL), Bedrock, or Vertex AI. Default: the environment's
+     * (`ANTHROPIC_PLATFORM`).
+     */
+    constructor({ model, apiKey, endpoint }) {
         super({ model });
         this.apiKey = apiKey;
+        this.endpoint = endpoint;
     }
     /**
      * Main generation method called by the ADK Runner for every turn.
@@ -105,29 +115,36 @@ export class ClaudeLlm extends BaseLlm {
         yield* traceLlmGeneration({ provider: 'anthropic', model: this.model, llmRequest }, this.generateInner(llmRequest, stream));
     }
     async *generateInner(llmRequest, stream) {
-        const apiKey = this.apiKey || process.env.ANTHROPIC_API_KEY;
-        if (!apiKey) {
+        let endpoint;
+        try {
+            endpoint = this.endpoint ?? endpointFromEnv('anthropic');
+        }
+        catch (err) {
+            yield { errorCode: 'ENDPOINT_MISCONFIGURED', errorMessage: err.message };
+            return;
+        }
+        const spec = claudeClientSpec(endpoint, this.apiKey || endpoint.apiKey || process.env.ANTHROPIC_API_KEY);
+        if ('error' in spec) {
             yield {
-                errorCode: 'MISSING_API_KEY',
-                errorMessage: 'ANTHROPIC_API_KEY is not set in environment.',
+                errorCode: endpoint.platform === 'direct' ? 'MISSING_API_KEY' : 'ENDPOINT_MISCONFIGURED',
+                errorMessage: spec.error,
             };
             return;
         }
-        // Dynamic import — only loads @anthropic-ai/sdk when actually called,
-        // so the framework boots without the SDK installed for Gemini-only users.
-        let Anthropic;
+        // Dynamic import — only loads the SDK (Anthropic's, or its Bedrock or
+        // Vertex AI client) when actually called, so the framework boots without
+        // it for users of other providers. All three share the Messages API.
+        let client;
         try {
-            const mod = await import('@anthropic-ai/sdk');
-            Anthropic = mod.default ?? mod.Anthropic;
+            client = await instantiateClient(spec);
         }
-        catch {
+        catch (err) {
             yield {
-                errorCode: 'SDK_NOT_INSTALLED',
-                errorMessage: 'The @anthropic-ai/sdk package is not installed. Run: npm install @anthropic-ai/sdk',
+                errorCode: err instanceof SdkMissingError ? 'SDK_NOT_INSTALLED' : 'ENDPOINT_MISCONFIGURED',
+                errorMessage: err.message,
             };
             return;
         }
-        const client = new Anthropic({ apiKey });
         // ── Translate ADK Contents → Anthropic messages ──────────────────────────
         const systemParts = [];
         const messages = [];
@@ -186,9 +203,22 @@ export class ClaudeLlm extends BaseLlm {
                 systemParts.unshift(text);
         }
         // ── Build Anthropic tool definitions from ADK toolsDict ──────────────────
-        const anthropicTools = buildAnthropicTools(llmRequest);
+        let anthropicTools = buildAnthropicTools(llmRequest);
         if (wantsWebSearch(llmRequest)) {
-            setLlmSpanAttribute('llm.web_search.native', true);
+            if (nativeSearchOn('anthropic', endpoint.platform)) {
+                setLlmSpanAttribute('llm.web_search.native', true);
+            }
+            else {
+                // Not sent off Anthropic's own API (lib/models/endpoints.ts); the
+                // doctor and the capability matrix state this before any request.
+                anthropicTools = anthropicTools.filter((t) => t.type !== 'web_search_20250305');
+                setLlmSpanAttribute('llm.web_search.omitted', true);
+                setLlmSpanAttribute('llm.capability.dropped', 'web_search');
+                if (!this.searchDropWarned) {
+                    this.searchDropWarned = true;
+                    console.warn(`⚠ web_search is not sent to Claude on ${endpoint.platform}; the agent answers without it (use web_extract).`);
+                }
+            }
         }
         // ── Extended thinking (Gemini thinkingConfig → Anthropic thinking) ───────
         const cfg = llmRequest.config ?? {};
@@ -219,7 +249,7 @@ export class ClaudeLlm extends BaseLlm {
             : undefined;
         const allTools = structuredTool ? [...anthropicTools, structuredTool] : anthropicTools;
         const requestBase = {
-            model: this.model,
+            model: platformModel(endpoint, this.model),
             max_tokens: maxTokens,
             system: systemParts.join('\n\n') || undefined,
             messages,
@@ -231,7 +261,7 @@ export class ClaudeLlm extends BaseLlm {
         try {
             if (stream) {
                 // Streaming path
-                const streamResponse = await client.messages.stream(requestBase);
+                const streamResponse = await client.messages.stream(requestBase, providerRequestOptions());
                 for await (const chunk of streamResponse) {
                     if (chunk.type === 'content_block_delta') {
                         if (chunk.delta.type === 'text_delta') {
@@ -266,7 +296,7 @@ export class ClaudeLlm extends BaseLlm {
             }
             else {
                 // Non-streaming path
-                const response = await client.messages.create(requestBase);
+                const response = await client.messages.create(requestBase, providerRequestOptions());
                 // Thinking first, as a display-only partial.
                 const thinkingText = (response.content ?? [])
                     .filter((b) => b.type === 'thinking')

package/dist/lib/models/endpoints.d.ts

@@ -0,0 +1,100 @@
+/**
+ * lib/models/endpoints.ts — where each provider's requests go and how they
+ * authenticate (ADR 0023).
+ *
+ * The model id still picks the provider (lib/models/providerMap.ts). This
+ * module picks the provider's PLATFORM: its own public API, or the cloud an
+ * enterprise reaches it through, plus a base URL for an internal proxy and a
+ * map from the YAML id to the id (or deployment) that platform knows.
+ *
+ *   provider   platforms                 credential on a cloud platform
+ *   gemini     direct | vertex           Google Application Default Credentials
+ *   anthropic  direct | bedrock | vertex AWS credential chain / Google ADC
+ *   openai     direct | azure            AZURE_OPENAI_API_KEY, else Entra ID
+ *   xai, ollama direct only
+ *
+ * Configuration comes from the environment (`endpointFromEnv`) or, per
+ * request, from the server's `credentials` plug point, which may return an
+ * API key or a partial endpoint merged over the environment's.
+ *
+ * The Vertex AI, Bedrock and Azure paths are built on each vendor SDK's own
+ * client for that platform and are tested against mocks; they have not been
+ * run against the live clouds from this repository. The doctor says so.
+ */
+import type { ProviderId } from './providerMap.ts';
+export type Platform = 'direct' | 'vertex' | 'bedrock' | 'azure';
+export declare const PLATFORMS_FOR: Record<ProviderId, readonly Platform[]>;
+export interface ProviderEndpoint {
+    platform: Platform;
+    /** direct: an OpenAI- or Anthropic-compatible proxy in front of the vendor API. */
+    baseURL?: string;
+    /** A static key: the environment's, a caller's, or one a secret manager returned. */
+    apiKey?: string;
+    /** A bearer-token source called per client (Entra ID, a secret manager). openai/azure only. */
+    token?: () => Promise<string>;
+    /** vertex: the Google Cloud project and location (region, or `global`). */
+    project?: string;
+    location?: string;
+    /** bedrock: the AWS region. */
+    region?: string;
+    /** YAML model id → the id or deployment name this platform uses. Unlisted ids pass through. */
+    models?: Record<string, string>;
+}
+/** The platform the environment selects for a provider (default direct). */
+export declare function platformFromEnv(provider: ProviderId, env?: NodeJS.ProcessEnv): Platform;
+/** A provider's endpoint as the environment configures it. */
+export declare function endpointFromEnv(provider: ProviderId, env?: NodeJS.ProcessEnv): ProviderEndpoint;
+/** Azure OpenAI's v1 API, which the plain OpenAI client speaks. */
+export declare function azureBaseURL(endpoint: string): string;
+/** The id to send: the platform's name for a YAML model id. */
+export declare function platformModel(endpoint: ProviderEndpoint | undefined, model: string): string;
+/** What is missing for an endpoint to be usable; empty when complete. */
+export declare function endpointProblems(provider: ProviderId, e: ProviderEndpoint): string[];
+/**
+ * True when a provider can be called: its key is present on the direct
+ * platform, or its cloud platform is fully configured (the cloud's own
+ * credential chain is then trusted to authenticate; the doctor says it was
+ * not checked).
+ */
+export declare function providerReady(provider: ProviderId): boolean;
+/** Merge a per-request endpoint (the credentials plug point) over the environment's. */
+export declare function mergeEndpoint(provider: ProviderId, override: Partial<ProviderEndpoint> | undefined): ProviderEndpoint;
+/** The label for logs and the doctor: "Claude on Bedrock (us-east-1)". */
+export declare function endpointLabel(provider: ProviderId, e: ProviderEndpoint): string;
+/** How a cloud platform authenticates, for the doctor. */
+export declare function credentialSource(provider: ProviderId, e: ProviderEndpoint): string;
+/** The vendor SDK package a platform needs, beyond the direct one. */
+export declare const PLATFORM_SDK: Partial<Record<`${ProviderId}/${Platform}`, string>>;
+/** Which SDK class to construct, with what options. */
+export interface ClientSpec {
+    module: string;
+    /** Export names tried in order (default export first for the direct SDKs). */
+    exportNames: string[];
+    options: Record<string, unknown>;
+}
+export type SdkImporter = (module: string) => Promise<any>;
+/**
+ * Replace how vendor SDKs are imported: for tests (a mock Bedrock client)
+ * and for bundlers that need static imports. Undefined restores the default.
+ */
+export declare function setSdkImporter(importer: SdkImporter | undefined): void;
+/** Import a spec's module and construct its client. Throws SdkMissingError when absent. */
+export declare function instantiateClient(spec: ClientSpec): Promise<any>;
+export declare class SdkMissingError extends Error {
+    readonly module: string;
+    constructor(module: string);
+}
+/** The Anthropic client for an endpoint, or why it cannot be built. */
+export declare function claudeClientSpec(e: ProviderEndpoint, apiKey: string | undefined): ClientSpec | {
+    error: string;
+};
+/** The scope Azure OpenAI tokens are issued for. */
+export declare const AZURE_COGNITIVE_SCOPE = "https://cognitiveservices.azure.com/.default";
+/**
+ * A bearer-token source from Entra ID (DefaultAzureCredential: managed
+ * identity, workload identity, the Azure CLI...), shared by every client in
+ * the process so tokens are cached and refreshed once.
+ */
+export declare function entraTokenSource(): () => Promise<string>;
+/** Platforms whose adapter does not send the provider's native web search. */
+export declare function nativeSearchOn(provider: ProviderId, platform: Platform): boolean;