@hotmeshio/long-tail 0.1.0

package/build/services/escalation-strategy/index.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escalationStrategyRegistry = void 0;
+/**
+ * Singleton registry for the escalation strategy.
+ *
+ * Follows the same pattern as mcpRegistry (single adapter):
+ * - register(strategy) — set the active strategy
+ * - clear()            — reset (for tests)
+ *
+ * The strategy is consulted during escalation resolution to determine
+ * whether to perform a standard re-run or route to the MCP triage
+ * orchestrator for dynamic remediation.
+ */
+class LTEscalationStrategyRegistry {
+    constructor() {
+        this.strategy = null;
+    }
+    register(strategy) {
+        this.strategy = strategy;
+    }
+    clear() {
+        this.strategy = null;
+    }
+    get hasStrategy() {
+        return this.strategy !== null;
+    }
+    get current() {
+        return this.strategy;
+    }
+}
+exports.escalationStrategyRegistry = new LTEscalationStrategyRegistry();

package/build/services/escalation-strategy/mcp.d.ts

@@ -0,0 +1,13 @@
+import type { LTEscalationStrategy, ResolutionContext, ResolutionDirective } from '../../types/escalation-strategy';
+/**
+ * MCP escalation strategy.
+ *
+ * Checks for `resolverPayload._lt.needsTriage`. When set, builds a
+ * triage envelope and returns `{ action: 'triage' }` so the resolution
+ * route starts the mcpTriage workflow instead of a standard re-run.
+ *
+ * When `needsTriage` is not set, falls through to standard `{ action: 'rerun' }`.
+ */
+export declare class McpEscalationStrategy implements LTEscalationStrategy {
+    onResolution(context: ResolutionContext): Promise<ResolutionDirective>;
+}

package/build/services/escalation-strategy/mcp.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpEscalationStrategy = void 0;
+/**
+ * MCP escalation strategy.
+ *
+ * Checks for `resolverPayload._lt.needsTriage`. When set, builds a
+ * triage envelope and returns `{ action: 'triage' }` so the resolution
+ * route starts the mcpTriage workflow instead of a standard re-run.
+ *
+ * When `needsTriage` is not set, falls through to standard `{ action: 'rerun' }`.
+ */
+class McpEscalationStrategy {
+    async onResolution(context) {
+        const { escalation, resolverPayload, envelope } = context;
+        if (!resolverPayload?._lt?.needsTriage) {
+            return { action: 'rerun' };
+        }
+        // Parse escalation payload safely
+        let escalationPayload = {};
+        if (escalation.escalation_payload) {
+            try {
+                escalationPayload = JSON.parse(escalation.escalation_payload);
+            }
+            catch { /* use empty */ }
+        }
+        // Strip routing fields from the original envelope's `lt` — triage
+        // runs on a separate axis and must NOT signal the original parent.
+        // Keep only originId and parentId which the triage workflow uses.
+        const originalLt = envelope.lt || {};
+        const triageEnvelope = {
+            data: {
+                escalationId: escalation.id,
+                originId: escalation.origin_id,
+                originalWorkflowType: escalation.workflow_type,
+                originalTaskQueue: escalation.task_queue,
+                originalTaskId: escalation.task_id,
+                escalationPayload,
+                resolverPayload,
+            },
+            metadata: envelope.metadata || {},
+            lt: {
+                originId: originalLt.originId,
+                parentId: originalLt.parentId,
+                userId: originalLt.userId,
+            },
+        };
+        return { action: 'triage', triageEnvelope };
+    }
+}
+exports.McpEscalationStrategy = McpEscalationStrategy;

package/build/services/events/index.d.ts

@@ -0,0 +1,37 @@
+import type { LTEvent, LTEventAdapter } from '../../types';
+declare class LTEventRegistry {
+    private adapters;
+    private connected;
+    /**
+     * Register an event adapter. Call before connect().
+     */
+    register(adapter: LTEventAdapter): void;
+    /**
+     * Connect all registered adapters. Call during startup.
+     */
+    connect(): Promise<void>;
+    /**
+     * Publish an event to all registered adapters.
+     * Best-effort: individual adapter failures are logged, not thrown.
+     */
+    publish(event: LTEvent): Promise<void>;
+    /**
+     * Disconnect all registered adapters. Call during shutdown.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Remove all adapters and reset state. Used in tests.
+     */
+    clear(): void;
+    /**
+     * Check if any adapters are registered.
+     */
+    get hasAdapters(): boolean;
+    /**
+     * Return the first registered adapter that matches the given type.
+     */
+    getAdapter<T extends LTEventAdapter>(ctor: new (...args: any[]) => T): T | undefined;
+}
+/** Singleton event registry */
+export declare const eventRegistry: LTEventRegistry;
+export {};

