@hotmeshio/long-tail 0.1.0

package/build/types/discovery.js

@@ -0,0 +1,3 @@
+"use strict";
+/** Shared types for workflow discovery (used by both mcpQuery and mcpTriage pipelines). */
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/types/envelope.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Authenticated principal resolved at the front door (API route, cron, escalation).
+ * Travels with the envelope so workflows and activities never re-query the DB.
+ */
+export interface LTEnvelopePrincipal {
+    id: string;
+    type: 'user' | 'bot';
+    displayName?: string;
+    roles: string[];
+    roleType?: string;
+}
+/**
+ * The standard envelope passed to every Long Tail workflow.
+ *
+ * - `data`: Business inputs — domain data the workflow processes.
+ * - `metadata`: Control flow and non-business data.
+ * - `lt`: Automatically managed by the interceptor. Do not set manually.
+ * - `resolver`: Present on re-entry from human escalation.
+ */
+export interface LTEnvelope {
+    data: Record<string, any>;
+    metadata: {
+        [key: string]: any;
+    };
+    lt?: {
+        /** Identity of the executing principal (user or bot). Set by the API route layer. */
+        userId?: string;
+        /** Resolved principal — set at the front door, never re-queried. */
+        principal?: LTEnvelopePrincipal;
+        /** Original human invoker when proxy invocation is used (audit trail). */
+        initiatedBy?: string;
+        /** Resolved principal of the original invoker when proxy invocation is used.
+         *  Enables credential fallback: activities can resolve credentials for the
+         *  human even when the workflow executes as a bot. */
+        initiatingPrincipal?: LTEnvelopePrincipal;
+        /** Authorization scopes for this invocation. */
+        scopes?: string[];
+        escalationId?: string;
+        escalationStatus?: string;
+        originId?: string;
+        parentId?: string;
+        signalId?: string;
+        taskId?: string;
+        providers?: import('./config').LTProviderData;
+        /** Orchestrator workflow ID — set by executeLT for signal routing */
+        parentWorkflowId?: string;
+        /** Orchestrator task queue — set by executeLT for signal routing */
+        parentTaskQueue?: string;
+        /** Orchestrator workflow function name — set by executeLT for signal routing */
+        parentWorkflowType?: string;
+    };
+    resolver?: Record<string, any>;
+}

package/build/types/envelope.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/types/escalation-strategy.d.ts

@@ -0,0 +1,37 @@
+import type { LTEscalationRecord } from './escalation';
+/**
+ * Context provided to the escalation strategy when a resolver submits.
+ */
+export interface ResolutionContext {
+    /** The escalation being resolved */
+    escalation: LTEscalationRecord;
+    /** The resolver's payload */
+    resolverPayload: Record<string, any>;
+    /** The reconstructed envelope (with lt fields preserved) */
+    envelope: Record<string, any>;
+}
+/**
+ * Directive returned by the strategy, controlling what happens after resolution.
+ *
+ * - `rerun` — standard re-run: start the original workflow with resolver data (default behavior)
+ * - `triage` — route to the MCP triage orchestrator for dynamic remediation
+ */
+export type ResolutionDirective = {
+    action: 'rerun';
+} | {
+    action: 'triage';
+    triageEnvelope: Record<string, any>;
+};
+/**
+ * Pluggable escalation strategy.
+ *
+ * Determines what happens when a resolver submits a resolution. The default
+ * strategy always returns `{ action: 'rerun' }` — standard re-run behavior.
+ * The MCP strategy checks for `resolverPayload._lt.needsTriage` and routes
+ * to the triage orchestrator when set.
+ *
+ * Follows the same adapter pattern as auth, events, telemetry, and logging.
+ */
+export interface LTEscalationStrategy {
+    onResolution(context: ResolutionContext): Promise<ResolutionDirective>;
+}

package/build/types/escalation-strategy.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/types/escalation.d.ts

