@hotmeshio/long-tail 0.23.2 → 0.24.1

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/seed-service-account.d.ts

@@ -6,6 +6,9 @@
  *   - `mcp:full`  — all tools (automation, orchestration)
  *
  * Idempotent — skips creation if the account already exists.
- * Keys are generated once and logged; they cannot be retrieved again.
+ * With LT_SEED_SERVICE_KEYS=true (local docker compose) the keys are
+ * generated once and printed to stdout, never to the logger; they cannot be
+ * retrieved again. Otherwise the account is created without keys and a
+ * superadmin mints them from the dashboard or the bot-accounts API.
  */
 export declare function seedMcpServiceAccount(): Promise<void>;

package/build/services/mcp/seed-service-account.js

@@ -7,7 +7,10 @@
  *   - `mcp:full`  — all tools (automation, orchestration)
  *
  * Idempotent — skips creation if the account already exists.
- * Keys are generated once and logged; they cannot be retrieved again.
+ * With LT_SEED_SERVICE_KEYS=true (local docker compose) the keys are
+ * generated once and printed to stdout, never to the logger; they cannot be
+ * retrieved again. Otherwise the account is created without keys and a
+ * superadmin mints them from the dashboard or the bot-accounts API.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -45,6 +48,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.seedMcpServiceAccount = seedMcpServiceAccount;
 const logger_1 = require("../../lib/logger");
+const config_1 = require("../../modules/config");
 const crud_1 = require("../user/crud");
 const iam = __importStar(require("../iam"));
 const SERVICE_ACCOUNT_NAME = 'mcp-service';
@@ -63,13 +67,14 @@ async function seedMcpServiceAccount() {
             display_name: 'MCP Service',
             roles: [{ role: 'system', type: 'member' }],
         });
-        // Generate read key (scoped to mcp:read)
+        if (!config_1.config.LT_SEED_SERVICE_KEYS) {
+            logger_1.loggerRegistry.info(`[seed-mcp] ${SERVICE_ACCOUNT_NAME} created; mint its API keys from the dashboard`);
+            return;
+        }
         const readKey = await iam.createBotKey(bot.id, 'read', ['mcp:read']);
-        logger_1.loggerRegistry.info(`[seed-mcp] read key: ${readKey.rawKey}`);
-        // Generate full key (scoped to mcp:full)
         const fullKey = await iam.createBotKey(bot.id, 'full', ['mcp:read', 'mcp:full']);
-        logger_1.loggerRegistry.info(`[seed-mcp] full key: ${fullKey.rawKey}`);
-        logger_1.loggerRegistry.info(`[seed-mcp] ${SERVICE_ACCOUNT_NAME} created with read + full API keys`);
+        process.stdout.write(`[seed-mcp] read key: ${readKey.rawKey}\n[seed-mcp] full key: ${fullKey.rawKey}\n`);
+        logger_1.loggerRegistry.info(`[seed-mcp] ${SERVICE_ACCOUNT_NAME} created with read + full API keys (printed to stdout)`);
     }
     catch (err) {
         logger_1.loggerRegistry.warn(`[seed-mcp] failed to seed: ${err.message}`);

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;
 }
 /**

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

@@ -53,7 +53,20 @@ export declare class InvocationError extends Error {
  */
 export declare function invokeWorkflow(input: InvokeWorkflowInput): Promise<InvokeWorkflowResult>;
 /**
- * Check invocation_roles when present on a workflow config.
- * Throws InvocationError if the user lacks the required role.
+ * Check a caller against the workflow's invocation rules, from the caller's
+ * live grants rather than any role claim a token carries. A workflow with no
+ * invocation roles is open, except a system-authority workflow, which needs a
+ * superadmin.
  */
-export declare function checkInvocationRoles(workflowType: string, userId: string, authRole?: string): Promise<void>;
+export declare function checkInvocationRoles(workflowType: string, userId: string): Promise<void>;
+/** Refuse an execute_as override that would exceed the caller's own authority. */
+export declare function assertMayActAs(userId: string, executeAs: string): Promise<void>;
+/**
+ * Authorize an invocation that arrives from outside the process (REST, /mcp):
+ * the workflow's invocation rules, then any execute_as override.
+ */
+export declare function authorizeInvocation(input: {
+    workflowType: string;
+    userId: string;
+    executeAs?: string;
+}): Promise<void>;

package/build/services/workflow-invocation.js

@@ -45,8 +45,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.InvocationError = void 0;
 exports.invokeWorkflow = invokeWorkflow;
 exports.checkInvocationRoles = checkInvocationRoles;
+exports.assertMayActAs = assertMayActAs;
+exports.authorizeInvocation = authorizeInvocation;
 const hotmesh_1 = require("@hotmeshio/hotmesh");
 const invocation_access_1 = require("./invocation-access");
+const uuid_1 = require("../lib/uuid");
 const workers_1 = require("../workers");
 const configService = __importStar(require("./config"));
 const userService = __importStar(require("./user"));