package/build/services/events/index.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.eventRegistry = void 0;
+const logger_1 = require("../logger");
+class LTEventRegistry {
+    constructor() {
+        this.adapters = [];
+        this.connected = false;
+    }
+    /**
+     * Register an event adapter. Call before connect().
+     */
+    register(adapter) {
+        this.adapters.push(adapter);
+    }
+    /**
+     * Connect all registered adapters. Call during startup.
+     */
+    async connect() {
+        if (this.connected)
+            return;
+        await Promise.allSettled(this.adapters.map((a) => a.connect()));
+        this.connected = true;
+    }
+    /**
+     * Publish an event to all registered adapters.
+     * Best-effort: individual adapter failures are logged, not thrown.
+     */
+    async publish(event) {
+        if (!this.adapters.length)
+            return;
+        await Promise.allSettled(this.adapters.map((a) => a.publish(event).catch((err) => {
+            logger_1.loggerRegistry.error(`[lt-events] adapter publish failed: ${err?.message}`);
+        })));
+    }
+    /**
+     * Disconnect all registered adapters. Call during shutdown.
+     */
+    async disconnect() {
+        await Promise.allSettled(this.adapters.map((a) => a.disconnect()));
+        this.connected = false;
+    }
+    /**
+     * Remove all adapters and reset state. Used in tests.
+     */
+    clear() {
+        this.adapters = [];
+        this.connected = false;
+    }
+    /**
+     * Check if any adapters are registered.
+     */
+    get hasAdapters() {
+        return this.adapters.length > 0;
+    }
+    /**
+     * Return the first registered adapter that matches the given type.
+     */
+    getAdapter(ctor) {
+        return this.adapters.find((a) => a instanceof ctor);
+    }
+}
+/** Singleton event registry */
+exports.eventRegistry = new LTEventRegistry();

package/build/services/events/memory.d.ts

@@ -0,0 +1,27 @@
+import type { LTEvent, LTEventAdapter } from '../../types';
+/**
+ * In-memory event adapter for testing.
+ *
+ * Captures all published events in an array that tests can inspect.
+ *
+ * Usage:
+ * ```typescript
+ * const adapter = new InMemoryEventAdapter();
+ * eventRegistry.register(adapter);
+ * await eventRegistry.connect();
+ *
+ * // ... run workflow ...
+ *
+ * expect(adapter.events).toContainEqual(
+ *   expect.objectContaining({ type: 'milestone', workflowName: 'reviewContent' })
+ * );
+ * ```
+ */
+export declare class InMemoryEventAdapter implements LTEventAdapter {
+    events: LTEvent[];
+    connect(): Promise<void>;
+    publish(event: LTEvent): Promise<void>;
+    disconnect(): Promise<void>;
+    /** Clear captured events */
+    clear(): void;
+}

package/build/services/events/memory.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryEventAdapter = void 0;
+/**
+ * In-memory event adapter for testing.
+ *
+ * Captures all published events in an array that tests can inspect.
+ *
+ * Usage:
+ * ```typescript
+ * const adapter = new InMemoryEventAdapter();
+ * eventRegistry.register(adapter);
+ * await eventRegistry.connect();
+ *
+ * // ... run workflow ...
+ *
+ * expect(adapter.events).toContainEqual(
+ *   expect.objectContaining({ type: 'milestone', workflowName: 'reviewContent' })
+ * );
+ * ```
+ */
+class InMemoryEventAdapter {
+    constructor() {
+        this.events = [];
+    }
+    async connect() {
+        // no-op
+    }
+    async publish(event) {
+        this.events.push(event);
+    }
+    async disconnect() {
+        // no-op
+    }
+    /** Clear captured events */
+    clear() {
+        this.events = [];
+    }
+}
+exports.InMemoryEventAdapter = InMemoryEventAdapter;

package/build/services/events/nats.d.ts

