@bevel-software/platform-core-backend 0.30.0 → 0.31.0

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

@@ -12,12 +12,15 @@ import { bevelSecretsLoaderConfig } from '../secrets-vault/index.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 { RequestAudit } from '../audit/request-audit.js';
+import { RequestAudit } from '../audit/index.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 { ToolSchemaGuard } from './tool-schema-guard.js';
 import { DownstreamRefreshGuard, isDownstreamTokenRejection } from './downstream-token-refresh.js';
+import { SurfaceCache } from './surface-cache.js';
+import { SharedDefinitions } from './shared-definitions.js';
+import { currentRequest, runInRequest } from './request-context.js';
 import { printable } from '../../shared/printable.js';
 import { composeAgentInstructions, prefixToolDescription, PREFIXED_TOOLS, } from '../agent-instructions/index.js';
 import { guideFirstDescription } from '../tool-registry/guide-first.js';
@@ -40,26 +43,54 @@ const LOOPBACK_TIMEOUT_MS = 15_000;
  */
 export const MCP_LOOPBACK_TOKEN_TTL_MS = 5 * 60 * 60 * 1000;
 const callTemplateSerializer = new CallTemplateSerializer();
+/**
+ * How long a surface missing a manual that failed is kept (see
+ * {@link RequestSurface.degraded}): the refresh policy's window, so the
+ * manual is retried as soon as a refresh may have settled.
+ */
+const DEGRADED_SURFACE_MAX_AGE_MS = 60_000;
+/**
+ * What the platform-hosted manuals' `${CONNECTION_KEY}` is seeded with when a
+ * cached client is built. Never sent anywhere: the variable is replaced by a
+ * getter that reads the bearer of the request a call belongs to (see
+ * {@link bindRequestBearer}).
+ */
+const REQUEST_BEARER_PLACEHOLDER = 'request-bearer';
 /** 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, 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
+ * uses the caller's `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), every tool
+ * discovered — 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.
+ * The client is built once per person, caller kind, key scope and catalog
+ * revision, and reused until one of those changes (see {@link SurfaceCache}):
+ * the revision is the fingerprint `hexis-mcp` already polls, so a `.tool`
+ * added, edited or put out of the caller's reach is a new revision and a new
+ * build, while a note saved anywhere is not. A secret changing evicts the
+ * person's clients (a shared one, everyone's). Building cost a full catalog
+ * fetch and discovery per request, which on a slow knowledge base was the
+ * difference between an answer and a client's discovery timeout.
  *
- * 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.
+ * A cached client carries no request's bearer. Each request brings its own,
+ * through the request context (see `request-context.ts`): the
+ * platform-hosted manuals read it at call time, so a connection key's metering
+ * and audit stay its own, a revoked key fails on its next request while the
+ * person's client stays warm for their other key, and a token minted for one
+ * request never has to outlive it. The cache holds references and nothing the
+ * process could not rebuild, so a restart between two requests is still
+ * undetectable by the client: the first request after it rebuilds.
+ *
+ * Tool definitions are held once for every client that discovered the same
+ * ones (see {@link SharedDefinitions}), so hundreds of warm clients of one
+ * catalog cost one catalog's worth of schemas and descriptions.
  *
  * The one exception to "nothing between requests" is proxied third-party MCP
  * servers (`mcp` manuals): those are session-ful by nature, so their
@@ -118,6 +149,10 @@ export class McpService {
     toolSchemas = new ToolSchemaGuard();
     // The downstream connection pool for `mcp` manuals — see the class doc.
     downstream;
+    // Built surfaces, per caller and catalog revision — see the class doc.
+    surfaces;
+    // Tool definitions shared by every surface that discovered the same ones.
+    definitions = new SharedDefinitions();
     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
@@ -164,25 +199,31 @@ export class McpService {
         });
         // Paced on the pool's clock, so a test that moves one moves both.
         this.tokenRefreshes = new DownstreamRefreshGuard(undefined, opts.downstreamPool?.now);
+        this.surfaces = new SurfaceCache(opts.surfaceCache);
     }
     /**
      * 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.
+     * Three things were built from the old value: remembered manual failures (so
+     * a just-repaired credential is retried on the very next request), pooled
+     * downstream connections (dialed and discovered with the old credential),
+     * and cached surfaces (whose tools, and whose list of manuals waiting on a
+     * sign-in, were decided with it). All are dropped; the next request
+     * rebuilds whatever it needs.
      */
     onSecretsChanged(userId) {
         this.forgetStaleRefreshWindows(userId);
         if (userId === null) {
             this.manualFailures.clearAll();
             this.downstream.closeAll();
+            this.surfaces.clear();
             return;
         }
         this.manualFailures.clearUser(userId);
-        this.downstream.evictWhere((key) => key.startsWith(`${userId}${POOL_KEY_SEPARATOR}`));
+        const mine = (key) => key.startsWith(`${userId}${POOL_KEY_SEPARATOR}`);
+        this.downstream.evictWhere(mine);
+        this.surfaces.evictWhere(mine);
     }
     /**
      * A credential changed, so a refresh window that FAILED to produce one no
@@ -208,12 +249,14 @@ export class McpService {
      * 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.
+     * surface is looked up on the first handler that needs it — the caller's
+     * cached one, or a fresh build — and shared by every message of the request
+     * (a JSON-RPC batch).
      */
     async createRequestServer(caller, messages) {
         const { userId, tokenId, bearer } = caller;
         const connectionId = caller.connectionId ?? null;
+        const page = caller.page ?? null;
         // The loopback surface (`/api/agent/*`) accepts connection keys and
         // 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
@@ -228,11 +271,17 @@ export class McpService {
         let instructions;
         const agentInstructions = () => (instructions ??= this.composeAgentInstructions());
         // The Audit log's view of this request — only when the request can be
-        // attributed to a key or an agent connection. The catalog names it
-        // classifies pooled tools by are the surface's, which is built lazily
-        // below, so it reads them through a holder the surface fills in.
+        // attributed to a key, an agent connection or a page. The catalog names
+        // it classifies pooled tools by are the surface's, which is looked up
+        // lazily below, so it reads them through a holder the surface fills in.
         const catalogNamesHolder = { current: new Map() };
-        const principal = tokenId != null ? { kind: 'key', id: tokenId } : connectionId ? { kind: 'agent', id: connectionId } : null;
+        const principal = tokenId != null
+            ? { kind: 'key', id: tokenId }
+            : connectionId
+                ? { kind: 'agent', id: connectionId }
+                : page
+                    ? { kind: 'page', path: page }
+                    : null;
         const audit = this.auditRecorder && principal
             ? new RequestAudit(this.auditRecorder, userId, principal, {
                 kbManualName: EXTERNAL_KB_MANUAL_NAME,
@@ -240,11 +289,15 @@ export class McpService {
                 loadSkills: () => this.fetchSkillList(loopbackBearer).then((skills) => skills.flatMap((s) => (s.path ? [{ name: s.name, path: s.path }] : []))),
             })
             : null;
+        // What this request brings to a client it shares with the person's other
+        // requests: its own loopback bearer and its own audit. Every handler that
+        // reaches the client runs inside it.
+        const ctx = { loopbackBearer, audit };
+        const inRequest = (fn) => runInRequest(ctx, fn);
         let surface;
-        const requestSurface = () => (surface ??= this.buildSurface(userId, tokenId, loopbackBearer).then((built) => {
-            catalogNamesHolder.current = built.catalogNames;
-            audit?.instrumentChainCalls(built.client);
-            return built;
+        const requestSurface = () => (surface ??= inRequest(() => this.surfaceFor(caller, loopbackBearer)).then((found) => {
+            catalogNamesHolder.current = found.catalogNames;
+            return found;
         }));
         const initializing = (Array.isArray(messages) ? messages : [messages]).some((m) => isInitializeRequest(m));
         // The deployment's MCP Apps, read once per request. Declaring the
@@ -267,7 +320,7 @@ export class McpService {
             // place the text in the model's system prompt without the model acting.
             ...(initializing ? { instructions: (await agentInstructions()).instructions } : {}),
         });
-        server.setRequestHandler(ListToolsRequestSchema, async () => {
+        server.setRequestHandler(ListToolsRequestSchema, async () => inRequest(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
@@ -360,7 +413,7 @@ export class McpService {
                 // Code-mode meta-tools first, then every validated direct tool.
                 tools: [...metaTools, ...direct],
             };
-        });
+        }));
         // The MCP App views. Registered only when this deployment serves one, so
         // the handlers and the declared capability agree.
         if (servesApps && apps) {
@@ -376,8 +429,12 @@ export class McpService {
                 return toReadResourceResult(resource);
             });
         }
-        server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
-            const { client, tools, unavailable, catalogNames, hidden: hiddenTools } = await requestSurface();
+        server.setRequestHandler(CallToolRequestSchema, async (request, extra) => inRequest(async () => {
+            const { client: shared, tools, unavailable, catalogNames, hidden: hiddenTools } = await requestSurface();
+            // The person's client, as this request uses it: every call it makes —
+            // a chain's too, which comes back from the isolate outside any async
+            // context — carries this request's bearer and audit.
+            const client = requestView(shared, ctx);
             const toolName = request.params.name;
             const args = request.params.arguments ?? {};
             if (META_TOOL_NAMES.has(toolName)) {
@@ -462,7 +519,7 @@ export class McpService {
             const structured = apps !== null && Object.hasOwn(apps.tools, proxied.mcpName);
             const run = () => this.dispatch(client, proxied, request, extra, structured);
             return audit ? audit.call(proxied.utcpName, args, run, isErrorResult) : run();
-        });
+        }));
         // 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
@@ -493,22 +550,116 @@ export class McpService {
         return server;
     }
     /**
-     * The request's tool surface: catalog over loopback, a fresh UTCP client,
-     * every manual registered (pooled for `mcp` ones), tools flattened.
+     * Record that the person viewing `page` refused it a call: the page asked to
+     * write, the app asked them, and they answered Deny. Nothing ran, so the
+     * call never reached this server as a `tools/call`; the app reports it here
+     * so the Audit log shows the page's attempt beside its allowed calls.
      *
-     * 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.
+     * The tool is named the way the page named it (its MCP name) and recorded
+     * the way that call would have been: through the person's surface, which
+     * the page's earlier calls have normally left warm.
      */
-    async buildSurface(userId, tokenId, loopbackBearer) {
+    async recordPageRefusal(caller, page, toolName, args) {
+        if (!this.auditRecorder)
+            return;
+        const { userId } = caller;
+        const loopbackBearer = this.internalTokens
+            ? this.internalTokens.mint({ userId, externalProxy: true }, MCP_LOOPBACK_TOKEN_TTL_MS)
+            : caller.bearer;
+        let catalogNames = new Map();
+        const audit = new RequestAudit(this.auditRecorder, userId, { kind: 'page', path: page }, {
+            kbManualName: EXTERNAL_KB_MANUAL_NAME,
+            catalogNames: () => catalogNames,
+            loadSkills: () => this.fetchSkillList(loopbackBearer).then((skills) => skills.flatMap((s) => (s.path ? [{ name: s.name, path: s.path }] : []))),
+        });
+        const ctx = { loopbackBearer, audit };
+        await runInRequest(ctx, async () => {
+            let utcpName = toolName;
+            if (!META_TOOL_NAMES.has(toolName)) {
+                const surface = await this.surfaceFor({ ...caller, tokenId: null }, loopbackBearer);
+                catalogNames = surface.catalogNames;
+                utcpName =
+                    surface.tools.find((t) => t.mcpName === toolName)?.utcpName ?? surface.hidden.get(toolName)?.utcpName ?? toolName;
+            }
+            await audit.denied(utcpName, args, 'refused');
+        });
+    }
+    /**
+     * The caller's tool surface: the one cached for their catalog revision, or
+     * a fresh build that is then cached.
+     *
+     * The key is the person, the kind of caller (a connection key, or a person
+     * through OAuth or their session — the latter two reach the same loopback
+     * identity), the credential's scope, and the catalog revision. The revision
+     * is asked for on every request, with the request's own bearer, so it is
+     * the caller's CURRENT catalog that picks the surface: a manual released,
+     * edited or put out of their reach moves it, and the request builds anew.
+     *
+     * When the revision cannot be read the request builds a surface of its own
+     * and keeps it to itself — the per-request behaviour this replaced, never a
+     * surface it cannot tell is current.
+     */
+    async surfaceFor(caller, loopbackBearer) {
+        const { userId, tokenId } = caller;
+        const revision = await this.fetchCatalogRevision(loopbackBearer);
+        if (revision === null)
+            return this.buildSurface(userId, tokenId, loopbackBearer, 'uncached');
+        const key = [userId, tokenId != null ? 'key' : 'person', caller.scope ?? 'write', revision].join(POOL_KEY_SEPARATOR);
+        const { value } = await this.surfaces.get(key, () => this.buildSurface(userId, tokenId, loopbackBearer, 'miss'), (built) => (built.degraded ? DEGRADED_SURFACE_MAX_AGE_MS : undefined));
+        return value;
+    }
+    /**
+     * The caller's catalog revision (`GET /api/agent/catalog-revision`, the one
+     * `hexis-mcp` polls), read with their bearer; null when it cannot be read.
+     * A deployment or a test that does not serve the route answers 404, which
+     * is not worth a line in the log; anything else is.
+     */
+    async fetchCatalogRevision(bearer) {
+        try {
+            const res = await fetch(`${this.opts.loopbackBaseUrl}/api/agent/catalog-revision`, {
+                headers: { Authorization: `Bearer ${bearer}` },
+                signal: AbortSignal.timeout(LOOPBACK_TIMEOUT_MS),
+            });
+            if (!res.ok) {
+                if (res.status !== 404)
+                    log.warn(`catalog-revision loopback failed: HTTP ${res.status}; building this request's surface uncached`);
+                return null;
+            }
+            const body = (await res.json());
+            return typeof body.revision === 'string' && body.revision ? body.revision : null;
+        }
+        catch (err) {
+            log.warn("catalog-revision loopback threw; building this request's surface uncached:", { err });
+            return null;
+        }
+    }
+    /**
+     * Build a tool surface: catalog over loopback, a UTCP client, every manual
+     * registered (pooled for `mcp` ones), tools flattened, definitions shared.
+     *
+     * Runs inside the request that asked for it, whose bearer the knowledge
+     * base's discovery reads; the client it builds keeps none of it.
+     *
+     * Logs one line with the time each half took and whether it was a cache
+     * miss, so a build is measured rather than assumed, and a log that shows
+     * one line for two requests shows the second was served warm.
+     */
+    async buildSurface(userId, tokenId, loopbackBearer, cache) {
         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, hidden } = await this.discoverTools(client, manuals, userId);
+        const client = await this.buildClient(userId, manuals);
+        const discovered = await this.discoverTools(client, manuals, userId);
+        // After discovery, which renames each template in place to the name it
+        // registered under: that is the name the repository keys it by.
+        const rawTemplates = new Map(manuals.map((m) => [utcpManualName(m), m]));
+        await this.definitions.share(client, rawTemplates);
+        // Chain calls are audited per request, by whichever request makes them.
+        RequestAudit.instrumentChainCalls(client, () => currentRequest()?.audit);
+        const tools = this.definitions.listing(discovered.tools);
         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.
@@ -517,12 +668,12 @@ export class McpService {
             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'} — ` +
+            `request surface: user=${printable(userId)} tokenId=${tokenId ? printable(tokenId) : 'none'} cache=${cache} — ` +
                 `${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, hidden };
+        return { ...discovered, client, tools };
     }
     /**
      * The instructions and tool prefix. A reader failure (a disk fault; ENOENT
@@ -635,7 +786,7 @@ export class McpService {
         });
     }
     /**
-     * One `CodeModeUtcpClient` per request. Reserved `API_URL`/`CONNECTION_KEY` are
+     * One `CodeModeUtcpClient` per surface. 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
@@ -643,13 +794,20 @@ export class McpService {
      * 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.
+     * `CONNECTION_KEY` is seeded as a placeholder and bound to the request
+     * context (see {@link bindRequestBearer}): the client is shared by the
+     * person's requests, and each call carries the bearer of the request it
+     * belongs to.
+     *
+     * Not `close()`d: a 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) {
-        const variables = seedBevelHostedManualVars(manuals, this.opts.loopbackBaseUrl, bearer);
-        return CodeModeUtcpClient.create(process.cwd(), utcpClientConfig(userId, variables, this.opts.secretsScope));
+    async buildClient(userId, manuals) {
+        const variables = seedBevelHostedManualVars(manuals, this.opts.loopbackBaseUrl, REQUEST_BEARER_PLACEHOLDER);
+        const client = await CodeModeUtcpClient.create(process.cwd(), utcpClientConfig(userId, variables, this.opts.secretsScope));
+        bindRequestBearer(client);
+        return client;
     }
     /**
      * Register EVERY manual for this request, then flatten each discovered tool
@@ -663,14 +821,16 @@ export class McpService {
      * 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
+     * {@link ManualFailureMemo}): a surface is rebuilt when its catalog
+     * revision or the caller's secrets change (see {@link RequestSurface.degraded}), 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();
+        // A manual left off this surface for a failure (see RequestSurface.degraded).
+        let degraded = false;
         const unavailable = [];
         // Taken BEFORE a single manual is registered, so it ranks this load by the
         // freshness of what it is about to read — see ToolSchemaGuard.beginLoad.
@@ -761,6 +921,8 @@ export class McpService {
                         this.manualFailures.recordFailure(userId, memoKey, result.error, generation);
                     if (result.signInMissing)
                         unavailable.push({ utcpName: rewritten });
+                    else if (result.retryable)
+                        degraded = true;
                     log.warn(`skipping manual "${name}": ${result.error}`);
                 }
                 else if (!isKb) {
@@ -780,7 +942,7 @@ export class McpService {
         const utcpTools = await client.getTools();
         const flattened = utcpTools.map((tool) => flattenManualTool(tool, EXTERNAL_KB_MANUAL_NAME));
         const { tools, hidden } = await this.hideInvalidSchemas(client, flattened, manualCatalogNames, userId, loadId);
-        return { tools, unavailable, catalogNames, hidden };
+        return { tools, unavailable, catalogNames, hidden, degraded };
     }
     /**
      * Check the input schema of every tool the servers just advertised, and take
@@ -1290,6 +1452,51 @@ function routeToDownstream(client, routes) {
         yield* once();
     };
 }
+/**
+ * The person's shared client as ONE request uses it: a view whose `callTool`
+ * runs inside that request's context, and which is otherwise the client
+ * itself (the prototype), so its repository, protocols and routing are the
+ * shared ones.
+ *
+ * `callTool` is the entry `call_tool_chain` bridges every in-isolate tool
+ * call to, and those calls come back from isolated-vm's callback queue with
+ * no async context of their own: without the view they would run as no
+ * request at all, with no bearer and no audit. The direct path
+ * (`callToolStreaming`) runs in the request's handler and needs nothing
+ * more.
+ */
+function requestView(client, ctx) {
+    const view = Object.create(client);
+    view.callTool = (toolName, toolArgs) => runInRequest(ctx, () => client.callTool(toolName, toolArgs));
+    return view;
+}
+/**
+ * Make every platform-hosted manual's `${CONNECTION_KEY}` the bearer of the
+ * request a call belongs to.
+ *
+ * The UTCP client substitutes a tool's `${VAR}`s each time the tool is
+ * called, from `config.variables` first — so a getter there is read at call
+ * time, never at build time. A call outside any request has no bearer to
+ * send, and is refused here rather than sent with the placeholder.
+ */
+function bindRequestBearer(client) {
+    const variables = client.config.variables ?? {};
+    for (const [key, value] of Object.entries(variables)) {
+        if (!key.endsWith('_CONNECTION_KEY') || value !== REQUEST_BEARER_PLACEHOLDER)
+            continue;
+        Object.defineProperty(variables, key, {
+            enumerable: true,
+            configurable: false,
+            get: () => {
+                const request = currentRequest();
+                if (!request)
+                    throw new Error('A platform tool was called outside an MCP request, so there is no bearer to call it with.');
+                return request.loopbackBearer;
+            },
+        });
+    }
+    client.config.variables = variables;
+}
 /**
  * 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