@hotmeshio/long-tail 0.23.2 → 0.24.0

package/build/services/invocation-access.d.ts

@@ -8,11 +8,32 @@ export declare const INVOCATION_ROLE_TYPES: {
     readonly ADMIN: "admin";
 };
 export declare const ADMIN_ROLE = "admin";
-/** Superadmin anywhere, or the named admin role held as admin type, invokes every workflow. */
-export declare function hasGlobalInvocationAccess(roles: readonly InvocationRoleGrant[], authRole?: string): boolean;
+/** The workflow that calls a named MCP tool with lt-system authority. */
+export declare const CAPABILITY_INVOKE_WORKFLOW = "capabilityInvoke";
+/**
+ * Workflows whose activities act with lt-system authority. Started from
+ * outside the process, they would lend that authority to the caller, so only
+ * a superadmin may start one. Internal starts (agent triggers) are unaffected.
+ */
+export declare const SYSTEM_AUTHORITY_WORKFLOWS: ReadonlySet<string>;
+/**
+ * Whether a caller may run a workflow as another principal. A superadmin may
+ * act as anyone. Otherwise the caller needs an admin-type grant, the target
+ * holds no superadmin grant, and every grant the target holds the caller
+ * holds at the same or a higher type: an override never exceeds the caller.
+ */
+export declare function mayActAs(caller: readonly InvocationRoleGrant[], target: readonly InvocationRoleGrant[]): boolean;
+/**
+ * Superadmin anywhere, or the named admin role held as admin type, invokes
+ * every workflow. Decided from grants only, never a token's role claim.
+ */
+export declare function hasGlobalInvocationAccess(roles: readonly InvocationRoleGrant[]): boolean;
 /**
  * The one invocation predicate, shared by the invoke gate and the per-caller
  * list so the two can never disagree. An empty invocation_roles list opens
- * the workflow to every authenticated caller.
+ * the workflow to every authenticated caller. A system-authority workflow
+ * needs a superadmin grant, whatever its stored roles say.
  */
-export declare function canInvokeWorkflow(config: Pick<LTWorkflowConfig, 'invocable' | 'invocation_roles'>, roles: readonly InvocationRoleGrant[], authRole?: string): boolean;
+export declare function canInvokeWorkflow(config: Pick<LTWorkflowConfig, 'invocable' | 'invocation_roles'> & {
+    workflow_type?: string;
+}, roles: readonly InvocationRoleGrant[]): boolean;

