@combycode/llm-sdk 1.0.0-rc.0

package/dist/plugins/internal-tools/runner/runner.d.ts

@@ -0,0 +1,47 @@
+/** InternalToolRunner — executes InternalTools with client pooling, fallback, hooks.
+ *
+ *  Contract:
+ *  1. run(toolId, input) resolves tool → validates input → resolves models → executes.
+ *  2. Key availability is checked IMMEDIATELY after tool lookup, before execution:
+ *     if no configured API key matches any of tool's required providers → throws.
+ *  3. Per attempt, skip models whose providers lack keys.
+ *  4. Emits onInternalToolCallStart/Complete/Error hooks.
+ *  5. Cost of underlying LLM calls is tracked via existing onCompletion (CostCollector).
+ *
+ *  v2 adaptation: clients are built via the engine handle's adapter resolver
+ *  (auto-discovers default adapter). The engine wires every LLMClient through
+ *  the network queue; every tool's underlying HTTP therefore inherits queue
+ *  rate-limit / retry / hook behavior automatically.
+ */
+import type { InternalTool } from '../types';
+import type { InternalToolRunnerConfig } from './types';
+export declare class InternalToolRunner {
+    private readonly config;
+    private clients;
+    private counter;
+    constructor(config: InternalToolRunnerConfig);
+    /** Execute a tool by ID. */
+    run<T = unknown>(toolId: string, input: unknown): Promise<T>;
+    /** Execute a tool instance directly (bypasses registry). */
+    runDirect<T = unknown>(tool: InternalTool, input: unknown): Promise<T>;
+    /** Close all pooled clients. */
+    destroy(): Promise<void>;
+    get poolSize(): number;
+    /** Expose the registry so adjacent tooling can resolve tools. */
+    get registry(): import("../registry").ToolRegistry;
+    private validateInput;
+    private validateOutput;
+    /** Build ordered model list. Precedence:
+     *  1. compat.recommended for this tool (benchmark-derived, cost-ranked).
+     *  2. tool.modelPreference.preferredModel.
+     *  3. tool.modelPreference.fallbackModels.
+     *  4. runner.defaultModel.
+     */
+    private resolveModels;
+    private assertKeyAvailability;
+    private parseModelId;
+    /** Build (or fetch from pool) a client pinned to (provider, model). */
+    private getClient;
+    private executeNonLLM;
+    private executeLLM;
+}

package/dist/plugins/internal-tools/runner/template.d.ts

@@ -0,0 +1,10 @@
+/** Template rendering — Mustache-style {{var}} substitution with dot-path support.
+ *  Strict: throws on missing variables. No conditionals or loops. */
+export declare function renderTemplate(template: string, vars: Record<string, unknown>): string;
+/**
+ * Parse JSON from text, tolerating common LLM preambles/postscripts.
+ * Handles markdown code fences, leading/trailing prose, extra whitespace.
+ */
+export declare function parseJsonWithFences(text: string): unknown;
+export declare function formatNumberedList(items: readonly (string | number)[], startIndex?: number): string;
+export declare function formatBulletedList(items: readonly (string | number)[], bullet?: string): string;

package/dist/plugins/internal-tools/runner/types.d.ts

