@hotmeshio/long-tail 0.23.2 → 0.24.1

package/build/adapters/express.d.ts

@@ -1,4 +1,4 @@
-import { Router } from 'express';
+import { Router } from '../lib/http';
 import type { Server as HttpServer } from 'http';
 /**
  * Express adapter for mounting the Long Tail dashboard at an arbitrary subpath
@@ -65,5 +65,15 @@ export declare class LTExpressAdapter {
      * - SPA fallback with injected `<base href>` and `window.__LT_BASE__`
      */
     getRouter(): Router;
+    /**
+     * The OAuth well-known documents. Mount at the host's root, not under the
+     * base path: clients look for them at the origin. It answers only its two
+     * paths and passes everything else on. Warns when the issuer's path is not
+     * the base path: the router would then publish metadata for a server that
+     * is not the one mounted here, possibly over the host's own.
+     */
+    getWellKnownRouter(): Router;
+    /** Whether a built dashboard was found to serve. */
+    hasDashboard(): boolean;
     private resolveDashboardDist;
 }

package/build/adapters/express.js

@@ -1,37 +1,4 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -39,13 +6,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.LTExpressAdapter = void 0;
 const fs_1 = require("fs");
 const path_1 = __importDefault(require("path"));
-const express_1 = __importStar(require("express"));
+const http_1 = require("../lib/http");
+const CONSENT_PAGE_PATH = '/oauth/consent';
 const routes_1 = __importDefault(require("../routes"));
 const mcp_endpoint_1 = __importDefault(require("../routes/mcp-endpoint"));
+const oauth_well_known_1 = require("../routes/oauth-well-known");
 const events_1 = require("../lib/events");
 const socketio_1 = require("../lib/events/socketio");
 const nats_1 = require("../lib/events/nats");
 const nats_ws_proxy_1 = require("../lib/events/nats-ws-proxy");
