@nylorun/runtime 0.20.0-beta → 0.21.1-beta

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

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import { McpPreviewRequestSchema } from "@nylorun/core/contracts";
+import { McpPreview, McpPreviewRequest, Rejected } from "../../components.js";
+import { readJson } from "../body.js";
+import { tenantRoute } from "../define.js";
+import { jsonResponse } from "../respond.js";
+/** The vault routes' access: a management key. */
+const MANAGEMENT = { credentials: ["management"], scopes: "never" };
+const json = (schema, description) => ({
+    description,
+    content: { "application/json": { schema } },
+});
+export function mcpRoutes(api) {
+    tenantRoute(api, MANAGEMENT, {
+        method: "post",
+        path: "/v1/tenant/mcp/preview",
+        tags: ["MCP servers"],
+        summary: "Preview an MCP server's tools",
+        description: "Connects to the remote MCP server at `url` with the installation vault's credential for that URL (its headers and `via`; never an identity header), under the Host's address policy, lists its tools within 15 s and closes the connection. It never calls a tool. Each tool comes with the name the model would call it (`modelName`, made with `name`), its annotations and its input schema's size. A server that answers `401` is `authRequired`, with its RFC 9728 protected-resource metadata when it publishes any: it needs a person's sign-in, so reach it through a gateway (`via`), or with a key. No credential value is in the answer.",
+        request: {
+            body: { required: true, content: { "application/json": { schema: McpPreviewRequest } } },
+        },
+        responses: {
+            200: json(McpPreview, "The server's tools, or that it needs a credential (`authRequired`)"),
+            409: json(Rejected, "Several installation vaults hold a credential for the URL (name one with `vaultId`), or the one there cannot be used"),
+            502: json(Rejected, "The server could not be listed (`mcp_preview_failed`): `details.failure` is the code a tool call would have failed with, such as `mcp.unreachable` for an address the Host refuses"),
+        },
+    }, async (c) => {
+        const request = McpPreviewRequestSchema.parse(await readJson(c.req.raw));
+        return jsonResponse(200, await c.env.tenant.keys.previewMcp(request));
+    });
+}

package/dist/api/http/routes/vaults.d.ts

@@ -3,16 +3,8 @@
  * a session's tools use. Only a management key (or Studio's key, acting as itself) reaches these
  * routes; an application key is `403 key_role_mismatch`, and nothing acts for a subject here. The
  * installation's own vaults (`scope: "installation"`) attach to any session (`vaultIds`); a vault
- * of one person (`ownerUserId`) attaches only to that person's sessions. A person's own
- * credentials come from the operator's credential resolver (`vault/sources.ts`), not from these
- * routes.
- *
- * MCP OAuth connect: a management key starts one into an installation vault (`/oauth/start`);
- * the authorization server sends the browser back to the anonymous, unversioned
- * `GET /v1/oauth/callback`. Both only route: the gateway's keys module does the OAuth.
+ * of one person (`ownerUserId`) attaches only to that person's sessions.
  */
 import type { OpenAPIHono } from "@hono/zod-openapi";
 import type { TenantEnv } from "../app.js";
-/** Where the authorization server sends the browser back. */
-export declare const OAUTH_CALLBACK_PATH = "/v1/oauth/callback";
 export declare function vaultRoutes(api: OpenAPIHono<TenantEnv>): void;

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/core/flow-host.d.ts

@@ -1,8 +1,7 @@
 import type { EffectOutcome } from "@nylorun/core/contracts";
 import { type JsonValue, type WorkflowManifest } from "@nylorun/core/define";
 import type { HostEffect } from "@nylorun/harness/run";
-import type { Wake } from "../execution/types.js";
-import type { EffectDoc, Tx } from "../store/types.js";
+import type { EffectDoc, Tx, WakeDelivery } from "../store/types.js";
 import { type FlowLimits } from "./limits.js";
 /** Deterministic agent session id: derive(workflowSessionId, path, …parts). */
 export declare function deriveSessionId(workflowSessionId: string, path: string, ...parts: string[]): string;
@@ -99,7 +98,7 @@ export type CascadeCancelPlan = {
     readonly agentSessionIds: string[];
 };
 /** Wakes a session after commit (`DurableExecution.wake` through the Tenant context). */
-type Schedule = (sessionId: string, wake: Wake) => void | Promise<void>;
+type Schedule = WakeDelivery;
 /** Effect documents as the flow host writes them. */
 export type FlowEffect = EffectDoc & {
     agentSessionId?: string;

package/dist/core/flow-host.js

@@ -4,7 +4,8 @@
  * Every function that touches state takes the caller's transaction `t: Tx` and
  * is async. Nothing here publishes, notifies or schedules directly (seam rule
  * 1): events go through `t.event(...)`, which the store publishes after
- * commit, and wakes go through `t.afterCommit(() => schedule(id, wake))`. Functions
+ * commit, and wakes go through `t.wake(id, wake, schedule)`, the wake outbox, which
+ * calls `schedule` after commit. Functions
  * that rewrite a session-scoped document lock that session first with
  * `t.lockSession` (a no-op when the caller already holds it).
  *
@@ -35,8 +36,9 @@
  * - `foreignInteractionConflict({ t, workflowSessionId, interactionId }): Promise<{ status: 409; message; ownerSessionId } | undefined>`
  * - `wakeForQueuedEffects({ t, workflowSessionId, turnId, limits, schedule }): Promise<boolean>`
  *
- * `schedule: (sessionId, wake) => void | Promise<void>` runs after commit, never inside `t`;
- * `wake` carries the reason (`linked`, `flow`) and, where the cause has one, a dedupe key.
+ * `schedule` (a `WakeDelivery`, the Tenant's `ctx.wake`) runs after commit, never inside `t`;
+ * `wake` carries the reason (`linked`, `flow`) and, where the cause has one, a dedupe key. A
+ * wake `schedule` does not deliver stays in the outbox for the Tenant sweep (`Tx.wake`).
  *
  * An `agent` effect settles only from the linked turn it started. A linked agent session is
  * reused by every iteration of a Loop (its id derives from the workflow and the path), so its
@@ -138,8 +140,9 @@ export async function recordVerdict(t, request, value) {
         ...(verdict.data !== undefined ? { data: verdict.data } : {}),
     });
 }
-function scheduleAfterCommit(t, schedule, id, wake) {
-    t.afterCommit(() => schedule(id, wake));
+/** Writes the wake to the outbox; `schedule` delivers it after commit. */
+function requestWake(t, schedule, id, wake) {
+    return t.wake(id, wake, schedule);
 }
 /** Active agent turns + tool nodes in flight for one workflow turn. */
 export async function countActiveFlowWork(t, workflowSessionId, turnId) {
@@ -242,7 +245,7 @@ export async function wakeLinkedWorkflow(input) {
     await settleAgentEffect({ t, effect, outcome });
     workflow.status = "runnable";
     await t.put("sessions", workflow.id, workflow);
-    scheduleAfterCommit(t, input.schedule, workflow.id, {
+    await requestWake(t, input.schedule, workflow.id, {
         reason: "linked",
         dedupeKey: `linked:${link.turnId}:${link.effectId}`,
     });
@@ -471,7 +474,7 @@ export async function wakeForQueuedEffects(input) {
         workflow.status = "runnable";
         await t.put("sessions", workflow.id, workflow);
     }
-    scheduleAfterCommit(t, input.schedule, input.workflowSessionId, {
+    await requestWake(t, input.schedule, input.workflowSessionId, {
         reason: "flow",
     });
     return true;

package/dist/execution/types.d.ts

@@ -3,7 +3,10 @@
  *
  * Durable Session Execution decides when to look at a session again. It never
  * holds session state: every outcome lives in the Session Store, and `advance`
- * is safe to repeat (§10.1). Restate is the supported implementation
+ * is safe to repeat (§10.1). It owns the schedule (wake delivery, one advance per
+ * key, retries, timers, the sweep chain); the Session Store owns the record (the
+ * checkpoint, the effect journal, the events) and the wake outbox that bridges the
+ * two. Restate is the supported implementation
  * (`adapters/execution/restate.ts`); `execution/memory.ts` is the in-process
  * implementation used by unit tests, `startEphemeralRuntime` and a Host
  * started without Restate endpoints.
@@ -15,11 +18,14 @@
  *   Different keys may run concurrently.
  * - **At least once after a wake.** When `wake` resolves, an `advance` for the
  *   key will start after that point (possibly merged with other wakes). Wakes
- *   are sent after the Session Store transaction that caused them commits
- *   (`Tx.afterCommit`), never inside it.
+ *   are sent after the Session Store transaction that caused them commits, never
+ *   inside it: the transaction writes the wake to its outbox (`Tx.wake`), and the
+ *   wake is sent after commit, or by the Tenant sweep when that send failed or a
+ *   crash cut it off. A wake may therefore be sent more than once, always with the
+ *   same `dedupeKey`.
  * - **Dedupe.** Wakes carrying the same `dedupeKey` for the same key cause at
  *   most one advance for that cause (within the implementation's retention
- *   window, at least 24 hours for Restate).
+ *   window, at least 24 hours for Restate). Every wake from the outbox has one.
  * - **Busy re-wake.** An advance that returns `busy` is re-run for the same key
  *   after `retryAfterMs`.
  * - **Retries on infrastructure errors.** A handler that throws is retried with
@@ -27,7 +33,9 @@
  *   becomes `uncertain` is settled in the Session Store and `advance` returns
  *   `done`.
  * - **Sweeps.** `armSweep` arms one self-re-arming sweep per Tenant; arming an
- *   armed Tenant is a no-op. The sweep re-wakes orphaned `runnable` sessions.
+ *   armed Tenant is a no-op. The sweep sends the outbox's undelivered wakes and,
+ *   as a backstop for what an implementation lost, re-wakes orphaned sessions
+ *   (`tenant/sweep.ts`).
  * - **One reconcile per sandbox at a time** (F7.2). `sandbox` runs
  *   `WorkerHandlers.sandbox` for the key `<tenantId>:<sandboxId>` at least once
  *   after a `reconcile` resolves, never overlapping another run for the key. A

package/dist/execution/types.js

@@ -3,7 +3,10 @@
  *
  * Durable Session Execution decides when to look at a session again. It never
  * holds session state: every outcome lives in the Session Store, and `advance`
- * is safe to repeat (§10.1). Restate is the supported implementation
+ * is safe to repeat (§10.1). It owns the schedule (wake delivery, one advance per
+ * key, retries, timers, the sweep chain); the Session Store owns the record (the
+ * checkpoint, the effect journal, the events) and the wake outbox that bridges the
+ * two. Restate is the supported implementation
  * (`adapters/execution/restate.ts`); `execution/memory.ts` is the in-process
  * implementation used by unit tests, `startEphemeralRuntime` and a Host
  * started without Restate endpoints.
@@ -15,11 +18,14 @@
  *   Different keys may run concurrently.
  * - **At least once after a wake.** When `wake` resolves, an `advance` for the
  *   key will start after that point (possibly merged with other wakes). Wakes
- *   are sent after the Session Store transaction that caused them commits
- *   (`Tx.afterCommit`), never inside it.
+ *   are sent after the Session Store transaction that caused them commits, never
+ *   inside it: the transaction writes the wake to its outbox (`Tx.wake`), and the
+ *   wake is sent after commit, or by the Tenant sweep when that send failed or a
+ *   crash cut it off. A wake may therefore be sent more than once, always with the
+ *   same `dedupeKey`.
  * - **Dedupe.** Wakes carrying the same `dedupeKey` for the same key cause at
  *   most one advance for that cause (within the implementation's retention
- *   window, at least 24 hours for Restate).
+ *   window, at least 24 hours for Restate). Every wake from the outbox has one.
  * - **Busy re-wake.** An advance that returns `busy` is re-run for the same key
  *   after `retryAfterMs`.
  * - **Retries on infrastructure errors.** A handler that throws is retried with
@@ -27,7 +33,9 @@
  *   becomes `uncertain` is settled in the Session Store and `advance` returns
  *   `done`.
  * - **Sweeps.** `armSweep` arms one self-re-arming sweep per Tenant; arming an
- *   armed Tenant is a no-op. The sweep re-wakes orphaned `runnable` sessions.
+ *   armed Tenant is a no-op. The sweep sends the outbox's undelivered wakes and,
+ *   as a backstop for what an implementation lost, re-wakes orphaned sessions
+ *   (`tenant/sweep.ts`).
  * - **One reconcile per sandbox at a time** (F7.2). `sandbox` runs
  *   `WorkerHandlers.sandbox` for the key `<tenantId>:<sandboxId>` at least once
  *   after a `reconcile` resolves, never overlapping another run for the key. A

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