@hotmeshio/long-tail 0.1.0

package/build/examples/workflows/kitchen-sink/index.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * Kitchen Sink Workflow
+ *
+ * Demonstrates every Durable primitive in one workflow:
+ *
+ *   1. proxyActivities  — turn functions into durable, checkpointed steps
+ *   2. Activity calls   — each call is cached on replay (deterministic)
+ *   3. Sleep            — durable timer that survives process crashes
+ *   4. Parallel calls   — Promise.all with multiple activities
+ *   5. waitFor          — pause until an external signal arrives
+ *   6. Conditional flow — branch based on signal data
+ *
+ * Use this as a copy-paste starting point for your own workflows.
+ *
+ * Structure:
+ *   examples/workflows/kitchen-sink/
+ *   ├── activities.ts     ← side-effect functions (API calls, DB writes, etc.)
+ *   ├── index.ts          ← this file (the workflow — must be deterministic)
+ *   └── orchestrator.ts   ← entry point wrapper using executeLT
+ */
+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.kitchenSink = kitchenSink;
+const hotmesh_1 = require("@hotmeshio/hotmesh");
+const activities = __importStar(require("./activities"));
+const { greet, fetchData, transformData, notifyComplete } = hotmesh_1.Durable.workflow.proxyActivities({
+    activities,
+    retryPolicy: {
+        maximumAttempts: 3,
+        backoffCoefficient: 2,
+        maximumInterval: '10 seconds',
+    },
+});
+// ── Workflow function ───────────────────────────────────────────────────────
+async function kitchenSink(envelope) {
+    const { name = 'World', mode = 'full' } = envelope.data;
+    // ── 1. Activity call ──────────────────────────────────────────────────
+    // Each proxied call is a durable checkpoint. If the process crashes after
+    // this completes, the cached result is replayed — the function isn't re-run.
+    const greeting = await greet(name);
+    // ── 2. Durable sleep ──────────────────────────────────────────────────
+    // Survives crashes. If the process restarts during the sleep, it resumes
+    // where it left off — no drift, no double-execution.
+    await hotmesh_1.Durable.workflow.sleepFor('2 seconds');
+    // ── 3. Parallel activities ────────────────────────────────────────────
+    // Promise.all works naturally. Both activities run concurrently and each
+    // is independently checkpointed.
+    const [dataA, dataB] = await Promise.all([
+        fetchData('source-a'),
+        fetchData('source-b'),
+    ]);
+    // ── 4. Transform (another activity) ──────────────────────────────────
+    const result = await transformData({ greeting, dataA, dataB });
+    // ── 5. Quick mode: skip signal wait ───────────────────────────────────
+    if (mode === 'quick') {
+        await notifyComplete({ status: 'auto-approved', result });
+        return {
+            type: 'return',
+            data: { greeting, result, mode, completedAt: new Date().toISOString() },
+        };
+    }
+    // ── 6. Escalation ────────────────────────────────────────────────────
+    // Return type 'escalation' to pause and wait for human input.
+    // The interceptor creates an escalation record in the database.
+    // When the operator resolves it, the workflow is re-run with
+    // envelope.resolver containing their decision.
+    if (!envelope.resolver) {
+        return {
+            type: 'escalation',
+            data: { greeting, result },
+            message: `Kitchen sink workflow needs approval (name: ${name})`,
+            role: 'reviewer',
+        };
+    }
+    // ── 7. Re-entry after human resolution ────────────────────────────────
+    // envelope.resolver contains the operator's payload from the dashboard.
+    // No resolver_schema is defined for this workflow — any response from
+    // the human (or triage) means "approved". The workflow completes.
+    await notifyComplete({ status: 'approved', result });
+    return {
+        type: 'return',
+        data: {
+            greeting,
+            result,
+            resolver: envelope.resolver,
+            approved: true,
+            completedAt: new Date().toISOString(),
+        },
+    };
+}

package/build/examples/workflows/review-content/activities.d.ts

@@ -0,0 +1,10 @@
+import type { ReviewAnalysis } from './types';
+/**
+ * Simulates AI content analysis. In production, this would call
+ * an LLM or classification model to analyze the content.
+ *
+ * The activity interceptor creates an 'llm' milestone in the
+ * "before" phase when this activity is invoked (configured via
+ * the milestones mapping passed to createLTActivityInterceptor).
+ */
+export declare function analyzeContent(content: string, contentType?: string): Promise<ReviewAnalysis>;

