@hotmeshio/long-tail 0.1.7 → 0.1.9

package/build/api/escalations.d.ts

@@ -1,4 +1,51 @@
 import type { LTApiResult, LTApiAuth } from '../types/sdk';
+/**
+ * Create a standalone escalation (not tied to a workflow).
+ *
+ * Useful for manual work items, support tickets, or approval requests
+ * that originate outside the durable workflow engine. The caller must
+ * hold the target role or be a superadmin.
+ *
+ * @param input.type — escalation category (e.g. `"support"`, `"approval"`)
+ * @param input.subtype — subcategory for finer routing
+ * @param input.role — role responsible for resolving this escalation
+ * @param input.description — human-readable summary
+ * @param input.priority — 1 (critical) through 4 (low), default 2
+ * @param input.envelope — serialized context for the resolver
+ * @param input.metadata — arbitrary key-value data (e.g. signal_routing)
+ * @param input.escalation_payload — serialized payload for the resolver UI
+ * @param auth — authenticated user context (must hold target role or be superadmin)
+ * @returns `{ status: 201, data: <escalation record> }`
+ */
+export declare function createEscalation(input: {
+    type: string;
+    subtype?: string;
+    role: string;
+    description?: string;
+    priority?: number;
+    envelope?: string;
+    metadata?: Record<string, any>;
+    escalation_payload?: string;
+}, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * 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;
@@ -11,6 +58,23 @@ export declare function listEscalations(input: {
     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;
@@ -21,49 +85,186 @@ export declare function listAvailableEscalations(input: {
     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>;
+/**
+ * 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>;
+/**
+ * Claim a pending escalation for the authenticated user.
+ *
+ * Sets `assigned_to` and `assigned_until` on the escalation (soft lock).
+ * Non-superadmin users must hold the escalation's role. Publishes a
+ * `escalation.claimed` event.
+ *
+ * @param input.id — escalation UUID
+ * @param input.durationMinutes — claim duration (default: 30)
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { escalation, isExtension } }` or 403/404/409
+ */
 export declare function claimEscalation(input: {
     id: string;
     durationMinutes?: number;
 }, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Release a claimed escalation back to the pool.
+ *
+ * Only the user who holds the claim can release it. Publishes a
+ * `escalation.released` event.
+ *
+ * @param input.id — escalation UUID
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { escalation } }` or 409
+ */
 export declare function releaseEscalation(input: {
     id: string;
 }, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Release all escalation claims past their `assigned_until` deadline.
+ *
+ * Typically called on a maintenance schedule. Returns the count of
+ * released claims.
+ *
+ * @returns `{ status: 200, data: { released: number } }`
+ */
 export declare function releaseExpiredClaims(): Promise<LTApiResult>;
+/**
+ * Update priority for one or more escalations.
+ *
+ * @param input.ids — array of escalation UUIDs
+ * @param input.priority — new priority (1=critical, 2=high, 3=medium, 4=low)
+ * @param auth — authenticated user context (admin or role-holder required)
+ * @returns `{ status: 200, data: { updated: number } }`
+ */
 export declare function updatePriority(input: {
     ids: string[];
     priority: number;
 }, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Claim multiple escalations at once for the authenticated user.
+ *
+ * @param input.ids — array of escalation UUIDs
+ * @param input.durationMinutes — claim duration (default: 30)
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { claimed, skipped } }`
+ */
 export declare function bulkClaim(input: {
     ids: string[];
     durationMinutes?: number;
 }, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Assign multiple escalations to a specific user.
+ *
+ * Non-superadmin callers must verify the target user holds each
+ * escalation's role. Publishes claim events for assigned items.
+ *
+ * @param input.ids — array of escalation UUIDs
+ * @param input.targetUserId — user to assign to
+ * @param input.durationMinutes — assignment duration (default: 30)
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { assigned, skipped } }`
+ */
 export declare function bulkAssign(input: {
     ids: string[];
     targetUserId: string;
     durationMinutes?: number;
 }, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Route multiple escalations to a different role.
+ *
+ * @param input.ids — array of escalation UUIDs
+ * @param input.targetRole — destination role
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { updated: number } }`
+ */
 export declare function bulkEscalate(input: {
     ids: string[];
     targetRole: string;
 }, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Trigger AI triage for multiple escalations.
+ *
+ * Resolves each escalation and starts a triage workflow that uses MCP
+ * tools to analyze and potentially auto-resolve the issue.
+ *
+ * @param input.ids — array of escalation UUIDs
+ * @param input.hint — optional natural-language guidance for the triage AI
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { triaged, workflows } }`
+ */
 export declare function bulkTriage(input: {
     ids: string[];
     hint?: string;
 }, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Resolve a pending escalation with a human-provided payload.
+ *
+ * Handles two resolution paths:
+ * 1. **Signal-routed** — if the escalation has `signal_routing` metadata,
+ *    the resolver payload is sent directly to the paused workflow via
+ *    `handle.signal()`. Supports both Durable and YAML engines.
+ * 2. **Re-run** — the original workflow is re-started with the resolver
+ *    payload injected into `envelope.resolver`. The interceptor detects
+ *    the re-run and skips to the resolution branch.
+ *
+ * Password fields in the resolver payload are replaced with ephemeral
+ * tokens (15-minute TTL) so plaintext never enters the signal store.
+ *
+ * Supports optional escalation strategy execution after resolution.
+ *
+ * @param input.id — escalation UUID
+ * @param input.resolverPayload — human decision data
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { signaled, escalationId, workflowId } }` (signal path)
+ *          or `{ status: 200, data: { workflowId, resumed, escalationId } }` (re-run path)
+ */
 export declare function resolveEscalation(input: {
     id: string;
     resolverPayload: Record<string, any>;

package/build/api/escalations.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEscalation = createEscalation;
 exports.listEscalations = listEscalations;
 exports.listAvailableEscalations = listAvailableEscalations;
 exports.listDistinctTypes = listDistinctTypes;
@@ -97,7 +98,88 @@ function publishBulkClaimEvents(ids, assignedTo) {
         });
     }
 }
+// ── Create ────────────────────────────────────────────────────────────────
+/**
+ * Create a standalone escalation (not tied to a workflow).
+ *
+ * Useful for manual work items, support tickets, or approval requests
+ * that originate outside the durable workflow engine. The caller must
+ * hold the target role or be a superadmin.
+ *
+ * @param input.type — escalation category (e.g. `"support"`, `"approval"`)
+ * @param input.subtype — subcategory for finer routing
+ * @param input.role — role responsible for resolving this escalation
+ * @param input.description — human-readable summary
+ * @param input.priority — 1 (critical) through 4 (low), default 2
+ * @param input.envelope — serialized context for the resolver
+ * @param input.metadata — arbitrary key-value data (e.g. signal_routing)
+ * @param input.escalation_payload — serialized payload for the resolver UI
+ * @param auth — authenticated user context (must hold target role or be superadmin)
+ * @returns `{ status: 201, data: <escalation record> }`
+ */
+async function createEscalation(input, auth) {
+    try {
+        const { type, role } = input;
+        if (!type || typeof type !== 'string') {
+            return { status: 400, error: 'type is required' };
+        }
+        if (!role || typeof role !== 'string') {
+            return { status: 400, error: 'role is required' };
+        }
+        // RBAC: caller must hold the target role or be superadmin
+        const isSuperAdminUser = await userService.isSuperAdmin(auth.userId);
+        if (!isSuperAdminUser) {
+            const userHasRole = await userService.hasRole(auth.userId, role);
+            if (!userHasRole) {
+                return { status: 403, error: `You must hold the "${role}" role or be a superadmin to create escalations for it` };
+            }
+        }
+        const escalation = await escalationService.createEscalation({
+            type,
+            subtype: input.subtype ?? type,
+            description: input.description,
+            priority: input.priority,
+            role,
+            envelope: input.envelope ?? '{}',
+            metadata: input.metadata,
+            escalation_payload: input.escalation_payload,
+        });
+        (0, publish_1.publishEscalationEvent)({
+            type: 'escalation.created',
+            source: 'api',
+            workflowId: '',
+            workflowName: '',
+            taskQueue: '',
+            escalationId: escalation.id,
+            status: 'pending',
+            data: { type: input.type, role },
+        });
+        return { status: 201, data: escalation };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
 // ── 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 getVisibleRoles(auth.userId);
@@ -123,6 +205,23 @@ async function listEscalations(input, auth) {
         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 getVisibleRoles(auth.userId);
@@ -146,6 +245,11 @@ async function listAvailableEscalations(input, auth) {
         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();
@@ -155,6 +259,13 @@ async function listDistinctTypes() {
         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 getVisibleRoles(auth.userId);
@@ -179,6 +290,15 @@ async function getEscalationStats(input, auth) {
     }
 }
 // ── Single-escalation routes ───────────────────────────────────────────────
+/**
+ * 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
+ */
 async function getEscalation(input, auth) {
     try {
         const escalation = await escalationService.getEscalation(input.id);
@@ -198,6 +318,12 @@ async function getEscalation(input, auth) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * List all escalations for a given workflow ID.
+ *
+ * @param input.workflowId — HotMesh workflow ID
+ * @returns `{ status: 200, data: { escalations } }`
+ */
 async function getEscalationsByWorkflowId(input) {
     try {
         const escalations = await escalationService.getEscalationsByWorkflowId(input.workflowId);
@@ -207,6 +333,17 @@ async function getEscalationsByWorkflowId(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * 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
+ */
 async function escalateToRole(input, auth) {
     try {
         const { id, targetRole } = input;
@@ -234,6 +371,18 @@ async function escalateToRole(input, auth) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Claim a pending escalation for the authenticated user.
+ *
+ * Sets `assigned_to` and `assigned_until` on the escalation (soft lock).
+ * Non-superadmin users must hold the escalation's role. Publishes a
+ * `escalation.claimed` event.
+ *
+ * @param input.id — escalation UUID
+ * @param input.durationMinutes — claim duration (default: 30)
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { escalation, isExtension } }` or 403/404/409
+ */
 async function claimEscalation(input, auth) {
     try {
         const { id, durationMinutes } = input;
@@ -271,6 +420,16 @@ async function claimEscalation(input, auth) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Release a claimed escalation back to the pool.
+ *
+ * Only the user who holds the claim can release it. Publishes a
+ * `escalation.released` event.
+ *
+ * @param input.id — escalation UUID
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { escalation } }` or 409
+ */
 async function releaseEscalation(input, auth) {
     try {
         const result = await escalationService.releaseEscalation(input.id, auth.userId);
@@ -294,6 +453,14 @@ async function releaseEscalation(input, auth) {
     }
 }
 // ── Bulk routes ────────────────────────────────────────────────────────────
+/**
+ * Release all escalation claims past their `assigned_until` deadline.
+ *
+ * Typically called on a maintenance schedule. Returns the count of
+ * released claims.
+ *
+ * @returns `{ status: 200, data: { released: number } }`
+ */
 async function releaseExpiredClaims() {
     try {
         const released = await escalationService.releaseExpiredClaims();
@@ -303,6 +470,14 @@ async function releaseExpiredClaims() {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Update priority for one or more escalations.
+ *
+ * @param input.ids — array of escalation UUIDs
+ * @param input.priority — new priority (1=critical, 2=high, 3=medium, 4=low)
+ * @param auth — authenticated user context (admin or role-holder required)
+ * @returns `{ status: 200, data: { updated: number } }`
+ */
 async function updatePriority(input, auth) {
     try {
         const { ids, priority } = input;
@@ -322,6 +497,14 @@ async function updatePriority(input, auth) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Claim multiple escalations at once for the authenticated user.
+ *
+ * @param input.ids — array of escalation UUIDs
+ * @param input.durationMinutes — claim duration (default: 30)
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { claimed, skipped } }`
+ */
 async function bulkClaim(input, auth) {
     try {
         const { ids, durationMinutes } = input;
@@ -340,6 +523,18 @@ async function bulkClaim(input, auth) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Assign multiple escalations to a specific user.
+ *
+ * Non-superadmin callers must verify the target user holds each
+ * escalation's role. Publishes claim events for assigned items.
+ *
+ * @param input.ids — array of escalation UUIDs
+ * @param input.targetUserId — user to assign to
+ * @param input.durationMinutes — assignment duration (default: 30)
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { assigned, skipped } }`
+ */
 async function bulkAssign(input, auth) {
     try {
         const { ids, targetUserId, durationMinutes } = input;
@@ -372,6 +567,14 @@ async function bulkAssign(input, auth) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Route multiple escalations to a different role.
+ *
+ * @param input.ids — array of escalation UUIDs
+ * @param input.targetRole — destination role
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { updated: number } }`
+ */
 async function bulkEscalate(input, auth) {
     try {
         const { ids, targetRole } = input;
@@ -391,6 +594,17 @@ async function bulkEscalate(input, auth) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Trigger AI triage for multiple escalations.
+ *
+ * Resolves each escalation and starts a triage workflow that uses MCP
+ * tools to analyze and potentially auto-resolve the issue.
+ *
+ * @param input.ids — array of escalation UUIDs
+ * @param input.hint — optional natural-language guidance for the triage AI
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { triaged, workflows } }`
+ */
 async function bulkTriage(input, auth) {
     try {
         const { ids, hint } = input;
@@ -414,6 +628,28 @@ async function bulkTriage(input, auth) {
     }
 }
 // ── Resolve route ──────────────────────────────────────────────────────────
+/**
+ * Resolve a pending escalation with a human-provided payload.
+ *
+ * Handles two resolution paths:
+ * 1. **Signal-routed** — if the escalation has `signal_routing` metadata,
+ *    the resolver payload is sent directly to the paused workflow via
+ *    `handle.signal()`. Supports both Durable and YAML engines.
+ * 2. **Re-run** — the original workflow is re-started with the resolver
+ *    payload injected into `envelope.resolver`. The interceptor detects
+ *    the re-run and skips to the resolution branch.
+ *
+ * Password fields in the resolver payload are replaced with ephemeral
+ * tokens (15-minute TTL) so plaintext never enters the signal store.
+ *
+ * Supports optional escalation strategy execution after resolution.
+ *
+ * @param input.id — escalation UUID
+ * @param input.resolverPayload — human decision data
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { signaled, escalationId, workflowId } }` (signal path)
+ *          or `{ status: 200, data: { workflowId, resumed, escalationId } }` (re-run path)
+ */
 async function resolveEscalation(input, auth) {
     try {
         const { id, resolverPayload } = input;
@@ -428,7 +664,42 @@ async function resolveEscalation(input, auth) {
         if (escalation.status !== 'pending') {
             return { status: 409, error: 'Escalation not available for resolution' };
         }
-        // 2. waitFor signal escalation -- signal the paused workflow directly
+        // 2. Lightweight signal path: metadata.signal_id + escalation fields
+        //    The workflow called `await conditionLT(signalId)` and created its
+        //    own escalation with the signal_id in metadata. On resolution, we
+        //    inject $escalation_id into the payload and signal the running
+        //    workflow. The workflow is responsible for resolving the escalation
+        //    (conditionLT handles this automatically via a durable activity).
+        const metadataSignalId = escalation.metadata?.signal_id;
+        if (metadataSignalId && escalation.workflow_id && escalation.task_queue && escalation.workflow_type) {
+            const client = (0, workers_1.createClient)();
+            const handle = await client.workflow.getHandle(escalation.task_queue, escalation.workflow_type, escalation.workflow_id);
+            await handle.signal(metadataSignalId, {
+                ...resolverPayload,
+                $escalation_id: escalation.id,
+            });
+            (0, publish_1.publishEscalationEvent)({
+                type: 'escalation.resolved',
+                source: 'api',
+                workflowId: escalation.workflow_id,
+                workflowName: escalation.workflow_type,
+                taskQueue: escalation.task_queue,
+                taskId: escalation.task_id,
+                escalationId: escalation.id,
+                originId: escalation.origin_id ?? undefined,
+                status: 'resolved',
+            });
+            return {
+                status: 200,
+                data: {
+                    signaled: true,
+                    escalationId: escalation.id,
+                    workflowId: escalation.workflow_id,
+                },
+            };
+        }
+        // 3. waitFor signal escalation -- signal the paused workflow directly
+        //    (full signal_routing object from interceptor/MCP tool)
         const signalRouting = escalation.metadata?.signal_routing;
         if (signalRouting?.signalId) {
             // Replace password fields with ephemeral tokens so plaintext never enters the signal store
@@ -480,7 +751,7 @@ async function resolveEscalation(input, auth) {
                 },
             };
         }
-        // 3. Reconstruct the original envelope from the escalation or task
+        // 4. Reconstruct the original envelope from the escalation or task
         let envelope = {};
         if (escalation.envelope) {
             try {
@@ -497,7 +768,7 @@ async function resolveEscalation(input, auth) {
                 catch { /* use empty */ }
             }
         }
-        // 4. Check escalation strategy for triage routing
+        // 5. Check escalation strategy for triage routing
         const strategy = escalation_strategy_1.escalationStrategyRegistry.current;
         if (strategy) {
             const directive = await strategy.onResolution({
@@ -557,12 +828,12 @@ async function resolveEscalation(input, auth) {
                 };
             }
         }
-        // 5. If no workflow_type, this is a notification-only escalation -- acknowledge and close
+        // 6. If no workflow_type, this is a notification-only escalation -- acknowledge and close
         if (!escalation.workflow_type || !escalation.task_queue) {
             await escalationService.resolveEscalation(escalation.id, resolverPayload);
             return { status: 200, data: { acknowledged: true, escalationId: escalation.id } };
         }
-        // 6. Standard re-run: inject resolver data and start original workflow
+        // 7. Standard re-run: inject resolver data and start original workflow
         envelope.resolver = resolverPayload;
         envelope.lt = {
             ...envelope.lt,