@bevel-software/platform-core-backend 0.1.0

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

@@ -0,0 +1,840 @@
+import { randomUUID } from 'node:crypto';
+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 '@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 { CodeModeUtcpClient } from '@utcp/code-mode';
+import { utcpNameToTsInterfaceName, findToolByName } from '../code-mode/code-mode-names.js';
+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';
+/** Default cap on a `call_tool_chain` result's stringified size before it spills. */
+const CALL_TOOL_CHAIN_MAX_OUTPUT = 200_000;
+/**
+ * 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.
+ */
+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.
+ */
+const MCP_LOOPBACK_TOKEN_TTL_MS = 5 * 60 * 60 * 1000;
+const callTemplateSerializer = new CallTemplateSerializer();
+/**
+ * Code-mode meta-tools exposed ALONGSIDE the direct tools. They let an external
+ * agent batch many Bevel calls into one isolated-vm run (`call_tool_chain`)
+ * instead of one MCP round-trip per call — the same efficiency our own agent
+ * gets. `call_tool_chain`'s description carries the code-mode protocol (there is
+ * no system prompt over MCP), so the client learns the convention from the tool
+ * itself; `list_tools`/`tools_info` are how it discovers what to call.
+ *
+ * Security is identical to the direct surface: the chain runs in our isolated-vm
+ * but calls tools over loopback with the CALLER's key against the external
+ * catalog — internal-only tools aren't in that catalog, so a chain can't reach
+ * them either.
+ */
+const CALL_TOOL_CHAIN_DESCRIPTION = [
+    'Execute a short JavaScript program with direct access to every registered UTCP tool as a synchronous function. Call tools as `KNOWLEDGE_BASE.<tool>({ body: { ...args } })` with NO `await` (results are already resolved), and `return` the final value. The runtime is plain JavaScript (no type annotations / no TypeScript-only syntax).',
+    'Discover first: `list_tools` lists every tool in callable form (e.g. `KNOWLEDGE_BASE.read_file`); `tools_info` returns their exact argument + return shapes — do not guess. Batch multiple tool calls into one chain to avoid a round-trip per call. The chain runs with your own connection key, so it can only reach the tools you can already call directly.',
+    'Large results: if the combined result+logs exceed `max_output_size` (default 200000 chars) the full JSON is spilled to a shared store and you get back a `__tool_chain_spill__/…` ref instead. Read it with `read_file` (pass that ref as `path` — `branch` is ignored — plus `offset`/`limit` to slice it), or better, re-run a narrower chain that returns only what you need.',
+].join('\n\n');
+const CODE_MODE_META_TOOLS = [
+    {
+        name: 'list_tools',
+        description: 'List every UTCP tool currently registered, in TypeScript-accessible form (e.g. `KNOWLEDGE_BASE.read_file`) for use inside `call_tool_chain`.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    },
+    {
+        name: 'tools_info',
+        description: 'Get full TypeScript interface definitions for named tools (names from `list_tools`). The schemas are the source of truth — do not guess shapes.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                tool_names: { type: 'array', items: { type: 'string' }, minItems: 1, description: 'Tool names to describe.' },
+            },
+            required: ['tool_names'],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: 'call_tool_chain',
+        description: CALL_TOOL_CHAIN_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                code: { type: 'string', minLength: 1, description: 'JavaScript to execute against the registered tools.' },
+                timeout: { type: 'integer', minimum: 1000, maximum: 120000, description: 'Timeout in ms (default 30000).' },
+                max_output_size: { type: 'integer', minimum: 1000, maximum: 1000000, description: 'Max result+logs size in chars before spilling (default 200000, max 1000000).' },
+            },
+            required: ['code'],
+            additionalProperties: false,
+        },
+    },
+];
+const META_TOOL_NAMES = new Set(CODE_MODE_META_TOOLS.map((t) => t.name));
+/** The prompt message text for a loaded skill: its instructions body + a pointer to bundled files. */
+function skillPromptText(skill) {
+    const rel = skill.files.map((f) => f.startsWith(`${skill.path}/`) ? f.slice(skill.path.length + 1) : f);
+    const footer = rel.length
+        ? `\n\n---\nSkill folder: ${skill.path}\nBundled files (fetch each with the get_skill tool: { name: "${skill.name}", file }): ${rel.join(', ')}`
+        : '';
+    return `${skill.body}${footer}`;
+}
+/**
+ * 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,
+ * thread continuity, and per-key token metering all live ONCE behind that REST
+ * endpoint (`AgentAskService` for `ask`), never duplicated here.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export class McpService {
+    sessionStore;
+    opts;
+    secretsVault;
+    toolManuals;
+    internalTokens;
+    revokeOAuthAccess;
+    constructor(sessionStore, 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
+    // 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
+    // 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;
+    }
+    /**
+     * Subscribe to store-driven evictions (idle-TTL sweep, size-cap eviction) so
+     * the route layer can drop its transport mirror. Returns an unsubscribe fn.
+     */
+    onSessionEvicted(listener) {
+        return this.sessionStore.onEvict(listener);
+    }
+    /**
+     * 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)`.
+     */
+    async createSession(userId, tokenId, bearer, onSessionInitialized) {
+        // 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
+        // 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.
+        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);
+        // 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);
+            },
+        });
+        const server = new Server({ name: 'bevel-mcp', version: '0.1.0' }, { capabilities: { tools: {}, prompts: {} } });
+        server.setRequestHandler(ListToolsRequestSchema, async () => {
+            // 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
+            // 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
+            // /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 = listed.filter((_, i) => ready[i]);
+            }
+            // Validate + dedupe each discovered tool so ONE non-conforming or
+            // duplicate-named entry can't make an MCP client reject the whole
+            // `tools/list` (blanking every tool). Every drop is logged with a reason
+            // so a missing tool is diagnosable instead of silent.
+            const seen = new Set(META_TOOL_NAMES);
+            const dropped = [];
+            const direct = [];
+            for (const t of listed) {
+                const entry = toListedTool(t); // logs its own reason on a name/schema drop
+                if (!entry) {
+                    dropped.push(t.mcpName);
+                    continue;
+                }
+                if (seen.has(entry.name)) {
+                    dropped.push(`${entry.name} (duplicate)`);
+                    continue;
+                }
+                seen.add(entry.name);
+                direct.push(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.
+            if (dropped.length) {
+                console.warn(`[mcp] tools/list: serving ${CODE_MODE_META_TOOLS.length + direct.length} tool(s); ` +
+                    `dropped ${dropped.length} non-listable: ${dropped.join(', ')}`);
+            }
+            return {
+                // Code-mode meta-tools first, then every validated direct tool.
+                tools: [...CODE_MODE_META_TOOLS, ...direct],
+            };
+        });
+        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 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) {
+                // A sign-in that EXISTS but is broken (expired grant, abandoned
+                // consent, missing scopes) on an interactive OAuth session: 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
+                // 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);
+                    }
+                }
+                return needsAuth.result;
+            }
+            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.
+        server.setRequestHandler(ListPromptsRequestSchema, async () => {
+            const skills = await this.fetchSkillList(loopbackBearer);
+            const prompts = skills.map((s) => ({
+                name: s.name,
+                description: s.description,
+                arguments: [],
+            }));
+            return { prompts };
+        });
+        server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+            const skill = await this.fetchSkill(loopbackBearer, request.params.name);
+            if (!skill) {
+                throw new McpError(ErrorCode.InvalidParams, `Unknown skill "${request.params.name}".`);
+            }
+            return {
+                description: skill.description,
+                messages: [{ role: 'user', content: { type: 'text', text: skillPromptText(skill) } }],
+            };
+        });
+        return { transport, server };
+    }
+    /** Loopback GET of the default-branch skill catalog (via the `list_skills` tool). */
+    async fetchSkillList(bearer) {
+        const res = await this.loopbackTool(bearer, 'list_skills', {});
+        const skills = res?.skills;
+        return Array.isArray(skills) ? skills : [];
+    }
+    /** Loopback GET of one skill's body (via the `get_skill` tool); null if unavailable. */
+    async fetchSkill(bearer, name) {
+        const res = (await this.loopbackTool(bearer, 'get_skill', { name }));
+        if (res?.ok && res.kind === 'skill' && res.skill)
+            return res.skill;
+        return null;
+    }
+    /**
+     * 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.
+     */
+    async loopbackJson(bearer, path, label, json) {
+        try {
+            const res = await fetch(`${this.opts.loopbackBaseUrl}${path}`, {
+                headers: {
+                    Authorization: `Bearer ${bearer}`,
+                    ...(json !== undefined ? { 'Content-Type': 'application/json' } : {}),
+                },
+                ...(json !== undefined ? { method: 'POST', body: JSON.stringify(json) } : {}),
+                signal: AbortSignal.timeout(LOOPBACK_TIMEOUT_MS),
+            });
+            if (!res.ok) {
+                console.error(`[mcp] ${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);
+            return null;
+        }
+    }
+    /** POST a skill tool endpoint over loopback with the caller's bearer; parsed JSON or null. */
+    async loopbackTool(bearer, tool, body) {
+        return this.loopbackJson(bearer, `/api/agent/tools/${tool}`, `skill ${tool}`, body);
+    }
+    /**
+     * Loopback GET of the caller's manual list (KB + accessible `.tool` manuals),
+     * 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
+     * received JSON even though the producing endpoint already validated it.
+     */
+    async fetchManualTemplates(bearer) {
+        // This is the REMOTE proxy, so ask for remote-capable manuals only — local-only
+        // `.tool`s are surfaced instead via the `list_local_tools` tool in the KB manual.
+        const body = (await this.loopbackJson(bearer, '/api/agent/all-tools?remote=true', 'all-tools'));
+        const rawManuals = Array.isArray(body?.manuals) ? body.manuals : [];
+        const out = [];
+        let hasKb = false;
+        for (const raw of rawManuals) {
+            const isKb = raw?.name === EXTERNAL_KB_MANUAL_NAME;
+            try {
+                out.push(callTemplateSerializer.validateDict(raw));
+                if (isKb)
+                    hasKb = true;
+            }
+            catch (err) {
+                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)}`);
+            }
+        }
+        // Always include the KB manual, even if `all-tools` was unavailable/regressed.
+        if (!hasKb)
+            out.unshift(this.kbManualTemplate());
+        return out;
+    }
+    /** The KB manual's discovery template — the fallback if `all-tools` is unavailable. */
+    kbManualTemplate() {
+        return callTemplateSerializer.validateDict({
+            name: EXTERNAL_KB_MANUAL_NAME,
+            call_template_type: 'http',
+            http_method: 'GET',
+            url: '${API_URL}/api/agent/utcp',
+            content_type: 'application/json',
+            headers: { Authorization: 'Bearer ${CONNECTION_KEY}' },
+        });
+    }
+    /**
+     * One `CodeModeUtcpClient` per session. 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.
+     */
+    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);
+    }
+    /**
+     * 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).
+     */
+    async discoverTools(client, manuals) {
+        for (const m of manuals) {
+            const isKb = m.name === EXTERNAL_KB_MANUAL_NAME;
+            try {
+                const result = await client.registerManual(m);
+                if (result && result.success === false) {
+                    const errs = Array.isArray(result.errors) ? result.errors.join('; ') : 'unknown error';
+                    if (isKb)
+                        throw new Error(`Bevel tool discovery failed: ${errs}`);
+                    console.warn(`[mcp] skipping manual "${String(m.name)}": ${errs}`);
+                }
+            }
+            catch (err) {
+                // Registration (network/discovery) failure — the templates are already
+                // validated, so this is a runtime, not a schema, problem.
+                if (isKb)
+                    throw err;
+                console.warn(`[mcp] skipping manual "${String(m.name)}": ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        const utcpTools = await client.getTools();
+        return utcpTools.map((tool) => flattenManualTool(tool));
+    }
+    /**
+     * 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.
+     */
+    /**
+     * 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
+     * to proceed. Reads the manual's `user`-scoped variables and asks the vault,
+     * with the SAME keys `resolve` uses, which the caller has configured — so the
+     * check can't drift from the actual resolution. A no-op when the vault/manual
+     * 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);
+        if (missing.length === 0)
+            return null;
+        return {
+            result: needsAuthorizationResult(tool.mcpName, 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
+            // opposed to a tool the caller never set up at all.
+            brokenSignIn: missing.some((v) => v.brokenSignIn),
+        };
+    }
+    /**
+     * 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
+     * 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)
+            return [];
+        const userVars = await this.toolManuals.userScopedKeysForManual(tool.manualName);
+        if (userVars.length === 0)
+            return [];
+        const status = await this.secretsVault.statusFor(userId, userVars.map((v) => v.key));
+        const statusMap = new Map(status.map((s) => [s.key, s]));
+        const missing = [];
+        for (const v of userVars) {
+            const st = statusMap.get(v.key);
+            // A sign-in the caller already HAS a row for but that isn't (or is no
+            // longer) usable: dead/wiped grant, abandoned consent, missing scopes.
+            const brokenSignIn = Boolean(v.oauth && st?.userConfigured);
+            if (!st?.userConfigured) {
+                missing.push({ name: v.name, label: v.label, brokenSignIn }); // no row at all → needs a value / sign-in
+                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)
+            // counts as not-yet-authorized.
+            if (v.oauth && st.userAuthorized !== true) {
+                missing.push({ name: v.name, label: v.label, brokenSignIn });
+                continue;
+            }
+            // An OAuth-backed var the user signed in for, but whose token was granted
+            // fewer scopes than the tool now declares, is ALSO not ready — the call would
+            // otherwise fail opaquely at the provider. Compare the live required scopes
+            // against the token's recorded granted scopes; an under-scoped (or unknown)
+            // token needs re-authorization.
+            if (v.oauth && !scopesCovered(v.oauthScopes, st.grantedScopes)) {
+                missing.push({ name: v.name, label: v.label, brokenSignIn });
+            }
+        }
+        return missing;
+    }
+    async dispatch(client, tool, request, 
+    // `sendNotification` typed loosely (`any`) so a `notifications/progress`
+    // payload without a `progressToken` is accepted — same approach the prior
+    // handler used; the strict ServerNotification type requires the token.
+    extra) {
+        const args = request.params.arguments ?? {};
+        const progressToken = request.params._meta?.progressToken;
+        let prev;
+        let hasPrev = false;
+        let progress = 0;
+        try {
+            // Args pass through to UTCP verbatim — each communication protocol does
+            // its own serialization (http reads the template's `body_field` out of the
+            // args, mcp forwards them untouched as MCP `arguments`). The advertised
+            // schema is the tool's UTCP `inputs` verbatim too, so what the caller
+            // sends is already in the shape the protocol expects; any reshaping here
+            // would be wrong for at least one protocol.
+            for await (const chunk of client.callToolStreaming(tool.utcpName, args)) {
+                if (hasPrev) {
+                    progress += 1;
+                    await extra
+                        .sendNotification({
+                        method: 'notifications/progress',
+                        params: {
+                            ...(progressToken !== undefined ? { progressToken } : {}),
+                            progress,
+                            message: renderProgress(prev),
+                        },
+                    })
+                        .catch((err) => console.warn('[mcp] progress notification failed:', err));
+                }
+                prev = chunk;
+                hasPrev = true;
+            }
+        }
+        catch (err) {
+            return toolError(`The "${tool.mcpName}" tool failed: ${describeToolFailure(err)}`);
+        }
+        return toCallToolResult(prev);
+    }
+    /**
+     * Handle a code-mode meta-tool. `list_tools`/`tools_info` reflect on the
+     * session client's discovered catalog; `call_tool_chain` runs the caller's
+     * JavaScript in the client's isolated-vm, where every tool is reachable as
+     * `<manual>.tool(...)` and resolves over loopback with the caller's key.
+     */
+    async dispatchMetaTool(client, name, args) {
+        try {
+            if (name === 'list_tools') {
+                const tools = await client.config.tool_repository.getTools();
+                return toCallToolResult({ tools: tools.map((t) => utcpNameToTsInterfaceName(t.name)) });
+            }
+            if (name === 'tools_info') {
+                const names = Array.isArray(args.tool_names) ? args.tool_names : [];
+                const interfaces = [];
+                const notFound = [];
+                for (const n of names) {
+                    const found = await findToolByName(client, n);
+                    if (found)
+                        interfaces.push(client.toolToTypeScriptInterface(found.tool));
+                    else
+                        notFound.push(n);
+                }
+                return toCallToolResult({ interfaces: interfaces.join('\n\n'), not_found: notFound });
+            }
+            // call_tool_chain
+            const code = typeof args.code === 'string' ? args.code : '';
+            const timeout = typeof args.timeout === 'number' ? args.timeout : 30_000;
+            // Clamp to [1000, 1_000_000] so a caller can't force oversized inline
+            // output past the spill (schema bounds are advisory over a raw JSON-RPC call).
+            const maxOutputSize = typeof args.max_output_size === 'number'
+                ? Math.min(1_000_000, Math.max(1_000, Math.trunc(args.max_output_size)))
+                : CALL_TOOL_CHAIN_MAX_OUTPUT;
+            const { result, logs } = await client.callToolChain(code, timeout);
+            // Bound the payload: an external session has no ambient workspace, so an
+            // oversized result spills to the shared store and we return only a ref —
+            // parity with the in-process agent's `call_tool_chain`.
+            if (JSON.stringify({ success: true, result, logs }).length <= maxOutputSize) {
+                return toCallToolResult({ success: true, result, logs });
+            }
+            const fullJson = JSON.stringify({ result, logs }, null, 2);
+            const { ref, bytes } = await this.opts.spillStore.write(fullJson);
+            return toCallToolResult({
+                success: true,
+                truncated: true,
+                result_ref: ref,
+                result_bytes: bytes,
+                message: `Result+logs payload was ${fullJson.length} characters (exceeded max_output_size of ${maxOutputSize}). Full JSON saved to the shared spill store as \`${ref}\`. Read it back with \`read_file\` (pass that ref as \`path\`, \`branch\` ignored, plus \`offset\`/\`limit\` to slice), or re-run a narrower chain that returns only what you need.`,
+            });
+        }
+        catch (err) {
+            return toolError(`The "${name}" tool failed: ${describeToolFailure(err)}`);
+        }
+    }
+}
+/**
+ * Flatten a discovered UTCP tool (`<manual>.<tool>`) into the proxy's advertised
+ * shape when MULTIPLE manuals are registered. KB tools keep their bare name (so
+ * existing external agents still call `read_file`); a user `.tool`'s tool is
+ * namespaced as `<manual>_<tool>` to guarantee a unique, dot-free MCP name.
+ */
+/**
+ * MCP tool-name grammar (also the Anthropic API's), and a length bound. A
+ * remote MCP server can expose a tool whose flattened name breaks this — too
+ * long, or an illegal char the `<manual>_<name>` flattening didn't remove — and
+ * an MCP client (or the model API behind it) rejects the ENTIRE `tools/list`
+ * response when a single entry is non-conforming. That makes EVERY tool vanish
+ * the moment one bad tool from a newly-added server enters the catalog, with no
+ * server-side error (the rejection is the client's). `toListedTool` isolates it
+ * per tool: drop the offender (logged), normalize an odd schema, keep the rest.
+ */
+const MCP_TOOL_NAME_RE = /^[a-zA-Z0-9_-]+$/;
+// The Anthropic API caps a tool name at 128 chars — but the MCP CLIENT (Claude
+// Code, claude.ai) prepends `mcp__<server>__` (≈20+ chars) before sending it,
+// and that FULL name is what the 128 applies to. So budget for the prefix here,
+// or a long `googlecalendar_…` name we pass gets the whole request 400'd. This
+// is deliberately conservative; a dropped tool is logged so it's diagnosable.
+const MCP_TOOL_NAME_MAX = 100;
+/** A discovered tool as an MCP listing entry, or null if its name can't be listed. */
+export function toListedTool(tool) {
+    if (!MCP_TOOL_NAME_RE.test(tool.mcpName) || tool.mcpName.length > MCP_TOOL_NAME_MAX) {
+        console.warn(`[mcp] dropping tool "${tool.mcpName}" from the listing — not a valid MCP tool name ` +
+            `(must match ${MCP_TOOL_NAME_RE} and be ≤${MCP_TOOL_NAME_MAX} chars). ` +
+            'One non-conforming tool would otherwise make the whole toolset disappear on the client.');
+        return null;
+    }
+    // MCP requires an object inputSchema. A remote server's schema that isn't a
+    // plain object (or omits `type: 'object'`) can invalidate the whole response,
+    // so normalize it — keeping any declared properties — rather than pass it
+    // through verbatim.
+    const raw = tool.inputSchema;
+    let inputSchema = raw && typeof raw === 'object' && !Array.isArray(raw)
+        ? { type: 'object', ...raw }
+        : { type: 'object', properties: {} };
+    // Sanitize the schema into what the Anthropic tool validator accepts. A
+    // remote server that emits a construct the validator rejects — Google's
+    // gmail/calendar use `$ref`/`$defs` AND OpenAPI `format` values like
+    // `int32`/`byte` — makes the CLIENT reject the ENTIRE tools/list response,
+    // so all tools vanish and nothing registers. Sanitizing per-tool means one
+    // odd server can't blank the whole toolset.
+    inputSchema = sanitizeInputSchema(inputSchema);
+    // The MCP/Anthropic validator requires the top-level `type` to be exactly
+    // "object" and (for the Anthropic API) `properties` to be present. Force both
+    // so a remote schema that declared something else — or a union like
+    // `["object","null"]` — can't reject the whole tools/list.
+    inputSchema.type = 'object';
+    if (typeof inputSchema.properties !== 'object' || inputSchema.properties === null) {
+        inputSchema.properties = {};
+    }
+    return {
+        name: tool.mcpName,
+        description: tool.description,
+        inputSchema: inputSchema,
+    };
+}
+/** JSON-Schema string `format` values the Anthropic tool validator accepts. */
+const SUPPORTED_SCHEMA_FORMATS = new Set([
+    'date-time',
+    'time',
+    'date',
+    'duration',
+    'email',
+    'hostname',
+    'uri',
+    'ipv4',
+    'ipv6',
+    'uuid',
+]);
+/**
+ * Make a remote server's JSON Schema safe for the Anthropic tool validator:
+ *  - inline local `$ref` pointers (`#/$defs/...`, `#/definitions/...`) and drop
+ *    the now-unreferenced `$defs`/`definitions` blocks (the API restricts `$ref`
+ *    and MCP clients converting our schemas reject it outright);
+ *  - drop non-standard `format` values (OpenAPI's `int32`/`byte`/… — only the
+ *    JSON-Schema-standard formats above are accepted; `format` is advisory, so
+ *    dropping it doesn't change tool behavior).
+ * Depth-bounded so a recursive schema degrades to a permissive `{}` node instead
+ * of hanging or emitting the unsupported recursion; non-local/external refs
+ * degrade the same way. Exported for direct testing.
+ */
+export function sanitizeInputSchema(schema) {
+    const root = schema;
+    const resolvePointer = (pointer) => {
+        if (!pointer.startsWith('#/'))
+            return undefined;
+        let node = root;
+        for (const partRaw of pointer.slice(2).split('/')) {
+            const part = partRaw.replace(/~1/g, '/').replace(/~0/g, '~');
+            if (!node || typeof node !== 'object')
+                return undefined;
+            node = node[part];
+        }
+        return node;
+    };
+    const walk = (node, depth) => {
+        if (depth > 20)
+            return {}; // recursion/cycle guard — permissive fallback
+        if (Array.isArray(node))
+            return node.map((item) => walk(item, depth + 1));
+        if (!node || typeof node !== 'object')
+            return node;
+        const obj = node;
+        if (typeof obj.$ref === 'string') {
+            const target = resolvePointer(obj.$ref);
+            // JSON Schema allows siblings next to $ref; keep them, target wins ties.
+            const { $ref: _ref, ...siblings } = obj;
+            const resolved = walk(target ?? {}, depth + 1);
+            return resolved && typeof resolved === 'object' && !Array.isArray(resolved)
+                ? { ...siblings, ...resolved }
+                : Object.keys(siblings).length
+                    ? siblings
+                    : resolved ?? {};
+        }
+        const out = {};
+        for (const [key, value] of Object.entries(obj)) {
+            if (key === '$defs' || key === 'definitions')
+                continue; // inlined above
+            // Drop a non-standard `format` (OpenAPI `int32`/`byte`/…) — the validator
+            // only allows the JSON-Schema-standard set; the annotation is non-load-bearing.
+            if (key === 'format' && (typeof value !== 'string' || !SUPPORTED_SCHEMA_FORMATS.has(value))) {
+                continue;
+            }
+            out[key] = walk(value, depth + 1);
+        }
+        return out;
+    };
+    return walk(schema, 0);
+}
+export function flattenManualTool(tool) {
+    const dot = tool.name.indexOf('.');
+    const manual = dot >= 0 ? tool.name.slice(0, dot) : '';
+    const bare = dot >= 0 ? tool.name.slice(dot + 1) : tool.name;
+    const mcpName = manual === EXTERNAL_KB_MANUAL_NAME ? bare : tool.name.replace(/\./g, '_');
+    return {
+        utcpName: tool.name,
+        mcpName,
+        description: tool.description,
+        inputSchema: tool.inputs,
+        manualName: manual,
+    };
+}
+/**
+ * Flatten one discovered UTCP tool into the proxy's advertised shape: strip the
+ * `<manual>.` namespace prefix for the MCP name and keep the UTCP input schema
+ * verbatim (Bevel-hosted HTTP tools show their `{body}` envelope, exactly as in
+ * `call_tool_chain`).
+ */
+export function flattenDiscoveredTool(prefix, tool) {
+    return {
+        utcpName: tool.name,
+        mcpName: tool.name.startsWith(prefix) ? tool.name.slice(prefix.length) : tool.name,
+        description: tool.description,
+        inputSchema: tool.inputs,
+        // `prefix` is `<manual>.`; the manual is that without the trailing dot.
+        manualName: prefix.endsWith('.') ? prefix.slice(0, -1) : prefix,
+    };
+}
+/**
+ * Extract a human-meaningful failure message from a tool-call error. UTCP's
+ * HTTP protocol surfaces a non-2xx as an axios-style error whose `.response.data`
+ * is the REST endpoint's JSON body (`{ error: "..." }`). Pull that out so the
+ * MCP caller sees the tool's real message instead of a bare "status code 500".
+ */
+export function describeToolFailure(err) {
+    const data = err?.response?.data;
+    if (data && typeof data === 'object') {
+        const inner = data.error;
+        if (typeof inner === 'string' && inner.length > 0)
+            return inner;
+    }
+    if (typeof data === 'string' && data.length > 0)
+        return data;
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Turn a tool's final value into an MCP result:
+ *  - a tool that already returns the MCP agentic shape (`{ content: [...] }`,
+ *    each entry a real content block) is passed through unchanged;
+ *  - a bare string becomes the text content;
+ *  - anything else is JSON-stringified into one text block.
+ *
+ * Note we do NOT collapse a structured object down to its `text` field: doing
+ * so silently dropped the other fields (e.g. `ask`'s `status` / `sessionId`,
+ * the id a caller must echo back to poll or continue a conversation).
+ * Stringifying the whole object keeps every field, so the caller always sees
+ * the id it is responsible for echoing.
+ *
+ * The passthrough guard checks the entries, not just that `content` is an array:
+ * a domain value that merely happens to carry a `content` array of non-blocks
+ * (e.g. `{ content: ['a', 'b'] }`) is data, not an MCP result, so it falls
+ * through to JSON-stringify and survives intact instead of being emitted as a
+ * malformed result the client can't parse.
+ */
+function isMcpContentBlock(entry) {
+    return typeof entry === 'object' && entry !== null && typeof entry.type === 'string';
+}
+export function toCallToolResult(value) {
+    // Already in MCP agentic format — pass through untouched, but only when every
+    // `content` entry is a real content block (has a string `type`).
+    const content = value?.content;
+    if (value && typeof value === 'object' && Array.isArray(content) && content.every(isMcpContentBlock)) {
+        return value;
+    }
+    const text = typeof value === 'string' ? value : JSON.stringify(value ?? null);
+    return { content: [{ type: 'text', text: text || '(tool produced no output)' }] };
+}
+function renderProgress(chunk) {
+    const s = typeof chunk === 'string' ? chunk : JSON.stringify(chunk);
+    return s.length > 500 ? s.slice(0, 497) + '...' : s;
+}
+function toolError(message) {
+    return { isError: true, content: [{ type: 'text', text: message }] };
+}
+/**
+ * The result returned when the caller is missing personal credentials a tool
+ * needs. Marked `isError` so the external agent surfaces it to the person rather
+ * than treating it as tool output. Names the tool, lists the missing items, and
+ * gives the absolute setup-page URL so the person can provide them and retry.
+ */
+export function needsAuthorizationResult(toolName, missing, connectUrl) {
+    const items = missing.join(', ');
+    const text = `The "${toolName}" tool needs credentials you haven't set up yet: ${items}. ` +
+        `Open ${connectUrl} to connect your accounts and enter your keys, then run the tool again.`;
+    return { isError: true, content: [{ type: 'text', text }] };
+}
+//# sourceMappingURL=mcp.service.js.map