@kodax-ai/kodax 0.7.46 → 0.7.48

package/dist/types-chunks/manager.d-DLmDhX3i.d.ts

@@ -0,0 +1,696 @@
+import { a as McpServerConfig, b as McpServersConfig, M as McpConnectMode } from './config.d-CJy1WENT.js';
+import { a as CapabilityProvider, C as CapabilityKind, b as CapabilityResult } from './capability.d-3C62G8Eq.js';
+
+type McpCapabilityKind = 'tool' | 'resource' | 'prompt';
+type McpCapabilityRisk = 'read' | 'write' | 'network' | 'exec';
+/** Per-tool task-augmentation support (2025-11-25 `execution.taskSupport`). */
+type McpToolTaskSupport = 'forbidden' | 'optional' | 'required';
+/** Icon metadata (2025-11-25) attached to tools / resources / prompts. */
+interface McpIcon {
+    src: string;
+    mimeType?: string;
+    sizes?: string[];
+    theme?: 'light' | 'dark';
+}
+interface McpCatalogItem {
+    id: string;
+    serverId: string;
+    kind: McpCapabilityKind;
+    name: string;
+    title?: string;
+    summary: string;
+    tags?: string[];
+    risk?: McpCapabilityRisk;
+    annotations?: Record<string, unknown>;
+    cachedAt: string;
+}
+interface McpCapabilityDescriptor extends McpCatalogItem {
+    inputSchema?: unknown;
+    outputSchema?: unknown;
+    promptArgsSchema?: unknown;
+    uri?: string;
+    mimeType?: string;
+    /** Sanitized icon metadata (unsafe-scheme icons dropped). */
+    icons?: McpIcon[];
+    /** Tool only — `execution.taskSupport`. Absent is treated as 'forbidden'. */
+    taskSupport?: McpToolTaskSupport;
+}
+interface McpServerCatalogSnapshot {
+    serverId: string;
+    items: McpCatalogItem[];
+    descriptors: McpCapabilityDescriptor[];
+    updatedAt: string;
+}
+interface McpCatalogSearchOptions {
+    kind?: McpCapabilityKind;
+    limit?: number;
+}
+declare function defaultMcpCacheDir(): string;
+declare function createMcpCapabilityId(serverId: string, kind: McpCapabilityKind, name: string): string;
+declare function parseMcpCapabilityId(id: string): {
+    serverId: string;
+    kind: McpCapabilityKind;
+    name: string;
+};
+declare function searchMcpCatalog(items: readonly McpCatalogItem[], query: string, options?: McpCatalogSearchOptions): McpCatalogItem[];
+declare function getMcpCachePaths(cacheDir: string, serverId: string): {
+    catalogDir: string;
+    indexPath: string;
+    itemsPath: string;
+};
+
+/**
+ * FEATURE_222 — MCP 2025-11-25 reverse capabilities (server→client).
+ *
+ * KodaX's MCP client historically advertised `capabilities: {}` and answered
+ * every server→client request with `-32601`. This module is the host-injected
+ * seam that lets the client actually serve the reverse capabilities — roots,
+ * elicitation, sampling (and, later, tasks).
+ *
+ * Core principle (spec MUST: "both sides only use capabilities they
+ * negotiated"): a capability is advertised in `initialize.capabilities` ONLY
+ * when its handler is injected. An absent handler stays unadvertised, so a
+ * conformant server never sends the corresponding request. `buildInitialize-
+ * Capabilities` assembles that declaration from the handlers actually present,
+ * which is what makes the feature incrementally shippable, slice by slice.
+ */
+/** A workspace root exposed to a server. The spec requires a `file://` URI. */
+interface McpRoot {
+    readonly uri: string;
+    readonly name?: string;
+}
+/** A server-initiated elicitation request (form mode now; url mode in Slice C). */
+interface McpElicitRequest {
+    readonly mode: 'form' | 'url';
+    /** The MCP server making the request. The host MUST show this to the user so
+     *  they know who is asking (anti-phishing). Enriched by the runtime. */
+    readonly serverId?: string;
+    readonly message?: string;
+    /** form mode: a flat object of primitive properties to collect. */
+    readonly requestedSchema?: Record<string, unknown>;
+    /** url mode: the URL the user must be shown + asked to consent to. */
+    readonly url?: string;
+    /** url mode: correlation id echoed in `notifications/elicitation/complete`. */
+    readonly elicitationId?: string;
+}
+/** The three-state elicitation response defined by the spec. */
+type McpElicitResult = {
+    readonly action: 'accept';
+    readonly content: Record<string, unknown>;
+} | {
+    readonly action: 'decline';
+} | {
+    readonly action: 'cancel';
+};
+/** A server-initiated sampling request (`sampling/createMessage`). */
+interface McpSamplingRequest {
+    readonly messages: readonly unknown[];
+    readonly systemPrompt?: string;
+    readonly maxTokens?: number;
+    readonly modelPreferences?: Record<string, unknown>;
+    /** The server id asking — for the host's user-visible prompt + guardrails. */
+    readonly serverId: string;
+}
+/** A sampling response bridged back from the user's LLM. */
+interface McpSamplingResult {
+    readonly role: 'assistant';
+    readonly content: {
+        readonly type: 'text';
+        readonly text: string;
+    };
+    readonly model: string;
+    readonly stopReason?: string;
+}
+/**
+ * Host-injected reverse-capability handlers. Each present handler lights up its
+ * capability; an absent one stays unadvertised (server won't ask). Handlers are
+ * provided by the host (REPL / ACP / CLI) because only it owns the workspace,
+ * the user-interaction channel, and the LLM. A headless host injects nothing
+ * and the client behaves exactly as before (all reverse requests → -32601).
+ */
+interface McpReverseCapabilities {
+    /** Slice A — current workspace roots (a function so it reflects live state). */
+    readonly listRoots?: () => readonly McpRoot[] | Promise<readonly McpRoot[]>;
+    /** Whether to advertise `roots.listChanged` (default false). */
+    readonly rootsListChanged?: boolean;
+    /**
+     * Slice B/C — ask the user (form or url elicitation). For `mode:'url'` the
+     * host MUST show the full URL + its domain, require explicit consent, and
+     * MUST NOT auto-open the browser or expose the URL/contents to the model
+     * (anti-phishing). It resolves `accept` when the user consents to open the
+     * URL; the server later signals completion via {@link onElicitationComplete}.
+     */
+    readonly elicit?: (request: McpElicitRequest) => Promise<McpElicitResult>;
+    /** Which elicitation modes the injected `elicit` actually supports. Defaults
+     *  to form-only (url is gated on the anti-phishing handler from Slice C). */
+    readonly elicitationModes?: {
+        readonly form?: boolean;
+        readonly url?: boolean;
+    };
+    /**
+     * Slice C — the server finished a url elicitation (the user completed the
+     * external flow in their browser); the host can dismiss its waiting state.
+     * Correlated by the `elicitationId` from the original url request.
+     */
+    readonly onElicitationComplete?: (elicitationId: string) => void;
+    /** Slice D — run a sampling request via the user's LLM. Security-sensitive:
+     *  the host injects this ONLY when the user opted in, and applies guardrails. */
+    readonly sample?: (request: McpSamplingRequest) => Promise<McpSamplingResult>;
+}
+/**
+ * Build the `initialize.capabilities` object from the injected handlers —
+ * advertise only what we can actually handle.
+ */
+declare function buildInitializeCapabilities(reverse: McpReverseCapabilities | undefined): Record<string, unknown>;
+
+interface McpServerRuntimeDiagnostics {
+    serverId: string;
+    connect: 'lazy' | 'prewarm' | 'disabled';
+    status: 'idle' | 'connecting' | 'ready' | 'error' | 'disabled';
+    resolvedTransport?: string;
+    dirty: boolean;
+    lastError?: string;
+    cachedAt?: string;
+    tools: number;
+    resources: number;
+    prompts: number;
+}
+declare class McpServerRuntime {
+    private readonly serverId;
+    private readonly config;
+    private readonly cacheDir;
+    /** FEATURE_222 — host-injected server→client reverse capabilities. */
+    private readonly reverse?;
+    private transport?;
+    private readonly pending;
+    /** FEATURE_222 — resolvers awaiting notifications/elicitation/complete, keyed
+     *  by elicitationId (used by the url-elicitation tool-retry closure). */
+    private readonly elicitationWaiters;
+    /** Completion notifications that arrived before the host finished consent. */
+    private readonly completedElicitations;
+    private nextRequestId;
+    private initialized;
+    private connectPromise?;
+    private catalog?;
+    private serverCapabilities?;
+    private cachedHttpTransport?;
+    private diagnostics;
+    constructor(serverId: string, config: McpServerConfig, cacheDir: string, 
+    /** FEATURE_222 — host-injected server→client reverse capabilities. */
+    reverse?: McpReverseCapabilities | undefined);
+    getDiagnostics(): McpServerRuntimeDiagnostics;
+    prewarmIfNeeded(): Promise<void>;
+    /** Load catalog from memory or disk only — never triggers a lazy connection. */
+    getCachedCatalog(): Promise<McpServerCatalogSnapshot | undefined>;
+    getCatalog(forceRefresh?: boolean): Promise<McpServerCatalogSnapshot>;
+    describeCapability(capabilityId: string): Promise<McpCapabilityDescriptor | undefined>;
+    callTool(name: string, args: Record<string, unknown>): Promise<{
+        content?: string;
+        structuredContent?: unknown;
+        metadata?: Record<string, unknown>;
+    }>;
+    /**
+     * Drive a url elicitation the server asked for before a tools/call can
+     * succeed: route it to the host (anti-phishing consent UI) and, on consent,
+     * wait for the server's completion notification. Returns false when the host
+     * cannot serve url elicitation or the user did not consent.
+     */
+    private satisfyUrlElicitation;
+    /** Resolve when the server signals the url elicitation completed, or on timeout
+     *  (a premature retry is harmless — the server re-requests and the loop caps). */
+    private waitForElicitationComplete;
+    readResource(name: string, options: Record<string, unknown>): Promise<{
+        content?: string;
+        structuredContent?: unknown;
+        metadata?: Record<string, unknown>;
+    }>;
+    getPrompt(name: string, args: Record<string, unknown>): Promise<unknown>;
+    refreshCatalog(forceReconnect?: boolean): Promise<void>;
+    /** Public teardown — clears everything including the connect lock. */
+    dispose(): Promise<void>;
+    /** Internal transport teardown — does NOT clear connectPromise so the
+     *  retry loop inside doConnect() can safely call it between attempts. */
+    private resetTransport;
+    private connect;
+    private doConnect;
+    /** Initial Authorization header: a static-config token, or a cached token
+     *  from a prior discovery-based login. Absent → connect unauthenticated. */
+    private resolveInitialAuthHeaders;
+    private handshakeWithFramings;
+    /**
+     * FEATURE_222 — discover + interactively log in to an authenticated MCP
+     * server. The authorization URL is shown through the host's url-elicitation
+     * consent (anti-phishing; never auto-opened). Returns undefined when the host
+     * has no url-consent surface, discovery fails, or the user declines.
+     */
+    private runOAuthLogin;
+    private listDescriptors;
+    private request;
+    private sendRequest;
+    private notify;
+    private handleMessage;
+    /** Best-effort JSON-RPC response send (server times out on its own if closed). */
+    private sendResponse;
+    /** Best-effort JSON-RPC error send. */
+    private sendError;
+    /**
+     * FEATURE_222 — handle a server→client request for an advertised reverse
+     * capability. Each slice adds a case to {@link dispatchServerRequest};
+     * anything unhandled replies -32601, and a handler that throws replies
+     * -32603 so the server never hangs.
+     */
+    private handleServerRequest;
+    /**
+     * Route a reverse request to its handler, or return the sentinel when the
+     * method is not an advertised capability. Slices add cases here.
+     */
+    private dispatchServerRequest;
+    private failPending;
+    private applyCatalogSnapshot;
+}
+
+/**
+ * `McpCapabilityProvider` — implements the Layer A `CapabilityProvider`
+ * contract for an MCP server fleet.
+ *
+ * FEATURE_082 (v0.7.24): moved from
+ * `@kodax-ai/coding/src/capabilities/providers/mcp/provider.ts` to this package.
+ * The coding-specific `registerConfiguredMcpCapabilityProvider` adapter (which
+ * pulls in `KodaXExtensionRuntime`) lives in
+ * `@kodax-ai/coding/src/capabilities/providers/mcp-adapter.ts`.
+ */
+
+interface McpProviderOptions {
+    cacheDir?: string;
+    /**
+     * FEATURE_222 — host-injected server→client reverse capabilities (workspace
+     * roots / elicitation / sampling), applied to every server in this provider.
+     * Omitted in headless hosts, in which case reverse requests reply -32601.
+     */
+    reverse?: McpReverseCapabilities;
+}
+declare class McpCapabilityProvider implements CapabilityProvider {
+    readonly id = "mcp";
+    readonly kinds: CapabilityProvider['kinds'];
+    private readonly runtimes;
+    private readonly cacheDir;
+    /**
+     * Construct an MCP capability provider.
+     *
+     * **Cache-dir capture warning (v0.7.35.1 FEATURE_145)** — when
+     * `options.cacheDir` is omitted, this constructor resolves
+     * `defaultMcpCacheDir()` ONCE at instantiation time and threads the
+     * result into every `McpServerRuntime` it spawns. If a substrate
+     * consumer plans to redirect the agent config home via
+     * `setAgentConfigHome()` from `@kodax-ai/agent`, that call MUST happen
+     * BEFORE constructing this provider. Late calls have no effect on
+     * already-constructed runtimes.
+     *
+     * To bypass the agent-home resolver entirely, pass
+     * `options.cacheDir` explicitly — that path wins unconditionally.
+     */
+    constructor(servers: McpServersConfig | undefined, options?: McpProviderOptions);
+    hasActiveServers(): boolean;
+    /**
+     * v0.7.42 — read-only accessor for the enabled server id list.
+     * Used by {@link McpManager} to drive popout-shape `listServers /
+     * startServer / stopServer / logs / tools` operations without
+     * exposing the internal runtimes Map.
+     */
+    getServerIds(): readonly string[];
+    /**
+     * v0.7.42 — single-server runtime accessor. Returns `undefined`
+     * for unknown / disabled servers. Use {@link McpManager} for
+     * higher-level lifecycle control.
+     */
+    getRuntime(serverId: string): McpServerRuntime | undefined;
+    prewarm(): Promise<void>;
+    search(query: string, options?: {
+        kind?: CapabilityKind;
+        limit?: number;
+        server?: string;
+    }): Promise<unknown[]>;
+    describe(id: string): Promise<unknown>;
+    execute(id: string, input: Record<string, unknown>): Promise<CapabilityResult>;
+    read(id: string, options?: Record<string, unknown>): Promise<CapabilityResult>;
+    getPrompt(id: string, args?: Record<string, unknown>): Promise<unknown>;
+    getPromptContext(): Promise<string | undefined>;
+    getDiagnostics(): Record<string, unknown> | undefined;
+    refresh(): Promise<void>;
+    dispose(): Promise<void>;
+    private collectCatalogItems;
+    private listServerDiagnostics;
+    private requireRuntime;
+}
+
+interface McpTransportEvents {
+    /** Called with a complete JSON-RPC message (raw JSON string). */
+    onMessage(raw: string): void;
+    onError(error: Error): void;
+    onClose(reason: string): void;
+}
+interface McpTransport {
+    open(events: McpTransportEvents): Promise<void>;
+    /** Send a JSON string. The transport handles framing. */
+    send(json: string): Promise<void>;
+    setProtocolVersion?(version: string | undefined): void;
+    close(): Promise<void>;
+    readonly connected: boolean;
+    /** Effective transport after auto-detection (diagnostics only). */
+    readonly resolvedTransport?: string;
+}
+declare class McpExpiredSessionError extends Error {
+    constructor();
+}
+/**
+ * FEATURE_222 — the server demanded OAuth (401) or a stronger scope (403). It
+ * carries the `WWW-Authenticate` header so the connect flow can discover the
+ * authorization server (RFC 9728 pointer) or read the step-up scope.
+ */
+declare class McpAuthRequiredError extends Error {
+    readonly status: number;
+    readonly wwwAuthenticate?: string | undefined;
+    constructor(status: number, wwwAuthenticate?: string | undefined);
+}
+type StdioFraming = 'content-length' | 'ndjson';
+interface McpTransportOptions {
+    stdioFraming?: StdioFraming;
+    httpResolvedTransport?: 'streamable-http' | 'sse';
+}
+declare function createMcpTransport(config: McpServerConfig, options?: McpTransportOptions): McpTransport;
+
+/**
+ * FEATURE_222 — MCP OAuth discovery (server→authorization-server resolution).
+ *
+ * The modern MCP auth flow does NOT require the user to hand-configure
+ * authorization/token endpoints. Instead the client discovers them at runtime:
+ *
+ *   401 WWW-Authenticate (resource_metadata=...)         [RFC 9728 pointer]
+ *     → GET /.well-known/oauth-protected-resource        [RFC 9728 PRM]
+ *       → authorization_servers[0]
+ *         → GET /.well-known/oauth-authorization-server  [RFC 8414]
+ *            (fallback /.well-known/openid-configuration) [OIDC]
+ *           → authorization_endpoint / token_endpoint / registration_endpoint
+ *
+ * This module is the pure-HTTP discovery layer (no PKCE, no browser, no token
+ * storage — those compose on top). The path-aware fallback ordering mirrors
+ * Claude Code's MCP client so KodaX resolves the same servers it does.
+ */
+interface WwwAuthenticateChallenge {
+    readonly scheme: string;
+    readonly params: Record<string, string>;
+}
+/** The RFC 9728 `resource_metadata` URL a 401 challenge points at, if any. */
+declare function extractResourceMetadataUrl(header: string | undefined): string | undefined;
+/**
+ * For a 403 `error="insufficient_scope"` challenge, the `scope` the server now
+ * requires (space-separated). Undefined when the challenge is not a step-up.
+ */
+declare function extractInsufficientScope(header: string | undefined): string | undefined;
+interface ProtectedResourceMetadata {
+    readonly authorizationServers: string[];
+    readonly resource?: string;
+    readonly scopesSupported?: string[];
+}
+/**
+ * Discover the protected-resource metadata for an MCP server URL. Prefers the
+ * `resource_metadata` URL from the 401 challenge; otherwise probes the
+ * path-specific then root `/.well-known/oauth-protected-resource`.
+ */
+declare function discoverProtectedResourceMetadata(options: {
+    serverUrl: string;
+    resourceMetadataUrl?: string;
+    fetchFn?: typeof fetch;
+}): Promise<ProtectedResourceMetadata | undefined>;
+interface AuthorizationServerMetadata {
+    readonly issuer?: string;
+    readonly authorizationEndpoint: string;
+    readonly tokenEndpoint: string;
+    readonly registrationEndpoint?: string;
+    readonly scopesSupported?: string[];
+    readonly codeChallengeMethodsSupported?: string[];
+}
+/** Discover an authorization server's endpoints. The first candidate returning
+ *  both an authorization + token endpoint wins. */
+declare function discoverAuthorizationServerMetadata(options: {
+    authorizationServerUrl: string;
+    fetchFn?: typeof fetch;
+}): Promise<AuthorizationServerMetadata | undefined>;
+/**
+ * End-to-end endpoint discovery: PRM → first authorization server → AS metadata.
+ * Returns the resolved endpoints plus the resource indicator (RFC 8707) and the
+ * scopes the resource advertises. Undefined when discovery fails at any step.
+ */
+interface DiscoveredOAuthEndpoints extends AuthorizationServerMetadata {
+    /** RFC 8707 resource indicator (the MCP server's canonical URL). */
+    readonly resource?: string;
+    /** Scopes from the protected-resource document, when the AS omits them. */
+    readonly resourceScopesSupported?: string[];
+}
+declare function discoverOAuthEndpoints(options: {
+    serverUrl: string;
+    resourceMetadataUrl?: string;
+    fetchFn?: typeof fetch;
+}): Promise<DiscoveredOAuthEndpoints | undefined>;
+
+interface OAuthToken {
+    readonly accessToken: string;
+    readonly refreshToken?: string;
+    readonly expiresAt?: number;
+    readonly tokenType?: string;
+    readonly scope?: string;
+}
+
+/** A dynamically-registered (or pre-configured) OAuth client. */
+interface OAuthClientInfo {
+    readonly clientId: string;
+    readonly clientSecret?: string;
+}
+/**
+ * RFC 7591 Dynamic Client Registration. Registers a public client (PKCE, no
+ * secret) for the loopback redirect and returns the issued client_id.
+ */
+declare function registerOAuthClient(options: {
+    registrationEndpoint: string;
+    redirectUri: string;
+    clientName: string;
+    scope?: string;
+    fetchFn?: typeof fetch;
+}): Promise<OAuthClientInfo>;
+/**
+ * The host's consent gate for a login. Receives the authorization URL and must
+ * return true to proceed (the user will open it in their browser). Returning
+ * false aborts the login. KodaX never auto-opens the URL.
+ */
+type OAuthLoginConsent = (authorizationUrl: string) => Promise<boolean>;
+interface PerformOAuthLoginOptions {
+    serverId: string;
+    /** The MCP server URL (resource) we are authenticating to. */
+    serverUrl: string;
+    /** resource_metadata URL from a 401 challenge, if one was seen. */
+    resourceMetadataUrl?: string;
+    /** A pre-configured client_id (skips dynamic registration). */
+    configuredClientId?: string;
+    /** Pre-configured scopes (override discovery). */
+    configuredScopes?: readonly string[];
+    /** For an insufficient_scope step-up: the elevated scope to request. */
+    stepUpScope?: string;
+    /** Host consent gate (anti-phishing) — receives the authorization URL. */
+    consent: OAuthLoginConsent;
+    /** Loopback callback port (defaults to {@link DEFAULT_OAUTH_REDIRECT_PORT}). */
+    redirectPort?: number;
+    fetchFn?: typeof fetch;
+}
+/**
+ * Run the full interactive login and persist the resulting token. Returns the
+ * token, or undefined when discovery fails, no client can be obtained, or the
+ * user declines consent. Throws only on a hard protocol error (bad exchange).
+ */
+declare function performOAuthLogin(options: PerformOAuthLoginOptions): Promise<OAuthToken | undefined>;
+/**
+ * Return a still-valid cached token for a server, or undefined. (Discovery-based
+ * refresh on expiry is driven by the connect flow, which knows the endpoints.)
+ */
+declare function loadValidToken(serverId: string): Promise<OAuthToken | undefined>;
+
+/**
+ * McpManager — v0.7.42 (extends FEATURE_186 MCP popout surface).
+ *
+ * `McpCapabilityProvider` (`./provider.ts`) is the capability-provider-
+ * shaped object KodaX uses internally to plug MCP into the agent runtime
+ * — its public methods are `search` / `describe` / `execute` / `read` /
+ * `getPrompt` / `getDiagnostics` / `refresh` / `dispose`, which is the
+ * shape the substrate consumes but NOT the shape a popout UI wants.
+ *
+ * KodaX Space reported that `@kodax-ai/kodax/mcp` only exposed "types +
+ * helpers, no manager-shape API" — concretely they wanted a thin
+ * `listServers / startServer / stopServer / getServerLogs / listTools`
+ * surface to drive a popout panel:
+ *
+ *   - One row per configured MCP server with live status
+ *   - "Start" / "Stop" buttons that map to refreshCatalog(true) / dispose
+ *   - Server logs (last error + status) so users can debug failures
+ *   - Per-server tool list (filtered descriptors) for the "what does
+ *     this MCP server expose" pane
+ *
+ * `McpManager` is the thin wrapper. It owns one `McpCapabilityProvider`
+ * instance internally, so all the existing lifecycle invariants
+ * (cache-dir capture, refresh, dispose, server-config validation) are
+ * preserved verbatim. The capability-provider-shaped methods stay
+ * available via `manager.provider()` as an escape hatch.
+ *
+ * Trust boundary: same as the rest of FEATURE_186 — KodaX is a
+ * single-user CLI, last-write-wins on the server-config-vs-active-
+ * runtime path; a Space popout that swaps configs hot would still need
+ * to construct a fresh `McpManager` (or call `dispose()` then
+ * `createMcpManager` again) to pick up the new wire.
+ */
+
+interface McpServerStatus {
+    readonly serverId: string;
+    readonly config: McpServerConfig;
+    readonly connect: McpConnectMode;
+    readonly status: McpServerRuntimeDiagnostics['status'];
+    readonly resolvedTransport?: string;
+    readonly tools: number;
+    readonly resources: number;
+    readonly prompts: number;
+    readonly dirty: boolean;
+    readonly cachedAt?: string;
+    readonly lastError?: string;
+}
+interface McpServerLogs {
+    readonly serverId: string;
+    readonly status: McpServerRuntimeDiagnostics['status'];
+    readonly connect: McpConnectMode;
+    readonly resolvedTransport?: string;
+    readonly lastError?: string;
+    readonly cachedAt?: string;
+}
+interface McpServerToolList {
+    readonly serverId: string;
+    readonly tools: readonly McpCapabilityDescriptor[];
+    readonly cachedAt?: string;
+}
+/**
+ * Full catalog snapshot for a server — tools + resources + prompts.
+ * Use {@link McpManager.getCatalog} when the popout needs to render
+ * all three capability kinds (not just tools).
+ *
+ * `cachedAt` matches the naming used by {@link McpServerStatus},
+ * {@link McpServerLogs}, and {@link McpServerToolList} for consistency
+ * across the manager surface (all are renames of the underlying
+ * `McpServerCatalogSnapshot.updatedAt` field).
+ */
+interface McpServerCatalog {
+    readonly serverId: string;
+    readonly items: readonly McpCatalogItem[];
+    readonly descriptors: readonly McpCapabilityDescriptor[];
+    readonly cachedAt: string;
+}
+/**
+ * Manager-shape facade over {@link McpCapabilityProvider}. Construct
+ * via the {@link createMcpManager} factory or `new McpManager(...)`
+ * directly.
+ */
+declare class McpManager {
+    private readonly capabilityProvider;
+    private readonly serversConfig;
+    constructor(servers: McpServersConfig | undefined, options?: McpProviderOptions);
+    /**
+     * Escape hatch — returns the underlying {@link McpCapabilityProvider}
+     * for callers that need the search / describe / execute / read /
+     * getPrompt API (e.g. embedding into a custom agent runtime).
+     */
+    provider(): McpCapabilityProvider;
+    /**
+     * One status row per configured server (lazy / prewarm / disabled
+     * all included). Returned objects are plain readonly snapshots —
+     * mutating them does NOT affect runtime state.
+     */
+    listServers(): McpServerStatus[];
+    /**
+     * Force a connection + catalog refresh for `serverId`. Returns the
+     * post-start status row. Throws if `serverId` is not configured.
+     *
+     * For lazy servers, this is the explicit "connect now" trigger —
+     * useful when a popout user clicks "Start" before any tool call has
+     * forced the lazy connection.
+     */
+    startServer(serverId: string): Promise<McpServerStatus>;
+    /**
+     * Disconnect `serverId` — closes the transport, drops the pending
+     * request queue, but keeps the server in the config so a subsequent
+     * `startServer` / `listTools` can reconnect. Returns the post-stop
+     * status (`status: 'idle'`).
+     */
+    stopServer(serverId: string): Promise<McpServerStatus>;
+    /**
+     * Return the most recent runtime diagnostic envelope for `serverId`
+     * — status, last error, last cached timestamp. Designed as the data
+     * source for a popout "Logs" pane.
+     *
+     * Logs API is intentionally conservative in v0.7.42: only the last
+     * error message + status are exposed. A future iteration may add a
+     * ring buffer of recent events; the field shape will extend (add
+     * fields), never break (rename / remove).
+     */
+    getServerLogs(serverId: string): McpServerLogs;
+    /**
+     * Return the tool descriptors for `serverId`. Triggers a lazy
+     * connect + catalog fetch if the catalog has not yet been built;
+     * pass `{ forceRefresh: true }` to force a fresh catalog regardless
+     * of cache state.
+     *
+     * Only `kind === 'tool'` descriptors are returned (filters out
+     * resources + prompts so popout consumers can render a clean
+     * "tools" table). Use the underlying `provider().describe(id)` for
+     * full descriptor introspection including resources + prompts.
+     */
+    listTools(serverId: string, options?: {
+        forceRefresh?: boolean;
+    }): Promise<McpServerToolList>;
+    /**
+     * Return the full catalog snapshot for `serverId` — every tool,
+     * resource, and prompt the server exposes — plus lightweight catalog
+     * items for menu rendering. `listTools` is the tools-only fast path;
+     * use this when the popout needs to render resources / prompts panes
+     * alongside tools.
+     *
+     * Triggers a lazy connect + catalog fetch if the catalog has not yet
+     * been built; pass `{ forceRefresh: true }` to force a fresh catalog
+     * regardless of cache state.
+     */
+    getCatalog(serverId: string, options?: {
+        forceRefresh?: boolean;
+    }): Promise<McpServerCatalog>;
+    /**
+     * Dispose all runtimes. After calling, the manager is no longer
+     * usable for `startServer` / `listTools` (they would reconnect, but
+     * the consumer should construct a fresh manager instead).
+     */
+    dispose(): Promise<void>;
+    /** v0.7.42 — escape hatch for advanced uses; usually consumers use the typed methods above. */
+    search(query: string, options?: {
+        kind?: CapabilityKind;
+        limit?: number;
+        server?: string;
+    }): Promise<readonly McpCatalogItem[]>;
+    /** v0.7.42 — escape hatch for advanced uses; usually consumers use {@link listTools}. */
+    describe(id: string): Promise<McpCapabilityDescriptor | undefined>;
+    /** v0.7.42 — invoke a tool by capability id (`mcp://<serverId>/<kind>/<name>`). */
+    execute(id: string, input: Record<string, unknown>): Promise<CapabilityResult>;
+    /** v0.7.42 — read a resource by capability id. */
+    read(id: string, options?: Record<string, unknown>): Promise<CapabilityResult>;
+    private requireRuntime;
+    private buildStatus;
+}
+/**
+ * Convenience factory matching the rest of the FEATURE_186 surface
+ * naming (`createSessionControl`, etc.). Equivalent to
+ * `new McpManager(servers, options)`.
+ */
+declare function createMcpManager(servers: McpServersConfig | undefined, options?: McpProviderOptions): McpManager;
+
+export { buildInitializeCapabilities as C, createMcpCapabilityId as E, createMcpManager as F, createMcpTransport as G, defaultMcpCacheDir as H, discoverAuthorizationServerMetadata as I, discoverOAuthEndpoints as J, discoverProtectedResourceMetadata as K, extractInsufficientScope as L, McpAuthRequiredError as M, extractResourceMetadataUrl as N, getMcpCachePaths as Q, loadValidToken as R, parseMcpCapabilityId as S, performOAuthLogin as T, registerOAuthClient as U, searchMcpCatalog as V, McpCapabilityProvider as c, McpExpiredSessionError as h, McpManager as j, McpServerRuntime as s };
+export type { AuthorizationServerMetadata as A, ProtectedResourceMetadata as B, DiscoveredOAuthEndpoints as D, OAuthClientInfo as O, PerformOAuthLoginOptions as P, WwwAuthenticateChallenge as W, McpCapabilityDescriptor as a, McpCapabilityKind as b, McpCapabilityRisk as d, McpCatalogItem as e, McpElicitRequest as f, McpElicitResult as g, McpIcon as i, McpProviderOptions as k, McpReverseCapabilities as l, McpRoot as m, McpSamplingRequest as n, McpSamplingResult as o, McpServerCatalog as p, McpServerCatalogSnapshot as q, McpServerLogs as r, McpServerRuntimeDiagnostics as t, McpServerStatus as u, McpServerToolList as v, McpToolTaskSupport as w, McpTransport as x, McpTransportEvents as y, OAuthLoginConsent as z };