package/build/examples/workflows/review-content/activities.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeContent = analyzeContent;
+/**
+ * Simulates AI content analysis. In production, this would call
+ * an LLM or classification model to analyze the content.
+ *
+ * The activity interceptor creates an 'llm' milestone in the
+ * "before" phase when this activity is invoked (configured via
+ * the milestones mapping passed to createLTActivityInterceptor).
+ */
+async function analyzeContent(content, contentType) {
+    // Simulate analysis latency
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    const flags = [];
+    let confidence = 0.95;
+    const text = content ?? '';
+    // Simple heuristic simulation
+    if (text.length < 10) {
+        flags.push('too_short');
+        confidence -= 0.3;
+    }
+    if (text.includes('REVIEW_ME')) {
+        flags.push('manual_review_requested');
+        confidence = 0.1;
+    }
+    if (text.includes('ERROR')) {
+        flags.push('error_detected');
+        confidence -= 0.4;
+    }
+    if (text.includes('WRONG_LANGUAGE')) {
+        flags.push('wrong_language');
+        confidence = 0.15;
+    }
+    const approved = confidence > 0.85 && flags.length === 0;
+    return {
+        approved,
+        confidence: Math.max(0, Math.min(1, confidence)),
+        flags,
+        summary: flags.length
+            ? `Content flagged: ${flags.join(', ')}`
+            : 'Content approved by AI analysis',
+    };
+}

package/build/examples/workflows/review-content/index.d.ts

@@ -0,0 +1,10 @@
+import type { LTEnvelope } from '../../../types';
+import type { ReviewContentReturn, ReviewContentEscalation } from './types';
+/**
+ * Review Content workflow.
+ *
+ * Analyzes content using AI. If confidence is high, auto-approves.
+ * If confidence is low (or flags are raised), escalates to a human reviewer.
+ * On re-run after human resolution, returns the resolver data directly.
+ */
+export declare function reviewContent(envelope: LTEnvelope): Promise<ReviewContentReturn | ReviewContentEscalation>;

package/build/examples/workflows/review-content/index.js

@@ -0,0 +1,95 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reviewContent = reviewContent;
+const hotmesh_1 = require("@hotmeshio/hotmesh");
+const activities = __importStar(require("./activities"));
+const { analyzeContent } = hotmesh_1.Durable.workflow.proxyActivities({
+    activities,
+});
+const CONFIDENCE_THRESHOLD = 0.85;
+/**
+ * Review Content workflow.
+ *
+ * Analyzes content using AI. If confidence is high, auto-approves.
+ * If confidence is low (or flags are raised), escalates to a human reviewer.
+ * On re-run after human resolution, returns the resolver data directly.
+ */
+async function reviewContent(envelope) {
+    const { contentId, content, contentType } = envelope.data;
+    // If this is a re-run with human-provided resolver data, return it
+    if (envelope.resolver) {
+        return {
+            type: 'return',
+            milestones: [
+                { name: 'ai_review', value: 'escalated' },
+                { name: 'resolved_by_human', value: true },
+            ],
+            data: {
+                contentId,
+                ...envelope.resolver,
+            },
+        };
+    }
+    // Step 1: AI analysis (activity interceptor creates 'llm' milestone before this runs)
+    const analysis = await analyzeContent(content, contentType);
+    // Step 2: Confidence check
+    if (analysis.confidence >= CONFIDENCE_THRESHOLD && analysis.approved) {
+        return {
+            type: 'return',
+            milestones: [
+                { name: 'llm', value: 'content_analysis' },
+                { name: 'ai_review', value: 'approved' },
+                { name: 'confidence', value: analysis.confidence },
+            ],
+            data: {
+                contentId,
+                approved: true,
+                analysis,
+            },
+        };
+    }
+    // Step 3: Escalate to human
+    return {
+        type: 'escalation',
+        data: {
+            contentId,
+            content,
+            analysis,
+        },
+        message: `Content review needed (confidence: ${analysis.confidence}, flags: ${analysis.flags.join(', ') || 'none'})`,
+        role: 'reviewer',
+    };
+}

package/build/examples/workflows/review-content/types.d.ts