@@ -0,0 +1,29 @@
+import type { LTEvent, LTEventAdapter } from '../../types';
+/**
+ * NATS event adapter — reference implementation.
+ *
+ * Publishes LTEvent payloads as JSON to NATS subjects
+ * following the pattern: `{subjectPrefix}.{event.type}`
+ *
+ * Usage:
+ * ```typescript
+ * import { eventRegistry, NatsEventAdapter } from '@hotmeshio/long-tail';
+ *
+ * eventRegistry.register(new NatsEventAdapter());
+ * await eventRegistry.connect();
+ * ```
+ */
+export declare class NatsEventAdapter implements LTEventAdapter {
+    private nc;
+    private url;
+    private subjectPrefix;
+    private token?;
+    constructor(options?: {
+        url?: string;
+        subjectPrefix?: string;
+        token?: string;
+    });
+    connect(): Promise<void>;
+    publish(event: LTEvent): Promise<void>;
+    disconnect(): Promise<void>;
+}

package/build/services/events/nats.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NatsEventAdapter = void 0;
+const nats_1 = require("nats");
+const config_1 = require("../../modules/config");
+const logger_1 = require("../logger");
+const sc = (0, nats_1.StringCodec)();
+/**
+ * NATS event adapter — reference implementation.
+ *
+ * Publishes LTEvent payloads as JSON to NATS subjects
+ * following the pattern: `{subjectPrefix}.{event.type}`
+ *
+ * Usage:
+ * ```typescript
+ * import { eventRegistry, NatsEventAdapter } from '@hotmeshio/long-tail';
+ *
+ * eventRegistry.register(new NatsEventAdapter());
+ * await eventRegistry.connect();
+ * ```
+ */
+class NatsEventAdapter {
+    constructor(options) {
+        this.nc = null;
+        this.url = options?.url || config_1.config.NATS_URL;
+        this.subjectPrefix = options?.subjectPrefix || 'lt.events';
+        this.token = options?.token || process.env.NATS_TOKEN || 'dev_api_secret';
+    }
+    async connect() {
+        this.nc = await (0, nats_1.connect)({
+            servers: this.url,
+            token: this.token,
+        });
+        logger_1.loggerRegistry.info(`[lt-events:nats] connected to ${this.url}`);
+    }
+    async publish(event) {
+        if (!this.nc)
+            return;
+        const subject = `${this.subjectPrefix}.${event.type}`;
+        this.nc.publish(subject, sc.encode(JSON.stringify(event)));
+    }
+    async disconnect() {
+        if (this.nc) {
+            await this.nc.drain();
+            this.nc = null;
+            logger_1.loggerRegistry.info('[lt-events:nats] disconnected');
+        }
+    }
+}
+exports.NatsEventAdapter = NatsEventAdapter;

package/build/services/events/publish.d.ts

@@ -0,0 +1,72 @@
+import type { LTMilestone } from '../../types';
+/**
+ * Publish a milestone event. Called from handleCompletion (workflow
+ * interceptor), ltCompleteTask (orchestrator activity), and the
+ * activity interceptor's after phase.
+ */
+export declare function publishMilestoneEvent(params: {
+    source: 'interceptor' | 'orchestrator' | 'activity';
+    workflowId: string;
+    workflowName: string;
+    taskQueue: string;
+    taskId?: string;
+    activityName?: string;
+    milestones: LTMilestone[];
+    data?: Record<string, any>;
+}): Promise<void>;
+/**
+ * Publish a task lifecycle event (created, started, completed, escalated, failed).
+ */
+export declare function publishTaskEvent(params: {
+    type: 'task.created' | 'task.started' | 'task.completed' | 'task.escalated' | 'task.failed';
+    source: string;
+    workflowId: string;
+    workflowName: string;
+    taskQueue: string;
+    taskId: string;
+    originId?: string;
+    status: string;
+    milestones?: LTMilestone[];
+    data?: Record<string, any>;
+}): Promise<void>;
+/**
+ * Publish an escalation lifecycle event (created, resolved).
+ */
+export declare function publishEscalationEvent(params: {
+    type: 'escalation.created' | 'escalation.resolved' | 'escalation.claimed' | 'escalation.released';
+    source: string;
+    workflowId: string;
+    workflowName: string;
+    taskQueue: string;
+    taskId?: string;
+    escalationId: string;
+    originId?: string;
+    status: string;
+    data?: Record<string, any>;
+}): Promise<void>;
+/**
+ * Publish an activity lifecycle event for YAML workflow steps.
+ * Lightweight — no payload data, just progress signals.
+ */
+export declare function publishActivityEvent(params: {
+    type: 'activity.started' | 'activity.completed' | 'activity.failed';
+    workflowId: string;
+    workflowName: string;
+    taskQueue: string;
+    activityName: string;
+    data?: Record<string, any>;
+}): Promise<void>;
+/**
+ * Publish a workflow lifecycle event (started, completed, failed).
+ */
+export declare function publishWorkflowEvent(params: {
+    type: 'workflow.started' | 'workflow.completed' | 'workflow.failed';
+    source: string;
+    workflowId: string;
+    workflowName: string;
+    taskQueue: string;
+    taskId?: string;
+    originId?: string;
+    status: string;
+    data?: Record<string, any>;
+}): Promise<void>;

