@hotmeshio/long-tail 0.1.14 → 0.1.15

package/build/api/escalations/helpers.js

@@ -0,0 +1,80 @@
+"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.getVisibleRoles = getVisibleRoles;
+exports.validateIds = validateIds;
+exports.checkBulkPermission = checkBulkPermission;
+exports.publishBulkClaimEvents = publishBulkClaimEvents;
+const escalationService = __importStar(require("../../services/escalation"));
+const userService = __importStar(require("../../services/user"));
+const publish_1 = require("../../lib/events/publish");
+// ── Private helpers ────────────────────────────────────────────────────────
+async function getVisibleRoles(userId) {
+    const isSuperAdminUser = await userService.isSuperAdmin(userId);
+    if (isSuperAdminUser)
+        return undefined;
+    const userRoles = await userService.getUserRoles(userId);
+    return userRoles.map((r) => r.role);
+}
+function validateIds(ids) {
+    return Array.isArray(ids) && ids.length > 0;
+}
+async function checkBulkPermission(userId, ids) {
+    const isSuperAdminUser = await userService.isSuperAdmin(userId);
+    if (isSuperAdminUser)
+        return { allowed: true };
+    const roles = await escalationService.getEscalationRoles(ids);
+    for (const role of roles) {
+        const canManage = await userService.isGroupAdmin(userId, role);
+        if (!canManage) {
+            return { allowed: false, status: 403, error: `Insufficient permissions for role "${role}"` };
+        }
+    }
+    return { allowed: true };
+}
+function publishBulkClaimEvents(ids, assignedTo) {
+    for (const id of ids) {
+        (0, publish_1.publishEscalationEvent)({
+            type: 'escalation.claimed',
+            source: 'api',
+            workflowId: '',
+            workflowName: '',
+            taskQueue: '',
+            escalationId: id,
+            status: 'claimed',
+            data: { assigned_to: assignedTo, bulk: true },
+        });
+    }
+}

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

@@ -0,0 +1,6 @@
+export { createEscalation } from './create';
+export { listEscalations, listAvailableEscalations, listDistinctTypes, getEscalationStats } from './list';
+export { getEscalation, getEscalationsByWorkflowId, escalateToRole } from './single';
+export { claimEscalation, releaseEscalation } from './claim';
+export { releaseExpiredClaims, updatePriority, bulkClaim, bulkAssign, bulkEscalate, bulkTriage } from './bulk';
+export { resolveEscalation } from './resolve';

package/build/api/escalations/index.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveEscalation = exports.bulkTriage = exports.bulkEscalate = exports.bulkAssign = exports.bulkClaim = exports.updatePriority = exports.releaseExpiredClaims = exports.releaseEscalation = exports.claimEscalation = exports.escalateToRole = exports.getEscalationsByWorkflowId = exports.getEscalation = exports.getEscalationStats = exports.listDistinctTypes = exports.listAvailableEscalations = exports.listEscalations = exports.createEscalation = void 0;
+var create_1 = require("./create");
+Object.defineProperty(exports, "createEscalation", { enumerable: true, get: function () { return create_1.createEscalation; } });
+var list_1 = require("./list");
+Object.defineProperty(exports, "listEscalations", { enumerable: true, get: function () { return list_1.listEscalations; } });
+Object.defineProperty(exports, "listAvailableEscalations", { enumerable: true, get: function () { return list_1.listAvailableEscalations; } });
+Object.defineProperty(exports, "listDistinctTypes", { enumerable: true, get: function () { return list_1.listDistinctTypes; } });
+Object.defineProperty(exports, "getEscalationStats", { enumerable: true, get: function () { return list_1.getEscalationStats; } });
+var single_1 = require("./single");
+Object.defineProperty(exports, "getEscalation", { enumerable: true, get: function () { return single_1.getEscalation; } });
+Object.defineProperty(exports, "getEscalationsByWorkflowId", { enumerable: true, get: function () { return single_1.getEscalationsByWorkflowId; } });
+Object.defineProperty(exports, "escalateToRole", { enumerable: true, get: function () { return single_1.escalateToRole; } });
+var claim_1 = require("./claim");
+Object.defineProperty(exports, "claimEscalation", { enumerable: true, get: function () { return claim_1.claimEscalation; } });
+Object.defineProperty(exports, "releaseEscalation", { enumerable: true, get: function () { return claim_1.releaseEscalation; } });
+var bulk_1 = require("./bulk");
+Object.defineProperty(exports, "releaseExpiredClaims", { enumerable: true, get: function () { return bulk_1.releaseExpiredClaims; } });
+Object.defineProperty(exports, "updatePriority", { enumerable: true, get: function () { return bulk_1.updatePriority; } });
+Object.defineProperty(exports, "bulkClaim", { enumerable: true, get: function () { return bulk_1.bulkClaim; } });
+Object.defineProperty(exports, "bulkAssign", { enumerable: true, get: function () { return bulk_1.bulkAssign; } });
+Object.defineProperty(exports, "bulkEscalate", { enumerable: true, get: function () { return bulk_1.bulkEscalate; } });
+Object.defineProperty(exports, "bulkTriage", { enumerable: true, get: function () { return bulk_1.bulkTriage; } });
+var resolve_1 = require("./resolve");
+Object.defineProperty(exports, "resolveEscalation", { enumerable: true, get: function () { return resolve_1.resolveEscalation; } });

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