@@ -0,0 +1,57 @@
+/** Types for InternalToolRunner — config, LLM tool definition. */
+import type { HookBus } from '../../../bus/hook-bus';
+import type { LLMClientConfig } from '../../../llm/client-config';
+import type { ProviderName } from '../../../llm/types/provider';
+import type { JsonSchema } from '../../../llm/types/tools';
+import type { ModelCatalog } from '../../model-catalog/catalog';
+import type { ToolRegistry } from '../registry';
+import type { CompatFile, ModelPreference } from '../types';
+import type { TokenCounter } from '../../../agent/types';
+import type { EngineHandle } from '../../../helpers/engine';
+export interface InternalToolRunnerConfig {
+    hooks: HookBus;
+    registry: ToolRegistry;
+    catalog?: ModelCatalog;
+    /** Engine handle — supplies fetch/hooks/adapter wiring for pooled clients.
+     *  When omitted, the runner can still execute non-LLM tools but every
+     *  LLM-backed tool will throw on first call. */
+    engine?: EngineHandle;
+    /** Map of provider → API key. A tool's model requires the matching key. */
+    apiKeys: Partial<Record<ProviderName, string>>;
+    /** Fallback model when a tool has no modelPreference and needs LLM. */
+    defaultModel?: string;
+    /** Benchmark-derived recommendations, keyed by tool ID. Optional. */
+    compat?: CompatFile;
+    /** Shared client options applied to every pooled LLMClient. */
+    clientOptions?: Partial<Omit<LLMClientConfig, 'provider' | 'apiKey' | 'model' | 'hooks' | 'fetch' | 'fetchStream' | 'adapter'>>;
+    /** Token counter used by tools to convert char-length to max-tokens.
+     *  Auto-created from catalog (HybridTokenCounter) when not provided. */
+    counter?: TokenCounter;
+}
+/** Context passed to a tool's resolveMaxTokens() function. */
+export interface ResolveMaxTokensContext {
+    provider: string;
+    model: string;
+    counter: TokenCounter;
+}
+/** Declarative LLM tool — prompt template + schema. Convert via defineLLMTool(). */
+export interface LLMToolDefinition {
+    id: string;
+    namespace: string;
+    name: string;
+    version: string;
+    description: string;
+    inputSchema: JsonSchema;
+    outputSchema?: JsonSchema;
+    systemPrompt?: string;
+    userTemplate?: string;
+    outputFormat?: 'text' | 'json';
+    prepareInput?: (input: Record<string, unknown>) => Record<string, unknown>;
+    resolveMaxTokens?: (input: Record<string, unknown>, ctx: ResolveMaxTokensContext) => number;
+    outputExample?: unknown;
+    variants?: import('./variants').PromptVariant[];
+    modelPreference: ModelPreference;
+    recommendedThreshold?: number;
+    tags?: string[];
+    signature?: string;
+}

package/dist/plugins/internal-tools/runner/variants.d.ts

@@ -0,0 +1,34 @@
+/** Prompt variant system — one tool, many prompts. Matched by mode, provider, or model. */
+import type { JsonSchema } from '../../../llm/types/tools';
+import type { ResolveMaxTokensContext } from './types';
+export interface PromptVariant {
+    /** Unique identifier within a tool. Conventions: "default", "strict", "for-haiku", "tool-mode". */
+    id: string;
+    description?: string;
+    systemPrompt: string;
+    userTemplate: string;
+    outputExample?: unknown;
+    outputSchema?: JsonSchema;
+    resolveMaxTokens?: (input: Record<string, unknown>, ctx: ResolveMaxTokensContext) => number;
+    modes?: string[];
+    supportedProviders?: string[];
+    supportedModels?: string[];
+    isDefault?: boolean;
+}
+export interface VariantSelectorContext {
+    provider: string;
+    model: string;
+    mode?: string;
+}
+/**
+ * Pick the best-matching variant for the given context.
+ *
+ * Priority (most-specific wins):
+ *   1. mode + supportedModels match
+ *   2. mode + supportedProviders match
+ *   3. mode + isDefault within mode filter
+ *   4. no mode + supportedModels match
+ *   5. no mode + supportedProviders match
+ *   6. global isDefault
+ */
+export declare function selectVariant(variants: PromptVariant[], ctx: VariantSelectorContext): PromptVariant;

package/dist/plugins/internal-tools/types.d.ts