@@ -0,0 +1,39 @@
+export type LTEscalationStatus = 'pending' | 'resolved' | 'cancelled';
+export type LTEscalationPriority = 1 | 2 | 3 | 4;
+export interface LTEscalationRecord {
+    id: string;
+    type: string;
+    subtype: string;
+    description: string | null;
+    status: LTEscalationStatus;
+    priority: LTEscalationPriority;
+    task_id: string | null;
+    origin_id: string | null;
+    parent_id: string | null;
+    workflow_id: string | null;
+    task_queue: string | null;
+    workflow_type: string | null;
+    role: string;
+    assigned_to: string | null;
+    assigned_until: Date | null;
+    resolved_at: Date | null;
+    claimed_at: Date | null;
+    envelope: string;
+    metadata: Record<string, any> | null;
+    escalation_payload: string | null;
+    resolver_payload: string | null;
+    trace_id: string | null;
+    span_id: string | null;
+    created_at: Date;
+    updated_at: Date;
+}
+/**
+ * An escalation is "effectively claimed" when assigned_to is set
+ * and assigned_until is in the future. Status remains 'pending'.
+ */
+export declare function isEffectivelyClaimed(esc: LTEscalationRecord): boolean;
+/**
+ * An escalation is "available" when status is pending and
+ * either unassigned or the assignment has expired.
+ */
+export declare function isAvailable(esc: LTEscalationRecord): boolean;

package/build/types/escalation.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isEffectivelyClaimed = isEffectivelyClaimed;
+exports.isAvailable = isAvailable;
+/**
+ * An escalation is "effectively claimed" when assigned_to is set
+ * and assigned_until is in the future. Status remains 'pending'.
+ */
+function isEffectivelyClaimed(esc) {
+    return !!(esc.assigned_to &&
+        esc.assigned_until &&
+        esc.assigned_until > new Date());
+}
+/**
+ * An escalation is "available" when status is pending and
+ * either unassigned or the assignment has expired.
+ */
+function isAvailable(esc) {
+    return (esc.status === 'pending' &&
+        (!esc.assigned_to || !esc.assigned_until || esc.assigned_until <= new Date()));
+}

package/build/types/events.d.ts

@@ -0,0 +1,65 @@
+import type { LTMilestone } from './task';
+/**
+ * All event types published through the NATS event system.
+ *
+ * Topic space: `lt.events.{type}` — e.g. `lt.events.task.created`
+ *
+ * Dashboard subscribes to `lt.events.>` to receive all events.
+ */
+export type LTEventType = 'task.created' | 'task.started' | 'task.completed' | 'task.escalated' | 'task.failed' | 'escalation.created' | 'escalation.resolved' | 'escalation.claimed' | 'escalation.released' | 'workflow.started' | 'workflow.completed' | 'workflow.failed' | 'activity.started' | 'activity.completed' | 'activity.failed' | 'milestone';
+/**
+ * Payload published through the events system.
+ */
+export interface LTEvent {
+    /** Event classification */
+    type: LTEventType | string;
+    /** Where the event originated: 'interceptor' | 'orchestrator' | 'activity' */
+    source: string;
+    /** The workflow instance that produced this event */
+    workflowId: string;
+    /** The workflow function name */
+    workflowName: string;
+    /** The task queue the workflow ran on */
+    taskQueue: string;
+    /** The task ID (present when orchestrated) */
+    taskId?: string;
+    /** The escalation ID (present for escalation events) */
+    escalationId?: string;
+    /** The origin ID — root process lineage */
+    originId?: string;
+    /** Task or workflow status after this event */
+    status?: string;
+    /** The activity name (present when source is 'activity') */
+    activityName?: string;
+    /** Milestones reported by the workflow */
+    milestones?: LTMilestone[];
+    /** Optional result data */
+    data?: Record<string, any>;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+}
+/**
+ * Pluggable event adapter interface.
+ *
+ * Implement this to route Long Tail events to your pub/sub system
+ * (NATS, SNS, GCP Pub/Sub, Kafka, etc.).
+ *
+ * Usage:
+ * ```typescript
+ * import { LTEventAdapter, LTEvent } from '@hotmeshio/long-tail';
+ *
+ * class MySnsAdapter implements LTEventAdapter {
+ *   async connect() { /* init SNS client *​/ }
+ *   async publish(event: LTEvent) { /* publish to SNS *​/ }
+ *   async disconnect() { /* cleanup *​/ }
+ * }
+ * ```
+ */
+export interface LTEventAdapter {
+    /** Initialize the connection (called once during startup) */
+    connect(): Promise<void>;
+    /** Publish an event (fire-and-forget semantics; errors are swallowed by the registry) */
+    publish(event: LTEvent): Promise<void>;
+    /** Graceful shutdown */
+    disconnect(): Promise<void>;
+}

