@nylorun/runtime 0.20.0-beta → 0.21.0-beta

package/dist/api/http/routes/vaults.js

@@ -1,25 +1,11 @@
 import { z } from "zod";
-import { CreateCredentialRequestSchema, CreateVaultRequestSchema, RotateCredentialRequestSchema, StartOAuthRequestSchema, } from "@nylorun/core/contracts";
-import { CreateCredentialRequest, CreateVaultRequest, CredentialInfo, DeletedResponse, ListCredentialsResponse, ListVaultsResponse, RotateCredentialRequest, StartOAuthRequest, StartOAuthResponse, VaultInfo, } from "../../components.js";
-import { HttpError } from "../../../tenant/http.js";
-import { VaultError } from "../../../vault/error.js";
+import { CreateCredentialRequestSchema, CreateVaultRequestSchema, RotateCredentialRequestSchema, } from "@nylorun/core/contracts";
+import { CreateCredentialRequest, CreateVaultRequest, CredentialInfo, DeletedResponse, ListCredentialsResponse, ListVaultsResponse, RotateCredentialRequest, VaultInfo, } from "../../components.js";
 import { readJson } from "../body.js";
 import { tenantRoute } from "../define.js";
 import { jsonResponse } from "../respond.js";
 /** The Management API's vault routes (`/v1/tenant/vaults`): a management key. */
 const MANAGEMENT = { credentials: ["management"], scopes: "never" };
