@hotmeshio/long-tail 0.5.11 → 0.5.12

package/build/services/escalation/sql.js

@@ -11,7 +11,8 @@
 // `hmsh_escalations` here rather than composed from generic SDK calls.
 // ---------------------------------------------------------------------------
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RESOLVE_BY_METADATA_ATOMIC = exports.RELEASE_EXPIRED_CLAIMS = void 0;
+exports.RESOLVE_BY_METADATA_ATOMIC = exports.COUNT_SEARCH_ESCALATIONS = exports.RELEASE_EXPIRED_CLAIMS = void 0;
+exports.searchEscalationsQuery = searchEscalationsQuery;
 /**
  * Sweep expired claims back to the available pool.
  *
@@ -31,6 +32,54 @@ SET assigned_to = NULL,
 WHERE status = 'pending'
   AND assigned_to IS NOT NULL
   AND assigned_until <= NOW()`;
+/**
+ * Free-text escalation search.
+ *
+ * The SDK's `client.list()` filters by structured columns only — it has no
+ * free-text predicate. Long-tail's contract needs a search box that matches a
+ * correlation key (order id, ticket id) or any visible field across the WHOLE
+ * result set, not just the current page. That is server-side SQL here (over the
+ * `lt_escalations` view, which adds the computed `available` flag), following the
+ * same raw-SQL-on-the-shared-table pattern as the atomic resolve below — so the
+ * filter flows SQL→service→API→route→dashboard rather than being faked client-side.
+ *
+ * All structured filters are optional and combine with the search term (AND).
+ * `metadata::text ILIKE` scans the JSONB as text (the GIN index is containment-only
+ * and cannot serve ILIKE) — bounded in practice by the other filters and the page.
+ *
+ * $1 status, $2 role, $3 roles (text[] visibleRoles), $4 type, $5 subtype,
+ * $6 priority, $7 assigned_to, $8 available (bool), $9 search.
+ * The list query adds $10 limit, $11 offset.
+ */
+const SEARCH_ESCALATIONS_WHERE = `\
+  FROM public.lt_escalations
+  WHERE ($1::text IS NULL OR status = $1)
+    AND ($2::text IS NULL OR role = $2)
+    AND ($3::text[] IS NULL OR role = ANY($3))
+    AND ($4::text IS NULL OR type = $4)
+    AND ($5::text IS NULL OR subtype = $5)
+    AND ($6::int IS NULL OR priority = $6)
+    AND ($7::text IS NULL OR assigned_to = $7)
+    AND ($8::boolean IS NULL OR available = $8)
+    AND ($9::text IS NULL OR (
+          description ILIKE '%' || $9 || '%'
+       OR type ILIKE '%' || $9 || '%'
+       OR subtype ILIKE '%' || $9 || '%'
+       OR role ILIKE '%' || $9 || '%'
+       OR workflow_id ILIKE '%' || $9 || '%'
+       OR origin_id ILIKE '%' || $9 || '%'
+       OR id::text ILIKE '%' || $9 || '%'
+       OR metadata::text ILIKE '%' || $9 || '%'
+    ))`;
+/** Count matching the search WHERE (params $1–$9). */
+exports.COUNT_SEARCH_ESCALATIONS = `SELECT COUNT(*)::int AS total\n${SEARCH_ESCALATIONS_WHERE}`;
+/**
+ * Build the search SELECT. `orderBy` is composed from a whitelist by the caller
+ * (never raw user input), so it is safe to interpolate; everything else is bound.
+ */
+function searchEscalationsQuery(orderBy) {
+    return `SELECT *\n${SEARCH_ESCALATIONS_WHERE}\n  ORDER BY ${orderBy}\n  LIMIT $10 OFFSET $11`;
+}
 /**
  * Atomic resolve by metadata with signal guard.
  *

package/build/services/task/resolve.d.ts

@@ -4,9 +4,11 @@ import type { ResolvedHandle } from './types';
  * HotMesh needs to get a workflow handle.
  *
  * 1. Look up lt_tasks by workflow_id — returns workflow_type and task_queue.
- * 2. If no task record (e.g., orchestrators/containers), fall back to
- *    durable.jobs (entity) + lt_config_workflows (task_queue).
+ * 2. If no task record (e.g., orchestrators/containers, or a child running in
+ *    another app), fall back to `<appId>.jobs` (entity) + lt_config_workflows
+ *    (task_queue). `appId` selects the HotMesh namespace to scan — children of
+ *    a workflow live under their own app's schema, not always `durable`.
  * 3. If task_queue is null (pre-migration record), fall back to lt_config_workflows.
  * 4. Throws if the workflow cannot be resolved.
  */
