@hotmeshio/long-tail 0.5.1 → 0.5.3

package/build/adapters/express.d.ts

@@ -59,6 +59,7 @@ export declare class LTExpressAdapter {
     /**
      * Return a self-contained Express Router that serves:
      * - `/api/*` — Long Tail API routes (auth, tasks, escalations, etc.)
+     * - `/mcp` — MCP streamable-HTTP transport (Claude Desktop, Cursor, agents)
      * - `/health` — health check
      * - Static dashboard assets
      * - SPA fallback with injected `<base href>` and `window.__LT_BASE__`

package/build/adapters/express.js

@@ -41,6 +41,7 @@ const fs_1 = require("fs");
 const path_1 = __importDefault(require("path"));
 const express_1 = __importStar(require("express"));
 const routes_1 = __importDefault(require("../routes"));
+const mcp_endpoint_1 = __importDefault(require("../routes/mcp-endpoint"));
 const events_1 = require("../lib/events");
 const socketio_1 = require("../lib/events/socketio");
 const nats_1 = require("../lib/events/nats");
@@ -134,6 +135,7 @@ class LTExpressAdapter {
     /**
      * Return a self-contained Express Router that serves:
      * - `/api/*` — Long Tail API routes (auth, tasks, escalations, etc.)
+     * - `/mcp` — MCP streamable-HTTP transport (Claude Desktop, Cursor, agents)
      * - `/health` — health check
      * - Static dashboard assets
      * - SPA fallback with injected `<base href>` and `window.__LT_BASE__`
@@ -147,6 +149,8 @@ class LTExpressAdapter {
         });
         // API routes — internal routes handle their own JWT auth
         router.use('/api', routes_1.default);
+        // MCP streamable-HTTP transport — same endpoint as standalone server
+        router.use('/mcp', mcp_endpoint_1.default);
         // Dashboard static assets
         const dashboardDist = this.resolveDashboardDist();
         if (dashboardDist) {

package/build/lib/events/system-events.d.ts

@@ -0,0 +1,19 @@
+import type { Types } from '@hotmeshio/hotmesh';
+import type { LTEvent } from '../../types';
+type SystemEvent = Types.SystemEvent;
+/**
+ * Translate a HotMesh `SystemEvent` into long-tail's `LTEvent`. Escalation
+ * events carry the full committed row in `data`, from which we lift the routing
+ * fields; engine/worker lifecycle events pass through with their canonical type.
+ */
+export declare function mapSystemEvent(event: SystemEvent): LTEvent;
+/**
+ * The `EventsConfig.publish` hook long-tail wires into every worker/engine it
+ * constructs. Fire-and-forget — never throws back into the SDK's committed call.
+ */
+export declare function onSystemEvent(event: SystemEvent): void;
+/** The EventsConfig long-tail passes to Durable.Client / Worker.create / HotMesh.init. */
+export declare const systemEventsConfig: {
+    publish: typeof onSystemEvent;
+};
+export {};

package/build/lib/events/system-events.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.systemEventsConfig = void 0;
+exports.mapSystemEvent = mapSystemEvent;
+exports.onSystemEvent = onSystemEvent;
+const index_1 = require("./index");
+/** Verb → long-tail event status, matching the manual publishEscalationEvent convention. */
+const ESCALATION_STATUS_BY_VERB = {
+    created: 'pending',
+    claimed: 'claimed',
+    released: 'released',
+    reassigned: 'pending',
+    resolved: 'resolved',
+    cancelled: 'cancelled',
+};
+/**
+ * Translate a HotMesh `SystemEvent` into long-tail's `LTEvent`. Escalation
+ * events carry the full committed row in `data`, from which we lift the routing
+ * fields; engine/worker lifecycle events pass through with their canonical type.
+ */
+function mapSystemEvent(event) {
+    const segments = event.type.split('.');
+    const domain = segments[1];
+    if (domain === 'escalation') {
+        const row = (event.data ?? {});
+        const verb = segments[3] ?? '';
+        return {
+            type: event.type,
+            source: 'sdk',
+            workflowId: row.workflow_id || event.workflow_id || '',
+            workflowName: row.workflow_type || '',
+            taskQueue: row.task_queue || '',
+            escalationId: row.id || segments[2],
+            originId: row.origin_id || event.origin_id || undefined,
+            status: ESCALATION_STATUS_BY_VERB[verb] ?? verb,
+            data: row,
+            timestamp: event.ts,
+        };
+    }
+    // Engine / worker lifecycle (system.engine.*, system.worker.*) — additive
+    // observability; pass through with the canonical type and metadata payload.
+    return {
+        type: event.type,
+        source: 'sdk',
+        workflowId: event.workflow_id || '',
+        workflowName: '',
+        taskQueue: event.data?.taskQueue || '',
+        data: event.data,
+        timestamp: event.ts,
+    };
+}
+/**
+ * The `EventsConfig.publish` hook long-tail wires into every worker/engine it
+ * constructs. Fire-and-forget — never throws back into the SDK's committed call.
+ */
+function onSystemEvent(event) {
+    if (!index_1.eventRegistry.hasAdapters)
+        return;
+    void index_1.eventRegistry.publish(mapSystemEvent(event)).catch(() => { });
+}
+/** The EventsConfig long-tail passes to Durable.Client / Worker.create / HotMesh.init. */
+exports.systemEventsConfig = { publish: onSystemEvent };

package/build/modules/ltconfig.d.ts

@@ -23,6 +23,14 @@ declare class LTConfigCache {
      * return null so the interceptor skips them.
      */
     getResolvedConfig(name: string): Promise<LTResolvedConfig | null>;
+    /**
+     * Get the config for any workflow REGISTERED in lt_config_workflows (a row
+     * exists), regardless of certification (roles/consumes). The interceptor
+     * uses this to decide whether to apply task tracking, escalation handling,
+     * and orchestrator context — every registered workflow gets the full
+     * treatment; only unregistered ad-hoc durable workflows are skipped.
+     */
+    getRegisteredConfig(name: string): Promise<LTResolvedConfig | null>;
 }
 export declare const ltConfig: LTConfigCache;
 export {};

package/build/modules/ltconfig.js

@@ -116,5 +116,15 @@ class LTConfigCache {
         const isCertified = (config.roles?.length ?? 0) > 0 || (config.consumes?.length ?? 0) > 0;
         return isCertified ? config : null;
     }
+    /**
+     * Get the config for any workflow REGISTERED in lt_config_workflows (a row
+     * exists), regardless of certification (roles/consumes). The interceptor
+     * uses this to decide whether to apply task tracking, escalation handling,
+     * and orchestrator context — every registered workflow gets the full
+     * treatment; only unregistered ad-hoc durable workflows are skipped.
+     */
+    async getRegisteredConfig(name) {
+        return (await this.get(name)) ?? null;
+    }
 }
 exports.ltConfig = new LTConfigCache();