-/**
- * The OAuth callback: a browser sent back by the authorization server, with no credential and no
- * protocol header. The `state` it carries is the grant.
- */
-const CALLBACK = {
-    credentials: ["application", "subject", "token"],
-    scopes: "any",
-    anonymous: true,
-    unversioned: true,
-};
-/** Where the authorization server sends the browser back. */
-export const OAUTH_CALLBACK_PATH = "/v1/oauth/callback";
 const json = (schema, description) => ({
     description,
     content: { "application/json": { schema } },
@@ -94,7 +80,7 @@ function vaultRoutesAt(api, base, access) {
         path: `${base}/{vaultId}/credentials`,
         tags: ["Vaults"],
         summary: "Add a credential",
-        description: "A bearer token or OAuth tokens, bound to the URLs a tool may send them to.",
+        description: "A bearer token, bound to the URL a tool may send it to.",
         request: { params: vaultId, body: body(CreateCredentialRequest) },
         responses: { 200: json(CredentialInfo, "The credential, without its secret") },
     }, async (c) => {
@@ -147,93 +133,7 @@ function vaultRoutesAt(api, base, access) {
     }, async (c) => {
         return jsonResponse(200, await c.env.tenant.vault.deleteCredential(c.req.param("vaultId"), c.req.param("credentialId")));
     });
-    tenantRoute(api, access, {
-        method: "post",
-        path: `${base}/{vaultId}/oauth/start`,
-        tags: ["Vaults"],
-        summary: "Start an MCP OAuth connect",
-        description: "Signs the installation in to the remote MCP server at `url` (declared as `server`) and stores its OAuth credential, bound to `url`, in this installation vault. The Runtime discovers the server's authorization server (RFC 9728, RFC 8414), registers itself (RFC 7591) unless `clientId` names a registered client, and answers the URL to open in a browser; the sign-in returns to `GET /v1/oauth/callback` within `expiresAt`. The callback URL is `NYLORUN_PUBLIC_URL` + `/v1/oauth/callback`, or this request's own origin when the Host has no public URL. Application keys acting for no one only. `oauth_client_required` when the server offers no registration and no `clientId` was given.",
-        request: { params: vaultId, body: body(StartOAuthRequest) },
-        responses: {
-            200: json(StartOAuthResponse, "Where to send the browser"),
-            502: {
-                description: "The authorization server, or its discovery, failed or refused (`oauth_failed`)",
-            },
-        },
-    }, async (c) => {
-        const request = StartOAuthRequestSchema.parse(await readJson(c.req.raw));
-        const tenant = c.env.tenant;
-        const base = tenant.config.publicUrl ?? new URL(c.req.url).origin;
-        return jsonResponse(200, await tenant.keys.startOAuth({
-            vaultId: c.req.param("vaultId"),
-            server: request.server,
-            url: request.url,
-            ...(request.clientId === undefined ? {} : { clientId: request.clientId }),
-            redirectUri: `${base}${OAUTH_CALLBACK_PATH}`,
-        }));
-    });
 }
 export function vaultRoutes(api) {
     vaultRoutesAt(api, "/v1/tenant/vaults", MANAGEMENT);
-    tenantRoute(api, CALLBACK, {
-        method: "get",
-        path: OAUTH_CALLBACK_PATH,
-        tags: ["Vaults"],
-        summary: "Finish an MCP OAuth connect",
-        description: "Where the authorization server sends the browser back with `code` and `state` (or `error`). Exchanges the code once and stores the credential; answers a small HTML page. Needs no credential and no `Nylorun-Protocol`. A `state` is used once, for ten minutes (`oauth_state_invalid`).",
-        request: {
-            query: z.object({
-                code: z.string().optional(),
-                state: z.string().optional(),
-                error: z.string().optional(),
-            }),
-        },
-        responses: {
-            200: { description: "Connected", content: { "text/html": { schema: z.string() } } },
-            502: { description: "The authorization server refused the code (`oauth_failed`)" },
-        },
-    }, async (c) => {
-        const state = c.req.query("state");
-        const code = c.req.query("code");
-        const error = c.req.query("error");
-        if (!state)
-            return page(400, "Sign-in failed", "The authorization server sent no state. Start the connect again.");
-        try {
-            await c.env.tenant.keys.finishOAuth({
-                state,
-                ...(code === undefined ? {} : { code }),
-                ...(error === undefined ? {} : { error }),
-            });
-        }
-        catch (failure) {
-            if (failure instanceof HttpError || failure instanceof VaultError)
-                return page(failure.status, "Sign-in failed", failure.message);
-            c.env.tenant.config.logger.error("oauth_callback_failed", {
-                error: failure instanceof Error ? failure.name : "unknown",
-            });
-            return page(500, "Sign-in failed", "The connect failed. Start it again.");
-        }
-        return page(200, "Connected", "Connected. You can close this tab.");
-    });
-}
-const ESCAPES = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
-const escape = (text) => text.replace(/[&<>"']/g, (char) => ESCAPES[char]);
-/** The callback's answer: a small page that loads nothing, is never cached and leaks no referrer. */
-function page(status, title, message) {
-    const html = `<!doctype html>
-<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
-<title>${escape(title)} · Nylorun</title>
-<style>body{font:16px/1.5 system-ui,sans-serif;max-width:32rem;margin:15vh auto;padding:0 1rem;color:#1a1a1a;background:#fff}@media (prefers-color-scheme:dark){body{color:#eee;background:#111}}h1{font-size:1.25rem}</style>
-</head><body><h1>${escape(title)}</h1><p>${escape(message)}</p></body></html>
-`;
-    return new Response(html, {
-        status,
-        headers: {
-            "content-type": "text/html; charset=utf-8",
-            "cache-control": "no-store",
-            "referrer-policy": "no-referrer",
-            "content-security-policy": "default-src 'none'; style-src 'unsafe-inline'",
-            "x-content-type-options": "nosniff",
-        },
-    });
 }

package/dist/api/openapi.js

@@ -236,7 +236,7 @@ const MANAGEMENT_TAGS = [
     },
     {
         name: "Vaults",
-        description: "The installation's credentials for agents' tools: API keys and MCP OAuth connections. Sessions attach a vault by id. `admin.vaults`.",
+        description: "The installation's and each person's credentials for agents' tools: API keys, bound to the URL they are sent to. Sessions attach a vault by id. `admin.vaults`.",
         operations: [
             "POST /v1/tenant/vaults",
             "GET /v1/tenant/vaults",
@@ -247,10 +247,13 @@ const MANAGEMENT_TAGS = [
             "GET /v1/tenant/vaults/{vaultId}/credentials/{credentialId}",
             "POST /v1/tenant/vaults/{vaultId}/credentials/{credentialId}",
             "DELETE /v1/tenant/vaults/{vaultId}/credentials/{credentialId}",
-            "POST /v1/tenant/vaults/{vaultId}/oauth/start",
-            "GET /v1/oauth/callback",
         ],
     },
+    {
+        name: "MCP servers",
+        description: "See a remote MCP server's tools before an agent names it, with the installation vault's credential for its URL: their model names, sizes and annotations, or that it needs a person's sign-in. `admin.mcp`.",
+        operations: ["POST /v1/tenant/mcp/preview"],
+    },
     {
         name: "Signing keys",
         description: "The keys the Runtime signs capability links and run tokens with; their public halves are the Runtime API's JWKS. `admin.signingKeys`.",

package/dist/artifacts/media-types.d.ts

@@ -11,3 +11,5 @@ export declare function contentTypeFor(name: string): string;
 export declare function isModelImage(contentType: string): boolean;
 /** Files the model reads as text: `text/*`, JSON, XML, YAML and their `+json`/`+xml` kin. */
 export declare function isText(contentType: string): boolean;
+/** The usual extension of a media type, for a name the Runtime gives a file; undefined if none. */
+export declare function extensionFor(contentType: string): string | undefined;

package/dist/artifacts/media-types.js

@@ -78,3 +78,8 @@ export function isText(contentType) {
         type.endsWith("+json") ||
         type.endsWith("+xml"));
 }
+/** The usual extension of a media type, for a name the Runtime gives a file; undefined if none. */
+export function extensionFor(contentType) {
+    const type = essence(contentType);
+    return Object.keys(BY_EXTENSION).find((extension) => BY_EXTENSION[extension] === type);
+}

package/dist/gates/http-tool.d.ts

@@ -11,10 +11,17 @@ export declare const HTTP_ERROR_BODY_CHARS = 2000;
 export type HttpOutcome = {
     readonly kind: "completed";
     readonly output: unknown;
+    /** How many credential values the answer echoed, replaced with `[redacted]` (R2b C8). */
+    readonly redacted?: number;
 } | {
     readonly kind: "failed";
     readonly code: string;
     readonly message: string;
+    /** With `credential_rejected`: the tool's `credential`, and the scope of its vault. */
+    readonly server?: string;
+    readonly vault?: "installation" | "user";
+    /** How many credential values the message had in it, replaced (R2b C8). */
+    readonly redacted?: number;
 };
 /**
  * One declared HTTP tool of a session: what the gate finds it by in the pinned manifest. An

package/dist/gates/http-tool.js

@@ -15,7 +15,9 @@
  */
 import { AGENT_ID_HEADER, SESSION_ID_HEADER, TURN_ID_HEADER, } from "@nylorun/core/compatibility";
 import { HTTP_TOOL_DEFAULT_TIMEOUT_MS, delegateManifest, flowHttpTarget, isWorkflowManifest, schemaFromJSON, } from "@nylorun/core/define";
+import { scrubValues } from "../redact.js";
 import { MAX_RESPONSE_BYTES, post } from "../tenant/outbound.js";
+import { credentialSecrets } from "../vault/headers.js";
 /** How much of a failed answer's body the model sees. */
 export const HTTP_ERROR_BODY_CHARS = 2_000;
 /** The HTTP tool `capabilityId`/`toolName` of the agent `agentId` (the root when absent). */
@@ -83,6 +85,9 @@ export async function callHttpTarget(target, input, options) {
         case "too_large":
             return failed("http.too-large", `The answer (HTTP ${result.status}) is larger than ${MAX_RESPONSE_BYTES} bytes`);
     }
+    // The service answered, so the outcome is known; never retried, and its body is not shown (R2b C1).
+    if (result.status === 401)
+        return failed("credential_rejected", "The service answered HTTP 401: it rejected the credential, or needs one");
     const text = result.body.toString("utf8");
     if (result.status < 200 || result.status > 299) {
         const body = text.length > HTTP_ERROR_BODY_CHARS ? `${text.slice(0, HTTP_ERROR_BODY_CHARS)}…` : text;
@@ -156,20 +161,26 @@ export async function runHttpTool(tenant, call, options) {
                 : `'${tool.toolName}' is not an HTTP tool of the session`);
         const { http } = declared;
         let credential = {};
+        let identity;
+        let target = http;
+        let vault;
         if (http.credential !== undefined) {
             const authorized = await tenant.authorize(tool.sessionId, {
-                kind: "http",
                 url: http.url,
                 serverName: http.credential,
-                ...(agentId === undefined ? {} : { agentId }),
             });
             if (authorized.status === "refused")
                 return failed("http.credential", `The credential '${http.credential}' was refused: ${authorized.reason}`);
             if (authorized.status === "unauthenticated")
                 return failed("http.credential", `The session's vaults hold no credential '${http.credential}' for ${authorized.url}`);
             credential = authorized.headers;
+            identity = authorized.identity;
+            vault = authorized.vault;
+            // A credential with `via` sends the call there, a gateway (R2b C2, Q9).
+            if (authorized.via !== undefined)
+                target = { ...http, url: authorized.via };
         }
-        return callHttpTarget(http, call.input, {
+        const answered = await callHttpTarget(target, call.input, {
             headers: {
                 ...credential,
                 [SESSION_ID_HEADER]: tool.sessionId,
@@ -181,6 +192,17 @@ export async function runHttpTool(tenant, call, options) {
             signal: options.signal,
             ...(declared.outputSchema === undefined ? {} : { outputSchema: declared.outputSchema }),
         });
+        // Nothing the service echoes of the credential reaches the model, an event or the gate's
+        // record of the call: its answer and the start of an error body alike (R2b C8).
+        const outcome = scrubbedOutcome(answered, credentialSecrets(credential, identity));
+        if (outcome.kind !== "failed" || outcome.code !== "credential_rejected" || http.credential === undefined)
+            return outcome;
+        return {
+            ...outcome,
+            message: `The service answered HTTP 401: it rejected the credential '${http.credential}' from the ${vault} vault`,
+            server: http.credential,
+            ...(vault === undefined ? {} : { vault }),
+        };
     }
 }
 /** The gates service's HTTP tool calls, with the Tenant's vault (`host/gates.ts`). */
@@ -195,3 +217,12 @@ export function gateHttpTools(vaults, policy, logger) {
 function failed(code, message) {
     return { kind: "failed", code, message };
 }
+/** `outcome` with each of `secrets` replaced by `[redacted]`, and how many were. */
+function scrubbedOutcome(outcome, secrets) {
+    if (outcome.kind === "completed") {
+        const output = scrubValues(outcome.output, secrets);
+        return output.redacted === 0 ? outcome : { ...outcome, output: output.value, redacted: output.redacted };
+    }
+    const message = scrubValues(outcome.message, secrets);
+    return message.redacted === 0 ? outcome : { ...outcome, message: message.value, redacted: message.redacted };
+}

package/dist/gates/mcp-handler.d.ts

@@ -18,7 +18,10 @@ export interface McpHandlerOptions {
     readonly delivery?: OutboundPolicy;
 }
 export interface McpHandler {
-    connect(tenantId: string | undefined, server: McpServerRef): Promise<McpAnswer<null>>;
+    /** Opens the connection; answers the server's instructions when it gave any (R2b C10). */
+    connect(tenantId: string | undefined, server: McpServerRef): Promise<McpAnswer<{
+        instructions: string;
+    } | null>>;
     list(tenantId: string | undefined, server: McpServerRef, cursor: string | undefined, signal: AbortSignal): Promise<McpAnswer<McpToolPage>>;
     /** One `tools/call`; the raw `CallToolResult` on success. */
     call(tenantId: string | undefined, request: {

package/dist/gates/mcp-handler.js

@@ -1,4 +1,4 @@
-import { openMcpServer, } from "../mcp/connect.js";
+import { McpCallFailed, McpConnectionStale, openMcpServer, unreachable, } from "../mcp/connect.js";
 import { findServer } from "../mcp/pool.js";
 import { GateRefusal } from "./tenant-vaults.js";
 /** A connection unused this long is closed; the next request opens it again. */
@@ -65,29 +65,79 @@ export function createMcpHandler(options) {
                 ...fields(server),
                 ...extra,
                 ms: now() - started,
-                outcome: failed.code === undefined ? "failed" : String(failed.code),
+                outcome: failed.failure?.code ?? (failed.code === undefined ? "failed" : String(failed.code)),
             });
             return { ok: false, error: failed };
         }
     }
-    async function use(tenantId, server, run) {
-        const entry = await connection(tenantId, server);
+    /** The server's connection; for a tool call, one that cannot be opened is `mcp.unreachable`. */
+    async function opened(tenantId, server, call) {
+        try {
+            return await connection(tenantId, server);
+        }
+        catch (error) {
+            // The call was never sent, so the model may try again (R2b C7). A gate that cannot serve
+            // the session is not the server's failure, and stays as it was.
+            if (!call || error instanceof GateRefusal || error instanceof NotDeclared)
+                throw error;
+            throw unreachable(server.serverName, error);
+        }
+    }
+    async function use(tenantId, server, run, call = false) {
+        const entry = await opened(tenantId, server, call);
         entry.active += 1;
         try {
             return await run(entry);
         }
+        catch (error) {
+            // The connection can no longer make requests: the next one opens a new connection, and
+            // the calls still running on this one finish first (the last closes it).
+            if (error instanceof McpConnectionStale) {
+                const key = keyOf(server);
+                if (live.get(key) === entry)
+                    live.delete(key);
+                entry.evicted = true;
+            }
+            throw error;
+        }
         finally {
             entry.active -= 1;
             entry.lastUsedAt = now();
+            if (entry.evicted && entry.active === 0)
+                void entry.connection.close().catch(() => { });
+        }
+    }
+    /**
+     * One `tools/call`. A connection found stale before the tool saw the call is opened again, and
+     * the call sent once more (R2b C7).
+     */
+    async function callOnce(tenantId, request, signal) {
+        for (let attempt = 0;; attempt += 1) {
+            try {
+                return await use(tenantId, request.server, (entry) => entry.connection.client.callTool({ name: request.name, arguments: request.arguments }, { signal }), true);
+            }
+            catch (error) {
+                if (!(error instanceof McpConnectionStale) || attempt > 0)
+                    throw error;
+            }
         }
     }
     return {
         connect: (tenantId, server) => answer("connect", server, async () => {
-            await connection(tenantId, server);
-            return null;
+            const { instructions } = (await connection(tenantId, server)).connection;
+            // The server's instructions, for the note on its deferred tools (R2b C10).
+            return instructions === undefined ? null : { instructions };
         }),
         list: (tenantId, server, cursor, signal) => answer("list", server, () => use(tenantId, server, (entry) => entry.connection.client.listTools(cursor ? { cursor } : undefined, { signal }))),
-        call: (tenantId, request, signal) => answer("call", request.server, () => use(tenantId, request.server, (entry) => entry.connection.client.callTool({ name: request.name, arguments: request.arguments }, { signal })), { effect: request.effectId }),
+        async call(tenantId, request, signal) {
+            const answered = await answer("call", request.server, () => callOnce(tenantId, request, signal), {
+                effect: request.effectId,
+            });
+            if (!answered.ok)
+                return answered;
+            const { result, redacted } = answered.result;
+            return { ok: true, result, ...(redacted ? { redacted } : {}) };
+        },
         async close(server) {
             const key = keyOf(server);
             const entry = live.get(key);
@@ -125,10 +175,16 @@ function fields(server) {
         ...(server.agentId === undefined ? {} : { agent: server.agentId }),
     };
 }
-/** An error as the loop's `diagnosticFromError` reads it. */
+/** An error as the loop's `diagnosticFromError` reads it, with a coded failure's code (R2b C7). */
 function errorOf(error) {
     if (error instanceof GateRefusal)
         return { message: error.outcome.message };
+    if (error instanceof McpCallFailed)
+        return {
+            message: error.message,
+            ...(error.code === "credential_rejected" ? { code: 401 } : {}),
+            failure: error.failure,
+        };
     const message = error instanceof Error ? error.message.slice(0, 2000) : String(error);
     const code = error && typeof error === "object" && "code" in error && typeof error.code === "number"
         ? error.code

package/dist/gates/tenant-vaults.d.ts

@@ -9,12 +9,12 @@
 import type { Credential } from "@earendil-works/pi-ai";
 import type { ModelFailureOutcome } from "@nylorun/core/define";
 import type { PostgresClient } from "../store/postgres/connect.js";
-import { type AuthorizeResult, type HostModelSecret } from "../vault/service.js";
-import { CredentialSources, type McpCredentialRequest, type ResolverConfig } from "../vault/sources.js";
+import { VaultService, type AuthorizeResult, type HostModelSecret } from "../vault/service.js";
+import { type McpCredentialRequest } from "../vault/sources.js";
 import type { SessionStore } from "../store/types.js";
+import type { OutboundPolicy } from "../tenant/outbound.js";
 import type { Session } from "../tenant/context.js";
 import { type Keys } from "../keys/keys.js";
-import { type OutboundPolicy } from "../tenant/outbound.js";
 /** The Tenant, as a model call needs it. */
 export interface TenantVault {
     readonly tenantId: string;
@@ -29,8 +29,7 @@ export interface TenantVault {
     session(sessionId: string): Promise<Session | undefined>;
     /**
      * The authorization of one request to a session's remote MCP server or HTTP tool: its
-     * credential from the session's attached vaults, refreshed when due (F4.1), else from the
-     * operator's credential resolver (F9 C1).
+     * credential from the session's attached vaults.
      */
     authorizeMcp(sessionId: string, request: McpCredentialRequest): Promise<AuthorizeResult>;
     /** Vault writes and token signing with the Tenant's vault key (the keys service, F4.2). */
@@ -52,18 +51,13 @@ export interface TenantVaultsOptions {
     readonly sql: PostgresClient;
     /** The Host root; the gate reads `keys/vault-kek` and `tenant/home` under it. */
     readonly hostRoot: string;
-    /** The operator's credential resolver (`NYLORUN_RESOLVER_*`, F9 C1). */
-    readonly resolver?: ResolverConfig;
-    /**
-     * The Host's address policy (`NYLORUN_ENDPOINT_*`): OAuth refresh and MCP OAuth connect call
-     * authorization servers through `guardedFetch` under it (F9 C2).
-     */
+    /** How the keys service's tool preview reaches a server (`NYLORUN_ENDPOINT_*`, R2b C12). */
     readonly delivery?: OutboundPolicy;
 }
 export declare function createTenantVaults(options: TenantVaultsOptions): TenantVaults;
 /**
- * A request to a session's remote MCP server, authorized from the session's attached vaults,
- * else the operator's credential resolver: what the loop does in its own process
- * (`tenant/effects.ts` `authorize`). The owner and turn come from the session row.
+ * A request to a session's remote MCP server, authorized from the session's attached vaults:
+ * what the loop does in its own process (`tenant/effects.ts` `authorize`). The vaults come from
+ * the session row.
  */
-export declare function authorizeSessionMcp(sources: CredentialSources, session: (sessionId: string) => Promise<Session | undefined>, sessionId: string, request: McpCredentialRequest): Promise<AuthorizeResult>;
+export declare function authorizeSessionMcp(vault: Pick<VaultService, "authorize">, session: (sessionId: string) => Promise<Session | undefined>, sessionId: string, request: McpCredentialRequest): Promise<AuthorizeResult>;

package/dist/gates/tenant-vaults.js

@@ -8,10 +8,9 @@ import { tenantPaths } from "../tenant/paths.js";
 import { readVaultKek } from "../vault/kek.js";
 import { HostModelVault } from "../vault/host-model.js";
 import { VaultService } from "../vault/service.js";
-import { CredentialSources } from "../vault/sources.js";
+import { sessionCredentials } from "../vault/sources.js";
 import { inProcessKeys } from "../keys/keys.js";
 import { SigningKeys } from "../tenant/signing-keys.js";
-import { guardedFetch } from "../tenant/outbound.js";
 /** A call the gate refuses before the provider is called; it answers with `outcome`. */
 export class GateRefusal extends Error {
     outcome;
@@ -35,20 +34,13 @@ export function createTenantVaults(options) {
             return kek;
         };
         const vault = new HostModelVault({ store, kek: readKek });
-        const credentials = new VaultService({
-            store,
-            kek: readKek,
-            fetch: guardedFetch(options.delivery ?? {}),
-        });
-        const sources = new CredentialSources({
-            vault: credentials,
-            ...(options.resolver ? { resolver: options.resolver } : {}),
-        });
+        const credentials = new VaultService({ store, kek: readKek });
         const keys = inProcessKeys({
             store,
             vault: credentials,
             signingKeys: new SigningKeys({ tenantId, kek: readKek }),
             kek: readKek,
+            ...(options.delivery ? { policy: options.delivery } : {}),
         });
         const session = (sessionId) => store.tx((t) => t.get("sessions", sessionId));
         return {
@@ -58,7 +50,7 @@ export function createTenantVaults(options) {
             readHostModel: () => vault.readHostModel(),
             writeHostCredential: (credential) => vault.updateHostCredential(credential),
             session,
-            authorizeMcp: (sessionId, request) => authorizeSessionMcp(sources, session, sessionId, request),
+            authorizeMcp: (sessionId, request) => authorizeSessionMcp(credentials, session, sessionId, request),
             keys: () => keys,
         };
     }
@@ -87,13 +79,13 @@ export function createTenantVaults(options) {
     };
 }
 /**
- * A request to a session's remote MCP server, authorized from the session's attached vaults,
- * else the operator's credential resolver: what the loop does in its own process
- * (`tenant/effects.ts` `authorize`). The owner and turn come from the session row.
+ * A request to a session's remote MCP server, authorized from the session's attached vaults:
+ * what the loop does in its own process (`tenant/effects.ts` `authorize`). The vaults come from
+ * the session row.
  */
-export async function authorizeSessionMcp(sources, session, sessionId, request) {
+export async function authorizeSessionMcp(vault, session, sessionId, request) {
     const found = await session(sessionId);
     if (!found)
         throw new Error(`Session ${sessionId} not found`);
-    return sources.authorize({ ...found, id: sessionId }, request);
+    return sessionCredentials(vault, { ...found, id: sessionId }, request);
 }

package/dist/gates/tool-client.js

@@ -6,9 +6,12 @@
  * has finished.
  *
  * Failures keep the meaning they had in the loop's own process:
- * - An MCP request that fails, at the server or on the hop, throws, so the pool reports a
- *   diagnostic and `resolveEffect` marks a call `uncertain`, as before. An HTTP tool call
- *   throws only for the hop, or a call lost with the gateway: its own failures are outcomes.
+ * - An MCP request that fails throws, so the pool reports a diagnostic. A tool call's coded
+ *   failure (R2b C7) throws the `McpCallFailed` the loop's own call would have, which becomes a
+ *   failed outcome the model sees. Only the hop's failures and a call lost with the gateway leave
+ *   it `uncertain`.
+ * - An HTTP tool call throws only for the hop, or a call lost with the gateway: its own failures
+ *   are outcomes.
  *
  * Credentials (F5): a session's MCP requests and keyed cancels carry its run token, read per
  * request from the advance's grant, and leave the session out of the body: the gate takes it
@@ -19,6 +22,7 @@
 import { randomUUID } from "node:crypto";
 import { request as httpRequest } from "node:http";
 import { request as httpsRequest } from "node:https";
+import { McpCallFailed, } from "../mcp/connect.js";
 import { TENANT_HEADER } from "./contract.js";
 import { GATE_CLIENT_TIMEOUT_MS } from "./http-client.js";
 import { HTTP_CALLS_PATH, MCP_CLOSE_PATH, MCP_CONNECT_PATH, MCP_LIST_PATH, TOOL_CALLS_PATH, } from "./tool-contract.js";
@@ -106,10 +110,11 @@ export function httpToolGate(options) {
         return { body: body(unnamed), bearer: token };
     }
     /**
-     * The result of an MCP or HTTP tool request, or a throw the pool and `resolveEffect` read as
-     * before: the call's fate is unknown, and the effect becomes `uncertain`.
+     * The answer of an MCP or HTTP tool request, or a throw: a coded MCP failure (`McpCallFailed`),
+     * or one the pool and `resolveEffect` read as before, the call's fate unknown and the effect
+     * `uncertain`.
      */
-    async function answered(path, scope, request) {
+    async function answer(path, scope, request) {
         const result = await exchange(path, scope.body, {
             ...request,
             timeoutMs,
@@ -123,9 +128,12 @@ export function httpToolGate(options) {
         if (result.status !== 200 || !parsed || !("ok" in parsed))
             throw new Error(gateRefusal(result.status, parsed));
         if (parsed.ok)
-            return parsed.result;
+            return parsed;
         throw mcpError(parsed.error);
     }
+    async function answered(path, scope, request) {
+        return (await answer(path, scope, request)).result;
+    }
     async function fireAndForget(path, scope) {
         await exchange(path, scope.body, {
             timeoutMs: SHORT_TIMEOUT_MS,
@@ -136,24 +144,32 @@ export function httpToolGate(options) {
         recovers: true,
         async openMcp(server) {
             // The credential is read per request: the connection outlives the advance that opened it.
-            await answered(MCP_CONNECT_PATH, scoped(server, (named) => ({ server: named })), {});
+            // A gate answers the server's instructions (R2b C10); an older one answers null.
+            const connected = await answered(MCP_CONNECT_PATH, scoped(server, (named) => ({ server: named })), {});
+            const instructions = typeof connected?.instructions === "string" && connected.instructions.length > 0
+                ? connected.instructions
+                : undefined;
             const client = {
                 listTools: (params, request) => answered(MCP_LIST_PATH, scoped(server, (named) => ({
                     server: named,
                     ...(params?.cursor ? { cursor: params.cursor } : {}),
                 })), request?.signal ? { signal: request.signal } : {}),
-                callTool: (params, request) => answered(TOOL_CALLS_PATH, scoped(server, (named) => ({
-                    server: named,
-                    effectId: request?.key ?? randomUUID(),
-                    name: params.name,
-                    arguments: params.arguments,
-                })), {
-                    ...(request?.signal ? { signal: request.signal } : {}),
-                    ...(request?.key ? { idempotencyKey: request.key } : {}),
-                }),
+                async callTool(params, request) {
+                    const called = await answer(TOOL_CALLS_PATH, scoped(server, (named) => ({
+                        server: named,
+                        effectId: request?.key ?? randomUUID(),
+                        name: params.name,
+                        arguments: params.arguments,
+                    })), {
+                        ...(request?.signal ? { signal: request.signal } : {}),
+                        ...(request?.key ? { idempotencyKey: request.key } : {}),
+                    });
+                    return { result: called.result, ...(called.redacted ? { redacted: called.redacted } : {}) };
+                },
             };
             return {
                 client,
+                ...(instructions === undefined ? {} : { instructions }),
                 close: () => fireAndForget(MCP_CLOSE_PATH, scoped(server, (named) => ({ server: named }))),
             };
         },
@@ -174,6 +190,9 @@ export function httpToolGate(options) {
 }
 /** An MCP failure the gate reported, as the loop's own MCP code would have thrown it. */
 function mcpError(error) {
+    // Coded (R2b C7): the model sees it. A call lost with the gateway never is.
+    if (error.failure && !error.uncertain)
+        return McpCallFailed.from(error.failure);
     const thrown = new Error(error.uncertain ? `${error.message} (the call may have run; it is not sent again)` : error.message);
     if (error.code !== undefined)
         thrown.code = error.code;