indusagi 0.12.32 → 0.12.34

package/dist/types/facade/ml/stream.d.ts

@@ -0,0 +1,27 @@
+import "./adapters/register-builtins.js";
+import type { Api, AssistantMessage, AssistantMessageEventStream, Context, Model, SimpleStreamOptions, StreamOptions } from "./types.js";
+export { getEnvApiKey } from "./env-api-keys.js";
+/**
+ * Optional sink for diagnostic traces emitted while a request is dispatched.
+ * Supplying one lets callers observe start-of-stream events without coupling
+ * this module to any particular logging library.
+ */
+export interface StreamLogger {
+    debug?: (message: string, details?: unknown) => void;
+}
+/**
+ * Open a streaming response for the given model and request context. Validates
+ * inputs, resolves the matching backend, optionally traces the dispatch, then
+ * hands off to the backend's full streaming path.
+ */
+export declare function stream<TApi extends Api>(model: Model<TApi>, context: Context, options?: StreamOptions, logger?: StreamLogger): AssistantMessageEventStream;
+/** Run a full stream to completion and resolve with the final assistant message. */
+export declare function complete<TApi extends Api>(model: Model<TApi>, context: Context, options?: StreamOptions, logger?: StreamLogger): Promise<AssistantMessage>;
+/**
+ * Open a streaming response over the simplified options surface, which omits
+ * tool wiring and other advanced knobs. Same validate/resolve/trace path as
+ * {@link stream}, but dispatched to the backend's simple entry point.
+ */
+export declare function streamSimple<TApi extends Api>(model: Model<TApi>, context: Context, options?: SimpleStreamOptions, logger?: StreamLogger): AssistantMessageEventStream;
+export declare function completeSimple<TApi extends Api>(model: Model<TApi>, context: Context, options?: SimpleStreamOptions, logger?: StreamLogger): Promise<AssistantMessage>;
+export declare function streamByApi<TApi extends Api>(api: TApi, model: Model<TApi>, context: Context, options?: StreamOptions, logger?: StreamLogger): AssistantMessageEventStream;

package/dist/types/facade/ml/types.d.ts