@@ -0,0 +1,28 @@
+import type { LTReturn, LTEscalation } from '../../../types';
+export interface ReviewContentInput {
+    contentId: string;
+    content: string;
+    contentType?: string;
+}
+export interface ReviewAnalysis {
+    approved: boolean;
+    confidence: number;
+    flags: string[];
+    summary: string;
+}
+export interface ReviewContentReturnData {
+    contentId: string;
+    approved: boolean;
+    analysis: ReviewAnalysis;
+}
+export interface ReviewContentReturn extends LTReturn {
+    data: ReviewContentReturnData;
+}
+export interface ReviewContentEscalationData {
+    contentId: string;
+    content: string;
+    analysis: ReviewAnalysis;
+}
+export interface ReviewContentEscalation extends LTEscalation {
+    data: ReviewContentEscalationData;
+}

package/build/examples/workflows/review-content/types.js

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

package/build/index.d.ts

@@ -0,0 +1,37 @@
+export { start } from './start';
+export { registerLT, createLTInterceptor } from './services/interceptor';
+export { createLTActivityInterceptor } from './services/interceptor/activity-interceptor';
+export { executeLT } from './services/orchestrator';
+export type { ExecuteLTOptions } from './services/orchestrator/types';
+export { JwtAuthAdapter, createAuthMiddleware, requireAuth, requireAdmin, signToken } from './modules/auth';
+export * from './types';
+export * as TaskService from './services/task';
+export * as EscalationService from './services/escalation';
+export * as ConfigService from './services/config';
+export * as UserService from './services/user';
+export { ltConfig } from './modules/ltconfig';
+export { eventRegistry } from './services/events';
+export { NatsEventAdapter } from './services/events/nats';
+export { InMemoryEventAdapter } from './services/events/memory';
+export { SocketIOEventAdapter } from './services/events/socketio';
+export { publishMilestoneEvent, publishTaskEvent, publishEscalationEvent, publishWorkflowEvent } from './services/events/publish';
+export { telemetryRegistry } from './services/telemetry';
+export { HoneycombTelemetryAdapter } from './services/telemetry/honeycomb';
+export { loggerRegistry } from './services/logger';
+export { PinoLoggerAdapter } from './services/logger/pino';
+export { maintenanceRegistry } from './services/maintenance';
+export { defaultMaintenanceConfig } from './modules/maintenance';
+export { mcpRegistry } from './services/mcp';
+export { BuiltInMcpAdapter } from './services/mcp/adapter';
+export * as McpService from './services/mcp/db';
+export * as McpClient from './services/mcp/client';
+export * as McpServer from './services/mcp/server';
+export * as McpVisionServer from './services/mcp/vision-server';
+export { escalationStrategyRegistry } from './services/escalation-strategy';
+export { DefaultEscalationStrategy } from './services/escalation-strategy/default';
+export { McpEscalationStrategy } from './services/escalation-strategy/mcp';
+export { exampleWorkers, seedExamples } from './examples';
+export { getActivityIdentity } from './services/iam/activity';
+export { getToolContext } from './services/iam/context';
+export { getSystemWorkers, builtinMcpServerFactories } from './system';
+export { seedSystemMcpServers } from './system/seed';

package/build/index.js