package/build/services/escalation/bulk.d.ts

@@ -22,6 +22,7 @@ export declare function bulkAssignEscalations(ids: string[], targetUserId: strin
 export declare function bulkEscalateToRole(ids: string[], targetRole: string): Promise<number>;
 /**
  * Bulk resolve escalations for AI triage.
- * Returns full records so the caller can start triage workflows.
+ * Returns full records so the caller can start triage workflows. No signal is
+ * delivered — the triage workflow takes over handling.
  */
 export declare function bulkResolveForTriage(ids: string[], hint?: string): Promise<LTEscalationRecord[]>;

package/build/services/escalation/bulk.js

@@ -4,8 +4,8 @@ exports.bulkClaimEscalations = bulkClaimEscalations;
 exports.bulkAssignEscalations = bulkAssignEscalations;
 exports.bulkEscalateToRole = bulkEscalateToRole;
 exports.bulkResolveForTriage = bulkResolveForTriage;
-const db_1 = require("../../lib/db");
-const sql_1 = require("./sql");
+const client_1 = require("./client");
+const map_1 = require("./map");
 /**
  * Bulk claim escalations for a user.
  * Items already claimed by another active user are skipped.
@@ -13,10 +13,8 @@ const sql_1 = require("./sql");
 async function bulkClaimEscalations(ids, userId, durationMinutes = 30) {
     if (ids.length === 0)
         return { claimed: 0, skipped: 0 };
-    const pool = (0, db_1.getPool)();
-    const { rowCount } = await pool.query(sql_1.BULK_CLAIM, [userId, durationMinutes, ids]);
-    const claimed = rowCount ?? 0;
-    return { claimed, skipped: ids.length - claimed };
+    const client = await (0, client_1.escalations)();
+    return client.claimMany({ ids, assignee: userId, durationMinutes });
 }
 /**
  * Bulk assign escalations to a specific user (admin action).
@@ -25,10 +23,13 @@ async function bulkClaimEscalations(ids, userId, durationMinutes = 30) {
 async function bulkAssignEscalations(ids, targetUserId, durationMinutes = 30) {
     if (ids.length === 0)
         return { assigned: 0, skipped: 0 };
-    const pool = (0, db_1.getPool)();
-    const { rowCount } = await pool.query(sql_1.BULK_ASSIGN, [targetUserId, durationMinutes, ids]);
-    const assigned = rowCount ?? 0;
-    return { assigned, skipped: ids.length - assigned };
+    const client = await (0, client_1.escalations)();
+    const { claimed, skipped } = await client.claimMany({
+        ids,
+        assignee: targetUserId,
+        durationMinutes,
+    });
+    return { assigned: claimed, skipped };
 }
 /**
  * Bulk reassign escalations to a different role.
@@ -37,21 +38,21 @@ async function bulkAssignEscalations(ids, targetUserId, durationMinutes = 30) {
 async function bulkEscalateToRole(ids, targetRole) {
     if (ids.length === 0)
         return 0;
-    const pool = (0, db_1.getPool)();
-    const { rowCount } = await pool.query(sql_1.BULK_ESCALATE_TO_ROLE, [targetRole, ids]);
-    return rowCount ?? 0;
+    const client = await (0, client_1.escalations)();
+    return client.escalateManyToRole({ ids, targetRole });
 }
 /**
  * Bulk resolve escalations for AI triage.
- * Returns full records so the caller can start triage workflows.
+ * Returns full records so the caller can start triage workflows. No signal is
+ * delivered — the triage workflow takes over handling.
  */
 async function bulkResolveForTriage(ids, hint) {
     if (ids.length === 0)
         return [];
-    const pool = (0, db_1.getPool)();
-    const resolverPayload = JSON.stringify({
-        _lt: { needsTriage: true, ...(hint ? { hint } : {}) },
+    const client = await (0, client_1.escalations)();
+    const resolved = await client.resolveMany({
+        ids,
+        resolverPayload: { _lt: { needsTriage: true, ...(hint ? { hint } : {}) } },
     });
-    const { rows } = await pool.query(sql_1.BULK_RESOLVE_FOR_TRIAGE, [resolverPayload, ids]);
-    return rows;
+    return (0, map_1.toEscalationRecords)(resolved);
 }

package/build/services/escalation/client.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The escalation client, with the `lt_escalations` compatibility view ensured
+ * exactly once per process. Every service function awaits this so the view is
+ * present before the first read/write in any context (app, route test, or the
+ * service-only test that runs `migrate()` without starting workers).
+ */
+export declare function escalations(): Promise<import("@hotmeshio/hotmesh/build/services/escalations").EscalationClientService>;
+/**
+ * Replace the legacy `lt_escalations` table with a view over
+ * `public.hmsh_escalations`. Idempotent and memoized per process.
+ *
+ * - Migrates any legacy rows into `hmsh_escalations` (no-op on a fresh DB), then
+ *   RENAMES the legacy table to `lt_escalations_legacy` (a recoverable backup —
+ *   never dropped here) so the view can take the `lt_escalations` name.
+ * - Read-path consumers (role, agent, mcp, overview) and frozen test cleanup
+ *   (`DELETE FROM lt_escalations`) continue to work unchanged against the view.
+ * - The one-time conversion is serialized across concurrent containers with a
+ *   dedicated Postgres advisory lock, so a multi-container deploy is safe.
+ *
+ * Safe to call eagerly at startup and lazily on first escalation use.
+ */
+export declare function ensureEscalationCompatView(): Promise<void>;

package/build/services/escalation/client.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escalations = escalations;
+exports.ensureEscalationCompatView = ensureEscalationCompatView;
+const hotmesh_1 = require("@hotmeshio/hotmesh");
+const db_1 = require("../../lib/db");
+const logger_1 = require("../../lib/logger");
+// ---------------------------------------------------------------------------
+// Escalation client — long-tail's service layer talks to the shared
+// `public.hmsh_escalations` table exclusively through `client.escalations.*`
+// (HotMesh 0.22.3). The escalation client is created off a `Durable.Client`,
+// which injects `getHotMeshClient` so the escalation engine pool is shared
+// with the rest of the app and torn down by `Durable.shutdown()`.
+// ---------------------------------------------------------------------------
+let durableClient = null;
+/** The raw `client.escalations` surface over `public.hmsh_escalations`. */
+function rawEscalations() {
+    if (!durableClient) {
+        durableClient = new hotmesh_1.Durable.Client({ connection: (0, db_1.getConnection)() });
+    }
+    return durableClient.escalations;
+}
+/**
+ * The escalation client, with the `lt_escalations` compatibility view ensured
+ * exactly once per process. Every service function awaits this so the view is
+ * present before the first read/write in any context (app, route test, or the
+ * service-only test that runs `migrate()` without starting workers).
+ */
+async function escalations() {
+    await ensureEscalationCompatView();
+    return rawEscalations();
+}
+let viewReady = null;
+/**
+ * Replace the legacy `lt_escalations` table with a view over
+ * `public.hmsh_escalations`. Idempotent and memoized per process.
+ *
+ * - Migrates any legacy rows into `hmsh_escalations` (no-op on a fresh DB), then
+ *   RENAMES the legacy table to `lt_escalations_legacy` (a recoverable backup —
+ *   never dropped here) so the view can take the `lt_escalations` name.
+ * - Read-path consumers (role, agent, mcp, overview) and frozen test cleanup
+ *   (`DELETE FROM lt_escalations`) continue to work unchanged against the view.
+ * - The one-time conversion is serialized across concurrent containers with a
+ *   dedicated Postgres advisory lock, so a multi-container deploy is safe.
+ *
+ * Safe to call eagerly at startup and lazily on first escalation use.
+ */
+function ensureEscalationCompatView() {
+    if (!viewReady)
+        viewReady = installEscalationCompatView();
+    return viewReady;
+}
+// Dedicated advisory-lock id for the compat-view conversion. Distinct from
+// migrate()'s lock (8675309) because this step runs after HotMesh engine init,
+// outside the migrate() sequence.
+const COMPAT_VIEW_LOCK_ID = 8675310;
+async function installEscalationCompatView() {
+    // Force HotMesh engine init so `public.hmsh_escalations` exists before the
+    // view binds to it (kvtables are deployed on first engine use).
+    await rawEscalations().get('00000000-0000-0000-0000-000000000000');
+    // Serialize the conversion across concurrent containers on a dedicated
+    // connection. Only one process performs the migrate+rename; the rest acquire
+    // the lock afterward, see the view already in place, and no-op (the DO block
+    // is guarded and CREATE OR REPLACE VIEW is idempotent).
+    const pool = (0, db_1.getPool)();
+    const client = await pool.connect();
+    try {
+        await client.query('SELECT pg_advisory_lock($1)', [COMPAT_VIEW_LOCK_ID]);
+        await client.query(MIGRATE_AND_RENAME_LEGACY_TABLE);
+        await client.query(CREATE_COMPAT_VIEW);
+        logger_1.loggerRegistry.info('[escalation] lt_escalations compatibility view ensured');
+    }
+    finally {
+        await client.query('SELECT pg_advisory_unlock($1)', [COMPAT_VIEW_LOCK_ID]).catch(() => { });
+        client.release();
+    }
+}
+// Migrate legacy `lt_escalations` rows into `hmsh_escalations` (idempotent),
+// then preserve the original table as `lt_escalations_legacy` rather than
+// dropping it — the rows survive untouched for verification and rollback; a
+// later explicit migration can drop the backup once the cut is confirmed. Runs
+// only while `lt_escalations` is still a real table; once it is a view this
+// block is skipped. Payload/envelope TEXT columns are cast to JSONB defensively
+// so a malformed value can never abort the upgrade.
+const MIGRATE_AND_RENAME_LEGACY_TABLE = `
+DO $$
+BEGIN
+  IF EXISTS (
+    SELECT 1 FROM pg_class c
+    JOIN pg_namespace n ON n.oid = c.relnamespace
+    WHERE c.relname = 'lt_escalations' AND c.relkind = 'r' AND n.nspname = 'public'
+  ) THEN
+    CREATE OR REPLACE FUNCTION pg_temp.lt_try_jsonb(t text) RETURNS jsonb AS $fn$
+      BEGIN
+        IF t IS NULL OR t = '' THEN RETURN NULL; END IF;
+        RETURN t::jsonb;
+      EXCEPTION WHEN others THEN
+        RETURN to_jsonb(t);
+      END;
+    $fn$ LANGUAGE plpgsql IMMUTABLE;
+
+    INSERT INTO public.hmsh_escalations
+      (id, namespace, app_id, type, subtype, description, status, priority,
+       task_id, origin_id, parent_id, workflow_id, task_queue, workflow_type,
+       role, assigned_to, assigned_until, claim_expires_at, resolved_at, claimed_at,
+       created_by, envelope, metadata, escalation_payload, resolver_payload,
+       trace_id, span_id, created_at, updated_at)
+    SELECT
+      id, 'hmsh', 'hmsh', type, subtype, description, status, priority,
+      task_id::text, origin_id, parent_id, workflow_id, task_queue, workflow_type,
+      role, assigned_to, assigned_until, assigned_until, resolved_at, claimed_at,
+      created_by::text,
+      pg_temp.lt_try_jsonb(envelope),
+      metadata,
+      pg_temp.lt_try_jsonb(escalation_payload),
+      pg_temp.lt_try_jsonb(resolver_payload),
+      trace_id, span_id, created_at, updated_at
+    FROM public.lt_escalations
+    ON CONFLICT (id) DO NOTHING;
+
+    -- Preserve the originals as a recoverable backup (rows already migrated).
+    -- If a backup already exists from a prior conversion, the current table is
+    -- redundant and is dropped instead of clobbering the backup.
+    IF EXISTS (
+      SELECT 1 FROM pg_class c
+      JOIN pg_namespace n ON n.oid = c.relnamespace
+      WHERE c.relname = 'lt_escalations_legacy' AND n.nspname = 'public'
+    ) THEN
+      DROP TABLE public.lt_escalations CASCADE;
+    ELSE
+      ALTER TABLE public.lt_escalations RENAME TO lt_escalations_legacy;
+    END IF;
+  END IF;
+END $$;`;
+// `available` mirrors the legacy isEffectivelyClaimed/isAvailable heuristic so
+// existing `SELECT *` consumers are unaffected; the column is additive.
+const CREATE_COMPAT_VIEW = `
+CREATE OR REPLACE VIEW public.lt_escalations AS
+  SELECT *,
+    (assigned_to IS NULL OR assigned_until IS NULL OR assigned_until <= NOW()) AS available
+  FROM public.hmsh_escalations;`;

package/build/services/escalation/crud.d.ts

@@ -2,20 +2,21 @@ import type { LTEscalationRecord } from '../../types';
 import type { CreateEscalationInput, ClaimResult } from './types';
 export declare function createEscalation(input: CreateEscalationInput): Promise<LTEscalationRecord>;
 /**
- * Atomic claim operation. Does NOT change status — "claimed" is implicit
- * via assigned_to + assigned_until > NOW().
- *
- * Conditions:
- * - status = 'pending' (not resolved/cancelled)
- * - Either: unassigned, expired claim, or same user (extension)
- *
- * Uses a CTE to capture the previous state so callers can detect extensions.
+ * Atomic claim. Implicit model — status stays 'pending'; "claimed" is
+ * assigned_to + assigned_until > NOW(). `isExtension` is true when the same
+ * user re-claims (extends expiry). Returns null when the row is not claimable.
  */
 export declare function claimEscalation(id: string, userId: string, durationMinutes?: number): Promise<ClaimResult | null>;
+/**
+ * Mark an escalation resolved. Signal delivery is owned by the resolution
+ * orchestrator (api/escalations/resolve.ts); service-created rows have no
+ * signal_key, so this never delivers a signal itself. Returns null when the
+ * row is missing or already terminal.
+ */
 export declare function resolveEscalation(id: string, resolverPayload: Record<string, any>): Promise<LTEscalationRecord | null>;
 /**
- * Bulk update priority for a set of escalations.
- * Only updates pending escalations.
+ * Bulk update priority for a set of escalations. Only pending escalations are
+ * updated.
  */
 export declare function updateEscalationsPriority(ids: string[], priority: 1 | 2 | 3 | 4): Promise<number>;
 /**
@@ -28,6 +29,12 @@ export declare function getEscalationRoles(ids: string[]): Promise<string[]>;
  * Only the assigned user (or superadmin via route) may release.
  */
 export declare function releaseEscalation(id: string, userId: string): Promise<LTEscalationRecord | null>;
+/**
+ * Sweep expired claims back to the available pool, returning the count cleared.
+ * Availability is already query-time in the implicit model, but long-tail's
+ * public contract clears `assigned_to` and returns a count, so this runs as a
+ * single direct UPDATE on the shared table (the SDK's releaseExpired is a no-op).
+ */
 export declare function releaseExpiredClaims(): Promise<number>;
 /**
  * Reassign an escalation to a different role.
@@ -50,13 +57,12 @@ export declare function findByMetadata(key: string, value: string, status?: stri
     total: number;
 }>;
 /**
- * Atomic claim by metadata with inline RBAC.
- * The SQL WHERE clause enforces role membership — if the caller
- * doesn't have an allowed role, zero rows match and the claim
- * never happens. No pre-flight find, no TOCTOU.
+ * Atomic claim by metadata with inline RBAC and optional metadata merge.
+ * The SDK enforces the role filter in SQL — callers without an allowed role
+ * match zero rows. Returns `{ escalation, isExtension, candidatesExist }` or
+ * null when nothing was claimed.
  *
- * @param allowedRoles — roles the caller can claim (null = no filter / global access)
- * @returns `{ escalation, isExtension, candidatesExist }` or null
+ * @param allowedRoles — roles the caller can claim (null = no filter / global)
  */
 export declare function claimByMetadata(key: string, value: string, userId: string, durationMinutes?: number, metadata?: Record<string, any>, allowedRoles?: string[] | null): Promise<(ClaimResult & {
     candidatesExist: number;
@@ -74,11 +80,13 @@ export interface ResolveByMetadataResult {
     taskQueue?: string;
 }
 /**
- * Atomic resolve by metadata with signal guard.
+ * Atomic resolve by metadata with signal guard, in a single CTE.
  *
- * Single query, two outcomes:
- * 1. No signal_id → claim + resolve atomically. Returns { outcome: 'resolved', escalation }.
- * 2. signal_id present → resolve skipped. Returns { outcome: 'signal_required', signalId, escalationId, ... }
- *    so the caller can signal the workflow. conditionLT handles the rest.
+ * Signal-backed rows (those carrying `metadata.signal_id`) are NOT resolved
+ * here — long-tail signals the paused workflow and the workflow interceptor
+ * resolves durably. If the workflow is gone the signal fails and the row stays
+ * pending, which is the contract the route suite pins. This guard is long-tail
+ * business logic over the shared table, so it runs as one atomic statement on
+ * `hmsh_escalations` rather than through the generic SDK resolve.
  */
 export declare function resolveByMetadataAtomic(key: string, value: string, userId: string, resolverPayload: Record<string, any>, metadata?: Record<string, any>, allowedRoles?: string[] | null): Promise<ResolveByMetadataResult>;