@hotmeshio/long-tail 0.4.18 → 0.4.20

package/build/services/agent/input-mapper.js

@@ -40,7 +40,23 @@ function applyInputMapping(mapping, event) {
         if (typeof value === 'string') {
             result[key] = resolveTemplate(value, event);
         }
-        else if (value && typeof value === 'object' && !Array.isArray(value)) {
+        else if (Array.isArray(value)) {
+            result[key] = value.map((item) => {
+                if (typeof item === 'string') {
+                    const resolved = resolveTemplate(item, event);
+                    // Coerce scalars to strings when the template was a string in an array context.
+                    // Objects/arrays pass through (e.g., "{event.data}" resolves to the full object).
+                    if (resolved !== null && resolved !== undefined && typeof resolved !== 'object') {
+                        return String(resolved);
+                    }
+                    return resolved;
+                }
+                if (item && typeof item === 'object')
+                    return applyInputMapping(item, event);
+                return item;
+            });
+        }
+        else if (value && typeof value === 'object') {
             result[key] = applyInputMapping(value, event);
         }
         else {

package/build/services/escalation/crud.d.ts

@@ -49,4 +49,20 @@ export declare function findByMetadata(key: string, value: string, status?: stri
     escalations: LTEscalationRecord[];
     total: number;
 }>;
-export declare function claimByMetadata(key: string, value: string, userId: string, durationMinutes?: number, metadata?: Record<string, any>): Promise<ClaimResult | null>;
+/**
+ * Atomic claim by metadata with inline RBAC.
+ * The SQL WHERE clause enforces role membership — if the caller
+ * doesn't have an allowed role, zero rows match and the claim
+ * never happens. No pre-flight find, no TOCTOU.
+ *
+ * @param allowedRoles — roles the caller can claim (null = no filter / global access)
+ * @returns `{ escalation, isExtension, candidatesExist }` or null
+ */
+export declare function claimByMetadata(key: string, value: string, userId: string, durationMinutes?: number, metadata?: Record<string, any>, allowedRoles?: string[] | null): Promise<(ClaimResult & {
+    candidatesExist: number;
+}) | null>;
+/**
+ * Atomic resolve by metadata: find + claim + resolve in one CTE.
+ * RBAC is enforced in the SQL WHERE clause via allowedRoles.
+ */
+export declare function resolveByMetadataAtomic(key: string, value: string, userId: string, resolverPayload: Record<string, any>, metadata?: Record<string, any>, allowedRoles?: string[] | null): Promise<LTEscalationRecord | null>;

package/build/services/escalation/crud.js

@@ -16,6 +16,7 @@ exports.enrichEscalationRouting = enrichEscalationRouting;
 exports.getEscalationsByOriginId = getEscalationsByOriginId;
 exports.findByMetadata = findByMetadata;
 exports.claimByMetadata = claimByMetadata;
+exports.resolveByMetadataAtomic = resolveByMetadataAtomic;
 const db_1 = require("../../lib/db");
 const publish_1 = require("../../lib/events/publish");
 const logger_1 = require("../../lib/logger");
@@ -135,7 +136,20 @@ async function getEscalationRoles(ids) {
 async function releaseEscalation(id, userId) {
     const pool = (0, db_1.getPool)();
     const { rows } = await pool.query(sql_1.RELEASE_ESCALATION, [id, userId]);
-    return rows[0] || null;
+    const released = rows[0];
+    if (released) {
+        (0, publish_1.publishEscalationEvent)({
+            type: 'escalation.released',
+            source: 'service',
+            workflowId: released.workflow_id || '',
+            workflowName: released.workflow_type || '',
+            taskQueue: released.task_queue || '',
+            escalationId: released.id,
+            status: 'released',
+            data: { released_by: userId },
+        });
+    }
+    return released || null;
 }
 async function releaseExpiredClaims() {
     const pool = (0, db_1.getPool)();
@@ -192,24 +206,32 @@ async function getEscalationsByOriginId(originId) {
 async function findByMetadata(key, value, status, limit = 50, offset = 0) {
     const pool = (0, db_1.getPool)();
     const filter = JSON.stringify({ [key]: value });
-    const [countResult, dataResult] = await Promise.all([
-        pool.query(sql_1.COUNT_BY_METADATA, [filter, status || null]),
-        pool.query(sql_1.FIND_BY_METADATA, [filter, status || null, limit, offset]),
-    ]);
-    return {
-        escalations: dataResult.rows,
-        total: parseInt(countResult.rows[0].count, 10),
-    };
+    const { rows } = await pool.query(sql_1.FIND_BY_METADATA, [filter, status || null, limit, offset]);
+    const total = rows.length > 0 ? parseInt(rows[0]._total, 10) : 0;
+    // Strip the window function column from results
+    const escalations = rows.map(({ _total, ...rest }) => rest);
+    return { escalations, total };
 }
-async function claimByMetadata(key, value, userId, durationMinutes = 30, metadata) {
+/**
+ * Atomic claim by metadata with inline RBAC.
+ * The SQL WHERE clause enforces role membership — if the caller
+ * doesn't have an allowed role, zero rows match and the claim
+ * never happens. No pre-flight find, no TOCTOU.
+ *
+ * @param allowedRoles — roles the caller can claim (null = no filter / global access)
+ * @returns `{ escalation, isExtension, candidatesExist }` or null
+ */
+async function claimByMetadata(key, value, userId, durationMinutes = 30, metadata, allowedRoles) {
     const pool = (0, db_1.getPool)();
     const filter = JSON.stringify({ [key]: value });
     const metaPatch = metadata ? JSON.stringify(metadata) : null;
-    const { rows } = await pool.query(sql_1.CLAIM_BY_METADATA, [filter, userId, durationMinutes, metaPatch]);
+    const roles = allowedRoles ?? null;
+    const { rows } = await pool.query(sql_1.CLAIM_BY_METADATA_GUARDED, [filter, userId, durationMinutes, metaPatch, roles]);
     if (rows.length === 0)
         return null;
     const row = rows[0];
-    const escalation = row;
+    const { candidates_exist, prev_assigned_to, _total, ...rest } = row;
+    const escalation = rest;
     (0, publish_1.publishEscalationEvent)({
         type: 'escalation.claimed',
         source: 'service',
@@ -222,6 +244,33 @@ async function claimByMetadata(key, value, userId, durationMinutes = 30, metadat
     });
     return {
         escalation,
-        isExtension: row.prev_assigned_to === userId,
+        isExtension: prev_assigned_to === userId,
+        candidatesExist: parseInt(candidates_exist, 10),
     };
 }
+/**
+ * Atomic resolve by metadata: find + claim + resolve in one CTE.
+ * RBAC is enforced in the SQL WHERE clause via allowedRoles.
+ */
+async function resolveByMetadataAtomic(key, value, userId, resolverPayload, metadata, allowedRoles) {
+    const pool = (0, db_1.getPool)();
+    const filter = JSON.stringify({ [key]: value });
+    const payloadJson = JSON.stringify(resolverPayload);
+    const metaPatch = metadata ? JSON.stringify(metadata) : null;
+    const roles = allowedRoles ?? null;
+    const { rows } = await pool.query(sql_1.RESOLVE_BY_METADATA_ATOMIC, [filter, userId, payloadJson, metaPatch, roles]);
+    if (rows.length === 0)
+        return null;
+    const escalation = rows[0];
+    (0, publish_1.publishEscalationEvent)({
+        type: 'escalation.resolved',
+        source: 'service',
+        workflowId: escalation.workflow_id || '',
+        workflowName: escalation.workflow_type || '',
+        taskQueue: escalation.task_queue || '',
+        escalationId: escalation.id,
+        status: 'resolved',
+        data: { resolved_by: userId },
+    });
+    return escalation;
+}

package/build/services/escalation/queries.d.ts

@@ -8,6 +8,7 @@ export declare function listEscalations(filters: {
     type?: string;
     subtype?: string;
     assigned_to?: string;
+    claimed?: boolean;
     priority?: number;
     limit?: number;
     offset?: number;

package/build/services/escalation/queries.js

@@ -96,6 +96,13 @@ async function listEscalations(filters) {
     if (filters.assigned_to) {
         conditions.push(`assigned_to = $${idx++}`);
         values.push(filters.assigned_to);
+        // Only return active claims — expired claims are back in the available pool
+        conditions.push('assigned_until > NOW()');
+    }
+    if (filters.claimed) {
+        // All actively claimed escalations (by anyone)
+        conditions.push('assigned_to IS NOT NULL');
+        conditions.push('assigned_until > NOW()');
     }
     if (filters.priority) {
         conditions.push(`priority = $${idx++}`);

package/build/services/escalation/sql.d.ts

@@ -19,8 +19,17 @@ export declare const BULK_RESOLVE_FOR_TRIAGE = "UPDATE lt_escalations\nSET statu
 export declare const UPDATE_ESCALATION_METADATA = "UPDATE lt_escalations\nSET metadata = COALESCE(metadata, '{}'::jsonb) || $2::jsonb,\n    updated_at = NOW()\nWHERE id = $1\nRETURNING *";
 export declare const ENRICH_ESCALATION_ROUTING = "UPDATE lt_escalations\nSET metadata = COALESCE(metadata, '{}'::jsonb) || $2::jsonb,\n    workflow_type = COALESCE(workflow_type, $3),\n    workflow_id = COALESCE(workflow_id, $4),\n    task_queue = COALESCE(task_queue, $5),\n    task_id = COALESCE(task_id, $6),\n    updated_at = NOW()\nWHERE id = $1\nRETURNING *";
 export declare const LIST_DISTINCT_TYPES = "SELECT DISTINCT type FROM lt_escalations ORDER BY type";
-/** Find escalations by a single metadata key-value pair. */
-export declare const FIND_BY_METADATA = "SELECT * FROM lt_escalations\nWHERE metadata @> $1::jsonb\n  AND ($2::text IS NULL OR status = $2)\nORDER BY priority ASC, created_at ASC\nLIMIT $3 OFFSET $4";
-export declare const COUNT_BY_METADATA = "SELECT COUNT(*) FROM lt_escalations\nWHERE metadata @> $1::jsonb\n  AND ($2::text IS NULL OR status = $2)";
-/** Atomic claim by metadata: find one available escalation, claim it, and optionally merge metadata. */
-export declare const CLAIM_BY_METADATA = "WITH target AS (\n  SELECT id, assigned_to\n  FROM lt_escalations\n  WHERE metadata @> $1::jsonb\n    AND status = 'pending'\n    AND (\n      assigned_to IS NULL\n      OR assigned_until <= NOW()\n      OR assigned_to = $2\n    )\n  ORDER BY priority ASC, created_at ASC\n  LIMIT 1\n  FOR UPDATE SKIP LOCKED\n),\nupdated AS (\n  UPDATE lt_escalations e\n  SET assigned_to = $2,\n      claimed_at = NOW(),\n      assigned_until = NOW() + INTERVAL '1 minute' * $3,\n      metadata = CASE WHEN $4::jsonb IS NOT NULL\n        THEN COALESCE(e.metadata, '{}'::jsonb) || $4::jsonb\n        ELSE e.metadata END\n  FROM target t\n  WHERE e.id = t.id\n  RETURNING e.*, t.assigned_to AS prev_assigned_to\n)\nSELECT * FROM updated";
+/** Find escalations by a single metadata key-value pair. Window function for total count. */
+export declare const FIND_BY_METADATA = "SELECT *, COUNT(*) OVER() AS _total\nFROM lt_escalations\nWHERE metadata @> $1::jsonb\n  AND ($2::text IS NULL OR status = $2)\nORDER BY priority ASC, created_at ASC\nLIMIT $3 OFFSET $4";
+/**
+ * Atomic claim by metadata with inline RBAC.
+ * $1 = metadata filter (jsonb), $2 = userId, $3 = durationMinutes,
+ * $4 = metadata patch (jsonb, nullable), $5 = allowed roles (text[], null = no filter)
+ */
+export declare const CLAIM_BY_METADATA_GUARDED = "WITH target AS (\n  SELECT id, assigned_to\n  FROM lt_escalations\n  WHERE metadata @> $1::jsonb\n    AND status = 'pending'\n    AND (assigned_to IS NULL OR assigned_until <= NOW() OR assigned_to = $2)\n    AND ($5::text[] IS NULL OR role = ANY($5))\n  ORDER BY priority ASC, created_at ASC\n  LIMIT 1\n  FOR UPDATE SKIP LOCKED\n),\nupdated AS (\n  UPDATE lt_escalations e\n  SET assigned_to = $2,\n      claimed_at = NOW(),\n      assigned_until = NOW() + INTERVAL '1 minute' * $3,\n      metadata = CASE WHEN $4::jsonb IS NOT NULL\n        THEN COALESCE(e.metadata, '{}'::jsonb) || $4::jsonb\n        ELSE e.metadata END,\n      updated_at = NOW()\n  FROM target t\n  WHERE e.id = t.id\n  RETURNING e.*, t.assigned_to AS prev_assigned_to\n)\nSELECT *,\n  (SELECT COUNT(*) FROM lt_escalations WHERE metadata @> $1::jsonb AND status = 'pending') AS candidates_exist\nFROM updated";
+/**
+ * Atomic resolve by metadata: find + claim + resolve in one CTE.
+ * $1 = metadata filter (jsonb), $2 = userId, $3 = resolver_payload (jsonb),
+ * $4 = metadata patch (jsonb, nullable), $5 = allowed roles (text[], null = no filter)
+ */
+export declare const RESOLVE_BY_METADATA_ATOMIC = "WITH target AS (\n  SELECT id\n  FROM lt_escalations\n  WHERE metadata @> $1::jsonb\n    AND status = 'pending'\n    AND ($5::text[] IS NULL OR role = ANY($5))\n  ORDER BY priority ASC, created_at ASC\n  LIMIT 1\n  FOR UPDATE SKIP LOCKED\n),\nclaimed AS (\n  UPDATE lt_escalations e\n  SET assigned_to = $2,\n      claimed_at = NOW(),\n      assigned_until = NOW() + INTERVAL '5 minutes',\n      metadata = CASE WHEN $4::jsonb IS NOT NULL\n        THEN COALESCE(e.metadata, '{}'::jsonb) || $4::jsonb\n        ELSE e.metadata END\n  FROM target\n  WHERE e.id = target.id\n  RETURNING e.*\n)\nUPDATE lt_escalations e\nSET status = 'resolved',\n    resolved_at = NOW(),\n    resolver_payload = $3,\n    updated_at = NOW()\nFROM claimed\nWHERE e.id = claimed.id\nRETURNING e.*";

package/build/services/escalation/sql.js

@@ -3,7 +3,7 @@
 // Escalation SQL – externalized from crud.ts, bulk.ts, queries.ts
 // ---------------------------------------------------------------------------
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CLAIM_BY_METADATA = exports.COUNT_BY_METADATA = exports.FIND_BY_METADATA = exports.LIST_DISTINCT_TYPES = exports.ENRICH_ESCALATION_ROUTING = exports.UPDATE_ESCALATION_METADATA = exports.BULK_RESOLVE_FOR_TRIAGE = exports.BULK_ESCALATE_TO_ROLE = exports.BULK_ASSIGN = exports.BULK_CLAIM = exports.GET_ESCALATIONS_BY_ORIGIN_ID = exports.GET_ESCALATIONS_BY_WORKFLOW_ID = exports.GET_ESCALATIONS_BY_TASK_ID = exports.GET_ESCALATION = exports.ESCALATE_TO_ROLE = exports.RELEASE_EXPIRED_CLAIMS = exports.RELEASE_ESCALATION = exports.GET_ESCALATION_ROLES = exports.UPDATE_ESCALATIONS_PRIORITY = exports.RESOLVE_ESCALATION = exports.CLAIM_ESCALATION = exports.CREATE_ESCALATION = exports.ENSURE_ROLE_EXISTS = void 0;
+exports.RESOLVE_BY_METADATA_ATOMIC = exports.CLAIM_BY_METADATA_GUARDED = exports.FIND_BY_METADATA = exports.LIST_DISTINCT_TYPES = exports.ENRICH_ESCALATION_ROUTING = exports.UPDATE_ESCALATION_METADATA = exports.BULK_RESOLVE_FOR_TRIAGE = exports.BULK_ESCALATE_TO_ROLE = exports.BULK_ASSIGN = exports.BULK_CLAIM = exports.GET_ESCALATIONS_BY_ORIGIN_ID = exports.GET_ESCALATIONS_BY_WORKFLOW_ID = exports.GET_ESCALATIONS_BY_TASK_ID = exports.GET_ESCALATION = exports.ESCALATE_TO_ROLE = exports.RELEASE_EXPIRED_CLAIMS = exports.RELEASE_ESCALATION = exports.GET_ESCALATION_ROLES = exports.UPDATE_ESCALATIONS_PRIORITY = exports.RESOLVE_ESCALATION = exports.CLAIM_ESCALATION = exports.CREATE_ESCALATION = exports.ENSURE_ROLE_EXISTS = void 0;
 // --- Role management -------------------------------------------------------
 exports.ENSURE_ROLE_EXISTS = 'INSERT INTO lt_roles (role) VALUES ($1) ON CONFLICT DO NOTHING';
 // --- Single-record CRUD ---------------------------------------------------
@@ -134,29 +134,27 @@ WHERE id = $1
 RETURNING *`;
 exports.LIST_DISTINCT_TYPES = 'SELECT DISTINCT type FROM lt_escalations ORDER BY type';
 // --- Metadata candidate key lookups -----------------------------------------
-/** Find escalations by a single metadata key-value pair. */
+/** Find escalations by a single metadata key-value pair. Window function for total count. */
 exports.FIND_BY_METADATA = `\
-SELECT * FROM lt_escalations
+SELECT *, COUNT(*) OVER() AS _total
+FROM lt_escalations
 WHERE metadata @> $1::jsonb
   AND ($2::text IS NULL OR status = $2)
 ORDER BY priority ASC, created_at ASC
 LIMIT $3 OFFSET $4`;
-exports.COUNT_BY_METADATA = `\
-SELECT COUNT(*) FROM lt_escalations
-WHERE metadata @> $1::jsonb
-  AND ($2::text IS NULL OR status = $2)`;
-/** Atomic claim by metadata: find one available escalation, claim it, and optionally merge metadata. */
-exports.CLAIM_BY_METADATA = `\
+/**
+ * Atomic claim by metadata with inline RBAC.
+ * $1 = metadata filter (jsonb), $2 = userId, $3 = durationMinutes,
+ * $4 = metadata patch (jsonb, nullable), $5 = allowed roles (text[], null = no filter)
+ */
+exports.CLAIM_BY_METADATA_GUARDED = `\
 WITH target AS (
   SELECT id, assigned_to
   FROM lt_escalations
   WHERE metadata @> $1::jsonb
     AND status = 'pending'
-    AND (
-      assigned_to IS NULL
-      OR assigned_until <= NOW()
-      OR assigned_to = $2
-    )
+    AND (assigned_to IS NULL OR assigned_until <= NOW() OR assigned_to = $2)
+    AND ($5::text[] IS NULL OR role = ANY($5))
   ORDER BY priority ASC, created_at ASC
   LIMIT 1
   FOR UPDATE SKIP LOCKED
@@ -168,9 +166,48 @@ updated AS (
       assigned_until = NOW() + INTERVAL '1 minute' * $3,
       metadata = CASE WHEN $4::jsonb IS NOT NULL
         THEN COALESCE(e.metadata, '{}'::jsonb) || $4::jsonb
-        ELSE e.metadata END
+        ELSE e.metadata END,
+      updated_at = NOW()
   FROM target t
   WHERE e.id = t.id
   RETURNING e.*, t.assigned_to AS prev_assigned_to
 )
-SELECT * FROM updated`;
+SELECT *,
+  (SELECT COUNT(*) FROM lt_escalations WHERE metadata @> $1::jsonb AND status = 'pending') AS candidates_exist
+FROM updated`;
+/**
+ * Atomic resolve by metadata: find + claim + resolve in one CTE.
+ * $1 = metadata filter (jsonb), $2 = userId, $3 = resolver_payload (jsonb),
+ * $4 = metadata patch (jsonb, nullable), $5 = allowed roles (text[], null = no filter)
+ */
+exports.RESOLVE_BY_METADATA_ATOMIC = `\
+WITH target AS (
+  SELECT id
+  FROM lt_escalations
+  WHERE metadata @> $1::jsonb
+    AND status = 'pending'
+    AND ($5::text[] IS NULL OR role = ANY($5))
+  ORDER BY priority ASC, created_at ASC
+  LIMIT 1
+  FOR UPDATE SKIP LOCKED
+),
+claimed AS (
+  UPDATE lt_escalations e
+  SET assigned_to = $2,
+      claimed_at = NOW(),
+      assigned_until = NOW() + INTERVAL '5 minutes',
+      metadata = CASE WHEN $4::jsonb IS NOT NULL
+        THEN COALESCE(e.metadata, '{}'::jsonb) || $4::jsonb
+        ELSE e.metadata END
+  FROM target
+  WHERE e.id = target.id
+  RETURNING e.*
+)
+UPDATE lt_escalations e
+SET status = 'resolved',
+    resolved_at = NOW(),
+    resolver_payload = $3,
+    updated_at = NOW()
+FROM claimed
+WHERE e.id = claimed.id
+RETURNING e.*`;

package/build/services/mcp/exposure.d.ts

@@ -0,0 +1,15 @@
+/**
+ * MCP exposure configuration — controls which tools are visible
+ * when long-tail acts as an MCP server for external clients.
+ *
+ * Set once at startup from startConfig.mcp.exposure.
+ * Read by the /mcp endpoint handler on each request.
+ */
+export interface ExposureConfig {
+    readOnly?: boolean;
+    hideAiWhenUnavailable?: boolean;
+    allowServers?: string[];
+    denyServers?: string[];
+}
+export declare function setExposureConfig(config?: ExposureConfig): void;
+export declare function getExposureConfig(): ExposureConfig | undefined;

package/build/services/mcp/exposure.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * MCP exposure configuration — controls which tools are visible
+ * when long-tail acts as an MCP server for external clients.
+ *
+ * Set once at startup from startConfig.mcp.exposure.
+ * Read by the /mcp endpoint handler on each request.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setExposureConfig = setExposureConfig;
+exports.getExposureConfig = getExposureConfig;
+let _exposure;
+function setExposureConfig(config) {
+    _exposure = config;
+}
+function getExposureConfig() {
+    return _exposure;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Unified MCP server for external clients.
+ *
+ * Aggregates tools from all shipped built-in servers into a single
+ * McpServer instance that can be connected to a StreamableHTTPServerTransport.
+ * Created per-request in stateless mode (pure in-memory, no IO).
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ExposureConfig } from './exposure';
+/**
+ * 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).
+ */
+export declare function createUnifiedMcpServer(exposure?: ExposureConfig, callerScopes?: string[]): Promise<McpServer>;

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

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * Unified MCP server for external clients.
+ *
+ * Aggregates tools from all shipped built-in servers into a single
+ * McpServer instance that can be connected to a StreamableHTTPServerTransport.
+ * Created per-request in stateless mode (pure in-memory, no IO).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createUnifiedMcpServer = createUnifiedMcpServer;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const logger_1 = require("../../lib/logger");
+const system_1 = require("../../system");
+// ── 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([
+    'long-tail-admin',
+    'long-tail-human-queue',
+    'long-tail-file-storage',
+    'long-tail-http-fetch',
+    'long-tail-schema-exchange',
+    'long-tail-oauth',
+    'long-tail-knowledge',
+    'long-tail-docs',
+    'long-tail-events',
+    'long-tail-vision',
+    'long-tail-translation',
+    'long-tail-claude-code',
+]);
+// ── Server instance cache ────────────────────────────────────────────────────
+// Built-in servers are lazily created once and reused across requests.
+// Tool handlers are stateless — safe to share.
+const serverCache = new Map();
+async function getOrCreateServer(name) {
+    if (serverCache.has(name))
+        return serverCache.get(name);
+    const entry = system_1.builtinMcpServerFactories[name];
+    if (!entry)
+        return null;
+    const server = await entry.factory();
+    serverCache.set(name, server);
+    return server;
+}
+// ── Exposure filtering ───────────────────────────────────────────────────────
+function isServerAllowed(name, exposure) {
+    if (!SHIPPED_SERVERS.has(name))
+        return false;
+    if (exposure?.allowServers?.length) {
+        if (!exposure.allowServers.includes(name))
+            return false;
+    }
+    if (exposure?.denyServers?.length) {
+        if (exposure.denyServers.includes(name))
+            return false;
+    }
+    if (exposure?.hideAiWhenUnavailable !== false) {
+        const config = system_1.builtinMcpServerFactories[name]?.config;
+        if (config?.aiRequired) {
+            const hasKey = !!(process.env.OPENAI_API_KEY || process.env.ANTHROPIC_API_KEY);
+            if (!hasKey)
+                return false;
+        }
+    }
+    return true;
+}
+function isToolAllowed(toolName, serverName, exposure, callerScopes) {
+    // Per-caller scope filtering: mcp:read callers only see read_safe tools
+    const isReadOnly = exposure?.readOnly
+        || (callerScopes?.length && callerScopes.includes('mcp:read') && !callerScopes.includes('mcp:full'));
+    if (!isReadOnly)
+        return true;
+    // Check read_safe in the tool manifest
+    const config = system_1.builtinMcpServerFactories[serverName]?.config;
+    const manifest = config?.toolManifest;
+    if (!manifest)
+        return true; // no manifest = allow (conservative)
+    const entry = manifest.find((t) => t.name === toolName);
+    return entry?.read_safe !== false; // allow if read_safe is true or absent
+}
+// ── 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).
+ */
+async function createUnifiedMcpServer(exposure, callerScopes) {
+    const unified = new mcp_js_1.McpServer({ name: 'long-tail', version: '1.0.0' });
+    const registered = new Set();
+    for (const [name, entry] of Object.entries(system_1.builtinMcpServerFactories)) {
+        if (!isServerAllowed(name, exposure))
+            continue;
+        const server = await getOrCreateServer(name);
+        if (!server)
+            continue;
+        const tools = server._registeredTools;
+        if (!tools)
+            continue;
+        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
+            let finalName = toolName;
+            if (registered.has(toolName)) {
+                const prefix = name.replace('long-tail-', '').replace(/-/g, '_');
+                finalName = `${prefix}_${toolName}`;
+                if (registered.has(finalName))
+                    continue; // still a collision — skip
+            }
+            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.
+            unified.registerTool(finalName, {
+                title: tool.title,
+                description: tool.description,
+                inputSchema: tool.inputSchema,
+                annotations: tool.annotations,
+            }, tool.handler);
+        }
+    }
+    logger_1.loggerRegistry.info(`[lt-mcp:endpoint] unified server ready (${registered.size} tools)`);
+    return unified;
+}

package/build/services/mcp/seed-service-account.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Seed the MCP service account at startup.
+ *
+ * Creates a single `mcp-service` bot account with two API keys:
+ *   - `mcp:read`  — read-safe tools only (discovery, monitoring)
+ *   - `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.
+ */
+export declare function seedMcpServiceAccount(): Promise<void>;

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

@@ -0,0 +1,77 @@
+"use strict";
+/**
+ * Seed the MCP service account at startup.
+ *
+ * Creates a single `mcp-service` bot account with two API keys:
+ *   - `mcp:read`  — read-safe tools only (discovery, monitoring)
+ *   - `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.
+ */
+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.seedMcpServiceAccount = seedMcpServiceAccount;
+const logger_1 = require("../../lib/logger");
+const crud_1 = require("../user/crud");
+const iam = __importStar(require("../iam"));
+const SERVICE_ACCOUNT_NAME = 'mcp-service';
+async function seedMcpServiceAccount() {
+    try {
+        // Check if account already exists (bot external_id = name)
+        const existing = await (0, crud_1.getUserByExternalId)(SERVICE_ACCOUNT_NAME);
+        if (existing) {
+            logger_1.loggerRegistry.info(`[seed-mcp] ${SERVICE_ACCOUNT_NAME} already exists, skipping`);
+            return;
+        }
+        // Create the service account
+        const bot = await iam.createBot({
+            name: SERVICE_ACCOUNT_NAME,
+            description: 'MCP service account for external tool access. Use the read key to explore, full key to automate.',
+            display_name: 'MCP Service',
+            roles: [{ role: 'system', type: 'member' }],
+        });
+        // Generate read key (scoped to mcp:read)
+        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`);
+    }
+    catch (err) {
+        logger_1.loggerRegistry.warn(`[seed-mcp] failed to seed: ${err.message}`);
+    }
+}

package/build/services/role/index.d.ts

@@ -21,7 +21,7 @@ export declare function removeEscalationChain(sourceRole: string, targetRole: st
 export declare function replaceEscalationTargets(sourceRole: string, targets: string[]): Promise<void>;
 /**
  * Check whether a user can escalate from sourceRole to targetRole.
- * Superadmins can escalate to any role.
+ * Superadmins and admin/admin can escalate to any role.
  * Others must hold the sourceRole AND the chain must exist.
  */
 export declare function canEscalateTo(userId: string, sourceRole: string, targetRole: string): Promise<boolean>;

package/build/services/role/index.js

@@ -74,11 +74,11 @@ async function replaceEscalationTargets(sourceRole, targets) {
 }
 /**
  * Check whether a user can escalate from sourceRole to targetRole.
- * Superadmins can escalate to any role.
+ * Superadmins and admin/admin can escalate to any role.
  * Others must hold the sourceRole AND the chain must exist.
  */
 async function canEscalateTo(userId, sourceRole, targetRole) {
-    if (await (0, user_1.isSuperAdmin)(userId))
+    if (await (0, user_1.hasGlobalEscalationAccess)(userId))
         return true;
     if (!(await (0, user_1.hasRole)(userId, sourceRole)))
         return false;