@hotmeshio/long-tail 0.1.7 → 0.1.9

package/build/examples/workflows/assembly-line/reverter.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * Reverter — durable step loop with revert support.
+ *
+ * Like stepIterator, but each human resolution can send the
+ * pipeline backwards. The resolver payload controls flow:
+ *
+ *   { approved: true }              → advance to next step
+ *   { approved: false, revertSteps: 1 }  → go back 1 step
+ *   { approved: false, revertSteps: 2 }  → go back 2 steps
+ *
+ * The orchestrator tracks a monotonic attempt counter so every
+ * child spawn gets a unique workflow ID and signal key — even
+ * when revisiting a step after a revert.
+ *
+ * The full history (approvals + reverts) is recorded in the result.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reverter = reverter;
+const hotmesh_1 = require("@hotmeshio/hotmesh");
+const defaults_1 = require("../../../modules/defaults");
+async function reverter(envelope) {
+    const { name, steps } = envelope.data;
+    const ctx = hotmesh_1.Durable.workflow.workflowInfo();
+    const history = [];
+    const finalResults = [];
+    let stepIndex = 0;
+    let attempt = 0;
+    while (stepIndex < steps.length) {
+        const step = steps[stepIndex];
+        const signalId = `step-${stepIndex}-a${attempt}-${ctx.workflowId}`;
+        const childWorkflowId = `workstation-${ctx.workflowId}-${stepIndex}-a${attempt}`;
+        await hotmesh_1.Durable.workflow.startChild({
+            workflowName: 'workstation',
+            args: [
+                {
+                    data: {
+                        ...step,
+                        parentSignalId: signalId,
+                        parentTaskQueue: 'long-tail-examples',
+                        parentWorkflowType: 'reverter',
+                        parentWorkflowId: ctx.workflowId,
+                    },
+                    metadata: {
+                        source: 'reverter',
+                        step: stepIndex,
+                        attempt,
+                        totalSteps: steps.length,
+                    },
+                },
+            ],
+            taskQueue: 'long-tail-examples',
+            workflowId: childWorkflowId,
+            expire: defaults_1.JOB_EXPIRE_SECS,
+            entity: 'workstation',
+        });
+        const result = await hotmesh_1.Durable.workflow.condition(signalId);
+        const approved = result.resolution?.approved !== false;
+        const revertSteps = Number(result.resolution?.revertSteps) || 0;
+        history.push({
+            type: approved ? 'advance' : 'revert',
+            stepIndex,
+            stationName: step.stationName,
+            attempt,
+            resolution: result.resolution,
+            completedAt: result.completedAt,
+        });
+        attempt++;
+        if (approved) {
+            finalResults[stepIndex] = result;
+            stepIndex++;
+        }
+        else {
+            // Clamp revert target to 0
+            stepIndex = Math.max(0, stepIndex - revertSteps);
+        }
+    }
+    return {
+        type: 'return',
+        data: {
+            name,
+            totalSteps: steps.length,
+            totalAttempts: attempt,
+            steps: finalResults,
+            history,
+            completedAt: new Date().toISOString(),
+        },
+    };
+}

package/build/examples/workflows/assembly-line/types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Assembly Line types.
+ *
+ * Defines the station config passed in the envelope and the
+ * result shape each station returns when a human resolves it.
+ */
+export interface AssemblyLineStation {
+    stationName: string;
+    role: string;
+    instructions: string;
+}
+export interface StationEnvelopeData {
+    stationName: string;
+    role: string;
+    instructions: string;
+    parentSignalId: string;
+    parentTaskQueue: string;
+    parentWorkflowType: string;
+    parentWorkflowId: string;
+}
+export interface StationResult {
+    stationName: string;
+    resolution: Record<string, any>;
+    completedAt: string;
+}

package/build/examples/workflows/assembly-line/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Assembly Line types.
+ *
+ * Defines the station config passed in the envelope and the
+ * result shape each station returns when a human resolves it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/examples/workflows/assembly-line/worker.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Workstation — child workflow for the assembly line.
+ *
+ * Each workstation:
+ *   1. Creates an escalation assigned to its role (grinder, gluer, etc.)
+ *   2. Pauses (condition) until a human claims and resolves the escalation
+ *   3. Signals the parent orchestrator with the result
+ *
+ * No interceptor, no registration — just raw Durable primitives
+ * and a direct escalation record with signal routing metadata.
+ */
+import type { LTEnvelope } from '../../../types';
+export declare function workstation(envelope: LTEnvelope): Promise<any>;