@@ -0,0 +1,151 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+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.seedSystemMcpServers = exports.builtinMcpServerFactories = exports.getSystemWorkers = exports.getToolContext = exports.getActivityIdentity = exports.seedExamples = exports.exampleWorkers = exports.McpEscalationStrategy = exports.DefaultEscalationStrategy = exports.escalationStrategyRegistry = exports.McpVisionServer = 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;
+const config_1 = require("./modules/config");
+const logger_1 = require("./services/logger");
+const start_1 = require("./start");
+// ─── Package Exports ─────────────────────────────────────────────────────────
+var start_2 = require("./start");
+Object.defineProperty(exports, "start", { enumerable: true, get: function () { return start_2.start; } });
+var interceptor_1 = require("./services/interceptor");
+Object.defineProperty(exports, "registerLT", { enumerable: true, get: function () { return interceptor_1.registerLT; } });
+Object.defineProperty(exports, "createLTInterceptor", { enumerable: true, get: function () { return interceptor_1.createLTInterceptor; } });
+var activity_interceptor_1 = require("./services/interceptor/activity-interceptor");
+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 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; } });
+Object.defineProperty(exports, "requireAuth", { enumerable: true, get: function () { return auth_1.requireAuth; } });
+Object.defineProperty(exports, "requireAdmin", { enumerable: true, get: function () { return auth_1.requireAdmin; } });
+Object.defineProperty(exports, "signToken", { enumerable: true, get: function () { return auth_1.signToken; } });
+__exportStar(require("./types"), exports);
+exports.TaskService = __importStar(require("./services/task"));
+exports.EscalationService = __importStar(require("./services/escalation"));
+exports.ConfigService = __importStar(require("./services/config"));
+exports.UserService = __importStar(require("./services/user"));
+var ltconfig_1 = require("./modules/ltconfig");
+Object.defineProperty(exports, "ltConfig", { enumerable: true, get: function () { return ltconfig_1.ltConfig; } });
+var events_1 = require("./services/events");
+Object.defineProperty(exports, "eventRegistry", { enumerable: true, get: function () { return events_1.eventRegistry; } });
+var nats_1 = require("./services/events/nats");
+Object.defineProperty(exports, "NatsEventAdapter", { enumerable: true, get: function () { return nats_1.NatsEventAdapter; } });
+var memory_1 = require("./services/events/memory");
+Object.defineProperty(exports, "InMemoryEventAdapter", { enumerable: true, get: function () { return memory_1.InMemoryEventAdapter; } });
+var socketio_1 = require("./services/events/socketio");
+Object.defineProperty(exports, "SocketIOEventAdapter", { enumerable: true, get: function () { return socketio_1.SocketIOEventAdapter; } });
+var publish_1 = require("./services/events/publish");
+Object.defineProperty(exports, "publishMilestoneEvent", { enumerable: true, get: function () { return publish_1.publishMilestoneEvent; } });
+Object.defineProperty(exports, "publishTaskEvent", { enumerable: true, get: function () { return publish_1.publishTaskEvent; } });
+Object.defineProperty(exports, "publishEscalationEvent", { enumerable: true, get: function () { return publish_1.publishEscalationEvent; } });
+Object.defineProperty(exports, "publishWorkflowEvent", { enumerable: true, get: function () { return publish_1.publishWorkflowEvent; } });
+var telemetry_1 = require("./services/telemetry");
+Object.defineProperty(exports, "telemetryRegistry", { enumerable: true, get: function () { return telemetry_1.telemetryRegistry; } });
+var honeycomb_1 = require("./services/telemetry/honeycomb");
+Object.defineProperty(exports, "HoneycombTelemetryAdapter", { enumerable: true, get: function () { return honeycomb_1.HoneycombTelemetryAdapter; } });
+var logger_2 = require("./services/logger");
+Object.defineProperty(exports, "loggerRegistry", { enumerable: true, get: function () { return logger_2.loggerRegistry; } });
+var pino_1 = require("./services/logger/pino");
+Object.defineProperty(exports, "PinoLoggerAdapter", { enumerable: true, get: function () { return pino_1.PinoLoggerAdapter; } });
+var maintenance_1 = require("./services/maintenance");
+Object.defineProperty(exports, "maintenanceRegistry", { enumerable: true, get: function () { return maintenance_1.maintenanceRegistry; } });
+var maintenance_2 = require("./modules/maintenance");
+Object.defineProperty(exports, "defaultMaintenanceConfig", { enumerable: true, get: function () { return maintenance_2.defaultMaintenanceConfig; } });
+var mcp_1 = require("./services/mcp");
+Object.defineProperty(exports, "mcpRegistry", { enumerable: true, get: function () { return mcp_1.mcpRegistry; } });
+var adapter_1 = require("./services/mcp/adapter");
+Object.defineProperty(exports, "BuiltInMcpAdapter", { enumerable: true, get: function () { return adapter_1.BuiltInMcpAdapter; } });
+exports.McpService = __importStar(require("./services/mcp/db"));
+exports.McpClient = __importStar(require("./services/mcp/client"));
+exports.McpServer = __importStar(require("./services/mcp/server"));
+exports.McpVisionServer = __importStar(require("./services/mcp/vision-server"));
+var escalation_strategy_1 = require("./services/escalation-strategy");
+Object.defineProperty(exports, "escalationStrategyRegistry", { enumerable: true, get: function () { return escalation_strategy_1.escalationStrategyRegistry; } });
+var default_1 = require("./services/escalation-strategy/default");
+Object.defineProperty(exports, "DefaultEscalationStrategy", { enumerable: true, get: function () { return default_1.DefaultEscalationStrategy; } });
+var mcp_2 = require("./services/escalation-strategy/mcp");
+Object.defineProperty(exports, "McpEscalationStrategy", { enumerable: true, get: function () { return mcp_2.McpEscalationStrategy; } });
+var examples_1 = require("./examples");
+Object.defineProperty(exports, "exampleWorkers", { enumerable: true, get: function () { return examples_1.exampleWorkers; } });
+Object.defineProperty(exports, "seedExamples", { enumerable: true, get: function () { return examples_1.seedExamples; } });
+var activity_1 = require("./services/iam/activity");
+Object.defineProperty(exports, "getActivityIdentity", { enumerable: true, get: function () { return activity_1.getActivityIdentity; } });
+var context_1 = require("./services/iam/context");
+Object.defineProperty(exports, "getToolContext", { enumerable: true, get: function () { return context_1.getToolContext; } });
+var system_1 = require("./system");
+Object.defineProperty(exports, "getSystemWorkers", { enumerable: true, get: function () { return system_1.getSystemWorkers; } });
+Object.defineProperty(exports, "builtinMcpServerFactories", { enumerable: true, get: function () { return system_1.builtinMcpServerFactories; } });
+var seed_1 = require("./system/seed");
+Object.defineProperty(exports, "seedSystemMcpServers", { enumerable: true, get: function () { return seed_1.seedSystemMcpServers; } });
+// ─── Server ──────────────────────────────────────────────────────────────────
+async function main() {
+    const honeycombKey = process.env.HONEYCOMB_API_KEY;
+    await (0, start_1.start)({
+        database: {
+            host: config_1.config.POSTGRES_HOST,
+            port: config_1.config.POSTGRES_PORT,
+            user: config_1.config.POSTGRES_USER,
+            password: config_1.config.POSTGRES_PASSWORD,
+            database: config_1.config.POSTGRES_DB,
+        },
+        server: {
+            port: config_1.config.PORT,
+        },
+        examples: true,
+        mcp: {
+            server: { enabled: true },
+        },
+        escalation: {
+            strategy: 'mcp',
+        },
+        telemetry: honeycombKey ? { honeycomb: { apiKey: honeycombKey } } : undefined,
+        events: process.env.NATS_URL
+            ? { nats: { url: config_1.config.NATS_URL, token: process.env.NATS_TOKEN || 'dev_api_secret' } }
+            : undefined,
+    });
+}
+// Run server when executed directly
+if (require.main === module) {
+    require('dotenv').config();
+    main().catch((err) => {
+        logger_1.loggerRegistry.error(`[long-tail] fatal: ${err}`);
+        process.exit(1);
+    });
+}