@@ -0,0 +1,80 @@
+/** Tool catalog types — InternalTool, backends, filters, compatibility.
+ *
+ *  Ported from llm-sdk/src/tools/types.ts. The `execute` signature still
+ *  takes a free-form context bag; the runner populates `client`, `modelId`,
+ *  `counter`, `recordLLMResponse` at execution time. */
+import type { JsonSchema } from '../../llm/types/tools';
+import type { HookBus } from '../../bus/hook-bus';
+import type { CompletionResponse } from '../../llm/types/response';
+import type { TokenCounter } from '../../agent/types';
+export interface InternalTool {
+    id: string;
+    namespace: string;
+    name: string;
+    version: string;
+    description: string;
+    inputSchema: JsonSchema;
+    outputSchema?: JsonSchema;
+    execute: (input: unknown, ctx: InternalToolContext) => Promise<unknown>;
+    modelPreference?: ModelPreference;
+    /** Minimum average benchmark score (0-100) for a model to enter the tool's
+     *  compat `recommended` chain. Defaults to 100. */
+    recommendedThreshold?: number;
+    signature?: string;
+    signedBy?: string;
+    tags?: string[];
+}
+export interface ModelPreference {
+    preferredModel?: string;
+    fallbackModels?: string[];
+    maxTokens?: number;
+    temperature?: number;
+}
+export interface InternalToolContext {
+    hooks?: HookBus;
+    /** LLMClient pinned to the chosen model — populated by the runner. */
+    client?: unknown;
+    /** "provider/model" string for the chosen model — populated by the runner. */
+    modelId?: string;
+    /** Tool ID under execution. */
+    toolId?: string;
+    /** Token counter — populated by the runner (defaults to HybridTokenCounter). */
+    counter?: TokenCounter;
+    /** Tool implementations (e.g. defineLLMTool) invoke this after each LLM call
+     *  so the runner can capture usage/latency for cost tracking and benchmarks. */
+    recordLLMResponse?: (response: CompletionResponse) => void;
+    [key: string]: unknown;
+}
+export interface ToolBackend {
+    readonly name: string;
+    list(): Promise<InternalTool[]>;
+    get(id: string): Promise<InternalTool | null>;
+}
+export interface ToolFilter {
+    namespace?: string;
+    prefix?: string;
+    tag?: string;
+    model?: {
+        provider: string;
+        model: string;
+        minScore?: number;
+    };
+}
+export interface SearchOptions {
+    namespace?: string;
+    limit?: number;
+}
+export interface ToolCompatScore {
+    score: number;
+    testedAt: number;
+    version?: string;
+}
+/** Per-tool benchmark record used by InternalToolRunner to pick a recommended
+ *  chain. The runner ships without a bench subsystem, so the shape is declared
+ *  inline so consumers can pass a CompatFile from elsewhere (or omit it
+ *  entirely). */
+export interface ToolCompat {
+    /** Models that scored at/above the threshold, ordered by est. cost (cheapest first). */
+    recommended: string[];
+}
+export type CompatFile = Record<string, ToolCompat>;

package/dist/plugins/logger/console-sink.d.ts

@@ -0,0 +1,26 @@
+/** ConsoleSink — writes LogEvents to stdout/stderr with simple formatting.
+ *
+ *  - error/warn → stderr
+ *  - info/debug/trace → stdout
+ *
+ *  Format (default): `[ISO_TIMESTAMP] [LEVEL] [source] kind: message  {data}`
+ *  Caller may pass a custom `format` callback for full control. */
+import type { LogEvent, LogSink } from './types';
+export interface ConsoleSinkConfig {
+    /** Custom formatter overrides the default `[ts] [level] [source] kind: message`. */
+    format?: (event: LogEvent) => string;
+    /** Writers (test override). Defaults to process.stderr / process.stdout. */
+    stderr?: {
+        write: (s: string) => unknown;
+    };
+    stdout?: {
+        write: (s: string) => unknown;
+    };
+}
+export declare class ConsoleSink implements LogSink {
+    private readonly format;
+    private readonly stderr;
+    private readonly stdout;
+    constructor(config?: ConsoleSinkConfig);
+    log(event: LogEvent): void;
+}

package/dist/plugins/logger/logger.d.ts