package/build/examples/workflows/assembly-line/worker.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * Workstation — child workflow for the assembly line.
+ *
+ * Each workstation:
+ *   1. Creates an escalation assigned to its role (grinder, gluer, etc.)
+ *   2. Pauses (condition) until a human claims and resolves the escalation
+ *   3. Signals the parent orchestrator with the result
+ *
+ * No interceptor, no registration — just raw Durable primitives
+ * and a direct escalation record with signal routing metadata.
+ */
+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.workstation = workstation;
+const hotmesh_1 = require("@hotmeshio/hotmesh");
+const activities = __importStar(require("./activities"));
+const { createStationEscalation, signalParent } = hotmesh_1.Durable.workflow.proxyActivities({ activities });
+async function workstation(envelope) {
+    const { stationName, role, instructions, parentSignalId, parentTaskQueue, parentWorkflowType, parentWorkflowId, } = envelope.data;
+    const ctx = hotmesh_1.Durable.workflow.workflowInfo();
+    const localSignalId = `station-done-${ctx.workflowId}`;
+    // 1. Create escalation — human sees this in their queue
+    await createStationEscalation({
+        role,
+        stationName,
+        instructions,
+        workflowId: ctx.workflowId,
+        workflowType: 'workstation',
+        taskQueue: 'long-tail-examples',
+        signalId: localSignalId,
+    });
+    // 2. Pause until the human resolves the escalation
+    const resolution = await hotmesh_1.Durable.workflow.condition(localSignalId);
+    // 3. Build result and signal the parent orchestrator
+    const result = {
+        stationName,
+        resolution,
+        completedAt: new Date().toISOString(),
+    };
+    await signalParent({
+        parentTaskQueue,
+        parentWorkflowType,
+        parentWorkflowId,
+        signalId: parentSignalId,
+        data: result,
+    });
+    return { type: 'return', data: result };
+}

package/build/examples/workflows/basic-signal/activities.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Basic Signal Activities
+ *
+ * Simple activity for post-resolution processing. The escalation
+ * creation and resolution are handled via interceptor activities
+ * (ltCreateEscalation / ltResolveEscalation) proxied from the workflow.
+ */
+export declare function processApproval(input: {
+    approved: boolean;
+    notes: string;
+    message: string;
+}): Promise<{
+    message: string;
+    approved: boolean;
+    notes: string;
+    processedAt: string;
+}>;

package/build/examples/workflows/basic-signal/activities.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * Basic Signal Activities
+ *
+ * Simple activity for post-resolution processing. The escalation
+ * creation and resolution are handled via interceptor activities
+ * (ltCreateEscalation / ltResolveEscalation) proxied from the workflow.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.processApproval = processApproval;
+async function processApproval(input) {
+    return {
+        message: input.message,
+        approved: input.approved,
+        notes: input.notes,
+        processedAt: new Date().toISOString(),
+    };
+}

package/build/examples/workflows/basic-signal/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Basic Signal Workflow
+ *
+ * Lightweight signal-based escalation — the workflow stays running
+ * while waiting for human input. No interceptor, no certification.
+ *
+ *   1. Creates an escalation with `signal_id` in metadata
+ *   2. Pauses via `conditionLT(signalId)` — workflow stays alive
+ *   3. Dashboard resolver signals in with the form payload
+ *   4. `conditionLT` resolves the escalation via durable activity
+ *   5. Workflow continues with the clean resolver payload
+ *
+ * This demonstrates the lightweight alternative to the certified
+ * interceptor pattern — same escalation UX, simpler wiring.
+ */
+import type { LTEnvelope } from '../../../types';
+export declare function basicSignal(envelope: LTEnvelope): Promise<any>;

package/build/examples/workflows/basic-signal/index.js