@@ -0,0 +1,75 @@
+import type { LTApiResult, LTApiAuth } from '../../types/sdk';
+/**
+ * List escalations with optional filters.
+ *
+ * Results are scoped to the authenticated user's roles unless the user
+ * is a superadmin (who sees all roles).
+ *
+ * @param input.status — filter by `pending`, `resolved`, or `cancelled`
+ * @param input.role — filter by assigned role
+ * @param input.type — filter by workflow type
+ * @param input.subtype — filter by subtype
+ * @param input.assigned_to — filter by assigned user ID
+ * @param input.priority — filter by priority (1–4)
+ * @param input.limit — max results (default: 50)
+ * @param input.offset — pagination offset
+ * @param input.sort_by — column to sort by (e.g. `created_at`, `priority`)
+ * @param input.order — `asc` or `desc`
+ * @param auth — authenticated user context (required for role scoping)
+ * @returns `{ status: 200, data: { escalations, total } }`
+ */
+export declare function listEscalations(input: {
+    status?: string;
+    role?: string;
+    type?: string;
+    subtype?: string;
+    assigned_to?: string;
+    priority?: number;
+    limit?: number;
+    offset?: number;
+    sort_by?: string;
+    order?: string;
+}, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * List escalations available for claim (pending and not actively claimed).
+ *
+ * Similar to `listEscalations` but excludes escalations with active claims.
+ * Scoped to the authenticated user's roles.
+ *
+ * @param input.role — filter by role
+ * @param input.type — filter by workflow type
+ * @param input.subtype — filter by subtype
+ * @param input.priority — filter by priority (1–4)
+ * @param input.limit — max results (default: 50)
+ * @param input.offset — pagination offset
+ * @param input.sort_by — column to sort by
+ * @param input.order — `asc` or `desc`
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { escalations, total } }`
+ */
+export declare function listAvailableEscalations(input: {
+    role?: string;
+    type?: string;
+    subtype?: string;
+    priority?: number;
+    limit?: number;
+    offset?: number;
+    sort_by?: string;
+    order?: string;
+}, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * List all distinct escalation type values.
+ *
+ * @returns `{ status: 200, data: { types: string[] } }`
+ */
+export declare function listDistinctTypes(): Promise<LTApiResult>;
+/**
+ * Get aggregate escalation statistics scoped to the user's roles.
+ *
+ * @param input.period — time window (`1h`, `24h`, `7d`, `30d`)
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { pending, claimed, created, resolved, by_role, by_type } }`
+ */
+export declare function getEscalationStats(input: {
+    period?: string;
+}, auth: LTApiAuth): Promise<LTApiResult>;

package/build/api/escalations/list.js