package/build/types/events.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/types/export.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Workflow state export types.
+ *
+ * Raw export types wrap the HotMesh DurableJobExport model with LT-specific
+ * naming so consumers never couple directly to the engine layer.
+ *
+ * Execution types are re-exported directly from HotMesh's native
+ * structured execution event format (added in 0.10.2).
+ */
+export type { WorkflowExecution, WorkflowExecutionEvent, WorkflowExecutionStatus, WorkflowExecutionSummary, WorkflowEventType, WorkflowEventCategory, WorkflowEventAttributes, ExecutionExportOptions, ExportMode, ActivityDetail, JobExport, WorkflowExecutionStartedAttributes, WorkflowExecutionCompletedAttributes, WorkflowExecutionFailedAttributes, ActivityTaskScheduledAttributes, ActivityTaskCompletedAttributes, ActivityTaskFailedAttributes, ChildWorkflowExecutionStartedAttributes, ChildWorkflowExecutionCompletedAttributes, ChildWorkflowExecutionFailedAttributes, TimerStartedAttributes, TimerFiredAttributes, WorkflowExecutionSignaledAttributes, } from '@hotmeshio/hotmesh/build/types/exporter';
+/**
+ * Facets available in a workflow export.
+ * Mirrors HotMesh ExportFields.
+ */
+export type LTExportField = 'data' | 'state' | 'status' | 'timeline' | 'transitions';
+/**
+ * Options for controlling which facets are included in an export.
+ *
+ * - `allow` — whitelist: only these facets are returned.
+ * - `block` — blacklist: all facets *except* these are returned.
+ * - `values` — when false, timeline entries omit their value payloads
+ *   (useful for reducing transfer size).
+ *
+ * If neither `allow` nor `block` is supplied every facet is included.
+ */
+export interface LTExportOptions {
+    allow?: LTExportField[];
+    block?: LTExportField[];
+    values?: boolean;
+    enrich_inputs?: boolean;
+}
+/**
+ * A single entry in the workflow activity timeline.
+ * Each entry represents an activity execution with its index
+ * position in the execution graph.
+ */
+export interface LTTimelineEntry {
+    key: string;
+    value: Record<string, any> | string | number | null;
+    index: number;
+    secondary?: number;
+    dimension?: string;
+}
+/**
+ * A single state transition in the workflow execution.
+ * Tracks which activity moved through which dimension and when.
+ */
+export interface LTTransitionEntry {
+    activity: string;
+    dimensions: string;
+    created: string;
+    updated: string;
+}
+/**
+ * Full workflow state export (raw HotMesh format).
+ *
+ * Returned by the export service and the
+ * `GET /api/workflow-states/:workflowId` endpoint.
+ *
+ * Facets are optional because callers may use `allow` / `block`
+ * to restrict the response.
+ */
+export interface LTWorkflowExport {
+    /** The workflow ID this export belongs to. */
+    workflow_id: string;
+    /** Input/output data stored during execution. */
+    data?: Record<string, any>;
+    /** Job state hash — current key/value pairs. */
+    state?: Record<string, any>;
+    /** Numeric status semaphore (positive = complete, 0 = pending, negative = interrupted). */
+    status?: number;
+    /** Ordered activity execution timeline. */
+    timeline?: LTTimelineEntry[];
+    /** Activity state transitions in chronological order. */
+    transitions?: LTTransitionEntry[];
+    /** Structured per-activity details with input/output (requires enrich_inputs). */
+    activities?: import('@hotmeshio/hotmesh/build/types/exporter').ActivityDetail[];
+}