@@ -0,0 +1,116 @@
+"use strict";
+/**
+ * Basic Signal Workflow
+ *
+ * Lightweight signal-based escalation — the workflow stays running
+ * while waiting for human input. No interceptor, no certification.
+ *
+ *   1. Creates an escalation with `signal_id` in metadata
+ *   2. Pauses via `conditionLT(signalId)` — workflow stays alive
+ *   3. Dashboard resolver signals in with the form payload
+ *   4. `conditionLT` resolves the escalation via durable activity
+ *   5. Workflow continues with the clean resolver payload
+ *
+ * This demonstrates the lightweight alternative to the certified
+ * interceptor pattern — same escalation UX, simpler wiring.
+ */
+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.basicSignal = basicSignal;
+const hotmesh_1 = require("@hotmeshio/hotmesh");
+const condition_1 = require("../../../services/orchestrator/condition");
+const interceptorActivities = __importStar(require("../../../services/interceptor/activities"));
+const activities = __importStar(require("./activities"));
+const LT_ACTIVITY_QUEUE = 'lt-interceptor';
+async function basicSignal(envelope) {
+    const { message = 'Please review and approve.', role = 'reviewer' } = envelope.data;
+    const { ltCreateEscalation } = hotmesh_1.Durable.workflow.proxyActivities({
+        activities: interceptorActivities,
+        taskQueue: LT_ACTIVITY_QUEUE,
+        retry: { maximumAttempts: 3 },
+    });
+    const { processApproval } = hotmesh_1.Durable.workflow.proxyActivities({
+        activities,
+    });
+    const ctx = hotmesh_1.Durable.workflow.workflowInfo();
+    const signalId = `approval-${ctx.workflowId}`;
+    // Create escalation with signal_id — dashboard knows to signal, not re-run.
+    //
+    // The resolver_schema registered in the workflow config provides the
+    // default form. To override per-instance, pass metadata.form_schema:
+    //
+    //   metadata: {
+    //     signal_id: signalId,
+    //     form_schema: {
+    //       properties: {
+    //         approved:    { type: 'boolean', default: false, description: 'Approve?' },
+    //         notes:       { type: 'string',  default: '',    description: 'Reviewer notes' },
+    //         environment: { type: 'string',  enum: ['staging', 'production'] },
+    //         api_key:     { type: 'string',  format: 'password', description: 'Deploy key (ephemeral)' },
+    //         confidence:  { type: 'number',  default: 0,     description: 'Confidence 0-1' },
+    //       },
+    //     },
+    //   },
+    //
+    // When form_schema is present it overrides the workflow config's
+    // resolver_schema for this specific escalation instance.
+    await ltCreateEscalation({
+        type: 'signal-approval',
+        subtype: 'basic-signal',
+        description: message,
+        role,
+        envelope: JSON.stringify(envelope),
+        workflowId: ctx.workflowId,
+        workflowType: 'basicSignal',
+        taskQueue: ctx.taskQueue,
+        metadata: {
+            signal_id: signalId,
+            // No form_schema here — the workflow config's resolver_schema is used.
+            // Pass form_schema to override per-instance (see comment above).
+        },
+    });
+    // Pause — conditionLT handles $escalation_id stripping and resolution
+    const decision = await (0, condition_1.conditionLT)(signalId);
+    // Continue with the clean resolver payload
+    const result = await processApproval({
+        approved: decision.approved,
+        notes: decision.notes || '',
+        message,
+    });
+    return {
+        type: 'return',
+        data: result,
+    };
+}

package/build/index.d.ts

@@ -2,6 +2,7 @@ export { start } from './start';
 export { registerLT, createLTInterceptor } from './services/interceptor';
 export { createLTActivityInterceptor } from './services/interceptor/activity-interceptor';
 export { executeLT } from './services/orchestrator';
+export { conditionLT } from './services/orchestrator/condition';
 export type { ExecuteLTOptions } from './services/orchestrator/types';
 export { JwtAuthAdapter, createAuthMiddleware, requireAuth, requireAdmin, signToken } from './modules/auth';
 export * from './types';

package/build/index.js

