@hotmeshio/long-tail 0.1.14 → 0.1.16

package/README.md

@@ -70,6 +70,19 @@ export async function analyzeContent(content: string) {
 }
 ```
 
+## Compile Workflows
+
+Write durable workflows in TypeScript. Compile to YAML DAGs that run without replay overhead. `ltc` is the compiler — like `tsc` for workflows.
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+
+npx ltc compile workflows/              # scan and compile all workflow files
+npx ltc compile --dry-run               # discover without compiling
+```
+
+The source is the spec. The compiled YAML is the optimized execution. Both live in the repo. See the [Compiler Guide](docs/compiler.md).
+
 ## Certify a Workflow
 
 Any durable workflow can be promoted to **certified** through the dashboard or API. A certified workflow gains interceptor guarantees: failures escalate instead of throwing, escalation chains route through roles, and every error is either handled or surfaced. It cannot silently fail.
@@ -243,6 +256,8 @@ All modes share PostgreSQL and scale independently. See [Cloud Deployment](docs/
 | [Dashboard](docs/dashboard.md) | Navigation, key pages, event feed |
 | [MCP](docs/mcp.md) | Server registration, tool calls, human queue |
 | [Compilation](docs/compilation.md) | Dynamic → deterministic pipeline wizard |
+| [Compiler](docs/compiler.md) | `ltc compile` — durable TypeScript to YAML DAGs |
+| [CLI](docs/cli.md) | `ltc` — terminal access to workflows, escalations, knowledge, MCP |
 | [Escalation Strategies](docs/escalation-strategies.md) | Default, MCP triage, custom handlers |
 | [SDK](docs/sdk.md) | Embedded usage, `createClient`, event subscriptions |
 | [Architecture](docs/architecture.md) | Project structure, conventions, discovery |

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

@@ -0,0 +1,78 @@
+import type { LTApiResult, LTApiAuth } from '../../types/sdk';
+/**
+ * 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>;

package/build/api/escalations/bulk.js

@@ -0,0 +1,279 @@
+"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.releaseExpiredClaims = releaseExpiredClaims;
+exports.updatePriority = updatePriority;
+exports.bulkClaim = bulkClaim;
+exports.bulkAssign = bulkAssign;
+exports.bulkEscalate = bulkEscalate;
+exports.bulkTriage = bulkTriage;
+const escalationService = __importStar(require("../../services/escalation"));
+const userService = __importStar(require("../../services/user"));
+const taskService = __importStar(require("../../services/task"));
+const workers_1 = require("../../workers");
+const defaults_1 = require("../../modules/defaults");
+const helpers_1 = require("./helpers");
+// ── 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();
+        return { status: 200, data: { released } };
+    }
+    catch (err) {
+        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;
+        if (!(0, helpers_1.validateIds)(ids)) {
+            return { status: 400, error: 'ids must be a non-empty array' };
+        }
+        if (![1, 2, 3, 4].includes(priority)) {
+            return { status: 400, error: 'priority must be 1, 2, 3, or 4' };
+        }
+        const perm = await (0, helpers_1.checkBulkPermission)(auth.userId, ids);
+        if (!perm.allowed)
+            return perm;
+        const updated = await escalationService.updateEscalationsPriority(ids, priority);
+        return { status: 200, data: { updated } };
+    }
+    catch (err) {
+        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;
+        if (!(0, helpers_1.validateIds)(ids)) {
+            return { status: 400, error: 'ids must be a non-empty array' };
+        }
+        const perm = await (0, helpers_1.checkBulkPermission)(auth.userId, ids);
+        if (!perm.allowed)
+            return perm;
+        const result = await escalationService.bulkClaimEscalations(ids, auth.userId, durationMinutes ?? 30);
+        if (result.claimed > 0)
+            (0, helpers_1.publishBulkClaimEvents)(ids, auth.userId);
+        return { status: 200, data: result };
+    }
+    catch (err) {
+        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;
+        if (!(0, helpers_1.validateIds)(ids)) {
+            return { status: 400, error: 'ids must be a non-empty array' };
+        }
+        if (!targetUserId || typeof targetUserId !== 'string') {
+            return { status: 400, error: 'targetUserId is required' };
+        }
+        const perm = await (0, helpers_1.checkBulkPermission)(auth.userId, ids);
+        if (!perm.allowed)
+            return perm;
+        // Non-superadmin: target user must hold each escalation's role
+        const isSuperAdminUser = await userService.isSuperAdmin(auth.userId);
+        if (!isSuperAdminUser) {
+            const roles = await escalationService.getEscalationRoles(ids);
+            for (const role of roles) {
+                const targetHasRole = await userService.hasRole(targetUserId, role);
+                if (!targetHasRole) {
+                    return { status: 400, error: `Target user does not hold the "${role}" role` };
+                }
+            }
+        }
+        const result = await escalationService.bulkAssignEscalations(ids, targetUserId, durationMinutes ?? 30);
+        if (result.assigned > 0)
+            (0, helpers_1.publishBulkClaimEvents)(ids, targetUserId);
+        return { status: 200, data: result };
+    }
+    catch (err) {
+        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;
+        if (!(0, helpers_1.validateIds)(ids)) {
+            return { status: 400, error: 'ids must be a non-empty array' };
+        }
+        if (!targetRole || typeof targetRole !== 'string') {
+            return { status: 400, error: 'targetRole is required' };
+        }
+        const perm = await (0, helpers_1.checkBulkPermission)(auth.userId, ids);
+        if (!perm.allowed)
+            return perm;
+        const updated = await escalationService.bulkEscalateToRole(ids, targetRole);
+        return { status: 200, data: { updated } };
+    }
+    catch (err) {
+        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;
+        if (!(0, helpers_1.validateIds)(ids)) {
+            return { status: 400, error: 'ids must be a non-empty array' };
+        }
+        const perm = await (0, helpers_1.checkBulkPermission)(auth.userId, ids);
+        if (!perm.allowed)
+            return perm;
+        const resolved = await escalationService.bulkResolveForTriage(ids, hint);
+        const client = (0, workers_1.createClient)();
+        const workflowIds = [];
+        for (const escalation of resolved) {
+            const triageWorkflowId = await startTriageWorkflow(escalation, hint, auth.userId, client);
+            workflowIds.push(triageWorkflowId);
+        }
+        return { status: 200, data: { triaged: resolved.length, workflows: workflowIds } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+// ── Triage workflow launcher (shared by bulkTriage) ────────────────────────
+async function startTriageWorkflow(escalation, hint, userId, client) {
+    let escalationPayload = {};
+    if (escalation.escalation_payload) {
+        try {
+            escalationPayload = JSON.parse(escalation.escalation_payload);
+        }
+        catch { }
+    }
+    let envelope = {};
+    if (escalation.envelope) {
+        try {
+            envelope = JSON.parse(escalation.envelope);
+        }
+        catch { }
+    }
+    const triageWorkflowId = `triage-${escalation.id}-${Date.now()}`;
+    const triageEnvelope = {
+        data: {
+            escalationId: escalation.id,
+            originId: escalation.origin_id ?? undefined,
+            originalWorkflowType: escalation.workflow_type,
+            originalTaskQueue: escalation.task_queue,
+            originalTaskId: escalation.task_id,
+            escalationPayload,
+            resolverPayload: {
+                _lt: { needsTriage: true, ...(hint ? { hint } : {}) },
+            },
+        },
+        metadata: envelope.metadata || {},
+        lt: { ...(envelope.lt || {}), userId },
+    };
+    const routing = escalation.task_id
+        ? (await taskService.getTask(escalation.task_id))?.metadata
+        : null;
+    await taskService.createTask({
+        workflow_id: triageWorkflowId,
+        workflow_type: 'mcpTriage',
+        lt_type: 'mcpTriage',
+        task_queue: 'long-tail-system',
+        signal_id: `lt-triage-${triageWorkflowId}`,
+        parent_workflow_id: routing?.parentWorkflowId || triageWorkflowId,
+        origin_id: escalation.origin_id || triageWorkflowId,
+        parent_id: escalation.parent_id ?? undefined,
+        envelope: JSON.stringify(triageEnvelope),
+        metadata: routing || undefined,
+    });
+    await client.workflow.start({
+        workflowName: 'mcpTriage',
+        args: [triageEnvelope],
+        taskQueue: 'long-tail-system',
+        workflowId: triageWorkflowId,
+        expire: defaults_1.JOB_EXPIRE_SECS,
+        entity: 'mcpTriage',
+    });
+    return triageWorkflowId;
+}

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

@@ -0,0 +1,30 @@
+import type { LTApiResult, LTApiAuth } from '../../types/sdk';
+/**
+ * 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>;

package/build/api/escalations/claim.js

@@ -0,0 +1,121 @@
+"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.claimEscalation = claimEscalation;
+exports.releaseEscalation = releaseEscalation;
+const escalationService = __importStar(require("../../services/escalation"));
+const userService = __importStar(require("../../services/user"));
+const publish_1 = require("../../lib/events/publish");
+/**
+ * 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;
+        const escalation = await escalationService.getEscalation(id);
+        if (!escalation) {
+            return { status: 404, error: 'Escalation not found' };
+        }
+        const isSuperAdminUser = await userService.isSuperAdmin(auth.userId);
+        if (!isSuperAdminUser) {
+            const userHasRole = await userService.hasRole(auth.userId, escalation.role);
+            if (!userHasRole) {
+                return {
+                    status: 403,
+                    error: `You must have the "${escalation.role}" role to claim this escalation`,
+                };
+            }
+        }
+        const result = await escalationService.claimEscalation(id, auth.userId, durationMinutes);
+        if (!result) {
+            return { status: 409, error: 'Escalation not available for claim' };
+        }
+        (0, publish_1.publishEscalationEvent)({
+            type: 'escalation.claimed',
+            source: 'api',
+            workflowId: escalation.workflow_id || '',
+            workflowName: escalation.workflow_type || '',
+            taskQueue: escalation.task_queue || '',
+            escalationId: id,
+            status: 'claimed',
+            data: { assigned_to: auth.userId },
+        });
+        return { status: 200, data: result };
+    }
+    catch (err) {
+        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);
+        if (!result) {
+            return { status: 409, error: 'Escalation not found or not claimed by you' };
+        }
+        (0, publish_1.publishEscalationEvent)({
+            type: 'escalation.released',
+            source: 'api',
+            workflowId: result.workflow_id || '',
+            workflowName: result.workflow_type || '',
+            taskQueue: result.task_queue || '',
+            escalationId: input.id,
+            status: 'released',
+            data: { released_by: auth.userId },
+        });
+        return { status: 200, data: { escalation: result } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}

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

@@ -0,0 +1,29 @@
+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>;

package/build/api/escalations/create.js

@@ -0,0 +1,101 @@
+"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.createEscalation = createEscalation;
+const escalationService = __importStar(require("../../services/escalation"));
+const userService = __importStar(require("../../services/user"));
+const publish_1 = require("../../lib/events/publish");
+// ── 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 };
+    }
+}

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

@@ -0,0 +1,10 @@
+export declare function getVisibleRoles(userId: string): Promise<string[] | undefined>;
+export declare function validateIds(ids: unknown): ids is string[];
+export declare function checkBulkPermission(userId: string, ids: string[]): Promise<{
+    allowed: true;
+} | {
+    allowed: false;
+    status: 403;
+    error: string;
+}>;
+export declare function publishBulkClaimEvents(ids: string[], assignedTo: string): void;