-export declare function resolveWorkflowHandle(workflowId: string): Promise<ResolvedHandle>;
+export declare function resolveWorkflowHandle(workflowId: string, appId?: string): Promise<ResolvedHandle>;

package/build/services/task/resolve.js

@@ -9,12 +9,14 @@ const sql_1 = require("./sql");
  * HotMesh needs to get a workflow handle.
  *
  * 1. Look up lt_tasks by workflow_id — returns workflow_type and task_queue.
- * 2. If no task record (e.g., orchestrators/containers), fall back to
- *    durable.jobs (entity) + lt_config_workflows (task_queue).
+ * 2. If no task record (e.g., orchestrators/containers, or a child running in
+ *    another app), fall back to `<appId>.jobs` (entity) + lt_config_workflows
+ *    (task_queue). `appId` selects the HotMesh namespace to scan — children of
+ *    a workflow live under their own app's schema, not always `durable`.
  * 3. If task_queue is null (pre-migration record), fall back to lt_config_workflows.
  * 4. Throws if the workflow cannot be resolved.
  */
-async function resolveWorkflowHandle(workflowId) {
+async function resolveWorkflowHandle(workflowId, appId = 'durable') {
     const pool = (0, db_1.getPool)();
     // 1. Try lt_tasks first (leaf workflows)
     const { rows } = await pool.query(sql_1.RESOLVE_TASK_BY_WORKFLOW_ID, [workflowId]);
@@ -29,9 +31,10 @@ async function resolveWorkflowHandle(workflowId) {
             return { taskQueue: configRows[0].task_queue, workflowName: workflow_type };
         }
     }
-    // 2. Fall back to durable.jobs — handles orchestrators/containers that
-    //    have no lt_tasks record but do have a job with an entity tag.
-    const { rows: jobRows } = await pool.query(sql_1.RESOLVE_JOB_ENTITY, [`hmsh:durable:j:${workflowId}`]);
+    // 2. Fall back to <appId>.jobs — handles orchestrators/containers that
+    //    have no lt_tasks record but do have a job with an entity tag, and
+    //    children running in a non-default namespace.
+    const { rows: jobRows } = await pool.query((0, sql_1.RESOLVE_JOB_ENTITY)(appId), [`hmsh:${appId}:j:${workflowId}`]);
     if (jobRows.length > 0 && jobRows[0].entity) {
         const entity = jobRows[0].entity;
         // 2a. Try lt_config_workflows for task_queue

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

@@ -5,7 +5,12 @@ export declare const GET_TASK_BY_SIGNAL_ID = "SELECT * FROM lt_tasks WHERE signa
 export declare const GET_TASK_BY_WORKFLOW_ID = "SELECT * FROM lt_tasks WHERE workflow_id = $1 ORDER BY created_at DESC LIMIT 1";
 export declare const RESOLVE_TASK_BY_WORKFLOW_ID = "SELECT workflow_type, task_queue FROM lt_tasks WHERE workflow_id = $1 ORDER BY created_at DESC LIMIT 1";
 export declare const RESOLVE_CONFIG_TASK_QUEUE = "SELECT task_queue FROM lt_config_workflows WHERE workflow_type = $1";
-export declare const RESOLVE_JOB_ENTITY = "SELECT entity FROM durable.jobs WHERE key = $1 LIMIT 1";
+/**
+ * Look up a job's entity tag in a specific HotMesh namespace. The namespace is a
+ * Postgres schema name, so it is interpolated (not a bind param) — same pattern
+ * as the diagnostics queries. Callers pass the trusted app_id from config.
+ */
+export declare const RESOLVE_JOB_ENTITY: (appId: string) => string;
 export declare const GET_PROCESS_TASKS = "SELECT * FROM lt_tasks WHERE origin_id = $1 ORDER BY created_at ASC";
 /**
  * Build the process-stats totals CTE query for a given interval.

package/build/services/task/sql.js

@@ -25,7 +25,13 @@ exports.GET_TASK_BY_WORKFLOW_ID = `SELECT * FROM lt_tasks WHERE workflow_id = $1
 // ---- resolve.ts queries ---------------------------------------------------
 exports.RESOLVE_TASK_BY_WORKFLOW_ID = `SELECT workflow_type, task_queue FROM lt_tasks WHERE workflow_id = $1 ORDER BY created_at DESC LIMIT 1`;
 exports.RESOLVE_CONFIG_TASK_QUEUE = `SELECT task_queue FROM lt_config_workflows WHERE workflow_type = $1`;
-exports.RESOLVE_JOB_ENTITY = `SELECT entity FROM durable.jobs WHERE key = $1 LIMIT 1`;
+/**
+ * Look up a job's entity tag in a specific HotMesh namespace. The namespace is a
+ * Postgres schema name, so it is interpolated (not a bind param) — same pattern
+ * as the diagnostics queries. Callers pass the trusted app_id from config.
+ */
+const RESOLVE_JOB_ENTITY = (appId) => `SELECT entity FROM "${appId}".jobs WHERE key = $1 LIMIT 1`;
+exports.RESOLVE_JOB_ENTITY = RESOLVE_JOB_ENTITY;
 // ---- process.ts queries ---------------------------------------------------
 exports.GET_PROCESS_TASKS = `SELECT * FROM lt_tasks WHERE origin_id = $1 ORDER BY created_at ASC`;
 /**

package/build/start/adapters.js

@@ -15,12 +15,15 @@ const adapter_1 = require("../services/mcp/adapter");
 const escalation_strategy_1 = require("../services/escalation-strategy");
 const default_1 = require("../services/escalation-strategy/default");
 const mcp_2 = require("../services/escalation-strategy/mcp");
+const features_1 = require("../modules/features");
 const socket_auth_1 = require("./socket-auth");
 /**
  * Register all adapters (logging, telemetry, events, maintenance,
  * escalation strategy, MCP) based on the startup config.
  */
 function registerAdapters(startConfig) {
+    // Dashboard feature flags (default permissive; deployment opts out).
+    (0, features_1.configureFeatureFlags)(startConfig.features);
     // Logging (register first so subsequent log calls use it)
     if (startConfig.logging?.adapter) {
         logger_1.loggerRegistry.register(startConfig.logging.adapter);

package/build/system/mcp-servers/admin/diagnostics.d.ts

@@ -2,15 +2,16 @@
  * Diagnostics tools — mirrors routes/diagnostics.ts. Pure read-only.
  *
  * Three tools:
- *   diagnose_job            — full per-job diagnosis: events + stream messages + findings
+ *   diagnose_job            — per-job verdict (compact by default; opt into events/streams)
  *   find_stalled_jobs       — fleet-level: running jobs with no recent status change
  *   find_orphaned_signals   — fleet-level: suspended waiters with no escalation row
  *
  * Efficient usage: start fleet-wide (find_orphaned_signals for the genuinely
  * broken case, find_stalled_jobs for candidates), then call diagnose_job on a
- * specific id for root cause — do not fan diagnose_job across every job. For
- * full raw message payloads, use the stream browser (list_stream_messages
- * filtered by jid), not diagnose_job, which returns a capped summary.
+ * specific id for root cause — do not fan diagnose_job across every job.
+ * diagnose_job returns the verdict only by default; add include: ['events'] or
+ * ['streams'] for the heavy arrays. For full raw message payloads, use the
+ * stream browser (list_stream_messages filtered by jid).
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export declare function registerDiagnosticsTools(server: McpServer): void;

package/build/system/mcp-servers/admin/diagnostics.js

@@ -39,21 +39,23 @@ const schemas_1 = require("./schemas");
 function registerDiagnosticsTools(server) {
     server.registerTool('diagnose_job', {
         title: 'Diagnose Job',
-        description: 'Read-only diagnosis for a single workflow job. Combines the execution event ' +
-            'timeline (from exportWorkflowExecution) with the raw stream messages for that ' +
-            'job (engine + worker, including retry state and timing) and the escalation row ' +
-            'from hmsh_escalations. Returns structured findings[] with confidence, evidence, ' +
-            'and read-only guidance (where to look next — never recovery; HotMesh state ' +
-            'cannot be unwound). ' +
+        description: 'Read-only diagnosis for a single workflow job. Compact by default — returns the ' +
+            'verdict only: status, idle_for_ms, workflow_type, stream_summary (counts), the ' +
+            'escalation row from hmsh_escalations, and structured findings[] with confidence, ' +
+            'evidence, and read-only guidance (where to look next — never recovery; HotMesh ' +
+            'state cannot be unwound). ' +
             'A workflow sitting at a condition()/waitFor()/sleepFor() for a long time is ' +
             'classified as a healthy wait, not a fault — only dead-letter, reservation-leak, ' +
             'or a suspended-waiter-with-no-escalation indicate a real problem. ' +
-            'Events are capped (max_events, default 500); for full raw message payloads use ' +
-            'the stream browser (list_stream_messages filtered by jid). Call ' +
-            'find_orphaned_signals / find_stalled_jobs first to surface IDs, then this per job.',
+            'To opt into the heavy arrays pass include: ["events"] for the execution timeline ' +
+            '(capped by max_events, default 500) and/or include: ["streams"] for raw engine+worker ' +
+            'messages; large result/message payloads are summarized to {bytes,preview,truncated}. ' +
+            'For full untruncated payloads use list_stream_messages filtered by jid (returned in ' +
+            'raw_messages). Call find_orphaned_signals / find_stalled_jobs first to surface IDs, ' +
+            'then this per job.',
         inputSchema: schemas_1.diagnoseJobSchema,
     }, async (args) => {
-        const result = await api.diagnose({ workflowId: args.workflow_id, appId: args.app_id, maxEvents: args.max_events });
+        const result = await api.diagnose({ workflowId: args.workflow_id, appId: args.app_id, maxEvents: args.max_events, include: args.include, verbosity: args.verbosity });
         if (result.error) {
             return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
         }

package/build/system/mcp-servers/admin/escalations.d.ts

@@ -1,5 +1,11 @@
 /**
  * Escalation tools — mirrors routes/escalations/
+ *
+ * Every tool runs as the `lt-system` bot. The escalation RBAC helpers
+ * (getVisibleRoles / getUserRoles / hasGlobalEscalationAccess) query a uuid
+ * column, so the bot's external_id string ('lt-system') would blow up with
+ * `invalid input syntax for type uuid`. `systemAuth()` resolves the bot's real
+ * UUID once and caches it; that UUID (a superadmin) is passed as the principal.
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export declare function registerEscalationTools(server: McpServer): void;

package/build/system/mcp-servers/admin/escalations.js

@@ -35,47 +35,109 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerEscalationTools = registerEscalationTools;
 const escalationService = __importStar(require("../../../services/escalation"));
+const escalationApi = __importStar(require("../../../api/escalations"));
 const escalationMetaApi = __importStar(require("../../../api/escalations/metadata"));
 const escalationBulkApi = __importStar(require("../../../api/escalations/bulk"));
+const iam_1 = require("../../../services/iam");
 const schemas_1 = require("./schemas");
+let systemPrincipalId = null;
+/**
+ * Resolve (and cache) the lt-system bot's real UUID. The escalation RBAC helpers
+ * query the uuid `user_id` column, so the external_id string 'lt-system' would
+ * raise `invalid input syntax for type uuid`. The bot is a superadmin, so it has
+ * global escalation access.
+ */
+async function systemAuth() {
+    if (!systemPrincipalId)
+        systemPrincipalId = await (0, iam_1.ensureSystemBot)();
+    return { userId: systemPrincipalId, role: 'superadmin' };
+}
+/** Project the full escalation record to the MCP-facing shape, including metadata. */
+function projectEscalation(e) {
+    return {
+        id: e.id,
+        type: e.type,
+        subtype: e.subtype,
+        role: e.role,
+        priority: e.priority,
+        status: e.status,
+        description: e.description,
+        workflow_id: e.workflow_id,
+        workflow_type: e.workflow_type,
+        assigned_to: e.assigned_to,
+        assigned_until: e.assigned_until,
+        signal_key: e.signal_key,
+        metadata: e.metadata,
+        created_at: e.created_at,
+        updated_at: e.updated_at,
+    };
+}
 function registerEscalationTools(server) {
+    // ── Read-only ───────────────────────────────────────────────────────────────
     // mirrors GET /api/escalations
     server.registerTool('find_escalations', {
         title: 'Find Escalations',
-        description: 'Search escalations with optional filters. Returns records with ' +
-            'type, role, priority, status, description, and assignment info.',
+        description: 'Search escalations with optional filters (status, role, type, subtype, ' +
+            'assigned_to, priority), free-text `search`, and sorting. `search` matches ' +
+            'across description, type/subtype, role, workflow/origin id, and metadata values ' +
+            '(e.g. a correlation key like an order id) server-side over the full result set. ' +
+            'Returns full records including metadata, workflow linkage, assignment, and signal_key.',
         inputSchema: schemas_1.findEscalationsSchema,
     }, async (args) => {
-        const { escalations, total } = await escalationService.listEscalations({
+        const result = await escalationApi.listEscalations({
             status: args.status,
             role: args.role,
             type: args.type,
+            subtype: args.subtype,
+            assigned_to: args.assigned_to,
+            search: args.search,
             priority: args.priority,
             limit: args.limit,
             offset: args.offset,
-        });
+            sort_by: args.sort_by,
+            order: args.order,
+        }, await systemAuth());
+        if (result.error) {
+            return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
+        }
+        const { escalations, total } = result.data;
         return {
             content: [{
                     type: 'text',
                     text: JSON.stringify({
                         total,
                         count: escalations.length,
-                        escalations: escalations.map((e) => ({
-                            id: e.id,
-                            type: e.type,
-                            subtype: e.subtype,
-                            role: e.role,
-                            priority: e.priority,
-                            status: e.status,
-                            description: e.description,
-                            workflow_type: e.workflow_type,
-                            assigned_to: e.assigned_to,
-                            created_at: e.created_at,
-                        })),
+                        escalations: escalations.map(projectEscalation),
                     }),
                 }],
         };
     });
+    // mirrors GET /api/escalations/:id
+    server.registerTool('get_escalation', {
+        title: 'Get Escalation',
+        description: 'Get a single escalation by ID — the full record including metadata, envelope ' +
+            'linkage, resolver/escalation payloads, signal_key, and assignment state.',
+        inputSchema: schemas_1.getEscalationSchema,
+    }, async (args) => {
+        const result = await escalationApi.getEscalation({ id: args.id }, await systemAuth());
+        if (result.error) {
+            return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(result.data) }] };
+    });
+    // mirrors GET /api/escalations/by-workflow/:workflowId
+    server.registerTool('get_escalations_by_workflow', {
+        title: 'Get Escalations by Workflow',
+        description: 'List all escalations linked to a specific workflow ID, newest first. Returns ' +
+            'full records including metadata.',
+        inputSchema: schemas_1.getEscalationsByWorkflowSchema,
+    }, async (args) => {
+        const result = await escalationApi.getEscalationsByWorkflowId({ workflowId: args.workflow_id });
+        if (result.error) {
+            return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(result.data) }] };
+    });
     // mirrors GET /api/escalations/stats
     server.registerTool('get_escalation_stats', {
         title: 'Get Escalation Stats',
@@ -85,12 +147,23 @@ function registerEscalationTools(server) {
     }, async (args) => {
         const stats = await escalationService.getEscalationStats(undefined, args.period);
         return {
-            content: [{
-                    type: 'text',
-                    text: JSON.stringify(stats),
-                }],
+            content: [{ type: 'text', text: JSON.stringify(stats) }],
         };
     });
+    // mirrors GET /api/escalations/by-metadata
+    server.registerTool('find_by_metadata', {
+        title: 'Find by Metadata',
+        description: 'Find escalations by a metadata key-value pair (e.g. a correlation key written ' +
+            'into metadata when the escalation was raised).',
+        inputSchema: schemas_1.findByMetadataSchema,
+    }, async (args) => {
+        const result = await escalationMetaApi.findByMetadata(args, await systemAuth());
+        if (result.error) {
+            return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(result.data) }] };
+    });
+    // ── Read-write ────────────────────────────────────────────────────────────────
     // mirrors POST /api/escalations/:id/claim
     server.registerTool('claim_escalation', {
         title: 'Claim Escalation',
@@ -99,23 +172,79 @@ function registerEscalationTools(server) {
             'the escalation returns to the queue.',
         inputSchema: schemas_1.claimEscalationSchema,
     }, async (args) => {
-        const escalation = await escalationService.getEscalation(args.id);
-        if (!escalation) {
-            return {
-                content: [{ type: 'text', text: JSON.stringify({ error: 'Escalation not found' }) }],
-                isError: true,
-            };
+        const result = await escalationApi.claimEscalation({ id: args.id, durationMinutes: args.duration_minutes }, await systemAuth());
+        if (result.error) {
+            return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
         }
-        const result = await escalationService.claimEscalation(args.id, 'lt-system', args.duration_minutes);
-        if (!result) {
-            return {
-                content: [{ type: 'text', text: JSON.stringify({ error: 'Escalation not available for claim' }) }],
-                isError: true,
-            };
+        return { content: [{ type: 'text', text: JSON.stringify(result.data) }] };
+    });
+    // mirrors POST /api/escalations/:id/release
+    server.registerTool('release_escalation', {
+        title: 'Release Escalation',
+        description: 'Release a claimed escalation back to the available pool. Reverses a ' +
+            'claim_escalation so another holder can pick it up.',
+        inputSchema: schemas_1.releaseEscalationSchema,
+    }, async (args) => {
+        const result = await escalationApi.releaseEscalation({ id: args.id }, await systemAuth());
+        if (result.error) {
+            return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
         }
-        return {
-            content: [{ type: 'text', text: JSON.stringify(result) }],
-        };
+        return { content: [{ type: 'text', text: JSON.stringify(result.data) }] };
+    });
+    // mirrors POST /api/escalations/:id/resolve
+    server.registerTool('resolve_escalation', {
+        title: 'Resolve Escalation',
+        description: 'Resolve a pending escalation with a human-provided payload. Routes by escalation ' +
+            'shape: efficient (signal_key) escalations resume the waiting workflow in place; ' +
+            'legacy paths signal via routing metadata or re-run the original workflow. ' +
+            'Password fields in the payload are replaced with ephemeral tokens.',
+        inputSchema: schemas_1.resolveEscalationSchema,
+    }, async (args) => {
+        const result = await escalationApi.resolveEscalation({ id: args.id, resolverPayload: args.resolverPayload }, await systemAuth());
+        if (result.error) {
+            return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(result.data) }] };
+    });
+    // mirrors POST /api/escalations/resolve-by-signal-key
+    server.registerTool('resolve_by_signal_key', {
+        title: 'Resolve by Signal Key',
+        description: 'Resolve an efficient (atomic) escalation directly by its signal_key and resume the ' +
+            'waiting workflow in place. For callers that know the deterministic signal id and want ' +
+            'to skip the id lookup.',
+        inputSchema: schemas_1.resolveBySignalKeySchema,
+    }, async (args) => {
+        const result = await escalationApi.resolveBySignalKey({ signalKey: args.signalKey, resolverPayload: args.resolverPayload }, await systemAuth());
+        if (result.error) {
+            return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(result.data) }] };
+    });
+    // mirrors PATCH /api/escalations/:id/escalate
+    server.registerTool('escalate_escalation', {
+        title: 'Escalate Escalation',
+        description: 'Route a pending escalation to a different role (per the escalation chain). The new ' +
+            'role becomes responsible for resolving it.',
+        inputSchema: schemas_1.escalateEscalationSchema,
+    }, async (args) => {
+        const result = await escalationApi.escalateToRole({ id: args.id, targetRole: args.targetRole }, await systemAuth());
+        if (result.error) {
+            return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(result.data) }] };
+    });
+    // mirrors POST /api/escalations/:id/cancel
+    server.registerTool('cancel_escalation', {
+        title: 'Cancel Escalation',
+        description: 'Permanently cancel a pending escalation — used when the tied workflow has ' +
+            'terminated and can never receive the resolution signal. Preserved for audit.',
+        inputSchema: schemas_1.cancelEscalationSchema,
+    }, async (args) => {
+        const result = await escalationApi.cancelSingleEscalation({ id: args.id }, await systemAuth());
+        if (result.error) {
+            return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(result.data) }] };
     });
     // mirrors POST /api/escalations/release-expired
     server.registerTool('release_expired_claims', {
@@ -148,26 +277,13 @@ function registerEscalationTools(server) {
                 }],
         };
     });