@@ -0,0 +1,170 @@
+"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.listEscalations = listEscalations;
+exports.listAvailableEscalations = listAvailableEscalations;
+exports.listDistinctTypes = listDistinctTypes;
+exports.getEscalationStats = getEscalationStats;
+const escalationService = __importStar(require("../../services/escalation"));
+const helpers_1 = require("./helpers");
+// ── List routes ────────────────────────────────────────────────────────────
+/**
+ * List escalations with optional filters.
+ *
+ * Results are scoped to the authenticated user's roles unless the user
+ * is a superadmin (who sees all roles).
+ *
+ * @param input.status — filter by `pending`, `resolved`, or `cancelled`
+ * @param input.role — filter by assigned role
+ * @param input.type — filter by workflow type
+ * @param input.subtype — filter by subtype
+ * @param input.assigned_to — filter by assigned user ID
+ * @param input.priority — filter by priority (1–4)
+ * @param input.limit — max results (default: 50)
+ * @param input.offset — pagination offset
+ * @param input.sort_by — column to sort by (e.g. `created_at`, `priority`)
+ * @param input.order — `asc` or `desc`
+ * @param auth — authenticated user context (required for role scoping)
+ * @returns `{ status: 200, data: { escalations, total } }`
+ */
+async function listEscalations(input, auth) {
+    try {
+        const visibleRoles = await (0, helpers_1.getVisibleRoles)(auth.userId);
+        if (visibleRoles && visibleRoles.length === 0) {
+            return { status: 200, data: { escalations: [], total: 0 } };
+        }
+        const result = await escalationService.listEscalations({
+            status: input.status,
+            role: input.role,
+            type: input.type,
+            subtype: input.subtype,
+            assigned_to: input.assigned_to,
+            priority: input.priority,
+            limit: input.limit,
+            offset: input.offset,
+            sort_by: input.sort_by,
+            order: input.order,
+            visibleRoles,
+        });
+        return { status: 200, data: result };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * List escalations available for claim (pending and not actively claimed).
+ *
+ * Similar to `listEscalations` but excludes escalations with active claims.
+ * Scoped to the authenticated user's roles.
+ *
+ * @param input.role — filter by role
+ * @param input.type — filter by workflow type
+ * @param input.subtype — filter by subtype
+ * @param input.priority — filter by priority (1–4)
+ * @param input.limit — max results (default: 50)
+ * @param input.offset — pagination offset
+ * @param input.sort_by — column to sort by
+ * @param input.order — `asc` or `desc`
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { escalations, total } }`
+ */
+async function listAvailableEscalations(input, auth) {
+    try {
+        const visibleRoles = await (0, helpers_1.getVisibleRoles)(auth.userId);
+        if (visibleRoles && visibleRoles.length === 0) {
+            return { status: 200, data: { escalations: [], total: 0 } };
+        }
+        const result = await escalationService.listAvailableEscalations({
+            role: input.role,
+            type: input.type,
+            subtype: input.subtype,
+            priority: input.priority,
+            limit: input.limit,
+            offset: input.offset,
+            sort_by: input.sort_by,
+            order: input.order,
+            visibleRoles,
+        });
+        return { status: 200, data: result };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * List all distinct escalation type values.
+ *
+ * @returns `{ status: 200, data: { types: string[] } }`
+ */
+async function listDistinctTypes() {
+    try {
+        const types = await escalationService.listDistinctTypes();
+        return { status: 200, data: { types } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Get aggregate escalation statistics scoped to the user's roles.
+ *
+ * @param input.period — time window (`1h`, `24h`, `7d`, `30d`)
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { pending, claimed, created, resolved, by_role, by_type } }`
+ */
+async function getEscalationStats(input, auth) {
+    try {
+        const visibleRoles = await (0, helpers_1.getVisibleRoles)(auth.userId);
+        if (visibleRoles && visibleRoles.length === 0) {
+            return {
+                status: 200,
+                data: {
+                    pending: 0,
+                    claimed: 0,
+                    created: 0,
+                    resolved: 0,
+                    by_role: [],
+                    by_type: [],
+                },
+            };
+        }
+        const stats = await escalationService.getEscalationStats(visibleRoles, input.period);
+        return { status: 200, data: stats };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}

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

@@ -0,0 +1,18 @@
+import type { LTApiResult, LTApiAuth } from '../../types/sdk';
+/**
+ * Resolve a pending escalation with a human-provided payload.
+ *
+ * Handles multiple resolution paths:
+ * 1. **Condition signal** — lightweight `conditionLT` signal via metadata.signal_id
+ * 2. **Signal-routed** — full signal_routing via YAML engine or Durable handle
+ * 3. **Strategy triage** — escalation strategy redirects to a triage workflow
+ * 4. **Notification-only** — no workflow_type; acknowledge and close
+ * 5. **Re-run** — restart the original workflow with resolver data injected
+ *
+ * Password fields in the resolver payload are replaced with ephemeral
+ * tokens (15-minute TTL) so plaintext never enters the signal store.
+ */
+export declare function resolveEscalation(input: {
+    id: string;
+    resolverPayload: Record<string, any>;
+}, _auth: LTApiAuth): Promise<LTApiResult>;

package/build/api/escalations/resolve.js

@@ -0,0 +1,243 @@
+"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.resolveEscalation = resolveEscalation;
+const escalationService = __importStar(require("../../services/escalation"));
+const taskService = __importStar(require("../../services/task"));
+const publish_1 = require("../../lib/events/publish");
+const escalation_strategy_1 = require("../../services/escalation-strategy");
+const ephemeral_1 = require("../../services/iam/ephemeral");
+const deployer_1 = require("../../services/yaml-workflow/deployer");
+const workers_1 = require("../../workers");
+const defaults_1 = require("../../modules/defaults");
+// ── Orchestrator ─────────────────────────────────────────────────────────
+/**
+ * Resolve a pending escalation with a human-provided payload.
+ *
+ * Handles multiple resolution paths:
+ * 1. **Condition signal** — lightweight `conditionLT` signal via metadata.signal_id
+ * 2. **Signal-routed** — full signal_routing via YAML engine or Durable handle
+ * 3. **Strategy triage** — escalation strategy redirects to a triage workflow
+ * 4. **Notification-only** — no workflow_type; acknowledge and close
+ * 5. **Re-run** — restart the original workflow with resolver data injected
+ *
+ * Password fields in the resolver payload are replaced with ephemeral
+ * tokens (15-minute TTL) so plaintext never enters the signal store.
+ */
+async function resolveEscalation(input, _auth) {
+    try {
+        const { id, resolverPayload } = input;
+        if (!resolverPayload) {
+            return { status: 400, error: 'resolverPayload is required' };
+        }
+        const escalation = await escalationService.getEscalation(id);
+        if (!escalation)
+            return { status: 404, error: 'Escalation not found' };
+        if (escalation.status !== 'pending')
+            return { status: 409, error: 'Escalation not available for resolution' };
+        // Path A: conditionLT signal
+        const metadataSignalId = escalation.metadata?.signal_id;
+        if (metadataSignalId && escalation.workflow_id && escalation.task_queue && escalation.workflow_type) {
+            return resolveViaConditionSignal(escalation, resolverPayload);
+        }
+        // Path B: waitFor signal routing
+        const signalRouting = escalation.metadata?.signal_routing;
+        if (signalRouting?.signalId) {
+            return resolveViaSignalRouting(escalation, resolverPayload);
+        }
+        // Path C: escalation strategy may redirect to triage
+        const envelope = await reconstructEnvelope(escalation);
+        const strategy = escalation_strategy_1.escalationStrategyRegistry.current;
+        if (strategy) {
+            const directive = await strategy.onResolution({ escalation, resolverPayload, envelope });
+            if (directive.action === 'triage') {
+                return resolveViaTriage(escalation, resolverPayload, directive.triageEnvelope);
+            }
+        }
+        // Path D: notification-only — no workflow to restart
+        if (!escalation.workflow_type || !escalation.task_queue) {
+            await escalationService.resolveEscalation(escalation.id, resolverPayload);
+            return { status: 200, data: { acknowledged: true, escalationId: escalation.id } };
+        }
+        // Path E: standard re-run
+        return resolveViaRerun(escalation, envelope, resolverPayload);
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+// ── Resolution paths ─────────────────────────────────────────────────────
+/** Path A: lightweight conditionLT signal — inject $escalation_id and signal the running workflow. */
+async function resolveViaConditionSignal(escalation, resolverPayload) {
+    const signalId = escalation.metadata.signal_id;
+    const client = (0, workers_1.createClient)();
+    const handle = await client.workflow.getHandle(escalation.task_queue, escalation.workflow_type, escalation.workflow_id);
+    await handle.signal(signalId, { ...resolverPayload, $escalation_id: escalation.id });
+    publishResolvedEvent(escalation);
+    return signaledResult(escalation, escalation.workflow_id);
+}
+/** Path B: waitFor signal escalation — signal via YAML engine or Durable handle. */
+async function resolveViaSignalRouting(escalation, resolverPayload) {
+    const signalRouting = escalation.metadata.signal_routing;
+    const signalPayload = await redactPasswords(resolverPayload, escalation.metadata?.form_schema);
+    if (signalRouting.engine === 'yaml' && signalRouting.hookTopic && signalRouting.appId) {
+        const engine = await (0, deployer_1.getEngine)(signalRouting.appId);
+        await engine.signal(signalRouting.hookTopic, {
+            ...signalPayload,
+            escalationId: escalation.id,
+            job_id: signalRouting.jobId,
+        });
+    }
+    else if (signalRouting.workflowId) {
+        const client = (0, workers_1.createClient)();
+        const handle = await client.workflow.getHandle(signalRouting.taskQueue, signalRouting.workflowType, signalRouting.workflowId);
+        await handle.signal(signalRouting.signalId, signalPayload);
+    }
+    // YAML workflows resolve transactionally inside the workflow; only resolve here for Durable
+    if (signalRouting.engine !== 'yaml') {
+        await escalationService.resolveEscalation(escalation.id, resolverPayload);
+    }
+    publishResolvedEvent(escalation, {
+        workflowId: escalation.workflow_id || signalRouting.workflowId,
+        workflowName: escalation.workflow_type || signalRouting.workflowType,
+        taskQueue: escalation.task_queue || signalRouting.taskQueue || signalRouting.appId,
+        status: signalRouting.engine === 'yaml' ? 'signaled' : 'resolved',
+    });
+    return signaledResult(escalation, signalRouting.workflowId || signalRouting.appId);
+}
+/** Path C: escalation strategy directed triage — start a triage workflow. */
+async function resolveViaTriage(escalation, resolverPayload, triageEnvelope) {
+    const triageWorkflowId = `triage-${escalation.id}-${Date.now()}`;
+    const client = (0, workers_1.createClient)();
+    await taskService.createTask({
+        workflow_id: triageWorkflowId,
+        workflow_type: 'mcpTriageRouter',
+        lt_type: 'mcpTriage',
+        task_queue: 'long-tail-system',
+        signal_id: `lt-triage-${triageWorkflowId}`,
+        parent_workflow_id: triageWorkflowId,
+        origin_id: escalation.origin_id || triageWorkflowId,
+        parent_id: escalation.parent_id ?? undefined,
+        envelope: JSON.stringify(triageEnvelope),
+    });
+    await client.workflow.start({
+        workflowName: 'mcpTriageRouter',
+        args: [triageEnvelope],
+        taskQueue: 'long-tail-system',
+        workflowId: triageWorkflowId,
+        expire: defaults_1.JOB_EXPIRE_SECS,
+        entity: 'mcpTriageRouter',
+    });
+    await escalationService.resolveEscalation(escalation.id, {
+        ...resolverPayload,
+        _lt: { ...resolverPayload._lt, triaged: true, triageWorkflowId },
+    });
+    publishResolvedEvent(escalation);
+    return {
+        status: 200,
+        data: { started: true, escalationId: escalation.id, workflowId: triageWorkflowId, triage: true },
+    };
+}
+/** Path E: standard re-run — inject resolver data and restart the original workflow. */
+async function resolveViaRerun(escalation, envelope, resolverPayload) {
+    envelope.resolver = resolverPayload;
+    envelope.lt = { ...envelope.lt, escalationId: escalation.id };
+    const newWorkflowId = `rerun-${escalation.id}-${Date.now()}`;
+    const client = (0, workers_1.createClient)();
+    await client.workflow.start({
+        workflowName: escalation.workflow_type,
+        args: [envelope],
+        taskQueue: escalation.task_queue,
+        workflowId: newWorkflowId,
+        expire: 180,
+    });
+    publishResolvedEvent(escalation);
+    return {
+        status: 200,
+        data: { started: true, escalationId: escalation.id, workflowId: newWorkflowId },
+    };
+}
+// ── Shared helpers ───────────────────────────────────────────────────────
+function publishResolvedEvent(escalation, overrides) {
+    (0, publish_1.publishEscalationEvent)({
+        type: 'escalation.resolved',
+        source: 'api',
+        workflowId: overrides?.workflowId || escalation.workflow_id || '',
+        workflowName: overrides?.workflowName || escalation.workflow_type || '',
+        taskQueue: overrides?.taskQueue || escalation.task_queue || '',
+        taskId: escalation.task_id,
+        escalationId: escalation.id,
+        originId: escalation.origin_id ?? undefined,
+        status: overrides?.status || 'resolved',
+    });
+}
+function signaledResult(escalation, workflowId) {
+    return {
+        status: 200,
+        data: { signaled: true, escalationId: escalation.id, workflowId },
+    };
+}
+/** Replace password fields with ephemeral tokens so plaintext never enters the signal store. */
+async function redactPasswords(payload, formSchema) {
+    if (!formSchema?.properties)
+        return payload;
+    const redacted = { ...payload };
+    for (const [key, def] of Object.entries(formSchema.properties)) {
+        if (def?.format === 'password' && typeof redacted[key] === 'string') {
+            const uuid = await (0, ephemeral_1.storeEphemeral)(redacted[key], { ttlSeconds: 900, label: key });
+            redacted[key] = (0, ephemeral_1.formatEphemeralToken)(uuid, key);
+        }
+    }
+    return redacted;
+}
+/** Reconstruct the original envelope from the escalation record or its task. */
+async function reconstructEnvelope(escalation) {
+    if (escalation.envelope) {
+        try {
+            return JSON.parse(escalation.envelope);
+        }
+        catch { /* use empty */ }
+    }
+    else if (escalation.task_id) {
+        const task = await taskService.getTask(escalation.task_id);
+        if (task?.envelope) {
+            try {
+                return JSON.parse(task.envelope);
+            }
+            catch { /* use empty */ }
+        }
+    }
+    return {};
+}

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

@@ -0,0 +1,37 @@
+import type { LTApiResult, LTApiAuth } from '../../types/sdk';
+/**
+ * Get a single escalation by ID.
+ *
+ * Non-superadmin users must hold the escalation's assigned role.
+ *
+ * @param input.id — escalation UUID
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: <escalation record> }` or 403/404
+ */
+export declare function getEscalation(input: {
+    id: string;
+}, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * List all escalations for a given workflow ID.
+ *
+ * @param input.workflowId — HotMesh workflow ID
+ * @returns `{ status: 200, data: { escalations } }`
+ */
+export declare function getEscalationsByWorkflowId(input: {
+    workflowId: string;
+}): Promise<LTApiResult>;
+/**
+ * Route a pending escalation to a different role.
+ *
+ * The user must be authorized to escalate from the current role to the
+ * target role (checked via escalation chain configuration).
+ *
+ * @param input.id — escalation UUID
+ * @param input.targetRole — destination role
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: <updated escalation> }` or 403/404/409
+ */
+export declare function escalateToRole(input: {
+    id: string;
+    targetRole: string;
+}, auth: LTApiAuth): Promise<LTApiResult>;