package/build/types/export.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * Workflow state export types.
+ *
+ * Raw export types wrap the HotMesh DurableJobExport model with LT-specific
+ * naming so consumers never couple directly to the engine layer.
+ *
+ * Execution types are re-exported directly from HotMesh's native
+ * structured execution event format (added in 0.10.2).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/types/index.d.ts

@@ -0,0 +1,21 @@
+export type { LTEnvelope, } from './envelope';
+export type { LTTaskStatus, LTTaskPriority, LTTaskRecord, LTMilestone, } from './task';
+export type { LTEscalationStatus, LTEscalationPriority, LTEscalationRecord, } from './escalation';
+export { isEffectivelyClaimed, isAvailable, } from './escalation';
+export type { LTReturn, LTEscalation, LTActivity, LTResult, } from './workflow';
+export type { LTWorkflowConfig, LTResolvedConfig, LTProviderData, } from './config';
+export type { AuthPayload, LTAuthAdapter, } from './auth';
+export type { LTUserStatus, LTRoleType, LTUserRole, LTUserRecord, } from './user';
+export type { LTEvent, LTEventType, LTEventAdapter, } from './events';
+export type { LTTelemetryAdapter, } from './telemetry';
+export type { LTLoggerAdapter, } from './logger';
+export type { LTMaintenanceRule, LTMaintenanceConfig, } from './maintenance';
+export type { LTExportField, LTExportOptions, LTTimelineEntry, LTTransitionEntry, LTWorkflowExport, } from './export';
+export type { WorkflowExecution, WorkflowExecutionEvent, WorkflowExecutionStatus, WorkflowExecutionSummary, WorkflowEventType, WorkflowEventCategory, WorkflowEventAttributes, ExecutionExportOptions, ExportMode, ActivityDetail, JobExport, } from './export';
+export type { LTStartConfig, LTInstance, } from './startup';
+export type { LTMcpTransportType, LTMcpServerRecord, LTMcpServerStatus, LTMcpToolManifest, LTMcpAdapter, } from './mcp';
+export type { ResolutionContext, ResolutionDirective, LTEscalationStrategy, } from './escalation-strategy';
+export type { WorkflowCandidate, } from './discovery';
+export type { DelegationTokenPayload, ToolAuthContext, ServiceTokenRecord, } from './delegation';
+export type { ToolContext, ToolPrincipal, ToolCredentials, ToolTrace, } from './tool-context';
+export type { LTOAuthProviderConfig, LTOAuthStartConfig, LTOAuthUserInfo, LTDecryptedToken, LTOAuthTokenRecord, } from './oauth';

package/build/types/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAvailable = exports.isEffectivelyClaimed = void 0;
+var escalation_1 = require("./escalation");
+Object.defineProperty(exports, "isEffectivelyClaimed", { enumerable: true, get: function () { return escalation_1.isEffectivelyClaimed; } });
+Object.defineProperty(exports, "isAvailable", { enumerable: true, get: function () { return escalation_1.isAvailable; } });