@@ -36,7 +36,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.api = exports.createClient = exports.CallbackEventAdapter = exports.seedSystemMcpServers = exports.builtinMcpServerFactories = exports.getSystemWorkers = exports.registerMcpTool = exports.getToolContext = exports.getActivityIdentity = exports.seedExamples = exports.exampleWorkers = exports.McpEscalationStrategy = exports.DefaultEscalationStrategy = exports.escalationStrategyRegistry = exports.McpVisionServer = exports.McpTranslationServer = exports.McpServer = exports.McpClient = exports.McpService = exports.BuiltInMcpAdapter = exports.mcpRegistry = exports.defaultMaintenanceConfig = exports.maintenanceRegistry = exports.PinoLoggerAdapter = exports.loggerRegistry = exports.HoneycombTelemetryAdapter = exports.telemetryRegistry = exports.publishWorkflowEvent = exports.publishEscalationEvent = exports.publishTaskEvent = exports.publishMilestoneEvent = exports.SocketIOEventAdapter = exports.InMemoryEventAdapter = exports.NatsEventAdapter = exports.eventRegistry = exports.ltConfig = exports.UserService = exports.ConfigService = exports.EscalationService = exports.TaskService = exports.signToken = exports.requireAdmin = exports.requireAuth = exports.createAuthMiddleware = exports.JwtAuthAdapter = exports.executeLT = exports.createLTActivityInterceptor = exports.createLTInterceptor = exports.registerLT = exports.start = void 0;
+exports.createClient = exports.CallbackEventAdapter = exports.seedSystemMcpServers = exports.builtinMcpServerFactories = exports.getSystemWorkers = exports.registerMcpTool = exports.getToolContext = exports.getActivityIdentity = exports.seedExamples = exports.exampleWorkers = exports.McpEscalationStrategy = exports.DefaultEscalationStrategy = exports.escalationStrategyRegistry = exports.McpVisionServer = exports.McpTranslationServer = exports.McpServer = exports.McpClient = exports.McpService = exports.BuiltInMcpAdapter = exports.mcpRegistry = exports.defaultMaintenanceConfig = exports.maintenanceRegistry = exports.PinoLoggerAdapter = exports.loggerRegistry = exports.HoneycombTelemetryAdapter = exports.telemetryRegistry = exports.publishWorkflowEvent = exports.publishEscalationEvent = exports.publishTaskEvent = exports.publishMilestoneEvent = exports.SocketIOEventAdapter = exports.InMemoryEventAdapter = exports.NatsEventAdapter = exports.eventRegistry = exports.ltConfig = exports.UserService = exports.ConfigService = exports.EscalationService = exports.TaskService = exports.signToken = exports.requireAdmin = exports.requireAuth = exports.createAuthMiddleware = exports.JwtAuthAdapter = exports.conditionLT = exports.executeLT = exports.createLTActivityInterceptor = exports.createLTInterceptor = exports.registerLT = exports.start = void 0;
+exports.api = void 0;
 const config_1 = require("./modules/config");
 const logger_1 = require("./lib/logger");
 const start_1 = require("./start");
@@ -50,6 +51,8 @@ var activity_interceptor_1 = require("./services/interceptor/activity-intercepto
 Object.defineProperty(exports, "createLTActivityInterceptor", { enumerable: true, get: function () { return activity_interceptor_1.createLTActivityInterceptor; } });
 var orchestrator_1 = require("./services/orchestrator");
 Object.defineProperty(exports, "executeLT", { enumerable: true, get: function () { return orchestrator_1.executeLT; } });
+var condition_1 = require("./services/orchestrator/condition");
+Object.defineProperty(exports, "conditionLT", { enumerable: true, get: function () { return condition_1.conditionLT; } });
 var auth_1 = require("./modules/auth");
 Object.defineProperty(exports, "JwtAuthAdapter", { enumerable: true, get: function () { return auth_1.JwtAuthAdapter; } });
 Object.defineProperty(exports, "createAuthMiddleware", { enumerable: true, get: function () { return auth_1.createAuthMiddleware; } });

package/build/lib/db/schemas/002_seed.sql

@@ -55,7 +55,14 @@ VALUES
    'Kitchen sink — demonstrates sleep, signals, parallel activities, escalation, and every durable primitive',
    '{}',
    '{"data": {"name": "World", "mode": "full"}, "metadata": {"source": "dashboard"}}'::jsonb,
-   NULL)
+   NULL),
+
+  -- Basic signal (configured, NOT certified — no escalation roles)
+  ('basicSignal', 'long-tail-examples', 'reviewer', true,
+   'Signal-based escalation — workflow stays running while waiting for human input via conditionLT',
+   '{}',
+   '{"data": {"message": "Deployment approval needed for v2.1.0", "role": "reviewer"}, "metadata": {"certified": false, "source": "dashboard"}}'::jsonb,
+   '{"properties": {"approved": {"type": "boolean", "default": false, "description": "Approve this deployment?"}, "notes": {"type": "string", "default": "", "description": "Reviewer notes — visible to the workflow author"}}}'::jsonb)
 ON CONFLICT (workflow_type) DO NOTHING;
 
 -- ─── Assign roles to all workflows ──────────────────────────────────────────