package/build/services/events/publish.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.publishMilestoneEvent = publishMilestoneEvent;
+exports.publishTaskEvent = publishTaskEvent;
+exports.publishEscalationEvent = publishEscalationEvent;
+exports.publishActivityEvent = publishActivityEvent;
+exports.publishWorkflowEvent = publishWorkflowEvent;
+const index_1 = require("./index");
+/**
+ * Fire-and-forget publish helper. Swallows errors (best-effort).
+ */
+function fireAndForget(event) {
+    if (!index_1.eventRegistry.hasAdapters)
+        return Promise.resolve();
+    return index_1.eventRegistry.publish(event).catch(() => { });
+}
+/**
+ * Publish a milestone event. Called from handleCompletion (workflow
+ * interceptor), ltCompleteTask (orchestrator activity), and the
+ * activity interceptor's after phase.
+ */
+function publishMilestoneEvent(params) {
+    if (!params.milestones?.length)
+        return Promise.resolve();
+    return fireAndForget({
+        type: 'milestone',
+        source: params.source,
+        workflowId: params.workflowId,
+        workflowName: params.workflowName,
+        taskQueue: params.taskQueue,
+        taskId: params.taskId,
+        activityName: params.activityName,
+        milestones: params.milestones,
+        data: params.data,
+        timestamp: new Date().toISOString(),
+    });
+}
+/**
+ * Publish a task lifecycle event (created, started, completed, escalated, failed).
+ */
+function publishTaskEvent(params) {
+    return fireAndForget({
+        type: params.type,
+        source: params.source,
+        workflowId: params.workflowId,
+        workflowName: params.workflowName,
+        taskQueue: params.taskQueue,
+        taskId: params.taskId,
+        originId: params.originId,
+        status: params.status,
+        milestones: params.milestones,
+        data: params.data,
+        timestamp: new Date().toISOString(),
+    });
+}
+/**
+ * Publish an escalation lifecycle event (created, resolved).
+ */
+function publishEscalationEvent(params) {
+    return fireAndForget({
+        type: params.type,
+        source: params.source,
+        workflowId: params.workflowId,
+        workflowName: params.workflowName,
+        taskQueue: params.taskQueue,
+        taskId: params.taskId,
+        escalationId: params.escalationId,
+        originId: params.originId,
+        status: params.status,
+        data: params.data,
+        timestamp: new Date().toISOString(),
+    });
+}
+/**
+ * Publish an activity lifecycle event for YAML workflow steps.
+ * Lightweight — no payload data, just progress signals.
+ */
+function publishActivityEvent(params) {
+    return fireAndForget({
+        type: params.type,
+        source: 'yaml-worker',
+        workflowId: params.workflowId,
+        workflowName: params.workflowName,
+        taskQueue: params.taskQueue,
+        activityName: params.activityName,
+        data: params.data,
+        timestamp: new Date().toISOString(),
+    });
+}
+/**
+ * Publish a workflow lifecycle event (started, completed, failed).
+ */
+function publishWorkflowEvent(params) {
+    return fireAndForget({
+        type: params.type,
+        source: params.source,
+        workflowId: params.workflowId,
+        workflowName: params.workflowName,
+        taskQueue: params.taskQueue,
+        taskId: params.taskId,
+        originId: params.originId,
+        status: params.status,
+        data: params.data,
+        timestamp: new Date().toISOString(),
+    });
+}

package/build/services/events/socketio.d.ts

