@nylorun/runtime 0.19.1-beta → 0.21.0-beta

package/dist/mcp/connect.d.ts

@@ -2,7 +2,9 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import type { McpServerManifest } from "@nylorun/core/define";
 import { type OutboundPolicy } from "../tenant/outbound.js";
 import type { AuthorizeResult } from "../vault/service.js";
-import { type McpDiagnostic, type McpToolRecord } from "./snapshot.js";
+import { type McpDiagnostic, type McpRenamedTool, type McpToolRecord } from "./snapshot.js";
+/** How much of a failed answer's body the model sees. */
+export declare const MCP_ERROR_BODY_CHARS = 2000;
 /** Options of one MCP request. */
 export interface McpRequestOptions {
     readonly signal?: AbortSignal;
@@ -22,9 +24,19 @@ export interface McpToolPage {
         readonly description?: string;
         readonly inputSchema?: unknown;
         readonly outputSchema?: unknown;
+        readonly annotations?: Readonly<Record<string, unknown>>;
     }[];
     readonly nextCursor?: string;
 }
+/**
+ * A `tools/call` answer: the raw `CallToolResult`, with each credential value sent for the call
+ * that it echoes replaced by `[redacted]` (R2b C8).
+ */
+export interface McpCallAnswer {
+    readonly result: Record<string, unknown>;
+    /** How many values were replaced; absent when none. */
+    readonly redacted?: number;
+}
 /**
  * What the pool needs of an MCP client: the SDK `Client` over a transport of this process
  * (`sdkClient`), or a client of the gates service that holds the real connection
@@ -34,18 +46,127 @@ export interface McpClient {
     listTools(params?: {
         cursor?: string;
     }, options?: McpRequestOptions): Promise<McpToolPage>;
-    /** The raw `CallToolResult`; `callMcpTool` reads it. */
+    /**
+     * One `tools/call`; `callMcpTool` reads its answer. A call that failed at the transport or
+     * the server rejects with `McpCallFailed`; any other rejection leaves its fate unknown.
+     */
     callTool(params: {
         name: string;
         arguments: Record<string, unknown>;
-    }, options?: McpCallOptions): Promise<Record<string, unknown>>;
+    }, options?: McpCallOptions): Promise<McpCallAnswer>;
 }
 export interface LiveConnection {
     readonly client: McpClient;
+    /** The server's instructions from `initialize`, cut (`serverInstructions`); absent when none. */
+    readonly instructions?: string;
+    /**
+     * The server's `serverInfo` from `initialize` (name, version, title), without a credential
+     * value sent; absent from a connection the gates service holds.
+     */
+    readonly serverInfo?: Readonly<Record<string, unknown>>;
     close(): Promise<void>;
 }