@@ -63,5 +70,6 @@ ON CONFLICT (workflow_type) DO NOTHING;
 INSERT INTO lt_config_roles (workflow_type, role)
 SELECT workflow_type, unnest(ARRAY['reviewer', 'engineer', 'admin'])
 FROM lt_config_workflows
+WHERE workflow_type != 'basicSignal'
 ON CONFLICT (workflow_type, role) DO NOTHING;
 

package/build/modules/ltconfig.d.ts

@@ -14,7 +14,14 @@ declare class LTConfigCache {
     getProviderData(name: string, originId: string): Promise<LTProviderData>;
     /** Force cache reload on next access. Call after config mutations. */
     invalidate(): void;
-    /** Get the full resolved config for a workflow (used by interceptor activities). */
+    /**
+     * Get the resolved config for a workflow, but only if certified.
+     *
+     * The interceptor uses this to decide whether to wrap the workflow
+     * with task tracking, escalation handling, and re-run detection.
+     * Configured-but-not-certified workflows (no roles, no consumes)
+     * return null so the interceptor skips them.
+     */
     getResolvedConfig(name: string): Promise<LTResolvedConfig | null>;
 }
 export declare const ltConfig: LTConfigCache;

package/build/modules/ltconfig.js

@@ -101,10 +101,20 @@ class LTConfigCache {
         this.loadedAt = 0;
         this.loadPromise = null;
     }
-    /** Get the full resolved config for a workflow (used by interceptor activities). */
+    /**
+     * Get the resolved config for a workflow, but only if certified.
+     *
+     * The interceptor uses this to decide whether to wrap the workflow
+     * with task tracking, escalation handling, and re-run detection.
+     * Configured-but-not-certified workflows (no roles, no consumes)
+     * return null so the interceptor skips them.
+     */
     async getResolvedConfig(name) {
         const config = await this.get(name);
-        return config ?? null;
+        if (!config)
+            return null;
+        const isCertified = (config.roles?.length ?? 0) > 0 || (config.consumes?.length ?? 0) > 0;
+        return isCertified ? config : null;
     }
 }
 exports.ltConfig = new LTConfigCache();

package/build/routes/escalations/list.js