@@ -138,26 +141,55 @@ async function resolveTaskQueue(workflowType) {
     }
     return worker.taskQueue;
 }
+/** A principal's grants by uuid or external_id, or null when no such user exists. */
+async function grantsOf(identifier) {
+    const user = (0, uuid_1.isUuid)(identifier)
+        ? await userService.getUser(identifier)
+        : await userService.getUserByExternalId(identifier);
+    return user ? user.roles.map((r) => ({ role: r.role, type: r.type })) : null;
+}
 /**
- * Check invocation_roles when present on a workflow config.
- * Throws InvocationError if the user lacks the required role.
+ * Check a caller against the workflow's invocation rules, from the caller's
+ * live grants rather than any role claim a token carries. A workflow with no
+ * invocation roles is open, except a system-authority workflow, which needs a
+ * superadmin.
  */
-async function checkInvocationRoles(workflowType, userId, authRole) {
+async function checkInvocationRoles(workflowType, userId) {
     const wfConfig = await configService.getWorkflowConfig(workflowType);
-    if (!wfConfig || wfConfig.invocation_roles.length === 0)
-        return;
-    // Superadmin from JWT bypasses all invocation role checks
-    if (authRole === 'superadmin')
+    const systemAuthority = invocation_access_1.SYSTEM_AUTHORITY_WORKFLOWS.has(workflowType);
+    if (!systemAuthority && (!wfConfig || wfConfig.invocation_roles.length === 0))
         return;
-    const user = await userService.getUser(userId);
-    if (!user) {
+    const roles = await grantsOf(userId);
+    if (!roles) {
         throw new InvocationError('User not registered', 403);
     }
     // invocable is resolveTaskQueue's concern; this gate decides roles only.
-    if (!(0, invocation_access_1.canInvokeWorkflow)({ ...wfConfig, invocable: true }, user.roles, authRole)) {
+    const rules = { workflow_type: workflowType, invocation_roles: wfConfig?.invocation_roles ?? [], invocable: true };
+    if (!(0, invocation_access_1.canInvokeWorkflow)(rules, roles)) {
         throw new InvocationError('Insufficient role for invocation', 403);
     }
 }
+/** Refuse an execute_as override that would exceed the caller's own authority. */
+async function assertMayActAs(userId, executeAs) {
+    const caller = await grantsOf(userId);
+    if (!caller)
+        throw new InvocationError('User not registered', 403);
+    const target = await grantsOf(executeAs);
+    if (!target)
+        throw new InvocationError(`execute_as principal "${executeAs}" not found`, 404);
+    if (!(0, invocation_access_1.mayActAs)(caller, target)) {
+        throw new InvocationError('execute_as may not exceed your own authority', 403);
+    }
+}
+/**
+ * Authorize an invocation that arrives from outside the process (REST, /mcp):
+ * the workflow's invocation rules, then any execute_as override.
+ */
+async function authorizeInvocation(input) {
+    await checkInvocationRoles(input.workflowType, input.userId);
+    if (input.executeAs)
+        await assertMayActAs(input.userId, input.executeAs);
+}
 /**
  * Build the LTEnvelope with IAM context.
  */

package/build/services/yaml-workflow/deployer.d.ts

@@ -27,10 +27,18 @@ export declare function deployYamlWorkflow(appId: string, yamlContent: string):
  * Activate a deployed version of a YAML workflow.
  */
 export declare function activateYamlWorkflow(appId: string, version: string): Promise<boolean>;
+/** The key compiled workflow activities read their identity context from. */
+export declare const SCOPE_KEY = "_scope";
+/**
+ * The trigger data a compiled workflow starts with. Identity context is never
+ * taken from the data a caller supplied: any `_scope` there is dropped, and
+ * only the scope the server resolved is set.
+ */
+export declare function withTrustedScope(data: Record<string, unknown>, scope?: Record<string, unknown>): Record<string, unknown>;
 /**
  * Invoke a YAML workflow (fire-and-forget). Returns the job ID.
  */
-export declare function invokeYamlWorkflow(appId: string, topic: string, data: Record<string, unknown>, entity?: string, context?: Record<string, any>): Promise<string>;
+export declare function invokeYamlWorkflow(appId: string, topic: string, data: Record<string, unknown>, entity?: string, context?: Record<string, any>, scope?: Record<string, unknown>): Promise<string>;
 /**
  * Invoke a YAML workflow and wait for the result.
  *
@@ -40,7 +48,7 @@ export declare function invokeYamlWorkflow(appId: string, topic: string, data: R
  *
  * Source: @hotmeshio/hotmesh engine/index.js pubsub()
  */
-export declare function invokeYamlWorkflowSync(appId: string, topic: string, data: Record<string, unknown>, timeout?: number, entity?: string): Promise<{
+export declare function invokeYamlWorkflowSync(appId: string, topic: string, data: Record<string, unknown>, timeout?: number, entity?: string, scope?: Record<string, unknown>): Promise<{
     job_id: string;
     result: Record<string, unknown>;
 }>;