@@ -0,0 +1,269 @@
+import type { AssistantMessageEventStream } from "./kit/event-stream.js";
+export type { AssistantMessageEventStream } from "./kit/event-stream.js";
+export type KnownApi = "mock-ai" | "openai-completions" | "openai-responses" | "azure-openai-responses" | "openai-codex-responses" | "anthropic-messages" | "bedrock-converse-stream" | "google-generative-ai" | "google-vertex" | "kimi-openai-compatible" | "nvidia-openai-compatible";
+export type Api = KnownApi | (string & {});
+export type KnownProvider = "mock" | "amazon-bedrock" | "anthropic" | "google" | "google-vertex" | "openai" | "azure-openai-responses" | "openai-codex" | "github-copilot" | "xai" | "groq" | "cerebras" | "openrouter" | "vercel-ai-gateway" | "zai" | "mistral" | "minimax" | "minimax-cn" | "opencode" | "kimi" | "kimi-coding" | "sarvam" | "krutrim" | "nvidia";
+export type Provider = KnownProvider | string;
+export type ThinkingLevel = "minimal" | "low" | "medium" | "high" | "xhigh";
+/** Per-level token allowances for reasoning, used only by token-budget providers. */
+export interface ThinkingBudgets {
+    minimal?: number;
+    low?: number;
+    medium?: number;
+    high?: number;
+}
+export interface StreamOptions {
+    temperature?: number;
+    maxTokens?: number;
+    signal?: AbortSignal;
+    apiKey?: string;
+    /**
+     * Identifier a provider may use to tie related requests together, e.g. to
+     * key prompt caching or routing. Providers that lack such a feature ignore it.
+     */
+    sessionId?: string;
+    /**
+     * Hook invoked with the outgoing provider payload right before it is sent.
+     */
+    onPayload?: (payload: unknown) => void;
+    /**
+     * Extra HTTP headers to attach to the request. These are combined with the
+     * provider's defaults and may overwrite them. Providers that authenticate via
+     * an SDK rather than raw HTTP (such as AWS Bedrock) do not apply them.
+     */
+    headers?: Record<string, string>;
+}
+export type ProviderStreamOptions = StreamOptions & Record<string, unknown>;
+export interface SimpleStreamOptions extends StreamOptions {
+    reasoning?: ThinkingLevel;
+    /** Override the default reasoning budgets; only honored by token-budget providers. */
+    thinkingBudgets?: ThinkingBudgets;
+}
+export type StreamFunction<TApi extends Api = Api, TOptions extends StreamOptions = StreamOptions> = (model: Model<TApi>, context: Context, options?: TOptions) => AssistantMessageEventStream;
+export interface TextContent {
+    type: "text";
+    text: string;
+    textSignature?: string;
+}
+export interface ThinkingContent {
+    type: "thinking";
+    thinking: string;
+    thinkingSignature?: string;
+}
+export interface ImageContent {
+    type: "image";
+    data: string;
+    mimeType: string;
+}
+export interface ToolCall {
+    type: "toolCall";
+    id: string;
+    name: string;
+    arguments: Record<string, any>;
+    thoughtSignature?: string;
+}
+export interface Usage {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    totalTokens: number;
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        total: number;
+    };
+}
+export type StopReason = "stop" | "length" | "toolUse" | "error" | "aborted";
+export interface UserMessage {
+    role: "user";
+    content: string | (TextContent | ImageContent)[];
+    timestamp: number;
+}
+export interface AssistantMessage {
+    role: "assistant";
+    content: (TextContent | ThinkingContent | ToolCall)[];
+    api: Api;
+    provider: Provider;
+    model: string;
+    usage: Usage;
+    stopReason: StopReason;
+    errorMessage?: string;
+    timestamp: number;
+}
+export interface ToolResultMessage<TDetails = any> {
+    role: "toolResult";
+    toolCallId: string;
+    toolName: string;
+    content: (TextContent | ImageContent)[];
+    details?: TDetails;
+    isError: boolean;
+    timestamp: number;
+}
+export type Message = UserMessage | AssistantMessage | ToolResultMessage;
+import type { TSchema } from "@sinclair/typebox";
+export interface JsonSchema {
+    type?: string;
+    description?: string;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    additionalProperties?: boolean;
+    items?: JsonSchema;
+    enum?: unknown[];
+    [key: string]: unknown;
+}
+export interface Tool<TParameters extends JsonSchema | TSchema = JsonSchema | TSchema> {
+    name: string;
+    description: string;
+    parameters: TParameters;
+}
+export interface Context {
+    systemPrompt?: string;
+    messages: Message[];
+    tools?: Tool[];
+}
+export type AssistantMessageEvent = {
+    type: "start";
+    partial: AssistantMessage;
+} | {
+    type: "text_start";
+    contentIndex: number;
+    partial: AssistantMessage;
+} | {
+    type: "text_delta";
+    contentIndex: number;
+    delta: string;
+    partial: AssistantMessage;
+} | {
+    type: "text_end";
+    contentIndex: number;
+    content: string;
+    partial: AssistantMessage;
+} | {
+    type: "thinking_start";
+    contentIndex: number;
+    partial: AssistantMessage;
+} | {
+    type: "thinking_delta";
+    contentIndex: number;
+    delta: string;
+    partial: AssistantMessage;
+} | {
+    type: "thinking_end";
+    contentIndex: number;
+    content: string;
+    partial: AssistantMessage;
+} | {
+    type: "toolcall_start";
+    contentIndex: number;
+    partial: AssistantMessage;
+} | {
+    type: "toolcall_delta";
+    contentIndex: number;
+    delta: string;
+    partial: AssistantMessage;
+} | {
+    type: "toolcall_end";
+    contentIndex: number;
+    toolCall: ToolCall;
+    partial: AssistantMessage;
+} | {
+    type: "done";
+    reason: Extract<StopReason, "stop" | "length" | "toolUse">;
+    message: AssistantMessage;
+} | {
+    type: "error";
+    reason: Extract<StopReason, "aborted" | "error">;
+    error: AssistantMessage;
+};
+/**
+ * Per-endpoint quirks for OpenAI-compatible chat-completions backends.
+ * When a field is left unset, the adapter infers a value from the base URL;
+ * set it explicitly to pin behavior for a custom or self-hosted endpoint.
+ */
+export interface OpenAICompletionsCompat {
+    /** Does the endpoint accept the `store` flag? Inferred from the URL when omitted. */
+    supportsStore?: boolean;
+    /** Does the endpoint accept a `developer` role in place of `system`? Inferred from the URL when omitted. */
+    supportsDeveloperRole?: boolean;
+    /** Does the endpoint accept `reasoning_effort`? Inferred from the URL when omitted. */
+    supportsReasoningEffort?: boolean;
+    /** Does the endpoint emit usage when asked via `stream_options: { include_usage: true }`? Defaults to true. */
+    supportsUsageInStreaming?: boolean;
+    /** Name of the output-token cap field to send. Inferred from the URL when omitted. */
+    maxTokensField?: "max_completion_tokens" | "max_tokens";
+    /** Must tool-result messages carry a `name` field? Inferred from the URL when omitted. */
+    requiresToolResultName?: boolean;
+    /** Must an assistant turn sit between tool results and the next user turn? Inferred from the URL when omitted. */
+    requiresAssistantAfterToolResult?: boolean;
+    /** Must reasoning blocks be flattened to text wrapped in <thinking> tags? Inferred from the URL when omitted. */
+    requiresThinkingAsText?: boolean;
+    /** Must tool-call ids be coerced to the Mistral shape (exactly 9 alphanumerics)? Inferred from the URL when omitted. */
+    requiresMistralToolIds?: boolean;
+    /** Shape of the reasoning parameter: "openai" sends reasoning_effort, "zai" sends thinking: { type: "enabled" }. Defaults to "openai". */
+    thinkingFormat?: "openai" | "zai";
+    /** Routing hints applied only when the base URL targets OpenRouter. */
+    openRouterRouting?: OpenRouterRouting;
+}
+/** Per-endpoint quirks for OpenAI Responses backends. Currently a placeholder. */
+export interface OpenAIResponsesCompat {
+}
+/**
+ * Upstream-routing hints for OpenRouter.
+ * Lets the caller constrain which downstream providers OpenRouter may dispatch to.
+ * @see https://openrouter.ai/docs/provider-routing
+ */
+export interface OpenRouterRouting {
+    /** Restrict dispatch to exactly these provider slugs (e.g. ["amazon-bedrock", "anthropic"]). */
+    only?: string[];
+    /** Preferred provider slugs to attempt in sequence (e.g. ["anthropic", "openai"]). */
+    order?: string[];
+}
+export interface Model<TApi extends Api> {
+    id: string;
+    name: string;
+    api: TApi;
+    provider: Provider;
+    baseUrl: string;
+    reasoning: boolean;
+    input: ("text" | "image")[];
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+    };
+    contextWindow: number;
+    maxTokens: number;
+    headers?: Record<string, string>;
+    /** Endpoint-quirk overrides for OpenAI-compatible APIs; inferred from baseUrl when absent. */
+    compat?: TApi extends "openai-completions" ? OpenAICompletionsCompat : TApi extends "openai-responses" ? OpenAIResponsesCompat : never;
+}
+/** All API identifiers wired up by the built-in adapters. */
+export declare const API_NAMES: readonly KnownApi[];
+/** All provider identifiers the catalog recognizes. */
+export declare const PROVIDER_NAMES: readonly KnownProvider[];
+/** The full set of terminal stop reasons a stream can report. */
+export declare const STOP_REASONS: readonly StopReason[];
+export declare const isTextContent: (value: unknown) => value is TextContent;
+export declare const isThinkingContent: (value: unknown) => value is ThinkingContent;
+export declare const isImageContent: (value: unknown) => value is ImageContent;
+export declare const isToolCall: (value: unknown) => value is ToolCall;
+export declare const isUserMessage: (value: unknown) => value is UserMessage;
+export declare const isAssistantMessage: (value: unknown) => value is AssistantMessage;
+export declare const isToolResultMessage: (value: unknown) => value is ToolResultMessage;
+export declare const isMessage: (value: unknown) => value is Message;
+export declare function createZeroUsage(): Usage;
+export declare function createAssistantMessage(params: {
+    api: Api;
+    provider: Provider;
+    model: string;
+    content?: AssistantMessage["content"];
+    stopReason?: StopReason;
+    errorMessage?: string;
+}): AssistantMessage;
+export declare function validateTool(tool: unknown): asserts tool is Tool;
+export declare function validateMessage(message: unknown): asserts message is Message;
+export declare function validateContext(context: unknown): asserts context is Context;