@@ -0,0 +1,38 @@
+/** Logger — fan-out from HookBus events into one or more LogSinks.
+ *
+ *  Two ways to feed the Logger:
+ *    1. `attach(hooks)` — subscribes to known SDK hook events (onWarning today;
+ *       more added as later phases land). Converts each to a LogEvent.
+ *    2. `log(event)` — direct entry for plugins that want to log without
+ *       going through HookBus.
+ *
+ *  Level filtering: events below `minLevel` are dropped before reaching sinks.
+ *
+ *  Multiple sinks are dispatched in parallel; sink errors are caught and
+ *  re-emitted as `system.logger-sink-error` to stderr (so a bad sink can't
+ *  silently kill log delivery). */
+import type { HookBus } from '../../bus/hook-bus';
+import { type LogEvent, type LogLevel, type LogSink } from './types';
+export interface LoggerConfig {
+    sinks: LogSink[];
+    /** Drop events with rank below this level. Default: 'info'. */
+    minLevel?: LogLevel;
+}
+export declare class Logger {
+    private readonly sinks;
+    private readonly minRank;
+    private detachers;
+    constructor(config: LoggerConfig);
+    /** Manually log an event. Bypasses HookBus. */
+    log(event: LogEvent): void;
+    /** Subscribe to known hook events on a HookBus, converting each to a leveled
+     *  LogEvent (carrying the request's correlation ids). Returns this. */
+    attach(hooks: HookBus): this;
+    /** Unsubscribe from any HookBus(es) attached to. */
+    detach(): void;
+    /** Flush any buffering sinks (best-effort; errors swallowed per-sink). */
+    flush(): Promise<void>;
+    /** Detach + flush. */
+    destroy(): Promise<void>;
+    private handleSinkError;
+}

package/dist/plugins/logger/types.d.ts

@@ -0,0 +1,25 @@
+/** Logger types — sinks, levels, events. */
+import type { RequestContext } from '../../types/request-context';
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error';
+/** Numeric ranking — higher is more severe. Used to compare against minLevel. */
+export declare const LOG_LEVEL_RANK: Record<LogLevel, number>;
+export interface LogEvent {
+    timestamp: number;
+    level: LogLevel;
+    /** Logical source: 'network', 'llm', 'agent', 'server', or a plugin name. */
+    source: string;
+    /** Hook name or short identifier of the kind of event. */
+    kind: string;
+    /** Optional human-readable message. */
+    message?: string;
+    /** Accumulating IDs (userId, requestId, conversationId, callId, ...). */
+    ctx?: RequestContext;
+    /** Arbitrary structured data — sinks decide how to render. */
+    data?: Record<string, unknown>;
+}
+/** A LogSink consumes LogEvents. Built-in: ConsoleSink. Future: OTel, Sentry, File. */
+export interface LogSink {
+    log(event: LogEvent): void | Promise<void>;
+    /** Optional flush hook — called by Logger.flush() / destroy(). */
+    flush?(): void | Promise<void>;
+}

package/dist/plugins/mcp/base-transport.d.ts