package/build/types/logger.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Pluggable logging adapter interface.
+ *
+ * Implement this to route Long Tail's internal log output through a
+ * structured logger (Pino, Winston, etc.).
+ *
+ * When no adapter is registered, Long Tail falls back to `console.*`.
+ *
+ * Usage:
+ * ```typescript
+ * import type { LTLoggerAdapter } from '@hotmeshio/long-tail';
+ *
+ * class MyLoggerAdapter implements LTLoggerAdapter {
+ *   info(msg: string, context?: Record<string, any>) { /* ... *​/ }
+ *   warn(msg: string, context?: Record<string, any>) { /* ... *​/ }
+ *   error(msg: string, context?: Record<string, any>) { /* ... *​/ }
+ *   debug(msg: string, context?: Record<string, any>) { /* ... *​/ }
+ * }
+ * ```
+ */
+export interface LTLoggerAdapter {
+    info(msg: string, context?: Record<string, any>): void;
+    warn(msg: string, context?: Record<string, any>): void;
+    error(msg: string, context?: Record<string, any>): void;
+    debug(msg: string, context?: Record<string, any>): void;
+}

package/build/types/logger.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/types/maintenance.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A single maintenance rule describing what to prune and when.
+ */
+export interface LTMaintenanceRule {
+    /** Which resource to target */
+    target: 'streams' | 'jobs';
+    /** delete = hard-delete rows; prune = strip execution artifacts */
+    action: 'delete' | 'prune';
+    /** Postgres interval for the retention window, e.g. '7 days', '90 days' */
+    olderThan: string;
+    /** When target is 'jobs': true = entity jobs, false = transient (entity IS NULL) */
+    hasEntity?: boolean;
+    /** When true, only target jobs that have already been pruned (pruned_at IS NOT NULL) */
+    pruned?: boolean;
+}
+/**
+ * Full maintenance configuration: schedule + ordered rules.
+ */
+export interface LTMaintenanceConfig {
+    /** Cron expression or ms-compatible interval, e.g. '0 2 * * *' or '1 day' */
+    schedule: string;
+    /** Rules executed sequentially each cycle */
+    rules: LTMaintenanceRule[];
+}

package/build/types/maintenance.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/types/mcp.d.ts

@@ -0,0 +1,80 @@
+/**
+ * MCP server transport type.
+ * - 'stdio'  — spawn a child process (command + args)
+ * - 'sse'    — connect to an SSE endpoint (url)
+ */
+export type LTMcpTransportType = 'stdio' | 'sse';
+/**
+ * MCP server registration as stored in the database (snake_case).
+ */
+export interface LTMcpServerRecord {
+    id: string;
+    name: string;
+    description: string | null;
+    transport_type: LTMcpTransportType;
+    transport_config: {
+        /** For stdio: the command to spawn */
+        command?: string;
+        /** For stdio: arguments to the command */
+        args?: string[];
+        /** For stdio: environment variables to set */
+        env?: Record<string, string>;
+        /** For sse: the URL to connect to */
+        url?: string;
+    };
+    /** Whether to auto-connect on startup */
+    auto_connect: boolean;
+    /** Cached tool manifest from last listTools() */
+    tool_manifest: LTMcpToolManifest[] | null;
+    metadata: Record<string, any> | null;
+    /** Categorization tags for efficient tool discovery (e.g., ['database', 'analytics']) */
+    tags: string[];
+    /** Per-server hints injected into the YAML compilation prompt when this server's tools are used */
+    compile_hints: string | null;
+    /** Credential providers required by this server's tools (e.g., ['anthropic']) */
+    credential_providers: string[];
+    status: LTMcpServerStatus;
+    last_connected_at: Date | null;
+    created_at: Date;
+    updated_at: Date;
+}
+export type LTMcpServerStatus = 'registered' | 'connected' | 'error' | 'disconnected';
+/**
+ * Cached tool manifest entry from listTools().
+ */
+export interface LTMcpToolManifest {
+    name: string;
+    description: string;
+    inputSchema: Record<string, any>;
+}
+/**
+ * MCP adapter interface. Follows the same pattern as
+ * LTTelemetryAdapter (single-adapter, connect/disconnect).
+ *
+ * The adapter manages:
+ * - One MCP server (human queue) exposing Long Tail escalations
+ * - Multiple MCP client connections to external servers
+ */
+export interface LTMcpAdapter {
+    /** Start the MCP server and connect all auto-connect clients */
+    connect(): Promise<void>;
+    /** Disconnect all clients and stop the server */
+    disconnect(): Promise<void>;
+    /** Connect to a registered MCP server by name or ID */
+    connectClient(serverId: string): Promise<void>;
+    /** Disconnect a specific client */
+    disconnectClient(serverId: string): Promise<void>;
+    /** List tools from a connected server */
+    listTools(serverId: string): Promise<LTMcpToolManifest[]>;
+    /** Call a tool on a connected server */
+    callTool(serverId: string, toolName: string, args: Record<string, any>, authContext?: {
+        userId?: string;
+        delegationToken?: string;
+    }): Promise<any>;
+    /**
+     * Return an object of tool functions suitable for
+     * Durable.workflow.proxyActivities(). Each key is a tool name
+     * and each value is an async function wrapping callTool().
+     */
+    toolActivities(serverId: string): Promise<Record<string, (...args: any[]) => Promise<any>>>;
+}