package/dist/types/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Indusagi — a terminal-first AI coding-agent framework.
+ *
+ * The public surface is organized by capability layer. Each subsystem is also
+ * reachable via its own subpath export (e.g. `indusagi/llmgateway`).
+ */
+export * as gateway from "./llmgateway";
+export * as runtime from "./runtime";
+export * as capabilities from "./capabilities";
+export * as interop from "./interop";
+export * as saas from "./connectors-saas";
+export * as swarm from "./swarm";
+export * as smithy from "./smithy";
+export * as tracing from "./tracing";
+export * as shell from "./shell-app";
+export declare const VERSION = "0.1.0";

package/dist/types/interop/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The interop layer — public surface.
+ *
+ * Indusagi's bridge to the wider Model Context Protocol ecosystem. The agent can
+ * act as a *client* of external MCP servers (connecting to them, enumerating
+ * their tools, and grafting those tools into its own kernel) and as a *provider
+ * host* (standing up an MCP server that publishes the agent's own built-in tools
+ * to outside clients). This barrel re-exports both halves from the protocol
+ * bridge so downstream consumers have one import site for the whole subsystem.
+ */
+export { ServerEndpointImpl, createServerEndpoint, ServerFleetImpl, startServerFleet, mountProtocolBridge, createProviderHost, ProtocolFault, protocolFault, isProtocolFault, isUsablePhase, isTerminalPhase, QUALIFIER, qualifyToolName, normalizeSchema, } from "./protocol-bridge";
+export type { ServerEndpoint, ServerFleet, ProviderHost, ProviderHostInfo, MountedProtocolBridge, FaultKind, EndpointPhase, StdioServerConfig, SseServerConfig, ServerConfig, TransportKind, BridgeConfig, RemoteToolRef, RemoteTool, RemoteCallResult, EndpointStatus, FleetStatus, MountedBridge, } from "./protocol-bridge";

package/dist/types/interop/interop.test.d.ts

@@ -0,0 +1,19 @@
+/**
+ * In-memory round-trip tests for the protocol bridge.
+ *
+ * The whole client/server loop is exercised without spawning a single process.
+ * A {@link createProviderHost} stands up the *server* half over an
+ * {@link InMemoryTransport}, publishing one trivial tool — `ping`, which returns
+ * the text `"pong"`. A {@link createServerEndpoint} stands up the *client* half
+ * over the transport's paired socket. Because the two halves share a linked pair,
+ * a `listTools` / `callTool` issued on the client travels to the host, runs the
+ * real kernel runner, and returns — all in one process.
+ *
+ * The cases pin the four behaviours a downstream consumer depends on:
+ *   1. the endpoint enumerates the host's tools (under their qualified names);
+ *   2. invoking a tool returns the host's content faithfully;
+ *   3. the `mountProtocolBridge` wrapping shape — a {@link defineTool} whose `run`
+ *      forwards to the endpoint — yields the same `"pong"`;
+ *   4. an operation before `connect` faults with kind `not_connected`.
+ */
+export {};

package/dist/types/interop/protocol-bridge/bridge.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Mounting the protocol bridge — grafting external MCP tools into the kernel.
+ *
+ * This module is the join between the two halves of the bridge. On one side sits
+ * a {@link ServerFleet} of live {@link ServerEndpoint}s, each speaking to an
+ * external MCP server. On the other sits the kernel's {@link ToolRegistry}, which
+ * the agent runs against. {@link mountProtocolBridge} starts the fleet, lists
+ * each *ready* endpoint's tools, and wraps every remote tool as a kernel
+ * {@link import("../../capabilities").DefinedTool} whose `run` routes the call
+ * back across the endpoint that owns it.
+ *
+ * Three translation concerns live here and nowhere else:
+ *
+ *   - **Naming.** Remote tool names are unique only within their own server, so
+ *     each is grafted under its collision-free qualified name
+ *     (`"<server>__<tool>"`, see {@link qualifyToolName}). The endpoint has
+ *     already stamped that qualified name onto each {@link RemoteTool.descriptor},
+ *     so the wrapper advertises it and routes back to the *unqualified*
+ *     {@link RemoteToolRef.name} the server actually knows.
+ *   - **Schema.** Each remote `inputSchema` is run through {@link normalizeSchema}
+ *     before it is shown to the model, so an untrusted, draft-divergent remote
+ *     schema becomes the clean subset every provider accepts.
+ *   - **Result.** A {@link RemoteCallResult}'s MCP content blocks are projected
+ *     onto the kernel's {@link ToolResult} content blocks, and its `isError`
+ *     flag is carried straight through.
+ *
+ * Failure isolation is inherited from the fleet: an endpoint that faulted on
+ * connect is simply not `ready`, contributes no tools, and is skipped here
+ * without sinking the mount.
+ */
+import type { ToolBox } from "../../runtime/contract";
+import type { BridgeConfig, ServerFleet } from "./contract";
+/** The successful result of mounting the bridge: the box plus the live fleet. */
+export interface MountedProtocolBridge {
+    /** The tool box exposing every grafted remote tool to the agent. */
+    readonly box: ToolBox;
+    /** The running fleet of endpoints backing those tools. */
+    readonly fleet: ServerFleet;
+}
+/**
+ * Start the fleet, graft every reachable remote tool into a fresh registry, and
+ * return the runnable {@link ToolBox} alongside the live {@link ServerFleet}.
+ *
+ * Only endpoints that came up `ready` are queried; a faulted endpoint is skipped.
+ * Each ready endpoint's tools are listed, wrapped, and registered under their
+ * qualified `"<server>__<tool>"` names — collision-free across servers — and the
+ * union of every wrapped tool is boxed into a single {@link ToolBox} the agent
+ * runs against.
+ *
+ * @param config the set of servers to connect and expose
+ */
+export declare function mountProtocolBridge(config: BridgeConfig): Promise<MountedProtocolBridge>;