package/build/modules/auth.d.ts

@@ -0,0 +1,58 @@
+import { Request, RequestHandler } from 'express';
+import type { AuthPayload, LTAuthAdapter } from '../types';
+export type { AuthPayload, LTAuthAdapter };
+declare global {
+    namespace Express {
+        interface Request {
+            auth?: AuthPayload;
+        }
+    }
+}
+/**
+ * Reference JWT auth adapter using `jsonwebtoken`.
+ *
+ * Reads a Bearer token from the Authorization header and verifies it
+ * with the configured secret. Returns the decoded payload or null.
+ */
+export declare class JwtAuthAdapter implements LTAuthAdapter {
+    private explicitSecret;
+    constructor(secret?: string);
+    authenticate(req: Request): AuthPayload | null | Promise<AuthPayload | null>;
+    private authenticateBotApiKey;
+}
+/**
+ * Create Express middleware from any auth adapter.
+ *
+ * The adapter handles token extraction and verification.
+ * This middleware handles the HTTP response (401) and ensures
+ * the payload contains a `userId` claim before setting `req.auth`.
+ *
+ * Usage:
+ * ```typescript
+ * import { createAuthMiddleware, JwtAuthAdapter } from '@hotmeshio/long-tail';
+ *
+ * // Use the reference JWT adapter
+ * app.use(createAuthMiddleware(new JwtAuthAdapter('my-secret')));
+ *
+ * // Or plug in your own adapter
+ * app.use(createAuthMiddleware(myClerkAdapter));
+ * ```
+ */
+export declare function createAuthMiddleware(adapter: LTAuthAdapter): RequestHandler;
+export declare const requireAuth: RequestHandler;
+/**
+ * Replace the auth adapter used by `requireAuth`.
+ * Call before starting the server.
+ */
+export declare function setAuthAdapter(adapter: LTAuthAdapter): void;
+/**
+ * Middleware that requires admin access. Must be placed AFTER requireAuth.
+ *
+ * Checks isSuperAdmin() via the database first, then falls back to the
+ * JWT `role` claim for stateless admin checks. Returns 403 otherwise.
+ */
+export declare const requireAdmin: RequestHandler;
+/**
+ * Generate a JWT token. Utility for tests and token provisioning.
+ */
+export declare function signToken(payload: AuthPayload, expiresIn?: string): string;