+const logger_1 = require("../lib/logger");
+const oauth_server_1 = require("../modules/oauth-server");
 /**
  * Express adapter for mounting the Long Tail dashboard at an arbitrary subpath
  * inside an existing Express-based application (NestJS, Fastify-Express, etc.).
@@ -124,6 +95,7 @@ class LTExpressAdapter {
             }
             (0, nats_ws_proxy_1.attachNatsWsProxy)(server, natsAdapter.wsProxyTarget, {
                 basePath: this.basePath,
+                authToken: natsAdapter.authToken,
                 onWsUrlDerived: (url) => {
                     if (!natsAdapter.wsUrl) {
                         natsAdapter.setWsUrl(url);
@@ -141,8 +113,8 @@ class LTExpressAdapter {
      * - SPA fallback with injected `<base href>` and `window.__LT_BASE__`
      */
     getRouter() {
-        const router = (0, express_1.Router)();
-        router.use(express_1.default.json());
+        const router = (0, http_1.Router)();
+        router.use((0, http_1.jsonBody)());
         // Health check
         router.get('/health', (_req, res) => {
             res.json({ status: 'ok', timestamp: new Date().toISOString() });
@@ -154,16 +126,25 @@ class LTExpressAdapter {
         // Dashboard static assets
         const dashboardDist = this.resolveDashboardDist();
         if (dashboardDist) {
-            router.use(express_1.default.static(dashboardDist, { index: false }));
-            // SPA fallback — inject base path into index.html
-            const indexHtml = (0, fs_1.readFileSync)(path_1.default.join(dashboardDist, 'index.html'), 'utf-8');
+            router.use((0, http_1.serveStatic)(dashboardDist, { index: false }));
+            // SPA fallback — inject base path into index.html. Outside production
+            // the file is re-read per request so dashboard rebuilds show without a restart.
+            const indexPath = path_1.default.join(dashboardDist, 'index.html');
+            const cachedIndex = process.env.NODE_ENV === 'production' ? (0, fs_1.readFileSync)(indexPath, 'utf-8') : null;
             const basePath = this.basePath;
             // Serve __LT_BASE__ as external script (CSP-safe, no inline scripts)
             router.get('/config.js', (_req, res) => {
                 res.type('application/javascript').send(`window.__LT_BASE__="${basePath}";`);
             });
-            router.get('/{*splat}', (_req, res) => {
-                const html = indexHtml.replace('<head>', '<head>' +
+            router.get('/{*splat}', (req, res) => {
+                // The consent page grants access to a person's account: never inside
+                // a frame. Browsers enforce every CSP header, so appending a second
+                // policy keeps the host's and still refuses framing.
+                if (req.path.startsWith(CONSENT_PAGE_PATH)) {
+                    res.setHeader('X-Frame-Options', 'DENY');
+                    res.append('Content-Security-Policy', "frame-ancestors 'none'");
+                }
+                const html = (cachedIndex ?? (0, fs_1.readFileSync)(indexPath, 'utf-8')).replace('<head>', '<head>' +
                     `<base href="${basePath}/">` +
                     `<script src="./config.js"></script>`);
                 res.type('html').send(html);
@@ -171,6 +152,26 @@ class LTExpressAdapter {
         }
         return router;
     }
+    /**
+     * The OAuth well-known documents. Mount at the host's root, not under the
+     * base path: clients look for them at the origin. It answers only its two
+     * paths and passes everything else on. Warns when the issuer's path is not
+     * the base path: the router would then publish metadata for a server that
+     * is not the one mounted here, possibly over the host's own.
+     */
+    getWellKnownRouter() {
+        const settings = (0, oauth_server_1.getOAuthServerSettings)();
+        const issuerPath = settings ? new URL(settings.issuer).pathname.replace(/\/+$/, '') : null;
+        if (issuerPath !== null && issuerPath !== this.basePath) {
+            logger_1.loggerRegistry.warn(`[long-tail] OAuth issuer path "${issuerPath || '/'}" differs from the mount path "${this.basePath || '/'}"; `
+                + `set the issuer to https://<host>${this.basePath}`);
+        }
+        return (0, oauth_well_known_1.createWellKnownRouter)();
+    }
+    /** Whether a built dashboard was found to serve. */
+    hasDashboard() {
+        return this.resolveDashboardDist() !== null;
+    }
     resolveDashboardDist() {
         // Check multiple paths relative to the compiled output location:
         // - Dev (ts-node from repo root): adapters/ -> dashboard/dist

package/build/api/auth-sso.d.ts

@@ -1,4 +1,4 @@
-import type { Request, Response } from 'express';
+import type { Request, Response } from '../lib/http';
 import type { LTApiResult } from '../types/sdk';
 /**
  * Exchange host authentication for a Long Tail JWT.

package/build/api/bot-accounts.d.ts

@@ -138,4 +138,6 @@ export declare function createBotKey(input: {
  */
 export declare function revokeBotKey(input: {
     keyId: string;
+    /** When given, the key is revoked only if it belongs to this bot. */
+    botId?: string;
 }): Promise<LTApiResult>;

package/build/api/bot-accounts.js

@@ -44,6 +44,7 @@ exports.removeBotRole = removeBotRole;
 exports.listBotKeys = listBotKeys;
 exports.createBotKey = createBotKey;
 exports.revokeBotKey = revokeBotKey;
+const bot_api_key_1 = require("../services/auth/bot-api-key");
 const iam = __importStar(require("../services/iam"));
 const user_1 = require("../services/user");
 /**
@@ -292,6 +293,9 @@ async function createBotKey(input) {
  */
 async function revokeBotKey(input) {
     try {
+        if (input.botId !== undefined && (await (0, bot_api_key_1.getBotApiKeyOwner)(input.keyId)) !== input.botId) {
+            return { status: 404, error: 'API key not found' };
+        }
         const revoked = await iam.revokeBotKey(input.keyId);
         if (!revoked) {
             return { status: 404, error: 'API key not found' };

package/build/api/capabilities.d.ts

@@ -1,2 +1,7 @@
-import type { LTApiResult } from '../types/sdk';
-export declare function listCapabilities(): Promise<LTApiResult>;
+import type { LTApiAuth, LTApiResult } from '../types/sdk';
+/**
+ * Every tool the caller may run, by category. A built-in server's tool is
+ * listed only when its manifest gate admits the caller, the same rule the
+ * tool-call route applies; an external server's tools are listed as before.
+ */
+export declare function listCapabilities(auth?: LTApiAuth): Promise<LTApiResult>;

package/build/api/capabilities.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.listCapabilities = listCapabilities;
 const db_1 = require("../lib/db");
+const capabilities_1 = require("../modules/capabilities");
+const tools_1 = require("./mcp/tools");
 const LIST_SERVERS_WITH_TOOLS = `
   SELECT id, name, description, tags, tool_manifest, compile_hints, category
   FROM lt_mcp_servers
@@ -40,18 +42,27 @@ function resolveCategory(server) {
     }
     return 'Other';
 }
-async function listCapabilities() {
+/**
+ * Every tool the caller may run, by category. A built-in server's tool is
+ * listed only when its manifest gate admits the caller, the same rule the
+ * tool-call route applies; an external server's tools are listed as before.
+ */
+async function listCapabilities(auth) {
     try {
         const pool = (0, db_1.getPool)();
         const { rows } = await pool.query(LIST_SERVERS_WITH_TOOLS);
         const categoryMap = new Map();
+        const access = (0, capabilities_1.capabilityAccess)(auth?.userId ? { userId: auth.userId } : undefined);
         for (const server of rows) {
             const category = resolveCategory(server);
             const tools = (server.tool_manifest || []);
             if (!categoryMap.has(category)) {
                 categoryMap.set(category, []);
             }
+            const builtin = await (0, tools_1.builtinServerFor)(server.name);
             for (const tool of tools) {
+                if (builtin && !(await access((0, tools_1.builtinToolGate)(builtin, tool.name))))
+                    continue;
                 categoryMap.get(category).push({
                     name: tool.name,
                     description: tool.description || '',
@@ -62,7 +73,7 @@ async function listCapabilities() {
             }
         }
         const categories = CATEGORY_ORDER
-            .filter((name) => categoryMap.has(name))
+            .filter((name) => (categoryMap.get(name)?.length ?? 0) > 0)
             .map((name) => ({
             name,
             tools: categoryMap.get(name).sort((a, b) => a.name.localeCompare(b.name)),

package/build/api/escalations/analytics.js

@@ -73,6 +73,11 @@ async function effectiveRoles(query) {
     // query will actually touch. Resolution throws AnalyticsInputError (→ 400)
     // for unknown keys, before any scope decision.
     if (query?.entity) {
+        // The gate covers the entity's roles only, so a role filter beside it is
+        // refused here, before the gate, rather than reaching the query unchecked.
+        if (query.role !== undefined || query.roles !== undefined) {
+            throw new escalation_1.AnalyticsInputError('query.entity and query.role/roles are two scoping mechanisms: use one');
+        }
         return (await escalationService.resolveEntitySystem(query.entity)).map((s) => s.role);
     }
     if (query?.role)

package/build/api/escalations/bulk.d.ts

@@ -43,6 +43,8 @@ export declare function bulkClaim(input: {
  *
  * Non-superadmin callers must verify the target user holds each
  * escalation's role (the query form requires exactly the declared role).
+ * The query form also requires the caller to manage that role's queue
+ * (write_scope all); read-only and self-scope members may not assign.
  * Publishes claim events for assigned items.
  *
  * @param input.ids — array of escalation UUIDs (ids form)

package/build/api/escalations/bulk.js

@@ -128,6 +128,8 @@ async function bulkClaim(input, auth) {
  *
  * Non-superadmin callers must verify the target user holds each
  * escalation's role (the query form requires exactly the declared role).
+ * The query form also requires the caller to manage that role's queue
+ * (write_scope all); read-only and self-scope members may not assign.
  * Publishes claim events for assigned items.
  *
  * @param input.ids — array of escalation UUIDs (ids form)
@@ -163,14 +165,17 @@ async function bulkAssign(input, auth) {
             if (!query.role || typeof query.role !== 'string') {
                 return { status: 400, error: 'query.role is required' };
             }
-            // RBAC, query form: the caller must hold the queried role (or global),
-            // and the target user must hold it — one role check instead of per-id.
+            // RBAC, query form: the caller must manage the queried role's queue
+            // (write_scope all, or global), and the target user must hold the role.
             const hasGlobal = await (0, helpers_1.hasGlobalEscalationAccess)(auth.userId);
             if (!hasGlobal) {
-                const callerHasRole = await userService.hasRole(auth.userId, query.role);
-                if (!callerHasRole) {
+                const callerScope = await userService.getRoleScope(auth.userId, query.role);
+                if (!callerScope) {
                     return { status: 404, error: 'One or more escalations not found' };
                 }
+                if (callerScope.write !== 'all') {
+                    return { status: 403, error: `You do not have permission to manage the "${query.role}" queue` };
+                }
                 const targetHasRole = await userService.hasRole(targetUserId, query.role);
                 if (!targetHasRole) {
                     return { status: 400, error: `Target user does not hold the "${query.role}" role` };

package/build/api/escalations/helpers.d.ts

@@ -15,6 +15,11 @@ export interface EscalationReadScope {
     selfRoles: string[];
 }
 export declare function getEscalationReadScope(userId: string): Promise<EscalationReadScope>;
+/** Whether a read scope admits one escalation: the same rule as assertReadAccess, with no lookup. */
+export declare function scopeAdmits(scope: EscalationReadScope, userId: string, escalation: {
+    role: string;
+    assigned_to?: string | null;
+}): boolean;
 export declare function validateIds(ids: unknown): ids is string[];
 /**
  * Write-scope partition for metadata-driven resolve. Splits the user's roles by

package/build/api/escalations/helpers.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hasGlobalEscalationAccess = void 0;
 exports.getEscalationReadScope = getEscalationReadScope;
+exports.scopeAdmits = scopeAdmits;
 exports.validateIds = validateIds;
 exports.getEscalationWriteScope = getEscalationWriteScope;
 exports.assertReadAccess = assertReadAccess;
@@ -70,6 +71,12 @@ async function getEscalationReadScope(userId) {
     }
     return { global: false, allRoles, selfRoles };
 }
+/** Whether a read scope admits one escalation: the same rule as assertReadAccess, with no lookup. */
+function scopeAdmits(scope, userId, escalation) {
+    if (scope.global || scope.allRoles.includes(escalation.role))
+        return true;
+    return scope.selfRoles.includes(escalation.role) && escalation.assigned_to === userId;
+}
 function validateIds(ids) {
     return Array.isArray(ids) && ids.length > 0;
 }

package/build/api/escalations/metadata.js

@@ -73,6 +73,9 @@ async function findByMetadata(input, auth) {
         // WHERE and COUNT. Global access → no filter. Never filter a fetched page
         // controller-side — that shrinks the page and reports a wrong total.
         const scope = await (0, helpers_1.getEscalationReadScope)(auth.userId);
+        if (!scope.global && scope.allRoles.length === 0 && scope.selfRoles.length === 0) {
+            return { status: 200, data: { escalations: [], total: 0 } };
+        }
         const result = await escalationService.findByMetadata(input.key, input.value, input.status, input.limit, input.offset, scope.global
             ? undefined
             : { allRoles: scope.allRoles, selfRoles: scope.selfRoles, meUserId: auth.userId });

package/build/api/escalations/single.d.ts

@@ -12,14 +12,15 @@ export declare function getEscalation(input: {
     id: string;
 }, auth: LTApiAuth): Promise<LTApiResult>;
 /**
- * List all escalations for a given workflow ID.
+ * List the escalations for a given workflow ID. With `auth`, only the rows
+ * that caller may read; without it (in-process callers), every row.
  *
  * @param input.workflowId — HotMesh workflow ID
  * @returns `{ status: 200, data: { escalations } }`
  */
 export declare function getEscalationsByWorkflowId(input: {
     workflowId: string;
-}): Promise<LTApiResult>;
+}, auth?: LTApiAuth): Promise<LTApiResult>;
 /**
  * Route a pending escalation to a different role.
  *

package/build/api/escalations/single.js

@@ -69,14 +69,19 @@ async function getEscalation(input, auth) {
     }
 }
 /**
- * List all escalations for a given workflow ID.
+ * List the escalations for a given workflow ID. With `auth`, only the rows
+ * that caller may read; without it (in-process callers), every row.
  *
  * @param input.workflowId — HotMesh workflow ID
  * @returns `{ status: 200, data: { escalations } }`
  */
-async function getEscalationsByWorkflowId(input) {
+async function getEscalationsByWorkflowId(input, auth) {
     try {
-        const escalations = await escalationService.getEscalationsByWorkflowId(input.workflowId);
+        const all = await escalationService.getEscalationsByWorkflowId(input.workflowId);
+        if (!auth?.userId)
+            return { status: 200, data: { escalations: all } };
+        const scope = await (0, helpers_1.getEscalationReadScope)(auth.userId);
+        const escalations = all.filter((e) => (0, helpers_1.scopeAdmits)(scope, auth.userId, e));
         return { status: 200, data: { escalations } };
     }
     catch (err) {

package/build/api/mcp/tools.d.ts

@@ -1,4 +1,16 @@
+import type { CapabilityGate } from '../../types';
 import type { LTApiResult, LTApiAuth } from '../../types/sdk';
+/**
+ * The built-in server a server id or name refers to: the one a tool call would
+ * dispatch to, else a shipped factory whose name matches. Null for an external
+ * server. Matching both keeps the gate in force wherever the code runs.
+ */
+export declare function builtinServerFor(serverIdOrName: string): Promise<string | null>;
+/**
+ * The capability a built-in tool's manifest gates it at, from the manifest the
+ * server was registered with (Long Tail's or the host's). A tool without a gate needs builder.
+ */
+export declare function builtinToolGate(serverName: string, toolName: string): CapabilityGate;
 /**
  * List all tools exposed by a connected MCP server.
  *

package/build/api/mcp/tools.js

@@ -1,8 +1,92 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.builtinServerFor = builtinServerFor;
+exports.builtinToolGate = builtinToolGate;
 exports.listMcpServerTools = listMcpServerTools;
 exports.callMcpTool = callMcpTool;
 const mcp_1 = require("../../services/mcp");
+const mcpClient = __importStar(require("../../services/mcp/client"));
+const userService = __importStar(require("../../services/user"));
+const capabilities_1 = require("../../modules/capabilities");
+const workflow_invocation_1 = require("../../services/workflow-invocation");
+const system_1 = require("../../system");
+const uuid_1 = require("../../lib/uuid");
+const ROLE_TYPE_ORDER = ['superadmin', 'admin', 'member'];
+const normalizeName = (name) => name.replace(/[^a-zA-Z0-9]/g, '').toLowerCase();
+/**
+ * The built-in server a server id or name refers to: the one a tool call would
+ * dispatch to, else a shipped factory whose name matches. Null for an external
+ * server. Matching both keeps the gate in force wherever the code runs.
+ */
+async function builtinServerFor(serverIdOrName) {
+    const registered = await mcpClient.resolveBuiltinServerName(serverIdOrName);
+    if (registered)
+        return registered;
+    if (system_1.builtinMcpServerFactories[serverIdOrName])
+        return serverIdOrName;
+    const wanted = normalizeName(serverIdOrName);
+    if (!wanted)
+        return null;
+    return Object.keys(system_1.builtinMcpServerFactories).find((name) => {
+        const have = normalizeName(name);
+        return have.includes(wanted) || wanted.includes(have);
+    }) ?? null;
+}
+/**
+ * The capability a built-in tool's manifest gates it at, from the manifest the
+ * server was registered with (Long Tail's or the host's). A tool without a gate needs builder.
+ */
+function builtinToolGate(serverName, toolName) {
+    const manifest = mcpClient.getBuiltinToolManifest(serverName)
+        ?? system_1.builtinMcpServerFactories[serverName]?.config?.toolManifest;
+    return manifest?.find((t) => t.name === toolName)?.gate ?? 'builder';
+}
+/** The principal a tool call acts as: the caller, or an execute_as target the caller outranks. */
+async function actingPrincipal(auth, executeAs) {
+    if (!executeAs)
+        return { userId: auth.userId, role: auth.role };
+    await (0, workflow_invocation_1.assertMayActAs)(auth.userId, executeAs);
+    const target = (0, uuid_1.isUuid)(executeAs)
+        ? await userService.getUser(executeAs)
+        : await userService.getUserByExternalId(executeAs);
+    if (!target)
+        throw new workflow_invocation_1.InvocationError(`execute_as principal "${executeAs}" not found`, 404);
+    const role = ROLE_TYPE_ORDER.find((type) => target.roles.some((r) => r.type === type));
+    return { userId: target.id, role };
+}
 /**
  * List all tools exposed by a connected MCP server.
  *
@@ -41,22 +125,42 @@ async function listMcpServerTools(input) {
  */
 async function callMcpTool(input, auth) {
     try {
-        const adapter = mcp_1.mcpRegistry.current;
-        if (!adapter) {
-            return { status: 400, error: 'MCP adapter not registered' };
-        }
-        const effectiveUserId = input.execute_as || auth?.userId;
-        const authContext = effectiveUserId ? { userId: effectiveUserId } : undefined;
+        if (!auth?.userId)
+            return { status: 401, error: 'Authentication required' };
+        const actor = await actingPrincipal(auth, input.execute_as);
         // Inject user_id into arguments so builtin tools can resolve
         // the calling user's credentials (OAuth tokens, etc.)
         const args = { ...(input.arguments || {}) };
-        if (effectiveUserId && !args.user_id) {
-            args.user_id = effectiveUserId;
+        if (!args.user_id)
+            args.user_id = actor.userId;
+        // A built-in tool runs in this process. It is gated as /mcp gates it, by
+        // the tool's manifest capability for the acting principal (live, never a
+        // role claim), and runs as that principal rather than as lt-system.
+        const builtin = await builtinServerFor(input.id);
+        if (builtin) {
+            const permitted = await (0, capabilities_1.capabilityAccess)({ userId: actor.userId })(builtinToolGate(builtin, input.toolName));
+            if (!permitted)
+                return { status: 403, error: `Forbidden: ${input.toolName} is not available to you` };
+            const result = await mcpClient.callBuiltinToolAs(builtin, input.toolName, args, actor);
+            return { status: 200, data: { result } };
+        }
+        // An external server's tools run on its stored credential (headers, env),
+        // which carries that server's authority: a builder's to use.
+        if (!(await (0, capabilities_1.capabilityAccess)({ userId: actor.userId })('builder'))) {
+            return { status: 403, error: `Forbidden: tools on an external MCP server need builder access` };
+        }
+        const adapter = mcp_1.mcpRegistry.current;
+        if (!adapter) {
+            return { status: 400, error: 'MCP adapter not registered' };
         }
-        const result = await adapter.callTool(input.id, input.toolName, args, authContext);
+        const result = await adapter.callTool(input.id, input.toolName, args, { userId: actor.userId });
         return { status: 200, data: { result } };
     }
     catch (err) {
+        if (err instanceof workflow_invocation_1.InvocationError)
+            return { status: err.statusCode, error: err.message };
+        if (err.name === 'ToolNotFoundError')
+            return { status: 404, error: err.message };
         if (err.name === 'MissingCredentialError') {
             return {
                 status: 422,

package/build/api/scan-codes/choice.js

@@ -39,6 +39,7 @@ const escalationService = __importStar(require("../../services/escalation"));
 const types_1 = require("../../types");
 const identity_1 = require("./identity");
 const grant_1 = require("./grant");
+const helpers_1 = require("../escalations/helpers");
 const context_1 = require("./context");
 const locate_1 = require("./locate");
 const verbs_1 = require("./verbs");
@@ -84,9 +85,21 @@ async function executeScanChoice(input, auth) {
             effectiveAuth = peeked.auth;
             grant = peeked.grant;
         }
-        // 3. The row anchors the target: the scheme's facet on the escalation the
-        // screen presented. A missing binding is loud misconfiguration.
-        const row = await escalationService.getEscalation(input.escalationId);
+        // 3. With no live grant, a choice that needs a badge parks for the next
+        // badge scan before any row is read, whatever the station may read.
+        if (!grant && choice.requireActingIdentity
+            && !(await (0, identity_1.actingIdentitySatisfied)(step, { stationAuth: auth, acting: false }))) {
+            return stampPointer((0, context_1.notPrimed)({ rule }), rule, input);
+        }
+        // 4. The row anchors the target: the scheme's facet on the escalation the
+        // screen presented. A missing binding is loud misconfiguration. A row the
+        // actor may not read answers as one that left the presented state, and
+        // discloses nothing of the row.
+        const loaded = await escalationService.getEscalation(input.escalationId);
+        if (loaded && (await (0, helpers_1.assertReadAccess)(effectiveAuth.userId, loaded))) {
+            return stampPointer((0, context_1.conflict)('the item is no longer in the presented state'), rule, input);
+        }
+        const row = loaded;
         const target = row?.metadata?.[scheme.target_facet];
         if (!row || typeof target !== 'string' || !target) {
             return {
@@ -104,11 +117,11 @@ async function executeScanChoice(input, auth) {
             acting: !!grant,
             grant,
         };
-        // 4. The identity gate, per the choice.
+        // 5. The identity gate, per the choice.
         if (choice.requireActingIdentity && !(await (0, identity_1.actingIdentitySatisfied)(step, ctx))) {
             return decorate((0, context_1.notPrimed)(ctx), ctx, input);
         }
-        // 5. The row must still match the step's query — the reality the screen
+        // 6. The row must still match the step's query — the reality the screen
         // showed. A row that moved on (resolved, claimed away, re-routed) is the
         // same double-actor race a second scan loses.
         const located = await (0, locate_1.locateForStep)(step, ctx, 2);
@@ -116,10 +129,10 @@ async function executeScanChoice(input, auth) {
         if (!presented) {
             return decorate((0, context_1.conflict)('the item is no longer in the presented state'), ctx, input);
         }
-        // 6. Dispatch through the same atomic executors a direct scan uses.
+        // 7. Dispatch through the same atomic executors a direct scan uses.
         const synthesized = { query: step.query, verb: choice.verb, params: choice.params };
         const result = decorate(await (0, verbs_1.dispatchChoiceVerb)(synthesized, ctx, presented), ctx, input);
-        // 7. Settle the badge: refund a spend whose act did not land
+        // 8. Settle the badge: refund a spend whose act did not land
         const acting = await (0, grant_1.settleGrant)(ctx, result);
         if (acting && result.data)
             result.data = { ...result.data, acting };
@@ -129,6 +142,17 @@ async function executeScanChoice(input, auth) {
         return { status: 500, error: err.message };
     }
 }
+/** Stamp the rule and pointer onto an outcome decided before the row was read. */
+function stampPointer(result, rule, input) {
+    if (result.data && typeof result.data === 'object' && 'outcome' in result.data) {
+        result.data = {
+            ...result.data,
+            rule: { schemeVersion: rule.scheme_version, category: rule.category, name: rule.name },
+            stepIndex: input.stepIndex,
+        };
+    }
+    return result;
+}
 /** Stamp the rule + pointer identity onto the outcome, mirroring execute. */
 function decorate(result, ctx, input) {
     if (result.data && typeof result.data === 'object' && 'outcome' in result.data) {