package/dist/types/interop/protocol-bridge/contract.d.ts

@@ -0,0 +1,249 @@
+/**
+ * Frozen type contract for the protocol bridge.
+ *
+ * The protocol bridge connects this agent to external Model Context Protocol
+ * servers and grafts their tools into the kernel's {@link ToolRegistry}. This
+ * module owns the *vocabulary* of that subsystem — the fault model, the endpoint
+ * lifecycle, the per-server configuration shapes, and the small handles the
+ * endpoint, fleet, and host pass between one another. It declares no behaviour;
+ * every executable part of the bridge imports its nouns from here so there is a
+ * single source of truth.
+ *
+ * Three deliberate design choices distinguish this contract:
+ *
+ *   - Faults are a *discriminated kind on an Error*, not an enum of numeric
+ *     codes with a factory per code. A caller branches on {@link FaultKind};
+ *     the underlying cause rides the native {@link Error.cause} chain.
+ *   - An endpoint advertises an explicit {@link EndpointPhase} state machine
+ *     rather than a scatter of `isConnected` / `connectionPromise` booleans.
+ *   - A server's configuration is a discriminated union on its transport
+ *     {@link ServerConfig.kind}, so a stdio server and an SSE server cannot be
+ *     confused at the type level.
+ */
+import type { ToolDescriptor } from "../../llmgateway/contract";
+import type { ToolBox } from "../../runtime/contract";
+/**
+ * The class of failure the bridge can surface.
+ *
+ * A small, closed vocabulary chosen so a caller can branch on the *cause class*
+ * without inspecting message text:
+ *
+ *   - `transport`     — the underlying byte stream failed (socket dropped, pipe
+ *     broke, HTTP request errored).
+ *   - `protocol`      — a message arrived but violated the MCP / JSON-RPC
+ *     contract (malformed envelope, unexpected method, bad result shape).
+ *   - `timeout`       — a request was issued but no reply arrived in time.
+ *   - `tool_error`    — a remote tool ran and reported its own failure.
+ *   - `not_connected` — an operation was attempted on an endpoint that is not in
+ *     the {@link EndpointPhase} `ready` state.
+ *   - `spawn_failed`  — a stdio server subprocess could not be started.
+ */
+export type FaultKind = "transport" | "protocol" | "timeout" | "tool_error" | "not_connected" | "spawn_failed";
+/**
+ * A normalized, discriminable failure raised anywhere inside the bridge.
+ *
+ * The failure class lives on {@link ProtocolFault.kind}; the triggering value
+ * (an SDK error, a thrown string, a rejected promise) rides the standard
+ * {@link Error.cause} chain rather than a bespoke field. Construct one with
+ * {@link protocolFault}.
+ */
+export declare class ProtocolFault extends Error {
+    /** Discriminates the failure class. */
+    readonly kind: FaultKind;
+    constructor(kind: FaultKind, message: string, cause?: unknown);
+}
+/**
+ * Construct a {@link ProtocolFault}. Convenience over the constructor that keeps
+ * call sites terse and uniform.
+ */
+export declare function protocolFault(kind: FaultKind, message: string, cause?: unknown): ProtocolFault;
+/** Narrowing guard: true when `value` is a {@link ProtocolFault}. */
+export declare function isProtocolFault(value: unknown): value is ProtocolFault;
+/**
+ * The lifecycle states of a single {@link ServerEndpoint}.
+ *
+ * An endpoint advances through this machine rather than juggling loose boolean
+ * flags. The legal progression is:
+ *
+ *   idle ──▶ connecting ──▶ ready ──▶ closing ──▶ closed
+ *              │              │          │
+ *              └──────────────┴──────────┴──────▶ faulted
+ *
+ *   - `idle`       — constructed but no connection has been attempted.
+ *   - `connecting` — a connection attempt is in flight.
+ *   - `ready`      — initialized and able to serve tool calls.
+ *   - `closing`    — a graceful shutdown is in progress.
+ *   - `closed`     — shut down cleanly; terminal.
+ *   - `faulted`    — a fault aborted the endpoint; terminal.
+ */
+export type EndpointPhase = "idle" | "connecting" | "ready" | "closing" | "closed" | "faulted";
+/** True when an endpoint in this phase can accept tool calls. */
+export declare function isUsablePhase(phase: EndpointPhase): boolean;
+/** True when an endpoint in this phase has reached a terminal state. */
+export declare function isTerminalPhase(phase: EndpointPhase): boolean;
+/** A server reached by spawning a subprocess and speaking JSON-RPC over stdio. */
+export interface StdioServerConfig {
+    /** Stable identifier; namespaces this server's tools and keys it in the fleet. */
+    readonly id: string;
+    /** Transport discriminant. */
+    readonly kind: "stdio";
+    /** The executable to launch (e.g. `npx`, `node`, an absolute binary path). */
+    readonly command: string;
+    /** Arguments passed to {@link command}, in order. */
+    readonly args?: readonly string[];
+    /** Extra environment variables for the spawned process. */
+    readonly env?: Readonly<Record<string, string>>;
+}
+/** A server reached over HTTP using Server-Sent Events for the inbound stream. */
+export interface SseServerConfig {
+    /** Stable identifier; namespaces this server's tools and keys it in the fleet. */
+    readonly id: string;
+    /** Transport discriminant. */
+    readonly kind: "sse";
+    /** The endpoint URL to connect to. */
+    readonly url: string;
+    /** Extra HTTP headers sent with the connection (e.g. authorization). */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/**
+ * One server's connection description, discriminated by its transport `kind`.
+ *
+ * Branch on `kind` to recover the transport-specific fields; the two variants
+ * share only `id` and `kind`.
+ */
+export type ServerConfig = StdioServerConfig | SseServerConfig;
+/** The transport kinds a {@link ServerConfig} may declare. */
+export type TransportKind = ServerConfig["kind"];
+/** The set of servers the bridge should connect on start-up. */
+export interface BridgeConfig {
+    /** The configured servers, in declaration order. */
+    readonly servers: readonly ServerConfig[];
+}
+/**
+ * A fully-qualified reference to one tool on one server.
+ *
+ * Remote tool names are only unique *within* a server, so a reference pairs the
+ * owning server's {@link ServerConfig.id} with the tool's own name. The bridge
+ * derives the agent-facing, collision-free name from this pair (see
+ * {@link RemoteToolRef.qualifiedName} consumers and {@link QUALIFIER}).
+ */
+export interface RemoteToolRef {
+    /** The id of the {@link ServerConfig} that owns the tool. */
+    readonly server: string;
+    /** The tool's name as the server advertises it, unqualified. */
+    readonly name: string;
+}
+/**
+ * The delimiter joining a server id and a remote tool name into the single,
+ * collision-free name advertised to the model. A double underscore keeps the
+ * qualified name a legal identifier across providers.
+ */
+export declare const QUALIFIER: "__";
+/** Build the agent-facing qualified name for a {@link RemoteToolRef}. */
+export declare function qualifyToolName(ref: RemoteToolRef): string;
+/**
+ * A remote tool as the bridge sees it: the descriptor advertised to the model,
+ * paired with the {@link RemoteToolRef} the endpoint needs to route an
+ * invocation back to the right server and tool.
+ */
+export interface RemoteTool {
+    /** Where this tool lives. */
+    readonly ref: RemoteToolRef;
+    /** The model-facing descriptor (qualified name, description, parameters). */
+    readonly descriptor: ToolDescriptor;
+}
+/**
+ * A point-in-time projection of a single endpoint's health.
+ *
+ * Pure data — a snapshot the fleet aggregates and a host can render — carrying
+ * the endpoint's current {@link EndpointPhase}, the count of tools it exposes,
+ * and the fault that retired it, when one did.
+ */
+export interface EndpointStatus {
+    /** The server this status describes. */
+    readonly server: string;
+    /** The endpoint's current lifecycle phase. */
+    readonly phase: EndpointPhase;
+    /** How many tools the endpoint currently exposes. */
+    readonly toolCount: number;
+    /** The fault that moved the endpoint to `faulted`, if it is faulted. */
+    readonly fault?: ProtocolFault;
+}
+/**
+ * The fleet's aggregate health: one {@link EndpointStatus} per configured
+ * server, keyed by {@link ServerConfig.id}.
+ */
+export type FleetStatus = Readonly<Record<string, EndpointStatus>>;
+/**
+ * The outcome of mounting the bridge.
+ *
+ * The mount routine connects every configured server, grafts the surviving
+ * remote tools into the host's registry, and returns the running fleet together
+ * with the {@link ToolBox} the agent will run against and the count of tools
+ * actually grafted.
+ */
+export interface MountedBridge {
+    /** The running fleet of endpoints. */
+    readonly fleet: ServerFleet;
+    /** The tool box exposing every grafted remote tool to the agent. */
+    readonly toolBox: ToolBox;
+    /** The number of remote tools successfully grafted. */
+    readonly toolCount: number;
+}
+/**
+ * A live connection to one external MCP server.
+ *
+ * An endpoint owns a single
+ * transport, advances through the {@link EndpointPhase} machine, and exposes the
+ * two operations the bridge needs: enumerate the server's tools and invoke one.
+ * Every failure surfaces as a {@link ProtocolFault}.
+ */
+export interface ServerEndpoint {
+    /** The configuration that defines this endpoint. */
+    readonly config: ServerConfig;
+    /** The endpoint's current lifecycle phase. */
+    readonly phase: EndpointPhase;
+    /** Open the transport and initialize the session. Idempotent while connecting. */
+    open(): Promise<void>;
+    /** List the tools this server currently advertises. */
+    listTools(): Promise<readonly RemoteTool[]>;
+    /** Invoke a remote tool by name with the given arguments. */
+    invoke(name: string, args: unknown): Promise<RemoteCallResult>;
+    /** A point-in-time projection of this endpoint's health. */
+    status(): EndpointStatus;
+    /** Gracefully close the transport. */
+    close(): Promise<void>;
+}
+/**
+ * The raw result of one remote tool invocation, before it is projected onto the
+ * runtime's {@link import("../../runtime/contract").ToolOutcome}.
+ *
+ * `content` is the ordered set of MCP content blocks the server returned;
+ * `isError`, when true, marks the result a {@link FaultKind} `tool_error`
+ * the model should be told about.
+ */
+export interface RemoteCallResult {
+    /** The content blocks returned by the remote tool, opaque to this contract. */
+    readonly content: readonly unknown[];
+    /** True when the remote tool reported its own failure. */
+    readonly isError: boolean;
+}
+/**
+ * A name-keyed collection of {@link ServerEndpoint}s with a unified lifecycle.
+ *
+ * The fleet connects and
+ * tears down every endpoint, isolates per-server failures so one bad server does
+ * not sink the rest, and projects an aggregate {@link FleetStatus}.
+ */
+export interface ServerFleet {
+    /** Connect every configured endpoint, isolating per-server failures. */
+    spinUp(): Promise<void>;
+    /** Gracefully close every endpoint. */
+    tearDown(): Promise<void>;
+    /** Look up a single endpoint by its server id. */
+    endpoint(server: string): ServerEndpoint | undefined;
+    /** Every endpoint currently held, in configuration order. */
+    endpoints(): readonly ServerEndpoint[];
+    /** The aggregate health of every endpoint. */
+    status(): FleetStatus;
+}