-    // ── Metadata-based operations ───────────────────────────────────────────────
-    // mirrors GET /api/escalations/by-metadata
-    server.registerTool('find_by_metadata', {
-        title: 'Find by Metadata',
-        description: 'Find escalations by a metadata key-value pair.',
-        inputSchema: schemas_1.findByMetadataSchema,
-    }, async (args) => {
-        const result = await escalationMetaApi.findByMetadata(args, { userId: 'lt-system' });
-        if (result.error) {
-            return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
-        }
-        return { content: [{ type: 'text', text: JSON.stringify(result.data) }] };
-    });
     // mirrors POST /api/escalations/claim-by-metadata
     server.registerTool('claim_by_metadata', {
         title: 'Claim by Metadata',
         description: 'Find and claim an escalation by metadata key-value pair.',
         inputSchema: schemas_1.claimByMetadataSchema,
     }, async (args) => {
-        const result = await escalationMetaApi.claimByMetadata(args, { userId: 'lt-system' });
+        const result = await escalationMetaApi.claimByMetadata(args, await systemAuth());
         if (result.error) {
             return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
         }
@@ -179,7 +295,7 @@ function registerEscalationTools(server) {
         description: 'Find and resolve an escalation by metadata key-value pair.',
         inputSchema: schemas_1.resolveByMetadataSchema,
     }, async (args) => {
-        const result = await escalationMetaApi.resolveByMetadata(args, { userId: 'lt-system' });
+        const result = await escalationMetaApi.resolveByMetadata(args, await systemAuth());
         if (result.error) {
             return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
         }
@@ -192,7 +308,7 @@ function registerEscalationTools(server) {
         description: 'Claim multiple escalations in a single operation.',
         inputSchema: schemas_1.bulkClaimSchema,
     }, async (args) => {
-        const result = await escalationBulkApi.bulkClaim(args, { userId: 'lt-system' });
+        const result = await escalationBulkApi.bulkClaim(args, await systemAuth());
         if (result.error) {
             return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
         }
@@ -204,7 +320,7 @@ function registerEscalationTools(server) {
         description: 'Assign multiple escalations to a specific user.',
         inputSchema: schemas_1.bulkAssignSchema,
     }, async (args) => {
-        const result = await escalationBulkApi.bulkAssign(args, { userId: 'lt-system' });
+        const result = await escalationBulkApi.bulkAssign(args, await systemAuth());
         if (result.error) {
             return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
         }
@@ -216,7 +332,19 @@ function registerEscalationTools(server) {
         description: 'Escalate multiple escalations to a different role.',
         inputSchema: schemas_1.bulkEscalateSchema,
     }, async (args) => {
-        const result = await escalationBulkApi.bulkEscalate(args, { userId: 'lt-system' });
+        const result = await escalationBulkApi.bulkEscalate(args, await systemAuth());
+        if (result.error) {
+            return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(result.data) }] };
+    });
+    // mirrors POST /api/escalations/bulk-cancel
+    server.registerTool('bulk_cancel', {
+        title: 'Bulk Cancel',
+        description: 'Cancel multiple pending escalations in a single operation.',
+        inputSchema: schemas_1.bulkCancelSchema,
+    }, async (args) => {
+        const result = await escalationApi.bulkCancel(args, await systemAuth());
         if (result.error) {
             return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
         }
@@ -228,7 +356,7 @@ function registerEscalationTools(server) {
         description: 'Update the priority of multiple escalations.',
         inputSchema: schemas_1.updatePrioritySchema,
     }, async (args) => {
-        const result = await escalationBulkApi.updatePriority(args, { userId: 'lt-system' });
+        const result = await escalationBulkApi.updatePriority(args, await systemAuth());
         if (result.error) {
             return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
         }

package/build/system/mcp-servers/admin/index.js

@@ -55,7 +55,7 @@ const settings_1 = require("./settings");
 const exports_1 = require("./exports");
 const overview_1 = require("./overview");
 const diagnostics_1 = require("./diagnostics");
-const TOOL_COUNT = 75;
+const TOOL_COUNT = 83;
 let server = null;
 async function createAdminServer(options) {
     if (server && !options?.fresh)
@@ -66,7 +66,7 @@ async function createAdminServer(options) {
         server = instance;
     }
     (0, tasks_1.registerTaskTools)(instance); //  2 tools
-    (0, escalations_1.registerEscalationTools)(instance); // 12 tools (5 base + 7 metadata/bulk)
+    (0, escalations_1.registerEscalationTools)(instance); // 20 tools (RO + RW single + metadata + bulk)
     (0, workflow_config_1.registerWorkflowConfigTools)(instance); //  3 tools
     (0, workflows_1.registerWorkflowTools)(instance); //  3 tools
     (0, mcp_servers_1.registerMcpServerTools)(instance); //  4 tools
@@ -83,7 +83,7 @@ async function createAdminServer(options) {
     (0, exports_1.registerExportTools)(instance); //  4 tools
     (0, overview_1.registerOverviewTools)(instance); //  1 tool
     (0, diagnostics_1.registerDiagnosticsTools)(instance); //  3 tools
-    // Total: 75
+    // Total: 83
     logger_1.loggerRegistry.info(`[lt-mcp:admin] ${name} ready (${TOOL_COUNT} tools registered)`);
     return instance;
 }