package/build/types/mcp.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/types/oauth.d.ts

@@ -0,0 +1,74 @@
+/**
+ * OAuth provider configuration for identity and resource OAuth.
+ */
+export interface LTOAuthProviderConfig {
+    /** Provider identifier: 'google' | 'github' | 'microsoft' | custom string */
+    provider: string;
+    /** OAuth2 client ID */
+    clientId: string;
+    /** OAuth2 client secret */
+    clientSecret: string;
+    /** Authorization scopes */
+    scopes: string[];
+    /** Override redirect URI (default: auto-computed from server URL) */
+    redirectUri?: string;
+    /** Display name for login buttons (default: capitalized provider) */
+    displayName?: string;
+}
+/**
+ * OAuth startup configuration. Added to LTStartConfig.auth.oauth.
+ */
+export interface LTOAuthStartConfig {
+    /** Encryption key for tokens at rest (32-byte hex). Falls back to OAUTH_ENCRYPTION_KEY env. */
+    encryptionKey?: string;
+    /** Configured OAuth providers */
+    providers?: LTOAuthProviderConfig[];
+    /** Auto-provision users on first OAuth login (default: true) */
+    autoProvision?: boolean;
+    /** Default role type for auto-provisioned OAuth users (default: 'member') */
+    defaultRoleType?: 'admin' | 'member';
+    /** Base URL for computing redirect URIs (default: derived from request) */
+    baseUrl?: string;
+}
+/**
+ * User info returned from an OAuth provider's userinfo endpoint.
+ */
+export interface LTOAuthUserInfo {
+    provider: string;
+    providerUserId: string;
+    email: string | null;
+    displayName: string | null;
+    raw: Record<string, any>;
+}
+/**
+ * Decrypted OAuth token set for a user+provider+label.
+ */
+export interface LTDecryptedToken {
+    accessToken: string;
+    refreshToken: string | null;
+    expiresAt: Date | null;
+    scopes: string[];
+    provider: string;
+    /** Label distinguishing multiple credentials for the same provider (default: 'default') */
+    label: string;
+}
+/**
+ * Database record shape for lt_oauth_tokens.
+ */
+export interface LTOAuthTokenRecord {
+    id: string;
+    user_id: string;
+    provider: string;
+    /** Label distinguishing multiple credentials for the same provider (default: 'default') */
+    label: string;
+    access_token_enc: string;
+    refresh_token_enc: string | null;
+    token_type: string;
+    scopes: string[];
+    expires_at: Date | null;
+    provider_user_id: string;
+    provider_email: string | null;
+    metadata: Record<string, any> | null;
+    created_at: Date;
+    updated_at: Date;
+}

package/build/types/oauth.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });