@bevel-software/platform-core-backend 0.14.0 → 0.19.0

package/dist/modules/mcp/mcp.service.js

@@ -1,30 +1,34 @@
-import { randomUUID } from 'node:crypto';
+import { createHash } from 'node:crypto';
+import { logger } from '../../shared/logging.js';
+const log = logger('mcp');
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, McpError, ErrorCode, } from '@modelcontextprotocol/sdk/types.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, McpError, ErrorCode, isInitializeRequest, } from '@modelcontextprotocol/sdk/types.js';
 import '@utcp/http'; // side effect: registers the 'http' UTCP communication protocol
 import '@utcp/mcp'; // side effect: registers the 'mcp' protocol (native MCP-server `.tool` sources)
-import { UtcpClientConfigSerializer, CallTemplateSerializer, } from '@utcp/sdk';
+import { UtcpClientConfigSerializer, CallTemplateSerializer, UtcpManualSchema, } from '@utcp/sdk';
 import { CodeModeUtcpClient } from '@utcp/code-mode';
-import { CODE_MODE_META_TOOLS, META_TOOL_NAMES, dispatchMetaTool, dispatchToolCall, registerManual, flattenManualTool, toListedTool, toolError, needsAuthorizationResult, skillPromptText, } from '@bevel-software/platform-mcp-core';
+import { CODE_MODE_META_TOOLS, META_TOOL_NAMES, dispatchMetaTool, dispatchToolCall, registerManual, installSessionRecovery, flattenManualTool, toListedTool, toolError, retiredToolMessage, needsAuthorizationResult, skillPromptText, } from '@bevel-software/platform-mcp-core';
 import { bevelSecretsLoaderConfig } from '../secrets-vault/index.js';
-import { scopesCovered } from '../secrets-vault/secrets-vault.contract.js';
+import { scopesCovered, } from '../secrets-vault/secrets-vault.contract.js';
 import { EXTERNAL_KB_MANUAL_NAME } from '../tool-manuals/tool-manuals.contract.js';
 import { seedBevelHostedManualVars } from '../../shared/utcp-namespace.js';
 import { ManualFailureMemo } from './manual-failure-memo.js';
+import { DownstreamPool, POOL_KEY_SEPARATOR } from './downstream-pool.js';
+import { SurfaceLogThrottle } from './surface-log-throttle.js';
+import { DownstreamRefreshGuard, isDownstreamTokenRejection } from './downstream-token-refresh.js';
+import { printable } from '../../shared/printable.js';
+import { composeAgentInstructions, prefixToolDescription, PREFIXED_TOOLS, } from '../agent-instructions/index.js';
 /**
  * Upper bound on one `loopbackJson` round-trip (manual list, skill fetch) so a
- * hung loopback can't stall `createSession`. Generous: these endpoints answer
- * in milliseconds; only a wedged process ever comes near it.
+ * hung loopback can't stall a request. Generous: these endpoints answer in
+ * milliseconds; only a wedged process ever comes near it.
  */
 const LOOPBACK_TIMEOUT_MS = 15_000;
 /**
- * Lifetime of the internal token minted as an OAuth/JWT session's loopback
- * bearer. Longer than the session store's 4h idle eviction (see
- * `DEFAULT_IDLE_TTL_MS` in mcp-session-store.ts) so the credential is not the
- * first thing to die under a session's normal lifecycle. A continuously-active
- * session CAN outlive it — its tool calls then fail at the loopback and the
- * client recovers by re-initializing, which mints a fresh token.
+ * Lifetime of the internal token minted as an OAuth/JWT request's loopback
+ * bearer. A request only needs it for as long as it runs, but one `tools/call`
+ * can legitimately run for a long time (`ask`, a long `call_tool_chain`), so
+ * the lifetime is generous rather than tight.
  *
  * Exported because `POST /api/mcp/local-token` (mcp.routes.ts) performs the
  * same OAuth-access-token → internal-token exchange for the LOCAL MCP server,
@@ -33,133 +37,189 @@ const LOOPBACK_TIMEOUT_MS = 15_000;
  */
 export const MCP_LOOPBACK_TOKEN_TTL_MS = 5 * 60 * 60 * 1000;
 const callTemplateSerializer = new CallTemplateSerializer();
+/** The {@link DownstreamRoute.afterFailure} answer that means "refreshed — retry once". */
+const RETRY_WITH_REFRESHED_TOKEN = Symbol('retry-with-refreshed-token');
 /**
- * The MCP server is a GENERIC proxy over the UTCP tool surface. It owns no tool
- * logic: per MCP session it stands up a `UtcpClient` pointed at the backend's
- * own `GET /api/agent/utcp` manual (over loopback, authenticated with the
- * caller's connection key), discovers every tool, and re-exposes each one to
- * the MCP client. A tool call is dispatched straight back through the same REST
- * endpoint the tool's UTCP `tool_call_template` names — so the agent logic,
+ * The MCP server is a GENERIC, STATELESS proxy over the UTCP tool surface. It
+ * owns no tool logic and no session: every HTTP request gets its own MCP
+ * `Server`, built from that request's bearer. When the request needs tools it
+ * stands up a `UtcpClient` pointed at the backend's own `GET /api/agent/all-tools`
+ * catalog (over loopback, authenticated as the caller, so ACL filtering lives
+ * ONCE behind the REST surface), discovers every tool, and re-exposes each one
+ * to the MCP client. A tool call is dispatched straight back through the same
+ * REST endpoint the tool's UTCP `tool_call_template` names — so the agent logic,
  * thread continuity, and per-key token metering all live ONCE behind that REST
  * endpoint (`AgentAskService` for `ask`), never duplicated here.
  *
+ * Because nothing is held between requests, a platform restart between two
+ * requests of one client conversation is undetectable by the client.
+ *
+ * There is NO catalog cache at this layer, deliberately: the catalog is
+ * re-derived per request, and if that ever proves too slow the fix belongs in
+ * the source path (all-tools/ACL), which serves every other caller too.
+ *
+ * The one exception to "nothing between requests" is proxied third-party MCP
+ * servers (`mcp` manuals): those are session-ful by nature, so their
+ * connections live in a {@link DownstreamPool} keyed by (user, manual) — lazy,
+ * single-flight, idle-evicted, bounded, and healed by session recovery. Losing
+ * any of it costs a reconnect, never correctness.
+ *
  * Dispatch always uses `callToolStreaming`, which is uniform across tool kinds:
  * a plain `http` tool yields exactly one chunk (its final result, emitted as
  * the tool result with no progress), while a `streamable_http` tool yields many
- * (the all-but-last become `notifications/progress`, the last is the result).
- * Because of that, adding — or later upgrading a tool to streaming — never
- * touches this file.
+ * (the all-but-last become `notifications/progress` on the request's own
+ * response stream, the last is the result).
  *
  * Auth note: `/api/agent/*` accepts connection keys and internal tokens only.
- * Connection-key sessions pass the caller's own key through to the loopback;
- * OAuth/JWT sessions can't (their bearer would 401 there), so `createSession`
- * mints a least-privilege internal token for the resolved user and uses THAT
- * as the session's loopback bearer instead.
+ * Connection-key requests pass the caller's own key through to the loopback;
+ * OAuth/JWT requests can't (their bearer would 401 there), so the proxy mints a
+ * least-privilege internal token for the resolved user and uses THAT as the
+ * request's loopback bearer instead.
  */
 export class McpService {
-    sessionStore;
     opts;
     secretsVault;
     toolManuals;
     internalTokens;
     revokeOAuthAccess;
     // Circuit breaker for manuals whose credentials just failed — see the memo.
+    // Retry policy, not session state: it survives the move to statelessness.
     manualFailures = new ManualFailureMemo();
+    surfaceLog = new SurfaceLogThrottle();
+    // One forced token refresh per (user, manual) per minute — see downstream-token-refresh.
+    tokenRefreshes;
     /**
-     * Invalidate remembered manual failures — wired to the secrets vault's
-     * mutation listener, so a just-repaired credential is retried on the very
-     * next session build. `null` = a shared secret changed (affects everyone).
+     * The tools each pooled manual last advertised, by manual definition. A
+     * downstream can only be asked what its tools are over a connection, and a
+     * caller whose sign-in is missing or broken has no connection — so their
+     * tools would silently vanish from the surface, and a call would answer
+     * "Unknown tool" instead of "sign in again on /connect". These definitions
+     * keep the manual on the surface for such a caller; the call-time credential
+     * check then answers with the link, and an interactive client is sent back
+     * through authorization. Definitions, never credentials or results. Keyed
+     * by catalog name — one entry per manual, replaced when the manual is next
+     * discovered — and used only while the manual's definition is the one the
+     * tools were discovered from, so an edited `mcp.json` never serves the old
+     * server's tools.
      */
-    clearManualFailures(userId) {
-        if (userId === null)
-            this.manualFailures.clearAll();
-        else
-            this.manualFailures.clearUser(userId);
-    }
-    constructor(sessionStore, opts, 
+    knownDownstreamTools = new Map();
+    // The downstream connection pool for `mcp` manuals — see the class doc.
+    downstream;
+    constructor(opts, 
     // The vault + manual catalog, used to check a caller's per-user credentials
     // before dispatching a tool. Optional so existing constructions/tests that
     // don't exercise the check keep working (the check is skipped when absent).
     secretsVault, toolManuals, 
-    // Mints the loopback bearer for OAuth/JWT sessions (see class doc).
-    // Optional for the same test-compat reason; without it those sessions
+    // Mints the loopback bearer for OAuth/JWT requests (see class doc).
+    // Optional for the same test-compat reason; without it those requests
     // fall back to the old pass-through (and 401 at the loopback hop).
     internalTokens, 
     // Revokes an MCP OAuth access token (BevelOAuthProvider.revokeByAccessToken)
-    // — the reset that sends an interactive session back through the browser
+    // — the reset that sends an interactive client back through the browser
     // authorization when one of its TOOL sign-ins breaks. Optional: without
     // it, broken sign-ins surface only as the /connect link in the result.
     revokeOAuthAccess) {
-        this.sessionStore = sessionStore;
         this.opts = opts;
         this.secretsVault = secretsVault;
         this.toolManuals = toolManuals;
         this.internalTokens = internalTokens;
         this.revokeOAuthAccess = revokeOAuthAccess;
+        this.downstream = new DownstreamPool({
+            ...opts.downstreamPool,
+            // Since @utcp/sdk 1.2.0 a client closes only the protocol instances it
+            // created, and @utcp/mcp registers as a factory — so this closes exactly
+            // this entry's MCP sessions and touches no other client's.
+            dispose: (entry) => entry.client.close(),
+        });
+        // Paced on the pool's clock, so a test that moves one moves both.
+        this.tokenRefreshes = new DownstreamRefreshGuard(undefined, opts.downstreamPool?.now);
     }
     /**
-     * Subscribe to store-driven evictions (idle-TTL sweep, size-cap eviction) so
-     * the route layer can drop its transport mirror. Returns an unsubscribe fn.
+     * A secret changed — wired to the secrets vault's mutation listener.
+     * `null` = a shared secret changed (affects everyone).
+     *
+     * Two things were built from the old value: remembered manual failures (so a
+     * just-repaired credential is retried on the very next request) and pooled
+     * downstream connections (dialed and discovered with the old credential).
+     * Both are dropped; the next request rebuilds whatever it needs.
      */
-    onSessionEvicted(listener) {
-        return this.sessionStore.onEvict(listener);
+    onSecretsChanged(userId) {
+        this.forgetStaleRefreshWindows(userId);
+        if (userId === null) {
+            this.manualFailures.clearAll();
+            this.downstream.closeAll();
+            return;
+        }
+        this.manualFailures.clearUser(userId);
+        this.downstream.evictWhere((key) => key.startsWith(`${userId}${POOL_KEY_SEPARATOR}`));
     }
     /**
-     * Build a fresh per-session (transport, server) pair. Async because tool
-     * discovery (a loopback round-trip authenticated with `bearer`) happens here,
-     * before the server is returned, so `tools/list` is ready the moment the
-     * client asks. The route awaits this, then `server.connect(transport)`.
+     * A credential changed, so a refresh window that FAILED to produce one no
+     * longer describes anything: a token the user has just re-authorized (or an
+     * admin has just re-keyed) must be tried on the very next rejection, not sit
+     * out the remainder of a minute earned by the credential it replaced.
+     *
+     * Only settled, non-`refreshed` windows are forgotten. A refresh of our own
+     * is itself a secrets mutation, and clearing on that would hand a provider
+     * that keeps minting tokens the downstream keeps refusing one refresh per
+     * call — precisely the loop the once-a-minute guard exists to bound. An
+     * in-flight attempt (no outcome yet) is left alone for the same reason: it
+     * may be the very refresh that raised this notification.
      */
-    async createSession(userId, tokenId, bearer, onSessionInitialized) {
+    forgetStaleRefreshWindows(userId) {
+        const mine = (key) => userId === null || key.startsWith(`${userId}${POOL_KEY_SEPARATOR}`);
+        this.tokenRefreshes.clearWhere((key, outcome) => mine(key) && outcome !== undefined && outcome !== 'refreshed');
+    }
+    /**
+     * Build the MCP `Server` for ONE request. The route connects it to a fresh
+     * stateless transport, lets it answer, and closes both with the response.
+     *
+     * Cheap by construction: nothing is fetched up front except what the
+     * request's own messages need. The agent instructions are read only when the
+     * request carries an `initialize` (the only place they ride); the tool
+     * catalog is built on the first handler that needs it and shared by every
+     * message of the request (a JSON-RPC batch), never beyond it.
+     */
+    async createRequestServer(caller, messages) {
+        const { userId, tokenId, bearer } = caller;
         // The loopback surface (`/api/agent/*`) accepts connection keys and
-        // internal tokens only. A connection-key session passes the caller's own
-        // key through (per-key metering rides on it); an OAuth/JWT session's
+        // internal tokens only. A connection-key request passes the caller's own
+        // key through (per-key metering rides on it); an OAuth/JWT request's
         // bearer would 401 there, so mint a least-privilege internal token for
         // the resolved user instead — flagged `externalProxy` so the tool-auth
         // verifier resolves it to `source: 'external'`: the caller IS an external
         // agent and must be treated like one (admitted to `start_session`/`ask`,
-        // refused from internal-only tools). TTL covers the session store's 4h
-        // idle eviction — an evicted session re-initializes and re-mints.
+        // refused from internal-only tools).
         const loopbackBearer = tokenId == null && this.internalTokens
             ? this.internalTokens.mint({ userId, externalProxy: true }, MCP_LOOPBACK_TOKEN_TTL_MS)
             : bearer;
-        // The list of manuals this caller gets: the KB manual + each `.tool` they
-        // can read. Fetched over loopback with the caller's key, so ACL filtering
-        // lives ONCE behind the REST surface.
-        const manuals = await this.fetchManualTemplates(loopbackBearer);
-        const client = await this.buildClient(loopbackBearer, userId, manuals);
-        const tools = await this.discoverTools(client, manuals, userId);
-        // Confirms the MCP session was built for a connecting client (vs. an
-        // in-process agent code-mode client, which never runs createSession) and
-        // how many tools discovery yielded before listing/filtering.
-        console.log(`[mcp] createSession: user=${userId} tokenId=${tokenId ?? 'none'} — ` +
-            `discovered ${tools.length} tool(s) across ${manuals.length} manual(s)`);
-        const transport = new StreamableHTTPServerTransport({
-            sessionIdGenerator: () => randomUUID(),
-            onsessioninitialized: (sessionId) => {
-                this.sessionStore.create(sessionId, userId, tokenId);
-                onSessionInitialized(sessionId);
-            },
-            onsessionclosed: (sessionId) => {
-                this.sessionStore.delete(sessionId);
-            },
+        let instructions;
+        const agentInstructions = () => (instructions ??= this.composeAgentInstructions());
+        let surface;
+        const requestSurface = () => (surface ??= this.buildSurface(userId, tokenId, loopbackBearer));
+        const initializing = (Array.isArray(messages) ? messages : [messages]).some((m) => isInitializeRequest(m));
+        const server = new Server({ name: 'bevel-mcp', version: '0.1.0' }, {
+            capabilities: { tools: {}, prompts: {} },
+            // `instructions` rides the initialize result; clients that honour it
+            // place the text in the model's system prompt without the model acting.
+            ...(initializing ? { instructions: (await agentInstructions()).instructions } : {}),
         });
-        const server = new Server({ name: 'bevel-mcp', version: '0.1.0' }, { capabilities: { tools: {}, prompts: {} } });
         server.setRequestHandler(ListToolsRequestSchema, async () => {
+            const [{ tools, catalogNames }, { toolPrefix }] = await Promise.all([requestSurface(), agentInstructions()]);
             // A discovered tool whose name collides with a meta-tool would be
             // listed but never callable (the dispatcher routes the name to the
             // meta-tool first), so drop it from the listing entirely.
             let listed = tools.filter((t) => !META_TOOL_NAMES.has(t.mcpName));
-            // Connection-key sessions are autonomous pipelines — nobody is present
+            // Connection-key callers are autonomous pipelines — nobody is present
             // to complete a sign-in mid-run, so register ONLY the tools whose
             // per-user credentials are already satisfied. Interactive (OAuth/JWT)
-            // sessions keep the full listing: their caller can configure a tool on
+            // callers keep the full listing: they can configure a tool on
             // /connect when the call-time check points them there.
             if (tokenId != null) {
                 const ready = await Promise.all(
                 // A per-tool check that throws must NOT reject the whole list (which
                 // would blank every tool) — fail that one tool closed and move on.
-                listed.map((t) => this.missingUserSecrets(userId, t).then((missing) => missing.length === 0, () => false)));
+                listed.map((t) => this.missingUserSecrets(userId, catalogNames.get(t.manualName) ?? t.manualName).then((missing) => missing.length === 0, () => false)));
                 listed = listed.filter((_, i) => ready[i]);
             }
             // Validate + dedupe each discovered tool so ONE non-conforming or
@@ -180,14 +240,20 @@ export class McpService {
                     continue;
                 }
                 seen.add(entry.name);
-                direct.push(entry);
+                // The four knowledge-base tools carry the purpose prefix: the one
+                // pre-call channel every client shows the model, for the clients that
+                // drop the handshake's `instructions`. Applied AFTER the credential
+                // filter above, so a connection-key caller's listing carries it too.
+                // Every other tool, meta-tools included, keeps its description as is.
+                direct.push(PREFIXED_TOOLS.has(entry.name)
+                    ? { ...entry, description: prefixToolDescription(toolPrefix, entry.description) }
+                    : entry);
             }
             // Log only when a tool was dropped (name/schema/duplicate) — that's the
             // anomaly worth surfacing, since a downstream client would otherwise hide
-            // it by rejecting the whole response. The steady-state served count is
-            // already visible once per session in the createSession log above.
+            // it by rejecting the whole response.
             if (dropped.length) {
-                console.warn(`[mcp] tools/list: serving ${CODE_MODE_META_TOOLS.length + direct.length} tool(s); ` +
+                log.warn(`tools/list: serving ${CODE_MODE_META_TOOLS.length + direct.length} tool(s); ` +
                     `dropped ${dropped.length} non-listable: ${dropped.join(', ')}`);
             }
             return {
@@ -196,44 +262,66 @@ export class McpService {
             };
         });
         server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
-            if (META_TOOL_NAMES.has(request.params.name)) {
-                return this.dispatchMetaTool(client, request.params.name, request.params.arguments ?? {});
+            const { client, tools, unavailable, catalogNames } = await requestSurface();
+            const toolName = request.params.name;
+            if (META_TOOL_NAMES.has(toolName)) {
+                return this.dispatchMetaTool(client, toolName, request.params.arguments ?? {});
             }
-            const proxied = tools.find((t) => t.mcpName === request.params.name);
-            if (!proxied) {
-                return toolError(`Unknown tool "${request.params.name}".`);
-            }
-            // Stop before running a tool whose personal (user-scoped) credentials the
-            // caller hasn't provided — return a setup link instead of a blank-credential
-            // request that would fail opaquely at the provider.
-            const needsAuth = await this.checkUserSecrets(userId, proxied);
-            if (needsAuth) {
+            /**
+             * The needs-authorization answer, when the caller's sign-in for the
+             * manual registered as `utcpName` is missing or broken; `null` to
+             * proceed. Stops before running a tool whose personal (user-scoped)
+             * credentials the caller hasn't provided — a setup link instead of a
+             * blank-credential request that would fail opaquely at the provider.
+             * The credential catalog keys manuals by their CATALOG name; a tool
+             * carries the registered (rewritten) one, so it is translated back.
+             */
+            const needsAuthorization = async (utcpName) => {
+                const needsAuth = await this.checkUserSecrets(userId, toolName, catalogNames.get(utcpName) ?? utcpName);
+                if (!needsAuth)
+                    return null;
                 // A sign-in that EXISTS but is broken (expired grant, abandoned
-                // consent, missing scopes) on an interactive OAuth session: revoke the
+                // consent, missing scopes) on an interactive OAuth caller: revoke the
                 // agent's own grant too. Its next request then 401s, its refresh
                 // fails, and it re-runs the browser authorization — landing the user
                 // on /connect where the broken sign-in shows as not-connected, to
                 // re-authorize or deselect. Never-configured tools keep the plain
                 // link (revoking for those would loop on every poke at a tool the
-                // user simply hasn't set up). Connection-key sessions have no grant
+                // user simply hasn't set up). Connection-key callers have no grant
                 // to reset; the revoke no-ops on non-OAuth bearers anyway.
                 if (needsAuth.brokenSignIn && tokenId == null && this.revokeOAuthAccess) {
                     try {
                         await this.revokeOAuthAccess(bearer);
                     }
                     catch (err) {
-                        console.warn('[mcp] failed to reset the session grant for re-auth:', err);
+                        log.warn('failed to reset the caller grant for re-auth:', { err });
                     }
                 }
                 return needsAuth.result;
+            };
+            const proxied = tools.find((t) => t.mcpName === toolName);
+            if (!proxied) {
+                // Not on the surface — but if the name belongs to a manual that is off
+                // it only because this caller's sign-in is gone (and nothing in this
+                // process has seen its tools yet), the honest answer is the sign-in
+                // link, exactly as if the tool were listed. Longest matching prefix:
+                // manual names may themselves contain underscores.
+                const owner = unavailable
+                    .filter((m) => toolName.startsWith(`${m.utcpName}_`))
+                    .sort((a, b) => b.utcpName.length - a.utcpName.length)[0];
+                const answer = owner ? await needsAuthorization(owner.utcpName) : null;
+                return answer ?? toolError(retiredToolMessage(toolName) ?? `Unknown tool "${toolName}".`);
             }
+            const needsAuth = await needsAuthorization(proxied.manualName);
+            if (needsAuth)
+                return needsAuth;
             return this.dispatch(client, proxied, request, extra);
         });
         // Prompts = skills. Each skill becomes a user-callable prompt (slash command
         // in MCP clients). Backed by the same skill endpoints the tools use, over
         // loopback with the caller's key — so the default-branch catalog, access
         // filtering, and progressive disclosure all live ONCE behind that REST
-        // surface, never duplicated here.
+        // surface, never duplicated here. Neither handler needs the tool catalog.
         server.setRequestHandler(ListPromptsRequestSchema, async () => {
             const skills = await this.fetchSkillList(loopbackBearer);
             const prompts = skills.map((s) => ({
@@ -253,7 +341,57 @@ export class McpService {
                 messages: [{ role: 'user', content: { type: 'text', text: skillPromptText(skill) } }],
             };
         });
-        return { transport, server };
+        return server;
+    }
+    /**
+     * The request's tool surface: catalog over loopback, a fresh UTCP client,
+     * every manual registered (pooled for `mcp` ones), tools flattened.
+     *
+     * Logs one line with the time each half took — the per-request overhead
+     * the stateless design trades for restart-invisibility, kept visible so it
+     * is measured rather than assumed.
+     */
+    async buildSurface(userId, tokenId, loopbackBearer) {
+        const started = performance.now();
+        // The list of manuals this caller gets: the KB manual + each `.tool` they
+        // can read. Fetched over loopback with the caller's key, so ACL filtering
+        // lives ONCE behind the REST surface.
+        const manuals = await this.fetchManualTemplates(loopbackBearer);
+        const catalogMs = performance.now() - started;
+        const client = await this.buildClient(loopbackBearer, userId, manuals);
+        const { tools, unavailable, catalogNames } = await this.discoverTools(client, manuals, userId);
+        const totalMs = performance.now() - started;
+        // Per user: on a shape change or once per interval, never per request —
+        // see SurfaceLogThrottle for why both halves matter.
+        const decision = this.surfaceLog.decide(userId, { tools: tools.length, manuals: manuals.length });
+        if (decision.log) {
+            log.info(
+            // Both ids come from the request (an identity provider's subject, a
+            // connection key's id), so neither is interpolated raw — see printable.
+            `request surface: user=${printable(userId)} tokenId=${tokenId ? printable(tokenId) : 'none'} — ` +
+                `${tools.length} tool(s) across ${manuals.length} manual(s) in ${totalMs.toFixed(0)}ms ` +
+                `(catalog ${catalogMs.toFixed(0)}ms, registration ${(totalMs - catalogMs).toFixed(0)}ms)` +
+                (decision.suppressed > 0 ? ` [+${decision.suppressed} identical rebuild(s) since last line]` : ''));
+        }
+        return { client, tools, unavailable, catalogNames };
+    }
+    /**
+     * The instructions and tool prefix. A reader failure (a disk fault; ENOENT
+     * is not one, the reader answers null for that) falls back to the header
+     * alone and the fixed prefix line with a logged warning: a request never
+     * fails over its preamble.
+     */
+    async composeAgentInstructions() {
+        const read = this.opts.readAgentPreamble;
+        if (!read)
+            return composeAgentInstructions(null);
+        try {
+            return composeAgentInstructions(await read());
+        }
+        catch (err) {
+            log.warn('could not read mcp-description.md; this request gets the platform header alone:', { err });
+            return composeAgentInstructions(null);
+        }
     }
     /** Loopback GET of the default-branch skill catalog (via the `list_skills` tool). */
     async fetchSkillList(bearer) {
@@ -272,10 +410,9 @@ export class McpService {
      * The ONE loopback round-trip: fetch `path` on our own REST surface with the
      * caller's bearer, parse JSON. Failures are logged under `label` (never the
      * bearer) and degrade to null — a loopback hiccup must not throw into the
-     * MCP session. GET when `json` is absent, POST with a JSON body when present.
-     * Bounded: a hung loopback (e.g. mid-restart) must not block `createSession`
-     * or a prompts handler indefinitely; a timeout aborts and degrades to null
-     * like any other failure.
+     * MCP request. GET when `json` is absent, POST with a JSON body when present.
+     * Bounded: a hung loopback (e.g. mid-restart) must not block a request
+     * indefinitely; a timeout aborts and degrades to null like any other failure.
      */
     async loopbackJson(bearer, path, label, json) {
         try {
@@ -288,13 +425,13 @@ export class McpService {
                 signal: AbortSignal.timeout(LOOPBACK_TIMEOUT_MS),
             });
             if (!res.ok) {
-                console.error(`[mcp] ${label} loopback failed: HTTP ${res.status} ${await res.text().catch(() => '')}`);
+                log.error(`${label} loopback failed: HTTP ${res.status} ${await res.text().catch(() => '')}`);
                 return null;
             }
             return await res.json();
         }
         catch (err) {
-            console.error(`[mcp] ${label} loopback threw:`, err instanceof Error ? err.message : err);
+            log.error(`${label} loopback threw:`, { err });
             return null;
         }
     }
@@ -307,7 +444,7 @@ export class McpService {
      * validated into `CallTemplate`s at the boundary. The KB manual is guaranteed
      * present (a fallback covers an unavailable endpoint); a user manual that
      * fails validation is dropped + logged so one bad `.tool` can't break the
-     * session. HTTP transport loses the `CallTemplate` type, so we re-validate the
+     * request. HTTP transport loses the `CallTemplate` type, so we re-validate the
      * received JSON even though the producing endpoint already validated it.
      */
     async fetchManualTemplates(bearer) {
@@ -328,7 +465,7 @@ export class McpService {
                 const name = String(raw?.name ?? '');
                 if (isKb)
                     throw err; // the KB manual must be valid — the core toolset depends on it
-                console.warn(`[mcp] skipping manual "${name}": ${err instanceof Error ? err.message : String(err)}`);
+                log.warn(`skipping manual "${name}": ${err instanceof Error ? err.message : String(err)}`);
             }
         }
         // Always include the KB manual, even if `all-tools` was unavailable/regressed.
@@ -348,75 +485,360 @@ export class McpService {
         });
     }
     /**
-     * One `CodeModeUtcpClient` per session. Reserved `API_URL`/`CONNECTION_KEY` are
+     * One `CodeModeUtcpClient` per request. Reserved `API_URL`/`CONNECTION_KEY` are
      * seeded (namespaced) ONLY for Bevel-hosted manuals — the KB manual and inline
      * `.tool` sub-manuals, whose discovery template targets the loopback (`${API_URL}`).
      * Third-party http/mcp `.tool`s point at arbitrary user URLs, so we must NOT seed
      * them the caller's bearer: a malicious `.tool` referencing `${CONNECTION_KEY}`
      * would otherwise exfiltrate the caller's token to its own endpoint. Tool
      * `${SECRET}` refs resolve lazily via the per-user `bevel-secrets` loader.
+     *
+     * Not `close()`d: a request's client holds no connection of its own (its
+     * `mcp` manuals route to the pool, so its own `mcp` protocol instance never
+     * opens a session), and dropping the reference is the whole teardown.
      */
     async buildClient(bearer, userId, manuals) {
-        // Bevel-hosted manuals (KB + inline `.tool` sub-manuals, discovery url
-        // `${API_URL}/…`) get the loopback creds; third-party `.tool` URLs are never
-        // seeded so the bearer can't leak. Same rule the in-process agent factory uses.
         const variables = seedBevelHostedManualVars(manuals, this.opts.loopbackBaseUrl, bearer);
-        const config = new UtcpClientConfigSerializer().validateDict({
-            variables,
-            load_variables_from: [bevelSecretsLoaderConfig(userId)],
-        });
-        return CodeModeUtcpClient.create(process.cwd(), config);
+        return CodeModeUtcpClient.create(process.cwd(), utcpClientConfig(userId, variables));
     }
     /**
-     * Register EVERY manual on the client, then flatten each discovered tool into
-     * the proxy's advertised shape. A failure registering a user `.tool` is
-     * isolated (logged + skipped) so one broken manual never breaks the session;
-     * the KB manual failing is fatal (the core toolset is unusable).
+     * Register EVERY manual for this request, then flatten each discovered tool
+     * into the proxy's advertised shape. Manuals register concurrently — they are
+     * independent, and a request pays for the slowest one rather than the sum. A
+     * failure registering a user `.tool` is isolated (logged + skipped) so one
+     * broken manual never breaks the request; the KB manual failing is fatal (the
+     * core toolset is unusable).
      *
-     * Failures are memoized per (user, manual) for a few minutes (see
-     * {@link ManualFailureMemo}): sessions rebuild constantly, and a manual with
-     * a broken credential (expired OAuth, revoked key) would otherwise re-dial
-     * its provider on every single build.
+     * `mcp` manuals never dial from here: they are attached from the downstream
+     * pool (see {@link attachDownstream}).
+     *
+     * Failures are memoized per (user, manual definition) for a few minutes (see
+     * {@link ManualFailureMemo}): the catalog is rebuilt on every request, and a
+     * manual with a broken credential (expired OAuth, revoked key) would
+     * otherwise re-dial its provider on every single one. The definition's
+     * fingerprint is part of the key, so a manual edited after a failure (a
+     * corrected `mcp.json` URL) is tried on the very next request.
      */
     async discoverTools(client, manuals, userId) {
+        const routes = new Map();
+        const unavailable = [];
+        const catalogNames = new Map();
+        for (const m of manuals) {
+            if (m.call_template_type === 'mcp')
+                catalogNames.set(utcpManualName(m), String(m.name));
+        }
+        // The shared layer rewrites every manual name (`[^\w]` → `_`) and tools
+        // route by the rewritten prefix, so two manuals whose names rewrite to one
+        // identifier would silently share it. Sequential registration used to
+        // throw "already registered" for the second; concurrent registration
+        // (below) would let both pass the shared layer's pre-check, one
+        // overwriting the other in the repository while `routes` kept whichever
+        // resolved last — tools/list from one server, tools/call to the other.
+        // Decided here, over the whole list, before anything is registered: every
+        // manual in a colliding group fails with a message naming the others. The
+        // KB manual always keeps its name — a `.tool` colliding with it fails,
+        // the KB manual does not.
+        const byRewrittenName = new Map();
         for (const m of manuals) {
+            const rewritten = utcpManualName(m);
+            byRewrittenName.set(rewritten, [...(byRewrittenName.get(rewritten) ?? []), String(m.name)]);
+        }
+        const outcomes = await Promise.all(manuals.map(async (m) => {
             const isKb = m.name === EXTERNAL_KB_MANUAL_NAME;
             const name = String(m.name);
+            // Both taken before registration, which renames the template in place.
+            const rewritten = utcpManualName(m);
+            const siblings = (byRewrittenName.get(rewritten) ?? []).filter((s) => s !== name);
+            // A collision is a property of the LIST, not of this manual's
+            // definition, so the memo key carries the siblings: the moment one is
+            // renamed away, the key changes and the survivor is tried on the very
+            // next request instead of sitting out the memo's TTL.
+            const memoKey = `${name}${POOL_KEY_SEPARATOR}${templateFingerprint(m)}` +
+                (siblings.length > 0 ? `${POOL_KEY_SEPARATOR}collides:${[...siblings].sort().join(',')}` : '');
             if (!isKb) {
-                const recent = this.manualFailures.recentFailure(userId, name);
+                const recent = this.manualFailures.recentFailure(userId, memoKey);
                 if (recent !== undefined) {
-                    console.warn(`[mcp] skipping manual "${name}" (recent failure, not retried): ${recent}`);
-                    continue;
+                    log.warn(`skipping manual "${name}" (recent failure, not retried): ${recent}`);
+                    return { isKb, ok: true };
                 }
             }
-            // Captured BEFORE the awaited attempt: if a secrets change clears the
-            // memo while registration is in flight, the stale failure from the OLD
-            // credential must not resurrect an entry the clear removed.
-            const generation = this.manualFailures.currentGeneration;
-            // `registerManual` never throws: a discovery/network failure and a
-            // validation failure both come back as `{ ok: false }`, because the retry
-            // policy — this memo — is ours, not the shared layer's.
-            const result = await registerManual(client, m);
-            if (!result.ok) {
-                if (isKb)
-                    throw new Error(`Bevel tool discovery failed: ${result.error}`);
-                this.manualFailures.recordFailure(userId, name, result.error, generation);
-                console.warn(`[mcp] skipping manual "${name}": ${result.error}`);
+            // Begun BEFORE the awaited attempt: if a secrets change (or a
+            // concurrent success of this same manual) clears the memo while
+            // registration is in flight, the stale failure must not resurrect an
+            // entry the clear removed.
+            const generation = this.manualFailures.beginAttempt();
+            try {
+                // Neither path throws: a discovery/network failure and a validation
+                // failure both come back as `{ ok: false }`, because the retry
+                // policy — this memo — is ours, not the shared layer's.
+                const result = !isKb && siblings.length > 0
+                    ? {
+                        ok: false,
+                        error: `manual name "${name}" rewrites to "${rewritten}", the same identifier as ` +
+                            `${siblings.map((s) => `"${s}"`).join(', ')} — rename one; a colliding manual is not registered`,
+                    }
+                    : m.call_template_type === 'mcp'
+                        ? await this.attachDownstream(client, m, userId, routes)
+                        : await registerManual(client, m);
+                if (!result.ok) {
+                    if (isKb)
+                        return { isKb, ok: false, error: result.error };
+                    // A failure the manual may recover from on its own schedule (a
+                    // token refresh that hasn't settled) is reported but NOT
+                    // remembered: the memo's five minutes would outlast the refresh
+                    // policy's one and hold the manual down after the provider is back.
+                    if (!result.retryable)
+                        this.manualFailures.recordFailure(userId, memoKey, result.error, generation);
+                    if (result.signInMissing)
+                        unavailable.push({ utcpName: rewritten });
+                    log.warn(`skipping manual "${name}": ${result.error}`);
+                }
+                else if (!isKb) {
+                    this.manualFailures.clear(userId, memoKey);
+                }
             }
-            else if (!isKb) {
-                this.manualFailures.clear(userId, name);
+            finally {
+                this.manualFailures.endAttempt(generation);
             }
-        }
+            return { isKb, ok: true };
+        }));
+        const kbFailure = outcomes.find((o) => o.isKb && !o.ok);
+        if (kbFailure && !kbFailure.ok)
+            throw new Error(`Bevel tool discovery failed: ${kbFailure.error}`);
+        if (routes.size > 0)
+            routeToDownstream(client, routes);
         const utcpTools = await client.getTools();
-        return utcpTools.map((tool) => flattenManualTool(tool, EXTERNAL_KB_MANUAL_NAME));
+        return {
+            tools: utcpTools.map((tool) => flattenManualTool(tool, EXTERNAL_KB_MANUAL_NAME)),
+            unavailable,
+            catalogNames,
+        };
     }
     /**
-     * Run one tool call through `callToolStreaming` with a one-chunk lookahead:
-     * every chunk except the last becomes a progress notification, the last is
-     * the result. Continuity is the caller's: a tool that supports it (e.g.
-     * `ask`) returns its `sessionId` in the result verbatim, and the caller
-     * echoes it back per the tool's own schema — the proxy never rewrites args.
+     * Make one `mcp` manual's tools part of this request's client, backed by the
+     * pooled connection for (user, manual).
+     *
+     * The pooled client's discovered tools are copied into the request client's
+     * repository — so `tools/list`, `list_tools`/`tools_info` and the TypeScript
+     * interfaces `call_tool_chain` generates all see them exactly as if they had
+     * been registered here — and `routes` records that calls to this manual go to
+     * the pool. The route re-acquires at CALL time rather than holding the pooled
+     * client, so an entry evicted between discovery and the call is transparently
+     * re-created instead of used after its connection was closed. Each use holds
+     * a pool lease only for its own duration, so the pool never closes a
+     * connection an operation is still using.
      */
+    async attachDownstream(client, template, userId, routes) {
+        const key = downstreamPoolKey(userId, template);
+        // The catalog name, which is what the manual's per-user variables are keyed by.
+        const catalogName = String(template.name ?? '');
+        const manualName = utcpManualName(template);
+        const definition = templateFingerprint(template);
+        const acquire = () => this.downstream.acquire(key, () => this.connectDownstream(userId, template));
+        const afterFailure = (err) => this.afterDownstreamFailure(userId, catalogName, key, err);
+        const attach = async (tools) => {
+            await client.config.tool_repository.saveManual({ ...template, name: manualName }, UtcpManualSchema.parse({ tools }));
+            routes.set(manualName, { acquire, afterFailure });
+        };
+        // Set when the handshake failed on a credential the provider may yet
+        // renew: the caller must NOT remember that as a dead manual (see below).
+        let credentialTransient = false;
+        try {
+            let lease;
+            try {
+                lease = await acquire();
+            }
+            catch (err) {
+                // A connection dialed with a token the server refuses fails right here,
+                // at the handshake — the same refresh-and-retry applies.
+                const verdict = await this.classifyDownstreamFailure(userId, catalogName, key, err);
+                if (!verdict.retry) {
+                    credentialTransient = verdict.credentialTransient;
+                    throw verdict.error;
+                }
+                lease = await acquire();
+            }
+            let tools;
+            try {
+                tools = (await lease.value.client.getTools()).filter((t) => t.name.startsWith(`${manualName}.`));
+            }
+            finally {
+                lease.release();
+            }
+            this.knownDownstreamTools.set(catalogName, { definition, tools });
+            await attach(tools);
+            return { ok: true };
+        }
+        catch (err) {
+            const error = err instanceof Error ? err.message : String(err);
+            // No connection because this CALLER has no usable sign-in for the manual
+            // (never signed in, or the grant was just found dead and wiped): the
+            // manual is not broken, the sign-in is. Keep its tools on the surface
+            // from what the downstream last advertised, so a call answers with the
+            // sign-in link — and never remember the failure, since re-authorizing is
+            // one visit to /connect away and the next attempt costs no network.
+            if (await this.signInMissing(userId, catalogName)) {
+                const known = this.knownDownstreamTools.get(catalogName);
+                if (known && known.definition === definition) {
+                    await attach(known.tools);
+                    return { ok: true };
+                }
+                return { ok: false, error, retryable: true, signInMissing: true };
+            }
+            // `retryable` keeps a transient credential failure out of the caller's
+            // five-minute failure memo: the refresh-and-retry policy for a rejected
+            // token is one minute, and a memo entry would silently outlast it.
+            return { ok: false, error, retryable: credentialTransient };
+        }
+    }
+    /** Whether the caller's sign-in for the manual named `catalogName` is missing or broken — a check that must never throw here. */
+    async signInMissing(userId, catalogName) {
+        try {
+            return (await this.missingUserSecrets(userId, catalogName)).length > 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Create one pooled downstream connection: a client registering just this
+     * manual.
+     *
+     * `@utcp/mcp` (1.2.0+) registers its protocol as a FACTORY, so this client
+     * gets an `mcp` protocol instance of its own: the session it opens lives in
+     * that instance, is reachable from no other client, and ends with
+     * `client.close()`. That is what makes a pool entry per (user, server) an
+     * actual isolation boundary — two users with byte-identical server
+     * definitions still never share a connection — with nothing reached into.
+     *
+     * SESSION RECOVERY is installed on the pooled client: a downstream server
+     * that restarts (or expires a session) answers our next call with the spec's
+     * 404/`-32001`, and recovery re-registers in place and retries once. It is
+     * deliberately clear of {@link ManualFailureMemo}: that memo is a circuit
+     * breaker for manuals whose REGISTRATION failed, so a recovery neither
+     * consults it nor records into it.
+     *
+     * A registration that fails closes the client it built (ending whatever the
+     * attempt opened) and throws, so the pool caches nothing and the caller's
+     * memo records the failure.
+     */
+    async connectDownstream(userId, template) {
+        // Third-party manuals are never seeded loopback credentials (see
+        // `buildClient`), so a pooled client carries no request-scoped bearer.
+        const client = await CodeModeUtcpClient.create(process.cwd(), utcpClientConfig(userId, {}));
+        // Our own copy: registration renames the template in place, and recovery
+        // re-registers from exactly what discovery used.
+        const own = structuredClone(template);
+        const manualName = utcpManualName(own);
+        installSessionRecovery(client, { manualTemplate: (name) => (name === manualName ? own : undefined) });
+        const result = await registerManual(client, own);
+        if (!result.ok) {
+            await client.close().catch(() => { });
+            throw new Error(result.error);
+        }
+        return { client };
+    }
+    /**
+     * A pooled manual's operation failed: may it be retried with a refreshed
+     * token? Answers {@link RETRY_WITH_REFRESHED_TOKEN} when so, otherwise the
+     * error the caller should see.
+     *
+     * Only a token rejection (401 / `invalid_token`) qualifies. Then the
+     * caller's OAuth token for this manual is refreshed once, ignoring its
+     * stored expiry, and:
+     *   - refreshed → the pooled connection (dialed with the dead token) is
+     *     dropped and the operation retried once, on a fresh one;
+     *   - rejected → the grant is gone and the vault has wiped it; the caller is
+     *     told to re-authorize on /connect, where it now shows as not connected;
+     *   - transient, or no refresh allowed / possible → the original error.
+     */
+    async afterDownstreamFailure(userId, manualName, poolKey, err) {
+        const verdict = await this.classifyDownstreamFailure(userId, manualName, poolKey, err);
+        return verdict.retry ? RETRY_WITH_REFRESHED_TOKEN : verdict.error;
+    }
+    /** {@link afterDownstreamFailure}, keeping the one distinction its symbol-or-error answer drops. */
+    async classifyDownstreamFailure(userId, manualName, poolKey, err) {
+        if (!isDownstreamTokenRejection(err))
+            return { retry: false, error: err, credentialTransient: false };
+        const outcome = await this.refreshDownstreamToken(userId, manualName);
+        if (outcome === 'refreshed') {
+            // The vault's mutation signal evicts this user's connections too; doing it
+            // here as well keeps the retry correct whether or not that is wired.
+            this.downstream.evictWhere((k) => k === poolKey);
+            return { retry: true };
+        }
+        if (outcome === 'rejected') {
+            // The connection was dialed with a grant that no longer exists; the
+            // vault's mutation signal drops it too, this keeps the next request
+            // honest whether or not that is wired.
+            this.downstream.evictWhere((k) => k === poolKey);
+            return {
+                retry: false,
+                credentialTransient: false,
+                error: new Error(`Your sign-in for "${manualName}" was rejected and has been disconnected. ` +
+                    `Re-authorize it on ${this.opts.publicFrontendUrl}/connect, then run the tool again.`),
+            };
+        }
+        // The token stands and so does the call's own error. Whether the NEXT
+        // call may try again depends on why: a refresh that failed transiently, or
+        // one the window refused, will be worth attempting shortly — while
+        // "nothing here to refresh" (no vault, no OAuth variable, no stored token)
+        // is a standing condition, and the failure memo should hold the manual
+        // down exactly as it does for any other broken credential.
+        const mayRecoverSoon = outcome === 'transient' || outcome === 'guarded';
+        return { retry: false, error: err, credentialTransient: mayRecoverSoon };
+    }
+    /**
+     * Force-refresh the caller's OAuth token(s) for `manualName`, at most once per
+     * (user, manual) per minute. Logs ONE line per attempt — manual, user,
+     * outcome, never token material.
+     *
+     * `'guarded'` when the window refused this one (a refresh just ran, or is
+     * running, for this pair); `undefined` when there was nothing to refresh at
+     * all: no vault wired, or no OAuth variable on the manual. The two are not
+     * the same thing to the caller — see {@link classifyDownstreamFailure}.
+     */
+    async refreshDownstreamToken(userId, manualName) {
+        const vault = this.secretsVault;
+        if (!vault || !this.toolManuals || !manualName)
+            return undefined;
+        let keys;
+        try {
+            keys = (await this.toolManuals.userScopedKeysForManual(manualName)).filter((v) => v.oauth).map((v) => v.key);
+        }
+        catch (err) {
+            // The error's own message is caller-controlled as well (it quotes the
+            // manual, and may quote a provider's reply), and a raw Error handed to
+            // the logger renders its message and stack verbatim — so it goes through
+            // the same escaper rather than travelling as an object.
+            log.warn(`downstream token refresh: could not read the variables of manual=${printable(manualName)}: ` +
+                printable(err instanceof Error ? err.message : String(err)));
+            return undefined;
+        }
+        if (keys.length === 0)
+            return undefined;
+        const attempt = this.tokenRefreshes.run(`${userId}${POOL_KEY_SEPARATOR}${manualName}`, async () => {
+            const outcomes = [];
+            for (const key of keys) {
+                // A vault fault is not a verdict on the grant: keep the token, try later.
+                outcomes.push(await vault.forceRefresh(userId, key).catch(() => 'transient'));
+            }
+            const outcome = outcomes.includes('rejected')
+                ? 'rejected'
+                : outcomes.includes('transient')
+                    ? 'transient'
+                    : outcomes.includes('refreshed')
+                        ? 'refreshed'
+                        : 'skipped';
+            if (outcome !== 'skipped') {
+                // Both values reach the log from outside (a catalog name, an identity
+                // provider's id), so both are escaped: one event stays one line.
+                log.info(`downstream token refresh: manual=${printable(manualName)} user=${printable(userId)} outcome=${outcome}`);
+            }
+            return outcome;
+        });
+        return attempt ? await attempt : 'guarded';
+    }
     /**
      * If the tool declares per-user credentials the caller hasn't set, return a
      * needs-authorization result (naming the tool + a setup link); otherwise null
@@ -426,15 +848,15 @@ export class McpService {
      * services aren't wired, or the tool's manual declares no per-user credential
      * (e.g. the built-in KB tools).
      */
-    async checkUserSecrets(userId, tool) {
-        const missing = await this.missingUserSecrets(userId, tool);
+    async checkUserSecrets(userId, toolName, manualName) {
+        const missing = await this.missingUserSecrets(userId, manualName);
         if (missing.length === 0)
             return null;
         return {
-            result: needsAuthorizationResult(tool.mcpName, missing.map((v) => v.label ?? v.name), `${this.opts.publicFrontendUrl}/connect`),
+            result: needsAuthorizationResult(toolName, missing.map((v) => v.label ?? v.name), `${this.opts.publicFrontendUrl}/connect`),
             // At least one missing item is a sign-in the caller already HAS a row
             // for (dead grant, abandoned consent, or missing scopes) — the state
-            // that warrants resetting an interactive session for re-auth, as
+            // that warrants resetting an interactive client for re-auth, as
             // opposed to a tool the caller never set up at all.
             brokenSignIn: missing.some((v) => v.brokenSignIn),
         };
@@ -442,14 +864,14 @@ export class McpService {
     /**
      * The per-user variables of `tool`'s manual the caller has NOT satisfied.
      * Shared by the call-time needs-authorization check above and the
-     * listing-time filter for connection-key sessions (which registers only
+     * listing-time filter for connection-key callers (which registers only
      * ready tools). Empty when the vault/manual services aren't wired or the
      * manual declares no per-user credential.
      */
-    async missingUserSecrets(userId, tool) {
-        if (!this.secretsVault || !this.toolManuals || !tool.manualName)
+    async missingUserSecrets(userId, manualName) {
+        if (!this.secretsVault || !this.toolManuals || !manualName)
             return [];
-        const userVars = await this.toolManuals.userScopedKeysForManual(tool.manualName);
+        const userVars = await this.toolManuals.userScopedKeysForManual(manualName);
         if (userVars.length === 0)
             return [];
         const status = await this.secretsVault.statusFor(userId, userVars.map((v) => v.key));
@@ -464,6 +886,17 @@ export class McpService {
                 missing.push({ name: v.name, label: v.label, brokenSignIn }); // no row at all → needs a value / sign-in
                 continue;
             }
+            // A row of the OTHER kind is not this credential: a `.tool` edited from
+            // an OAuth sign-in to a plain key (or back) leaves the old row behind,
+            // and serving a token where a key is declared — or a key where a
+            // sign-in is — fails opaquely at the provider. Not a broken sign-in
+            // either: nothing to reset, the user has to set the credential up as
+            // the manual now declares it.
+            const declaredKind = v.oauth ? 'oauth' : 'static';
+            if (st.userKind && st.userKind !== declaredKind) {
+                missing.push({ name: v.name, label: v.label, brokenSignIn: false });
+                continue;
+            }
             // An OAuth-backed var whose row exists but has no token yet is NOT ready —
             // the user has registered but not completed sign-in. Fail closed: anything
             // other than a confirmed `true` (including a non-oauth row → undefined)
@@ -483,6 +916,14 @@ export class McpService {
         }
         return missing;
     }
+    /**
+     * Run one tool call through `callToolStreaming` with a one-chunk lookahead:
+     * every chunk except the last becomes a progress notification — sent on THIS
+     * request's own response stream — and the last is the result. Continuity is
+     * the caller's: a tool that supports it (e.g. `ask`) returns its `sessionId`
+     * in the result verbatim, and the caller echoes it back per the tool's own
+     * schema — the proxy never rewrites args.
+     */
     async dispatch(client, tool, request, 
     // `sendNotification` typed loosely (`any`) so a `notifications/progress`
     // payload without a `progressToken` is accepted — same approach the prior
@@ -500,8 +941,8 @@ export class McpService {
     }
     /**
      * Handle a code-mode meta-tool. The shared implementation reflects on this
-     * session's client, so `list_tools`/`tools_info` describe exactly the catalog
-     * this session discovered and `call_tool_chain` runs in that client's
+     * request's client, so `list_tools`/`tools_info` describe exactly the catalog
+     * this request discovered and `call_tool_chain` runs in that client's
      * isolated-vm — resolving over loopback with the caller's key. The workspace
      * spill store is passed in so an oversized chain result comes back as a
      * `read_file`-able ref rather than a wall of JSON.
@@ -510,6 +951,119 @@ export class McpService {
         return dispatchMetaTool(client, name, args, this.opts.spillStore);
     }
 }
+/**
+ * The UTCP client config for `userId`: the given variables, plus the per-user
+ * `bevel-secrets` loader that resolves every `${SECRET}` ref lazily. Shared by
+ * request clients and pooled downstream clients, so both resolve a manual's
+ * variables through exactly the same tiers.
+ */
+function utcpClientConfig(userId, variables) {
+    return new UtcpClientConfigSerializer().validateDict({
+        variables,
+        load_variables_from: [bevelSecretsLoaderConfig(userId)],
+    });
+}
+/**
+ * The name a manual is registered under. `UtcpClient.registerManual` rewrites
+ * every non-word character to `_`, and tool names are prefixed with the result,
+ * so routing has to key on the same rewrite.
+ */
+function utcpManualName(template) {
+    return String(template.name ?? '').replace(/[^\w]/g, '_');
+}
+/**
+ * The pool key for (user, manual). The template's fingerprint is part of it, so
+ * an edited `mcp.json` (new URL, new headers) gets a new connection rather than
+ * the one dialed for the old definition, which simply idles out. Hashed: the
+ * template can carry credentials and the key must stay log-safe.
+ */
+function downstreamPoolKey(userId, template) {
+    return [userId, utcpManualName(template), templateFingerprint(template)].join(POOL_KEY_SEPARATOR);
+}
+/** A short, log-safe hash of a manual's whole definition: changes whenever the definition does. */
+function templateFingerprint(template) {
+    return createHash('sha256').update(JSON.stringify(template)).digest('hex').slice(0, 16);
+}
+/**
+ * Route tool calls for pooled manuals to their pooled client, in place on the
+ * request client. Both entry points are wrapped — `callToolStreaming` is the
+ * MCP dispatch path, `callTool` is what `call_tool_chain` bridges every
+ * in-isolate tool function to — so the two can never disagree. Every other
+ * manual's calls go through the request client unchanged.
+ *
+ * Each routed call holds its pool lease until the call ends — for a stream,
+ * until the consumer finishes or abandons it (`for await` returns the
+ * generator, which runs the `finally`).
+ *
+ * A call the downstream refuses for its token (401 / `invalid_token`) goes to
+ * the route's `afterFailure`, which may refresh the token and ask for ONE retry
+ * on a fresh connection. Retrying is safe for the same reason session recovery
+ * is: authentication is decided before the request reaches a tool, so the
+ * refused attempt ran nothing.
+ */
+function routeToDownstream(client, routes) {
+    const callTool = client.callTool.bind(client);
+    const callToolStreaming = client.callToolStreaming.bind(client);
+    const routeOf = (toolName) => routes.get(toolName.split('.')[0] ?? '');
+    client.callTool = async function routedCallTool(toolName, toolArgs) {
+        const route = routeOf(toolName);
+        if (!route)
+            return callTool(toolName, toolArgs);
+        const once = async () => {
+            const lease = await route.acquire();
+            try {
+                return await lease.value.client.callTool(toolName, toolArgs);
+            }
+            finally {
+                lease.release();
+            }
+        };
+        try {
+            return await once();
+        }
+        catch (err) {
+            const next = await route.afterFailure(err);
+            if (next !== RETRY_WITH_REFRESHED_TOKEN)
+                throw next;
+            // Exactly one retry: whatever it produces is what the caller sees.
+            return await once();
+        }
+    };
+    client.callToolStreaming = async function* routedCallToolStreaming(toolName, toolArgs) {
+        const route = routeOf(toolName);
+        if (!route) {
+            yield* callToolStreaming(toolName, toolArgs);
+            return;
+        }
+        const once = async function* () {
+            const lease = await route.acquire();
+            try {
+                yield* lease.value.client.callToolStreaming(toolName, toolArgs);
+            }
+            finally {
+                lease.release();
+            }
+        };
+        let yielded = false;
+        try {
+            for await (const chunk of once()) {
+                yielded = true;
+                yield chunk;
+            }
+            return;
+        }
+        catch (err) {
+            // A stream that already produced output was accepted — a rejection can
+            // only come before the first chunk, and replaying would duplicate output.
+            if (yielded)
+                throw err;
+            const next = await route.afterFailure(err);
+            if (next !== RETRY_WITH_REFRESHED_TOKEN)
+                throw next;
+        }
+        yield* once();
+    };
+}
 /**
  * The pieces of the proxy that are shared with the local MCP server now live in
  * `@bevel-software/platform-mcp-core`. Re-exported here because this module is