@@ -0,0 +1,58 @@
+/** Shared JSON-RPC dispatch logic for MCP transports (stdio, WebSocket, HTTP).
+ *
+ * Owns:
+ *   - `pending` map + `nextId` counter (client-initiated requests)
+ *   - `handlers` field + `setHandlers()`
+ *   - `routeIncoming(msg)` — dispatch: response | server-request | notification
+ *   - `resolveResponse(msg)` — settle a pending promise from a response message
+ *   - `handleRequest(msg)` — call `handlers.onRequest` and send back the result
+ *   - `failAll(err)` — reject all in-flight pending requests
+ *   - `allocateId()` — return the next monotonic request id
+ *   - `registerPending(id, resolve, reject, timeoutMs, method)` — set up timer
+ *
+ * Each concrete transport implements:
+ *   - `protected abstract sendMessage(obj: unknown): void | Promise<void>`
+ *     Write a serialised JSON-RPC object back to the peer.
+ *   - The medium-specific lifecycle (connect / close / listen) and inbound
+ *     parsing, which ends with a call to `this.routeIncoming(parsedMsg)`.
+ */
+import { McpError } from './jsonrpc';
+import type { IncomingMcpHandlers } from './transport';
+/** A loosely-typed inbound JSON-RPC message (response, request, or notification). */
+export interface InboundMessage {
+    id?: number | string;
+    method?: string;
+    params?: unknown;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+export interface Pending {
+    resolve: (v: unknown) => void;
+    reject: (e: unknown) => void;
+    timer: ReturnType<typeof setTimeout>;
+}
+export declare abstract class BaseJsonRpcTransport {
+    protected nextId: number;
+    protected handlers: IncomingMcpHandlers;
+    protected readonly pending: Map<number, Pending>;
+    setHandlers(handlers: IncomingMcpHandlers): void;
+    /** Write a serialised JSON-RPC object back to the peer. */
+    protected abstract sendMessage(obj: unknown): void | Promise<void>;
+    /** Allocate the next monotonic request id. */
+    protected allocateId(): number;
+    /** Register a pending request and arm its timeout. */
+    protected registerPending(id: number, resolve: (v: unknown) => void, reject: (e: unknown) => void, timeoutMs: number, method: string): void;
+    /** Dispatch a parsed inbound message to the correct handler. */
+    protected routeIncoming(msg: InboundMessage): void;
+    /** Settle a pending client-initiated request from its response message. */
+    protected resolveResponse(msg: InboundMessage): void;
+    /** Handle a server-initiated request: call the registered handler and send
+     *  the result (or an error) back via `sendMessage`. */
+    protected handleRequest(msg: InboundMessage): Promise<void>;
+    /** Reject all in-flight pending requests with the given error. */
+    protected failAll(err: McpError): void;
+}

package/dist/plugins/mcp/client.d.ts

@@ -0,0 +1,92 @@
+/** McpClient — the protocol layer over a (bidirectional) transport: initialize
+ *  handshake, tools/list (paginated), tools/call, resources, prompts, and
+ *  routing of server->client requests (ping, sampling, elicitation, roots) and
+ *  notifications. */
+import type { HookBus } from '../../bus/hook-bus';
+import type { McpTransport } from './transport';
+import type { TraceContext } from '../../network/types';
+import type { McpCallResult, McpCompletionRef, McpCompletionResult, McpGetPromptResult, McpInitializeResult, McpLogLevel, McpPrompt, McpResource, McpResourceContent, McpResourceTemplate, McpTask, McpTaskMetadata, McpToolDef } from './types';
+export interface McpClientOptions {
+    clientInfo?: {
+        name: string;
+        version: string;
+    };
+    /** Capabilities to advertise in `initialize` (e.g. sampling/roots/elicitation). */
+    capabilities?: Record<string, unknown>;
+    /** Every server->client notification (logging, *_changed, progress, …). */
+    onNotification?: (method: string, params: unknown) => void;
+    /** Handle a server->client request we don't answer internally (sampling,
+     *  elicitation/create, roots/list). Return the result or throw McpError. */
+    onServerRequest?: (method: string, params: unknown) => Promise<unknown>;
+    /** Primary hooks bus for unconditional MCP telemetry (onMcpToolCall / onMcpError).
+     *  When set, emission is unconditional — no telemetry adapter is required.
+     *  `server` is the namespace label emitted in MCP hook contexts. */
+    hooks?: HookBus;
+    /** MCP namespace / server label (paired with `hooks`). */
+    server?: string;
+    /** @deprecated Use `hooks` + `server` instead. Kept for backward compatibility. */
+    telemetry?: {
+        hooks: HookBus;
+        server: string;
+    };
+    /** Send a `ping` every N ms to keep the connection alive (0/undefined = off). */
+    keepAliveMs?: number;
+}
+export declare class McpClient {
+    private readonly transport;
+    private readonly opts;
+    private serverInfo;
+    private pingTimer;
+    constructor(transport: McpTransport, opts?: McpClientOptions);
+    /** The server's `initialize` result, or null before `connect()`. */
+    get info(): McpInitializeResult | null;
+    /** Open the transport, run the initialize handshake, and start listening for
+     *  server-initiated messages. */
+    connect(): Promise<McpInitializeResult>;
+    /** List every tool the server exposes (follows cursor pagination). */
+    listTools(): Promise<McpToolDef[]>;
+    /** Follow cursor pagination for a list method, collecting `field` from each page. */
+    private paginate;
+    /** Invoke a tool by its (un-namespaced) server name.
+     *  Pass `trace` when the call originates from an AgentLoop run so that
+     *  `onMcpToolCall` and `onMcpError` carry the run's sessionId/requestId. */
+    callTool(name: string, args?: Record<string, unknown>, trace?: TraceContext): Promise<McpCallResult>;
+    /** List the server's resources (follows cursor pagination). */
+    listResources(): Promise<McpResource[]>;
+    /** List the server's resource templates. */
+    listResourceTemplates(): Promise<McpResourceTemplate[]>;
+    /** Read a resource's contents by URI. */
+    readResource(uri: string): Promise<McpResourceContent[]>;
+    /** Subscribe to updates for a resource (server sends `notifications/resources/updated`). */
+    subscribeResource(uri: string): Promise<void>;
+    unsubscribeResource(uri: string): Promise<void>;
+    /** List the server's prompts (follows cursor pagination). */
+    listPrompts(): Promise<McpPrompt[]>;
+    /** Render a prompt by name with arguments → its messages. */
+    getPrompt(name: string, args?: Record<string, string>): Promise<McpGetPromptResult>;
+    /** Set the server's log verbosity (it then sends `notifications/message`). */
+    setLogLevel(level: McpLogLevel): Promise<void>;
+    /** Argument autocompletion for a prompt or resource template. */
+    completeArgument(ref: McpCompletionRef, argument: {
+        name: string;
+        value: string;
+    }): Promise<McpCompletionResult>;
+    /** Call a tool as a long-running task; returns the created task immediately. */
+    callToolTask(name: string, args?: Record<string, unknown>, meta?: McpTaskMetadata): Promise<McpTask>;
+    /** Current status of a task. */
+    getTask(taskId: string): Promise<McpTask>;
+    /** The final result of a completed task. */
+    getTaskResult(taskId: string): Promise<McpCallResult>;
+    /** List the server's tasks. */
+    listTasks(): Promise<McpTask[]>;
+    cancelTask(taskId: string): Promise<void>;
+    /** Poll `tasks/get` until the task reaches a terminal status. */
+    awaitTask(taskId: string, opts?: {
+        pollIntervalMs?: number;
+        timeoutMs?: number;
+    }): Promise<McpTask>;
+    /** Low-level escape hatch: send any request method. */
+    request(method: string, params?: unknown): Promise<unknown>;
+    close(): Promise<void>;
+    private handleServerRequest;
+}

package/dist/plugins/mcp/jsonrpc.d.ts

@@ -0,0 +1,20 @@
+/** JSON-RPC 2.0 error codes + the error type the MCP client throws on a
+ *  protocol-level failure (distinct from a tool-level `isError` result). */
+import type { JsonRpcError } from './types';
+export declare const McpErrorCode: {
+    readonly ConnectionClosed: -32000;
+    readonly RequestTimeout: -32001;
+    readonly ParseError: -32700;
+    readonly InvalidRequest: -32600;
+    readonly MethodNotFound: -32601;
+    readonly InvalidParams: -32602;
+    readonly InternalError: -32603;
+};
+/** A JSON-RPC / transport level error (server unreachable, error response,
+ *  timeout). Tool execution failures arrive as a normal result with
+ *  `isError: true` and are NOT thrown. */
+export declare class McpError extends Error {
+    readonly code: number;
+    readonly data?: unknown;
+    constructor(err: JsonRpcError);
+}

package/dist/plugins/mcp/oauth.d.ts

@@ -0,0 +1,122 @@
+/** OAuth 2.1 + PKCE for MCP servers that require authorization (zero-dep).
+ *
+ *  The library owns the non-interactive machinery — metadata discovery, PKCE,
+ *  dynamic client registration, authorization-code exchange, and token refresh —
+ *  and delegates the inherently-interactive bits (storing tokens, redirecting
+ *  the user, capturing the callback code) to an `McpAuthProvider` the consumer
+ *  implements. All HTTP goes through the engine's fetch. */
+import type { EngineFetch } from '../../network/types';
+import type { SsrfGuardOptions } from './url-guard';
+export interface McpOAuthTokens {
+    access_token: string;
+    token_type?: string;
+    expires_in?: number;
+    refresh_token?: string;
+    scope?: string;
+    /** Stamped by us when the tokens were obtained (for expiry math). */
+    obtained_at?: number;
+}
+export interface McpOAuthClientInfo {
+    client_id: string;
+    client_secret?: string;
+}
+export interface McpOAuthClientMetadata {
+    redirect_uris: string[];
+    client_name?: string;
+    scope?: string;
+    grant_types?: string[];
+    response_types?: string[];
+    token_endpoint_auth_method?: string;
+}
+/** Consumer-implemented storage + interactive redirect. */
+export interface McpAuthProvider {
+    /** Where the authorization server redirects back to. */
+    readonly redirectUrl: string;
+    /** Metadata used for dynamic client registration. */
+    readonly clientMetadata: McpOAuthClientMetadata;
+    clientInformation(): McpOAuthClientInfo | undefined | Promise<McpOAuthClientInfo | undefined>;
+    saveClientInformation?(info: McpOAuthClientInfo): void | Promise<void>;
+    tokens(): McpOAuthTokens | undefined | Promise<McpOAuthTokens | undefined>;
+    saveTokens(tokens: McpOAuthTokens): void | Promise<void>;
+    /** Open / navigate to the authorization URL. */
+    redirectToAuthorization(authorizationUrl: string): void | Promise<void>;
+    saveCodeVerifier(verifier: string): void | Promise<void>;
+    codeVerifier(): string | Promise<string>;
+    /** Persist the CSRF state token generated during redirect (required for validation). */
+    saveState(state: string): void | Promise<void>;
+    /** Retrieve the persisted state token for comparison on callback. */
+    state(): string | undefined | Promise<string | undefined>;
+}
+export interface AuthServerMetadata {
+    authorization_endpoint: string;
+    token_endpoint: string;
+    registration_endpoint?: string;
+}
+/** Security options for the OAuth flow.  All fields default to the most
+ *  restrictive posture.  Re-exported from `url-guard` for consumer convenience. */
+export type { SsrfGuardOptions as McpOAuthSecurityOptions };
+/** Thrown when an interactive authorization is required (the provider's
+ *  `redirectToAuthorization` has been called; finish via `finishMcpAuth`). */
+export declare class McpUnauthorizedError extends Error {
+    constructor(message?: string);
+}
+/** Generate a PKCE code verifier + S256 challenge. */
+export declare function generatePkce(): Promise<{
+    verifier: string;
+    challenge: string;
+}>;
+/** Generate a cryptographically-random CSRF state token (32 bytes, base64url). */
+export declare function generateState(): string;
+/** Discover the authorization-server metadata for an MCP server URL.
+ *  All discovered endpoint URLs are validated against the SSRF guard before
+ *  being returned; pass `security` to configure the allowlist or escape hatches. */
+export declare function discoverMetadata(fetch: EngineFetch, serverUrl: string, security?: SsrfGuardOptions): Promise<AuthServerMetadata>;
+/** Dynamic Client Registration (RFC 7591).
+ *  The `serverUrl` anchor is required so the SSRF guard can check the endpoint origin. */
+export declare function registerClient(fetch: EngineFetch, registrationEndpoint: string, metadata: McpOAuthClientMetadata, serverUrl: string, security?: SsrfGuardOptions): Promise<McpOAuthClientInfo>;
+/** Build the authorization URL (code flow + PKCE). */
+export declare function buildAuthorizationUrl(authorizationEndpoint: string, params: {
+    client_id: string;
+    redirect_uri: string;
+    code_challenge: string;
+    scope?: string;
+    state?: string;
+    resource?: string;
+}): string;
+/** Exchange an authorization code for tokens. */
+export declare function exchangeCode(fetch: EngineFetch, tokenEndpoint: string, p: {
+    code: string;
+    code_verifier: string;
+    client_id: string;
+    client_secret?: string;
+    redirect_uri: string;
+    resource?: string;
+}): Promise<McpOAuthTokens>;
+/** Refresh tokens with a refresh_token. */
+export declare function refreshTokens(fetch: EngineFetch, tokenEndpoint: string, p: {
+    refresh_token: string;
+    client_id: string;
+    client_secret?: string;
+}): Promise<McpOAuthTokens>;
+export declare class McpOAuth {
+    private readonly serverUrl;
+    private readonly provider;
+    private readonly fetch;
+    private readonly security;
+    private metadata;
+    constructor(serverUrl: string, provider: McpAuthProvider, fetch: EngineFetch, security?: SsrfGuardOptions);
+    /** Ensure a usable access token exists. Returns 'redirect' if the user must
+     *  authorize interactively (the provider has been asked to redirect). */
+    authorize(): Promise<'authorized' | 'redirect'>;
+    /** Bearer header for a request (refreshing a stale token if possible). */
+    authHeader(): Promise<Record<string, string>>;
+    /** Handle a 401: refresh if we can (return true -> retry), else start a redirect. */
+    reauthorize(): Promise<boolean>;
+    /** Finish the interactive flow: exchange the callback code for tokens.
+     *  The `returnedState` MUST match the state persisted during redirect (CSRF guard). */
+    finish(code: string, returnedState: string): Promise<void>;
+    private startRedirect;
+    private tryRefresh;
+    private ensureMetadata;
+    private ensureClient;
+}

package/dist/plugins/mcp/sampling.d.ts

@@ -0,0 +1,17 @@
+/** Sampling (P3): when an MCP server sends `sampling/createMessage`, it is asking
+ *  US to run an LLM completion on its behalf. We fulfill it with our own engine —
+ *  so the server borrows our multi-provider brain. The caller either supplies a
+ *  custom handler or a model id to auto-wire. */
+import type { EngineHandle } from '../../helpers/engine';
+import type { ProviderName } from '../../llm/types/provider';
+import type { McpCreateMessageParams, McpCreateMessageResult } from './types';
+export type McpSamplingHandler = (params: McpCreateMessageParams) => Promise<McpCreateMessageResult>;
+/** Auto-wire sampling to our LLM. */
+export interface McpSamplingViaLLM {
+    model: string;
+    provider?: ProviderName;
+    engine?: EngineHandle;
+}
+export type McpSamplingConfig = McpSamplingHandler | McpSamplingViaLLM;
+/** Build a sampling handler: pass-through a custom function, or auto-wire a model. */
+export declare function samplingHandler(config: McpSamplingConfig): McpSamplingHandler;

package/dist/plugins/mcp/tools.d.ts

@@ -0,0 +1,20 @@
+/** Adapt MCP results into our shapes: tool-call results -> AgentTool results,
+ *  and prompt results -> Message[]. */
+import type { AgentTool } from '../../agent/types';
+import type { ContentPart, Message } from '../../llm/types/messages';
+import type { McpClient } from './client';
+import type { McpCallResult, McpGetPromptResult, McpToolDef } from './types';
+export interface McpToolAdapterOptions {
+    /** Validate `structuredContent` against the tool's `outputSchema`; on mismatch
+     *  the tool returns an error string instead of the content. Default false. */
+    validateOutput?: boolean;
+}
+/** Map a `tools/call` result to our tool-result shape: a plain string when the
+ *  content is text-only, else a ContentPart[] (images/audio kept as base64).
+ *  A tool-level `isError` is surfaced to the model as text, not thrown. */
+export declare function mcpContentToResult(res: McpCallResult): string | ContentPart[];
+/** Map a `prompts/get` result to our Message[] (drop straight into a request). */
+export declare function mcpPromptToMessages(result: McpGetPromptResult): Message[];
+/** Wrap one MCP tool as an `AgentTool`. The model sees `<namespace>__<tool>`
+ *  (collision-free across servers); execution calls the server with the raw name. */
+export declare function mcpToolToAgentTool(client: McpClient, tool: McpToolDef, namespace: string, opts?: McpToolAdapterOptions): AgentTool;