@@ -36,6 +36,28 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerListRoutes = registerListRoutes;
 const api = __importStar(require("../../api/escalations"));
 function registerListRoutes(router) {
+    /**
+     * POST /api/escalations
+     * Create a standalone escalation (not tied to a workflow).
+     *
+     * RBAC: caller must hold the target role or be superadmin.
+     *
+     * Body: { type, role, subtype?, description?, priority?, envelope?,
+     *         metadata?, escalation_payload? }
+     */
+    router.post('/', async (req, res) => {
+        const result = await api.createEscalation({
+            type: req.body?.type,
+            subtype: req.body?.subtype,
+            role: req.body?.role,
+            description: req.body?.description,
+            priority: req.body?.priority,
+            envelope: req.body?.envelope,
+            metadata: req.body?.metadata,
+            escalation_payload: req.body?.escalation_payload,
+        }, req.auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
     /**
      * GET /api/escalations
      * List escalations with optional filters.

package/build/routes/tasks.js

@@ -36,6 +36,29 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const express_1 = require("express");
 const api = __importStar(require("../api/tasks"));
 const router = (0, express_1.Router)();
+/**
+ * POST /api/tasks
+ * Create a new task record.
+ * Body: { workflow_id, workflow_type, lt_type, signal_id, parent_workflow_id, envelope, ... }
+ */
+router.post('/', async (req, res) => {
+    const result = await api.createTask({
+        workflow_id: req.body?.workflow_id,
+        workflow_type: req.body?.workflow_type,
+        lt_type: req.body?.lt_type,
+        task_queue: req.body?.task_queue,
+        signal_id: req.body?.signal_id,
+        parent_workflow_id: req.body?.parent_workflow_id,
+        origin_id: req.body?.origin_id,
+        parent_id: req.body?.parent_id,
+        envelope: req.body?.envelope,
+        metadata: req.body?.metadata,
+        priority: req.body?.priority,
+        trace_id: req.body?.trace_id,
+        span_id: req.body?.span_id,
+    }, { userId: req.auth?.userId ?? '', role: req.auth?.role, scopes: req.auth?.scopes });
+    res.status(result.status).json(result.data ?? { error: result.error });
+});
 /**
  * GET /api/tasks
  * List tasks with optional filters.

package/build/routes/workflows/invocation.js

@@ -39,22 +39,28 @@ const router = (0, express_1.Router)();
 // ── Workflow invocation ─────────────────────────────────────────────────────
 /**
  * POST /api/workflows/:type/invoke
- * Start a workflow by its registered type.
+ * Proxy for `Durable.Client.workflow.start()` with IAM resolution.
  *
- * The workflow must have `invocable: true` in its config. If the config
- * includes `invocation_roles`, the authenticated user must hold at least
- * one of those roles. When invocation_roles is empty, any authenticated
- * user can invoke.
+ * The workflow must have `invocable: true` in its config (or an active
+ * worker). If the config includes `invocation_roles`, the authenticated
+ * user must hold at least one of those roles.
  *
- * Body: { data: Record<string, any>, metadata?: Record<string, any> }
+ * Body fields `data`, `metadata`, and `execute_as` are extracted for
+ * envelope/IAM handling. Everything else in `options` passes through
+ * to the Durable client unchanged (workflowId, expire, entity,
+ * namespace, search, signalIn, pending, etc.).
+ *
+ * @see https://docs.hotmesh.io/types/types_durable.WorkflowOptions.html
  */
 router.post('/:type/invoke', async (req, res) => {
+    const { data, metadata, execute_as, ...options } = req.body ?? {};
     const result = await api.invokeWorkflow({
         type: req.params.type,
-        data: req.body?.data,
-        metadata: req.body?.metadata,
-        execute_as: req.body?.execute_as,
-    }, { userId: req.auth?.userId ?? '' });
+        data,
+        metadata,
+        execute_as,
+        options: Object.keys(options).length > 0 ? options : undefined,
+    }, { userId: req.auth?.userId ?? '', role: req.auth?.role, scopes: req.auth?.scopes });
     res.status(result.status).json(result.data ?? { error: result.error });
 });
 // ── Workflow observation ────────────────────────────────────────────────────

package/build/sdk/index.d.ts

@@ -47,6 +47,21 @@ export interface LTClientOptions {
  */
 export declare function createClient(options?: LTClientOptions): {
     tasks: {
+        create: (input: {
+            workflow_id: string;
+            workflow_type: string;
+            lt_type: string;
+            task_queue?: string;
+            signal_id: string;
+            parent_workflow_id: string;
+            origin_id?: string;
+            parent_id?: string;
+            envelope?: string;
+            metadata?: Record<string, any>;
+            priority?: number;
+            trace_id?: string;
+            span_id?: string;
+        }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         list: typeof tasksApi.listTasks;
         get: typeof tasksApi.getTask;
         listProcesses: typeof tasksApi.listProcesses;
@@ -54,6 +69,16 @@ export declare function createClient(options?: LTClientOptions): {
         getProcessStats: typeof tasksApi.getProcessStats;
     };
     escalations: {
+        create: (input: {
+            type: string;
+            subtype?: string;
+            role: string;
+            description?: string;
+            priority?: number;
+            envelope?: string;
+            metadata?: Record<string, any>;
+            escalation_payload?: string;
+        }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         list: (input: {
             status?: string;
             role?: string;
@@ -128,6 +153,7 @@ export declare function createClient(options?: LTClientOptions): {
             data?: Record<string, any>;
             metadata?: Record<string, any>;
             execute_as?: string;
+            options?: Record<string, any>;
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         getStatus: typeof workflowsApi.getWorkflowStatus;
         getResult: typeof workflowsApi.getWorkflowResult;

package/build/sdk/index.js

@@ -100,6 +100,7 @@ function createClient(options = {}) {
     return {
         // ── Tasks ──────────────────────────────────────────────────────────────
         tasks: {
+            create: bindAuth(tasksApi.createTask, auth),
             list: tasksApi.listTasks,
             get: tasksApi.getTask,
             listProcesses: tasksApi.listProcesses,
@@ -108,6 +109,7 @@ function createClient(options = {}) {
         },
         // ── Escalations ────────────────────────────────────────────────────────
         escalations: {
+            create: bindAuth(escalationsApi.createEscalation, auth),
             list: bindAuth(escalationsApi.listEscalations, auth),
             listAvailable: bindAuth(escalationsApi.listAvailableEscalations, auth),
             listTypes: escalationsApi.listDistinctTypes,