@@ -0,0 +1,33 @@
+import type { Server as HttpServer } from 'http';
+import type { LTEvent, LTEventAdapter } from '../../types';
+/**
+ * Socket.IO event adapter for browser clients.
+ *
+ * Publishes LTEvent payloads to all connected Socket.IO clients
+ * on channels following the pattern: `lt.events.{event.type}`
+ *
+ * The HTTP server must be attached via `attachServer()` before
+ * `connect()` is called. The startup flow handles this automatically
+ * when Socket.IO is the active event transport.
+ *
+ * Usage:
+ * ```typescript
+ * import { eventRegistry } from '@hotmeshio/long-tail';
+ * import { SocketIOEventAdapter } from '@hotmeshio/long-tail';
+ *
+ * const adapter = new SocketIOEventAdapter();
+ * eventRegistry.register(adapter);
+ * // After HTTP server is created:
+ * adapter.attachServer(httpServer);
+ * await eventRegistry.connect();
+ * ```
+ */
+export declare class SocketIOEventAdapter implements LTEventAdapter {
+    private io;
+    private httpServer;
+    /** Attach to an HTTP server. Must be called before connect(). */
+    attachServer(server: HttpServer): void;
+    connect(): Promise<void>;
+    publish(event: LTEvent): Promise<void>;
+    disconnect(): Promise<void>;
+}

package/build/services/events/socketio.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SocketIOEventAdapter = void 0;
+const socket_io_1 = require("socket.io");
+const logger_1 = require("../logger");
+/**
+ * Socket.IO event adapter for browser clients.
+ *
+ * Publishes LTEvent payloads to all connected Socket.IO clients
+ * on channels following the pattern: `lt.events.{event.type}`
+ *
+ * The HTTP server must be attached via `attachServer()` before
+ * `connect()` is called. The startup flow handles this automatically
+ * when Socket.IO is the active event transport.
+ *
+ * Usage:
+ * ```typescript
+ * import { eventRegistry } from '@hotmeshio/long-tail';
+ * import { SocketIOEventAdapter } from '@hotmeshio/long-tail';
+ *
+ * const adapter = new SocketIOEventAdapter();
+ * eventRegistry.register(adapter);
+ * // After HTTP server is created:
+ * adapter.attachServer(httpServer);
+ * await eventRegistry.connect();
+ * ```
+ */
+class SocketIOEventAdapter {
+    constructor() {
+        this.io = null;
+        this.httpServer = null;
+    }
+    /** Attach to an HTTP server. Must be called before connect(). */
+    attachServer(server) {
+        this.httpServer = server;
+    }
+    async connect() {
+        if (!this.httpServer) {
+            logger_1.loggerRegistry.warn('[lt-events:socketio] no HTTP server attached — skipping');
+            return;
+        }
+        this.io = new socket_io_1.Server(this.httpServer, {
+            cors: { origin: '*', methods: ['GET', 'POST'] },
+            path: '/socket.io',
+            transports: ['polling', 'websocket'],
+            allowEIO3: true,
+        });
+        this.io.on('connection', (socket) => {
+            logger_1.loggerRegistry.info(`[lt-events:socketio] client connected (${socket.id})`);
+            socket.on('disconnect', () => {
+                logger_1.loggerRegistry.debug(`[lt-events:socketio] client disconnected (${socket.id})`);
+            });
+        });
+        logger_1.loggerRegistry.info('[lt-events:socketio] attached to HTTP server');
+    }
+    async publish(event) {
+        if (!this.io)
+            return;
+        const channel = `lt.events.${event.type}`;
+        this.io.emit(channel, event);
+    }
+    async disconnect() {
+        if (this.io) {
+            this.io.close();
+            this.io = null;
+            logger_1.loggerRegistry.info('[lt-events:socketio] disconnected');
+        }
+    }
+}
+exports.SocketIOEventAdapter = SocketIOEventAdapter;

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

@@ -0,0 +1,2 @@
+export declare function createClient(): import("@hotmeshio/hotmesh").Client;
+export declare function getHandle(taskQueue: string, workflowName: string, workflowId: string): Promise<import("@hotmeshio/hotmesh").WorkflowHandle>;

package/build/services/export/client.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createClient = createClient;
+exports.getHandle = getHandle;
+const hotmesh_1 = require("@hotmeshio/hotmesh");
+const pg_1 = require("pg");
+const config_1 = require("../../modules/config");
+function createClient() {
+    return new hotmesh_1.Durable.Client({
+        connection: { class: pg_1.Client, options: config_1.postgres_options },
+    });
+}
+async function getHandle(taskQueue, workflowName, workflowId) {
+    const client = createClient();
+    return client.workflow.getHandle(taskQueue, workflowName, workflowId);
+}