-/** An SDK `Client` as an `McpClient`. */
-export declare function sdkClient(client: Client): McpClient;
+/** What a failed tool call says to the model (`callMcpTool`). */
+export type McpToolFailure = {
+    readonly kind: "failed";
+    readonly code: string;
+    readonly message: string;
+    /** True when calling again may work (R2b C7). */
+    readonly retryable?: boolean;
+    /** With `credential_rejected`: the server, and the scope of the vault whose credential was sent. */
+    readonly server?: string;
+    readonly vault?: "installation" | "user";
+    /** How many credential values the message had in it, replaced (R2b C8). */
+    readonly redacted?: number;
+};
+/** What a tool call came to (`callMcpTool`). */
+export type McpToolOutcome = {
+    readonly kind: "completed";
+    readonly output: unknown;
+    readonly redacted?: number;
+} | McpToolFailure;
+/**
+ * How a tool call failed at the transport or the server (R2b C7), as the gate answers it:
+ * - `mcp.unreachable`: never sent (address policy, DNS, refused connection, TLS, a connection
+ *   that could not be opened). Calling again may work.
+ * - `credential_rejected`: the server answered `401` (C1).
+ * - `mcp.forbidden`: the server answered `403`.
+ * - `mcp.error`: the server answered a JSON-RPC error; the message has its code.
+ * - `mcp.status`: the server answered another HTTP error status, without a JSON-RPC error.
+ * - `mcp.lost`: sent, and the answer was lost, so the tool may have run. The model sees it only
+ *   for a tool the server marks read-only or idempotent (Q15); any other call is `uncertain`.
+ * - `mcp.too-large`: the answer passed `MCP_RESULT_MAX_BYTES` (R2b C11), as an HTTP tool's
+ *   answer is `http.too-large`. The tool ran; its answer was not kept.
+ */
+export type McpFailureCode = "mcp.unreachable" | "credential_rejected" | "mcp.forbidden" | "mcp.error" | "mcp.status" | "mcp.lost" | "mcp.too-large";
+/**
+ * The largest `tools/call` answer the gate holds (R2b C11): 8 MiB, an HTTP tool's cap. Core
+ * stores what does not fit a tool result as an artifact (`tenant/tool-results.ts`).
+ */
+export declare const MCP_RESULT_MAX_BYTES: number;
+export interface McpCallFailure {
+    readonly code: McpFailureCode;
+    readonly message: string;
+    /** The request reached the server, so it may have acted on it. */
+    readonly sent: boolean;
+    readonly retryable: boolean;
+    /** With `credential_rejected`: the server, and the scope of the vault whose credential was sent. */
+    readonly server?: string;
+    readonly vault?: "installation" | "user";
+    /** How many credential values the message had in it, replaced (R2b C8). */
+    readonly redacted?: number;
+}
+/** A tool call that failed with a code the model can act on (R2b C7). */
+export declare class McpCallFailed extends Error {
+    readonly failure: McpCallFailure;
+    constructor(failure: McpCallFailure);
+    get code(): McpFailureCode;
+    /** The failure the gate answered, as the class the loop's own call would have thrown. */
+    static from(failure: McpCallFailure): McpCallFailed;
+    /** The failed tool outcome the model sees. */
+    outcome(): McpToolFailure;
+}
+/**
+ * A request the server answered `401` (R2b C1): it rejected the vault's credential, or wanted one
+ * and got none. Never retried, since nothing the gate holds changes between tries (Q4). A tool
+ * call that meets it fails with `credential_rejected` for the model to see; at discovery it is the
+ * server's `failed` diagnostic.
+ */
+export declare class CredentialRejected extends McpCallFailed {
+    readonly server: string;
+    /** The scope of the vault whose credential was sent; absent when none was. */
+    readonly vault?: "installation" | "user" | undefined;
+    /**
+     * The answer's `WWW-Authenticate`, which may name the server's protected-resource metadata
+     * (RFC 9728 `resource_metadata`): a tool preview reads it (R2b C12). Never shown to the model.
+     */
+    readonly challenge?: string | undefined;
+    constructor(server: string, 
+    /** The scope of the vault whose credential was sent; absent when none was. */
+    vault?: "installation" | "user" | undefined, 
+    /**
+     * The answer's `WWW-Authenticate`, which may name the server's protected-resource metadata
+     * (RFC 9728 `resource_metadata`): a tool preview reads it (R2b C12). Never shown to the model.
+     */
+    challenge?: string | undefined);
+}
+/**
+ * A request its connection can no longer make, refused before it reached a tool: the server
+ * answered `404` to the connection's `Mcp-Session-Id` (the session is gone, MCP 2025-06-18
+ * "Session Management"), or the credential's `via` now sends the server's requests elsewhere.
+ * Whoever holds the connection drops it, opens it again and sends the call once more (R2b C7).
+ * When that fails too, it is `mcp.unreachable`: nothing ran.
+ */
+export declare class McpConnectionStale extends McpCallFailed {
+    constructor(server: string, reason: string);
+}
+/** A tool call that never reached its server: its connection could not be opened. */
+export declare function unreachable(server: string, error: unknown): McpCallFailed;
+/**
+ * An SDK `Client` as an `McpClient`. Its answers and failures carry no credential value sent
+ * with them (R2b C8), and a failed call is an `McpCallFailed` (C7).
+ */
+export declare function sdkClient(client: Client, serverName: string): McpClient;
 export declare function openMcpServer(input: {
     server: McpServerManifest;
     authorize: (url: string) => Promise<AuthorizeResult>;
@@ -55,22 +176,47 @@ export declare function openMcpServer(input: {
      * Host that refuses private addresses refuses them here too. Default: no limits.
      */
     policy?: OutboundPolicy;
+    /** Ends `initialize` (a tool preview's timeout, R2b C12). */
+    signal?: AbortSignal;
 }): Promise<LiveConnection>;
+/**
+ * What a server's `initialize` said to do with its tools, for the note on its deferred tools
+ * (R2b C10): cut to `SERVER_INSTRUCTIONS_MAX_CHARS`, without a credential value sent (C8).
+ */
+export declare function serverInstructions(text: unknown, secrets: readonly string[]): string | undefined;
+/**
+ * Lists a server's tools under the names the model knows them by (R2b C6): `server__tool` where
+ * that is a name every provider accepts, else `normalizeToolName`'s, listed in `renamed`. A name
+ * taken by a declared tool or an earlier server's tool omits the tool; a renamed tool that
+ * collides gets the hash suffix first.
+ */
 export declare function listMcpTools(client: McpClient, input: {
     capabilityId: string;
     serverName: string;
     taken: Set<string>;
     signal?: AbortSignal;
+    /**
+     * The server's declaration: a tool its `tools` settings disable is left out before it takes
+     * a name (R2b C9), and a key that names no listed tool is in `unknownTools`.
+     */
+    server?: McpServerManifest;
 }): Promise<{
     tools: McpToolRecord[];
     omitted: string[];
+    renamed: McpRenamedTool[];
+    disabled: number;
+    unknownTools: string[];
 }>;
-export declare function callMcpTool(client: McpClient, serverToolName: string, args: unknown, options?: McpCallOptions): Promise<{
-    kind: "completed";
-    output: unknown;
-} | {
-    kind: "failed";
-    code: string;
-    message: string;
-}>;
+/**
+ * One tool call and what it came to. Rejects with `McpConnectionStale` when the connection must
+ * be opened again (the caller retries once), and with any error that leaves the call's fate
+ * unknown.
+ */
+export declare function callMcpTool(client: McpClient, serverToolName: string, args: unknown, options?: McpCallOptions & {
+    /**
+     * The tool is read-only or idempotent (`McpToolRecord.annotations`): a call whose answer was
+     * lost after it was sent is `mcp.lost` to the model. Otherwise it is left uncertain (Q15).
+     */
+    readonly retrySafe?: boolean;
+}): Promise<McpToolOutcome>;
 export declare function diagnosticFromError(capabilityId: string, serverName: string, error: unknown): McpDiagnostic;