package/build/services/invocation-access.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ADMIN_ROLE = exports.INVOCATION_ROLE_TYPES = void 0;
+exports.SYSTEM_AUTHORITY_WORKFLOWS = exports.CAPABILITY_INVOKE_WORKFLOW = exports.ADMIN_ROLE = exports.INVOCATION_ROLE_TYPES = void 0;
+exports.mayActAs = mayActAs;
 exports.hasGlobalInvocationAccess = hasGlobalInvocationAccess;
 exports.canInvokeWorkflow = canInvokeWorkflow;
 exports.INVOCATION_ROLE_TYPES = {
@@ -8,24 +9,55 @@ exports.INVOCATION_ROLE_TYPES = {
     ADMIN: 'admin',
 };
 exports.ADMIN_ROLE = 'admin';
-/** Superadmin anywhere, or the named admin role held as admin type, invokes every workflow. */
-function hasGlobalInvocationAccess(roles, authRole) {
-    if (authRole === exports.INVOCATION_ROLE_TYPES.SUPERADMIN)
+/** The workflow that calls a named MCP tool with lt-system authority. */
+exports.CAPABILITY_INVOKE_WORKFLOW = 'capabilityInvoke';
+/**
+ * Workflows whose activities act with lt-system authority. Started from
+ * outside the process, they would lend that authority to the caller, so only
+ * a superadmin may start one. Internal starts (agent triggers) are unaffected.
+ */
+exports.SYSTEM_AUTHORITY_WORKFLOWS = new Set([exports.CAPABILITY_INVOKE_WORKFLOW]);
+const ROLE_TYPE_RANK = { member: 1, admin: 2, superadmin: 3 };
+function holdsSuperadmin(roles) {
+    return roles.some((r) => r.type === exports.INVOCATION_ROLE_TYPES.SUPERADMIN);
+}
+/**
+ * Whether a caller may run a workflow as another principal. A superadmin may
+ * act as anyone. Otherwise the caller needs an admin-type grant, the target
+ * holds no superadmin grant, and every grant the target holds the caller
+ * holds at the same or a higher type: an override never exceeds the caller.
+ */
+function mayActAs(caller, target) {
+    if (holdsSuperadmin(caller))
         return true;
+    if (!caller.some((r) => r.type === exports.INVOCATION_ROLE_TYPES.ADMIN))
+        return false;
+    if (holdsSuperadmin(target))
+        return false;
+    return target.every((t) => caller.some((c) => c.role === t.role && (ROLE_TYPE_RANK[c.type] ?? 0) >= (ROLE_TYPE_RANK[t.type] ?? 0)));
+}
+/**
+ * Superadmin anywhere, or the named admin role held as admin type, invokes
+ * every workflow. Decided from grants only, never a token's role claim.
+ */
+function hasGlobalInvocationAccess(roles) {
     return roles.some((r) => r.type === exports.INVOCATION_ROLE_TYPES.SUPERADMIN)
         || roles.some((r) => r.role === exports.ADMIN_ROLE && r.type === exports.INVOCATION_ROLE_TYPES.ADMIN);
 }
 /**
  * The one invocation predicate, shared by the invoke gate and the per-caller
  * list so the two can never disagree. An empty invocation_roles list opens
- * the workflow to every authenticated caller.
+ * the workflow to every authenticated caller. A system-authority workflow
+ * needs a superadmin grant, whatever its stored roles say.
  */
-function canInvokeWorkflow(config, roles, authRole) {
+function canInvokeWorkflow(config, roles) {
     if (!config.invocable)
         return false;
+    if (config.workflow_type && exports.SYSTEM_AUTHORITY_WORKFLOWS.has(config.workflow_type))
+        return holdsSuperadmin(roles);
     if (config.invocation_roles.length === 0)
         return true;
-    if (hasGlobalInvocationAccess(roles, authRole))
+    if (hasGlobalInvocationAccess(roles))
         return true;
     const held = new Set(roles.map((r) => r.role));
     return config.invocation_roles.some((r) => held.has(r));

package/build/services/mcp/client/connection-dispatch.d.ts

@@ -8,7 +8,12 @@ import type { LTMcpToolManifest } from '../../../types';
  * are called via server._registeredTools[toolName].handler(args). This
  * eliminates the InMemoryTransport bottleneck under concurrent load.
  */
-export declare function dispatchBuiltinTool(serverId: string, toolName: string, args: Record<string, any>): Promise<{
+export declare function dispatchBuiltinTool(serverId: string, toolName: string, args: Record<string, any>, extra?: {
+    authInfo?: {
+        userId: string;
+        role?: string;
+    };
+}): Promise<{
     dispatched: true;
     result: any;
 } | null>;

package/build/services/mcp/client/connection-dispatch.js

@@ -13,7 +13,7 @@ const connection_lifecycle_1 = require("./connection-lifecycle");
  * are called via server._registeredTools[toolName].handler(args). This
  * eliminates the InMemoryTransport bottleneck under concurrent load.
  */
-async function dispatchBuiltinTool(serverId, toolName, args) {
+async function dispatchBuiltinTool(serverId, toolName, args, extra) {
     const builtinFactories = (0, connection_lifecycle_1.getBuiltinFactories)();
     const builtinServers = (0, connection_lifecycle_1.getBuiltinServers)();
     // Normalize and match against builtin factories
@@ -43,7 +43,8 @@ async function dispatchBuiltinTool(serverId, toolName, args) {
     // Call the handler directly — no transport, no JSON-RPC.
     // Tool handlers return MCP-shaped responses: { content: [{ type: 'text', text: '...' }] }
     // Parse the text content the same way callServerTool does.
-    const mcpResponse = await tool.handler(args);
+    // With `extra`, the handler sees an external caller and acts as them.
+    const mcpResponse = extra ? await tool.handler(args, extra) : await tool.handler(args);
     let parsed = mcpResponse;
     if (mcpResponse && Array.isArray(mcpResponse.content)) {
         const textContent = mcpResponse.content.find((c) => c.type === 'text');

package/build/services/mcp/client/connection-lifecycle.d.ts

@@ -1,5 +1,5 @@
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import type { LTMcpServerRecord } from '../../../types';
+import type { LTMcpServerRecord, LTToolManifestEntry } from '../../../types';
 /** Read-only access to the clients map for sibling modules. */
 export declare function getClients(): Map<string, Client>;
 /** Read-only access to the builtin factories map for sibling modules. */
@@ -10,7 +10,9 @@ export declare function getBuiltinServers(): Map<string, any>;
  * Register a built-in server factory so it can be auto-connected
  * when callServerTool is invoked with its name.
  */
-export declare function registerBuiltinServer(name: string, factory: () => Promise<any>): void;
+export declare function registerBuiltinServer(name: string, factory: () => Promise<any>, toolManifest?: LTToolManifestEntry[]): void;
+/** The tool manifest a built-in server was registered with, if any. */
+export declare function getBuiltinToolManifest(name: string): LTToolManifestEntry[] | undefined;
 /**
  * Connect to a registered MCP server.
  * Creates the appropriate transport based on transport_type,
@@ -29,6 +31,12 @@ export declare function disconnectFromServer(serverId: string): Promise<void>;
  * Alias lookups (e.g. 'translation' matching 'long-tail-translation') reuse
  * the same client instance to avoid double-connecting the singleton server.
  */
+/**
+ * The built-in server a server id or name resolves to, by the same rules
+ * resolveClient follows: an exact or fuzzy factory name, else a registered
+ * server whose name matches a factory. Null for an external server.
+ */
+export declare function resolveBuiltinServerName(serverId: string): Promise<string | null>;
 export declare function resolveClient(serverId: string): Promise<Client | null>;
 /**
  * Connect to all auto-connect servers.

package/build/services/mcp/client/connection-lifecycle.js

@@ -37,8 +37,10 @@ exports.getClients = getClients;
 exports.getBuiltinFactories = getBuiltinFactories;
 exports.getBuiltinServers = getBuiltinServers;
 exports.registerBuiltinServer = registerBuiltinServer;
+exports.getBuiltinToolManifest = getBuiltinToolManifest;
 exports.connectToServer = connectToServer;
 exports.disconnectFromServer = disconnectFromServer;
+exports.resolveBuiltinServerName = resolveBuiltinServerName;
 exports.resolveClient = resolveClient;
 exports.connectAutoServers = connectAutoServers;
 exports.disconnectAll = disconnectAll;
@@ -46,10 +48,9 @@ exports.isConnected = isConnected;
 exports.clear = clear;
 const index_js_1 = require("@modelcontextprotocol/sdk/client/index.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/client/stdio.js");
-const sse_js_1 = require("@modelcontextprotocol/sdk/client/sse.js");
-const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/client/streamableHttp.js");
 const inMemory_js_1 = require("@modelcontextprotocol/sdk/inMemory.js");
 const logger_1 = require("../../../lib/logger");
+const network_transport_1 = require("./network-transport");
 const mcpDbService = __importStar(require("../db"));
 /** In-memory map of server ID/name to active MCP client */
 const clients = new Map();
@@ -59,6 +60,8 @@ const clients = new Map();
  * rather than external stdio/SSE connections.
  */
 const builtinFactories = new Map();
+/** Tool manifests declared with a built-in factory (Long Tail's or the host's), keyed by server name. */
+const builtinManifests = new Map();
 /**
  * Cached built-in McpServer instances -- keyed by canonical server name.
  * Used by dispatchBuiltinTool() to call tool handlers directly without
@@ -81,8 +84,16 @@ function getBuiltinServers() {
  * Register a built-in server factory so it can be auto-connected
  * when callServerTool is invoked with its name.
  */
-function registerBuiltinServer(name, factory) {
+function registerBuiltinServer(name, factory, toolManifest) {
     builtinFactories.set(name, factory);
+    if (toolManifest)
+        builtinManifests.set(name, toolManifest);
+    else
+        builtinManifests.delete(name);
+}
+/** The tool manifest a built-in server was registered with, if any. */
+function getBuiltinToolManifest(name) {
+    return builtinManifests.get(name);
 }
 /**
  * Connect to a registered MCP server.
@@ -135,11 +146,8 @@ async function connectToServer(server) {
             env: server.transport_config.env,
         });
     }
-    else if (ttype === 'streamable-http') {
-        transport = new streamableHttp_js_1.StreamableHTTPClientTransport(new URL(server.transport_config.url));
-    }
     else {
-        transport = new sse_js_1.SSEClientTransport(new URL(server.transport_config.url));
+        transport = (0, network_transport_1.createNetworkTransport)(ttype === 'streamable-http' ? 'streamable-http' : 'sse', server.transport_config);
     }
     await client.connect(transport);
     clients.set(server.id, client);
@@ -174,6 +182,36 @@ async function disconnectFromServer(serverId) {
  * Alias lookups (e.g. 'translation' matching 'long-tail-translation') reuse
  * the same client instance to avoid double-connecting the singleton server.
  */
+/**
+ * The built-in server a server id or name resolves to, by the same rules
+ * resolveClient follows: an exact or fuzzy factory name, else a registered
+ * server whose name matches a factory. Null for an external server.
+ */
+async function resolveBuiltinServerName(serverId) {
+    if (builtinFactories.has(serverId))
+        return serverId;
+    const norm = (s) => s.replace(/[^a-zA-Z0-9]/g, '').toLowerCase();
+    const normId = norm(serverId);
+    for (const [name] of builtinFactories) {
+        const normName = norm(name);
+        if (normName.includes(normId) || normId.includes(normName))
+            return name;
+    }
+    try {
+        const dbServer = (await mcpDbService.getMcpServer(serverId)) ||
+            (await mcpDbService.getMcpServerByName(serverId));
+        if (!dbServer)
+            return null;
+        for (const [name] of builtinFactories) {
+            if (dbServer.name === name || name.includes(dbServer.name) || dbServer.name.includes(name))
+                return name;
+        }
+    }
+    catch {
+        // DB lookup failed: treated as external
+    }
+    return null;
+}
 async function resolveClient(serverId) {
     // 1. Direct lookup (by UUID or name)
     if (clients.has(serverId))

package/build/services/mcp/client/connection-test.js

@@ -3,8 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.testConnection = testConnection;
 const index_js_1 = require("@modelcontextprotocol/sdk/client/index.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/client/stdio.js");
-const sse_js_1 = require("@modelcontextprotocol/sdk/client/sse.js");
-const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/client/streamableHttp.js");
+const network_transport_1 = require("./network-transport");
 /**
  * Test connectivity to an MCP server without persisting.
  * Creates a temporary client, connects, lists tools, then disconnects.
@@ -21,11 +20,8 @@ async function testConnection(transportType, transportConfig) {
                 env: transportConfig.env,
             });
         }
-        else if (transportType === 'streamable-http') {
-            transport = new streamableHttp_js_1.StreamableHTTPClientTransport(new URL(transportConfig.url));
-        }
         else {
-            transport = new sse_js_1.SSEClientTransport(new URL(transportConfig.url));
+            transport = (0, network_transport_1.createNetworkTransport)(transportType, transportConfig);
         }
         await client.connect(transport);
         const { tools } = await client.listTools();

package/build/services/mcp/client/connection.d.ts

@@ -1,3 +1,3 @@
-export { registerBuiltinServer, connectToServer, disconnectFromServer, resolveClient, connectAutoServers, disconnectAll, isConnected, clear, } from './connection-lifecycle';
+export { registerBuiltinServer, getBuiltinToolManifest, connectToServer, disconnectFromServer, resolveClient, resolveBuiltinServerName, connectAutoServers, disconnectAll, isConnected, clear, } from './connection-lifecycle';
 export { testConnection } from './connection-test';
 export { dispatchBuiltinTool, listServerTools, } from './connection-dispatch';

package/build/services/mcp/client/connection.js

@@ -1,11 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.listServerTools = exports.dispatchBuiltinTool = exports.testConnection = exports.clear = exports.isConnected = exports.disconnectAll = exports.connectAutoServers = exports.resolveClient = exports.disconnectFromServer = exports.connectToServer = exports.registerBuiltinServer = void 0;
+exports.listServerTools = exports.dispatchBuiltinTool = exports.testConnection = exports.clear = exports.isConnected = exports.disconnectAll = exports.connectAutoServers = exports.resolveBuiltinServerName = exports.resolveClient = exports.disconnectFromServer = exports.connectToServer = exports.getBuiltinToolManifest = exports.registerBuiltinServer = void 0;
 var connection_lifecycle_1 = require("./connection-lifecycle");
 Object.defineProperty(exports, "registerBuiltinServer", { enumerable: true, get: function () { return connection_lifecycle_1.registerBuiltinServer; } });
+Object.defineProperty(exports, "getBuiltinToolManifest", { enumerable: true, get: function () { return connection_lifecycle_1.getBuiltinToolManifest; } });
 Object.defineProperty(exports, "connectToServer", { enumerable: true, get: function () { return connection_lifecycle_1.connectToServer; } });
 Object.defineProperty(exports, "disconnectFromServer", { enumerable: true, get: function () { return connection_lifecycle_1.disconnectFromServer; } });
 Object.defineProperty(exports, "resolveClient", { enumerable: true, get: function () { return connection_lifecycle_1.resolveClient; } });
+Object.defineProperty(exports, "resolveBuiltinServerName", { enumerable: true, get: function () { return connection_lifecycle_1.resolveBuiltinServerName; } });
 Object.defineProperty(exports, "connectAutoServers", { enumerable: true, get: function () { return connection_lifecycle_1.connectAutoServers; } });
 Object.defineProperty(exports, "disconnectAll", { enumerable: true, get: function () { return connection_lifecycle_1.disconnectAll; } });
 Object.defineProperty(exports, "isConnected", { enumerable: true, get: function () { return connection_lifecycle_1.isConnected; } });

package/build/services/mcp/client/index.d.ts

@@ -1,2 +1,2 @@
-export { registerBuiltinServer, connectToServer, disconnectFromServer, listServerTools, resolveClient, connectAutoServers, disconnectAll, isConnected, clear, } from './connection';
-export { callServerTool, toolActivities, } from './tools';
+export { registerBuiltinServer, getBuiltinToolManifest, connectToServer, disconnectFromServer, listServerTools, resolveClient, resolveBuiltinServerName, connectAutoServers, disconnectAll, isConnected, clear, } from './connection';
+export { callServerTool, callBuiltinToolAs, toolActivities, } from './tools';

package/build/services/mcp/client/index.js

@@ -1,16 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toolActivities = exports.callServerTool = exports.clear = exports.isConnected = exports.disconnectAll = exports.connectAutoServers = exports.resolveClient = exports.listServerTools = exports.disconnectFromServer = exports.connectToServer = exports.registerBuiltinServer = void 0;
+exports.toolActivities = exports.callBuiltinToolAs = exports.callServerTool = exports.clear = exports.isConnected = exports.disconnectAll = exports.connectAutoServers = exports.resolveBuiltinServerName = exports.resolveClient = exports.listServerTools = exports.disconnectFromServer = exports.connectToServer = exports.getBuiltinToolManifest = exports.registerBuiltinServer = void 0;
 var connection_1 = require("./connection");
 Object.defineProperty(exports, "registerBuiltinServer", { enumerable: true, get: function () { return connection_1.registerBuiltinServer; } });
+Object.defineProperty(exports, "getBuiltinToolManifest", { enumerable: true, get: function () { return connection_1.getBuiltinToolManifest; } });
 Object.defineProperty(exports, "connectToServer", { enumerable: true, get: function () { return connection_1.connectToServer; } });
 Object.defineProperty(exports, "disconnectFromServer", { enumerable: true, get: function () { return connection_1.disconnectFromServer; } });
 Object.defineProperty(exports, "listServerTools", { enumerable: true, get: function () { return connection_1.listServerTools; } });
 Object.defineProperty(exports, "resolveClient", { enumerable: true, get: function () { return connection_1.resolveClient; } });
+Object.defineProperty(exports, "resolveBuiltinServerName", { enumerable: true, get: function () { return connection_1.resolveBuiltinServerName; } });
 Object.defineProperty(exports, "connectAutoServers", { enumerable: true, get: function () { return connection_1.connectAutoServers; } });
 Object.defineProperty(exports, "disconnectAll", { enumerable: true, get: function () { return connection_1.disconnectAll; } });
 Object.defineProperty(exports, "isConnected", { enumerable: true, get: function () { return connection_1.isConnected; } });
 Object.defineProperty(exports, "clear", { enumerable: true, get: function () { return connection_1.clear; } });
 var tools_1 = require("./tools");
 Object.defineProperty(exports, "callServerTool", { enumerable: true, get: function () { return tools_1.callServerTool; } });
+Object.defineProperty(exports, "callBuiltinToolAs", { enumerable: true, get: function () { return tools_1.callBuiltinToolAs; } });
 Object.defineProperty(exports, "toolActivities", { enumerable: true, get: function () { return tools_1.toolActivities; } });

package/build/services/mcp/client/network-transport.d.ts

@@ -0,0 +1,12 @@
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+/**
+ * The client transport for a network MCP server. `headers` ride every
+ * request (the SSE stream and its POSTs alike), which is how a server that
+ * authenticates its callers, such as another Long Tail's /mcp with a
+ * service-account key, is reached.
+ */
+export declare function createNetworkTransport(transportType: 'sse' | 'streamable-http', config: {
+    url?: string;
+    headers?: Record<string, string>;
+}): SSEClientTransport | StreamableHTTPClientTransport;

package/build/services/mcp/client/network-transport.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createNetworkTransport = createNetworkTransport;
+const sse_js_1 = require("@modelcontextprotocol/sdk/client/sse.js");
+const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/client/streamableHttp.js");
+/**
+ * The client transport for a network MCP server. `headers` ride every
+ * request (the SSE stream and its POSTs alike), which is how a server that
+ * authenticates its callers, such as another Long Tail's /mcp with a
+ * service-account key, is reached.
+ */
+function createNetworkTransport(transportType, config) {
+    if (!config.url)
+        throw new Error('A network MCP server needs a url');
+    const url = new URL(config.url);
+    const requestInit = config.headers && Object.keys(config.headers).length ? { headers: config.headers } : undefined;
+    return transportType === 'streamable-http'
+        ? new streamableHttp_js_1.StreamableHTTPClientTransport(url, { requestInit })
+        : new sse_js_1.SSEClientTransport(url, { requestInit });
+}

package/build/services/mcp/client/tools.d.ts

@@ -1,3 +1,16 @@
+/**
+ * Call a built-in server's tool as a named caller: the handler sees the
+ * caller as an external principal, so caller-aware tools act with the
+ * caller's own rights rather than lt-system's. `serverName` is the canonical
+ * built-in name (resolveBuiltinServerName).
+ */
+export declare function callBuiltinToolAs(serverName: string, toolName: string, args: Record<string, any>, caller: {
+    userId: string;
+    role?: string;
+}, credentials?: {
+    userId?: string;
+    delegationToken?: string;
+}): Promise<any>;
 /**
  * Call a tool on a connected server.
  * Resolves the server by ID or name, auto-connecting built-in servers.

package/build/services/mcp/client/tools.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.callBuiltinToolAs = callBuiltinToolAs;
 exports.callServerTool = callServerTool;
 exports.toolActivities = toolActivities;
 const logger_1 = require("../../../lib/logger");
@@ -53,6 +54,23 @@ function deriveAuthFromToolContext() {
         delegationToken: ctx.credentials.delegationToken,
     };
 }
+/**
+ * Call a built-in server's tool as a named caller: the handler sees the
+ * caller as an external principal, so caller-aware tools act with the
+ * caller's own rights rather than lt-system's. `serverName` is the canonical
+ * built-in name (resolveBuiltinServerName).
+ */
+async function callBuiltinToolAs(serverName, toolName, args, caller, credentials) {
+    // `_auth` carries the identity tools resolve credentials with, as callServerTool sets it.
+    const toolArgs = {
+        ...args,
+        _auth: credentials ? { userId: credentials.userId, token: credentials.delegationToken } : { userId: caller.userId },
+    };
+    const builtin = await (0, connection_1.dispatchBuiltinTool)(serverName, toolName, toolArgs, { authInfo: caller });
+    if (!builtin)
+        throw Object.assign(new Error(`Tool ${toolName} not found on ${serverName}`), { name: 'ToolNotFoundError' });
+    return builtin.result;
+}
 /**
  * Call a tool on a connected server.
  * Resolves the server by ID or name, auto-connecting built-in servers.

package/build/services/mcp/db-server/index.js

@@ -5,6 +5,7 @@ exports.getDbServer = getDbServer;
 exports.stopDbServer = stopDbServer;
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const logger_1 = require("../../../lib/logger");
+const registered_tools_1 = require("../registered-tools");
 const tools_1 = require("./tools");
 let server = null;
 /**
@@ -28,7 +29,7 @@ async function createDbServer(options) {
         server = instance;
     }
     (0, tools_1.registerDbTools)(instance);
-    logger_1.loggerRegistry.info(`[lt-mcp:db-server] ${name} ready (6 tools registered)`);
+    logger_1.loggerRegistry.info(`[lt-mcp:db-server] ${name} ready (${(0, registered_tools_1.registeredToolCount)(instance)} tools registered)`);
     return instance;
 }
 /**

package/build/services/mcp/external-server.d.ts

@@ -6,10 +6,15 @@
  * Created per-request in stateless mode (pure in-memory, no IO).
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CapabilityAccess } from '../../types';
 import type { ExposureConfig } from './exposure';
+export declare const SHIPPED_SERVERS: Set<string>;
 /**
- * Create a unified McpServer with tools from all qualifying shipped servers.
- * Called per-request in stateless mode. Server instances are cached; only
- * the McpServer wrapper and tool registrations are fresh (pure in-memory).
+ * Create a unified McpServer with the tools this caller may use from all
+ * qualifying shipped servers. Called per-request in stateless mode, so a tool
+ * the caller lacks the capability for is neither listed nor callable. When
+ * the request calls one tool, only that tool is registered and only its gate
+ * is checked. Server instances are cached; only the McpServer wrapper and
+ * tool registrations are fresh (pure in-memory).
  */
-export declare function createUnifiedMcpServer(exposure?: ExposureConfig, callerScopes?: string[]): Promise<McpServer>;
+export declare function createUnifiedMcpServer(access: CapabilityAccess, exposure?: ExposureConfig, callerScopes?: string[], requestedTool?: string): Promise<McpServer>;

package/build/services/mcp/external-server.js

@@ -7,6 +7,7 @@
  * Created per-request in stateless mode (pure in-memory, no IO).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SHIPPED_SERVERS = void 0;
 exports.createUnifiedMcpServer = createUnifiedMcpServer;
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const logger_1 = require("../../lib/logger");
@@ -44,7 +45,7 @@ async function buildInstructions() {
 // ── Shipped server allowlist ─────────────────────────────────────────────────
 // Only these servers are exposed via the /mcp endpoint.
 // Example servers (playwright, gmail, image-tools) are excluded.
-const SHIPPED_SERVERS = new Set([
+exports.SHIPPED_SERVERS = new Set([
     'long-tail-admin',
     'long-tail-human-queue',
     'long-tail-file-storage',
@@ -74,7 +75,7 @@ async function getOrCreateServer(name) {
 }
 // ── Exposure filtering ───────────────────────────────────────────────────────
 function isServerAllowed(name, exposure) {
-    if (!SHIPPED_SERVERS.has(name))
+    if (!exports.SHIPPED_SERVERS.has(name))
         return false;
     if (exposure?.allowServers?.length) {
         if (!exposure.allowServers.includes(name))
@@ -94,6 +95,15 @@ function isServerAllowed(name, exposure) {
     }
     return true;
 }
+/**
+ * Whether the caller holds the capability the tool's manifest entry declares.
+ * Fails closed: a tool without a manifest entry or a gate is never exposed.
+ */
+async function isToolPermitted(toolName, serverName, access) {
+    const manifest = system_1.builtinMcpServerFactories[serverName]?.config?.toolManifest;
+    const gate = manifest?.find((t) => t.name === toolName)?.gate;
+    return gate !== undefined && (await access(gate));
+}
 function isToolAllowed(toolName, serverName, exposure, callerScopes) {
     // Per-caller scope filtering: mcp:read callers only see read_safe tools
     const isReadOnly = exposure?.readOnly
@@ -114,12 +124,16 @@ function isToolAllowed(toolName, serverName, exposure, callerScopes) {
 }
 // ── Unified server creation ──────────────────────────────────────────────────
 /**
- * Create a unified McpServer with tools from all qualifying shipped servers.
- * Called per-request in stateless mode. Server instances are cached; only
- * the McpServer wrapper and tool registrations are fresh (pure in-memory).
+ * Create a unified McpServer with the tools this caller may use from all
+ * qualifying shipped servers. Called per-request in stateless mode, so a tool
+ * the caller lacks the capability for is neither listed nor callable. When
+ * the request calls one tool, only that tool is registered and only its gate
+ * is checked. Server instances are cached; only the McpServer wrapper and
+ * tool registrations are fresh (pure in-memory).
  */
-async function createUnifiedMcpServer(exposure, callerScopes) {
+async function createUnifiedMcpServer(access, exposure, callerScopes, requestedTool) {
     const unified = new mcp_js_1.McpServer({ name: 'long-tail', version: '1.0.0' }, { instructions: await buildInstructions() });
+    const named = new Set();
     const registered = new Set();
     for (const [name] of Object.entries(system_1.builtinMcpServerFactories)) {
         if (!isServerAllowed(name, exposure))
@@ -137,16 +151,22 @@ async function createUnifiedMcpServer(exposure, callerScopes) {
             for (const [toolName, tool] of Object.entries(tools)) {
                 if (!tool?.handler || !tool.enabled)
                     continue;
-                if (!isToolAllowed(toolName, name, exposure, callerScopes))
-                    continue;
-                // Deduplicate: prefix with server short name on collision
+                // Deduplicate: prefix with server short name on collision. Names are
+                // claimed before filtering so a tool keeps its name for every caller.
                 let finalName = toolName;
-                if (registered.has(toolName)) {
+                if (named.has(toolName)) {
                     const prefix = name.replace('long-tail-', '').replace(/-/g, '_');
                     finalName = `${prefix}_${toolName}`;
-                    if (registered.has(finalName))
+                    if (named.has(finalName))
                         continue; // still a collision — skip
                 }
+                named.add(finalName);
+                if (requestedTool !== undefined && finalName !== requestedTool)
+                    continue;
+                if (!(await isToolPermitted(toolName, name, access)))
+                    continue;
+                if (!isToolAllowed(toolName, name, exposure, callerScopes))
+                    continue;
                 registered.add(finalName);
                 // Re-register the tool handler on the unified server.
                 // Use the low-level `tool()` API since we already have the parsed handler.
@@ -162,6 +182,9 @@ async function createUnifiedMcpServer(exposure, callerScopes) {
             logger_1.loggerRegistry.error(`[lt-mcp:endpoint] server "${name}" failed to load, skipping its tools: ${err?.stack || err?.message || err}`);
         }
     }
+    // A call to one denied or unknown tool registers none; the tool handlers
+    // still answer it the way the SDK answers any unknown tool.
+    unified.setToolRequestHandlers();
     logger_1.loggerRegistry.info(`[lt-mcp:endpoint] unified server ready (${registered.size} tools)`);
     return unified;
 }

package/build/services/mcp/playwright-server/index.js

@@ -4,6 +4,7 @@ exports.stopPlaywrightServer = void 0;
 exports.createPlaywrightServer = createPlaywrightServer;
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const logger_1 = require("../../../lib/logger");
+const registered_tools_1 = require("../registered-tools");
 const tools_1 = require("./tools");
 var lifecycle_1 = require("./lifecycle");
 Object.defineProperty(exports, "stopPlaywrightServer", { enumerable: true, get: function () { return lifecycle_1.stopPlaywrightServer; } });
@@ -20,6 +21,6 @@ async function createPlaywrightServer(options) {
     const name = options?.name || 'long-tail-playwright';
     const instance = new mcp_js_1.McpServer({ name, version: '1.0.0' });
     (0, tools_1.registerTools)(instance);
-    logger_1.loggerRegistry.info(`[lt-mcp:playwright] ${name} ready (8 tools registered)`);
+    logger_1.loggerRegistry.info(`[lt-mcp:playwright] ${name} ready (${(0, registered_tools_1.registeredToolCount)(instance)} tools registered)`);
     return instance;
 }

package/build/services/mcp/registered-tools.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/** How many tools a server registered, for its ready log line. */
+export declare function registeredToolCount(server: McpServer): number;

package/build/services/mcp/registered-tools.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registeredToolCount = registeredToolCount;
+/** How many tools a server registered, for its ready log line. */
+function registeredToolCount(server) {
+    return Object.keys(server._registeredTools ?? {}).length;
+}

package/build/services/mcp/server-lifecycle.js

@@ -5,6 +5,7 @@ exports.getServer = getServer;
 exports.stopServer = stopServer;
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const logger_1 = require("../../lib/logger");
+const registered_tools_1 = require("./registered-tools");
 const server_tools_1 = require("./server-tools");
 let server = null;
 /**
@@ -28,7 +29,7 @@ async function createHumanQueueServer(options) {
     const name = options?.name || 'long-tail-human-queue';
     server = new mcp_js_1.McpServer({ name, version: '1.0.0' });
     (0, server_tools_1.registerHumanQueueTools)(server);
-    logger_1.loggerRegistry.info(`[lt-mcp:server] ${name} ready (5 tools registered)`);
+    logger_1.loggerRegistry.info(`[lt-mcp:server] ${name} ready (${(0, registered_tools_1.registeredToolCount)(server)} tools registered)`);
     return server;
 }
 /**